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-24 12:27:20 +08:00
Harnesses are [Cordis ](cordis-primer.md ) contexts with package-contributed services, typed events, and disposable registrations.
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-21 22:59:41 +08:00
`packages/core/` groups the default agent 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-21 22:24:45 +08:00
| — | [`dsh-scope` ](../packages/core/scope/README.md ) | scoped-context registration and shared layer storage (library) |
2026-07-05 03:32:11 +08:00
| `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions |
2026-07-05 20:54:48 +08:00
| `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and prompt variables |
2026-07-05 19:52:07 +08:00
| `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline ](tool-execution-pipeline.md ) |
2026-07-19 16:41:51 +08:00
| `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, and 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 |
|---|---|---|
| `ctx.llm` | [`llm/` ](../packages/llm/README.md ) | adapter registry and streaming model calls |
2026-07-16 12:58:07 +08:00
| `ctx.tokenMeter` | [`llm/token-meter` ](../packages/llm/token-meter/README.md ) | singleton replay-aware request/surface pressure |
2026-07-05 03:32:11 +08:00
| `ctx.bash` | [`bash/` ](../packages/bash/README.md ) | foreground/background command execution |
2026-07-26 16:50:36 +08:00
| `ctx.subprocess` | [`subprocess/` ](../packages/subprocess/README.md ) | managed child-process trees for the bash executors, the LSP host, and the ACP subagent backend |
2026-07-21 16:01:00 +08:00
| `ctx.pty` | [`pty/` ](../packages/pty/README.md ) | owner-scoped persistent terminal sessions |
2026-07-09 16:44:32 +08:00
| `ctx.sandbox` | [`sandbox/` ](../packages/sandbox/README.md ) | same-world process confinement (argv wrapping, 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-10 14:19:06 +08:00
| `ctx.skills` | [`skill/` ](../packages/skill/README.md ) | skill provider registry and progressive disclosure |
2026-07-05 03:32:11 +08:00
| `ctx.web` | [`web/` ](../packages/web/README.md ) | search/fetch provider registries |
2026-07-19 17:54:55 +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 |
feat(tasks): background task runtime, generic task_* control tools, bash/subagent producers
One shared ctx.tasks registry (branded <kind>-N ids, owner-fenced
read/kill/wait/list, attachSurface misconfiguration fence, reported-flag
notice dedup, atomic register) + dsh-tool-tasks (task_output/task_list/
task_kill, completion-notice injection, background prompt habit).
Producers opt in via their own enableRunInBackground config: bash
(stream kind; seam slimmed to resolve/run/start returning a BashProcess
handle, bash_output/bash_kill deleted) and subagent (final-output kind;
done settles after run.dispose()). Owner disposal drains tasks through
the new awaited ctx.agents.onCleanup seam in the loop's disposal chain.
Both RFCs moved to implemented/; docs, catalogs, snapshots re-pinned.
2026-07-09 21:22:54 +08:00
| `ctx.tasks` | [`tasks/` ](../packages/tasks/README.md ) | background task registry + generic `task_*` control tools |
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-24 15:09:55 +08:00
| `ctx.sessionQuery` | [`session-query/` ](../packages/session-query/README.md ) | Live-preferred exact/filter/trace interface, SQLite FTS backend, and workspace-authorized model tools |
2026-07-23 21:13:29 +08:00
| `ctx.sessionTitle` | [`session-title/` ](../packages/session-title/README.md ) | log-backed fallbacks plus one optional asynchronous provider |
| `ctx.invariants` | [`support/invariants` ](../packages/support/invariants/README.md ) | package-name-selected registry for 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-24 12:27:20 +08:00
Events form the service extension API; see the [catalog ](cordis-catalog/events.md ) and [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-21 01:54:00 +08:00
- **Session events** are durable facts appended to the log and emitted through `session/event` .
- **Agent events** carry the live `Agent` for status, prompt admission, request shaping, validation, and continuation.
- **Capability events** let owning seams attach policy and adapters without importing 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-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
refactor(agent): replace the per-step advice seam with agent/session-prefix
Review discussion converged on the industry shape (Claude Code caches
user context per conversation; Codex separates initial context from
diffs; Kimi appends at continuation boundaries to protect prompt
caching): stable openers belong in a compose-once prefix, mid-session
changes belong in append-only history — not in a per-request slot.
agent/session-prefix fires ONCE per loop instance, lazily on its first
request-building step: the composed Message[] is deep-frozen, cached on
the transmission bookkeeping, recorded as EpochHeader.messagePrefix on
the anchoring 'initial'/'resume' snapshot, and reused verbatim for
every request the instance sends — prefix stability is structural, not
a producer discipline, and a resume recomposes with attributable drift.
The request is messagePrefix + boundary snapshot.
The per-step RequestAdvice/RequestAdviceContext surface and the
messageSuffix header field are dropped: the tail slot had no consumer,
and every current update pattern (new AGENTS.md discovered, memory
update, skills change) routes through the existing append-only history
channels — inject(), tools/post-execute additionalContext,
prompt-submit additionalContext — each paid once and prefix-cached
thereafter. The messagePrefix delta arm stays for codec totality; the
loop never produces one in practice.
2026-07-08 15:44:30 +08:00
Waterfall events behave like around-middleware: a listener delegates by calling `next()` ; returning without it vetoes or takes over. Full rule: [Cordis waterfall 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-07-24 12:27:20 +08:00
The loop runs through plugin services and events.
2026-06-13 18:39:20 +08:00
2026-07-24 12:27:20 +08:00
A **session** is append-only. Each ordinary **turn** claims one queued message; injection claims none. Successors await the preceding checkpoint but may share its `running` interval ([decision ](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md )). A **step** is one model request plus tools; quotes in the [sequence below ](agent-lifecycle.md ) mark durable events.
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-24 12:27:20 +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 failures emit `agent-loop/config-start-failed` ; teardown is silent.
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-07-14 11:23:38 +08:00
choose declarative identity and fresh/resume path
-> prepare private session + agent.ctx -> await unpublished setup
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-07-17 17:14:52 +08:00
wait for a queued message
2026-07-05 18:51:52 +08:00
emit agent/status(running)
TURN:
'turn/start'
2026-07-21 21:57:21 +08:00
claimed message + contexts -> agent/prompt-submit
2026-07-22 17:34:31 +08:00
allowed prompt -> 'user/message' with prompt-prefix context baked in; append separate contexts
2026-07-17 17:14:52 +08:00
blocked prompt -> 'prompt/blocked' -> 'turn/end'(rejected)
2026-07-05 18:51:52 +08:00
STEP loop:
2026-07-22 17:34:31 +08:00
drain steering with the same prefix/separate context placement (no prompt-submit)
2026-07-05 19:07:34 +08:00
assemble system prompt and tool schemas
2026-07-08 20:30:10 +08:00
agent/session-prefix (first step)
2026-07-05 19:07:34 +08:00
agent/pre-step
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
snapshot the derived messages (the reconstruction boundary)
2026-07-15 16:03:52 +08:00
'step/start'
2026-07-25 22:59:45 +08:00
agent/request -> prepare reasoning/default under turn signal -> log request/header -> checkpoint -> llm/stream (frozen, registration-bound)
2026-07-19 13:13:36 +08:00
on final adapter-path or terminal in-band failure:
2026-07-15 16:03:52 +08:00
'step/end'
2026-07-20 03:34:19 +08:00
agent/request-error(original error, failure facts, immutable prior failures, signal)
2026-07-15 16:03:52 +08:00
retry in the next numbered step or preserve the original error
otherwise:
2026-07-05 19:07:34 +08:00
'assistant/chunk'
2026-07-15 16:03:52 +08:00
agent/step-result
2026-07-16 10:14:33 +08:00
'assistant/message' (transformed content or empty success anchor after step-result rejection)
2026-07-19 12:06:23 +08:00
schedule tool calls by ctx.tools.executionMode:
exclusive -> one-call barrier
parallel -> rolling pool, < = maxParallelToolCalls in flight; reclassify before start
2026-07-21 14:50:06 +08:00
each start -> 'tool/call' -> ordered tools/pre-execute -> checkpoint -> concurrent tools/execute
2026-07-19 12:06:23 +08:00
each model-order result -> ordered tools/post-execute -> 'tool/result'
append accepted tool-batch context after all recorded results, then steering
2026-07-21 14:50:06 +08:00
agent/post-step -> checkpoint complete response/results
2026-07-15 16:03:52 +08:00
'step/end'
agent/turn-continuation
agent/turn-stop (terminal policy)
stop unless tools or continuation policy ask for another step
2026-07-05 19:07:34 +08:00
'turn/end'
checkpoint persistence and notify idle/running status
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-24 12:27:20 +08:00
Steps assemble ordered prompt sections, tool schemas, and variables; unknown references fail turns. `dsh-system-prompt` owns identity and persona; the loop supplies `model` and `cwd` ([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-07-24 12:27:20 +08:00
Async `inject()` and post-tool `additionalContexts` settle after results; steering drains before `agent/post-step` . Leftovers queue. Terminal `agent/turn-stop` remains authoritative through close/flush and discards later steering, not queued prompts.
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-24 12:27:20 +08:00
Pruning precedes summaries; overflow retries require durable progress. Bounded retries compose on `agent/request-error` ; cancellation wins ([compaction ](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md ), [retry ](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 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-24 12:27:20 +08:00
Adapter failures close the step before `agent/request-error` with exact `Error` , `LlmFailure` , and history. Retries open steps; success clears history; exhaustion stores failure on `turn/end` . Failed chunks commit nothing.
2026-07-15 16:03:52 +08:00
2026-07-25 22:59:45 +08:00
Other failures use `agent/error` . Cancellation and disposal beat recovery; the turn signal also cancels asynchronous model-capability preparation before any request header is committed, and undispatched tools get synthetic `tool/call` /`ABORTED_BEFORE_DISPATCH` pairs. The signal retires before `turn/end` . Effective `cancel()` emits its cause, clears queues, and aborts; observers cannot veto, idle calls emit nothing, and durability records `aborted` . Disposal 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-07-24 12:27:20 +08:00
Session events are turn-enclosed; reload closes an interrupted tail with a synthetic `interrupted` turn end. Post-close failures use `agent/error` . 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-24 15:08:36 +08:00
`ctx.agents` returns `AgentHandle { agent, dispose() }` . Plugins use intent helpers `followup()` , `queue()` , `steer()` , and `inject()` ; callers with exact routing facts use mandatory-field `send()` ([decision ](../.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md )). `cancel()` and `whenIdle()` control lifecycle. Caller, provider, and handle co-own teardown.
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-24 12:27:20 +08:00
Each agent owns a scoped `agent.ctx` over global tool, prompt, and command storage ([decision ](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md )); scoped listeners filter and contributions unwind with awaited cleanup. `CreateAgentOptions.setup(agentCtx)` composes before publication; typed resolvers derive carrier checks from `Events` and `scopeTarget` ([gates ](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md )). `AgentLoop` runs inside `ctx.agents.withInitiator()` ; private orchestration derives `agent.session` , while turn, step, signal, cwd, and authority stay explicit ([decision ](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md )). See [agent scope ](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md ) and [subagent composition ](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.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-24 12:27:20 +08:00
The session log is authoritative. `deriveMessages()` projects model history; raw `assistant/chunk` events preserve replay and UI fidelity. Fork, resume, transcripts, telemetry, and persistence share that stream.
2026-07-05 18:51:52 +08:00
2026-07-24 12:27:20 +08:00
**Model-visible ⟺ logged**: `step/start` messages plus the header's session prefix and folded `request/header` reconstruct every request; `dsh-agent-loop/invariant` asserts this through `ctx.invariants` ([decision ](../.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-24 12:27:20 +08:00
Durability is a plugin concern; backends buffer synchronous `session/event` notifications. Checkpoints drain before adapter dispatch, recorded top-level tool calls before tool dispatch, complete response/result batches at `agent/post-step` , and final turn ends. `SessionPersistence` stores `SessionEvent` plus `SessionHeader` metadata; JSONL defaults to checksummed Zstandard, with SQLite under one contract ([decision ](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md )).
2026-06-15 20:56:17 +08:00
2026-07-21 22:59:41 +08:00
`ctx.sessions.appendOutOfBand()` joins plugin-owned log-only events to an open turn or creates a balanced, flushed zero-step turn. `session/title` folds latest-wins with source seqs and provenance; its immediate fallback and sole optional async provider never delay the agent response. Forks inherit titles ([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-21 22:59:41 +08:00
Messages use typed blocks from merge-extensible `ContentBlockMap` ; the same pattern 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-21 22:59:41 +08:00
Streaming uses raw chunks and `BlockAssembler` . Each `LlmAdapter.stream()` is one provider attempt; adapters report facts and `agent/request-error` owns recovery. The loop logs chunks and successful provenance/replay state. Remote adapters use per-read idle watchdogs. Replay state crosses routes only when they share an 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-19 22:11:59 +08:00
A swappable capability usually splits into **interface / implementation / consumer** : service/events, a 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-19 22:11:59 +08:00
Exceptions combine layers: LLM interface/consumer; filesystem policy; web registries; 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-07-19 22:50:49 +08:00
`dsh-workspace-context` composes baselines on `agent/session-prefix` and appends `ctx.fs` -discovered nested changes on `tools/post-execute` ; its [decision ](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md ) records isolation. `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-07-24 22:12:23 +08:00
`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own TUI, 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 supplies a default only without explicit config ([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
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 |
|---|---|
| Add a model provider | register an adapter on `ctx.llm` |
2026-07-19 22:11:59 +08:00
| Add a model-facing capability | register on `ctx.tools` ; schemas enter prompt assembly |
refactor(subprocess): rename the process seam to subprocess and address review
Review feedback (tianyicui): 'process' is a poor service name. The family is
now packages/subprocess/ — @deepseek-ai/dsh-subprocess (ctx.subprocess,
abstract SubprocessService, Subprocess* vocabulary) and
@deepseek-ai/dsh-subprocess-local (LocalSubprocessService) — renamed
throughout code, compositions, docs (en+zh, pairs re-recorded), catalogs,
and gates. 'subprocess' is the precise term for managed OS children (the
Python-stdlib sense), avoids colliding with Node's global process object,
and reads as one system beside dsh-subagent-subprocess.
ds-review-bot findings addressed:
- kill() on a settled handle is now a no-op (no signal to a possibly-reused
pgid, no referenced grace timer delaying exit); pinned by a spy test.
- The moved DshEnvironmentKey/DshEnvironment/CollectedOutput types get
drift-checked type-equiv blocks on the new subprocess.md page, restoring
their manifest registration.
- subprocess.md is registered in the core.md sub-page index (en+zh).
2026-07-26 12:43:14 +08:00
| Add shell execution | implement and register a `ctx.bash` backend (the local one spawns through `ctx.subprocess` ) |
2026-07-21 16:01:00 +08:00
| Add persistent terminal execution | register a `ctx.pty` backend and `dsh-tool-pty` |
2026-07-19 22:11:59 +08:00
| Add a human command | register on `ctx.commands` ; adapters discover and dispatch it without a model turn |
| Add background work | register on `ctx.tasks` ; generic `task_*` tools collect or stop it |
2026-07-05 19:52:07 +08:00
| Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events |
2026-07-09 16:44:32 +08:00
| Confine spawned processes | a `ctx.sandbox` backend; consumers wrap their argv before spawning |
2026-07-19 22:11:59 +08:00
| Intercept a request, tool, or turn | use its `agent/*` or `tools/*` event; `agent/turn-stop` is the serial terminal stop |
| Add a session-stable prefix outside history | compose `agent/session-prefix` ; the request header logs it |
2026-07-22 21:30:08 -07:00
| Add UI or editor integration | drive `ctx.agents` and render from `session/event` ; terminal-only overlays use `ctx.tui` |
2026-07-05 03:32:11 +08:00
| Add durable session state | add a `SessionEventMap` member and render/replay from the log |
2026-07-21 01:54:00 +08:00
| Add asynchronous session-title generation | register the sole provider on `ctx.sessionTitle` |
2026-07-20 20:13:39 +08:00
| Manage a same-session objective | use `ctx.goals` ; continue through `Agent` and `agent/*` |
2026-07-07 09:04:49 +08:00
| Fork a live session | use `ctx.sessions.fork(source, boundary?, childSessionId?)` |
2026-07-19 22:11:59 +08:00
| Scope a registration to one agent | use that agent's `agent.ctx` (see Agent Scope) |
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
The [extension cookbook ](cookbook/extension-cookbook.md ) carries plugin skeletons and the feature-to-seam map; step-by-step 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 ).
2026-07-09 23:48:29 +08:00
## Quick Reference
2026-07-12 22:49:46 +08:00
- Domain terms in the [glossary ](glossary.md )
2026-07-09 23:48:29 +08:00
- Type definitions in [core-data-structures/ ](core-data-structures/core.md )
2026-07-21 22:59:41 +08:00
- Exact signatures in the [event ](cordis-catalog/events.md ) and [service ](cordis-catalog/services.md ) catalogs
2026-07-09 23:48:29 +08:00
- package contracts in the [package map ](../packages/README.md )
2026-07-19 22:50:49 +08:00
- [Agent Notes ](../.agents/notes/README.md )
