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-08-09 12:13:58 +08:00
| `ctx.agentDefaultModel` | [`dsh-agent-default-model` ](../packages/core/agent-default-model/README.md ) | Settings-backed model selection shared by Agent front doors |
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 |
fix(rebase): migrate the replayed stack onto current master APIs
The linear replay carried each commit's own lineage, so this checkpoint
restores the master-owned surfaces the conflicted regions clobbered and
migrates branch-owned code to master's post-rebase APIs:
- rebuild subprocess-local spawn.ts on master's tree-exit-observer
machinery, keeping the branch's win32 childEnv key semantics and the
Linux zombie-quiescence probe; the zombie test reaps its survivor
directly since a confirmed-absent verdict is a permanent
no-more-signals boundary
- migrate pty-local test stubs to the Inbox-model Agent interface,
Session.create, runnerFailureRules, and the new turn/start payload
- implement the seam's resolveExecutable/spawnTerminal abstracts in the
new pwsh-local and tool-fs-search test fakes
- restore code-runtime, atomic-write, pwsh-local, and app-boot to
master's exact content (the net-zero code-runtime churn is pruned
from this history) and drop rename-detection graft debris
- re-apply the PR's architecture rows and execution-world paragraph,
re-record bilingual pairings, regenerate catalogs, and reconcile the
lockfile
2026-08-07 20:34:31 +08:00
| `ctx.subprocess` | [`subprocess/` ](../packages/subprocess/README.md ) | executable lookup, managed trees, terminals |
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 |
fix(rebase): migrate the replayed stack onto current master APIs
The linear replay carried each commit's own lineage, so this checkpoint
restores the master-owned surfaces the conflicted regions clobbered and
migrates branch-owned code to master's post-rebase APIs:
- rebuild subprocess-local spawn.ts on master's tree-exit-observer
machinery, keeping the branch's win32 childEnv key semantics and the
Linux zombie-quiescence probe; the zombie test reaps its survivor
directly since a confirmed-absent verdict is a permanent
no-more-signals boundary
- migrate pty-local test stubs to the Inbox-model Agent interface,
Session.create, runnerFailureRules, and the new turn/start payload
- implement the seam's resolveExecutable/spawnTerminal abstracts in the
new pwsh-local and tool-fs-search test fakes
- restore code-runtime, atomic-write, pwsh-local, and app-boot to
master's exact content (the net-zero code-runtime churn is pruned
from this history) and drop rename-detection graft debris
- re-apply the PR's architecture rows and execution-world paragraph,
re-record bilingual pairings, regenerate catalogs, and reconcile the
lockfile
2026-08-07 20:34:31 +08:00
| `ctx.fs` | [`fs/` ](../packages/fs/README.md ) | execution-world paths, bounded IO, 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 |
refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
| `ctx.sessionPersistence` | [`session/` ](../packages/session/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 |
refactor(session): fold the session family into packages/session/
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
2026-07-30 01:52:06 +08:00
| `ctx.sessionTitle` | [`session/session-title` ](../packages/session/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-08-07 15:48:29 +08:00
| `ctx.typertGateway` | [`api/gateway` ](../packages/api/gateway/README.md ) | dispatches TypeRT Remote unary calls through the [API Gateway ](api-gateway.md ) |
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-30 21:40:58 +08:00
Events are the service extension API ([subsystems ](subsystems/core.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-22 18:02:26 +08:00
Waterfalls are around-middleware: listeners delegate with `next()` ; returning without it short-circuits 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-15 16:03:52 +08:00
'step/start'
2026-07-31 19:21:16 +08:00
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-08-09 15:35:02 +08:00
agent/request (config only) -> resolve adapter defaults and mark defaulted fields + 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-08-07 14:54:31 +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. Waking input that lands after the abort fires but before convergence runs at the driver's convergence boundary, while a `disposed` cancel leaves it parked ([cancel-convergence wake latch ](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md )). 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-07-28 18:06:07 +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 ](subsystems/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-08-08 15:43:52 +08:00
Durability is a plugin concern. Backends copy synchronous `session/event` notifications into fixed-window durable batches; `session/flush` bypasses the wait before requests and top-level tool dispatch, and after `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([checkpoint decision ](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md ), [batching decision ](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md )).
2026-06-15 20:56:17 +08:00
2026-08-09 15:35:02 +08:00
Between turns, owners append log-only events through `Session` , flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; the latest title event wins, and it records the source message seqs and whether the user, fallback, or provider supplied it. 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-28 18:06:07 +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 ](subsystems/token-meter.md ).
2026-06-15 23:53:47 +08:00
2026-08-09 15:35:02 +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, the successful provider/model route, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract ](subsystems/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
fix(rebase): migrate the replayed stack onto current master APIs
The linear replay carried each commit's own lineage, so this checkpoint
restores the master-owned surfaces the conflicted regions clobbered and
migrates branch-owned code to master's post-rebase APIs:
- rebuild subprocess-local spawn.ts on master's tree-exit-observer
machinery, keeping the branch's win32 childEnv key semantics and the
Linux zombie-quiescence probe; the zombie test reaps its survivor
directly since a confirmed-absent verdict is a permanent
no-more-signals boundary
- migrate pty-local test stubs to the Inbox-model Agent interface,
Session.create, runnerFailureRules, and the new turn/start payload
- implement the seam's resolveExecutable/spawnTerminal abstracts in the
new pwsh-local and tool-fs-search test fakes
- restore code-runtime, atomic-write, pwsh-local, and app-boot to
master's exact content (the net-zero code-runtime churn is pruned
from this history) and drop rename-detection graft debris
- re-apply the PR's architecture rows and execution-world paragraph,
re-record bilingual pairings, regenerate catalogs, and reconcile the
lockfile
2026-08-07 20:34:31 +08:00
Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph ](capability-seams.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-28 18:06:07 +08:00
Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md ](subsystems/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-06 10:16:16 +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. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. 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
refactor(packages): dissolve ui/ and rename sdk/ to scaffold/
git mv per the regrouping RFC: the five human-collaboration seams and
tui join packages/interaction/, app-boot becomes packages/boot/, and
jsonrpc joins the renamed scaffold/ (formerly sdk/) as its server half
beside client/protocol/create-sdk/helper/scripts/telemetry, whose
folders drop the legacy sdk- prefix. Three new group README triplets
replace the ui/ and sdk/ ones; tsconfig references/paths/globs,
knip keys, vitest globs, gate scripts, catalogs, docs, and the
lockfile follow. Adds the four settled FIXME rename markers
(dsh-sdk-server, dsh-sdk-telemetry, dsh-sdk-helper, dsh-sdk-scripts).
The scaffold folders diverge from their npm names until those renames
land, so tsconfig.base.json maps the three affected names explicitly
beside the group wildcard. Also repairs two pre-existing stale-path
classes the strengthened sweep surfaced: docs/web-styling.md's retired
web-ui host package and type-model spec fixture-literal joins.
app-boot's three Loader-composition specs time out at the default 5s
under full-suite parallel load on this filesystem (pre-existing;
pass isolated with --testTimeout=30000); interaction/scaffold/boot
suites otherwise green (687 passed).
2026-07-30 03:13:49 +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 ), [interaction/ ](../packages/interaction/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
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 |
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 ).
