e2bde2902c
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.
3.7 KiB
AGENTS.md — Examples
Runnable demos that show how the harness is wired. Examples are NOT workspaces — each examples/*/package.json is a private, dependency-free stub with no build. 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 with-key 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/{full-loop,coding-task,resume}.e2e.ts — real model + real bash, world-verified |
acp-agent |
pnpm run test:snapshot — boots the real ACP subprocess and replays a recorded session keyless; tests/acp.e2e.ts also asserts stdout purity without a key |
tests/acp.e2e.ts — real ACP prompt, verifies a file the agent wrote |
See the root AGENTS.md for repo-wide conventions and docs/architecture.md for the design.