Tianyi Cui
072f97c184
Logic that lived under examples/ was outside the per-file 100% coverage
gate (examples/ are not workspaces) and, in the stdio-UI case, duplicated
across two examples. Move it into packages/ so it is gated and de-duped.
- packages/ui-stdio (new): unify the two diverged stdio-chat.ts copies into
one @deepseek-ai/dsh-ui-stdio plugin (welcome/agent Config). A test-only
I/O seam (createStdioChat(ctx, config, runtime)) keeps process streams out
of the serializable config and makes every render/EOF/disposal branch
unit-testable. Per-file 100%. echo/coding cordis.yml now load the package;
both src/stdio-chat.ts deleted.
- packages/llm-replay (new): move examples/acp-agent/src/llm-replay.ts (+ its
spec) here so its derive/parse/replay branches fall under the coverage gate.
cordis.snapshot.yml + README rewired to the package name; added apply/env
/assertNever/abort tests to reach per-file 100%.
- examples/{echo,coding}-agent: keyless Loader-path e2e smokes that boot the
real cordis.yml (no key) — the guard a hand-mounted unit test cannot be for
the unwrapExports/export-shape class (postmortem 0001). examples/AGENTS.md
codifies the keyless+with-key smoke convention (keyless-by-nature exception
for echo-agent).
- AGENTS.md: a scoped, removal-triggered pre-release stance (foundation over
blast radius). packages/README.md: new rows + a FIXME to later regroup ALL
packages into a hierarchy. Wiring: tsconfig paths/refs, publint, knip,
module-graph.
Verified: typecheck, lint, test:coverage (887 tests, 100%), build, hygiene,
doc-sync, test:snapshot (10), test:e2e (6 keyless pass, with-key self-skip).
echo-agent
Runnable demo: stdin chat with a scripted mock model and an echo tool.
What it shows
- A complete Cordis app loaded from
cordis.yml— the standard "stack of plugins" pattern mock-llm.ts— a mockLlmAdapterthat streams scripted responses and calls theechotool when the user types "echo "echo-tool.ts— a tool registered viactx.tools.register()that echoes text back uppercased@deepseek-ai/dsh-session-persistence-jsonl— the durable JSONL persistence backend (loaded fromcordis.yml,root: ./.sessions): append-only event log per session with crash-safe atomic writes, replacing the old write-only example pluginstdio-chat.ts— a minimal UI plugin: reads stdin lines andsend/steers the agent, renders stream deltas, tool calls, and tool results
Plugin files
| File | Role | Key patterns demonstrated |
|---|---|---|
mock-llm.ts |
LlmAdapter registration |
ctx.llm.registerAdapter(['mock-echo'], …), streaming chunks with proper block-start/block-end protocol |
echo-tool.ts |
Tool registration | ctx.tools.register(defineTool(…)) with typed execute args, tool execution returning ContentBlock[] |
stdio-chat.ts |
UI | agent/stream-chunk, session/event (tool/*), stdin→send/steer |
start.ts |
Bootstrap | Context + Loader + plugin-include wired to cordis.yml |
Persistence is the shared @deepseek-ai/dsh-session-persistence-jsonl plugin (not a per-example file).
Run
pnpm run demo:echo
# or:
node --expose-internals --import tsx examples/echo-agent/start.ts
Type a message and press Enter. "echo " triggers a tool call round-trip (the mock model requests the echo tool, which echoes the text uppercased, and the next model step acknowledges it).
The session is persisted under .sessions/ relative to the directory you launch the demo from. pnpm run demo:echo runs from the repo root, so the logs land in <repo-root>/.sessions/ (a session with no cwd goes in the _no-cwd/ bucket, one .jsonl log per session). Clean up with: rm -rf .sessions