Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
# DeepSeek Harness Architecture
2026-07-21 01:54:00 +08:00
English | [中文 ](architecture.zh.md )
2026-07-21 02:13:10 +08:00
**DeepSeek Harness SDK** uses Cordis: **everything is a plugin** , including the loop.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-09 23:48:29 +08:00
## Overview
docs: accuracy sweep, architecture restructure, two ADRs, review skill
- AGENTS.md Commands: fix typecheck/build descriptions; add lint, lint:fix,
test:coverage, knip, publint, hygiene (were undocumented).
- Drop the bare `yarn demo` for explicit `demo:echo` + `demo:coding`; update
README, examples READMEs (and document coding-agent in examples/README).
- New cookbook guide: adding-a-vendored-package.md (the missing "add" half of
vendor/README's update-only procedure).
- architecture.md: add a table-of-contents and extract the Extension cookbook
to docs/cookbook/extension-cookbook.md (link-preserving); drop the completed
"restructure this document" TODO.
- ADR 0009 (capability seams) + 0010 (twin LLM adapters), and a "when to write
an ADR" standard in adr/README.
- Add a committed dsh-code-review skill under .agents/skills, exposed to Claude
Code via a tracked .claude/skills symlink (gitignore carve-out).
2026-06-13 18:50:13 +08:00
2026-07-31 22:00:39 +08:00
Harnesses are [Cordis ](cordis-primer.md ) contexts; packages contribute services, typed events, and disposable registrations. `packages/core/` groups the default flow; capabilities remain plugins.
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
2026-07-09 23:48:29 +08:00
### Default Services
Document the architecture and rewrite AGENTS.md
docs/architecture.md: layering, service map, event taxonomy, the
session/turn/step lifecycle, Cordis waterfall semantics, an extension
cookbook, the plugin sanity checklist mapping every MVP feature to its
extension mechanism, and the deferred-work TODO list (sub-agents,
persistence backends, compaction, DeepSeek V4 adapter, parallel tool
execution, streaming-protocol review).
AGENTS.md: repo layout, commands, conventions (dsh-* naming, ESM,
effect-based registrations, declaration merging, waterfall semantics),
and the vendoring policy pointer.
2026-06-11 10:55:05 +08:00
docs(architecture): rewrite the system map to the 1,800-word budget
architecture.md is the behavior map: layering, service map, seam
pattern, and the loop — everything else defers to its owning tier.
- Seam narrations compress to two-to-four sentences plus links to the
RFC and type-catalog homes that carry the detail (turn-end variant
semantics -> session.md, derivation mapping -> session.md, StreamChunk
conventions -> llm-streaming.md + source).
- The MVP feature-to-mechanism checklist moves de-statused into the
extension cookbook as 'The feature -> mechanism map' — mechanisms
only, no implementation-status bolding to rot; the microkernel RFC's
proof-obligation pointer follows it.
- The layering diagram describes layers by family instead of
enumerating packages (the stale 'future plugins: hooks, compaction'
row is gone); the dependency rule defers to packages/README.md.
- The loop pseudocode, the three externally-cited anchors (the
vocabulary, event taxonomy, waterfall semantics), and the filename
are unchanged.
- Budget ratchet: docs/architecture.md 3897 -> 1800 (now 1,797 words);
the doc-tiers RFC's deferred list prunes the item this ships.
2026-07-04 14:43:48 +08:00
| ctx key | Package | Role |
|---|---|---|
2026-07-27 17:04:22 +08:00
| — | [`dsh-scope` ](../packages/core/scope/README.md ) | scoped-context registrations and shared layer storage (library) |
2026-07-05 03:32:11 +08:00
| `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions |
2026-07-27 17:04:22 +08:00
| `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and variables |
2026-07-05 19:52:07 +08:00
| `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline ](tool-execution-pipeline.md ) |
2026-07-27 17:04:22 +08:00
| `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, process-local initiator scope |
2026-07-22 15:13:12 +08:00
| `ctx.agentDefaultModel` | [`dsh-agent-default-model` ](../packages/core/agent-default-model/README.md ) | Settings-backed model selection shared by Agent entry points |
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 |
2026-08-10 11:28:38 -07:00
| `ctx.messageFeedback` | [`feedback/` ](../packages/feedback/README.md ) | lifecycle-bound editable feedback for individual assistant messages and its Host Remote contract |
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 19:33:19 +08:00
-> assemble system prompt
-> agent/pre-step({ agent, messages, turn, step, signal })
2026-08-04 13:49:35 +08:00
reject, empty input, cancellation, or listener failure
2026-08-06 19:33:19 +08:00
-> the claimed batch stays removed; close the no-step turn; stop the driver
2026-08-04 13:49:35 +08:00
enter -> step loop:
2026-07-15 16:03:52 +08:00
'step/start'
2026-08-06 19:33:19 +08:00
append the returned batch as separate 'user/message' events
2026-08-06 15:03:48 +08:00
render the assembled prompt and tool schemas -> snapshot derived messages
agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
2026-07-24 16:05:52 +08:00
'assistant/chunk'
'assistant/message'
schedule tool calls by ctx.tools.executionMode:
2026-07-29 22:10:26 +08:00
exclusive -> barrier
2026-07-31 22:00:39 +08:00
parallel -> rolling pool, < = maxParallelToolCalls; reclassify at start
start -> 'tool/call' -> tools/pre-execute -> concurrent tools/execute
2026-07-29 22:10:26 +08:00
model-order result -> ordered tools/post-execute -> 'tool/result'
2026-07-24 16:05:52 +08:00
'step/end'
2026-07-31 19:21:16 +08:00
tools owe another request or next-step inbox is nonempty
2026-08-06 19:33:19 +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-08-06 19:33:19 +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 19:33:19 +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. `agent/pre-step` receives the exclusive claimed batch and 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-09 15:27:21 +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. The driver processes waking input received after abort starts but before convergence; 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-09 15:27:21 +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 uses the same checkpoint and batching rules ([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
2026-08-09 15:34:32 +08:00
A **seam** is a swappable capability with **Service Definition** , **Service provider** , and **Consumer** roles. Packages may combine roles; individual roles are not seams. Filesystem and subprocess providers share one execution world; Bash, PTY, and LSP need no provider forks ([capability graph ](capability-seams.md )).
2026-07-20 14:45:32 +08:00
2026-08-09 15:34:32 +08:00
Exceptions combine LLM Service Definition/Consumer roles, filesystem policy, web registries, and skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate a self-contained turn to Codex or another product provider ([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
2026-07-22 15:13:12 +08:00
`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own CLI, ACP automation, and JSON-RPC entry points ([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
docs(agent-presets): bring the note and the architecture map up to what shipped
The Agent Note was written when only the seam existed and never caught up.
Rewritten in place, per the implemented-note contract, with the four facts the
later work established:
- a preset file is an INPUT: `EntryTree.write()` persists a tree whenever the
Loader thinks the config changed, and a self-disposing plugin is enough, so
the inherited behaviour truncates a shipped preset to `[]` the first time a
session ends
- a plugin that looks itself up in the global registry breaks inside a preset,
because `register()` files into the calling context's scope — the general
rule behind the `dsh-tool-skill` fix
- an entry-local `isolate` realm is invisible to the agent's own scope too, not
only to the host, which is what makes a preset's registry that agent's own
and also why a consumer left outside the group silently contributes nothing
- switching is blank-only, and why it swaps the subtree rather than the session
`docs/architecture.md` gains an Agent Presets section: the map has to carry a
new architectural concept or it is wrong, and the root layout gains the group.
Both budget ceilings are raised rather than the content cut. `AGENTS.md` sat at
1774/1775 — one word of room, already far under the 5% headroom the standard
asks for — so no group line could be added at all; `architecture.md` was in the
same shape. Raising restores headroom instead of encoding "the map may not grow".
2026-08-04 11:17:26 +08:00
### Agent Presets
A deployment may compose each session's model-facing plugin set separately. An **agent preset** is a directory holding one `agent.cordis.yml` , mounted as an `include` subtree under that agent's scope during `setup(agentCtx)` , so its tool and prompt registrations file into that agent's layer and unwind with it — no new tier in the registries. The host composition keeps what must be shared: the registries themselves, cross-session facilities, the sandbox and approval stack, the model route. `ctx.agentPresets` owns discovery and the guarded mount, rejecting a row that never activates or that publishes into the root service realm. Details: [per-session agent presets ](../.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md ), [preset/ ](../packages/preset/README.md ).
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 |
docs(agent-presets): bring the note and the architecture map up to what shipped
The Agent Note was written when only the seam existed and never caught up.
Rewritten in place, per the implemented-note contract, with the four facts the
later work established:
- a preset file is an INPUT: `EntryTree.write()` persists a tree whenever the
Loader thinks the config changed, and a self-disposing plugin is enough, so
the inherited behaviour truncates a shipped preset to `[]` the first time a
session ends
- a plugin that looks itself up in the global registry breaks inside a preset,
because `register()` files into the calling context's scope — the general
rule behind the `dsh-tool-skill` fix
- an entry-local `isolate` realm is invisible to the agent's own scope too, not
only to the host, which is what makes a preset's registry that agent's own
and also why a consumer left outside the group silently contributes nothing
- switching is blank-only, and why it swaps the subtree rather than the session
`docs/architecture.md` gains an Agent Presets section: the map has to carry a
new architectural concept or it is wrong, and the root layout gains the group.
Both budget ceilings are raised rather than the content cut. `AGENTS.md` sat at
1774/1775 — one word of room, already far under the 5% headroom the standard
asks for — so no group line could be added at all; `architecture.md` was in the
same shape. Raising restores headroom instead of encoding "the map may not grow".
2026-08-04 11:17:26 +08:00
| Give one session a different capability set | compose it in an agent preset; a service row there needs an `isolate` realm |
2026-07-27 19:55:55 +08:00
| Add shell execution | implement and register a `ctx.bash` backend; the local backend spawns through `ctx.subprocess` |
2026-07-27 17:04:22 +08:00
| Add persistent terminal execution | register a `ctx.pty` backend plus `dsh-tool-pty` |
| Add a human command | register on `ctx.commands` ; adapters discover and dispatch without a model turn |
2026-07-19 22:11:59 +08:00
| Add background work | register on `ctx.tasks` ; generic `task_*` tools collect or stop it |
2026-07-27 17:04:22 +08:00
| Add filesystem access or policy | implement a `ctx.fs` provider or listen to `fs/*` policy events |
| Confine spawned processes | use a `ctx.sandbox` backend; consumers wrap argv before spawning |
2026-08-09 15:27:21 +08:00
| Intercept a request, tool, or turn | use its `agent/*` or `tools/*` event; `agent/turn-stopping` is the event that stops a turn |
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-08-09 19:36:15 +08:00
| Web Client Chat node | register a `ConversationNodeDefinition` + keyed renderer |
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-08-12 21:07:57 +08:00
[Extension cookbook ](cookbook/extension-cookbook.md ) maps features to capabilities; guides cover [packages ](cookbook/adding-a-package.md ), [tools ](cookbook/adding-a-tool.md ), [LLM adapters ](cookbook/adding-an-llm-adapter.md ), [Chat nodes ](cookbook/adding-a-conversation-node.md ), [settings cards ](cookbook/adding-a-settings-card.md ), and [vendored packages ](cookbook/adding-a-vendored-package.md ).
