2026-06-11 15:27:07 +08:00
# RFCs
2026-06-18 02:18:24 +08:00
One kind of design doc lives here. An **RFC** records a decision or proposal that shapes this codebase — the *why* and *what we gave up* , the parts code and docs can't carry. (Earlier this split into separate "ADR" and "RFC" trees; they were unified, since most ADRs were simply implemented RFCs.)
## Layout and naming
2026-06-20 22:29:45 +08:00
Every RFC has two axes, both encoded in its **path** — `{lifecycle}/{class}/yyyy-mm-dd-topic-title.md` :
2026-06-18 02:18:24 +08:00
2026-06-20 22:29:45 +08:00
- **Lifecycle** (the top-level folder) is the RFC's status, and an RFC moves between folders as that status changes:
- **`proposed/` ** — proposals reviewed before implementation; not yet built (or only partly).
- **`implemented/` ** — the decision shipped. The file records what was decided and what was rejected, and is **kept current with what actually shipped** : when the code later moves a file, renames a package, or changes a key/default, the RFC is updated in the same change to match (facts only — paths, names, structure — not the decision itself). See [implemented/AGENTS.md ](implemented/AGENTS.md ).
- **`rejected/` ** — the proposal was considered and declined. Kept for the record so the rejection isn't re-litigated.
- **Class** (the nested folder) is the *kind* of decision — see [Classification ](#classification ) below.
2026-06-18 02:18:24 +08:00
2026-06-20 22:29:45 +08:00
The date in the filename is when the topic was **first proposed** (per git history). Cross-references between RFCs use relative markdown links (`[topic](../../implemented/architecture/2026-…-….md)` ) — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.
## Classification
Each RFC is filed under exactly one **class** — the kind of decision it records. The class is encoded in the path (the folder *is* the label, so a file's location declares its class) and the set is **closed** : `scripts/verify-rfc-classification.ts` rejects any folder outside the set and asserts this index lists every RFC under the heading matching its path. Adding a new class means amending that gate and this section, not just dropping a new folder. See [the classification RFC ](implemented/process/2026-06-20-rfc-classification.md ) for why the taxonomy is path-encoded and gated.
| Class | What it covers |
|---|---|
| `feature` | A new user- or model-facing capability. |
| `bug-fix` | Corrects a defect or closes a gap a postmortem surfaced. |
| `simplification` | Removes code, behavior, or surface area without adding a capability. |
| `architecture` | A structural decision about the **shipped source** — how packages relate, what the runtime vocabulary is. |
| `process` | Tooling, policy, or workflow **around** the code — gates, the package manager, vendoring — not runtime behavior. |
| `testing` | Test infrastructure and strategy. |
The `architecture` / `process` line: **architecture** is about the source we ship; **process** is the surrounding tooling and workflow. (`refactor` is deliberately absent — it overlaps `simplification` , whose discriminator, "does observable behavior change?", already covers it.)
2026-06-18 02:18:24 +08:00
## When to write one
2026-06-20 22:29:45 +08:00
Write an RFC when a decision is **durable** (it shapes the codebase beyond a single function or package), **contested** (there was a real alternative a reasonable engineer might have chosen), and **surprising** (a future reader would otherwise ask "why on earth is it done this way?"). A proposal for substantial future work starts in `proposed/` ; a decision already made starts in `implemented/` . Pick the class folder that matches the decision (see [Classification ](#classification )).
2026-06-18 02:18:24 +08:00
2026-06-19 17:06:20 +08:00
Do NOT write one for a mechanical or local choice (a variable name, a one-file refactor), for anything already enforced and explained by a gate or a convention in AGENTS.md, or for a still-provisional decision tagged `TODO(...)` in the code — record those as TODOs and promote to an RFC only once they settle. An RFC is never edited into a *different decision* : supersede it with a new one and cross-link. (Editing an `implemented/` RFC to track where its already-made decision now *lives* — a moved file, a renamed package — is not a different decision and is required, not forbidden; see [implemented/AGENTS.md ](implemented/AGENTS.md ).)
2026-06-18 02:18:24 +08:00
## Proposed
2026-06-20 22:29:45 +08:00
### Feature
| Title | First proposed |
|---|---|
| [Agent Client Protocol (ACP) support for external editors ](proposed/feature/2026-06-14-acp-agent-client-protocol.md ) | 2026-06-14 |
| [Multiplex concurrent ACP sessions over one connection ](proposed/feature/2026-06-14-acp-multi-session.md ) | 2026-06-14 |
| [Optional Code Mode — model writes TypeScript against an SDK of all tools ](proposed/feature/2026-06-15-optional-code-mode.md ) | 2026-06-15 |
2026-06-30 17:11:18 +08:00
| [Pre-tool input rewrite — a consistent design ](proposed/feature/2026-06-30-pre-tool-input-rewrite.md ) | 2026-06-30 |
2026-06-20 22:29:45 +08:00
### Simplification
| Title | First proposed |
|---|---|
| [Unify the agent id and the session id ](proposed/simplification/2026-06-20-unify-agent-and-session-id.md ) | 2026-06-20 |
2026-07-04 02:39:50 +08:00
| [Narrow the subagent seam to synchronous collect ](proposed/simplification/2026-07-04-narrow-subagent-synchronous-collect.md ) | 2026-07-04 |
| [Drop idle registry observation surfaces ](proposed/simplification/2026-07-04-drop-idle-registry-observation-surfaces.md ) | 2026-07-04 |
| [Prune the bash task roster from the public seam ](proposed/simplification/2026-07-04-prune-bash-task-roster.md ) | 2026-07-04 |
| [Remove defaults from the tool-schema DSL ](proposed/simplification/2026-07-04-remove-tool-schema-defaults.md ) | 2026-07-04 |
2026-06-20 22:29:45 +08:00
### Architecture
| Title | First proposed |
|---|---|
| [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern) ](proposed/architecture/2026-06-16-typed-event-schemas.md ) | 2026-06-16 |
| [Extract a generic long-running tool runtime ](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md ) | 2026-06-20 |
### Process
| Title | First proposed |
|---|---|
| [Architectural conformance — dependency rules and the adapter kit ](proposed/process/2026-06-11-architectural-conformance.md ) | 2026-06-11 |
| [API extractor reports ](proposed/process/2026-06-11-api-extractor-reports.md ) | 2026-06-11 |
| [Supply chain checks and vendor drift verification ](proposed/process/2026-06-11-supply-chain-and-vendor-drift.md ) | 2026-06-11 |
| [Discover package inventories instead of maintaining static lists ](proposed/process/2026-06-20-discover-package-inventory.md ) | 2026-06-20 |
### Testing
2026-06-18 02:18:24 +08:00
| Title | First proposed |
|---|---|
2026-06-20 22:29:45 +08:00
| [Mutation testing as the coverage counterweight ](proposed/testing/2026-06-11-mutation-testing.md ) | 2026-06-11 |
| [Deterministic tests, the replay invariant fixture, and race stress ](proposed/testing/2026-06-11-deterministic-and-stress-testing.md ) | 2026-06-11 |
2026-06-18 02:18:24 +08:00
## Implemented
2026-06-20 22:29:45 +08:00
### Feature
| Title | First proposed |
|---|---|
2026-06-22 10:48:41 +08:00
| [Filesystem tool schemas — model-facing read/write/edit shapes ](implemented/feature/2026-06-17-filesystem-tool-schemas.md ) | 2026-06-17 |
2026-06-20 22:29:45 +08:00
| [Rich ACP bash rendering — the terminal card (`_meta`) and command classification ](implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md ) | 2026-06-18 |
2026-06-26 08:59:33 +08:00
| [Compaction as a capability seam (abstract contract + basic backend) ](implemented/feature/2026-06-18-compaction-capability-seam.md ) | 2026-06-18 |
Add the ACP subagent backend: out-of-process delegation (PR3)
The first OUT-OF-PROCESS subagent backend, proving the seam generalizes past the
in-process backends. @deepseek-ai/dsh-subagent-acp runs each child agent in a
spawned subprocess, driven over the Agent Client Protocol as the CLIENT — the
direction-inverted twin of the dsh-acp server bridge. Point the configured
command at the acp-agent example and the harness talks to its own process.
- Fresh process per run: start spawns, runs one ACP session (initialize →
newSession → prompt), dispose kills the subprocess and awaits its exit.
- Minimal client stub: advertises no fs/terminal; accumulates agent_message_chunk
text as the result output; auto-answers session/request_permission by a
configured policy (reject default / allow). No start-time capabilities (an
out-of-process child can't enforce the parent's depth/tool-filter); ignores
request.parent; injects only `subagents`.
- StopReason mapping (end_turn→completed, cancelled→aborted, …); result resolves
error/aborted on a child failure, never rejects (seam contract).
- Security: credential-shaped ambient env vars are scrubbed; the child's own key
is forwarded only via explicit config.env. A spawn-level error (ENOENT) is
captured and raced against the ACP drive so a bad command settles error rather
than crashing the parent.
Testing designed at every tier: keyless integration drives a scripted mock ACP
server subprocess (cancellation incl. the pre-newSession race and a
torn-pipe-after-cancel, permission auto-answer, non-message updates, spawn
failure, HMR, export shape) at 100% coverage; a with-key e2e drives the REAL
acp-agent example process (PONG + real file write, verified on disk) — the
harness driving itself. Snapshot coverage of an ACP child is deferred as
TODO(acp-subagent-replay) (each child is its own process with its own replay).
Stayed on @agentclientprotocol/sdk 0.25.1: the proposed 0.28.x bump only
deprecates the stable ClientSideConnection/AgentSideConnection API this layer
uses (33 sites incl. the server bridge), turning no-deprecated red across code
this PR shouldn't rewrite — that fluent-API migration is its own follow-up. The
backend needs nothing 0.28.x adds.
This completes the subagent seam stack (PR1 interface → PR2 in-process → PR2.5
snapshot infra → PR3 ACP); the seam RFC moves to implemented/, amended.
2026-06-22 10:47:02 +08:00
| [Subagent capability seam ](implemented/feature/2026-06-21-subagent-capability-seam.md ) | 2026-06-21 |
| [ACP subagent backend (out-of-process delegation) ](implemented/feature/2026-06-22-acp-subagent-backend.md ) | 2026-06-22 |
feat(tool-todo): add the model-facing todo_write tool
Add @deepseek-ai/dsh-tool-todo (a new packages/todo/ group): a model-facing
todo_write(todos: [{content, status}]) tool with whole-list-replace semantics.
Each call appends the full list as a todo/write event to the calling agent's
session log; the current list is the most recent such event (last-write-wins).
Single-owner — a non-agent caller is rejected. Beyond the schema's
type/required/enum checks, execute rejects empty/duplicate content and more than
one in_progress task, narrowing the loosely-typed args into a real TodoItem[].
Both UIs render off the existing session/event: the stdio UI prints a glyphed
checklist; the ACP bridge maps the list to a `plan` sessionUpdate (todosToPlan
synthesizes the priority ACP requires; status maps 1:1). Wired into the
coding-agent, acp-agent, and snapshot example configs with a system-prompt nudge.
Tests: unit (schema, validation, append/replace, no-agent rejection, presentCall,
HMR-safety, Loader export-shape guard), full-loop integration through the agent
loop, the ACP todosToPlan mapping + stream-update arm, the stdio render arm, and
a session/load replay that re-emits the plan. New-group TS wiring added to
tsconfig.base/json/build. RFC + a doc-inventory sweep (architecture, packages
README, AGENTS layout, cookbook group list, example READMEs) ship with it.
The todo-plan ACP snapshot scenario is recorded separately (needs an API key).
2026-06-29 10:30:52 +08:00
| [The `todo_write` tool — model task list as event-sourced session state ](implemented/feature/2026-06-29-todo-write-tool.md ) | 2026-06-29 |
2026-06-30 17:11:18 +08:00
| [Interception seams — the typed-Decision surface a hook programs against ](implemented/feature/2026-06-30-interception-seams.md ) | 2026-06-30 |
2026-07-02 05:52:02 +08:00
| [Subagent lifecycle enrichment — lastAssistantMessage (observe-only) ](implemented/feature/2026-06-30-subagent-observe-enrich.md ) | 2026-06-30 |
feat(hooks): dsh-hook-protocol — shared Claude Code / Codex hook wire-protocol core
The two hook bridges (dsh-hooks-claude, dsh-hooks-codex) would otherwise duplicate
the bulk of the protocol — Codex deliberately reimplements a SUBSET of the Claude
Code protocol (same hooks.json shape, exit-code/stdout contract, command-hook
model). This library holds the genuinely-identical primitives; each bridge owns
only what differs (per-event stdin payload, env/substitution, decision mapping).
New packages/hooks/ group; hook-protocol is a LIBRARY (no plugin, registers/injects
nothing):
- matcher: matchesMatcher(pattern, query, mode) — the one dialect axis collapsed to
a mode param (claude = literal-or-regex with pipe alternation; codex = always
unanchored regex). Match-all on absent/''/'*'; invalid regex matches nothing.
- codec: parseHookOutput(exit, stdout, stderr) → dialect-neutral HookOutput. Exit 0
→ lenient JSON; exit 2 → blocking error (stderr = reason, surfaced as
decision:'block'); other → non-blocking. Parses the CC superset
(continue/stopReason/decision/hookSpecificOutput.{permissionDecision,
additionalContext,updatedInput}/systemMessage); permissionDecision overrides the
legacy top-level decision.
- runner: runHook(bash, hook, opts, now) — runs a command hook via ctx.bash (stdin
payload + trusted-plugin env), honors timeoutSec, never throws (executor reject →
non-blocking-error HookOutput). Injected clock for testable durations.
- merge: mergeHookOutputs — most-restrictive fold (deny>ask>allow, sticky stop,
block reasons joined, context/system-messages accumulated).
- hook/* session events (declaration-merged into SessionEventMap, log-only like
compact/*) + appendHookInvoked/appendHookResult helpers.
updatedInput is parsed but NOT honored (deferred pre-tool-input-rewrite RFC); a
bridge logs+warns. 47 unit tests at per-file 100% (matcher per-mode, codec per
exit-code/field, runner plumbing w/ stub executor, merge precedence, hook/*
helpers). RFC: implemented/feature/2026-06-30-hook-protocol-lib.md.
2026-07-01 00:38:06 +08:00
| [dsh-hook-protocol — the shared Claude Code / Codex hook wire-protocol core ](implemented/feature/2026-06-30-hook-protocol-lib.md ) | 2026-06-30 |
feat(hooks): dsh-hooks-claude + dsh-hooks-codex bridges (hooks stack PR-F)
The two bridge plugins that run a user's existing Claude Code / Codex hook
config on the harness's typed interception seams, built on the shared
dsh-hook-protocol library. A bridge is a faithfulness adapter, not a power
tool: anything it does a native cordis plugin does more powerfully — the
bridge exists only to run UNMODIFIED external hooks.
- dsh-hooks-claude: CC dialect. Seven hook points (SessionStart,
UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart,
SubagentStop), CC per-event stdin payloads, env + ${CLAUDE_PLUGIN_ROOT}/
${CLAUDE_PROJECT_DIR} substitution, literal-or-regex matcher.
- dsh-hooks-codex: Codex dialect — a deliberate subset. Five hook points,
always-regex matcher, snake_case payloads (turn_id/model, no trailing
newline), no env/substitution, block-only decisions.
Both map the neutral merged outcome onto the seam's typed Decision and stamp
an explicit {kind:'plugin'} source on injected context (so it is never
mislabeled as a user prompt). Config parse-failure is contained; only command
hooks run. updatedInput is logged+warned (input rewrite deferred); the Stop
loop-guard is deferred (TODO).
Tests: per-file 100% — config-parse unit branches + per-seam mappings
end-to-end through the REAL loop + REAL bash + REAL shell scripts (scripted
mock model only) + a real-Loader export-shape guard. A keyless ACP snapshot
scenario (hook-prompt-block) proves a UserPromptSubmit hook blocks a prompt
end-to-end (rejected turn -> ACP cancelled, hook/* events in the log); a
with-key e2e (hooks.e2e.ts) proves a PreToolUse hook blocks real bash
(verified on disk). The snapshot normalizer now scrubs hook/result.durationMs.
RFC: docs/rfc/implemented/feature/2026-06-30-hook-bridges.md
2026-07-01 04:22:00 +08:00
| [dsh-hooks-claude + dsh-hooks-codex — the Claude Code / Codex hook bridges ](implemented/feature/2026-06-30-hook-bridges.md ) | 2026-06-30 |
2026-06-20 22:29:45 +08:00
### Simplification
| Title | First proposed |
|---|---|
| [Drop the mutable session summary ](implemented/simplification/2026-06-19-drop-mutable-session-summary.md ) | 2026-06-19 |
2026-06-21 01:27:41 +08:00
| [Drop unconsumed assembled LLM convenience surfaces ](implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md ) | 2026-06-20 |
| [Drop the unconsumed `llm/adapter-change` event ](implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md ) | 2026-06-20 |
2026-06-21 11:05:56 +08:00
| [Prune dead methods from the persistence seam ](implemented/simplification/2026-06-20-prune-dead-seam-methods.md ) | 2026-06-20 |
2026-06-21 09:10:56 +08:00
| [Keep one public stop primitive ](implemented/simplification/2026-06-20-public-agent-stop-surface.md ) | 2026-06-20 |
2026-06-21 10:00:06 +08:00
| [Fold trace-only session facts into load-bearing events ](implemented/simplification/2026-06-20-collapse-trace-only-session-events.md ) | 2026-06-20 |
2026-07-02 03:26:45 +08:00
| [Stop mirroring durable boundaries as agent events ](implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md ) | 2026-06-20 |
fix(fs): address review — rename to dsh-fs-policy, fs/*-intent events, RFC currency, ENOTDIR
Rename per review naming decisions:
- package dsh-file-context → dsh-fs-policy (dir, package name, plugin name,
tsconfig refs, importers, type-equiv manifest, generated catalog + module-graph)
- events fs/write-expectation → fs/write-intent, fs/edit-expectation → fs/edit-intent
(fs/observed unchanged); type FsWriteExpectation → FsWriteIntent, "expectation"
wording → "intent" throughout
- exported FileContextExec → FsPolicyExec
Make the implemented RFCs describe what shipped, not the superseded designs:
the 2026-06-17 capability-seam + tool-schemas RFCs no longer place policy on
ctx.fs or use full/partial-view authorization, and the fsspec RFC's ctx.fileContext
service prose is rewritten to the fs/* event-gate reality (freshness-based auth).
Sharpen docs/rfc/implemented/AGENTS.md: a rename is a fact to fix IN PLACE — the
"new RFC" escape hatch is for macro decision reversals only, not renames.
Code fixes from review:
- fsio.ts resolveLocalTarget/probe translate ENOTDIR (a parent path segment is a
file) into the structured FsError taxonomy instead of leaking a raw Node error;
resolve reports FS_NOT_FOUND, probe reports absent. Regression tests proven to
fail on the unfixed code.
- tool-fs HMR test now asserts prompt sections (not just tool schemas) are
withdrawn on disposal.
- fs/observed is a plain (unguarded) ctx.emit: correct the fs-policy comment,
filesystem.md, and tool-fs module doc that wrongly claimed the tool "contains"
a throwing listener; a throw surfaces as the tool's isError result.
- drop the false "loaded by the default product config" claim (no config wires
the fs tools yet), the duplicate ctx.bash service-map row, the stale
FileReadRequest catalog link-map entry, and the fs/fs README EOF blank line;
correct the dsh-fs package.json description.
2026-07-02 03:12:38 +08:00
| [Split the filesystem seam — provider text mutations plus the `dsh-fs-policy` plugin ](implemented/simplification/2026-06-26-fsspec-style-fs-seam.md ) | 2026-06-26 |
2026-07-02 23:42:16 +08:00
| [Stop mirroring the token stream as an agent event ](implemented/simplification/2026-07-02-remove-stream-chunk-mirror.md ) | 2026-07-02 |
2026-06-20 22:29:45 +08:00
### Architecture
| Title | First proposed |
|---|---|
| [Microkernel: extension via Cordis event taxonomy, one concrete loop ](implemented/architecture/2026-06-11-microkernel-event-taxonomy.md ) | 2026-06-11 |
| [Event-sourced sessions with derived message history ](implemented/architecture/2026-06-11-event-sourced-sessions.md ) | 2026-06-11 |
| [Provider-neutral content-block vocabulary owned by dsh-llm ](implemented/architecture/2026-06-11-content-block-vocabulary.md ) | 2026-06-11 |
| [Custom typed tool-schema DSL instead of schemastery ](implemented/architecture/2026-06-11-custom-schema-dsl.md ) | 2026-06-11 |
| [Tool schemas are part of the system-prompt assembly ](implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md ) | 2026-06-11 |
| [Runtime arg validation at the model boundary ](implemented/architecture/2026-06-11-runtime-arg-validation.md ) | 2026-06-11 |
| [Dev-mode invariants over compile-time deep-readonly ](implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md ) | 2026-06-11 |
| [Structured error taxonomy ](implemented/architecture/2026-06-11-structured-error-taxonomy.md ) | 2026-06-11 |
| [Capability seams — interface / implementation / consumer split ](implemented/architecture/2026-06-13-capability-seams.md ) | 2026-06-13 |
| [Two LLM adapters as a design-verification twin ](implemented/architecture/2026-06-13-twin-llm-adapters.md ) | 2026-06-13 |
| [Session persistence as an abstract service over `SessionEvent` ](implemented/architecture/2026-06-14-session-persistence.md ) | 2026-06-14 |
| [Every session event is enclosed in a turn ](implemented/architecture/2026-06-15-turn-enclosure-invariant.md ) | 2026-06-15 |
2026-06-22 10:48:41 +08:00
| [Filesystem capability seam — ctx.fs, local backend, and model-facing filesystem tools ](implemented/architecture/2026-06-17-filesystem-capability-seam.md ) | 2026-06-17 |
2026-06-20 22:29:45 +08:00
| [Shared persistence write coordinator ](implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md ) | 2026-06-18 |
| [Agent lifecycle and ownership seams ](implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md ) | 2026-06-18 |
2026-06-22 10:35:59 +08:00
| [Session surface — a linked list over the event log for LLM message derivation ](implemented/architecture/2026-06-18-session-surface.md ) | 2026-06-18 |
2026-06-20 23:25:33 +08:00
| [Reorganize packages into a modular hierarchy ](implemented/architecture/2026-06-20-package-hierarchy.md ) | 2026-06-20 |
feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand
Type-only change (brands are zero-cost casts; no runtime/wire impact). Closes
the two gaps in the "brand ids that cross package boundaries" policy and fixes
the dependency direction so a capability package never pulls in an unrelated one.
- Extract the `Branded<B>` primitive into a new standalone type-only package
`@deepseek-ai/dsh-brand` (packages/util/brand) with no harness-package deps.
dsh-llm keeps its owned CallId but imports Branded from dsh-brand; dsh-session,
dsh-agent, and dsh-bash all import Branded from there. dsh-bash depends on
dsh-brand ALONE — never on dsh-llm or dsh-session (the architectural fix: a
generic execution backend must not couple to the LLM or session vocabulary).
- Mint BashTaskId + OwnerToken in dsh-bash and thread them through BashTask.id,
the get/ownerOf/list/readOutput/kill seam, the bash-local generation site, and
the dsh-tool-bash validate/access surface. OwnerToken is a DISTINCT brand from
SessionId so the seam stays decoupled; dsh-tool-bash is the single boundary
that casts SessionId -> OwnerToken.
- Brand at the SOURCE, not via mid-pipeline casts: agent-loop's Config types
agents[].id as AgentId and resumeSessionId as SessionId, so the brand enters
at the config boundary and the inner create()/resume casts disappear (only the
genuinely-new per-run session-id string is cast).
- Stop brand erosion: propagate CallId/SessionId/AgentId to the registry/store
Map keys and public params/exports (SessionStore, AgentRegistry + factory
options, the ACP session-id surface + ToolPresenter CallId map, the
persistence coordinator, invariants pendingCalls, the pi-ai tool-call maps).
- Docs: document BashTaskId/OwnerToken in bash.md (type-equiv re-pasted), point
the Branded type-equiv at dsh-brand, fix stale param types in the session/
agent/bash READMEs, regenerate the cordis catalog + module graph.
Implements docs/rfc/proposed/architecture/2026-06-20-branded-ids.md
2026-06-21 07:17:25 +08:00
| [Branded IDs everywhere they belong ](implemented/architecture/2026-06-20-branded-ids.md ) | 2026-06-20 |
refactor(examples): extract the app spine into dsh-agent-core + app packages
Implements docs/rfc/.../2026-06-20-extract-example-app-packages.md. Each
example was thick — a hand-rolled start.ts, an infra preamble, nested
base.yml/base-core.yml/acp-tail.yml includes, and a coupled front-door
cluster enforced only by prose. This moves the composition into packages so
each example is a thin leaf cordis.yml: pick the swappable backends, load one
app package.
New packages:
- @deepseek-ai/dsh-agent-core (packages/core/agent-core): one bundle plugin
that loads the providerless/executor-less/UI-less spine (timer + llm +
sessions + system-prompt + tools + agents + invariants + tool-bash +
agent-loop) via ctx.plugin(...) inside apply(), and forwards agent-loop's
`agents` list as its own Config (export const Config = AgentLoop.Config,
default []).
- @deepseek-ai/dsh-stdio-agent (packages/ui/stdio-agent): terminal chat APP —
agent-core + console logger + readline UI + a pre-created `main` agent, with
a bin. The demo:echo/coding front door.
- @deepseek-ai/dsh-acp-agent (packages/ui/acp-agent): ACP server APP —
agent-core + JSONL persistence + the acp bridge, NO stdout logger, with a
bin. The stdout-purity footgun is structurally unreachable from the leaf.
Amendment to the RFC: hmr stays a LEAF cordis.yml entry, not baked into
dsh-stdio-agent. hmr is a Loader-only dev plugin (throws without
--expose-internals; the in-process test tier can't even import its decorator
form), so a package statically importing it could never carry the per-file
coverage gate. Unlike the console logger, a stray hmr is not a stdout-purity
footgun, so leaving it at the leaf costs no safety. With hmr out, all three new
packages carry in-process unit specs at 100%.
Boot glue (Loader tail, .env load, snapshot-mode selection, stdin-dispose
lifecycle) moves into each app's bin; start.ts and base.yml/base-core.yml/
acp-tail.yml are deleted. Each app package gets a keyless real-load-path test
that boots through its bin + the cordis Loader (guarding the unwrapExports
export-shape bug class, postmortem 0001). ACP snapshot replay stays green
against the existing committed goldens (pure boot restructuring). RFC moved
proposed->implemented with the amendment recorded; package/example/architecture
docs and the module graph updated.
2026-06-21 12:03:44 +08:00
| [Extract example apps into packages ](implemented/architecture/2026-06-20-extract-example-app-packages.md ) | 2026-06-20 |
Add web capability seam: ctx.web, search/fetch providers, web tools
Introduce web access as a first-class capability seam so the model-facing
web tools stay stable while backends change. dsh-web owns ctx.web as a
provider registry with registration-order-independent selection and the
WebError taxonomy; dsh-web-search-exa, dsh-web-search-perplexity, and
dsh-web-fetch-local register capabilities into it; dsh-tool-web is the sole
owner of the model-facing web_search/web_fetch schemas, prompt sections, and
HTML-to-markdown presentation. Search and fetch are deliberately one seam.
Providers ship as namespace plugins that register into ctx.web (like an
LlmAdapter into ctx.llm), not key-owning services, since multiple search
providers cannot each own the key. Tool registration follows product
enablement, not backend availability, so load order/credentials never enter
the model contract; the seam resolves the provider at execution time and
surfaces a structured WebError otherwise.
Moves the RFC to implemented/ amended to match what shipped. Example/app
configs are intentionally not wired yet (RFC migration step 6).
2026-06-25 15:04:12 +08:00
| [Web capability seam — provider registry and model-facing web tools ](implemented/architecture/2026-06-24-web-capability-seam.md ) | 2026-06-24 |
fix(fs): address review — rename to dsh-fs-policy, fs/*-intent events, RFC currency, ENOTDIR
Rename per review naming decisions:
- package dsh-file-context → dsh-fs-policy (dir, package name, plugin name,
tsconfig refs, importers, type-equiv manifest, generated catalog + module-graph)
- events fs/write-expectation → fs/write-intent, fs/edit-expectation → fs/edit-intent
(fs/observed unchanged); type FsWriteExpectation → FsWriteIntent, "expectation"
wording → "intent" throughout
- exported FileContextExec → FsPolicyExec
Make the implemented RFCs describe what shipped, not the superseded designs:
the 2026-06-17 capability-seam + tool-schemas RFCs no longer place policy on
ctx.fs or use full/partial-view authorization, and the fsspec RFC's ctx.fileContext
service prose is rewritten to the fs/* event-gate reality (freshness-based auth).
Sharpen docs/rfc/implemented/AGENTS.md: a rename is a fact to fix IN PLACE — the
"new RFC" escape hatch is for macro decision reversals only, not renames.
Code fixes from review:
- fsio.ts resolveLocalTarget/probe translate ENOTDIR (a parent path segment is a
file) into the structured FsError taxonomy instead of leaking a raw Node error;
resolve reports FS_NOT_FOUND, probe reports absent. Regression tests proven to
fail on the unfixed code.
- tool-fs HMR test now asserts prompt sections (not just tool schemas) are
withdrawn on disposal.
- fs/observed is a plain (unguarded) ctx.emit: correct the fs-policy comment,
filesystem.md, and tool-fs module doc that wrongly claimed the tool "contains"
a throwing listener; a throw surfaces as the tool's isError result.
- drop the false "loaded by the default product config" claim (no config wires
the fs tools yet), the duplicate ctx.bash service-map row, the stale
FileReadRequest catalog link-map entry, and the fs/fs README EOF blank line;
correct the dsh-fs package.json description.
2026-07-02 03:12:38 +08:00
| [Make `dsh-fs-policy` an event-gate plugin, not a method interface ](implemented/architecture/2026-06-26-file-context-as-event-gate.md ) | 2026-06-26 |
2026-06-30 10:32:55 +08:00
| [Event-domain semantics — session is the fact log, agent is the live surface ](implemented/architecture/2026-06-30-event-domain-semantics.md ) | 2026-06-30 |
2026-07-02 04:30:40 +08:00
| [stdin + extra env on the bash seam ](implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md ) | 2026-06-30 |
2026-07-02 18:29:29 +08:00
| [Resolve filesystem paths against the caller's session cwd ](implemented/architecture/2026-07-02-fs-per-session-cwd.md ) | 2026-07-02 |
2026-07-03 02:04:03 +08:00
| [Tagged render-intent union for tool-call presentation ](implemented/architecture/2026-07-02-tool-render-intent-union.md ) | 2026-07-02 |
2026-07-03 17:12:00 +08:00
| [Result-time applied-hunk diffs for file mutations ](implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md ) | 2026-07-02 |
2026-07-03 15:12:40 +08:00
| [Add direct directory listing to the filesystem seam ](implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md ) | 2026-07-03 |
2026-06-20 22:29:45 +08:00
### Process
| Title | First proposed |
|---|---|
| [Vendor Cordis as source, not npm dependencies ](implemented/process/2026-06-11-vendor-cordis-as-source.md ) | 2026-06-11 |
| [Mechanical quality gates over prose guidelines ](implemented/process/2026-06-11-quality-gates.md ) | 2026-06-11 |
| [tsdown for JS bundling instead of dumble ](implemented/process/2026-06-11-tsdown-over-dumble.md ) | 2026-06-11 |
| [Doc-sync enforcement ](implemented/process/2026-06-11-doc-sync-enforcement.md ) | 2026-06-11 |
| [pnpm as the package manager instead of Yarn 4 ](implemented/process/2026-06-16-pnpm-over-yarn.md ) | 2026-06-16 |
2026-06-22 01:01:08 +08:00
| [TSC-first build and one tsconfig ](implemented/process/2026-06-17-ts-build-config.md ) | 2026-06-17 |
2026-06-20 22:29:45 +08:00
| [Markdown cross-link validity linting ](implemented/process/2026-06-18-markdown-cross-link-lint.md ) | 2026-06-18 |
| [Core-data-structures catalog and the `ts type-equiv` drift gate ](implemented/process/2026-06-20-core-data-structures-catalog.md ) | 2026-06-20 |
| [Generated cordis events + services catalog ](implemented/process/2026-06-20-generated-cordis-catalog.md ) | 2026-06-20 |
| [Classify RFCs by kind via path-encoded subdirectories ](implemented/process/2026-06-20-rfc-classification.md ) | 2026-06-20 |
feat(docs): generate a tool-schema catalog by booting the tool plugins
Add docs/tool-catalog/tools.md, a generated reference of every model-facing
tool a shipped `packages/*/tool-*` plugin contributes (name, description,
JSON-Schema parameters) — the third generated catalog alongside the cordis
events/services and core-data-structures catalogs.
Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each
tool plugin on a real cordis Context and reads `ctx.tools.schemas()`, because a
tool schema is not statically knowable: `todo_write` builds its enum with a
runtime spread, descriptions are string-concatenated, `subagent`'s name is
config-driven, and MCP tools register raw JSON Schema without `defineTool`. A
completeness guard globs the on-disk `tool-*` packages and fails if any is
absent from the boot manifest, restoring the "nothing silently omitted"
property booting would otherwise lose. `verify-tool-catalog` runs inside
`doc-sync`, so the artifact cannot drift.
The boot-over-AST decision and the discovered-inventory / hand-written-recipe
split are recorded in a process RFC.
2026-07-02 02:20:24 +08:00
| [Generated tool-schema catalog (boot-and-harvest) ](implemented/process/2026-07-02-tool-schema-catalog.md ) | 2026-07-02 |
docs: bilingual docs contract, translation skill, and pairing gate
Establish EN->ZH bilingual documentation for the README and docs tree:
- docs/i18n/README.md — the pairing contract: sibling foo.md <-> foo.zh.md,
English canonical, blob-hash source fingerprints, language switchers,
scope/exclusions, and a manifest-driven rollout ratchet.
- docs/i18n/translation-rules.md — how to translate: faithfulness, structure
preservation, terminology discipline over docs/i18n/terminology.md, and
typography rules grounded in MDN/K8s/Vue/clreq conventions.
- .agents/skills/dsh-translate-docs — the committed agent workflow, following
the dsh-code-review pattern of deferring to docs as sources of truth.
- scripts/verify-translation-pairing.ts + manifest — a doc-sync gate: required
pairs exist; every existing .zh.md is fresh (fingerprint = current source
blob), switcher-linked, structure-matched, and non-orphaned; excluded
(generated) docs stay unpaired. --list prints the translation work list.
- RFC (implemented/process) recording the decision and the alternatives.
- Dogfood: README.zh.md and the two i18n docs translated under their own rules.
Gates: doc-sync green including the new gate; red/green proven for stale
fingerprint, orphan, and excluded-file violations.
2026-07-02 23:12:25 -07:00
| [Bilingual documentation via paired sibling files and a pairing gate ](implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md ) | 2026-07-02 |
2026-06-20 22:29:45 +08:00
### Testing
2026-06-18 02:18:24 +08:00
| Title | First proposed |
|---|---|
2026-06-20 22:29:45 +08:00
| [Property-based testing for protocol-shaped code ](implemented/testing/2026-06-11-property-based-testing.md ) | 2026-06-11 |
| [ACP snapshot tests — record-once / replay-deterministic ](implemented/testing/2026-06-19-acp-snapshot-tests.md ) | 2026-06-19 |
| [Real-API e2e in CI against the external DeepSeek API ](implemented/testing/2026-06-19-real-api-e2e-ci.md ) | 2026-06-19 |
test(snapshot): use session.jsonl as the only session-log artifact (drop session.golden.jsonl)
Model-driving ACP snapshot scenarios shipped both session.jsonl (the
replay fixture) and session.golden.jsonl (the expected re-persisted log).
For recorded scenarios the normalized fixture and golden were byte-identical
— pure duplication. Remove session.golden.jsonl entirely: every model
scenario now has at most one committed session-log artifact, session.jsonl,
which doubles as the replay source AND the expected produced log.
The snapshot test compares the replay run's persisted log against the
session.jsonl fixture, normalizing BOTH sides — but each against its OWN
volatile values, not a shared context. A raw harvested fixture bakes in the
recording run's session id / cwd / timestamps, distinct from the live replay
run's; since normalizeSessionLog scrubs cwd by exact string match, the
fixture must be normalized against its own header (new fixtureContext helper)
or its stale recorded cwd would leak unscrubbed and the compare would fail.
The session side uses a normalized-string toEqual, NOT toMatchFileSnapshot,
so a run never overwrites the fixture.
Authored override scenarios (error-finish, cancel) now hold their expected
produced log in session.jsonl. Verified llm-replay ignores the fixture for
model chunks when an override exists: loadReplayScript() returns the override
array and never reads config.file, so committing the full expected log there
does not affect replay behavior.
The required-fixture guard is now per-kind: every scenario needs input.json +
stdout.golden.jsonl; model scenarios need session.jsonl; authored ones
additionally need replay.override.json. Updates the ACP-snapshot-tests RFC to
the reduced fixture set and moves the proposing RFC proposed -> implemented.
2026-06-21 10:36:57 +08:00
| [Use `session.jsonl` as the only snapshot session-log artifact ](implemented/testing/2026-06-20-remove-redundant-snapshot-log-goldens.md ) | 2026-06-20 |
Add per-session snapshot replay for nested agents (PR2.5)
The snapshot tier was built single-session: dsh-llm-replay served calls from
one global positional cursor, and the harness harvested one session log. A
subagent runs as a second agent with its own session, so a parent→child
scenario could neither replay deterministically nor harvest the child's log.
This resolves the TODO(subagent-snapshots) deferral from the subagent RFC.
- Stamp the calling session id onto the model request: GenerateOptions.sessionId
(typed Branded<'SessionId'> to avoid the dsh-llm↔dsh-session cycle), set by the
agent loop from agent.session.id. Adapters ignore it; an llm/stream listener
routes by it.
- Key replay per session: dsh-llm-replay loads the parent log plus one per child
(childFiles / $DSH_SNAPSHOT_CHILD_FILES), derives a script per recorded session,
and binds each live (freshly-random) session to a recorded script by first-call
order — parent first (earliest createdAt, first to stream). Keys by WHO calls,
so it survives a future concurrent/backgrounded subagent; a global cursor would
not. An unrecorded extra session fails loud.
- Harvest every log: the harness collects all .jsonl across cwd buckets, ordered
primary-first (top-level, then children by createdAt), and RunResult exposes the
plural sessionLogs. The spec writes each back on record (session.jsonl +
session.<n>.jsonl) and diffs each against its fixture on replay.
- Wire the subagent seam + spawn + fork + tool into the acp-agent example (both
cordis configs) and add two nested scenarios recorded against the real API:
subagent-spawn (parent + 1 child) and subagent-multi (parent + 2 children, 3
sessions). Both replay keyless in the default gate.
A new RFC documents the design (docs/rfc/implemented/testing/). Single-session
replay is unchanged (a call with no sessionId is one anonymous primary session).
TODO follow-up: a dedicated branded-ids package could own the SessionId brand and
dissolve the cross-package cycle note; out of scope for this testing PR.
2026-06-22 08:39:36 +08:00
| [Per-session snapshot replay for nested agents ](implemented/testing/2026-06-22-subagent-snapshot-replay.md ) | 2026-06-22 |
Persist the seed boundary so fork-child replay routes correctly
A fork subagent seeds its child session with a prefix of the parent's log, and
that seed becomes the child's persisted log — so a fork child's .jsonl begins
with the PARENT's events, including the parent's assistant/chunk events. The
snapshot replay harness derived a child's script from its whole log, which would
replay the parent's recorded responses as the child's model calls. Spawn-only
scenarios never hit it, but a fork snapshot would mis-route silently.
Record the seed boundary and skip the inherited prefix at replay:
- SessionHeader gains an optional `seedLength` (how many leading events were
inherited via a seed), threaded through CreateSessionOptions/CreateAgentOptions
meta and stamped by the fork backend (= seeded-prefix length; absent for spawn).
It is EXPLICIT, never inferred from seed.length: a resume seeds the whole stored
log, so the resume path passes the persisted boundary back.
- Both persistence backends round-trip it: JSONL header line, SQLite seed_length
column. The SQLite table change bumps SCHEMA_VERSION 2->3; per the pre-release
stance the backend rejects an older user_version on open with NO migration.
- llm-replay's parseSessionHeader reads seedLength and loadSessionScripts derives
a child script from events AFTER the boundary. seedLength is 0 for spawn, so
spawn replay is byte-for-byte unchanged.
Closes the routing-correctness gap the per-session snapshot replay RFC under-
stated; a recorded fork scenario remains a future addition but now derives
correctly. RFC: docs/rfc/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md.
Regression coverage: a fork child fixture whose seeded prefix carries a parent
chunk (derived script must exclude it, proven red without the slice); a seedLength
persistence round-trip through the shared coordinator contract (both backends);
the fork backend stamping it; resume preserving it from the persisted header.
2026-06-22 20:55:32 +08:00
| [Persist the seed boundary so fork-child replay routes correctly ](implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md ) | 2026-06-22 |
2026-06-22 21:20:54 +08:00
| [Record fork and mixed spawn+fork snapshot scenarios ](implemented/testing/2026-06-22-fork-snapshot-scenarios.md ) | 2026-06-22 |
test(hooks): snapshot the CC + Codex hook matrix end-to-end
Load both hook bridges in the ACP example (dsh-hooks-claude → ./hooks.json,
dsh-hooks-codex → ./codex-hooks.json) so the full-transcript snapshot tier can
exercise each dialect against the real app. An absent config file is a silent
no-op, so a scenario carries only the file it needs and the other bridge
vanishes — verified byte-identical against every pre-existing snapshot.
Add a scenario per hook point × its headline Decision outcome, both dialects:
UserPromptSubmit block (authored, keyless) + context-fold, PreToolUse deny/ask,
PostToolUse block/context, Stop force-continue. The mid-turn scenarios are
recorded against the real API with the hook active, so the model's reaction to
a denied/blocked/force-continued turn is part of the replayed transcript.
SessionStart and SubagentStart are deliberately excluded (detached best-effort
inject races the log position — a recorded golden fails 10/10 on its own
replay), as is SubagentStop (observe-only, zero transcript footprint — a golden
could never be proven to fail). Both stay on the bridges' unit coverage. See
docs/rfc/implemented/testing/2026-07-04-hook-snapshot-matrix.md.
2026-07-04 00:40:35 +08:00
| [Hook snapshot matrix — end-to-end goldens for both bridges ](implemented/testing/2026-07-04-hook-snapshot-matrix.md ) | 2026-07-04 |
2026-06-18 02:18:24 +08:00
## Rejected
2026-06-20 22:29:45 +08:00
### Simplification
| Title | First proposed |
|---|---|
| [Persist assembled assistant messages, not stream chunks ](rejected/simplification/2026-06-20-assembled-assistant-messages-only.md ) | 2026-06-20 |
| [Drop ACP session/load until resume has a product shape ](rejected/simplification/2026-06-20-drop-acp-session-load.md ) | 2026-06-20 |
| [Drop ACP terminal `_meta` rendering ](rejected/simplification/2026-06-20-drop-acp-terminal-meta.md ) | 2026-06-20 |
| [Drop bash full-output spill files ](rejected/simplification/2026-06-20-drop-bash-output-spill-files.md ) | 2026-06-20 |
| [Drop durable step boundary events ](rejected/simplification/2026-06-20-drop-durable-step-boundaries.md ) | 2026-06-20 |
| [Drop unused session lineage metadata ](rejected/simplification/2026-06-20-drop-unused-session-lineage.md ) | 2026-06-20 |
| [Fold the persistence interface into dsh-session ](rejected/simplification/2026-06-20-fold-session-persistence-interface.md ) | 2026-06-20 |
| [Collapse tool-owned UI presentation ](rejected/simplification/2026-06-20-generic-tool-rendering.md ) | 2026-06-20 |
| [Retire mid-turn steering ](rejected/simplification/2026-06-20-retire-mid-turn-steering.md ) | 2026-06-20 |
| [Return the ACP bridge to one live session per connection ](rejected/simplification/2026-06-20-single-session-acp-bridge.md ) | 2026-06-20 |
| [Truncate interrupted final turns on load ](rejected/simplification/2026-06-20-truncate-interrupted-turns.md ) | 2026-06-20 |
### Architecture
2026-06-18 02:18:24 +08:00
| Title | First proposed |
|---|---|
2026-06-20 22:29:45 +08:00
| [Deep-readonly public surfaces ](rejected/architecture/2026-06-11-immutable-public-surfaces.md ) | 2026-06-11 |
2026-06-20 23:37:41 +08:00
| [Make the shared example base providerless ](rejected/architecture/2026-06-20-providerless-example-base.md ) | 2026-06-20 |
