Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
# DeepSeek Harness Architecture
2026-07-21 01:54:00 +08:00
English | [中文 ](architecture.zh.md )
2026-07-21 02:13:10 +08:00
**DeepSeek Harness SDK** uses Cordis: **everything is a plugin** , including the loop.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-09 23:48:29 +08:00
## Overview
docs: accuracy sweep, architecture restructure, two ADRs, review skill
- AGENTS.md Commands: fix typecheck/build descriptions; add lint, lint:fix,
test:coverage, knip, publint, hygiene (were undocumented).
- Drop the bare `yarn demo` for explicit `demo:echo` + `demo:coding`; update
README, examples READMEs (and document coding-agent in examples/README).
- New cookbook guide: adding-a-vendored-package.md (the missing "add" half of
vendor/README's update-only procedure).
- architecture.md: add a table-of-contents and extract the Extension cookbook
to docs/cookbook/extension-cookbook.md (link-preserving); drop the completed
"restructure this document" TODO.
- ADR 0009 (capability seams) + 0010 (twin LLM adapters), and a "when to write
an ADR" standard in adr/README.
- Add a committed dsh-code-review skill under .agents/skills, exposed to Claude
Code via a tracked .claude/skills symlink (gitignore carve-out).
2026-06-13 18:50:13 +08:00
2026-07-31 22:00:39 +08:00
Harnesses are [Cordis ](cordis-primer.md ) contexts; packages contribute services, typed events, and disposable registrations. `packages/core/` groups the default flow; capabilities remain plugins.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-09 23:48:29 +08:00
### Default Services
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
docs(architecture): rewrite the system map to the 1,800-word budget
architecture.md is the behavior map: layering, service map, seam
pattern, and the loop — everything else defers to its owning tier.
- Seam narrations compress to two-to-four sentences plus links to the
RFC and type-catalog homes that carry the detail (turn-end variant
semantics -> session.md, derivation mapping -> session.md, StreamChunk
conventions -> llm-streaming.md + source).
- The MVP feature-to-mechanism checklist moves de-statused into the
extension cookbook as 'The feature -> mechanism map' — mechanisms
only, no implementation-status bolding to rot; the microkernel RFC's
proof-obligation pointer follows it.
- The layering diagram describes layers by family instead of
enumerating packages (the stale 'future plugins: hooks, compaction'
row is gone); the dependency rule defers to packages/README.md.
- The loop pseudocode, the three externally-cited anchors (the
vocabulary, event taxonomy, waterfall semantics), and the filename
are unchanged.
- Budget ratchet: docs/architecture.md 3897 -> 1800 (now 1,797 words);
the doc-tiers RFC's deferred list prunes the item this ships.
2026-07-04 14:43:48 +08:00
| ctx key | Package | Role |
|---|---|---|
2026-07-27 17:04:22 +08:00
| — | [`dsh-scope` ](../packages/core/scope/README.md ) | scoped-context registrations and shared layer storage (library) |
2026-07-05 03:32:11 +08:00
| `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions |
2026-07-27 17:04:22 +08:00
| `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and variables |
2026-07-05 19:52:07 +08:00
| `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline ](tool-execution-pipeline.md ) |
2026-07-27 17:04:22 +08:00
| `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, process-local initiator scope |
2026-07-14 13:51:21 +08:00
| `ctx.agentLoop` | `dsh-agent-loop` | concrete `Agent` driver |
docs(architecture): rewrite the system map to the 1,800-word budget
architecture.md is the behavior map: layering, service map, seam
pattern, and the loop — everything else defers to its owning tier.
- Seam narrations compress to two-to-four sentences plus links to the
RFC and type-catalog homes that carry the detail (turn-end variant
semantics -> session.md, derivation mapping -> session.md, StreamChunk
conventions -> llm-streaming.md + source).
- The MVP feature-to-mechanism checklist moves de-statused into the
extension cookbook as 'The feature -> mechanism map' — mechanisms
only, no implementation-status bolding to rot; the microkernel RFC's
proof-obligation pointer follows it.
- The layering diagram describes layers by family instead of
enumerating packages (the stale 'future plugins: hooks, compaction'
row is gone); the dependency rule defers to packages/README.md.
- The loop pseudocode, the three externally-cited anchors (the
vocabulary, event taxonomy, waterfall semantics), and the filename
are unchanged.
- Budget ratchet: docs/architecture.md 3897 -> 1800 (now 1,797 words);
the doc-tiers RFC's deferred list prunes the item this ships.
2026-07-04 14:43:48 +08:00
2026-07-05 19:07:34 +08:00
### Capability Services
2026-06-20 19:47:09 +08:00
2026-07-05 03:32:11 +08:00
| ctx key | Package family | Role |
|---|---|---|
2026-07-28 22:29:34 +08:00
| `ctx.llm` | [`llm/` ](../packages/llm/README.md ) | adapter registry, streaming model calls |
| `ctx.tokenMeter` | [`llm/token-meter` ](../packages/llm/token-meter/README.md ) | replay-aware request and surface pressure |
2026-07-05 03:32:11 +08:00
| `ctx.bash` | [`bash/` ](../packages/bash/README.md ) | foreground/background command execution |
2026-07-28 22:29:34 +08:00
| `ctx.subprocess` | [`subprocess/` ](../packages/subprocess/README.md ) | managed child-process trees for bash, LSP, and ACP subagent backends |
2026-07-21 16:01:00 +08:00
| `ctx.pty` | [`pty/` ](../packages/pty/README.md ) | owner-scoped persistent terminal sessions |
2026-07-27 17:04:22 +08:00
| `ctx.sandbox` | [`sandbox/` ](../packages/sandbox/README.md ) | same-world process confinement through argv wrapping and per-call policy |
2026-07-20 11:40:29 +08:00
| `ctx.sandboxPolicy` | [`sandbox/` ](../packages/sandbox/README.md ) | shared sandbox policy home |
2026-07-08 02:17:24 +08:00
| `ctx.codeRuntime` | [`code-runtime/` ](../packages/code-runtime/README.md ) | model-written program execution |
2026-07-05 19:07:34 +08:00
| `ctx.fs` | [`fs/` ](../packages/fs/README.md ) | filesystem provider primitives and policy events |
2026-07-20 13:54:38 +08:00
| `ctx.lsp` | [`lsp/` ](../packages/lsp/README.md ) | semantic navigation registry |
2026-07-28 22:29:34 +08:00
| `ctx.skills` | [`skill/` ](../packages/skill/README.md ) | skill provider registry, progressive disclosure |
2026-07-05 03:32:11 +08:00
| `ctx.web` | [`web/` ](../packages/web/README.md ) | search/fetch provider registries |
2026-07-28 22:29:34 +08:00
| `ctx.compact` , `ctx.toolResultPrune` | [`compact/` ](../packages/compact/README.md )/[`compact-tool-result-prune` ](../packages/compact/compact-tool-result-prune/README.md ) | summary compaction, optional model-free result pruning |
2026-07-05 03:32:11 +08:00
| `ctx.subagents` | [`subagent/` ](../packages/subagent/README.md ) | named delegation providers |
2026-07-22 16:57:23 +08:00
| `ctx.planMode` | [`plan/` ](../packages/plan/README.md ) | logged plan collaboration state |
2026-07-28 22:29:34 +08:00
| `ctx.tasks` | [`tasks/` ](../packages/tasks/README.md ) | background task registry, generic `task_*` controls |
2026-07-06 03:14:07 +08:00
| `ctx.workflows` | [`workflow/` ](../packages/workflow/README.md ) | script-driven multi-agent orchestration |
2026-07-19 18:47:34 +08:00
| `ctx.goals` | [`goal/` ](../packages/goal/README.md ) | persisted same-session goals |
2026-07-23 21:13:29 +08:00
| `ctx.sessionPersistence` | [`session-persistence/` ](../packages/session-persistence/README.md ) | durable session-log storage |
2026-07-28 22:29:34 +08:00
| `ctx.sessionQuery` | [`session-query/` ](../packages/session-query/README.md ) | live-preferred exact/filter/trace queries over SQLite FTS, workspace-authorized model tools |
| `ctx.sessionTitle` | [`session-title/` ](../packages/session-title/README.md ) | log-backed fallbacks, one optional asynchronous provider |
2026-07-30 23:23:18 +08:00
| `ctx.settings` | [`settings/` ](../packages/settings/README.md ) | per-plugin user-settings namespaces layered over composition entries |
| `ctx.credentials` | [`credentials/` ](../packages/credentials/README.md ) | named secret references resolved per operation, never inlined in configuration |
2026-07-28 22:29:34 +08:00
| `ctx.directoryPicker` | [`host/directory-picker` ](../packages/host/directory-picker/README.md ) | GUI-host directory picking (`native` /`browse` interactions) |
2026-07-28 23:47:57 +08:00
| `ctx.typert` | [`typert/registry` ](../packages/typert/registry/README.md ) | runtime registry for generated package reflection and live Zod schemas |
2026-07-27 17:04:22 +08:00
| `ctx.invariants` | [`support/invariants` ](../packages/support/invariants/README.md ) | package-name-selected registry of package-owned runtime checks |
Add bash execution: dsh-bash seam, dsh-bash-local impl, dsh-tool-bash tools
Three packages following the new capability-seam pattern (interface /
implementation / consumer, now documented in docs/architecture.md):
- dsh-bash: abstract BashExecutor service (ctx.bash) + vocabulary types.
- dsh-bash-local: local subprocesses — bash -c per call in a detached
process group, SIGTERM→SIGKILL group kills, tail-keep truncation with
full-stream spill files, model-friendly env, background task registry.
- dsh-tool-bash: the bash / bash_output / bash_kill tool schemas with
runtime arg validation and background completion notices via
agent.inject(). Non-zero exits are reported, not errored.
Design surveyed against the bash tools of Claude Code, OpenCode, Codex,
and pi (notes in the package READMEs). Permissions/sandbox stay TODO on
the tools/execute waterfall seam; stateful-shell alternatives recorded
in run.ts.
2026-06-12 23:28:44 +08:00
2026-07-09 23:48:29 +08:00
## Event
2026-06-13 18:39:20 +08:00
2026-07-27 17:04:22 +08:00
Events are the service extension API ([catalog ](cordis-catalog/events.md ), [producer/consumer map ](event-producer-consumer.md )).
Add bash execution: dsh-bash seam, dsh-bash-local impl, dsh-tool-bash tools
Three packages following the new capability-seam pattern (interface /
implementation / consumer, now documented in docs/architecture.md):
- dsh-bash: abstract BashExecutor service (ctx.bash) + vocabulary types.
- dsh-bash-local: local subprocesses — bash -c per call in a detached
process group, SIGTERM→SIGKILL group kills, tail-keep truncation with
full-stream spill files, model-friendly env, background task registry.
- dsh-tool-bash: the bash / bash_output / bash_kill tool schemas with
runtime arg validation and background completion notices via
agent.inject(). Non-zero exits are reported, not errored.
Design surveyed against the bash tools of Claude Code, OpenCode, Codex,
and pi (notes in the package READMEs). Permissions/sandbox stay TODO on
the tools/execute waterfall seam; stateful-shell alternatives recorded
in run.ts.
2026-06-12 23:28:44 +08:00
2026-07-05 19:07:34 +08:00
### Event Domains
2026-06-22 10:48:41 +08:00
2026-07-27 17:04:22 +08:00
- **Session events** are durable log facts emitted through `session/event` .
2026-07-31 22:00:39 +08:00
- **Agent events** carry live `Agent` for inbox, step, status, request, validation, and continuation.
- **Capability events** attach policy and adapters without a loop import.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:07:34 +08:00
### Interception Semantics
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-27 17:04:22 +08:00
Waterfalls are around-middleware: listeners delegate with `next()` ; returning without it vetoes or takes over ([semantics ](cordis-primer.md#cordis-waterfall-semantics )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:07:34 +08:00
## Default Loop Lifecycle
2026-06-13 18:39:20 +08:00
2026-08-05 22:54:55 +08:00
A **session** is append-only. A **turn** claims one queued follow-up, waits for its predecessor's checkpoint, and may share its `running` interval ([decision ](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md )); injection claims none. A **step** is one model request plus tools. Fresh creation and persisted resume first acquire an exact unpublished `SessionPreparation` ; Agent and session publication happen only after private setup against that Session is ready ([decision ](../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md )). Quotes in the [sequence ](agent-lifecycle.md ) mark durable events.
2026-06-13 18:39:20 +08:00
2026-07-31 22:00:39 +08:00
Creation without an id mints `<config-id>-session-<uuid>` ; `sessionId` resumes or creates, while `resumeSessionId` requires history. Resume restores lineage and delegation depth before publication; setup failure emits `agent-loop/config-start-failed` .
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 18:51:52 +08:00
### Turn Flow
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 18:51:52 +08:00
```text
2026-08-05 22:54:55 +08:00
choose declarative identity and acquire fresh/restored SessionPreparation
-> prepare private agent.ctx around exact Session -> await unpublished setup -> invoke optional synchronous setup commit
2026-07-11 22:55:40 +08:00
-> enter session + agent -> session/created -> agent/created
-> enable driving -> agent/session-start(source) -> start driver
2026-07-05 18:51:52 +08:00
forever:
2026-08-04 21:02:28 +08:00
waking inbox insertion starts the driver before send returns
2026-08-04 13:49:35 +08:00
-> emit agent/status(running) if starting an interval
-> 'turn/start'
2026-07-31 22:00:39 +08:00
claim next-step input plus one next-turn message
2026-07-31 19:21:16 +08:00
-> emit agent/inbox/claimed({ message, turn }) for each claimed message
2026-08-06 13:44:23 +08:00
-> agent/pre-step({ agent, messages, turn, step, signal })
2026-08-04 13:49:35 +08:00
reject, empty input, cancellation, or listener failure
-> the claimed batch stays removed; close the no-step turn; stop the driver
enter -> step loop:
2026-07-31 19:21:16 +08:00
'step/start'
append the returned batch as separate 'user/message' events
2026-07-31 22:16:40 +08:00
assemble ordered prompt and tool schemas -> snapshot derived messages
2026-07-31 09:28:52 +08:00
agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
2026-07-24 16:05:52 +08:00
'assistant/chunk'
'assistant/message'
schedule tool calls by ctx.tools.executionMode:
2026-07-29 22:10:26 +08:00
exclusive -> barrier
2026-07-31 22:00:39 +08:00
parallel -> rolling pool, < = maxParallelToolCalls; reclassify at start
start -> 'tool/call' -> tools/pre-execute -> concurrent tools/execute
2026-07-29 22:10:26 +08:00
model-order result -> ordered tools/post-execute -> 'tool/result'
2026-07-24 16:05:52 +08:00
'step/end'
2026-07-31 19:21:16 +08:00
tools owe another request or next-step inbox is nonempty
2026-07-31 22:00:39 +08:00
-> claim -> agent/pre-step -> append entered batch -> continue
2026-07-31 19:21:16 +08:00
otherwise agent/turn-stopping -> re-check the next-step inbox
2026-07-31 22:16:40 +08:00
'turn/end'
2026-07-24 16:05:52 +08:00
start the next waking queued message, or emit agent/status(idle)
idle inject:
2026-07-31 19:21:16 +08:00
queue non-waking next-step context
leave it pending until followup or steer wakes the driver
2026-07-05 18:51:52 +08:00
```
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-27 17:04:22 +08:00
Each step assembles ordered prompt sections, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona; the loop supplies `provider` , `model` , and `cwd` ([prompt ownership ](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-08-06 13:44:23 +08:00
`inject()` queues non-waking `next-step` context; an idle driver leaves it pending until `followup()` or `steer()` wakes the driver. Post-tool `additionalContexts` use the same inbox. The `agent/pre-step` payload carries the exclusive claimed batch and the upcoming turn, step, and signal. Reject opens no step; enter supplies the complete batch appended after `step/start` . Empty tool continuations still traverse the waterfall, whose final value settles all rewrites.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-08-05 20:43:30 +08:00
Pruning precedes summaries; overflow retries require durable progress. `agent/request-error` may authorize a same-step retry of the frozen prompt; cancellation wins. Adapter `retryPolicy` bounds normal mode, while always mode retries after specialized recovery ([compaction ](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md ), [retry foundation ](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md ), [provider policy ](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md )). The generated [agent lifecycle ](agent-lifecycle.md ) owns exact event order, and the [agent-loop README ](../packages/core/agent-loop/README.md ) owns queue, steering, retry, and cancellation mechanics.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 18:51:52 +08:00
### Failure Boundaries
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-31 22:00:39 +08:00
Adapter selection, dispatch, and iteration failures become terminal error or aborted `finish` chunks. `agent/request-error` receives request coordinates, normalized `LlmFailure` , available retry policy, and signal; middleware and consumer errors remain outside recovery. Failed chunks commit neither messages nor tool calls.
2026-07-15 16:03:52 +08:00
2026-07-31 22:00:39 +08:00
Other failures use `agent/error` ; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call` /`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision ](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-08-04 14:09:52 +08:00
Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason ](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap ).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:52:07 +08:00
### Agent Handles
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-31 22:16:40 +08:00
`ctx.agents` owns agents and returns `AgentHandle { agent, dispose() }` . Plugins use `send()` or its `followup()` , `steer()` , and `inject()` presets. `cancel()` and `whenIdle()` control lifecycle, while awaited disposal owns teardown. A follow-up `MessageId` follows durable inbox insertion, claiming, and discard notifications, not prompt output or turn ending; only an owner of a whole activity interval may summarize it as a run result ([decision ](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
docs: agent-scope RFC, CONTEXT.md glossary, architecture scope section, README sync
The agent-scope-contexts RFC (implemented) records the decision tree:
the dsh-scope primitive over cordis extend/Context.filter/no-op fibers,
two-level flat scope with shadowing, restriction/grant semantics, the
scoped-dispatch rule with fused helpers, the setup window, and the
alternatives (explicit scope params, isolate, event-filtering-only,
vendored support) with why each lost. CONTEXT.md pins the glossary.
architecture.md gains the Agent Scope section, the dsh-scope spine row,
the scoped turn-flow line, and an extension-table row (ceiling 1640→1790:
the two-layer registration model is a new architectural axis; additions
are condensed to pointers). READMEs of every touched package re-state
their scoped facts; the stale structured-runtime README section is
replaced by the scoped-registration description.
2026-07-09 03:01:11 +08:00
### Agent Scope
2026-07-27 17:04:22 +08:00
Each agent owns scoped `agent.ctx` ; shared storage overlays its tool, prompt, and command entries on globals while preserving domain views ([decision ](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md )). Scoped listeners filter dispatch; contributions unwind with awaited cleanup. `CreateAgentOptions.setup(agentCtx)` composes before publication. Typed resolvers derive carrier checks from merged `Events` and `scopeTarget` ([semantic gates ](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md )). Details: [agent scope ](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md ), [subagent composition ](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md ). `AgentLoop` runs under `ctx.agents.withInitiator()` ; private orchestration derives `agent.session` , but turn, step, signal, cwd, and authority stay explicit ([decision ](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md )).
2026-07-05 19:52:07 +08:00
2026-07-09 23:48:29 +08:00
## State
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:07:34 +08:00
### Session Log
2026-07-05 18:51:52 +08:00
2026-07-27 17:04:22 +08:00
The session log is authoritative. `deriveMessages()` projects model history; raw `assistant/chunk` events preserve replay and UI fidelity. Fork, resume, transcript rendering, telemetry, and persistence derive from this stream.
2026-07-05 18:51:52 +08:00
2026-07-31 22:16:40 +08:00
**Model-visible ⟺ logged**: messages entering at `step/start` plus the folded `request/header` reconstruct every request. The header marks adapter defaults so later proposals discard them and re-resolve the route without losing explicit settings. `request/context` separately records registration-bound provider, model, and capacity metadata when the route changes; it does not participate in request reconstruction or header equality. `dsh-agent-loop/invariant` asserts reconstructability through `ctx.invariants` ([reconstructability ](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md )).
docs: the governing principle — every LLM request is reconstructable from the session log
The reconstructability RFC is the principle's home: model-visible ⟺
logged in both forms, the mechanism (boundary derivation + header
fold), the enforcement (write-time round-trip guard, the dev
invariant), the corollaries ranked (prefix-cache stability first), the
MiniCode lineage with the provenance arrow inverted, and the
alternatives it beat — including the stateful transmission client
whose three-design archaeology lives in PR #162.
Placements per the one-home-per-fact taxonomy: a standing-order line in
root AGENTS.md (with displacement trims to stay inside the 1,575-word
ceiling), the principle statement in architecture.md § Session Log and
its Turn Flow lines (condensed to the ratcheted 1,630 ceiling), the
request-envelope section in core-data-structures/core.md with the
LlmCallConfig paste, both review-requested FIXMEs
(FIXME(call-config-shape) beside the type, FIXME(catalog-verbs) at the
catalog's drift-gate note), cookbook rows redirected off agent/request
(tool filtering → system-prompt/assemble, plan-mode prompt → sections/
inject()), and the llm/stream JSDoc stating the frozen-request
contract. RFC index and all generated catalogs regenerated.
2026-07-06 03:49:35 +08:00
2026-07-31 22:00:39 +08:00
Durability is a plugin concern. Backends eagerly drain synchronous `session/event` notifications. `session/flush` precedes requests and top-level tool dispatch, and follows `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([decision ](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md )).
2026-06-15 20:56:17 +08:00
2026-07-31 22:16:40 +08:00
Between turns, owners append log-only events through `Session` , flushing only for durability. `session/title` needs eager persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; latest wins with provenance. Title records are inherited fork boundaries ([decision ](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:07:34 +08:00
### Model Content
2026-06-15 20:56:17 +08:00
2026-07-27 17:04:22 +08:00
Messages use typed blocks from merge-extensible `ContentBlockMap` ; the pattern also types `MessageSource` , `FinishReason` , `TurnTrigger` , and `TurnEndReason` . New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md ](core-data-structures/token-meter.md ).
2026-06-15 23:53:47 +08:00
2026-07-27 21:17:49 +08:00
Streaming uses raw chunks and `BlockAssembler` . Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract ](core-data-structures/llm-streaming.md )).
2026-06-11 12:18:52 +08:00
2026-07-05 19:07:34 +08:00
## Extension And Composition
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:07:34 +08:00
### Capability Pattern
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-27 17:04:22 +08:00
A swappable capability usually has **interface / implementation / consumer** layers: service/events, backend, and model-facing tools/prompts. Bash is the reference; the [capability graph ](capability-seams.md ) maps each family.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-27 17:04:22 +08:00
Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, or use ACP children ([subagent.md ](core-data-structures/subagent.md )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-08-05 14:46:48 +08:00
`dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision ](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md )). `dsh-paths` owns shared paths.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-05 19:07:34 +08:00
### Bundles And Apps
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-08-04 10:07:17 +08:00
`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own CLI, ACP automation, and JSON-RPC front doors ([README ](../packages/examples/agent-spine-demo/README.md ), [acp/ ](../packages/acp/README.md ), [ui/ ](../packages/ui/README.md )). `dsh-jsonrpc-agent` boots external `cordis.yml` ; the Python SDK defaults when config is absent ([Python SDK ](../python/README.md )). Thin deployments use swappable backends and optional tools ([examples/ ](../examples/AGENTS.md ), [runnable wirings ](cookbook/extension-cookbook.md#runnable-wirings ), [graph atlas ](graph-atlas.md )).
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
docs(agent-presets): bring the note and the architecture map up to what shipped
The Agent Note was written when only the seam existed and never caught up.
Rewritten in place, per the implemented-note contract, with the four facts the
later work established:
- a preset file is an INPUT: `EntryTree.write()` persists a tree whenever the
Loader thinks the config changed, and a self-disposing plugin is enough, so
the inherited behaviour truncates a shipped preset to `[]` the first time a
session ends
- a plugin that looks itself up in the global registry breaks inside a preset,
because `register()` files into the calling context's scope — the general
rule behind the `dsh-tool-skill` fix
- an entry-local `isolate` realm is invisible to the agent's own scope too, not
only to the host, which is what makes a preset's registry that agent's own
and also why a consumer left outside the group silently contributes nothing
- switching is blank-only, and why it swaps the subtree rather than the session
`docs/architecture.md` gains an Agent Presets section: the map has to carry a
new architectural concept or it is wrong, and the root layout gains the group.
Both budget ceilings are raised rather than the content cut. `AGENTS.md` sat at
1774/1775 — one word of room, already far under the 5% headroom the standard
asks for — so no group line could be added at all; `architecture.md` was in the
same shape. Raising restores headroom instead of encoding "the map may not grow".
2026-08-04 11:17:26 +08:00
### Agent Presets
A deployment may compose each session's model-facing plugin set separately. An **agent preset** is a directory holding one `agent.cordis.yml` , mounted as an `include` subtree under that agent's scope during `setup(agentCtx)` , so its tool and prompt registrations file into that agent's layer and unwind with it — no new tier in the registries. The host composition keeps what must be shared: the registries themselves, cross-session facilities, the sandbox and approval stack, the model route. `ctx.agentPresets` owns discovery and the guarded mount, rejecting a row that never activates or that publishes into the root service realm. Details: [per-session agent presets ](../.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md ), [preset/ ](../packages/preset/README.md ).
2026-07-05 19:07:34 +08:00
### Where New Behavior Goes
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-19 22:11:59 +08:00
New behavior attaches to a documented extension point; a loop change updates this map.
docs(architecture): rewrite the system map to the 1,800-word budget
architecture.md is the behavior map: layering, service map, seam
pattern, and the loop — everything else defers to its owning tier.
- Seam narrations compress to two-to-four sentences plus links to the
RFC and type-catalog homes that carry the detail (turn-end variant
semantics -> session.md, derivation mapping -> session.md, StreamChunk
conventions -> llm-streaming.md + source).
- The MVP feature-to-mechanism checklist moves de-statused into the
extension cookbook as 'The feature -> mechanism map' — mechanisms
only, no implementation-status bolding to rot; the microkernel RFC's
proof-obligation pointer follows it.
- The layering diagram describes layers by family instead of
enumerating packages (the stale 'future plugins: hooks, compaction'
row is gone); the dependency rule defers to packages/README.md.
- The loop pseudocode, the three externally-cited anchors (the
vocabulary, event taxonomy, waterfall semantics), and the filename
are unchanged.
- Budget ratchet: docs/architecture.md 3897 -> 1800 (now 1,797 words);
the doc-tiers RFC's deferred list prunes the item this ships.
2026-07-04 14:43:48 +08:00
2026-07-05 03:32:11 +08:00
| Goal | Mechanism |
|---|---|
2026-07-27 17:04:22 +08:00
| Add a model provider | register its adapter on `ctx.llm` |
| Add a model-facing capability | register on `ctx.tools` ; schemas join prompt assembly |
docs(agent-presets): bring the note and the architecture map up to what shipped
The Agent Note was written when only the seam existed and never caught up.
Rewritten in place, per the implemented-note contract, with the four facts the
later work established:
- a preset file is an INPUT: `EntryTree.write()` persists a tree whenever the
Loader thinks the config changed, and a self-disposing plugin is enough, so
the inherited behaviour truncates a shipped preset to `[]` the first time a
session ends
- a plugin that looks itself up in the global registry breaks inside a preset,
because `register()` files into the calling context's scope — the general
rule behind the `dsh-tool-skill` fix
- an entry-local `isolate` realm is invisible to the agent's own scope too, not
only to the host, which is what makes a preset's registry that agent's own
and also why a consumer left outside the group silently contributes nothing
- switching is blank-only, and why it swaps the subtree rather than the session
`docs/architecture.md` gains an Agent Presets section: the map has to carry a
new architectural concept or it is wrong, and the root layout gains the group.
Both budget ceilings are raised rather than the content cut. `AGENTS.md` sat at
1774/1775 — one word of room, already far under the 5% headroom the standard
asks for — so no group line could be added at all; `architecture.md` was in the
same shape. Raising restores headroom instead of encoding "the map may not grow".
2026-08-04 11:17:26 +08:00
| Give one session a different capability set | compose it in an agent preset; a service row there needs an `isolate` realm |
2026-07-27 19:55:55 +08:00
| Add shell execution | implement and register a `ctx.bash` backend; the local backend spawns through `ctx.subprocess` |
2026-07-27 17:04:22 +08:00
| Add persistent terminal execution | register a `ctx.pty` backend plus `dsh-tool-pty` |
| Add a human command | register on `ctx.commands` ; adapters discover and dispatch without a model turn |
2026-07-19 22:11:59 +08:00
| Add background work | register on `ctx.tasks` ; generic `task_*` tools collect or stop it |
2026-07-27 17:04:22 +08:00
| Add filesystem access or policy | implement a `ctx.fs` provider or listen to `fs/*` policy events |
| Confine spawned processes | use a `ctx.sandbox` backend; consumers wrap argv before spawning |
2026-07-27 17:38:42 +08:00
| Intercept a request, tool, or turn | use its `agent/*` or `tools/*` event; `agent/turn-stopping` is the stop boundary |
2026-07-31 19:21:16 +08:00
| Add model-facing context | call `agent.inject()` to queue sourced context for the next admitted request |
2026-08-04 10:07:17 +08:00
| Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
2026-07-27 17:04:22 +08:00
| Add durable session state | extend `SessionEventMap` ; render and replay from the log |
| Add asynchronous session-title generation | register the sole `ctx.sessionTitle` provider |
2026-07-20 20:13:39 +08:00
| Manage a same-session objective | use `ctx.goals` ; continue through `Agent` and `agent/*` |
2026-07-27 17:04:22 +08:00
| Fork a live session | call `ctx.sessions.fork(source, boundary?, childSessionId?)` |
| Scope a registration to one agent | use its `agent.ctx` (see Agent Scope) |
2026-07-09 23:48:29 +08:00
2026-07-27 17:04:22 +08:00
The [extension cookbook ](cookbook/extension-cookbook.md ) has plugin skeletons and the feature-to-seam map; guides cover [packages ](cookbook/adding-a-package.md ), [tools ](cookbook/adding-a-tool.md ), [LLM adapters ](cookbook/adding-an-llm-adapter.md ), and [vendored packages ](cookbook/adding-a-vendored-package.md ).
