edc065666f
Plan mode's stage 2 (RFC 2026-07-07-plan-mode). The exit tool: one required plan argument (the durable log artifact), execute re-checks the folded mode, then conducts the review over the user-interaction seam — one single-select question (Approve / Keep planning) with free text open — so an approval appends mode/set back to default in-turn and every other outcome (keep-planning feedback verbatim, aborted, no provider) returns the corrective isError with the mode unchanged. presentCall is a generic card titled by the plan's first heading carrying the plan markdown; over ACP the review rides the ask_user elicitation flow, in the terminal the stdio prompt queue — no approval-seam dependency. The ACP bridge maps the picker 1:1 onto ctx.modes (opportunistic, a type-only peer edge): session/new + session/load advertise availableModes/currentModeId, session/set_mode validates through set() and echoes an optimistic current_mode_update (the pending mode IS the selection; the logged mode/set lands at the boundary and, matching, is not re-sent), and a session/event listener re-notifies on each logged flip that differs from the last sent — the tool-driven exit updates the picker. The feature matrix rows move from 'not modeled' to the picker-to-modes / knobs-to-config-options division, with the ACP v2 removal direction recorded as a mechanical-migration risk. The snapshot harness gains the setMode/setModeExpectError ops and a scripted elicitationAnswers FIFO (cancel on exhaustion; a stray choice string reaches the agent verbatim as a non-consenting custom answer, so a scenario bug fails safe). The suite factory's header-pin requirement now applies only to model-turn scenarios — a protocol-only suite has no header content to anchor. examples/plan-acp-agent is the live composition; its keyless modes-advertise scenario pins the wire surface (advertisement, both set_mode round-trips, unknown-id rejection). The recorded plan-mode approve/reject arc awaits a with-key recording session; its texts are pinned at the unit tier meanwhile. examples/AGENTS.md ceiling 653 → 680: the new example's required smoke row does not fit the old budget.
4.7 KiB
AGENTS.md — Examples
Runnable demos showing how the harness is wired. Examples are NOT workspaces — each examples/*/package.json is a private, dependency-free stub, never built. They are booted as unbuilt tsx subprocesses via the cordis Loader reading a cordis.yml; the @deepseek-ai/dsh-* plugin names in those YAML files resolve through the root tsconfig.json paths map, not through node_modules.
Because examples are not under the packages/*/src coverage gate, an example that grows real, reusable logic should extract it into a packages/ package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: the cordis.yml wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios. There is no start.ts — the boot glue (Loader tail, .env load, snapshot-mode selection, stdin-dispose lifecycle) lives in each app package's bin (@deepseek-ai/dsh-stdio-agent, @deepseek-ai/dsh-acp-agent), which the demo:* scripts invoke against the leaf cordis.yml.
Every example ships e2e smokes (keyless + with-key)
Each example must have both kinds of end-to-end smoke, because they catch different failures:
- Keyless smoke — boot the example through its real
cordis.ymlvia the Loader (no API key), drive it, and assert the rendered output and a clean exit. This is the guard a hand-mounted unit test structurally cannot be: it exercises the REAL load path (unwrapExports,inject, the whole plugin tree), so a broken plugin export shape — e.g. a strayexport defaultthat collapses a namespace plugin and dropsinject— fails here even when unit tests stay green (see docs/postmortem/0001). It runs in the default e2e gate (CI has no secrets). - With-key smoke — send a real prompt against the live model and verify the WORLD (a file on disk, a non-empty assistant turn), not the agent's self-report. This proves the actual product works, which a mock/keyless run structurally cannot. Key-gated: it self-skips without
DEEPSEEK_API_KEY(see the testing policy — inference is cheap here, so write many).
Exception — keyless-by-nature examples. An example whose model is itself a mock/deterministic stand-in (no real provider) has no meaningful with-key smoke; the keyless smoke is the complete requirement. State the exception inline in the test.
A keyless smoke that spawns the example from a temp cwd must set TSX_TSCONFIG_PATH to the repo-root tsconfig — the unbuilt paths map is found by searching UP from cwd, so a temp cwd outside the repo would otherwise fall back to stale built lib/. Pass --expose-internals when the example's cordis.yml loads the HMR plugin (mirror the demo:* script).
Current state
| Example | Keyless smoke | With-key smoke |
|---|---|---|
echo-agent |
tests/echo.e2e.ts — boots the real cordis.yml, drives the echo tool round-trip and the direct canned reply |
N/A — keyless by nature (the mock-echo model has no real provider) |
coding-agent |
tests/keyless-smoke.e2e.ts — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit; tests/code-mode-keyless-smoke.e2e.ts — the same boot guard for the Code Mode overlay |
tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts — real model + real bash + real todo_write, world-verified; tests/code-mode.e2e.ts — a real model composes two bash calls in one run_code program; collapsed header, dispatch events, written file all verified |
cordis-agent |
tests/keyless-smoke.e2e.ts — boots the real tree incl. @deepseek-ai/dsh-tool-cordis by package name; the tool logic is unit-tested in packages/cordis/tool-cordis |
tests/cordis-tools.e2e.ts — real model mounts a listener (tagged line fires), builds+calls its own tool, composes two mounts via provide/inject |
acp-agent |
pnpm run test:snapshot — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); tests/acp.e2e.ts also asserts stdout purity without a key |
tests/acp.e2e.ts — real ACP prompt, verifies a file the agent wrote; tests/hooks.e2e.ts — a real PreToolUse hook blocks bash, verifies the file is NOT written |
plan-acp-agent |
pnpm run test:snapshot — the session-mode wire surface as committed protocol bytes |
none yet (the recorded plan-mode scenarios are the pending with-key tier) |
See the root AGENTS.md for repo-wide conventions and docs/architecture.md for the design.