diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md index e84d7fefd3..ffb3afa51a 100644 --- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md +++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md @@ -13,7 +13,7 @@ The [event-sourced model](2026-06-11-event-sourced-sessions.md) makes the append Persistence is an abstract **capability seam** ([capability seams](2026-06-13-capability-seams.md), the `dsh-bash` template), not loop or core logic: 1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `create`/`append`/`load`/`list`. Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type. -2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only JSONL log per session (a `SessionHeader` line then one `SessionEvent` per line, verbatim **including `assistant/chunk`**). +2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only logical JSONL log per session (a `SessionHeader` line then one `SessionEvent` per line, verbatim **including `assistant/chunk`**), encoded as [checksummed Zstandard frames by default](2026-07-19-zstandard-jsonl-session-logs.md) or raw lines by configuration. Key choices recorded here because they are durable, contested, and surprising: diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md index 7c73cf24a4..27360087a2 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md +++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md @@ -28,7 +28,7 @@ Six methods (five required + an optional lifecycle hook) — the only seam betwe ### The opaque torn marker -The single design choice that keeps the seam clean: the crash-repair "where is the torn tail" token is OPAQUE to the coordinator. The coordinator computes the synthetic closers (it owns `interruptedTurnClosers` from `dsh-session`), but it only ever tests `tornMarker !== undefined` and passes the value straight back to `commitRepair` — it never inspects it. Each backend picks its own marker type: JSONL uses the byte offset to truncate to, SQLite the seq to delete from (both happen to be `number`). The JSONL backend folds its `committedBytes < buffer.byteLength` comparison INSIDE the hook so the returned marker is already `number | undefined`; without that fold the coordinator would have to know about byte lengths. +The single design choice that keeps the seam clean: the crash-repair "where is the torn tail" token is OPAQUE to the coordinator. The coordinator computes the synthetic closers (it owns `interruptedTurnClosers` from `dsh-session`), but it only ever tests `tornMarker !== undefined` and passes the value straight back to `commitRepair` — it never inspects it. Each backend picks its own marker type: JSONL carries the byte offset to truncate to plus any complete events decoded from an incomplete final frame, while SQLite carries the seq to delete from. The coordinator therefore knows neither byte lengths nor frame recovery state. ## Testing diff --git a/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md index 3fa7227d04..05d72e4e49 100644 --- a/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md +++ b/.agents/notes/implemented/architecture/2026-06-20-extract-example-app-packages.md @@ -6,29 +6,28 @@ Status: implemented An example folder is supposed to be *thin* — the variable wiring of a demo, not the demo's machinery. Before this change it was thick. Each example carried a hand-rolled `start.ts` boot bootstrap, an infra preamble (`timer`, and — for the stdio demos — `logger` + `hmr`), nested includes of three shared YAML fragments (`base.yml` / `base-core.yml` / `acp-agent/acp-tail.yml`), and per-example `agent-loop`/persistence/system-prompt config. The actual app — the spine of services every agent needs — was spread across the leaf and those includes. -The leaf configs also owned a coupled front door. ACP requires stdout purity and creates agents through `session/new`; stdio requires a console logger and a pre-created `main`. Prose warnings were the only guard against combining these incorrectly, while three `start.ts` files duplicated the Loader bootstrap and lifecycle code. +The leaf configs also owned coupled front doors. ACP requires stdout purity and creates agents through `session/new`; terminal and Headless apps pre-create `main` but have different process I/O contracts. Prose warnings were the only guard against combining these incorrectly, while three `start.ts` files duplicated the Loader bootstrap and lifecycle code. ## Decision Each example is now **mostly an invocation of an app package**, splitting the wiring along the existing [interface / implementation / consumer seam](2026-06-13-capability-seams.md): the **app package owns the composition**, the leaf `cordis.yml` owns only the **swappable choices** (which LLM adapter, which bash executor, model, prompt, persistence root). - **`@deepseek-ai/dsh-agent-spine-demo`** ([packages/examples/agent-spine-demo](../../../../packages/examples/agent-spine-demo)) composes the providerless, executor-less, UI-less spine and forwards the loop's agent-list config. Its dependency on the concrete loop is intentional because this package composes the spine rather than extending it; swapping the loop means supplying another bundle. -- **`@deepseek-ai/dsh-stdio-demo`** ([packages/examples/stdio-demo](../../../../packages/examples/stdio-demo)) and **`@deepseek-ai/dsh-acp-demo`** ([packages/examples/acp-demo](../../../../packages/examples/acp-demo)) bake in their front doors. Stdio includes `ui-stdio`, a console logger, and `main`; ACP includes the bridge and JSONL persistence but no stdout logger or pre-created agent. Leaves may add plugins, but the safe composition is now the default artifact. -- **`start.ts` is gone.** Each app package exposes a `bin` (`dsh-stdio-demo` / `dsh-acp-demo`); the `demo:*` scripts invoke it (e.g. `dsh-stdio-demo ./cordis.yml`). The Loader-boot tail, `.env` loading, and fail-loud guards live in the shared [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) package (unit-tested under the per-file coverage gate — see [share the app bins' boot glue](../simplification/2026-07-04-share-app-bin-boot-glue.md)); each bin is a thin self-executing composition over those helpers plus its app-specific lifecycle (the ACP bin: snapshot-mode selection and stdin-dispose). The `bin.ts` files themselves stay coverage-excluded (self-executing CLI entries, like the old `start.ts`) and are driven by the keyless Loader-path tests. -- **Each leaf `cordis.yml` collapses** to backends + config: the LLM adapter (`llm-deepseek` with apiKey/models, or `llm-replay`), the bash executor (`bash-local`), `hmr` for the stdio demos (see the amendment below), and one app entry carrying the app's config (model, system prompt, persistence root — surfaced as the app package's own `Config`, which routes each value to wherever the app wires it: stdio onto its pre-created agent, acp onto the bridge plugin). -- **echo-agent folds onto `dsh-stdio-demo`**, swapping the LLM backend to the local `mock-llm` and adding the local `echo-tool` (plus `bash-local`, which the spine's `tool-bash` injects) at the leaf — the clean demonstration of "swap the backend, keep the app". `mock-llm.ts` / `echo-tool.ts` stay as example-local teaching plugins. +- **`@deepseek-ai/dsh-tui-demo`**, **`@deepseek-ai/dsh-cli-demo`**, and **`@deepseek-ai/dsh-acp-demo`** bake in their process roles. TUI includes the full-screen UI and a pre-created `main`; Headless includes the one-shot driver and a pre-created `main`; ACP includes the bridge and no pre-created agent. All three include JSONL persistence and omit stdout loggers. +- **`start.ts` is gone.** Each app package exposes a bin; the `demo:*` scripts invoke it. Loader boot, `.env` loading, and fail-loud guards live in the shared [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) package (unit-tested under the per-file coverage gate — see [share the app bins' boot glue](../simplification/2026-07-04-share-app-bin-boot-glue.md)); the thin self-executing entries are driven by keyless Loader-path tests. +- **Each leaf `cordis.yml` collapses** to backends, optional product tools, and one app entry carrying the app config. TUI and Headless route model/session choices onto a pre-created agent; ACP routes the initial provider/model onto its bridge. - **`base.yml`, `base-core.yml`, and `acp-agent/acp-tail.yml` are retired** — the spine they shared now lives in `dsh-agent-spine-demo`. `bash-local` and the LLM adapter stay **leaf choices**: the bundle ships `tool-bash` (the consumer schema), the leaf picks the executor implementation, so a sandboxed executor or replay adapter swaps in without touching the app. ### Amendment on implementation: `hmr` stays a leaf entry -The proposal listed `hmr` among the stdio app's baked-in front-door cluster. Validating against the code, baking `hmr` into the `dsh-stdio-demo` package fights cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead: +The proposal listed `hmr` among the interactive app's baked-in front-door cluster. Validating against the code, baking `hmr` into the app package fights Cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead: 1. `@cordisjs/plugin-hmr` is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader` service, so it can only run in the real `demo:*`/bin subprocess, never in the in-process unit/coverage tier. 2. The in-process test tier (vitest) cannot even *import* the vendored `hmr` module (its class-decorator `@Inject` form fails under Vite's transform), so a package whose `apply` statically imported it could never satisfy the per-file 100% coverage gate on its headline function. -Crucially, `hmr` is **not** a stdout-purity footgun the way the console logger is — a stray `hmr` in the ACP config would not corrupt the JSON-RPC frames — so leaving it at the leaf costs none of the safety the coupling argument is about. The **logger** (the real coupling) stays baked in: the stdio app includes it, the ACP app omits it. +Crucially, `hmr` is not a stdout-purity footgun: a stray entry in the ACP config does not corrupt JSON-RPC frames. Every shipped app omits a stdout console logger; the app or protocol driver alone owns stdout. ## Alternatives considered @@ -39,13 +38,13 @@ The old `base*.yml`/`acp-tail.yml` includes already deduped the *config*, but a ## Verification - Example directories contain only their config, README, and tests: `start.ts`, the infrastructure preamble, and the shared YAML includes are gone. -- `demo:echo`, `demo:repl`, and `demo:acp` invoke the app-package bins. +- `demo:tui`, `demo:headless`, and `demo:acp` invoke the app-package bins. - Each new package has a README and per-file 100% coverage; each app package also has a keyless real-Loader-path bin smoke that catches export-shape failures described in [postmortem 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md). - The ACP replay transcript remains unchanged because the plugin set and load order did not change. ## Consequences -- **The bare-plugin-tree pedagogy.** echo-agent's inlined `cordis.yml` showed every plugin at once; the spine now lives behind a bundle, so seeing the whole tree means opening `dsh-agent-spine-demo`. The app package's README carries that teaching weight. +- **The bare-plugin-tree pedagogy.** The spine lives behind a bundle, so seeing the whole tree means opening `dsh-agent-spine-demo`. The app package's README carries that teaching weight. - **A layer of indirection.** "What does this demo load?" becomes a package read, not a single YAML scan. ## Related @@ -53,3 +52,4 @@ The old `base*.yml`/`acp-tail.yml` includes already deduped the *config*, but a - Supersedes [Make the shared example base providerless](../../rejected/architecture/2026-06-20-providerless-example-base.md): renaming `base.yml` to the providerless core is moot once the spine moves into `dsh-agent-spine-demo` and the `base*.yml` files are deleted. - Builds on the [capability-seams](2026-06-13-capability-seams.md) interface/implementation/consumer split — backends and presentation stay leaf choices; the spine is the shared bundle. - Complements [Reorganize packages into a modular hierarchy](2026-06-20-package-hierarchy.md): the new app/core packages slot into existing groups under that hierarchy (`core` for the reusable spine bundle, `ui` for the app-specific front doors). +- The later [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) owns the final TUI/Headless split and removes the line-oriented and mock-only leaves. diff --git a/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md index d853696226..85c62b7e17 100644 --- a/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md +++ b/.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md @@ -2,6 +2,8 @@ Status: implemented +The later [fold-stdio-helper](../simplification/2026-07-04-fold-stdio-ui-helper.md) decision superseded the original `support/ui-stdio` placement, and the [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) subsequently removed that surface entirely. The uniform depth-two hierarchy remains the decision owned here. + ## Problem `packages/` was flat: 18 packages all sat at `packages//`, so a package's location said nothing about whether it was core product API, a swappable capability seam, a provider adapter, a product integration, or example/test support. The package README carried a `FIXME(package-hierarchy)` and `scripts/publint-all.ts` a `TODO(package-inventory)` flagging exactly this. Core packages, provider integrations, capability seams, example UI support, and snapshot-only replay support all looked equally foundational. diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md index 631e5b570c..cdd37091a2 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md +++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md @@ -8,7 +8,7 @@ The assembled system prompt had four defects, all of one family: facts the harne **The model could not know its own name.** `AgentOptions.model` drives every request, but no prompt text carried it — and nothing COULD carry it: sections in `dsh-system-prompt` were context-global while the model name is per-agent, and `assemble()` took no per-agent input at all. -**Tool guidance was hand-written prose in leaf YAML.** The bash/subagent/todo_write usage guidance lived in the `systemPrompt` strings of `examples/repl-agent/cordis.yml` and `examples/acp-agent/cordis.yml` — two drifting copies (the ACP one was already abridged) — while `dsh-tool-fs` and `dsh-tool-web` owned their guidance as `ctx.systemPrompt.section()` contributions. Loading or dropping a tool plugin meant editing every deployment's persona by hand; both YAMLs carried a `FIXME(config-comments)` apologizing for a symptom of the split, and the stdio welcome banner hand-enumerated the tool set too. +**Tool guidance was hand-written prose in leaf YAML.** The bash/subagent/todo_write usage guidance lived in the coding-agent and ACP persona strings — two drifting copies (the ACP one was already abridged) — while `dsh-tool-fs` and `dsh-tool-web` owned their guidance as `ctx.systemPrompt.section()` contributions. Loading or dropping a tool plugin meant editing every deployment's persona by hand; both YAMLs carried a `FIXME(config-comments)` apologizing for a symptom of the split, and the old terminal welcome banner hand-enumerated the tool set too. **The persona rendered after tool guidance.** The loop string-joined `agent.options.systemPrompt` AFTER the assembled sections, so the model read "Use the read tool…" before "You are a coding agent" — backwards relative to the identity-first convention (Claude Code, Codex) and a second composition path besides the section pipeline. @@ -56,7 +56,7 @@ Per-tool semantics and selection guidance live in tool descriptions. Prompt sect ## Shipped invariants -- The repl-agent prompt renders identity, persona with the interpolated model, then fs/bash/web guidance through one assembly path. +- The tui-agent prompt renders identity, persona with the interpolated model, then fs/bash/web guidance through one assembly path. - Fork and fresh subagent descriptions reflect whether the provider inherits completed conversation turns; the tool appears, disappears, and is reworded with provider lifecycle changes. - Unknown, valueless, malformed, or unbalanced variable references name the section and throw; duplicate section, variable, and tool registrations also throw. - Snapshot replay is prompt-independent: it keys recorded chunk streams by turn and step without comparing the outgoing request. diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md index 1255dc7328..a9197de179 100644 --- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md +++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md @@ -162,7 +162,7 @@ Those cases can consume `ctx.spillStore` directly in later work. They are not pa - `dsh-spill-local` unit tests cover `saveText`, `encodeSegment` sanitization (separators/tilde/whole-segment dots/empty), the session-hash directory, owner-only permissions, distinct paths per save, the configured/private root, and a storage-failure rejection. - `dsh-spill-policy` unit tests drive real tools through `ctx.tools.execute`: disabled-mode no-op, oversized-text replacement, small/non-text passthrough, `read` skip, best-effort fallback (save failure / no backend / no owner), and downstream-composition (bounding a replaced result, preserving `additionalContexts`). - `dsh-tool-web` integration drives `web_fetch` through `ctx.tools.execute` with the real `spill-local` backend + policy, proving the model-facing text changes only by the deliberate spill notice while the spill file holds the full formatted result. -- The `repl-agent` example loads `spill-local` + `spill-policy`, so its keyless Loader smoke exercises the real load path (the namespace-plugin export shape + `inject`). +- The `tui-agent` example loads `spill-local` + `spill-policy`, so its keyless Loader/PTY smoke exercises the real load path (the namespace-plugin export shape + `inject`). ## Consequences diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml new file mode 100644 index 0000000000..c19fec81ae --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-19-zstandard-jsonl-session-logs.md: 09d30594fe31eed138a128dabc1947b15857808d +2026-07-19-zstandard-jsonl-session-logs.zh.md: 131531d9dba7cb01407191bf937f8b0ee3c6860a diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md new file mode 100644 index 0000000000..09d30594fe --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md @@ -0,0 +1,57 @@ +# Agent Note: Zstandard JSONL session logs + +Status: implemented + +English | [中文](2026-07-19-zstandard-jsonl-session-logs.zh.md) + +## Problem + +The JSONL persistence backend keeps every `SessionEvent` verbatim, including high-volume `assistant/chunk` records. Raw text makes logs inspectable but spends storage and I/O on repeated JSON keys and model text. Compression must retain the existing append/fsync commit boundary, collision-safe first materialization, crash repair, and metadata-only listing; rewriting a whole compressed file after every turn would discard those properties. + +The encoding also has to remain explicit at the deployment boundary. Snapshot fixtures and external line readers require raw JSONL, while a backend cannot safely guess between compressed and raw artifacts in one root or silently migrate pre-release session data. + +## Decision + +### Configuration and suffix ownership + +`dsh-session-persistence-jsonl` accepts `compression?: 'zstd' | 'none'` and explicitly resolves omission to `'zstd'`. Zstandard artifacts end in `.jsonl.zstd`; `'none'` retains the original newline-delimited UTF-8 `.jsonl` representation. `SessionLocation.kind` remains `'jsonl'`, because both encodings carry the same logical record format, and `SESSION_FORMAT_VERSION` remains `0` under the repository's pre-release reject-without-migration policy. + +Each persistence root belongs to one encoding. A one-time discovery preflight rejects any opposite suffix, and targeted load, live-adoption, listing, and materialization paths repeat the relevant suffix check after an initially empty preflight. The error names the incompatible artifact and directs the deployment to the matching configuration or a separate root. There is no migration, dual read, dual write, or extension-based fallback. + +### Frame and write path + +The compressed artifact is a standard concatenation of independent [Zstandard frames](https://datatracker.ietf.org/doc/html/rfc8878): one checksummed frame containing exactly the header line, followed by one checksummed frame for every durable append batch. Normal loop batches are turn commits, so frame boundaries preserve the existing persistence checkpoint without making the storage layer depend on turn event types. + +Compression uses Node's built-in [`zstdCompress` and `zstdDecompress`](https://nodejs.org/download/release/v22.19.0/docs/api/zlib.html), available at the repository's Node 22.19 floor. The backend enables `ZSTD_c_checksumFlag`, otherwise accepts Node's defaults, and exposes neither a compression-level knob nor a new dependency. The API is marked experimental by Node, so the Node 22.19, 24, and 26 compatibility gate exercises the exact helper. + +First materialization compresses the two initial frames before opening the temporary file, then keeps the existing write, file `fsync`, collision-safe hard-link publication, and directory `fsync` sequence. Later batches are compressed before opening the destination and appended at EOF. A caught write or file-sync failure truncates to the prior byte length, syncs the rollback, and rethrows so the coordinator can retry the unchanged batch. + +### Read, listing, and crash recovery + +A frame-boundary scanner reads the standard magic, variable header fields, block headers and payload sizes, and optional checksum trailer. It does not interpret compressed blocks. Complete frames are decompressed independently and sequentially, which validates their checksums, and their plaintext is passed to the existing JSONL scanner. A checksum/decompression failure in any complete frame, a malformed complete-frame JSONL tail, or invalid frame structure is corruption and rejects. + +Listing reads in bounded chunks only until the first complete frame is available, validates and decompresses that header frame, and never reads an event frame. The dedicated header frame therefore preserves metadata-only listing even for very large session logs. + +EOF inside the final frame is a recoverable torn tail. Node's decoder is given the available frame prefix; every complete newline-terminated event it emits is retained. Repair truncates from that frame's starting byte and appends one new checksummed frame containing the recovered complete events followed by the coordinator's synthetic tool, step, and turn closers. If the tear occurs before any complete event is decodable, repair drops the partial frame and retains all prior complete frames. + +### Consumers and verification + +The CLI, ACP, and stdio app bundles expose symmetric `persistenceCompression` pass-through configuration. Snapshot recording and replay compositions select `'none'` explicitly because committed fixtures are raw JSONL inputs to replay and normalization; ordinary runtime compositions use the compressed default. + +The shared persistence and coordinator contracts run against both encodings. Backend tests cover standard framing and checksum interoperability, header-only listing, append rollback, encoding mismatch rejection, complete-frame corruption, and final-frame tears through headers, blocks, and checksum trailers. Default runtime, built-bin, headless, ACP, and Python smokes assert the compressed suffix and Zstandard magic or decode the header; raw-content tests opt out explicitly. + +## Alternatives considered + +- **One frame per JSONL record** — rejected because it multiplies frame headers and checksums for high-volume chunk events and makes a physical boundary unrelated to the durable append batch. +- **Rewrite one whole compressed stream after every append** — rejected because cost grows with log size and replacement would give up append/fsync rollback and the established collision-safe materialization mechanics. +- **Use a streaming compressor across appends** — rejected because an interrupted encoder state does not leave independently checksummed append units, complicating bounded listing and frame-start repair. +- **Add an external native Zstandard dependency** — rejected because the supported Node floor already provides the required codec; another native artifact would enlarge installation and executable-packaging risk without adding a required behavior. +- **Expose compression level or keep raw JSONL as the default** — rejected because there is no deployment evidence for a second tuning policy, while `'none'` preserves the line-readable path for fixtures and integrations that need it. + +## Consequences + +- Ordinary session roots store `.jsonl.zstd` and retain append-only, fsync, rollback, and interrupted-turn recovery semantics. +- Raw JSONL remains a deliberate configuration, but changing encoding requires a fresh/separate root or selecting the mode that matches existing artifacts. +- One frame per durable batch adds bounded framing/checksum overhead and allows header-only listing plus repair from an exact append boundary. +- External tools must understand concatenated Zstandard frames or consume raw-mode artifacts; generic one-shot Node decompression reads only the first independent frame, so backend reads walk frames explicitly. +- The implementation depends on Node's experimental built-in Zstandard API without an npm dependency; the supported-version compatibility gate makes drift visible. diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md new file mode 100644 index 0000000000..131531d9db --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md @@ -0,0 +1,57 @@ +# Agent Note: Zstandard JSONL 会话日志 + +Status: implemented + +[English](2026-07-19-zstandard-jsonl-session-logs.md) | 中文 + +## 问题 + +JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量庞大的 `assistant/chunk` 记录。原始文本便于检查，但重复的 JSON 键和模型文本会增加存储与 I/O 开销。压缩编码必须保留既有的 append/fsync 提交边界、首次物化时的无冲突发布、崩溃修复以及仅元数据列举；如果每轮都重写整个压缩文件，就会失去这些属性。 + +编码还必须在部署边界上保持显式。快照 fixture 与外部逐行读取器需要原始 JSONL，而后端无法在同一根目录中安全猜测压缩产物与原始产物，也不能静默迁移预发布会话数据。 + +## 决策 + +### 配置与后缀归属 + +`dsh-session-persistence-jsonl` 接受 `compression?: 'zstd' | 'none'`，并将省略值显式解析为 `'zstd'`。Zstandard 产物使用 `.jsonl.zstd` 后缀；`'none'` 保留原有的换行分隔 UTF-8 `.jsonl` 表示。`SessionLocation.kind` 仍为 `'jsonl'`，因为两种编码承载同一逻辑记录格式；按照仓库的预发布拒绝且不迁移策略，`SESSION_FORMAT_VERSION` 仍为 `0`。 + +每个持久化根目录只归属于一种编码。一次性的发现预检会拒绝任何相反后缀，而针对性的加载、活跃采用、列举与物化路径会在最初空目录预检之后再次执行对应后缀检查。错误会指出不兼容产物，并要求部署选择匹配配置或单独根目录。系统不提供迁移、双重读取、双重写入或基于扩展名的兜底。 + +### 帧与写入路径 + +压缩产物是标准独立 [Zstandard 帧](https://datatracker.ietf.org/doc/html/rfc8878)的串联：第一个带校验和的帧只包含头部行，后续每个持久追加批次各占一个带校验和的帧。正常 agent loop 批次就是轮次提交，因此帧边界保留既有持久化检查点，同时不让存储层依赖轮次事件类型。 + +压缩使用 Node 内置的 [`zstdCompress` 与 `zstdDecompress`](https://nodejs.org/download/release/v22.19.0/docs/api/zlib.html)，仓库最低支持的 Node 22.19 已提供这些 API。后端启用 `ZSTD_c_checksumFlag`，其余采用 Node 默认值，不公开压缩级别调节项，也不增加依赖。Node 将该 API 标记为实验性，因此 Node 22.19、24 与 26 兼容性门禁会执行同一个辅助实现。 + +首次物化会在打开临时文件之前压缩两个初始帧，然后保留既有的写入、文件 `fsync`、避免冲突的硬链接发布与目录 `fsync` 顺序。后续批次也会先压缩，再打开目标并在 EOF 追加。捕获到写入或文件同步失败时，后端会截断到原有字节长度，同步回滚结果，再重新抛出错误，让协调器重试未变化的批次。 + +### 读取、列举与崩溃恢复 + +帧边界扫描器会读取标准魔数、可变头字段、块头与负载长度，以及可选校验和尾部，但不会解释压缩块。后端独立且按顺序解压完整帧，由此验证各帧校验和，再把明文交给既有 JSONL 扫描器。任何完整帧的校验和或解压失败、完整帧中畸形的 JSONL 尾部，或者无效帧结构都属于损坏并拒绝加载。 + +列举只按有界分片读取到第一个完整帧可用为止，验证并解压该头部帧，绝不读取事件帧。因此，即使会话日志很大，专用头部帧仍能维持仅元数据列举。 + +最终帧内部遇到 EOF 属于可恢复的撕裂尾部。后端把已有帧前缀交给 Node 解码器，并保留其产出的每个完整、以换行结束的事件。修复从该帧起始字节截断，再追加一个新的带校验和帧，其中依次包含恢复出的完整事件，以及协调器生成的工具、步骤与轮次闭合事件。如果撕裂位置尚不足以解码任何完整事件，修复会丢弃该不完整帧并保留此前全部完整帧。 + +### 消费方与验证 + +CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入；普通运行时组合使用压缩默认值。 + +共享持久化契约与协调器契约会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。 + +## 考虑过的替代方案 + +- **每条 JSONL 记录一个帧**——不予采纳，因为它会让大量分片事件各自承担帧头与校验和开销，并让物理边界脱离持久追加批次。 +- **每次追加都重写一个完整压缩流**——不予采纳，因为成本会随日志大小增长，而且替换操作会放弃追加/fsync 回滚和既有的无冲突物化机制。 +- **跨追加使用流式压缩器**——不予采纳，因为编码器状态中断后不会留下可独立校验的追加单元，从而使有界列举与按帧起点修复更复杂。 +- **增加外部原生 Zstandard 依赖**——不予采纳，因为受支持的 Node 最低版本已经提供所需编解码器；另一个原生产物会增加安装与可执行文件打包风险，却不增加必需行为。 +- **公开压缩级别或继续默认使用原始 JSONL**——不予采纳，因为没有部署证据支持第二种调节策略，而 `'none'` 已为需要逐行读取的 fixture 与集成保留路径。 + +## 后果 + +- 普通会话根目录存储 `.jsonl.zstd`，并保留仅追加、fsync、回滚与中断轮次恢复语义。 +- 原始 JSONL 仍是显式配置，但切换编码需要使用全新或单独根目录，或者选择与既有产物匹配的模式。 +- 每个持久批次一个帧会增加有界的帧与校验和开销，同时支持仅头部列举和从精确追加边界开始修复。 +- 外部工具必须理解串联的 Zstandard 帧，或者消费原始模式产物；Node 通用的一次性解压只读取第一个独立帧，因此后端读取会显式遍历各帧。 +- 实现依赖 Node 的实验性内置 Zstandard API，但不增加 NPM 依赖；受支持版本兼容性门禁会暴露 API 漂移。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml new file mode 100644 index 0000000000..630a1b05e6 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-20-error-cause-chain-diagnostics.md: 2d860d0e966158dd9ec12b45f88e3b031e1cb35a +2026-07-20-error-cause-chain-diagnostics.zh.md: 6eac19dd08d50e4662d53889577b5e3ddabaafdd diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md new file mode 100644 index 0000000000..2d860d0e96 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md @@ -0,0 +1,37 @@ +# Agent Note: Render error cause chains at every diagnostic seam + +Status: implemented + +English | [中文](2026-07-20-error-cause-chain-diagnostics.zh.md) + +## Problem + +A TUI run against an unreachable DeepSeek endpoint failed with the single notice `fetch failed` and no further detail. Two independent gaps produced that dead end: + +1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic seam in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line. +2. The readline front door (`dsh-stdio`) rendered no failure reason at all: a `turn/end` with `reason.kind === 'error'` printed nothing but the next `> ` prompt, so the same failure in `demo:repl` was pure silence. + +## Decision + +- `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-surface renderer only; routing stays on `HarnessError.code`. +- The DeepSeek adapter wraps a pre-response transport failure in `LlmError('NETWORK')` naming the configured `baseURL` and chaining the original `TypeError` as `cause`. An aborted request keeps its `DOMException` so the loop still classifies it as cancellation, not a provider failure. +- Every diagnostic seam renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer. +- `dsh-stdio` renders failure `turn/end` reasons: `[turn failed ] `, `[turn aborted] `, `[turn rejected] `, `[turn interrupted by a previous process exit]`, and the output-token-limit notice. Unknown merge-extended kinds fall through as ordinary turn ends. + +`errorChain` lives in `dsh-llm` beside `HarnessError` for the same reason the base class does: it is the leaf package every consumer already imports, so sharing costs no new dependency edge. + +## Alternatives considered + +**Chain rendering inside each error's constructor (bake the cause into `message`).** Rejected: it double-renders once consumers also walk `cause` (the first draft of the adapter fix produced `… fetch failed: bad port: fetch failed: bad port`), and it destroys the structured chain for consumers that want to route on the inner error. + +**A `cause`-aware logger exporter only.** Rejected: the durable `turn/end` reason and the TUI notice are not logger lines; the masked message would persist in the session log — the single durable record of an in-turn failure — and in the primary UI surface. + +**Per-package `renderThrown` upgrades.** Rejected: three packages already carried near-identical private copies; upgrading each separately entrenches the duplication the shared renderer removes. + +## Consequences + +- A transport failure now reads `DeepSeek API request to failed: fetch failed: connect ECONNREFUSED …` in the TUI notice, the readline transcript, and the persisted session log, at the cost of longer diagnostic strings. +- Durable `turn/end` error messages include cause detail. Existing snapshot fixtures replay byte-identically because their scripted errors carry no `cause` (for such errors `errorChain(err)` equals `err.message`); only unit-test expectation strings changed. A fixture recorded from a real transport failure would carry the chain. +- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: `), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these seams. +- `dsh-stdio` output for failed turns is no longer silent; piped consumers that parsed the transcript see new `[turn …]` lines. +- Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, `dsh-workflow-workerthread`, and `cli-demo` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient. diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md new file mode 100644 index 0000000000..6eac19dd08 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md @@ -0,0 +1,37 @@ +# Agent Note: 在每个诊断接缝处渲染错误 cause 链 + +Status: implemented + +[English](2026-07-20-error-cause-chain-diagnostics.md) | 中文 + +## Problem + +TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed` 通知，没有任何进一步细节。两个独立缺口共同造成了这个死胡同： + +1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断接缝都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。 +2. readline 前门（`dsh-stdio`）完全不渲染失败原因：`reason.kind === 'error'` 的 `turn/end` 只打印下一个 `> ` 提示符，同样的失败在 `demo:repl` 里就是纯粹的沉默。 + +## Decision + +- `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是诊断表面的渲染器；路由仍然基于 `HarnessError.code`。 +- DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('NETWORK')`，写明配置的 `baseURL` 并把原始 `TypeError` 链为 `cause`。被中止的请求保留其 `DOMException`，使循环仍将其归类为取消而非 provider 失败。 +- 每个诊断接缝改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。 +- `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed ] `、`[turn aborted] `、`[turn rejected] `、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。未知的 merge 扩展 kind 按普通 turn 结束处理。 + +`errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费者都已导入的叶子包，共享不增加新的依赖边。 + +## Alternatives considered + +**在每个错误的构造函数里渲染链（把 cause 烤进 `message`）。** 否决：当消费者同时遍历 `cause` 时会双重渲染（适配器修复的第一版产出了 `… fetch failed: bad port: fetch failed: bad port`），并且破坏了想按内层错误路由的消费者所需的结构化链。 + +**只做一个感知 `cause` 的日志导出器。** 否决：持久化的 `turn/end` reason 和 TUI 通知不是日志行；被掩盖的消息会留在会话日志——回合内失败的唯一持久记录——以及主要 UI 表面里。 + +**逐包升级 `renderThrown`。** 否决：三个包已经各自持有几乎相同的私有副本；分别升级只会固化共享渲染器所要消除的重复。 + +## Consequences + +- 传输失败现在在 TUI 通知、readline transcript 和持久化会话日志里显示为 `DeepSeek API request to failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。 +- 持久化的 `turn/end` 错误消息包含 cause 细节。现有 snapshot fixture 字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。 +- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: `），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些接缝上，链细节被判断为比类名更有价值。 +- `dsh-stdio` 对失败回合的输出不再沉默；解析 transcript 的管道消费者会看到新的 `[turn …]` 行。 +- `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread`、`cli-demo` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。 diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md index 30a0c83a31..99313866ed 100644 --- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md +++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md @@ -116,7 +116,7 @@ Two failure paths, both documented: - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry. - **`dsh-compact`** owns `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)`, the cached surface-edge checks that `compactRegion` and `compactIfNeeded` use to avoid splitting a tool-call/result pair. The cache validates current membership by seq and answers both edges from one per-cut balance sequence; stale or missing seqs and orphan results reject. - **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. `dsh-invariants` treats fresh appended tool results as executions that require an open step and pending call; validated replacements remain turn-enclosed rewrites. -- **Wiring**: `examples/repl-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, then `dsh-compact-basic`; service-wide defaults make the composition usable without repeated numeric policy. +- **Wiring**: `examples/tui-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, then `dsh-compact-basic`; service-wide defaults make the composition usable without repeated numeric policy. ## Testing diff --git a/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md index 4227341aec..e1c5d03c08 100644 --- a/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md +++ b/.agents/notes/implemented/feature/2026-06-25-ask-user-question.md @@ -20,7 +20,7 @@ Providers return `{ answers: [{ id, selected, custom? }] }`. `selected` is alway ## UI mappings -`dsh-stdio-demo`'s in-package readline module renders each question, shows each option's `description` on the next line, supports comma/space-separated numeric choices for `multi_select`, accepts free-form custom answers, and rejects pending questions on abort, provider disposal, or stdin EOF. A batched request is asked in order and resolved as one answer object. The stdio provider serializes simultaneous requests with an internal queue so only one prompt owns stdin at a time. +`dsh-tui` renders each question as a keyboard overlay, shows option descriptions, supports single- and multi-select choices plus free-form custom answers, and rejects pending questions on abort, provider disposal, or terminal shutdown. Batched and simultaneous requests are queued so one overlay owns keyboard focus at a time. `dsh-acp` provides the same seam for ACP sessions. It resolves the calling `Agent` through `ownedRecord`, requiring the forward session-map record at `agent.session.id` to own that exact agent object, and calls ACP `unstable_createElicitation` with a session-scoped form for each question. Single-select options become a `choice` string enum; `multi_select` options become a `choice` array enum; optionless questions use a required `custom` text field. If the client returns both `choice` and non-empty `custom`, the custom answer wins. ACP `decline`/`cancel`, a missing answer, a missing session, and a client without elicitation support all become structured `UserInteractionError`s. @@ -42,8 +42,8 @@ ACP elicitation is currently marked unstable in the SDK. The fallback is still s The feature gives the model a powerful pause primitive, so prompt guidance matters. The tool description tells the model to ask concise questions and use options when possible. Product policy can later wrap `tools/execute` to restrict when the tool is allowed, but the loop should not special-case it. -`dsh-user-interaction` and `dsh-tool-ask-user` both live in `packages/ui` because they form one product-facing human-interaction capability. `agent-core` does not load either the tool or a provider. `stdio-agent` opts into the seam, its readline provider, and the model-facing tool. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests. +`dsh-user-interaction` and `dsh-tool-ask-user` both live in `packages/ui` because they form one product-facing human-interaction capability. `agent-core` does not load either the tool or a provider. `dsh-tui-demo` opts into the seam, TUI provider, and model-facing tool. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests. ## Testing -Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. `dsh-stdio-demo` tests cover option descriptions, queued requests, EOF/abort cleanup, optionless free-form input, invalid option reprompts, duplicate multi-select numbers, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop. +Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. TUI tests cover option descriptions, queued requests, shutdown/abort cleanup, optionless free-form input, invalid choices, duplicate multi-select selections, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop. diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md index d46579dee1..c78126e92a 100644 --- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md +++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md @@ -21,7 +21,7 @@ The system-prompt assembly owns the canonical model-facing tool order, exactly w Scope is deliberately narrow: this fixes the REGISTRATION-ORDER race, not plugin behavior. A `system-prompt/assemble` listener may still add, remove, or rearrange tools — same as it may edit sections after their sort — and owns the determinism of what it emits; the waterfall contract already demands deterministic listeners (the reconstructability invariant would catch a listener that diverges between build and replay). -Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it: the app configs (`dsh-stdio-demo`, `dsh-acp-demo`) accept the key and forward it through `dsh-agent-spine-demo` (whose schema is the intersection of the owners' schemas) to the `SystemPrompt` child. One schemastery footnote is load-bearing: a schemastery array defaults to `[]`, but an omitted `toolOrder` must stay ABSENT (= lexicographic) rather than become an explicitly-configured empty list (invalid — it lacks the rest entry), so every schema on the chain forces the default to `undefined`. +Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it: the TUI, Headless, and ACP app configs accept the key and forward it through `dsh-agent-spine-demo` (whose schema is the intersection of the owners' schemas) to the `SystemPrompt` child. One schemastery footnote is load-bearing: a schemastery array defaults to `[]`, but an omitted `toolOrder` must stay ABSENT (= lexicographic) rather than become an explicitly-configured empty list (invalid — it lacks the rest entry), so every schema on the chain forces the default to `undefined`. ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-09-bash-backed-grep-glob-discovery.md b/.agents/notes/implemented/feature/2026-07-09-bash-backed-grep-glob-discovery.md index 60a5e3e3a0..64fa232831 100644 --- a/.agents/notes/implemented/feature/2026-07-09-bash-backed-grep-glob-discovery.md +++ b/.agents/notes/implemented/feature/2026-07-09-bash-backed-grep-glob-discovery.md @@ -155,7 +155,7 @@ If the complete logical result fits under the inline cap, no formatted spill art - The tools execute through `ctx.bash.resolve(request)` → `ctx.bash.run(spec)`, forward `exec.signal`, never call `ctx.bash.start()`, and never expose a bash task id. The bash request workdir comes from `exec.agent?.session.header.cwd` when available; the resolved `spec.workdir` drives execution and relative-path display. - The tools request `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam, parse only untruncated stdout within that cap, and treat over-cap or still-truncated raw output as a clear search failure; raw `rg` output is never exposed to the model. - Oversized complete formatted results are saved through `ctx.spillStore.saveText()` when available while inline results stay bounded; spill failure, a missing backend, or a missing owner preserves the inline result and reports the unsaved remainder — never an `isError`. -- The package README, the generated config catalog, and exported JSDoc document the Config fields and `SEARCH_*` codes; the repl-agent example ships the conditional tool plugin (the acp-agent tree waits on the snapshot re-record above); the fs group README records the `rg` availability and co-located bash/filesystem deployment requirements. +- The package README, the generated config catalog, and exported JSDoc document the Config fields and `SEARCH_*` codes; the tui-agent example ships the conditional tool plugin (the acp-agent tree waits on the snapshot re-record above); the fs group README records the `rg` availability and co-located bash/filesystem deployment requirements. ## Risks diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml index 34c342ffd3..bc77edbd0a 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-17-dedicated-full-screen-tui-front-door.md: 178b5ea44be67f820a8ea7fed8acb987dffb3f80 -2026-07-17-dedicated-full-screen-tui-front-door.zh.md: ac055bad1b7a692c7a980430fdbd1e34737a9994 +2026-07-17-dedicated-full-screen-tui-front-door.md: 8fbc5dddc029190b346075a65c9e7857187f3d2b +2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 6ddc3523b7a7173013efe2ef15c5ca0e940929fb diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md index 178b5ea44b..8fbc5dddc0 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md @@ -6,7 +6,7 @@ English | [中文](2026-07-17-dedicated-full-screen-tui-front-door.zh.md) ## Problem -The line-oriented `@deepseek-ai/dsh-stdio` front door works in pipes and ordinary terminals, but a full-screen coding interface must own raw input, differential screen drawing, cursor state, overlays, and terminal restoration. Combining those contracts in one UI plugin couples the pipe-safe path to a TTY-only lifecycle and makes it unclear which terminal behavior a composition selects. +At the time this front door was introduced, the line-oriented agent handled pipes and ordinary terminals, but a full-screen coding interface had to own raw input, differential screen drawing, cursor state, overlays, and terminal restoration. Combining those contracts in one UI plugin would have coupled a stream-oriented path to a TTY-only lifecycle. The later [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) removes that line agent; this Note continues to own the TUI design. The interactive channel must remain a Cordis plugin over the same agent, session, tool, and user-interaction services as every other front door. It needs to resume durable history, follow compaction replacements, display tool-owned presentation, and restore the terminal on startup failure and disposal. A standalone chat application or a second agent composition would duplicate behavior outside the plugin graph. @@ -14,7 +14,7 @@ The interactive channel must remain a Cordis plugin over the same agent, session DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior. -The app layer selects a concrete terminal front door before mounting it. `@deepseek-ai/dsh-stdio-demo` can resolve `auto` from the two process streams, while the `repl-agent` and `tui-agent` leaves explicitly select readline and TUI respectively. The TUI leaf reuses the repl-agent backend and tool composition through an asserted include patch, so the three runnable agent leaves remain symmetric without duplicating deployment choices. +The app layer has one terminal front door. `@deepseek-ai/dsh-tui-demo` mounts the TUI before the configured agent, and `examples/tui-agent` owns the interactive coding composition and Code Mode overlay directly. Non-interactive tasks use `@deepseek-ai/dsh-cli-demo`; ACP remains a separate editor protocol. The selected front door receives the exact generated or resumed `SessionId` used by the pre-created agent. It mounts before the agent composition, waits for the matching root agent, and enters full-screen mode only after that agent exists. A matching `agent-loop/config-start-failed` event is therefore reported before screen takeover and exits with status 1. @@ -42,7 +42,7 @@ The implemented [TUI terminal-state snapshot Agent Note](../testing/2026-07-18-t ## Consequences -- Interactive terminal work gains a stateful Markdown, card, plan, and question interface without changing the line-oriented protocol used by pipes and automation. -- The TUI carries a pi-tui dependency and a strict TTY requirement; non-TTY deployments select `@deepseek-ai/dsh-stdio` at composition time. +- Interactive terminal work has a stateful Markdown, card, plan, and question interface with no second terminal protocol to keep aligned. +- The TUI carries a pi-tui dependency and a strict TTY requirement; non-TTY deployments use the Headless app or a structured protocol. - Session projection makes resume and compaction consistent with the durable conversation, but one configured session owns the transcript and editor. - Tool packages extend terminal cards through their existing presentation methods without adding tool-specific branches to the TUI. diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md index ac055bad1b..6ddc3523b7 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md @@ -6,7 +6,7 @@ Status: implemented ## 问题 -逐行输出的 `@deepseek-ai/dsh-stdio` 入口适用于管道和普通终端，但全屏编码界面必须负责原始输入、差分绘制、光标状态、浮层和终端恢复。把这两类契约合并到一个 UI 插件中，会迫使管道安全路径依赖仅适用于 TTY 的生命周期，也使组合无法明确表达所选终端行为。 +在本入口引入时，面向行的 agent 负责 pipe 与普通终端，但全屏 coding 界面必须负责原始输入、差分绘制、光标状态、浮层和终端恢复。把这两类契约合并到一个 UI 插件中，会迫使面向 stream 的路径依赖仅适用于 TTY 的生命周期。后续的[移除重复 agent 决策](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)移除了这个面向行 agent；本 Note 继续负责 TUI 设计。 交互通道必须继续作为 Cordis 插件，使用与其他入口相同的 agent（智能体）、会话、工具和用户交互服务。它需要恢复持久历史、跟随压缩替换、显示工具自有的呈现内容，并在启动失败和资源释放时恢复终端。独立聊天应用或第二套 agent 组合会在插件图之外重复实现这些行为。 @@ -14,7 +14,7 @@ Status: implemented DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。 -应用组合层在挂载前选择具体的终端入口。`@deepseek-ai/dsh-stdio-demo` 可以根据两个进程流通过 `auto` 作出选择，`repl-agent` 和 `tui-agent` 叶节点则分别明确选择 readline 与 TUI。TUI 叶节点通过带断言的 include patch 复用 repl-agent 的后端和工具组合，使三个可运行的 agent 叶节点保持对称，同时避免重复部署选项。 +应用组合层只有一个终端入口。`@deepseek-ai/dsh-tui-demo` 在已配置 agent 之前挂载 TUI，`examples/tui-agent` 直接拥有交互式 coding 组装及其 Code Mode overlay。非交互任务使用 `@deepseek-ai/dsh-cli-demo`；ACP 仍是独立的编辑器协议。 所选入口接收预创建 agent 使用的同一个新建或恢复 `SessionId`。入口先于 agent 组合挂载，等待相符的根 agent 出现，然后才进入全屏模式。因此，相符的 `agent-loop/config-start-failed` 事件会在接管屏幕前报告，并以状态码 1 退出。 @@ -42,7 +42,7 @@ agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调 ## 后果 -- 交互式终端获得带状态的 Markdown、卡片、计划和提问界面，同时不会改变管道与自动化使用的逐行协议。 -- TUI 会引入 pi-tui 依赖并严格要求 TTY；非 TTY 部署在组合时选择 `@deepseek-ai/dsh-stdio`。 +- 交互式终端拥有带状态的 Markdown、卡片、计划和提问界面，无需再对齐第二套终端协议。 +- TUI 会引入 pi-tui 依赖并严格要求 TTY；非 TTY 部署使用 Headless app 或结构化协议。 - 会话投影使恢复和压缩与持久会话保持一致，但只有一个已配置会话拥有 transcript 和编辑器。 - 工具包通过既有呈现方法扩展终端卡片，无需在 TUI 中增加工具专用分支。 diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml index 9ef2bae475..17e3cdf5e2 100644 --- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-19-fresh-agent-ralph-workflow-tool.md: 46816b8cc06f0acf5615ffb44035c79ea13b6794 -2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 188a0bf50a7a6a683cd6aa1004c4d78673d3631d +2026-07-19-fresh-agent-ralph-workflow-tool.md: c2db4d7dd30c27a25adecdfc425db261cc3dfeb5 +2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: e33e9848d71c98c8f83494ebe8bf171ef10b9305 diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md index 46816b8cc0..c2db4d7dd3 100644 --- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md +++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md @@ -40,7 +40,7 @@ The workflow language maps a normally settled but unsuccessful child to `null`. The model may supply only `objective` and optional `maxRounds`; provider selection, report schema, handoff cap, and script are deployment-owned. A fixed prompt section says to use `ralph` only when the direct human explicitly asks for Ralph or fresh-agent iteration, and distinguishes it from same-session goals, bounded delegation, and general fan-out workflows. This is guidance rather than a new goal UX state machine. -ACP and terminal presentation use a generic `ralph` card whose raw input is the objective. Successful completion and blocker envelopes say that a worker reported the outcome rather than presenting it as independent certification. The parent transcript retains the original tool call and one bounded successful terminal report or an error, not intermediate child messages. Shipped headless, REPL/TUI, and ACP compositions load the plugin beside the existing workflow engine; JSON-RPC remains unchanged because its default composition does not expose workflows. +ACP and terminal presentation use a generic `ralph` card whose raw input is the objective. Successful completion and blocker envelopes say that a worker reported the outcome rather than presenting it as independent certification. The parent transcript retains the original tool call and one bounded successful terminal report or an error, not intermediate child messages. Shipped headless, TUI, and ACP compositions load the plugin beside the existing workflow engine; JSON-RPC remains unchanged because its default composition does not expose workflows. ## Testing diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md index 188a0bf50a..e33e9848d7 100644 --- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md @@ -40,7 +40,7 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要 模型只能提供 `objective` 和可选的 `maxRounds`；provider 选择、报告 schema、交接上限和脚本都由部署拥有。固定提示区段说明，只有直接人类明确要求 Ralph 或全新 agent 迭代时才使用 `ralph`，并将其与同会话目标、有界委派和通用扇出工作流区分开。这是指导，而不是新的目标 UX 状态机。 -ACP 和终端展示使用通用 `ralph` 卡片，并把目标作为原始输入。成功完成与阻塞的外层文本会说明结果由工作者报告，而不会把它呈现为独立认证。父转录只保留原始工具调用，以及一份有界成功终止报告或一个错误，不包含中间子 agent 消息。发布的无头、REPL/TUI 与 ACP 组合会在现有工作流引擎旁加载该插件；JSON-RPC 保持不变，因为其默认组合不暴露工作流。 +ACP 和终端展示使用通用 `ralph` 卡片，并把目标作为原始输入。成功完成与阻塞的外层文本会说明结果由工作者报告，而不会把它呈现为独立认证。父转录只保留原始工具调用，以及一份有界成功终止报告或一个错误，不包含中间子 agent 消息。发布的无头、TUI 与 ACP 组合会在现有工作流引擎旁加载该插件；JSON-RPC 保持不变，因为其默认组合不暴露工作流。 ## 测试 diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml index 3505cfabca..5379f25772 100644 --- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-19-human-goal-command.md: e2a59c3bddd7e135b0878cb59c964c3e7be64002 -2026-07-19-human-goal-command.zh.md: 0d6a0e22de091cd7a4a00ef59f1ac1b936c930f9 +2026-07-19-human-goal-command.md: a272206a3bfad50a01ce871c56c7e7bcf924684e +2026-07-19-human-goal-command.zh.md: 370c9bc24510320c70e3d789926c492e543968b1 diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md index e2a59c3bdd..a272206a3b 100644 --- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md +++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md @@ -40,11 +40,11 @@ Generic slash input, status text, and errors are not persisted. Successful goal `agent-spine-demo` accepts an optional `goals` composition object containing the goal-domain and model-tool owner configs. Omission or `false` leaves the stack unmounted. This explicit opt-in is important for headless one-shot callers: their result API settles one correlated physical turn and must not silently become a long-running logical goal operation. -The interactive app bundles make the opposite product choice. ACP defaults `goals` to the owner defaults and mounts the goal domain, model tools, same-session driver, command registry, and this producer. The terminal app enables the same goal stack by default but mounts the producer only for TUI mode; line-oriented stdio does not consume the command plane, so a typed `/goal` there remains an ordinary human prompt that the model may interpret through its separately authorized goal tools. Both apps accept `goals: false` as one coherent stack opt-out. The Python SDK runtime closure ships this producer alongside ACP, commands, and the goal stack so an external `cordis.yml` can compose the same command. +The interactive app bundles make the opposite product choice. ACP and TUI default `goals` to the owner defaults and mount the goal domain, model tools, same-session driver, command registry, and this producer. Both apps accept `goals: false` as one coherent stack opt-out. The Python SDK runtime closure ships this producer alongside ACP, commands, and the goal stack so an external `cordis.yml` can compose the same command. ## Testing -The producer suite uses the real command registry, goal service, agent registry, and session log. It covers Loader-safe exports, registry discovery, disposal, empty status, objective parsing, unfinished replacement refusal, inline edit, completed replacement, all missing-state controls, pause/resume/clear, every durable phase, blocked code/explanation presentation, armed/disarmed presentation, sanitized domain errors, unexpected failures, and persisted mutation records. App composition tests cover explicit spine opt-in, TUI/ACP defaults, readline producer absence, coherent opt-out, forwarded domain/tool config, command discovery, the packaged-runtime closure, and the expanded model-tool assembly. A keyless snapshot boots the shipped ACP application, observes its advertised `/goal` metadata, invokes `/goal` directly, and pins the no-model-turn result; the surrounding ACP snapshots also pin the goal tool schemas in that composition. +The producer suite uses the real command registry, goal service, agent registry, and session log. It covers Loader-safe exports, registry discovery, disposal, empty status, objective parsing, unfinished replacement refusal, inline edit, completed replacement, all missing-state controls, pause/resume/clear, every durable phase, blocked code/explanation presentation, armed/disarmed presentation, sanitized domain errors, unexpected failures, and persisted mutation records. App composition tests cover explicit spine opt-in, TUI/ACP defaults, coherent opt-out, forwarded domain/tool config, command discovery, the packaged-runtime closure, and the expanded model-tool assembly. A keyless snapshot boots the shipped ACP application, observes its advertised `/goal` metadata, invokes `/goal` directly, and pins the no-model-turn result; the surrounding ACP snapshots also pin the goal tool schemas in that composition. ## Alternatives considered @@ -68,5 +68,5 @@ The producer suite uses the real command registry, goal service, agent registry, - The portable command contract has no modal editor or confirmation interaction; inline edit and explicit clear are intentional until a general cross-surface interaction primitive exists. - `/goal` does not accept a per-command round cap. Deployment config owns the default, and the authorized model tool can edit a cap after direct human instruction. - TUI and ACP render portable plain text rather than a continuously updated goal status widget. Reconnectable command output and adapter-specific status indicators are deferred. -- The line-oriented stdio and JSON-RPC front doors do not consume the command registry. +- The headless CLI and JSON-RPC front doors do not consume the command registry. - The command observes and mutates state but does not certify completion or blockers. Evaluator-backed certification remains deferred to a separate policy layer with an explicit authority and isolation contract. diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md index 0d6a0e22de..370c9bc245 100644 --- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md @@ -40,11 +40,11 @@ Status: implemented `agent-spine-demo` 接受可选的 `goals` 组合对象，其中包含目标领域与模型工具的所有者配置。省略或设为 `false` 时不会挂载该栈。对无头单次调用方而言，明确选择加入非常重要：它们的结果 API 会在一个相关物理轮次后结束，不能静默变成长时间运行的逻辑目标操作。 -交互式应用包作出相反的产品选择。ACP 默认让 `goals` 使用所有者默认值，并挂载目标领域、模型工具、同会话驱动器、命令注册表与本生产方。终端应用默认启用相同目标栈，但只在 TUI 模式挂载本生产方；行式 stdio 不消费命令平面，因此在那里输入的 `/goal` 仍是普通人类提示词，模型可以通过独立授权的目标工具解释它。两个应用都接受 `goals: false` 作为一致的整体退出选项。Python SDK 运行时闭包把本生产方与 ACP、命令及目标栈一并交付，使外部 `cordis.yml` 能组合相同命令。 +交互式应用包作出相反的产品选择。ACP 与 TUI 默认让 `goals` 使用所有者默认值，并挂载目标领域、模型工具、同会话驱动器、命令注册表与本生产方。两个应用都接受 `goals: false` 作为一致的整体退出选项。Python SDK 运行时闭包把本生产方与 ACP、命令及目标栈一并交付，使外部 `cordis.yml` 能组合相同命令。 ## 测试 -生产方测试套件使用真实命令注册表、目标服务、agent 注册表与会话日志。它覆盖 Loader 安全导出、注册表发现、资源释放、空状态、目标描述解析、拒绝未完成目标替换、行内编辑、已完成目标替换、所有缺失状态控制、暂停/恢复/清除、每个持久阶段、阻塞代码/说明展示、已激活/未激活展示、经净化的领域错误、意外失败与持久变更记录。应用组合测试覆盖显式主干选择加入、TUI/ACP 默认值、readline 不挂载生产方、一致退出、转发的领域/工具配置、命令发现、打包运行时闭包与扩展后的模型工具组装。一个无密钥快照会启动交付的 ACP 应用，观察其公布的 `/goal` 元数据，直接调用 `/goal`，并固定不经过模型轮次的结果；周边 ACP 快照还会固定该组合中的目标工具 schema。 +生产方测试套件使用真实命令注册表、目标服务、agent 注册表与会话日志。它覆盖 Loader 安全导出、注册表发现、资源释放、空状态、目标描述解析、拒绝未完成目标替换、行内编辑、已完成目标替换、所有缺失状态控制、暂停/恢复/清除、每个持久阶段、阻塞代码/说明展示、已激活/未激活展示、经净化的领域错误、意外失败与持久变更记录。应用组合测试覆盖显式主干选择加入、TUI/ACP 默认值、一致退出、转发的领域/工具配置、命令发现、打包运行时闭包与扩展后的模型工具组装。一个无密钥快照会启动交付的 ACP 应用，观察其公布的 `/goal` 元数据，直接调用 `/goal`，并固定不经过模型轮次的结果；周边 ACP 快照还会固定该组合中的目标工具 schema。 ## 考虑过的替代方案 @@ -68,5 +68,5 @@ Status: implemented - 可移植命令契约没有模态编辑器或确认交互；在出现通用跨表面交互原语之前，行内编辑与明确清除是有意选择。 - `/goal` 不接受逐命令回合上限。部署配置拥有默认值；得到直接人类指示后，已授权模型工具可以编辑上限。 - TUI 与 ACP 渲染可移植纯文本，而不是持续更新的目标状态组件。可重连命令输出和适配器专用状态指示器予以延期。 -- 行式 stdio 与 JSON-RPC 前端不消费命令注册表。 +- 无头 CLI 与 JSON-RPC 前端不消费命令注册表。 - 该命令观察并改变状态，但不认证完成或阻塞。基于评估器的认证延期到具有明确权限与隔离契约的独立策略层。 diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml index 7294638f1a..0addad9e97 100644 --- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-19-plugin-command-registration.md: c414f8183e100f712a552828992d108193fc33cf -2026-07-19-plugin-command-registration.zh.md: 3cd820c55ec30f3b2f6cf471376abfd8edd8ac5e +2026-07-19-plugin-command-registration.md: a207c6257bd4e9e4013f1abb661dd967ed2a52dc +2026-07-19-plugin-command-registration.zh.md: e21d187ded0ee0f4daa370655994eb306fb1c5fd diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md index c414f8183e..a207c6257b 100644 --- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md +++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md @@ -78,4 +78,4 @@ TUI tests exercise all migrated built-ins, live plugin discovery, help/autocompl - Input metadata is ACP's current unstructured text hint. Typed forms, argument schemas, and completion providers remain command-owned or require a later protocol extension. - Generic command output is live-only and is not reconstructed after TUI restart or ACP reconnect. - Registry cancellation stops awaiting immediately, but external work stops only when a handler cooperates with its signal. -- The shipped line-oriented `dsh-stdio` and JSON-RPC SDK front doors do not expose the command plane; only TUI and ACP consume it. +- The headless CLI and JSON-RPC SDK front doors do not expose the command plane; only TUI and ACP consume it. diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md index 3cd820c55e..e21d187ded 100644 --- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md @@ -78,4 +78,4 @@ TUI 测试覆盖全部迁移后的内置命令、实时插件发现、帮助与 - 输入元数据仅为 ACP 当前的非结构化文本提示。类型化表单、参数模式和补全提供器仍由命令拥有，或需要后续协议扩展。 - 通用命令输出仅实时存在，TUI 重启或 ACP 重新连接后不会重建。 - 注册表取消会立即停止等待，但外部工作只有在处理器配合信号时才会停止。 -- 已发布的行式 `dsh-stdio` 与 JSON-RPC SDK 前端不暴露命令平面；只有 TUI 和 ACP 消费它。 +- 无头 CLI 与 JSON-RPC SDK 前端不暴露命令平面；只有 TUI 和 ACP 消费它。 diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.md b/.agents/notes/implemented/process/2026-06-11-quality-gates.md index 1a1cfe5b54..84c3da7b95 100644 --- a/.agents/notes/implemented/process/2026-06-11-quality-gates.md +++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.md @@ -15,7 +15,7 @@ Every AGENTS.md promise gets a command that exits non-zero, wired into git hooks - jscpd detects cross-file clones in package production TypeScript and repository scripts; narrow source-range exceptions document deliberately parallel implementations. - Per-file 100% coverage on `packages/*/*/src` (v8); unreachable defensive guards carry `/* v8 ignore */ ` with stated reasons instead of deletion. - knip (dead code/deps), publint (package correctness), workspace constraints (workspace rules: private, cordis peer+dev, uniform version, ESM), and a NodeNext consumer typecheck for built package declarations. -- lefthook pre-commit (lint staged, typecheck, vendor-manifest guard) and pre-push (tests, hygiene); CI runs the full matrix on node 22.19/24/26 plus a demo smoke test driving the echo-agent end to end. +- lefthook pre-commit (lint staged, typecheck, vendor-manifest guard) and pre-push (tests, hygiene); CI runs the full matrix on node 22.19/24/26 plus built application smokes for the Headless, TUI, ACP, JSON-RPC, workflow, and code-runtime entry paths. ## Consequences diff --git a/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md index f4a5d43f96..42eb4228b6 100644 --- a/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md +++ b/.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md @@ -38,4 +38,4 @@ Performance (measured at migration time on the dev NFS filesystem; single-digit- On a fast local disk pnpm's content-addressed store typically wins on cold/warm installs and, especially, on **disk footprint** across multiple checkouts (one global store hardlinked into every `node_modules` vs Yarn copying ~279 MB per worktree — some devs regularly keep ~10 or more worktrees for this repo). That dedup advantage did **not** show in the migration-time numbers above because the test store and `node_modules` sat on different filesystems, defeating hardlinks; on a single-filesystem dev box or CI cache it applies. The honest summary: install speed on our NFS dev filesystem is a wash within noise; the move is justified by ecosystem alignment, phantom-dependency safety, and cross-checkout disk dedup — not by a raw install-time win. -All quality gates (constraints, typecheck, lint, doc-sync, test:coverage at 100%, build, knip, publint, echo-agent demo smoke) pass unchanged on pnpm, which is the correctness proof that the linker swap introduced no phantom-dependency breakage. +All quality gates (constraints, typecheck, lint, doc-sync, test:coverage at 100%, build, knip, publint, and built application smokes) pass on pnpm, which is the correctness proof that the linker swap introduces no phantom-dependency breakage. diff --git a/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md index 4f3fafe59d..7969f0e80c 100644 --- a/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md +++ b/.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md @@ -26,15 +26,16 @@ Every graph page declares one maintenance mode: ### First shipped index -The first index links ten relationship surfaces. Package topology and tool-package affordances live in the existing generated catalogs that already own those facts; the remaining focused diagrams are generated by `scripts/gen-doc-graphs.ts`. +The index links eleven relationship surfaces. Package topology and tool-package affordances live in the existing generated catalogs that already own those facts; the remaining focused diagrams are generated by `scripts/gen-doc-graphs.ts`. | Graph | Maintenance mode | Source of truth | |---|---|---| | [module dependency graph](../../../../docs/module-graph.md) | generated | `packages/*/*/package.json` peer dependencies plus package group paths | | [tool schema catalog and package map](../../../../docs/tool-catalog.md) | generated | boot-harvested tool schemas plus tool-package service/effect metadata | | [capability seams and core services](../../../../docs/capability-seams.md) | hybrid generated | Cordis service declarations plus a role manifest in `gen-doc-graphs.ts` | -| [echo-agent app composition](../../../../examples/echo-agent/composition.md) | hybrid generated | `examples/echo-agent/cordis.yml` plugin list plus curated app/bundle expansion | -| [repl-agent app composition](../../../../examples/repl-agent/composition.md) | hybrid generated | `examples/repl-agent/cordis.yml` plugin list plus curated app/bundle expansion | +| [tui-agent app composition](../../../../examples/tui-agent/composition.md) | hybrid generated | `examples/tui-agent/cordis.yml` plugin list plus curated app/bundle expansion | +| [headless-agent app composition](../../../../examples/headless-agent/composition.md) | hybrid generated | `examples/headless-agent/cordis.yml` plugin list plus curated app/bundle expansion | +| [cordis-agent app composition](../../../../examples/cordis-agent/composition.md) | hybrid generated | `examples/cordis-agent/cordis.yml` plugin list plus curated app/bundle expansion | | [acp-agent app composition](../../../../examples/acp-agent/composition.md) | hybrid generated | `examples/acp-agent/cordis.yml` plugin list plus curated app/bundle expansion | | [event producer/consumer matrix](../../../../docs/event-producer-consumer.md) | hybrid generated | Cordis event declarations, AST-scanned `ctx.on/emit/parallel/serial/waterfall` sites, and explicit dynamic dispatch overrides | | [agent turn and step lifecycle](../../../../docs/agent-lifecycle.md) | curated | architecture.md loop lifecycle, Cordis catalog links, and session event semantics | diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md index 59f4c347eb..507641a99a 100644 --- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md +++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md @@ -13,7 +13,7 @@ Set `engines.node` to `^22.19.0 || >=24.0.0` and test the keyless CI compatibili Two Node features gate the source runtime: - **`node:sqlite`** — `packages/session-persistence/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load. -- **Native TypeScript type-stripping** — the `packages/examples/stdio-demo/tests/built-bin.e2e.ts` smoke boots the published `lib/bin.js` under plain `node` (no tsx) and loads the example's `.ts` plugins (`mock-llm.ts`, `echo-tool.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`. +- **Native TypeScript type-stripping** — the built-mode `examples/headless-agent/tests/keyless-smoke.e2e.ts` smoke boots `dsh-cli-demo`'s published `lib/bin.js` under plain `node` (no tsx) and loads the example's `.ts` test adapter (`cli-mock-llm.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`. Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use. diff --git a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md index ecea052387..d8d4015b0d 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md +++ b/.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md @@ -24,7 +24,7 @@ If an LLM adapter browser or dynamic model-picker needs this signal later, reint ## Verification -`llm/adapter-change` and its emits are gone and the regenerated cordis catalog is fresh; HMR-safety holds (disposing a contributing fiber removes the adapter); `tools/change` and `system-prompt/change` remain documented and tested; and no production path changed observable behavior — the ACP snapshot expected outputs and the echo-agent smoke are byte-unchanged. +`llm/adapter-change` and its emits are gone and the regenerated cordis catalog is fresh; HMR-safety holds (disposing a contributing fiber removes the adapter); `tools/change` and `system-prompt/change` remain documented and tested; and the ACP snapshots plus the keyless Headless Loader smoke pin the unchanged production paths. ## Consequences diff --git a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md index bde3efcc75..b05dd22357 100644 --- a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md +++ b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md @@ -2,6 +2,8 @@ Status: implemented +The later [redundant-agent removal](2026-07-20-remove-stdio-and-echo-agents.md) supersedes this package-placement decision and removes the folded package, app, and line-oriented surface entirely. + ## Problem The readline UI was a whole package (`@deepseek-ai/dsh-ui-stdio` under `packages/support/`) whose only runtime importer was the app package `@deepseek-ai/dsh-stdio-demo`. The examples reach the readline UI by loading the app, never by composing the helper themselves; every other repo reference was mechanical or descriptive surface that existed BECAUSE the package boundary existed — manifest and tsconfig entries, generated module-graph rows, dependency-graph and README rows, and doc comments naming the package. The ui group README recorded the support placement rationale ("exists chiefly for the examples and the coverage gate — `ui/` is reserved for surfaces shipped as product"), which left a standing tension: a shipped product app depending on a support package documented as NOT product surface. @@ -10,9 +12,9 @@ The boundary bought package metadata, workspace and tsconfig references, module- ## Decision -The helper lives in `@deepseek-ai/dsh-stdio` as the terminal-channel plugin (`packages/ui/stdio/src/index.ts`): `createStdioChat`, its `StdioRuntime` test seam, and its unit tests (`packages/ui/stdio/tests/stdio.spec.ts`, `readline.spec.ts`) moved with it, so EOF handling, rendering, disposal, and piped-vs-TTY behavior stay unit-covered under the per-file coverage gate without hijacking process globals. The module keeps the named `name`/`inject`/`Config`/`apply` export shape — the contract the app's `ctx.plugin(uiStdio, …)` mount consumes — and the keyless Loader-path smokes in `examples/echo-agent` and `examples/repl-agent` keep proving the composed tree boots through the real Loader (the stdio package's plugin-shape unit suite pins the explicit `unwrapExports` assertion, since a bundle without `inject` would boot past a stray default rather than crash). +At the time, the helper moved into `@deepseek-ai/dsh-stdio` as the terminal-channel plugin. `createStdioChat`, its `StdioRuntime` test seam, and its unit tests moved with it, keeping EOF handling, rendering, disposal, and piped-vs-TTY behavior under the per-file coverage gate without hijacking process globals. The module kept the named `name`/`inject`/`Config`/`apply` export shape consumed by the app mount, while the then-current Echo and REPL Loader smokes proved the composed tree and the plugin-shape suite pinned explicit `unwrapExports` behavior. The superseding removal note above owns the current package and example state. -The `packages/support/ui-stdio` package is gone: manifest, tsconfig references, module-graph rows, and README rows deleted; the doc comments that named the package (the example e2e module docs, `packages/README.md`, the support and todo READMEs, [the ui group README](../../../../packages/ui/README.md)) describe the in-package module. +The earlier support helper package was removed: its manifest, tsconfig references, module-graph rows, and README rows disappeared, while the remaining documentation described the in-package module. ## Alternatives considered diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml new file mode 100644 index 0000000000..91e9b078ad --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-20-remove-stdio-and-echo-agents.md: 2aba8193710c96d3726b91062bfa43d039b4cabf +2026-07-20-remove-stdio-and-echo-agents.zh.md: 2c3916683f4743384a2ce4104319da26145837fe diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md new file mode 100644 index 0000000000..2aba819371 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md @@ -0,0 +1,45 @@ +# Agent Note: Remove the stdio and Echo agents + +Status: implemented + +English | [中文](2026-07-20-remove-stdio-and-echo-agents.zh.md) + +## Problem + +DeepSeek Harness exposed two redundant product agents beside the TUI and Headless coding agents. The line-oriented stdio agent duplicated terminal interaction and non-interactive execution with a mixed prompt/output protocol. Echo duplicated Headless as a network-free mock model plus one teaching tool, making a test fixture into a user-facing agent and the default quick-start path. + +Both agents carried support surfaces beyond their leaf configurations. Stdio owned a UI plugin, app package, SDK interface, REPL leaf, prompt protocol, and Loader tests. Echo owned a runnable command, mock adapter, tool, CI demo gate, graph entry, teaching references, and a shared test fixture. Keeping any of those product paths would preserve the redundant agent indirectly. + +Standard input and output remain protocol boundaries for ACP, JSON-RPC, MCP, and child processes. Deterministic model adapters also remain valid inside tests. Those mechanisms do not justify a line-oriented or mock-only product agent. + +## Decision + +The stdio and Echo agents are removed without compatibility packages, modes, commands, or aliases. The stdio UI and app packages, `examples/repl-agent`, `examples/echo-agent`, `demo:repl`, `demo:echo`, their dedicated tests, and supporting manifests, gates, graphs, and documentation entries are deleted. + +The remaining application roles are explicit: + +- [`@deepseek-ai/dsh-tui-demo`](../../../../packages/examples/tui-demo/README.md) owns terminal-interactive execution. `examples/tui-agent` owns the complete coding composition, Code Mode overlay, PTY coverage, and terminal snapshots. +- [`@deepseek-ai/dsh-cli-demo`](../../../../packages/examples/cli-demo/README.md) owns non-interactive execution. `examples/headless-agent` owns the real-model one-shot composition, replay snapshots, generic real-agent suites, and test-only keyless Loader fixtures. +- [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) and `@deepseek-ai/dsh-jsonrpc` own their framed protocol integrations. + +The SDK project model and create/config workflows replace the `stdio` run-interface option with `tui`; generated TUI projects compose `@deepseek-ai/dsh-tui` and create or resume one exact session. Repository-facing demo documentation requires a DeepSeek API key and leads with the real Headless or TUI agents. + +Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapter to exercise a real tool round trip, the CLI built-bin suite pins output, persistence, failure, and signal semantics, and package-specific Loader tests keep deterministic adapters beside their scenarios. None is exposed as a runnable mock agent. + +## Verification + +TUI and Headless Loader coverage run the real app packages in source and built modes. TUI uses a pseudo-terminal; Headless proves its task/result and tool-call contracts. Generated graphs and repository searches reject stale package, command, leaf, and SDK-interface references. + +## Alternatives considered + +- **Keep the line agent only for pipes** — rejected because Headless has a bounded task contract, format-pure stdout, durable completion, and process exit status. +- **Keep Echo as the keyless quick start** — rejected because the first product experience should exercise the real model and supported coding agent, not a scripted adapter with a bespoke tool. +- **Keep Echo only as a CI demo command** — rejected because test-owned Headless fixtures cover the same Loader and built-artifact boundaries without preserving a mock product leaf. +- **Remove every stdio or mock mechanism** — rejected because framed protocols, process I/O, and deterministic test adapters are independent infrastructure, not the removed agents. + +## Consequences + +- Interactive and non-interactive product execution each have one owner and one runnable coding leaf. +- The repository has no keyless user-facing agent demo; local agent demos require `DEEPSEEK_API_KEY`. +- CI retains keyless real-entry coverage through test fixtures rather than a product command. +- Existing stdio-agent configurations, Echo commands, and SDK `--interface=stdio` invocations fail instead of being translated. diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md new file mode 100644 index 0000000000..2c3916683f --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md @@ -0,0 +1,45 @@ +# Agent Note: 移除 stdio 和 Echo agent + +Status: implemented + +[English](2026-07-20-remove-stdio-and-echo-agents.md) | 中文 + +## 问题 + +DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个重复的产品 agent（智能体）。面向行的 stdio agent 使用混合的提示符/输出协议，同时重复实现终端交互与非交互执行。Echo 则以无需联网的 mock 模型加一个教学工具重复实现 Headless，把测试 fixture（测试前置数据）变成面向用户的 agent 和默认快速上手路径。 + +两个 agent 的配套实现都不止叶节点配置。stdio 拥有 UI 插件、app 包（package）、SDK 接口、REPL 叶节点、提示符协议和 Loader 测试。Echo 拥有可运行命令、mock 适配器、工具、CI 演示门禁、图谱条目、教学引用和共享测试 fixture。保留其中任何产品路径，都会间接保留这个重复的 agent。 + +标准输入输出仍是 ACP、JSON-RPC、MCP 和子进程的协议边界。确定性模型适配器也仍可用于测试。这些机制不足以成为保留面向行或仅使用 mock 的产品 agent 的理由。 + +## 决策 + +彻底移除 stdio 和 Echo agent，不提供兼容包、模式、命令或别名。删除 stdio UI 包与 app 包、`examples/repl-agent`、`examples/echo-agent`、`demo:repl`、`demo:echo`、各自的专属测试，以及相关的 manifest（元数据清单）、门禁、图谱和文档条目。 + +保留的应用角色均有明确归属： + +- [`@deepseek-ai/dsh-tui-demo`](../../../../packages/examples/tui-demo/README.md) 负责终端交互式执行。`examples/tui-agent` 拥有完整 coding 组装、Code Mode 覆盖层、PTY 覆盖和终端快照。 +- [`@deepseek-ai/dsh-cli-demo`](../../../../packages/examples/cli-demo/README.md) 负责非交互式执行。`examples/headless-agent` 拥有真实模型的单次任务组装、回放快照、通用真实 agent 测试套件，以及仅供测试使用的无密钥 Loader fixture。 +- [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。 + +SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。 + +无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；CLI built-bin 测试套件固定输出、持久化、失败和信号语义；各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。 + +## 验证 + +TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。TUI 使用伪终端；Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点和 SDK 接口引用。 + +## 曾考虑的替代方案 + +- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务契约、格式纯净的 stdout、持久完成边界和进程退出状态。 +- **保留 Echo 作为无密钥快速上手路径**：不予采纳，因为首次产品体验应使用真实模型和受支持的 coding agent，而不是带专用工具的脚本化适配器。 +- **只为 CI 演示命令保留 Echo**：不予采纳，因为由测试持有的 Headless fixture 可以覆盖相同的 Loader 和构建产物边界，无需保留 mock 产品叶节点。 +- **移除所有 stdio 或 mock 机制**：不予采纳，因为分帧协议、进程 I/O 和确定性测试适配器是独立基础设施，并不是被移除的 agent。 + +## 后果 + +- 交互式与非交互式产品执行分别只有一个归属方和一个可运行的 coding 叶节点。 +- 仓库没有面向用户的无密钥 agent 演示；本地 agent 演示需要 `DEEPSEEK_API_KEY`。 +- CI 通过测试 fixture 保留针对真实入口的无密钥覆盖，而不是依赖产品命令。 +- 既有 stdio agent 配置、Echo 命令和 SDK `--interface=stdio` 调用会直接失败，不会被转换。 diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md index 56a102f456..f400701fcd 100644 --- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md +++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md @@ -40,7 +40,7 @@ Replay is positional and therefore permits only one in-flight model stream per s ### Recording harvests the log; keyless replay needs a providerless config -Recording runs the scenario with the real `llm-deepseek` adapter and the JSONL persistence backend, then copies the produced `.jsonl` into the scenario dir. Per-event appends are durable, but the harness shuts the subprocess down gracefully (close stdin → `await ctx.dispose()`) before harvesting so the final events are flushed. `llm-replay` itself does no recording — it is replay-only. +Recording runs the scenario with the real `llm-deepseek` adapter and the JSONL persistence backend configured with `persistenceCompression: 'none'`, then copies the produced `.jsonl` into the scenario dir. The explicit raw mode keeps committed replay fixtures line-readable while ordinary deployments use the backend's compressed default. Per-event appends are durable, but the harness shuts the subprocess down gracefully (close stdin → `await ctx.dispose()`) before harvesting so the final events are flushed. `llm-replay` itself does no recording — it is replay-only. Replay uses a `cordis.snapshot.yml` overlay that replaces the real adapter with `llm-replay` while retaining the live composition. Recording uses the ordinary config and a harness-supplied persistence root. Replay mode skips `.env` loading, so a stray API key cannot trigger a live call. See the [single-source config Agent Note](2026-07-04-single-source-acp-replay-config.md). diff --git a/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml b/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml index c208a1e553..133198a4d2 100644 --- a/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-18-tui-terminal-state-snapshots.md: 192e872ab63cf4ff8a121ea0a2ee9345379cfa26 -2026-07-18-tui-terminal-state-snapshots.zh.md: 9766a8087632daa1be0dcfb191696dbad354ff68 +2026-07-18-tui-terminal-state-snapshots.md: 8e86588f69fdb9d615232252ecf57309d440f1cd +2026-07-18-tui-terminal-state-snapshots.zh.md: b70a46830f44e9da663e30745fcdb7ad281592da diff --git a/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md b/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md index 192e872ab6..8e86588f69 100644 --- a/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md +++ b/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md @@ -21,7 +21,7 @@ TUI coverage has four complementary layers: 3. `examples/tui-agent/tests/tui.snapshot.ts` replays committed JSONL session logs through the production agent loop and real tools, then compares the resulting semantic terminal state. 4. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots the real Loader composition in a PTY, drives a scripted conversation through streaming and `ask_user_question`, and verifies startup, input, exit, failure reporting, and terminal restoration. -The runnable TUI has its own `examples/tui-agent` leaf beside the readline `repl-agent` and `acp-agent` leaves. It reuses the repl-agent backend and tool composition through an asserted include patch while fixing the shared terminal app to `ui.mode: tui`; TUI snapshots and PTY tests live with that leaf. +The runnable TUI has its own `examples/tui-agent` leaf beside the Headless and ACP leaves. It owns the interactive coding backends and tools directly and loads `@deepseek-ai/dsh-tui-demo`; TUI snapshots and PTY tests live with that leaf. The [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) owns this consolidation. ### Recorded-session replay diff --git a/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md b/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md index 9766a80876..b70a46830f 100644 --- a/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md +++ b/.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.zh.md @@ -21,7 +21,7 @@ TUI 覆盖分为四个互补层次： 3. `examples/tui-agent/tests/tui.snapshot.ts` 通过生产 agent loop 和真实工具回放已提交的 JSONL 会话日志，再比较生成的语义终端状态。 4. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 在 PTY 中启动真实 Loader 组合，驱动一段经过流式输出和 `ask_user_question` 的脚本化会话，并验证启动、输入、退出、失败报告和终端恢复。 -可运行 TUI 在 `examples/tui-agent` 中拥有独立叶节点，与 readline `repl-agent` 和 `acp-agent` 叶节点并列。它通过带断言的 include patch 复用 repl-agent 的后端与工具组合，只把共享终端应用固定为 `ui.mode: tui`；TUI 快照和 PTY 测试也归属这个叶节点。 +可运行 TUI 在 `examples/tui-agent` 中拥有独立叶节点，与 Headless 和 ACP 叶节点并列。它直接拥有交互式 coding 后端与工具，并加载 `@deepseek-ai/dsh-tui-demo`；TUI 快照和 PTY 测试也归属这个叶节点。[移除重复 agent 的决策](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)负责此次整合。 ### 已录制会话回放 diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml index c876ddc68f..f64160a5a0 100644 --- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml +++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-14-sdk-developer-projects.md: 1be9abcad1e51a1b9a1406f21ce60073427576e0 -2026-07-14-sdk-developer-projects.zh.md: a8ba1d658f78484a46a7148a4e2ff1b073a3e9f2 +2026-07-14-sdk-developer-projects.md: aa5cf64d7dd33dea229d74c2ae45a9244ee70e3c +2026-07-14-sdk-developer-projects.zh.md: 8f7d1de5b16f38019c802f07eda701cee72deb4f diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md index 1be9abcad1..aa5cf64d7d 100644 --- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md +++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md @@ -44,7 +44,7 @@ The table is the developer-visible support set for this phase. A `required` feat | Feature | Create state | Feature options | Constraints and relationships | |---|---|---|---| | `provider` | required | `deepseek` (default) / `custom` | DeepSeek collects an API key; custom also collects a base URL, and a CLI option may override the model name | -| `app` | required | `stdio` (default) / `acp` / `embed` | Selects the run interface | +| `app` | required | `tui` (default) / `acp` / `embed` | Selects the run interface | | `spine` | required | `default` | Timer, the LLM seam, session storage, system prompt, the tool registry, the agent registry, and the agent loop | | `bash` | required | `local` (default) / `sandbox` | The two feature options are exclusive and independent of the run interface, and both install the model-facing bash tool; sandbox installs the local sandbox provider and sandboxed bash backend | | `persistence` | required | `jsonl` (default) / `sqlite` | Every project selects exactly one persistence backend | @@ -59,9 +59,9 @@ The table is the developer-visible support set for this phase. A `required` feat | `hooks` | optional | `claude` (default) / `codex`, multiple | Each feature option creates a separate editable configuration file | | `guard` | optional | `repeat-tool` | Provides repeated-tool-call reminders | | `timeout-policy` | optional | `default` | Applies a uniform policy to tools that declare timeout budgets | -| `ask-user` | optional | `default` | Provides the `ask_user_question` tool; only `acp` and `stdio` can select it because those two feature options provide the injected user-interaction service | +| `ask-user` | optional | `default` | Provides the `ask_user_question` tool; only `acp` and `tui` can select it because those two feature options provide the injected user-interaction service | -Both `bash` feature options apply to ACP, stdio, and embed and are not selected by the run interface. The sandbox feature option writes no active config key and therefore keeps `dsh-bash-sandbox`'s `read-only` default. Generated `cordis.yml` includes a commented example that developers can change explicitly to `workspace-write`: +Both `bash` feature options apply to ACP, TUI, and embed and are not selected by the run interface. The sandbox feature option writes no active config key and therefore keeps `dsh-bash-sandbox`'s `read-only` default. Generated `cordis.yml` includes a commented example that developers can change explicitly to `workspace-write`: ```yaml - id: bash @@ -72,11 +72,11 @@ Both `bash` feature options apply to ACP, stdio, and embed and are not selected # workspaceRoot: !!js process.cwd() ``` -Feature contributions reference only single-plugin npm packages and never bundle packages such as `agent-spine-demo`, `stdio-demo`, or `acp-demo`. Plugins outside the table are not managed by create in this phase; advanced developers may still compose them by editing the ordinary project files directly. +Feature contributions reference only single-plugin npm packages and never bundle packages such as `agent-spine-demo`, `tui-demo`, or `acp-demo`. Plugins outside the table are not managed by create in this phase; advanced developers may still compose them by editing the ordinary project files directly. ## Generated project -With default answers, an npm project uses the DeepSeek provider, the stdio interface, local bash, JSONL persistence, and the preselected hmr, fs, todo, and skill features. Its initial tree is: +With default answers, an npm project uses the DeepSeek provider, the TUI interface, local bash, JSONL persistence, and the preselected hmr, fs, todo, and skill features. Its initial tree is: ```text my-agent/ @@ -106,7 +106,7 @@ Generated `package.json` provides the following scripts. `dev`, `build`, `start` `dsh-sdk start` and `dsh-sdk dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`. -- Stdio projects pass the selected model through `--model=` and create or resume an agent according to optional `--resume=`; +- TUI projects pass the selected model through `--model=` and create or resume an agent according to optional `--resume=`; - ACP uses protocol `session/load` - Embed uses the model written into the generated code. diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md index a8ba1d658f..8f7d1de5b1 100644 --- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md +++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md @@ -44,7 +44,7 @@ create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `pl | 功能 | create 状态 | 功能选项 | 限制与关系 | |---|---|---|---| | `provider` | required | `deepseek`（默认）/ `custom` | DeepSeek 收集 API key；custom 另收集 base URL，模型名可由 CLI 参数覆盖 | -| `app` | required | `stdio`（默认）/ `acp` / `embed` | 选择运行接口 | +| `app` | required | `tui`（默认）/ `acp` / `embed` | 选择运行接口 | | `spine` | required | `default` | timer、LLM seam、会话存储、系统提示词、工具注册表、agent 注册表，以及 agent loop | | `bash` | required | `local`（默认）/ `sandbox` | 两个功能选项互斥、与运行接口正交，且都安装面向模型的 bash 工具；sandbox 安装本地沙箱提供方和沙箱 bash 后端 | | `persistence` | required | `jsonl`（默认）/ `sqlite` | 每个工程恰好选择一个持久化后端 | @@ -59,9 +59,9 @@ create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `pl | `hooks` | optional | `claude`（默认）/ `codex`，可多选 | 各功能选项生成独立的可编辑配置文件 | | `guard` | optional | `repeat-tool` | 提供重复工具调用提醒 | | `timeout-policy` | optional | `default` | 对声明超时预算的工具执行统一策略 | -| `ask-user` | optional | `default` | 提供 `ask_user_question` 工具；注入的 user-interaction 服务由 acp/stdio 两个功能选项提供，因此仅这两个接口可选 | +| `ask-user` | optional | `default` | 提供 `ask_user_question` 工具；注入的 user-interaction 服务由 acp/tui 两个功能选项提供，因此仅这两个接口可选 | -`bash` 的两个功能选项都适用于 ACP、stdio 和 embed，不由运行接口决定。sandbox 功能选项不写任何生效的配置键，因而沿用 `dsh-bash-sandbox` 的 `read-only` 默认值；生成的 `cordis.yml` 保留注释示例，开发者可以显式改为 `workspace-write`： +`bash` 的两个功能选项都适用于 ACP、TUI 和 embed，不由运行接口决定。sandbox 功能选项不写任何生效的配置键，因而沿用 `dsh-bash-sandbox` 的 `read-only` 默认值；生成的 `cordis.yml` 保留注释示例，开发者可以显式改为 `workspace-write`： ```yaml - id: bash @@ -72,11 +72,11 @@ create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `pl # workspaceRoot: !!js process.cwd() ``` -功能贡献只引用单插件 NPM 包，绝不引用 `agent-spine-demo`、`stdio-demo`、`acp-demo` 这类组合 NPM 包。表格之外的插件不由本期 create 管理；开发者仍可直接编辑普通工程文件进行高级组合。 +功能贡献只引用单插件 NPM 包，绝不引用 `agent-spine-demo`、`tui-demo`、`acp-demo` 这类组合 NPM 包。表格之外的插件不由本期 create 管理；开发者仍可直接编辑普通工程文件进行高级组合。 ## 生成工程 -使用默认答案创建 npm 工程时，provider 为 DeepSeek，运行接口为 stdio，bash 为 local，持久化为 JSONL，hmr、fs、todo 与 skill 处于选中状态。初始目录树为： +使用默认答案创建 npm 工程时，provider 为 DeepSeek，运行接口为 TUI，bash 为 local，持久化为 JSONL，hmr、fs、todo 与 skill 处于选中状态。初始目录树为： ```text my-agent/ @@ -106,7 +106,7 @@ my-agent/ `dsh-sdk start` 与 `dsh-sdk dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。 -- stdio 工程通过 `--model=` 传入所选 model，并根据可选的 `--resume=` 创建或恢复 agent； +- TUI 工程通过 `--model=` 传入所选 model，并根据可选的 `--resume=` 创建或恢复 agent； - acp 使用协议 `session/load` - embed 使用生成代码中的 model。 diff --git a/.agents/skills/dsh-pre-push-checks/SKILL.md b/.agents/skills/dsh-pre-push-checks/SKILL.md index 5c51209113..a138c5b4b4 100644 --- a/.agents/skills/dsh-pre-push-checks/SKILL.md +++ b/.agents/skills/dsh-pre-push-checks/SKILL.md @@ -5,7 +5,7 @@ description: Use before pushing, force-pushing, marking ready for review, claimi # DSH Pre-Push Checks -Use this skill to choose and run the smallest sufficient verification set before a `deepseek-harness` push. Do not treat the local pre-push hook as the full CI contract: CI also runs coverage, build, demo smoke, and built-bin smoke. +Use this skill to choose and run the smallest sufficient verification set before a `deepseek-harness` push. Do not treat the local pre-push hook as the full CI contract: CI also runs coverage, build, and built-bin smoke. ## First Steps @@ -54,7 +54,7 @@ pnpm run test:snapshot Run built-bin smoke tests after `pnpm run build` when app packages, app boot, package runtime imports, bin entries, loader behavior, or published artifact paths change. ```sh -pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/cli-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts +DSH_EXAMPLE_MODE=lib pnpm exec vitest run --config vitest.e2e.config.ts examples/headless-agent/tests/keyless-smoke.e2e.ts examples/tui-agent/tests/tui-keyless-smoke.e2e.ts packages/examples/cli-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts ``` Run real e2e when behavior depends on a real model/API, tool-use loop, ACP integration, prompt injection, or end-to-end agent UX. If `.env` is available, use it; do not print secrets. diff --git a/AGENTS.md b/AGENTS.md index 24a138e396..860f60f1e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,8 +27,8 @@ packages/ @deepseek-ai/dsh- workspaces at packages/// cordis/ self-referential toolset: the agent inspects/mounts plugins in its own runtime hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends - ui/ ACP/stdio/TUI/JSON-RPC bridges; boot, approval, interaction plugins - examples/ demo bundles (agent-spine + stdio/CLI/ACP/JSON-RPC bins) leaves load + ui/ ACP/TUI/JSON-RPC bridges; boot, approval, interaction plugins + examples/ demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load support/ dev/test infrastructure packages util/ zero-dependency utilities python/ Python SDK and bundled runtime (see python/README.md) @@ -58,9 +58,7 @@ pnpm run build # tsc emits lib/types, tsdown bundles runtime pnpm run hygiene # knip + publint + workspace constraints + NodeNext consumer check pnpm run doc-sync # all documentation gates; see the doc-sync script in package.json pnpm run website:build # VitePress build (doubles as the site's dead-link check) -pnpm run demo:echo # mock-model REPL, no key needed -pnpm run demo:repl # real REPL coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:headless -- "task" # one-shot agent (needs DEEPSEEK_API_KEY) +pnpm run demo:headless "task" # one-shot agent (needs DEEPSEEK_API_KEY) pnpm run demo:tui # full-screen TUI coding agent (needs DEEPSEEK_API_KEY) pnpm run demo:cordis # self-referential demo: the agent modifies its own runtime (needs key) pnpm run demo:acp # ACP server agent (needs DEEPSEEK_API_KEY) @@ -86,12 +84,7 @@ pnpm run website:build pnpm run verify-module-graph pnpm run build pnpm run hygiene -out=$(printf 'echo ci smoke\n' | pnpm run demo:echo 2>&1) -printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})' -printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE' -test -n "$(find .sessions -path '.sessions/cwd-*/main-session-*.jsonl' -type f -print -quit)" -rm -rf .sessions -pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/cli-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts +DSH_EXAMPLE_MODE=lib pnpm exec vitest run --config vitest.e2e.config.ts examples/headless-agent/tests/keyless-smoke.e2e.ts examples/tui-agent/tests/tui-keyless-smoke.e2e.ts packages/examples/cli-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts ``` `test:coverage`, not `test`, is the gate ([why](docs/testing.md)); report only commands actually run. diff --git a/README.i18n.yaml b/README.i18n.yaml index 64e212ff3a..d78213a292 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -README.md: ef9a3a8832d1eaa35ec5f0fed1780ab27e8ff37c -README.zh.md: a30d6db4b04f23559c36a7aba80b4feb2962a1c6 +README.md: 32958db0e74bd14d6d41e8d7886b8d3257fe0f59 +README.zh.md: b28b175a8296347a7bed05b4e53c0d75dc51efed diff --git a/README.md b/README.md index ef9a3a8832..32958db0e7 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,11 @@ This monorepo is built on the [Cordis](https://github.com/cordiverse/cordis) fra ```sh pnpm install pnpm run test # vitest -pnpm run demo:echo # keyless mock-model REPL -pnpm run demo:repl # readline coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:tui # full-screen TUI coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:headless -- "task" # one-shot coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:cordis # self-referential agent demo (needs DEEPSEEK_API_KEY) -pnpm run demo:acp # ACP server agent demo (needs DEEPSEEK_API_KEY) +# Agent demos require DEEPSEEK_API_KEY. +pnpm run demo:tui # full-screen TUI coding agent +pnpm run demo:headless "task" # one-shot coding agent +pnpm run demo:cordis # self-referential agent demo +pnpm run demo:acp # ACP server agent demo ``` For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) and [documentation graph index](docs/graph-atlas.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/). diff --git a/README.zh.md b/README.zh.md index a30d6db4b0..b28b175a82 100644 --- a/README.zh.md +++ b/README.zh.md @@ -11,12 +11,11 @@ ```sh pnpm install pnpm run test # vitest -pnpm run demo:echo # keyless mock-model REPL -pnpm run demo:repl # readline coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:tui # full-screen TUI coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:headless -- "task" # one-shot coding agent (needs DEEPSEEK_API_KEY) -pnpm run demo:cordis # self-referential agent demo (needs DEEPSEEK_API_KEY) -pnpm run demo:acp # ACP server agent demo (needs DEEPSEEK_API_KEY) +# Agent demos require DEEPSEEK_API_KEY. +pnpm run demo:tui # full-screen TUI coding agent +pnpm run demo:headless "task" # one-shot coding agent +pnpm run demo:cordis # self-referential agent demo +pnpm run demo:acp # ACP server agent demo ``` 面向开发者：先读[开发指南](docs/development.md)，了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)和[文档关系图索引](docs/graph-atlas.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。 diff --git a/docs/architecture.md b/docs/architecture.md index f9728afacb..ca02ee567f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -138,7 +138,7 @@ The session log is the source of truth. `deriveMessages()` projects session even **Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` fronted by the header's session prefix, headers by folding `request/header` — and dev invariants assert this ([reconstructability](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)). -Durability is a plugin concern. Persistence backends buffer synchronous `session/event` notifications and the loop awaits a turn-end checkpoint before moving on. The `SessionPersistence` seam stores `SessionEvent` directly, with metadata in `SessionHeader`; JSONL and SQLite share one contract suite. +Durability is a plugin concern. Backends buffer synchronous `session/event` notifications; the loop awaits a turn-end checkpoint. `SessionPersistence` stores `SessionEvent` directly and metadata in `SessionHeader`; JSONL defaults to checksummed Zstandard, with SQLite under one contract. ### Model Content @@ -158,7 +158,7 @@ Exceptions combine layers: LLM interface/consumer; filesystem policy; web regist ### Bundles And Apps -`dsh-agent-spine-demo` bundles the default spine and an opt-in persisted-goal stack ([README](../packages/examples/agent-spine-demo/README.md)). Terminal and ACP apps enable goals plus the shared `/goal` command by default; other apps choose explicitly. `dsh-jsonrpc-agent` boots external `cordis.yml`, including the Python SDK default ([Python SDK](../python/README.md)). Deployments stay thin with swappable backends/tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)). +`dsh-agent-spine-demo` bundles the default spine and an opt-in persisted-goal stack ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-tui-demo` owns the interactive full-screen terminal and enables goals plus `/goal` by default; `dsh-cli-demo` runs one persisted headless turn with format-pure stdout; `dsh-acp-demo` adds stdout-pure ACP over JSON-RPC and enables the same goal and command stack ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies its default only without an explicit config channel and drives `dsh-jsonrpc` over line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)). ### Where New Behavior Goes diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 58eb8b00ef..4b60089577 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -47,14 +47,14 @@ flowchart LR pkg_tool_todo["tool-todo"] pkg_user_interaction["user-interaction"] svc_userInteraction["ctx.userInteraction
Human question/answer seam"] - pkg_stdio_demo["stdio-demo"] + pkg_tui["tui"] pkg_commands["commands"] svc_commands["ctx.commands
Human command registry"] - pkg_tui["tui"] pkg_skill["skill"] svc_skills["ctx.skills
Skill provider registry"] pkg_skill_local["skill-local"] svc_agents["ctx.agents
Agent service"] + pkg_tui_demo["tui-demo"] svc_agentLoop["ctx.agentLoop
Concrete loop driver"] pkg_agent_spine_demo["agent-spine-demo"] pkg_goal["goal"] @@ -141,7 +141,6 @@ flowchart LR pkg_skill_local --> svc_skills pkg_spill --> svc_spillStore pkg_spill_local --> svc_spillStore - pkg_stdio_demo --> svc_userInteraction pkg_subagent --> svc_subagents pkg_subagent_acp --> svc_subagents pkg_subagent_fork --> svc_subagents @@ -151,6 +150,7 @@ flowchart LR pkg_token_meter --> svc_tokenMeter pkg_tool_bash --> svc_bashEnv pkg_tools --> svc_tools + pkg_tui --> svc_userInteraction pkg_user_interaction --> svc_userInteraction pkg_web --> svc_web pkg_web_fetch_local --> svc_web @@ -164,8 +164,8 @@ flowchart LR svc_agents --> pkg_agent_loop svc_agents --> pkg_cli_demo svc_agents --> pkg_invariants - svc_agents --> pkg_stdio_demo svc_agents --> pkg_subagent_inprocess + svc_agents --> pkg_tui_demo svc_approval --> pkg_tool_bash svc_approval --> pkg_tools svc_bash --> pkg_hooks_claude @@ -219,8 +219,8 @@ flowchart LR svc_tools --> pkg_tool_todo svc_tools --> pkg_tool_web svc_userInteraction --> pkg_acp - svc_userInteraction --> pkg_stdio_demo svc_userInteraction --> pkg_tool_ask_user + svc_userInteraction --> pkg_tui svc_web --> pkg_tool_web svc_workflows --> pkg_tool_ralph svc_workflows --> pkg_tool_workflow @@ -237,10 +237,10 @@ flowchart LR | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | - | - | - | Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces. | | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. | | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. | -| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-demo`](../packages/examples/stdio-demo), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-demo`](../packages/examples/stdio-demo), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. | +| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. | | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | Plugins register direct human commands; TUI and ACP consume the same effective per-agent catalog without sending invocations to the model. | | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. | -| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-demo`](../packages/examples/stdio-demo), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. | +| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. | | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index e8167d228f..deb84f7255 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -58,6 +58,8 @@ export interface Config { dshHome?: string /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string + /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */ + persistenceCompression?: JsonlCompression /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */ workspaceContext: agentCore.Config['workspaceContext'] /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */ @@ -71,9 +73,9 @@ export interface Config { } ``` -Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) +Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) -Source: [`packages/examples/acp-demo/src/index.ts:35`](../packages/examples/acp-demo/src/index.ts) +Source: [`packages/examples/acp-demo/src/index.ts:38`](../packages/examples/acp-demo/src/index.ts) ## `@deepseek-ai/dsh-agent-loop` @@ -103,7 +105,7 @@ export interface Config { Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md) -Source: [`packages/core/agent-loop/src/index.ts:369`](../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:360`](../packages/core/agent-loop/src/index.ts) ## `@deepseek-ai/dsh-agent-spine-demo` @@ -237,6 +239,8 @@ export interface Config { dshHome?: string /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string + /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */ + persistenceCompression?: JsonlCompression /** Skill registry, local-provider, and model-facing consumer config. */ skills?: agentCore.SkillConfig /** Model-facing bash tool config forwarded through agent-spine-demo. */ @@ -248,9 +252,9 @@ export interface Config { } ``` -Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) +Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) -Source: [`packages/examples/cli-demo/src/index.ts:22`](../packages/examples/cli-demo/src/index.ts) +Source: [`packages/examples/cli-demo/src/index.ts:25`](../packages/examples/cli-demo/src/index.ts) ## `@deepseek-ai/dsh-code-runtime-worker` @@ -765,10 +769,15 @@ export interface Config { * (bash calls, subprocesses). Sessions group under per-cwd subdirectories. */ root: string + /** Physical encoding; defaults to checksummed Zstandard frames. */ + compression?: JsonlCompression } + +/** Physical encoding selected for JSONL session artifacts. */ +export type JsonlCompression = 'zstd' | 'none' ``` -Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:24`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) +Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:36`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) ## `@deepseek-ai/dsh-session-persistence-sqlite` @@ -887,90 +896,6 @@ export interface Config { Source: [`packages/spill/spill-policy/src/index.ts:45`](../packages/spill/spill-policy/src/index.ts) -## `@deepseek-ai/dsh-stdio` - -Requires: `agents` · `userInteraction` - -```ts config-catalog -/** Serializable plugin configuration (cordis-native, schemastery). */ -export interface Config { - /** Banner printed once on start, before the first `> ` prompt. */ - welcome?: string - /** Exact shared agent/session identity stdin drives. Defaults to `'main'`. */ - sessionId?: string -} -``` - -Source: [`packages/ui/stdio/src/index.ts:33`](../packages/ui/stdio/src/index.ts) - -## `@deepseek-ai/dsh-stdio-demo` - -```ts config-catalog -/** - * App config: the swappable per-demo values, each routed to where the app wires - * it. `provider`/`model`/`resumeSessionId` configure the pre-created `main` agent (through - * {@link @deepseek-ai/dsh-agent-spine-demo}'s forwarded `agents` list); `persona` is - * the deployment persona (forwarded to the system-prompt plugin); `toolOrder` - * is the explicit model-facing tool order (forwarded to the system-prompt plugin); - * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions - * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory; - * `welcome` is the UI banner and `ui` configures terminal mode/presentation. - */ -export interface Config { - /** Provider route for the `main` agent. */ - provider: string - /** Model name for the `main` agent (must have a registered adapter). */ - model: string - /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ - maxParallelToolCalls?: number - /** Deployment persona (the system-prompt plugin's `persona` config). */ - persona?: string - /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ - toolOrder?: string[] - /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */ - tools?: ToolsConfig - /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */ - dshHome?: string - /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ - persistenceRoot?: string - /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */ - welcome?: string - /** Terminal front-door selection and pi-tui presentation settings. */ - ui?: UiConfig - /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */ - skills?: agentCore.SkillConfig - /** Model-facing bash tool config forwarded through agent-core. */ - toolBash?: NonNullable - /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */ - toolTasks?: NonNullable - /** Persisted same-session goals; owner defaults enable them, or false disables the stack and TUI command. */ - goals?: agentCore.GoalConfig | false - /** - * If set, the pre-created agent RESUMES this persisted session id instead of - * starting fresh. Sourced from an env var in the leaf `cordis.yml` - * (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`). - */ - resumeSessionId?: string - /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */ - workspaceContext: agentCore.Config['workspaceContext'] -} - -/** App-level terminal selection with nested TUI presentation settings. */ -export interface UiConfig { - /** Select a concrete front door or infer it from the process streams. */ - mode?: TerminalMode - /** Settings forwarded only when the pi-tui front door is selected. */ - tui?: uiTui.TuiConfig -} - -/** Terminal front door selected by the app bundle. */ -export type TerminalMode = 'auto' | 'readline' | 'tui' -``` - -Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts) - -Source: [`packages/examples/stdio-demo/src/index.ts:77`](../packages/examples/stdio-demo/src/index.ts) - ## `@deepseek-ai/dsh-subagent-acp` Requires: `subagents` @@ -1385,7 +1310,53 @@ export interface TuiConfig { } ``` -Source: [`packages/ui/tui/src/index.ts:101`](../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:102`](../packages/ui/tui/src/index.ts) + +## `@deepseek-ai/dsh-tui-demo` + +```ts config-catalog +/** App config routed to the spine, TUI, configured agent, and JSONL backend. */ +export interface Config { + /** Provider route for the `main` agent. */ + provider: string + /** Model name for the `main` agent; a matching adapter must be registered. */ + model: string + /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ + maxParallelToolCalls?: number + /** Deployment persona forwarded to the system-prompt plugin. */ + persona?: string + /** Explicit model-facing tool order forwarded to the system-prompt plugin. */ + toolOrder?: string[] + /** Tool-registry presentation config forwarded through agent-spine-demo. */ + tools?: ToolsConfig + /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */ + dshHome?: string + /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ + persistenceRoot?: string + /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */ + persistenceCompression?: JsonlCompression + /** TUI subtitle rendered on start. Defaults to `ready.`. */ + welcome?: string + /** Full-screen TUI presentation settings. */ + ui?: uiTui.TuiConfig + /** Skill registry, local-provider, and model-facing consumer config. */ + skills?: agentCore.SkillConfig + /** Model-facing bash tool config forwarded through agent-spine-demo. */ + toolBash?: NonNullable + /** Generic background-task controls forwarded through agent-spine-demo; set false to omit them. */ + toolTasks?: NonNullable + /** Persisted same-session goals; owner defaults enable them, or false disables the stack and command. */ + goals?: agentCore.GoalConfig | false + /** Persisted session id to resume instead of creating a fresh session. */ + resumeSessionId?: string + /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */ + workspaceContext: agentCore.Config['workspaceContext'] +} +``` + +Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts) + +Source: [`packages/examples/tui-demo/src/index.ts:33`](../packages/examples/tui-demo/src/index.ts) ## `@deepseek-ai/dsh-user-approval` diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml index 5bcb3bac1d..070cc45f93 100644 --- a/docs/cookbook/adding-a-tool.i18n.yaml +++ b/docs/cookbook/adding-a-tool.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -adding-a-tool.md: 68a8449bc189497b917efe678837d757f85aaf75 -adding-a-tool.zh.md: 003534e04550bfbee6740aa3b6bee02ac2cdc237 +adding-a-tool.md: a45315dc0ec92ab28963c2aca32dffcf5f778dcd +adding-a-tool.zh.md: f574957ddd0e42cedc93ddc0f3270110a8f110c5 diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md index 68a8449bc1..a45315dc0e 100644 --- a/docs/cookbook/adding-a-tool.md +++ b/docs/cookbook/adding-a-tool.md @@ -2,7 +2,7 @@ English | [中文](adding-a-tool.zh.md) -How to give the model a new capability. Reference implementations: `examples/echo-agent/src/echo-tool.ts` (minimal) and `packages/bash/tool-bash` (production-grade, three-package seam). +How to give the model a new capability. The minimal shape below shows the contract; `packages/bash/tool-bash` is the production-grade three-package seam. ## The minimal shape diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md index 003534e045..f574957ddd 100644 --- a/docs/cookbook/adding-a-tool.zh.md +++ b/docs/cookbook/adding-a-tool.zh.md @@ -2,7 +2,7 @@ [English](adding-a-tool.md) | 中文 -如何为模型赋予一项新能力。参考实现：`examples/echo-agent/src/echo-tool.ts`（最小化）和 `packages/bash/tool-bash`（生产级，由三个包（package）构成的 seam）。 +如何为模型赋予一项新能力。下文的最小形态展示这项契约；`packages/bash/tool-bash` 是生产级、由三个包（package）构成的 seam。 ## 最小形态 diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml index cb211c881a..17b2346249 100644 --- a/docs/cookbook/extension-cookbook.i18n.yaml +++ b/docs/cookbook/extension-cookbook.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -extension-cookbook.md: 37e994844030620349ff3f4d989680fbe18daa88 -extension-cookbook.zh.md: e2304f84797e6111ebc28f97dbc5f2d15dc087b0 +extension-cookbook.md: a1f6d2f0d27b2258ae06236721bbd80cbd3af80e +extension-cookbook.zh.md: f7729492b68bfef50d5e289581028d0c0c4164cf diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md index 37e9948440..a1f6d2f0d2 100644 --- a/docs/cookbook/extension-cookbook.md +++ b/docs/cookbook/extension-cookbook.md @@ -87,7 +87,7 @@ export function apply(ctx: Context) { ## Runnable wirings -Six runnable leaves load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool, `pnpm run demo:echo`), [`examples/repl-agent`](../../examples/repl-agent) (DeepSeek V4 + coding tools through a line-oriented readline REPL, `pnpm run demo:repl`), [`examples/tui-agent`](../../examples/tui-agent) (the same coding composition through full-screen pi-tui, `pnpm run demo:tui`), [`examples/headless-agent`](../../examples/headless-agent) (the same capability class behind a one-shot task and DSH-native output, `pnpm run demo:headless -- "task"`), [`examples/cordis-agent`](../../examples/cordis-agent) (self-inspection and dynamic plugin mounting, `pnpm run demo:cordis`), and [`examples/acp-agent`](../../examples/acp-agent) (an ACP server over JSON-RPC stdio, `pnpm run demo:acp`). The terminal leaves load [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo), the headless leaf loads [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo), the ACP leaf loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and all three app packages share [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo). +Four runnable leaves load their plugin trees from `cordis.yml`: [`examples/tui-agent`](../../examples/tui-agent) (DeepSeek coding tools through the full-screen TUI, `pnpm run demo:tui`), [`examples/headless-agent`](../../examples/headless-agent) (the coding capabilities behind a one-shot task and DSH-native output, `pnpm run demo:headless "task"`), [`examples/cordis-agent`](../../examples/cordis-agent) (self-inspection and dynamic plugin mounting through the TUI, `pnpm run demo:cordis`), and [`examples/acp-agent`](../../examples/acp-agent) (an ACP server over JSON-RPC stdio, `pnpm run demo:acp`). Interactive leaves load [`@deepseek-ai/dsh-tui-demo`](../../packages/examples/tui-demo), non-interactive leaves load [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo), the ACP leaf loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and all three app packages share [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo). ## The feature → mechanism map diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md index e2304f8479..f7729492b6 100644 --- a/docs/cookbook/extension-cookbook.zh.md +++ b/docs/cookbook/extension-cookbook.zh.md @@ -87,7 +87,7 @@ export function apply(ctx: Context) { ## 可运行的组装示例 -六个可运行叶子从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具，`pnpm run demo:echo`）、[`examples/repl-agent`](../../examples/repl-agent)（DeepSeek V4 + coding 工具，通过面向行的 readline REPL 交互，`pnpm run demo:repl`）、[`examples/tui-agent`](../../examples/tui-agent)（通过全屏 pi-tui 复用相同的 coding 组装，`pnpm run demo:tui`）、[`examples/headless-agent`](../../examples/headless-agent)（同类能力通过单次任务和 DSH 原生输出运行，`pnpm run demo:headless -- "task"`）、[`examples/cordis-agent`](../../examples/cordis-agent)（自我检查和动态插件挂载，`pnpm run demo:cordis`）与 [`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露的 ACP 服务器，`pnpm run demo:acp`）。终端叶子加载 [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo)，headless 叶子加载 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo)，ACP 叶子加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，三个 app 包都通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) 共享主干。 +四个可运行叶子从 `cordis.yml` 加载各自的插件树：[`examples/tui-agent`](../../examples/tui-agent)（通过全屏 TUI 运行的 DeepSeek coding 工具，`pnpm run demo:tui`）、[`examples/headless-agent`](../../examples/headless-agent)（通过单次任务和 DSH 原生输出运行的 coding 能力，`pnpm run demo:headless "task"`）、[`examples/cordis-agent`](../../examples/cordis-agent)（通过 TUI 进行自我检查和动态插件挂载，`pnpm run demo:cordis`）与 [`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露的 ACP 服务器，`pnpm run demo:acp`）。交互式叶子加载 [`@deepseek-ai/dsh-tui-demo`](../../packages/examples/tui-demo)，非交互式叶子加载 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo)，ACP 叶子加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，三个 app 包都通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) 共享主干。 ## 功能→机制映射 diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 1fdd1dfe9f..794130c9aa 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -387,7 +387,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers Types: [SessionId](../core-data-structures/core.md) -Source: [`packages/core/agent-loop/src/index.ts:362`](../../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:353`](../../packages/core/agent-loop/src/index.ts) ## `approval/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 89a94d72a0..fc4a4c1fa5 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -44,7 +44,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise pkg_scope pkg_jsonrpc --> pkg_session pkg_jsonrpc --> pkg_subagent - pkg_stdio --> pkg_agent - pkg_stdio --> pkg_agent_loop - pkg_stdio --> pkg_llm - pkg_stdio --> pkg_session - pkg_stdio --> pkg_user_interaction pkg_tui --> pkg_agent pkg_tui --> pkg_agent_loop pkg_tui --> pkg_commands @@ -489,21 +483,20 @@ flowchart TD pkg_cli_demo --> pkg_session_persistence_jsonl pkg_cli_demo --> pkg_tools pkg_cli_demo --> pkg_workspace_context - pkg_stdio_demo --> pkg_agent - pkg_stdio_demo --> pkg_agent_loop - pkg_stdio_demo --> pkg_agent_spine_demo - pkg_stdio_demo --> pkg_app_boot - pkg_stdio_demo --> pkg_command_goal - pkg_stdio_demo --> pkg_commands - pkg_stdio_demo --> pkg_llm - pkg_stdio_demo --> pkg_session - pkg_stdio_demo --> pkg_session_persistence_jsonl - pkg_stdio_demo --> pkg_stdio - pkg_stdio_demo --> pkg_tool_ask_user - pkg_stdio_demo --> pkg_tools - pkg_stdio_demo --> pkg_tui - pkg_stdio_demo --> pkg_user_interaction - pkg_stdio_demo --> pkg_workspace_context + pkg_tui_demo --> pkg_agent + pkg_tui_demo --> pkg_agent_loop + pkg_tui_demo --> pkg_agent_spine_demo + pkg_tui_demo --> pkg_app_boot + pkg_tui_demo --> pkg_command_goal + pkg_tui_demo --> pkg_commands + pkg_tui_demo --> pkg_llm + pkg_tui_demo --> pkg_session + pkg_tui_demo --> pkg_session_persistence_jsonl + pkg_tui_demo --> pkg_tool_ask_user + pkg_tui_demo --> pkg_tools + pkg_tui_demo --> pkg_tui + pkg_tui_demo --> pkg_user_interaction + pkg_tui_demo --> pkg_workspace_context ``` | Package | Group | Depends on | @@ -597,7 +590,6 @@ flowchart TD | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) | | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | -| [`stdio`](../packages/ui/stdio) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`user-interaction`](../packages/ui/user-interaction) | | [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | @@ -606,4 +598,4 @@ flowchart TD | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) | | [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) | -| [`stdio-demo`](../packages/examples/stdio-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`stdio`](../packages/ui/stdio), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) | +| [`tui-demo`](../packages/examples/tui-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) | diff --git a/docs/postmortem/0001-acp-default-export-drops-inject.md b/docs/postmortem/0001-acp-default-export-drops-inject.md index e024f4d698..10e88c390c 100644 --- a/docs/postmortem/0001-acp-default-export-drops-inject.md +++ b/docs/postmortem/0001-acp-default-export-drops-inject.md @@ -24,7 +24,7 @@ The ACP server could not create or load a single session — the two RPCs an edi ## Root cause #1 — `export default apply` drops the plugin's `inject` (broke `session/new`) -`packages/ui/acp/src/index.ts` is a *namespace plugin*: it exports `name`, `inject`, `Config`, and `apply` as separate named exports — the same shape as every other plugin in the repo (`invariants`, `llm-deepseek`, `tool-bash`, `stdio-chat`, …). But it *also* ended with one extra line no other plugin had: +`packages/ui/acp/src/index.ts` is a *namespace plugin*: it exports `name`, `inject`, `Config`, and `apply` as separate named exports — the same shape as every other plugin in the repo (`invariants`, `llm-deepseek`, `tool-bash`, `tui`, …). But it *also* ended with one extra line no other plugin had: ```ts ignore-check export const name = 'acp' diff --git a/docs/testing.md b/docs/testing.md index 84629aae45..19cd60ebdb 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -11,7 +11,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning ## The with-key policy: inference is cheap here -We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Write many: file-writing prompts, multi-turn conversations, tool use, cancellation mid-stream. Highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal. Every example ships a keyless smoke and — unless keyless-by-nature — a with-key smoke ([examples/AGENTS.md](../examples/AGENTS.md)). +We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Write many: file-writing prompts, multi-turn conversations, tool use, cancellation mid-stream. Highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal. Every example ships both a keyless smoke and a with-key smoke ([examples/AGENTS.md](../examples/AGENTS.md)). ## Prefer the real implementation over a mock diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 782fc27189..6196a71521 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -24,7 +24,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `context/message goal snapshot for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. | | `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`, `ctx.workflows`, `ctx.subagents`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents every fresh round)` | `tool/call`, `tool/result`, `workflow and child session events during execution` | - | A fixed foreground workflow starts one fresh structured child per round; the model selects only the immutable objective and an optional round cap. | | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - | -| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/repl-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | +| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/tui-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | | `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflows`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - | @@ -571,7 +571,7 @@ Delegate a self-contained task to a subagent (a separate agent that works in its Source: [`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/tool-subagent/src/index.ts) -The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/repl-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. +The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/tui-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. ## `@deepseek-ai/dsh-tool-tasks` diff --git a/docs/user/develop/basic/index.i18n.yaml b/docs/user/develop/basic/index.i18n.yaml index 22b03af93e..711715a5de 100644 --- a/docs/user/develop/basic/index.i18n.yaml +++ b/docs/user/develop/basic/index.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -index.md: 5fa46806bc195ad2566fc0a29b45eb1dd7a68179 -index.zh.md: a6d238c12841c8c25b00376ee032e5db50fc6b4e +index.md: d7d657ff7b8cb9001dd5e9c3af658a7a3c45b5b7 +index.zh.md: 7a134f7aaed470b87ee8ca8978dd39593de2651b diff --git a/docs/user/develop/basic/index.md b/docs/user/develop/basic/index.md index 5fa46806bc..d7d657ff7b 100644 --- a/docs/user/develop/basic/index.md +++ b/docs/user/develop/basic/index.md @@ -122,24 +122,24 @@ Function form is sufficient in most cases. Use class form when the plugin provid ## Complete example -`examples/echo-agent/src/echo-tool.ts` is a plugin that registers a tool: +A minimal tool plugin registers its definition on `ctx.tools`: ```ts import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' -export const name = 'echo-tool' +export const name = 'greet-tool' export const inject = ['tools'] export function apply(ctx: Context) { ctx.tools.register(defineTool({ - name: 'echo', - description: 'Echo the given text back, uppercased.', + name: 'greet', + description: 'Greet the named person.', parameters: { - text: { type: 'string', required: true }, + name: { type: 'string', required: true }, }, async execute(args) { - return [{ type: 'text', text: `ECHO: ${args.text.toUpperCase()}` }] + return [{ type: 'text', text: `Hello, ${args.name}!` }] }, })) } diff --git a/docs/user/develop/basic/index.zh.md b/docs/user/develop/basic/index.zh.md index a6d238c128..7a134f7aae 100644 --- a/docs/user/develop/basic/index.zh.md +++ b/docs/user/develop/basic/index.zh.md @@ -122,24 +122,24 @@ export default class MyService extends Service { ## 完整示例 -参考仓库中的 `examples/echo-agent/src/echo-tool.ts`，这是一个注册 tool 的插件： +最小化的工具插件会在 `ctx.tools` 上注册其定义： ```ts import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' -export const name = 'echo-tool' +export const name = 'greet-tool' export const inject = ['tools'] export function apply(ctx: Context) { ctx.tools.register(defineTool({ - name: 'echo', - description: 'Echo the given text back, uppercased.', + name: 'greet', + description: 'Greet the named person.', parameters: { - text: { type: 'string', required: true }, + name: { type: 'string', required: true }, }, async execute(args) { - return [{ type: 'text', text: `ECHO: ${args.text.toUpperCase()}` }] + return [{ type: 'text', text: `Hello, ${args.name}!` }] }, })) } diff --git a/docs/user/develop/practice/llm-adapter.i18n.yaml b/docs/user/develop/practice/llm-adapter.i18n.yaml index 30805c97b4..8735e8d5a6 100644 --- a/docs/user/develop/practice/llm-adapter.i18n.yaml +++ b/docs/user/develop/practice/llm-adapter.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -llm-adapter.md: f34fc9e1d5b59a323bb562764821ef910025880e -llm-adapter.zh.md: 3c781ae8a1a011e2f73d5f6de43f6f75e1fb549f +llm-adapter.md: 3e83289b8072ef231f83c0fa3cfe3260547b42fa +llm-adapter.zh.md: 92fcf9b22f4bb356ada4c46f9a03ef0cc2d159da diff --git a/docs/user/develop/practice/llm-adapter.md b/docs/user/develop/practice/llm-adapter.md index f34fc9e1d5..3e83289b80 100644 --- a/docs/user/develop/practice/llm-adapter.md +++ b/docs/user/develop/practice/llm-adapter.md @@ -131,10 +131,12 @@ The first argument lists the model names handled by the adapter. If `cordis.yml` - my-model-v1 - my-model-v2 -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: + provider: my-llm model: my-model-v1 # References the model registered above. + workspaceContext: false ``` ## Reference implementations @@ -143,9 +145,8 @@ The repository contains complete implementations: - `packages/llm/llm-deepseek/` — DeepSeek API adapter using the OpenAI-compatible format - `packages/llm/llm-pi-ai/` — Pi AI adapter using a different API format -- `examples/echo-agent/src/mock-llm.ts` — minimal local teaching adapter -Start with the mock adapter to study a complete chunk sequence without network behavior. +Compare the two shipped adapters to see the same harness contract implemented over different provider SDKs. ## Error handling diff --git a/docs/user/develop/practice/llm-adapter.zh.md b/docs/user/develop/practice/llm-adapter.zh.md index 3c781ae8a1..92fcf9b22f 100644 --- a/docs/user/develop/practice/llm-adapter.zh.md +++ b/docs/user/develop/practice/llm-adapter.zh.md @@ -131,10 +131,12 @@ ctx.llm.registerAdapter(['model-name-1', 'model-name-2'], adapter) - my-model-v1 - my-model-v2 -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: + provider: my-llm model: my-model-v1 # References the model registered above. + workspaceContext: false ``` ## 实战参考 @@ -143,9 +145,8 @@ ctx.llm.registerAdapter(['model-name-1', 'model-name-2'], adapter) - `packages/llm/llm-deepseek/` — DeepSeek API 适配器（OpenAI 兼容格式） - `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式） -- `examples/echo-agent/src/mock-llm.ts` — 最简 mock 适配器（教学用） -mock 适配器是学习 StreamChunk 协议的最佳起点——它用纯本地逻辑演示了完整的 chunk 序列。 +对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。 ## 错误处理 diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml index 9894ca95bc..cf2658bf4d 100644 --- a/docs/user/guide/config.i18n.yaml +++ b/docs/user/guide/config.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -config.md: a3f56018fd43cc803c1710f97c29a77340a0b257 -config.zh.md: af661b9d7ef72e4085551202169e975bd0c3ec99 +config.md: 8958729d04224215ca420c3103d253a8a5783405 +config.zh.md: 530f2b335453d5064acdac28a60d7df51cd915f0 diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md index a3f56018fd..8958729d04 100644 --- a/docs/user/guide/config.md +++ b/docs/user/guide/config.md @@ -8,8 +8,8 @@ Harness uses `cordis.yml` to describe which plugins an agent loads and the confi The repository examples are runnable configurations and the most reliable starting points for a new project: -- [echo-agent](../../../examples/echo-agent/cordis.yml) uses a local mock model and needs no API key. -- [repl-agent](../../../examples/repl-agent/cordis.yml) combines the DeepSeek model, Bash, filesystem, compaction, subagents, and workflows. +- [tui-agent](../../../examples/tui-agent/cordis.yml) combines the DeepSeek model, Bash, filesystem, compaction, subagents, workflows, and the interactive TUI. +- [headless-agent](../../../examples/headless-agent/cordis.yml) exposes the coding composition as a one-shot task. - [acp-agent](../../../examples/acp-agent/cordis.yml) connects to editor clients over ACP. A minimal configuration is a list of plugin entries: @@ -22,10 +22,15 @@ A minimal configuration is a list of plugin entries: models: - deepseek-v4-flash -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: bash + name: '@deepseek-ai/dsh-bash-local' + +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: + provider: deepseek model: deepseek-v4-flash + workspaceContext: false ``` ## Plugin entries diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md index af661b9d7e..530f2b3354 100644 --- a/docs/user/guide/config.zh.md +++ b/docs/user/guide/config.zh.md @@ -8,8 +8,8 @@ Harness 使用 `cordis.yml` 描述 Agent 加载哪些插件以及每个插件的 仓库中的示例就是可以运行的配置，也是新项目最可靠的起点： -- [echo-agent](../../../examples/echo-agent/cordis.yml) 使用本地 mock 模型，不需要 API key。 -- [repl-agent](../../../examples/repl-agent/cordis.yml) 组合 DeepSeek 模型、Bash、文件系统、压缩、子代理和工作流。 +- [tui-agent](../../../examples/tui-agent/cordis.yml) 组合 DeepSeek 模型、Bash、文件系统、压缩、子代理、工作流和交互式 TUI。 +- [headless-agent](../../../examples/headless-agent/cordis.yml) 以单次任务形式暴露 coding 组装。 - [acp-agent](../../../examples/acp-agent/cordis.yml) 通过 ACP 接入编辑器客户端。 最小配置由一组插件条目组成： @@ -22,10 +22,15 @@ Harness 使用 `cordis.yml` 描述 Agent 加载哪些插件以及每个插件的 models: - deepseek-v4-flash -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: bash + name: '@deepseek-ai/dsh-bash-local' + +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: + provider: deepseek model: deepseek-v4-flash + workspaceContext: false ``` ## 插件条目 diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml index 6743abcdd4..e2b307201e 100644 --- a/docs/user/guide/index.i18n.yaml +++ b/docs/user/guide/index.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -index.md: a20b1041e13b01b6b1d01a5baa8975d3e68c6aa0 -index.zh.md: 56ec50352218e2e28ad2dd7a6ef387376de75606 +index.md: b698b8aeee6cebff374e20ca0f76ddc9e75213c0 +index.zh.md: 337d246baa12ccf6d7a9656d1ea3b06002554c13 diff --git a/docs/user/guide/index.md b/docs/user/guide/index.md index a20b1041e1..b698b8aeee 100644 --- a/docs/user/guide/index.md +++ b/docs/user/guide/index.md @@ -14,10 +14,12 @@ Harness implements every capability an AI agent needs—including LLM calls, too config: apiKey: !!js process.env.DEEPSEEK_API_KEY -# Select the application template -- name: '@deepseek-ai/dsh-stdio-demo' +# Select the interactive application +- name: '@deepseek-ai/dsh-tui-demo' config: + provider: deepseek model: deepseek-v4-flash + workspaceContext: false ``` ## Who it is for diff --git a/docs/user/guide/index.zh.md b/docs/user/guide/index.zh.md index 56ec503522..337d246baa 100644 --- a/docs/user/guide/index.zh.md +++ b/docs/user/guide/index.zh.md @@ -14,10 +14,12 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调 config: apiKey: !!js process.env.DEEPSEEK_API_KEY -# Select the application template -- name: '@deepseek-ai/dsh-stdio-demo' +# Select the interactive application +- name: '@deepseek-ai/dsh-tui-demo' config: + provider: deepseek model: deepseek-v4-flash + workspaceContext: false ``` ## 适合谁 diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml index a4898be8e0..b3de74949b 100644 --- a/docs/user/guide/quickstart.i18n.yaml +++ b/docs/user/guide/quickstart.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -quickstart.md: acae2ac095e057971043c2bcece7a52d3ebc1c2c -quickstart.zh.md: 54643fe54e62dbbd3696362cb43ff8569577c53b +quickstart.md: 25ce51ee3d010d2eb800071b9697fc62857dace1 +quickstart.zh.md: e2e023670a999566e273d8893c42103dc273e7b1 diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md index acae2ac095..25ce51ee3d 100644 --- a/docs/user/guide/quickstart.md +++ b/docs/user/guide/quickstart.md @@ -7,91 +7,52 @@ This guide gets an agent running in five minutes. ## Prerequisites - [Node.js](https://nodejs.org/) ^22.19 or >= 24 -- [pnpm](https://pnpm.io/) 11 (use Corepack to select the repository-pinned version) +- [pnpm](https://pnpm.io/) 11 through Corepack +- A [DeepSeek Platform](https://platform.deepseek.com/) API key ```sh -# Check versions -node -v # v22.19.x, or v24.x and newer +node -v corepack enable -pnpm -v # 11.x +pnpm -v ``` -## Step 1: run echo-agent - -echo-agent needs no API key and runs after dependencies are installed. +## Step 1: install and configure the API key ```sh -# Clone the repository git clone https://github.com/deepseek-harness/deepseek-harness.git cd deepseek-harness - -# Install dependencies pnpm install - -# Start echo-agent -pnpm run demo:echo ``` -The process prints: - -``` -echo-agent ready. Type a message ("echo " triggers the tool). -> -``` - -Enter: - -``` -> echo hello world -``` - -The model issues a tool call, and the echo tool returns the text in uppercase: - -``` -[tool call] echo({"text":"hello world"}) -[tool result] ECHO: HELLO WORLD -``` - -Your local environment is ready. - -## Step 2: use a real model - -Next, connect a real DeepSeek model and run the complete command-line agent. - -### Get an API key - -Get an API key from [DeepSeek Platform](https://platform.deepseek.com/). - -### Configure the environment - -Create a gitignored `.env` file in the repository root: +Create the gitignored repository-root `.env`: ```sh DEEPSEEK_API_KEY=sk-your-key-here ``` -### Start repl-agent +## Step 2: run one Headless task + +Run a non-interactive task and print its final answer: ```sh -pnpm run demo:repl +pnpm run demo:headless "summarize the architecture of this workspace" ``` -``` -agent REPL ready. Give it a coding task. -> +Headless runs one complete model/tool turn, persists the session, prints the result, and exits. Use `--output-format stream-json` when you need the canonical event stream. + +## Step 3: use the TUI + +Start the interactive coding agent: + +```sh +pnpm run demo:tui ``` -This is a complete coding assistant that can read and write files, run commands, and delegate subtasks. - -Try a task: - -``` -> Create hello.js in the current directory, print "Hello from Harness!", and run it -``` +The full-screen agent can read and write files, run commands, delegate subtasks, and track a plan. Try: `Create hello.js in the current directory, print "Hello from Harness!", and run it`. ## What happened -echo-agent and repl-agent use the same application framework (`@deepseek-ai/dsh-stdio-demo`). Their `cordis.yml` files select different plugins and configuration. Custom agents use the same composition model. +headless-agent uses the `@deepseek-ai/dsh-cli-demo` app; tui-agent uses the interactive `@deepseek-ai/dsh-tui-demo` app. Both load the same providerless agent spine, while their `cordis.yml` files select the DeepSeek model and capability plugins appropriate to each surface. ## Next steps diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md index 54643fe54e..e2e023670a 100644 --- a/docs/user/guide/quickstart.zh.md +++ b/docs/user/guide/quickstart.zh.md @@ -7,93 +7,54 @@ ## 环境准备 - [Node.js](https://nodejs.org/) ^22.19 或 >= 24 -- [pnpm](https://pnpm.io/) 11（建议通过 Corepack 使用仓库固定的版本） +- 通过 Corepack 使用 [pnpm](https://pnpm.io/) 11 +- [DeepSeek Platform](https://platform.deepseek.com/) API key ```sh -# Check versions -node -v # v22.19.x, or v24.x and newer +node -v corepack enable -pnpm -v # 11.x +pnpm -v ``` -## 第一步：运行 echo-agent - -echo-agent 不需要 API key，装好依赖就能跑。 +## 第一步：安装并配置 API key ```sh -# Clone the repository git clone https://github.com/deepseek-harness/deepseek-harness.git cd deepseek-harness - -# Install dependencies pnpm install - -# Start echo-agent -pnpm run demo:echo ``` -启动后你会看到： - -``` -echo-agent ready. Type a message ("echo " triggers the tool). -> -``` - -试着输入： - -``` -> echo hello world -``` - -你会看到模型发起了一次 tool call（工具调用），echo 工具将文本转为大写并返回： - -``` -[tool call] echo({"text":"hello world"}) -[tool result] ECHO: HELLO WORLD -``` - -恭喜！环境没问题。 - -## 第二步：使用真实模型调用 - -接下来接入真实的 DeepSeek 模型，跑一个完整的命令行 Agent。 - -### 获取 API Key - -前往 [DeepSeek Platform](https://platform.deepseek.com/) 获取你的 API key。 - -### 配置环境变量 - -在仓库根目录创建 `.env` 文件（已被 gitignore）： +在仓库根目录创建已被 Git 忽略的 `.env`： ```sh DEEPSEEK_API_KEY=sk-your-key-here ``` -### 启动 repl-agent +## 第二步：运行一个 Headless 任务 + +运行一个非交互式任务并打印最终回答： ```sh -pnpm run demo:repl +pnpm run demo:headless "summarize the architecture of this workspace" ``` -``` -agent REPL ready. Give it a coding task. -> +Headless 运行一个完整的模型/工具轮次，持久化会话，打印结果后退出。需要规范事件流时可使用 `--output-format stream-json`。 + +## 第三步：使用 TUI + +启动交互式 coding agent： + +```sh +pnpm run demo:tui ``` -这就是一个完整的编程助手，它能读写文件、跑命令、拆分子任务。 - -试着给它一个任务： - -``` -> Create hello.js in the current directory, print "Hello from Harness!", and run it -``` +这个全屏 Agent 可以读写文件、运行命令、分配子任务和跟踪计划。可以尝试：`Create hello.js in the current directory, print "Hello from Harness!", and run it`。 ## 回头看 -echo-agent 和 repl-agent 用的是同一个应用框架(`@deepseek-ai/dsh-stdio-demo`)，区别只在 `cordis.yml`——换了哪些插件、填了什么配置。你以后定制自己的 Agent 也是同样的方式。 +headless-agent 使用 `@deepseek-ai/dsh-cli-demo` app，tui-agent 使用交互式 `@deepseek-ai/dsh-tui-demo` app。二者加载同一个 providerless agent spine，并通过各自的 `cordis.yml` 为对应 surface 选择 DeepSeek 模型和能力插件。 ## 下一步 -- [配置文件](./config.md) — 了解 `cordis.yml` 的完整语法 -- [开发插件](../develop/basic/) — 编写你自己的 tool 或后端 +- [配置文件](./config.md) — 了解 `cordis.yml` 的格式 +- [开发插件](../develop/basic/) — 编写自己的 tool 或后端 diff --git a/examples/AGENTS.md b/examples/AGENTS.md index 6b820368e4..a1f87ac8fb 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -11,9 +11,7 @@ Each example has both: - **Keyless:** boot the real `cordis.yml` through the Loader, drive it, and assert output and clean exit. Catches Loader/export-shape failures hand-mounted tests miss ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)). - **With-key:** send a live-model prompt and verify external state, not the model's claim. Self-skip without `DEEPSEEK_API_KEY`; see [testing.md](../docs/testing.md). -Mock-only examples require only the keyless tier; state that exception in the test. - -Keyless stdio smokes use `@deepseek-ai/dsh-loader-smoke`; tests supply paths, environment, input, and assertions. Every checked-in test Cordis config lives under its corresponding `examples//` leaf. Map a package-owned config to `examples//tests/fixtures///cordis.yml`, keep its driver and assertions package-local, and declare every package it names in both root `tsconfig.json` references and `examples/package.json`. +Keyless process smokes use `@deepseek-ai/dsh-loader-smoke` for Loader launch resolution; terminal tests wrap that launch in a pseudo-terminal. Tests supply paths, environment, input, and assertions. Every checked-in test Cordis config lives under its corresponding `examples//` leaf. Map a package-owned config to `examples//tests/fixtures///cordis.yml`, keep its driver and assertions package-local, and declare every package it names in both root `tsconfig.json` references and `examples/package.json`. Do not inventory example tests here; the `tests/` trees and root scripts are authoritative. diff --git a/examples/README.md b/examples/README.md index 6524a36f7f..8578c5c25a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,37 +1,18 @@ # Examples -Runnable demos (not workspaces) that showcase how the harness is wired. Each example is a **thin leaf**: a `cordis.yml` that picks the swappable backends (an LLM adapter, a bash executor), loads one app package, and may add optional product tools or demo-only mocks. The composition — the spine, the front-door cluster, and the boot glue — lives in the app packages ([`@deepseek-ai/dsh-stdio-demo`](../packages/examples/stdio-demo), [`@deepseek-ai/dsh-cli-demo`](../packages/examples/cli-demo), [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo)) and the [`@deepseek-ai/dsh-agent-spine-demo`](../packages/examples/agent-spine-demo) bundle they share. There is no `start.ts`; the `demo:*` scripts invoke each app package's `bin`. - -## echo-agent - -A mock model + echo tool on the stdio chat app — the all-mock skeleton. The leaf swaps `dsh-stdio-demo`'s LLM backend to a local `mock-echo` adapter and adds a local `echo` tool. Demonstrates: - -- A thin leaf `cordis.yml` loading the `@deepseek-ai/dsh-stdio-demo` app -- Registering a mock `LlmAdapter` (streaming scripted responses) -- Registering a tool via `ctx.tools.register()` -- "Swap the backend, keep the app" — the only difference from `repl-agent` is the adapter - -Run with: `pnpm run demo:echo`. When prompted, type "echo " to trigger a tool call round-trip. - -## repl-agent - -A coding agent with DeepSeek V4, the `read`/`write`/`edit` filesystem tools, the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the `@deepseek-ai/dsh-stdio-demo` app's readline front door. - -Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [repl-agent/README.md](repl-agent/README.md) for details. - -Run the Code Mode overlay with `pnpm run demo:code-mode`, or pass `acp` for the ACP example. See the [Code Mode example](repl-agent/README.md#code-mode) for its composition and a sample task. +Runnable demos (not workspaces) that showcase how the harness is wired. Each example is a **thin leaf**: a `cordis.yml` that picks swappable backends, loads one app package, and may add optional product tools. The composition and boot glue live in [`@deepseek-ai/dsh-tui-demo`](../packages/examples/tui-demo), [`@deepseek-ai/dsh-cli-demo`](../packages/examples/cli-demo), [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo), and their shared [`@deepseek-ai/dsh-agent-spine-demo`](../packages/examples/agent-spine-demo) bundle. There is no `start.ts`; the `demo:*` scripts invoke each app package's bin. ## headless-agent A non-interactive agent demo that accepts one positional task, runs one complete model/tool turn on the `@deepseek-ai/dsh-cli-demo` app, persists a fresh session, prints `text`, `json`, or `stream-json`, and exits. -Run with: `pnpm run demo:headless -- "task"` (needs `DEEPSEEK_API_KEY`). See [headless-agent/README.md](headless-agent/README.md) for the output contract, safety boundaries, and snapshot suite. +Run with: `pnpm run demo:headless "task"` (needs `DEEPSEEK_API_KEY`). See [headless-agent/README.md](headless-agent/README.md) for the output contract, safety boundaries, and snapshot suite. ## tui-agent -The full-screen terminal sibling of `repl-agent`: it reuses the same coding backends and tools while forcing the shared terminal app to `dsh-tui`. It is the home of TUI PTY and snapshot scenarios. +The interactive coding agent: DeepSeek V4, filesystem and bash tools, subagents, workflows, `todo_write`, compaction, and the full-screen TUI. It is also the home of TUI PTY and snapshot scenarios. -Run with: `pnpm run demo:tui` (needs `DEEPSEEK_API_KEY`). See [tui-agent/README.md](tui-agent/README.md) for controls and composition. +Run with: `pnpm run demo:tui` (needs `DEEPSEEK_API_KEY`). Run its Code Mode overlay with `pnpm run demo:code-mode`. See [tui-agent/README.md](tui-agent/README.md) for controls and composition. ## jsonrpc-agent diff --git a/examples/acp-agent/advanced.cordis.snapshot.yml b/examples/acp-agent/advanced.cordis.snapshot.yml index 97ae72d222..fb1050a259 100644 --- a/examples/acp-agent/advanced.cordis.snapshot.yml +++ b/examples/acp-agent/advanced.cordis.snapshot.yml @@ -13,6 +13,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: 'none' workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/advanced.cordis.yml b/examples/acp-agent/advanced.cordis.yml index fee31ebc0d..2765b384fe 100644 --- a/examples/acp-agent/advanced.cordis.yml +++ b/examples/acp-agent/advanced.cordis.yml @@ -11,6 +11,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/both-mode.cordis.snapshot.yml b/examples/acp-agent/both-mode.cordis.snapshot.yml index 85c1ff8239..de424bad0d 100644 --- a/examples/acp-agent/both-mode.cordis.snapshot.yml +++ b/examples/acp-agent/both-mode.cordis.snapshot.yml @@ -15,6 +15,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: 'none' workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/both-mode.cordis.yml b/examples/acp-agent/both-mode.cordis.yml index 6b554abefb..e44f3450de 100644 --- a/examples/acp-agent/both-mode.cordis.yml +++ b/examples/acp-agent/both-mode.cordis.yml @@ -13,6 +13,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/code-mode-workspace-context.cordis.snapshot.yml b/examples/acp-agent/code-mode-workspace-context.cordis.snapshot.yml index 8dad8832a0..0681881f96 100644 --- a/examples/acp-agent/code-mode-workspace-context.cordis.snapshot.yml +++ b/examples/acp-agent/code-mode-workspace-context.cordis.snapshot.yml @@ -14,6 +14,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: 'none' workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/code-mode-workspace-context.cordis.yml b/examples/acp-agent/code-mode-workspace-context.cordis.yml index 71edf9750e..807de9b3c3 100644 --- a/examples/acp-agent/code-mode-workspace-context.cordis.yml +++ b/examples/acp-agent/code-mode-workspace-context.cordis.yml @@ -11,6 +11,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/code-mode.cordis.snapshot.yml b/examples/acp-agent/code-mode.cordis.snapshot.yml index f672c7a8d7..2730ee8a87 100644 --- a/examples/acp-agent/code-mode.cordis.snapshot.yml +++ b/examples/acp-agent/code-mode.cordis.snapshot.yml @@ -15,6 +15,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: 'none' workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/code-mode.cordis.yml b/examples/acp-agent/code-mode.cordis.yml index fee39ef22a..38d8eb33cb 100644 --- a/examples/acp-agent/code-mode.cordis.yml +++ b/examples/acp-agent/code-mode.cordis.yml @@ -14,6 +14,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 tools: diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml index 5a61af7009..c70b41f9c7 100644 --- a/examples/acp-agent/cordis.yml +++ b/examples/acp-agent/cordis.yml @@ -41,12 +41,14 @@ # The ACP server app: the agent-spine-demo spine + JSONL persistence + the ACP bridge. # Persistence root: $DSH_SNAPSHOT_SESSIONS_ROOT when the snapshot harness sets it # (so it can harvest / isolate the log), else ./.sessions for the demo. +# Snapshot modes use raw JSONL fixtures; ordinary runs keep the compressed default. - id: acp-agent name: '@deepseek-ai/dsh-acp-demo' config: provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 # Keep the persona to identity and behavior; tool plugins own tool guidance. diff --git a/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl b/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl index 348e9881a5..65f92c4916 100644 --- a/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl +++ b/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl @@ -10,7 +10,7 @@ {"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_spill","name":"bash","arguments":"{\"command\":\"node -e \\\"process.stdout.write('SPILL_START-' + 'x'.repeat(2000) + '-SPILL_END')\\\"\",\"description\":\"Print large deterministic output\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"} {"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"call_spill","name":"bash","arguments":"{\"command\":\"node -e \\\"process.stdout.write('SPILL_START-' + 'x'.repeat(2000) + '-SPILL_END')\\\"\",\"description\":\"Print large deterministic output\"}"}} -{"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_spill","content":[{"type":"text","text":"SPILL_START-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-SPILL_END\n\n(Omitted 1417 bytes. Full formatted result stored at: /tmp/dsh-acp-snapshot-spill/session-de946378f5ae/dc816fc5677c-bash.txt. Use read with offset/limit, or grep this path to search within it.)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} +{"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_spill","content":[{"type":"text","text":"SPILL_START-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-SPILL_END\n\n(Omitted 1417 bytes. Full formatted result stored at: /tmp/dsh-acp-snapshot-spill/session-2ef0a5f14624/b5e2b8c5e6a6-bash.txt. Use read with offset/limit, or grep this path to search within it.)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} {"type":"step/end","seq":12,"time":0,"data":{"turn":1,"step":1}} {"type":"step/start","seq":13,"time":0,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl b/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl index 22aaa2159b..354a014a63 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl +++ b/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl @@ -131,8 +131,8 @@ {"type":"assistant/chunk","seq":129,"time":1783962245385,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":130,"time":1783962245385,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a command with sandbox_permissions set to danger-full-access, no prior run needed, justified as instructed."},{"type":"tool-call","id":"call_00_d0sAHpJ9mYOJi0z7KNy30441","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write file outside workspace and verify\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":1501,"outputTokens":174,"cacheReadTokens":0,"reasoningTokens":28}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129],"surfaceOp":"append"} {"type":"tool/call","seq":131,"time":1783962245385,"data":{"turn":1,"step":1,"callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write file outside workspace and verify\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}} -{"type":"approval/asked","seq":132,"time":1783962245386,"data":{"id":"ccc9f362-f1e0-4ccc-bb8e-a54df8bba8da","toolName":"bash","callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} -{"type":"approval/decided","seq":133,"time":1783962245387,"data":{"id":"ccc9f362-f1e0-4ccc-bb8e-a54df8bba8da","outcome":"allowed-once"}} +{"type":"approval/asked","seq":132,"time":1783962245386,"data":{"id":"e2d45b4a-ff48-488d-aeb6-8edc9dc5c3de","toolName":"bash","callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} +{"type":"approval/decided","seq":133,"time":1783962245387,"data":{"id":"e2d45b4a-ff48-488d-aeb6-8edc9dc5c3de","outcome":"allowed-once"}} {"type":"tool/result","seq":134,"time":1783962245399,"data":{"turn":1,"step":1,"callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","content":[{"type":"text","text":"escalated\n"}],"isError":false},"sourceEventSeqs":[131],"surfaceOp":"append"} {"type":"step/end","seq":135,"time":1783962245400,"data":{"turn":1,"step":1}} {"type":"step/start","seq":136,"time":1783962245400,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl b/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl index 3b0f2ec403..ff6d1187b3 100644 --- a/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl +++ b/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl @@ -155,8 +155,8 @@ {"type":"assistant/chunk","seq":153,"time":1783962246274,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":154,"time":1783962246274,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a specific command with `sandbox_permissions` set to `danger-full-access` and a specific justification. They explicitly said NOT to run it without sandbox_permissions first. Let me do exactly that."},{"type":"tool-call","id":"call_00_WB1vnPomi8yr6MlcFKTj7912","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write to /tmp and verify, then clean up\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":1509,"outputTokens":198,"cacheReadTokens":0,"reasoningTokens":48}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153],"surfaceOp":"append"} {"type":"tool/call","seq":155,"time":1783962246274,"data":{"turn":1,"step":1,"callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write to /tmp and verify, then clean up\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}} -{"type":"approval/asked","seq":156,"time":1783962246275,"data":{"id":"e0679c4e-2486-402d-928d-dd11c737f0b8","toolName":"bash","callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} -{"type":"approval/decided","seq":157,"time":1783962246275,"data":{"id":"e0679c4e-2486-402d-928d-dd11c737f0b8","outcome":"rejected"}} +{"type":"approval/asked","seq":156,"time":1783962246275,"data":{"id":"46c8dba4-52c9-4a6a-b6a6-5f34c95c28df","toolName":"bash","callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} +{"type":"approval/decided","seq":157,"time":1783962246275,"data":{"id":"46c8dba4-52c9-4a6a-b6a6-5f34c95c28df","outcome":"rejected"}} {"type":"tool/result","seq":158,"time":1783962246275,"data":{"turn":1,"step":1,"callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","content":[{"type":"text","text":"Error: the user rejected escalating this command to \"danger-full-access\""}],"isError":true},"sourceEventSeqs":[155],"surfaceOp":"append"} {"type":"step/end","seq":159,"time":1783962246276,"data":{"turn":1,"step":1}} {"type":"step/start","seq":160,"time":1783962246276,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl b/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl index 5d45608888..54601f5354 100644 --- a/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl @@ -89,8 +89,8 @@ {"type":"assistant/chunk","seq":87,"time":1784045703776,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":88,"time":1784045703780,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to create a file using the write tool with sandbox_permissions. Let me do that."},{"type":"tool-call","id":"call_00_Fnymmavpr4klMDy4Fdej3227","name":"write","arguments":"{\"file_path\": \"escalated.md\", \"content\": \"escalated\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to escalate this write\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3871,"outputTokens":132,"cacheReadTokens":0,"reasoningTokens":23}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87],"surfaceOp":"append"} {"type":"tool/call","seq":89,"time":1784045703780,"data":{"turn":1,"step":1,"callId":"call_00_Fnymmavpr4klMDy4Fdej3227","name":"write","arguments":"{\"file_path\": \"escalated.md\", \"content\": \"escalated\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to escalate this write\"}"}} -{"type":"approval/asked","seq":90,"time":1784045703782,"data":{"id":"5d605db6-a94b-4466-b426-62938370f754","toolName":"write","callId":"call_00_Fnymmavpr4klMDy4Fdej3227","reason":"escalate sandbox to danger-full-access: the user asked to escalate this write"}} -{"type":"approval/decided","seq":91,"time":1784045703786,"data":{"id":"5d605db6-a94b-4466-b426-62938370f754","outcome":"allowed-once"}} +{"type":"approval/asked","seq":90,"time":1784045703782,"data":{"id":"c37500b3-c252-4a9b-ad0d-9c4349419b30","toolName":"write","callId":"call_00_Fnymmavpr4klMDy4Fdej3227","reason":"escalate sandbox to danger-full-access: the user asked to escalate this write"}} +{"type":"approval/decided","seq":91,"time":1784045703786,"data":{"id":"c37500b3-c252-4a9b-ad0d-9c4349419b30","outcome":"allowed-once"}} {"type":"tool/result","seq":92,"time":1784045703798,"data":{"turn":1,"step":1,"callId":"call_00_Fnymmavpr4klMDy4Fdej3227","content":[{"type":"text","text":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-vmEGzd/escalated.md\nfile\n\nCreated file\n"}],"isError":false},"sourceEventSeqs":[89],"surfaceOp":"append"} {"type":"step/end","seq":93,"time":1784045703798,"data":{"turn":1,"step":1}} {"type":"step/start","seq":94,"time":1784045703799,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl index 38779efc94..247e13a075 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl @@ -55,8 +55,8 @@ {"type":"tool/call","seq":53,"time":1783352172557,"data":{"turn":1,"step":1,"callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","name":"bash","arguments":"{\"command\": \"echo HELLO\", \"description\": \"Echo HELLO\"}"}} {"type":"hook/invoked","seq":54,"time":1783352172558,"data":{"turn":1,"point":"PreToolUse","dialect":"claude","handlerId":"claude:PreToolUse:1","matcher":"bash"}} {"type":"hook/result","seq":55,"time":1783352172573,"data":{"turn":1,"point":"PreToolUse","handlerId":"claude:PreToolUse:1","decision":"ask","exitCode":0,"durationMs":14.113374999999905}} -{"type":"approval/asked","seq":56,"time":1783962235813,"data":{"id":"1eb7e3e2-21c4-485f-b2d8-b0bb0577c884","toolName":"bash","callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","reason":"bash requires manual approval in this session"}} -{"type":"approval/decided","seq":57,"time":1783962235813,"data":{"id":"1eb7e3e2-21c4-485f-b2d8-b0bb0577c884","outcome":"rejected"}} +{"type":"approval/asked","seq":56,"time":1783962235813,"data":{"id":"68f1e09d-f3e5-4e39-8a51-da082ba3ba99","toolName":"bash","callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","reason":"bash requires manual approval in this session"}} +{"type":"approval/decided","seq":57,"time":1783962235813,"data":{"id":"68f1e09d-f3e5-4e39-8a51-da082ba3ba99","outcome":"rejected"}} {"type":"tool/result","seq":58,"time":1783962235814,"data":{"turn":1,"step":1,"callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","content":[{"type":"text","text":"Error: the user rejected tool \"bash\""}],"isError":true},"sourceEventSeqs":[53],"surfaceOp":"append"} {"type":"step/end","seq":59,"time":1783962235814,"data":{"turn":1,"step":1}} {"type":"step/start","seq":60,"time":1783962235814,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/workspace-context.cordis.snapshot.yml b/examples/acp-agent/workspace-context.cordis.snapshot.yml index c5cccac519..fc47c24ae1 100644 --- a/examples/acp-agent/workspace-context.cordis.snapshot.yml +++ b/examples/acp-agent/workspace-context.cordis.snapshot.yml @@ -15,6 +15,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: 'none' workspaceContext: maxBytes: 65536 dshHome: !!js process.cwd() + '/.dsh' diff --git a/examples/acp-agent/workspace-context.cordis.yml b/examples/acp-agent/workspace-context.cordis.yml index 9f422f65b9..f9dadc8189 100644 --- a/examples/acp-agent/workspace-context.cordis.yml +++ b/examples/acp-agent/workspace-context.cordis.yml @@ -12,6 +12,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 dshHome: !!js process.cwd() + '/.dsh' diff --git a/examples/cordis-agent/README.md b/examples/cordis-agent/README.md index 310fbb30af..a0bb2188da 100644 --- a/examples/cordis-agent/README.md +++ b/examples/cordis-agent/README.md @@ -1,6 +1,6 @@ # cordis-agent -The self-referential harness demo: the coding spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). +The self-referential harness demo: the DeepSeek V4 coding spine on the full-screen TUI plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). ## Run it diff --git a/examples/cordis-agent/composition.md b/examples/cordis-agent/composition.md index 499379482f..a812f71445 100644 --- a/examples/cordis-agent/composition.md +++ b/examples/cordis-agent/composition.md @@ -20,11 +20,11 @@ flowchart LR cfg --> plugin_cordis_web plugin_cordis_web_fetch_local["web-fetch-local
@deepseek-ai/dsh-web-fetch-local"] cfg --> plugin_cordis_web_fetch_local - plugin_cordis_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-demo"] - cfg --> plugin_cordis_stdio_agent - plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"] - plugin_cordis_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] - plugin_cordis_stdio_agent --> frontdoor_stdio["dsh-tui (TTY) / dsh-stdio (pipes)
pre-created main agent"] + plugin_cordis_tui_agent["tui-agent
@deepseek-ai/dsh-tui-demo"] + cfg --> plugin_cordis_tui_agent + plugin_cordis_tui_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"] + plugin_cordis_tui_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] + plugin_cordis_tui_agent --> frontdoor_tui["@deepseek-ai/dsh-tui
pre-created main agent"] bundle_agent_core --> spine_llm["ctx.llm"] bundle_agent_core --> spine_sessions["ctx.sessions"] bundle_agent_core --> spine_tools["ctx.tools + tool-bash"] @@ -41,7 +41,7 @@ flowchart LR | `fs-local` | `@deepseek-ai/dsh-fs-local` | | `web` | `@deepseek-ai/dsh-web` | | `web-fetch-local` | `@deepseek-ai/dsh-web-fetch-local` | -| `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` | +| `tui-agent` | `@deepseek-ai/dsh-tui-demo` | | `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` | Source config: [`examples/cordis-agent/cordis.yml`](cordis.yml). diff --git a/examples/cordis-agent/cordis.yml b/examples/cordis-agent/cordis.yml index 7c7c010c3a..39b6cd3b48 100644 --- a/examples/cordis-agent/cordis.yml +++ b/examples/cordis-agent/cordis.yml @@ -1,4 +1,4 @@ -# Self-referential stdio demo: the coding spine plus tools to inspect the live +# Self-referential TUI demo: the coding spine plus tools to inspect the live # service/plugin/tool/mount/API/event state, mount a model-written plugin under # `cordis-dynamic`, and quiescently unmount it. The app bin loads the gitignored # root `.env` before reading the required DeepSeek key and optional base URL. @@ -45,8 +45,8 @@ name: '@deepseek-ai/dsh-web-fetch-local' # The app bundle pre-creates the self-referential demo's `main` agent. -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: provider: deepseek model: deepseek-v4-flash diff --git a/examples/cordis-agent/tests/keyless-smoke.e2e.ts b/examples/cordis-agent/tests/keyless-smoke.e2e.ts index 24cf2138fb..6e5cca3b08 100644 --- a/examples/cordis-agent/tests/keyless-smoke.e2e.ts +++ b/examples/cordis-agent/tests/keyless-smoke.e2e.ts @@ -1,27 +1,23 @@ import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' -import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' +import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke' +import { runTuiPtySmoke } from '../../tui-agent/tests/pty-harness.ts' -/** - * Keyless Loader-path smoke for examples/cordis-agent: boot the real tree, - * including tool-cordis resolved by package name, then close stdin without a - * prompt and assert the banner. The dummy key never reaches a model call. - */ - -const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url)) +const binScript = fileURLToPath(new URL('../../../packages/examples/tui-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) -describe('cordis-agent keyless smoke (real cordis.yml via the Loader)', () => { - it('boots the full plugin tree incl. tool-cordis, prints its banner, and exits cleanly on EOF', async () => { - const { stdout } = await runLoaderSmoke({ +describe('cordis-agent keyless smoke (real Loader tree in a PTY)', () => { + it('boots the full tool-cordis tree and exits cleanly through the TUI', async () => { + const output = await runTuiPtySmoke({ label: 'cordis-agent', - tempDirPrefix: 'cordis-smoke-', + tempDirPrefix: 'cordis-agent-smoke-', binScript, configPath, tsconfigPath, env: { DEEPSEEK_API_KEY: 'keyless-smoke-no-call' }, + actions: [{ waitFor: 'cordis-agent ready.', send: '/exit\r' }], }) - expect(stdout).toContain('cordis-agent ready.') + expect(output).toContain('cordis-agent ready.') }, LOADER_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/examples/echo-agent/README.md b/examples/echo-agent/README.md deleted file mode 100644 index f397cc633f..0000000000 --- a/examples/echo-agent/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# echo-agent - -Runnable demo: stdin chat with a scripted mock model and an echo tool. The all-mock skeleton — "swap the backend, keep the app". - -## What it shows - -This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app (which bundles the whole [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) spine, JSONL persistence, the TTY-selected `dsh-tui`/`dsh-stdio` front doors, and a pre-created `main` agent), and swaps in two example-local backends plus `hmr`: - -- `mock-llm.ts` — a mock `LlmAdapter` that streams scripted responses and calls the `echo` tool when the user types "echo ". Registered with `ctx.llm.registerAdapter(['mock-echo'], …)`. -- `echo-tool.ts` — a tool registered via `ctx.tools.register(defineTool(…))` with typed `execute` args; echoes text back uppercased. - -Swapping `mock-llm` for the real `llm-deepseek` adapter is all that separates this from `repl-agent` — the same app, a different backend. - -## Plugin files - -| File | Role | Key patterns demonstrated | -|---|---|---| -| `src/mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter(['mock-echo'], …)`, streaming chunks with the proper `block-start`/`block-end` protocol | -| `src/echo-tool.ts` | Tool registration | `ctx.tools.register(defineTool(…))` with typed `execute` args, returning `ContentBlock[]` | -| `cordis.yml` | Leaf wiring | the two backends + `hmr` + one `@deepseek-ai/dsh-stdio-demo` entry carrying the app config | - -The spine, UI, persistence, and boot glue all live in `@deepseek-ai/dsh-stdio-demo` and the bundle it loads — this folder holds only the demo-specific mocks and the leaf wiring. - -## Run - -```sh -pnpm run demo:echo -# or: -node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml -``` - -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 `/.sessions/cwd-/` (one `.jsonl` log per session). Clean up with: `rm -rf .sessions` diff --git a/examples/echo-agent/composition.md b/examples/echo-agent/composition.md deleted file mode 100644 index 15f8e078fb..0000000000 --- a/examples/echo-agent/composition.md +++ /dev/null @@ -1,43 +0,0 @@ - - -# Echo Agent App Composition - -The echo demo swaps in a local mock LLM and teaching echo tool, then loads the stdio app package for the shared spine and terminal front door. - -```mermaid -flowchart LR - cfg["examples/echo-agent
cordis.yml"] - plugin_echo_hmr["hmr
@cordisjs/plugin-hmr"] - cfg --> plugin_echo_hmr - plugin_echo_mock_llm["mock-llm
./src/mock-llm.ts"] - cfg --> plugin_echo_mock_llm - plugin_echo_echo_tool["echo-tool
./src/echo-tool.ts"] - cfg --> plugin_echo_echo_tool - plugin_echo_bash["bash
@deepseek-ai/dsh-bash-local"] - cfg --> plugin_echo_bash - plugin_echo_fs_local["fs-local
@deepseek-ai/dsh-fs-local"] - cfg --> plugin_echo_fs_local - plugin_echo_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-demo"] - cfg --> plugin_echo_stdio_agent - plugin_echo_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"] - plugin_echo_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] - plugin_echo_stdio_agent --> frontdoor_stdio["dsh-tui (TTY) / dsh-stdio (pipes)
pre-created main agent"] - bundle_agent_core --> spine_llm["ctx.llm"] - bundle_agent_core --> spine_sessions["ctx.sessions"] - bundle_agent_core --> spine_tools["ctx.tools + tool-bash"] - bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"] -``` - -| Plugin id | Package / module | -| --- | --- | -| `hmr` | `@cordisjs/plugin-hmr` | -| `mock-llm` | `./src/mock-llm.ts` | -| `echo-tool` | `./src/echo-tool.ts` | -| `bash` | `@deepseek-ai/dsh-bash-local` | -| `fs-local` | `@deepseek-ai/dsh-fs-local` | -| `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` | - -Source config: [`examples/echo-agent/cordis.yml`](cordis.yml). - -Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source. diff --git a/examples/echo-agent/cordis.yml b/examples/echo-agent/cordis.yml deleted file mode 100644 index 6b3d19839b..0000000000 --- a/examples/echo-agent/cordis.yml +++ /dev/null @@ -1,43 +0,0 @@ -# Stdio agent with the network-free `mock-echo` adapter and example-local `echo` -# tool. The app bundle supplies the spine; this leaf selects backends, HMR, and app config. -# No API key: the `mock-echo` adapter never touches the network. - -# Hot-module reload for the dev/demo loop (a leaf entry, not baked into -# dsh-stdio-demo — it needs `node --expose-internals`, which `demo:echo` passes). -- id: hmr - name: '@cordisjs/plugin-hmr' - config: - root: ['.'] - -# Example-local model and tool plugins resolve relative to this file. -- id: mock-llm - name: './src/mock-llm.ts' - -- id: echo-tool - name: './src/echo-tool.ts' - -# Local bash executor: agent-spine-demo ships the `tool-bash` consumer schema, so the -# leaf provides the executor it runs on (the echo demo doesn't drive bash, but -# the tool is part of the shared spine). -- id: bash - name: '@deepseek-ai/dsh-bash-local' - -# Local filesystem provider for agent-spine-demo's workspace-context loader. This -# does not expose model-facing read/write/edit tools in the echo demo. -- id: fs-local - name: '@deepseek-ai/dsh-fs-local' - config: - cwd: !!js process.cwd() - -# The app pre-creates `main` on the mock model and supplies persistence plus -# TTY-selected `dsh-tui`/`dsh-stdio` front doors; readline mode also owns logging. -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' - config: - provider: mock - model: mock-echo - persona: 'You are echo-agent, a demo agent.' - welcome: 'echo-agent ready. Type a message ("echo " triggers the tool).' - persistenceRoot: './.sessions' - workspaceContext: - maxBytes: 65536 diff --git a/examples/echo-agent/package.json b/examples/echo-agent/package.json deleted file mode 100644 index 00982fa297..0000000000 --- a/examples/echo-agent/package.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "echo-agent-example", - "private": true, - "version": "0.0.1", - "type": "module", - "description": "Runnable demo: stdin chat with a scripted mock model + echo tool" -} diff --git a/examples/echo-agent/src/echo-tool.ts b/examples/echo-agent/src/echo-tool.ts deleted file mode 100644 index dfdcb9b001..0000000000 --- a/examples/echo-agent/src/echo-tool.ts +++ /dev/null @@ -1,19 +0,0 @@ -import type { Context } from 'cordis' -import { defineTool } from '@deepseek-ai/dsh-tools' - -export const name = 'echo-tool' -export const inject = ['tools'] - -export function apply(ctx: Context) { - ctx.tools.register(defineTool({ - name: 'echo', - description: 'Echo the given text back, uppercased.', - parameters: { - text: { type: 'string', required: true }, - }, - async execute(args) { - // args is typed: { text: string } - return [{ type: 'text', text: `ECHO: ${args.text.toUpperCase()}` }] - }, - })) -} diff --git a/examples/echo-agent/src/mock-llm.ts b/examples/echo-agent/src/mock-llm.ts deleted file mode 100644 index 1f61dc4ee3..0000000000 --- a/examples/echo-agent/src/mock-llm.ts +++ /dev/null @@ -1,59 +0,0 @@ -import type { Context } from 'cordis' -import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm' -import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm' - -/** - * Demo adapter for the `mock-echo` model. - * - * Behavior: if the last user text starts with "echo ", it calls the `echo` - * tool with the rest of the line (exercising the tool round-trip), otherwise - * it streams a canned reply quoting the input. - */ -class MockEchoAdapter extends LlmAdapter { - async * stream(options: GenerateOptions): AsyncIterable { - const lastUserText = [...options.messages].reverse() - .filter(message => message.role === 'user') - .flatMap(message => message.content) - .filter(block => block.type === 'text') - .map(block => block.text) - .find(text => !text.startsWith('<')) ?? '' - - const hasToolResult = options.messages.at(-1)?.content.some(block => block.type === 'tool-result') - - if (lastUserText.startsWith('echo ') && !hasToolResult) { - const payload = lastUserText.slice(5) - const args = JSON.stringify({ text: payload }) - yield { type: 'block-start', index: 0, blockType: 'text' } - for (const char of 'Let me echo that for you.') { - yield { type: 'text-delta', index: 0, text: char } - await new Promise(resolve => setTimeout(resolve, 2)) - } - yield { type: 'block-end', index: 0, block: { type: 'text', text: 'Let me echo that for you.' } } - yield { type: 'block-start', index: 1, blockType: 'tool-call' } - yield { type: 'tool-call-delta', index: 1, id: CallId('call-echo'), name: 'echo', argumentsDelta: args } - yield { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('call-echo'), name: 'echo', arguments: args } } - yield { type: 'usage', usage: { inputTokens: 20, outputTokens: 10 } } - yield { type: 'finish', reason: { kind: 'tool-calls' } } - return - } - - const reply = hasToolResult - ? 'The echo tool has spoken.' - : `You said: "${lastUserText}". Try "echo " to see a tool call.` - yield { type: 'block-start', index: 0, blockType: 'text' } - for (const char of reply) { - yield { type: 'text-delta', index: 0, text: char } - await new Promise(resolve => setTimeout(resolve, 2)) - } - yield { type: 'block-end', index: 0, block: { type: 'text', text: reply } } - yield { type: 'usage', usage: { inputTokens: 20, outputTokens: reply.length } } - yield { type: 'finish', reason: { kind: 'stop' } } - } -} - -export const name = 'mock-llm' -export const inject = ['llm'] - -export function apply(ctx: Context) { - ctx.llm.registerAdapter(['mock'], new MockEchoAdapter()) -} diff --git a/examples/echo-agent/tests/echo.e2e.ts b/examples/echo-agent/tests/echo.e2e.ts deleted file mode 100644 index db0d998336..0000000000 --- a/examples/echo-agent/tests/echo.e2e.ts +++ /dev/null @@ -1,43 +0,0 @@ -import { fileURLToPath } from 'node:url' -import { describe, expect, it } from 'vitest' -import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' - -/** - * Keyless-by-nature Loader-path coverage for examples/echo-agent. The real - * tree uses its deterministic mock model, so this suite is both the boot smoke - * and the complete behavior proof for the example. - */ - -const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url)) -const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) - -async function runEcho(stdinLines: readonly string[]): Promise { - const { stdout } = await runLoaderSmoke({ - label: 'echo-agent', - tempDirPrefix: 'echo-smoke-', - binScript, - configPath, - tsconfigPath, - stdinLines, - }) - return stdout -} - -describe('echo-agent keyless smoke (real cordis.yml via the Loader)', () => { - it('boots, prints its welcome banner, and exits cleanly on stdin EOF', async () => { - expect(await runEcho([])).toContain('echo-agent ready.') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) - - it('runs the echo tool round-trip for an "echo …" line', async () => { - const stdout = await runEcho(['echo hello world']) - expect(stdout).toContain('[tool call] echo') - expect(stdout).toContain('[tool result] ECHO: HELLO WORLD') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) - - it('streams a direct canned reply for a non-echo line', async () => { - const stdout = await runEcho(['just chatting']) - expect(stdout).toContain('just chatting') - expect(stdout).not.toContain('[tool call]') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) -}) diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md index 10667a6101..a1e2455ed3 100644 --- a/examples/headless-agent/README.md +++ b/examples/headless-agent/README.md @@ -8,7 +8,7 @@ Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + # repo root .env (gitignored) or exported env: # DEEPSEEK_API_KEY=sk-… # DEEPSEEK_BASE_URL=https://… # optional; defaults to the public API -pnpm run demo:headless -- "fix the failing test in this workspace" +pnpm run demo:headless "fix the failing test in this workspace" pnpm run demo:headless --output-format json -- "summarize the implementation" pnpm run demo:headless --output-format stream-json -- "run the focused tests" ``` diff --git a/examples/headless-agent/advanced.cordis.yml b/examples/headless-agent/advanced.cordis.yml index 862a2f769b..fe553aa2b9 100644 --- a/examples/headless-agent/advanced.cordis.yml +++ b/examples/headless-agent/advanced.cordis.yml @@ -10,6 +10,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 tools: diff --git a/examples/headless-agent/cordis.yml b/examples/headless-agent/cordis.yml index a8330f0efb..aa2d9fd7ca 100644 --- a/examples/headless-agent/cordis.yml +++ b/examples/headless-agent/cordis.yml @@ -25,6 +25,7 @@ provider: deepseek model: deepseek-v4-flash persistenceRoot: './.sessions' + persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'" workspaceContext: maxBytes: 65536 persona: | diff --git a/examples/repl-agent/tests/code-mode.e2e.ts b/examples/headless-agent/tests/code-mode.e2e.ts similarity index 100% rename from examples/repl-agent/tests/code-mode.e2e.ts rename to examples/headless-agent/tests/code-mode.e2e.ts diff --git a/examples/repl-agent/tests/coding-task.e2e.ts b/examples/headless-agent/tests/coding-task.e2e.ts similarity index 100% rename from examples/repl-agent/tests/coding-task.e2e.ts rename to examples/headless-agent/tests/coding-task.e2e.ts diff --git a/examples/repl-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts similarity index 100% rename from examples/repl-agent/tests/compaction.e2e.ts rename to examples/headless-agent/tests/compaction.e2e.ts diff --git a/examples/echo-agent/tests/fixtures/goal/goal/cordis.yml b/examples/headless-agent/tests/fixtures/goal-domain/cordis.yml similarity index 63% rename from examples/echo-agent/tests/fixtures/goal/goal/cordis.yml rename to examples/headless-agent/tests/fixtures/goal-domain/cordis.yml index 9d9e644cfa..bc9b71685e 100644 --- a/examples/echo-agent/tests/fixtures/goal/goal/cordis.yml +++ b/examples/headless-agent/tests/fixtures/goal-domain/cordis.yml @@ -1,6 +1,6 @@ -# Test-only composition: create one goal through a Loader-mounted lifecycle consumer. -- id: mock-llm - name: '../../../../src/mock-llm.ts' +# Test-only composition: create one goal through a Loader-mounted step consumer. +- id: cli-mock-llm + name: '../cli-mock-llm.ts' - id: bash name: '@deepseek-ai/dsh-bash-local' @@ -13,12 +13,12 @@ - id: seed-goal name: './seed-goal.ts' -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: cli-agent + name: '@deepseek-ai/dsh-cli-demo' config: - provider: mock - model: mock-echo + provider: cli-mock + model: cli-mock persona: 'Test the persisted goal domain.' - welcome: 'goal-domain e2e ready.' persistenceRoot: './.sessions' + persistenceCompression: none workspaceContext: false diff --git a/examples/echo-agent/tests/fixtures/goal/goal/seed-goal.ts b/examples/headless-agent/tests/fixtures/goal-domain/seed-goal.ts similarity index 66% rename from examples/echo-agent/tests/fixtures/goal/goal/seed-goal.ts rename to examples/headless-agent/tests/fixtures/goal-domain/seed-goal.ts index ae3d0d231c..254870eca9 100644 --- a/examples/echo-agent/tests/fixtures/goal/goal/seed-goal.ts +++ b/examples/headless-agent/tests/fixtures/goal-domain/seed-goal.ts @@ -1,4 +1,4 @@ -/** Test-only Loader plugin that creates a goal at the real session-start edge. */ +/** Test-only Loader plugin that creates a goal at the first real step edge. */ import type { Context } from 'cordis' import type {} from '@deepseek-ai/dsh-goal' @@ -7,7 +7,8 @@ export const name = 'seed-goal' export const inject = ['goals'] export function apply(ctx: Context): void { - ctx.on('agent/session-start', (agent) => { + ctx.on('agent/pre-step', (agent) => { + if (ctx.goals.get(agent) !== undefined) return ctx.goals.create(agent, { objective: 'Prove the composed goal survives in the session log', maxGoalRounds: 7, diff --git a/examples/headless-agent/tests/fixtures/time-context-driver.ts b/examples/headless-agent/tests/fixtures/time-context-driver.ts new file mode 100644 index 0000000000..cac81daeec --- /dev/null +++ b/examples/headless-agent/tests/fixtures/time-context-driver.ts @@ -0,0 +1,16 @@ +#!/usr/bin/env node +/** Test driver that sends two turns through one Headless Loader composition. */ + +import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot' +import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts' + +const configPath = process.argv[2] +if (configPath === undefined) throw new Error('time-context driver requires a config path') + +const ctx = await boot('time-context-e2e', resolveConfigPath(configPath, undefined)) +try { + await runOneShot(ctx, { task: 'first' }) + await runOneShot(ctx, { task: 'second' }) +} finally { + await ctx.fiber.dispose() +} diff --git a/examples/headless-agent/tests/fixtures/time-context-mock-llm.ts b/examples/headless-agent/tests/fixtures/time-context-mock-llm.ts new file mode 100644 index 0000000000..8cd3155ca7 --- /dev/null +++ b/examples/headless-agent/tests/fixtures/time-context-mock-llm.ts @@ -0,0 +1,22 @@ +import type { Context } from 'cordis' +import { LlmAdapter, type StreamChunk } from '@deepseek-ai/dsh-llm' + +/** Deterministic one-step adapter for the time-context Loader fixture. */ +class TimeContextMockAdapter extends LlmAdapter { + async * stream(): AsyncIterable { + const text = 'time context sampled' + yield { type: 'block-start', index: 0, blockType: 'text' } + yield { type: 'text-delta', index: 0, text } + yield { type: 'block-end', index: 0, block: { type: 'text', text } } + yield { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } } + yield { type: 'finish', reason: { kind: 'stop' } } + } +} + +export const name = 'time-context-mock-llm' +export const inject = ['llm'] + +/** Register the test-only `time-context-mock` adapter. */ +export function apply(ctx: Context): void { + ctx.llm.registerAdapter(['time-context-mock'], new TimeContextMockAdapter()) +} diff --git a/examples/echo-agent/tests/fixtures/context/time-context/cordis.yml b/examples/headless-agent/tests/fixtures/time-context.cordis.yml similarity index 60% rename from examples/echo-agent/tests/fixtures/context/time-context/cordis.yml rename to examples/headless-agent/tests/fixtures/time-context.cordis.yml index 9b59e2ded9..91ba8a1254 100644 --- a/examples/echo-agent/tests/fixtures/context/time-context/cordis.yml +++ b/examples/headless-agent/tests/fixtures/time-context.cordis.yml @@ -1,6 +1,6 @@ # Test-only composition: keep time-context opt-in while exercising its real Loader/app path. -- id: mock-llm - name: '../../../../src/mock-llm.ts' +- id: time-context-mock-llm + name: './time-context-mock-llm.ts' - id: bash name: '@deepseek-ai/dsh-bash-local' @@ -8,12 +8,12 @@ - id: time-context name: '@deepseek-ai/dsh-time-context' -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: cli-agent + name: '@deepseek-ai/dsh-cli-demo' config: - provider: mock - model: mock-echo + provider: time-context-mock + model: time-context-mock persona: 'Test the time-context plugin.' - welcome: 'time-context e2e ready.' persistenceRoot: './.sessions' + persistenceCompression: 'none' workspaceContext: false diff --git a/examples/repl-agent/tests/full-loop.e2e.ts b/examples/headless-agent/tests/full-loop.e2e.ts similarity index 100% rename from examples/repl-agent/tests/full-loop.e2e.ts rename to examples/headless-agent/tests/full-loop.e2e.ts diff --git a/examples/repl-agent/tests/harness.ts b/examples/headless-agent/tests/harness.ts similarity index 98% rename from examples/repl-agent/tests/harness.ts rename to examples/headless-agent/tests/harness.ts index edf611e89d..ca1c59871e 100644 --- a/examples/repl-agent/tests/harness.ts +++ b/examples/headless-agent/tests/harness.ts @@ -15,7 +15,7 @@ import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic' import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic' /** - * Shared harness for the repl-agent e2e suites: the full plugin stack + * Shared harness for the headless-agent e2e suites: the full plugin stack * with the real DeepSeek adapter and the real bash + todo_write tools. Lives * outside the *.e2e.ts pattern so importing it never re-registers another * file's tests. diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts index 57b8660c03..4cd06aed78 100644 --- a/examples/headless-agent/tests/keyless-smoke.e2e.ts +++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts @@ -1,4 +1,7 @@ -import { readdir } from 'node:fs/promises' +import { readFile, readdir } from 'node:fs/promises' +import { zstdDecompress } from 'node:zlib' +import { promisify } from 'node:util' +import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' @@ -7,10 +10,11 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session' const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url)) const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) +const decompress = promisify(zstdDecompress) describe('headless-agent keyless smoke', () => { it('boots the real Loader tree, runs a real bash tool round trip, and persists the turn', async () => { - let persisted = false + let persistedHeader: Record | undefined const { stdout, stderr } = await runLoaderSmoke({ label: 'headless-agent', tempDirPrefix: 'headless-agent-smoke-', @@ -20,7 +24,11 @@ describe('headless-agent keyless smoke', () => { tsconfigPath, inspect: async (cwd) => { const files = await readdir(cwd, { recursive: true }) - persisted = files.some(file => file.endsWith('.jsonl')) + const relativePath = files.find(file => file.endsWith('.jsonl.zstd')) + if (relativePath === undefined) return + const compressed = await readFile(join(cwd, relativePath)) + expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd') + persistedHeader = JSON.parse((await decompress(compressed)).toString()) as Record }, }) const lines = stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record) @@ -38,6 +46,6 @@ describe('headless-agent keyless smoke', () => { usage: { inputTokens: 18, outputTokens: 8, cacheReadTokens: 2, reasoningTokens: 1 }, }) expect(String(result?.['result'])).toContain('CLI_TOOL_ROUND_TRIP') - expect(persisted).toBe(true) + expect(persistedHeader).toMatchObject({ type: 'session' }) }, LOADER_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/examples/repl-agent/tests/resume.e2e.ts b/examples/headless-agent/tests/resume.e2e.ts similarity index 100% rename from examples/repl-agent/tests/resume.e2e.ts rename to examples/headless-agent/tests/resume.e2e.ts diff --git a/examples/repl-agent/tests/todo-write.e2e.ts b/examples/headless-agent/tests/todo-write.e2e.ts similarity index 100% rename from examples/repl-agent/tests/todo-write.e2e.ts rename to examples/headless-agent/tests/todo-write.e2e.ts diff --git a/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts b/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts index c99b2c3c50..fb8ee81f64 100644 --- a/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts +++ b/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts @@ -1,14 +1,17 @@ import { spawn } from 'node:child_process' import { createServer } from 'node:http' -import { mkdtemp, rm } from 'node:fs/promises' +import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' +import { promisify } from 'node:util' +import { zstdDecompress } from 'node:zlib' import { describe, expect, it } from 'vitest' const binScript = fileURLToPath(new URL('../../../packages/examples/jsonrpc-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) const repoRoot = fileURLToPath(new URL('../../..', import.meta.url)) +const decompress = promisify(zstdDecompress) function waitForLine( lines: string[], @@ -152,6 +155,13 @@ describe('jsonrpc-agent keyless smoke', () => { } else { expect(child.exitCode, stderr).toBe(0) } + const sessionsRoot = join(root, '.sessions') + const files = await readdir(sessionsRoot, { recursive: true }) + const log = files.find(file => file.endsWith('.jsonl.zstd')) + expect(log).toBeDefined() + const compressed = await readFile(join(sessionsRoot, log!)) + expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd') + expect(JSON.parse((await decompress(compressed)).toString())).toMatchObject({ type: 'session', id: 'main' }) } finally { if (child.exitCode === null) child.kill('SIGKILL') await new Promise(resolve => modelServer.close(() => { resolve() })) diff --git a/examples/package.json b/examples/package.json index edebb054a5..8ea7a93002 100644 --- a/examples/package.json +++ b/examples/package.json @@ -9,6 +9,7 @@ "@cordisjs/plugin-include": "workspace:*", "@deepseek-ai/dsh-acp-demo": "workspace:*", "@deepseek-ai/dsh-agent-spine-demo": "workspace:*", + "@deepseek-ai/dsh-app-boot": "workspace:*", "@deepseek-ai/dsh-bash-local": "workspace:*", "@deepseek-ai/dsh-bash-sandbox": "workspace:*", "@deepseek-ai/dsh-cli-demo": "workspace:*", @@ -33,7 +34,7 @@ "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*", "@deepseek-ai/dsh-spill-local": "workspace:*", "@deepseek-ai/dsh-spill-policy": "workspace:*", - "@deepseek-ai/dsh-stdio-demo": "workspace:*", + "@deepseek-ai/dsh-tui-demo": "workspace:*", "@deepseek-ai/dsh-subagent": "workspace:*", "@deepseek-ai/dsh-subagent-fork": "workspace:*", "@deepseek-ai/dsh-subagent-spawn": "workspace:*", diff --git a/examples/repl-agent/README.md b/examples/repl-agent/README.md deleted file mode 100644 index c81443ebf1..0000000000 --- a/examples/repl-agent/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# repl-agent - -The repl-agent wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + readline chat + JSONL persistence, loaded from `cordis.yml`. The sibling [`tui-agent`](../tui-agent/README.md) fixes the same agent composition to the full-screen terminal front door. - -## Run it - -```sh -# repo root .env (gitignored) or exported env: -# DEEPSEEK_API_KEY=sk-… -# DEEPSEEK_BASE_URL=https://… # optional; defaults to the public API -pnpm run demo:repl -``` - -Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ the generic `task_output` / `task_list` / `task_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write`. - -The REPL renders reasoning, tool calls/results, and the latest todo list as line-oriented output suitable for terminals and pipes. Use `pnpm run demo:tui` for the interactive Markdown/card interface. - -### Resuming a prior session - -Each run starts a fresh session by default (its event log lands under `./.sessions/`). To **continue** a previous conversation, set `RESUME_SESSION_ID` to that session's id — the `main` agent then rehydrates the persisted log instead of starting fresh, so the model sees the earlier turns as history: - -```sh -RESUME_SESSION_ID= pnpm run demo:repl -``` - -The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing or unreadable id starts no agent and emits `agent-loop/config-start-failed`: the TUI prints the failure and exits nonzero, while readline reports any dropped queued input and allows piped EOF to finish. Unset it or choose an existing session id. - -## Code Mode - -[`code-mode.cordis.yml`](code-mode.cordis.yml) overlays the same tree with the worker-thread runtime and `tools: { mode: code }`. The model receives one `run_code` transport plus a generated TypeScript SDK for the visible tools; only program output returns to model context. Use `mode: both` to expose native calls alongside `run_code`. See the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) for the execution contract. - -```sh -pnpm run demo:code-mode # this overlay under the REPL (default UI) -pnpm run demo:code-mode acp # the acp-agent example's same-shaped overlay -``` - -Try a task that spans several tool calls, e.g.: - -> Count the lines of every `*.md` file under docs/ and write the three largest to summary.txt. - -and watch the transcript: one `run_code` call, a program looping over tools, and a result the model curated instead of five round-trips of raw tool output. - -## What each leaf entry demonstrates - -This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads one app package, and adds product tools that are intentionally outside the shared spine. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (JSONL persistence, the selected terminal channel, the pre-created `main` agent) live inside the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app and the [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle it loads; the leaf wires the backends and model-facing optional tools: - -| Entry | Demonstrates | -|---|---| -| `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:repl` passes | -| `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin | -| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash` schema (`tool-bash`) and generic `task_*` controls (`tool-tasks`) come from `dsh-agent-spine-demo`, so only the executor is a leaf choice | -| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-spine demo + JSONL persistence + the configured terminal channel + a pre-created `main` agent. This leaf fixes `ui.mode` to `readline`; `tui-agent` owns the corresponding TUI leaf | -| `token-meter`, `tool-result-prune`, `compact-basic` | replay-aware pressure, model-free oversized tool-result pruning, and LLM summary compaction. Pruning runs only after a compaction trigger qualifies and can avoid the summarization call | -| `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix | -| `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) | -| `workflow-workerthread`, `tool-workflow`, `tool-ralph` | the worker-thread engine, general model-written `workflow` tool, and separate fixed fresh-agent `ralph` consumer, with children routed through spawn | -| `tool-todo` | the model-facing `todo_write` tool; writes the whole task list to the session log and renders as a persistent TUI plan or readline checklist | -| `fs-local`, `fs-policy`, `tool-fs` | the filesystem stack: the local `ctx.fs` provider, the read-before-write/edit policy gate (on the `fs/*` event gate), and the model-facing `read`/`write`/`edit` tools. Relative paths resolve against the session workspace | - -## End-to-end tests (`pnpm run test:e2e`, key-gated) - -- `tests/full-loop.e2e.ts` — the canary: real model runs `echo e2e-ok` through the real bash tool; asserts `tool/call`/`tool/result` session events and the final answer. -- `tests/coding-task.e2e.ts` — the swebench-style smoke: a temp dir holds `add.js` (with `a - b` where `a + b` belongs) and a failing `add.test.js`; the agent must fix the bug and verify. The test re-runs `node add.test.js` ITSELF and inspects the files — agent claims are not trusted. -- `tests/resume.e2e.ts` — durable continuity across processes: run 1 tells the real model a secret code and persists the turn to a temp JSONL root, then the whole context is disposed; run 2 is a fresh context over the same root that RESUMES the session id and asks the model to recall the code. The recall can only come from the rehydrated log. -- `tests/compaction.e2e.ts` — the compaction smoke: a real multi-step bash task runs with a deliberately tiny context window so automatic pruning or summary compaction fires mid-session. It verifies the world: a replayable surface replacement lands, summary brackets are complete when summarization is needed, the surface shrinks, and the agent still produces a correct final answer. -- `tests/todo-write.e2e.ts` — a real model drives the real `todo_write` tool and the test verifies the resulting `todo/write` session event. - -These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. The keyless Loader smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts` and `tests/code-mode-keyless-smoke.e2e.ts`. diff --git a/examples/repl-agent/code-mode.cordis.yml b/examples/repl-agent/code-mode.cordis.yml deleted file mode 100644 index 8802b510ba..0000000000 --- a/examples/repl-agent/code-mode.cordis.yml +++ /dev/null @@ -1,33 +0,0 @@ -# Code Mode adds `ctx.codeRuntime` and changes the registry to one wire tool, -# `run_code`, plus a generated SDK for bash/read/write/edit/subagent/todo_write. -# `demo:code-mode` selects this overlay; the ACP example has the same UI-specific -# shape. A config patch replaces the whole app config, so unchanged base fields -# are restated; only `tools`, `welcome`, and the persona's second paragraph differ. -- id: base - name: '@cordisjs/plugin-include' - config: - path: ./cordis.yml - patches: - - id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' - config: - provider: deepseek - model: deepseek-v4-flash - resumeSessionId: !!js process.env.RESUME_SESSION_ID - persistenceRoot: './.sessions' - workspaceContext: - maxBytes: 65536 - tools: - mode: code - welcome: 'code-mode agent ready. Give it a multi-tool task.' - ui: - mode: readline - persona: | - You are a coding agent powered by the {{model}} model. - - You work by writing TypeScript programs for run_code: batch related - tool work into one program, loop and branch where it helps, and print - or return ONLY the findings that matter. - - insert: - - id: code-runtime - name: '@deepseek-ai/dsh-code-runtime-worker' diff --git a/examples/repl-agent/composition.md b/examples/repl-agent/composition.md deleted file mode 100644 index 9b05dbcb6f..0000000000 --- a/examples/repl-agent/composition.md +++ /dev/null @@ -1,94 +0,0 @@ - - -# REPL Agent App Composition - -The REPL agent demo adds the real DeepSeek adapter, filesystem tools, todo_write, tool-result pruning, compaction, and both subagent transports on top of the stdio app package. - -```mermaid -flowchart LR - cfg["examples/repl-agent
cordis.yml"] - plugin_repl_hmr["hmr
@cordisjs/plugin-hmr"] - cfg --> plugin_repl_hmr - plugin_repl_llm_deepseek["llm-deepseek
@deepseek-ai/dsh-llm-deepseek"] - cfg --> plugin_repl_llm_deepseek - plugin_repl_bash["bash
@deepseek-ai/dsh-bash-local"] - cfg --> plugin_repl_bash - plugin_repl_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-demo"] - cfg --> plugin_repl_stdio_agent - plugin_repl_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"] - plugin_repl_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] - plugin_repl_stdio_agent --> frontdoor_stdio["@deepseek-ai/dsh-stdio
pre-created main agent"] - bundle_agent_core --> spine_llm["ctx.llm"] - bundle_agent_core --> spine_sessions["ctx.sessions"] - bundle_agent_core --> spine_tools["ctx.tools + tool-bash"] - bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"] - plugin_repl_token_meter["token-meter
@deepseek-ai/dsh-token-meter"] - cfg --> plugin_repl_token_meter - plugin_repl_tool_result_prune["tool-result-prune
@deepseek-ai/dsh-compact-tool-result-prune"] - cfg --> plugin_repl_tool_result_prune - plugin_repl_compact_basic["compact-basic
@deepseek-ai/dsh-compact-basic"] - cfg --> plugin_repl_compact_basic - plugin_repl_subagent["subagent
@deepseek-ai/dsh-subagent"] - cfg --> plugin_repl_subagent - plugin_repl_subagent_spawn["subagent-spawn
@deepseek-ai/dsh-subagent-spawn"] - cfg --> plugin_repl_subagent_spawn - plugin_repl_subagent_fork["subagent-fork
@deepseek-ai/dsh-subagent-fork"] - cfg --> plugin_repl_subagent_fork - plugin_repl_tool_subagent["tool-subagent
@deepseek-ai/dsh-tool-subagent"] - cfg --> plugin_repl_tool_subagent - plugin_repl_tool_subagent_fork["tool-subagent-fork
@deepseek-ai/dsh-tool-subagent"] - cfg --> plugin_repl_tool_subagent_fork - plugin_repl_workflow_workerthread["workflow-workerthread
@deepseek-ai/dsh-workflow-workerthread"] - cfg --> plugin_repl_workflow_workerthread - plugin_repl_tool_workflow["tool-workflow
@deepseek-ai/dsh-tool-workflow"] - cfg --> plugin_repl_tool_workflow - plugin_repl_tool_ralph["tool-ralph
@deepseek-ai/dsh-tool-ralph"] - cfg --> plugin_repl_tool_ralph - plugin_repl_tool_todo["tool-todo
@deepseek-ai/dsh-tool-todo"] - cfg --> plugin_repl_tool_todo - plugin_repl_fs_local["fs-local
@deepseek-ai/dsh-fs-local"] - cfg --> plugin_repl_fs_local - plugin_repl_fs_policy["fs-policy
@deepseek-ai/dsh-fs-policy"] - cfg --> plugin_repl_fs_policy - plugin_repl_tool_fs["tool-fs
@deepseek-ai/dsh-tool-fs"] - cfg --> plugin_repl_tool_fs - plugin_repl_tool_fs_search["tool-fs-search
@deepseek-ai/dsh-tool-fs-search"] - cfg --> plugin_repl_tool_fs_search - plugin_repl_timeout_policy["timeout-policy
@deepseek-ai/dsh-timeout-policy"] - cfg --> plugin_repl_timeout_policy - plugin_repl_spill_local["spill-local
@deepseek-ai/dsh-spill-local"] - cfg --> plugin_repl_spill_local - plugin_repl_spill_policy["spill-policy
@deepseek-ai/dsh-spill-policy"] - cfg --> plugin_repl_spill_policy -``` - -| Plugin id | Package / module | -| --- | --- | -| `hmr` | `@cordisjs/plugin-hmr` | -| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | -| `bash` | `@deepseek-ai/dsh-bash-local` | -| `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` | -| `token-meter` | `@deepseek-ai/dsh-token-meter` | -| `tool-result-prune` | `@deepseek-ai/dsh-compact-tool-result-prune` | -| `compact-basic` | `@deepseek-ai/dsh-compact-basic` | -| `subagent` | `@deepseek-ai/dsh-subagent` | -| `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` | -| `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` | -| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` | -| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` | -| `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` | -| `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` | -| `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` | -| `tool-todo` | `@deepseek-ai/dsh-tool-todo` | -| `fs-local` | `@deepseek-ai/dsh-fs-local` | -| `fs-policy` | `@deepseek-ai/dsh-fs-policy` | -| `tool-fs` | `@deepseek-ai/dsh-tool-fs` | -| `tool-fs-search` | `@deepseek-ai/dsh-tool-fs-search` | -| `timeout-policy` | `@deepseek-ai/dsh-timeout-policy` | -| `spill-local` | `@deepseek-ai/dsh-spill-local` | -| `spill-policy` | `@deepseek-ai/dsh-spill-policy` | - -Source config: [`examples/repl-agent/cordis.yml`](cordis.yml). - -Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source. diff --git a/examples/repl-agent/cordis.yml b/examples/repl-agent/cordis.yml deleted file mode 100644 index 284a19a2d8..0000000000 --- a/examples/repl-agent/cordis.yml +++ /dev/null @@ -1,148 +0,0 @@ -# Readline coding REPL with swappable DeepSeek and local-bash backends. -# `dsh-stdio-demo` supplies the agent spine, workspace instructions, generic -# task controls, JSONL persistence, the line-oriented front door, and `main`. -# HMR remains a leaf because it requires Loader internals; `demo:repl` passes -# `--expose-internals`. The app bin loads the gitignored root `.env`; this file -# reads `DEEPSEEK_API_KEY` and optional `DEEPSEEK_BASE_URL` through `!!js`. - -# Hot-module reload for the dev/demo loop (needs `node --expose-internals`). -- id: hmr - name: '@cordisjs/plugin-hmr' - config: - root: ['.'] - -# The native DeepSeek adapter. -- id: llm-deepseek - name: '@deepseek-ai/dsh-llm-deepseek' - config: - apiKey: !!js process.env.DEEPSEEK_API_KEY - baseURL: !!js process.env.DEEPSEEK_BASE_URL - -# Local executor for the app bundle's bash tool. -- id: bash - name: '@deepseek-ai/dsh-bash-local' - config: - timeoutMs: 60000 - -# The app bundle pre-creates the REPL's `main` agent. -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' - config: - provider: deepseek - model: deepseek-v4-flash - # Set RESUME_SESSION_ID to continue a prior persisted session (the ids live - # under ./.sessions); unset starts a fresh session each run. - resumeSessionId: !!js process.env.RESUME_SESSION_ID - persistenceRoot: './.sessions' - workspaceContext: - maxBytes: 65536 - welcome: 'agent REPL ready. Give it a coding task.' - ui: - mode: readline - # Keep the persona to identity and behavior; tool plugins own tool guidance. - # The loop resolves {{model}} from this agent's configuration. - persona: | - You are a coding agent powered by the {{model}} model. - - Verify your work by running the code or tests. Keep answers brief and - factual. - -# Replay-aware request pressure with one service-wide context window. -- id: token-meter - name: '@deepseek-ai/dsh-token-meter' - -# Prune oversized tool output without a model call before summary compaction. -- id: tool-result-prune - name: '@deepseek-ai/dsh-compact-tool-result-prune' - -# Summarize an older range after measured pressure or a canonical provider overflow. -# Service-wide policy provides pressure, retention, and one overflow-retry default. -- id: compact-basic - name: '@deepseek-ai/dsh-compact-basic' - -# Expose fresh-child `spawn` and completed-prefix `fork` through independent -# in-process backends. Each tool instance needs a distinct `toolName`; the registry -# rejects duplicates. These leaves follow the app because it provides `ctx.agents` and `ctx.tools`. -- id: subagent - name: '@deepseek-ai/dsh-subagent' - -- id: subagent-spawn - name: '@deepseek-ai/dsh-subagent-spawn' - config: - providerName: spawn - -- id: subagent-fork - name: '@deepseek-ai/dsh-subagent-fork' - config: - providerName: fork - -- id: tool-subagent - name: '@deepseek-ai/dsh-tool-subagent' - config: - provider: spawn - toolName: subagent - maxDepth: 1 - -- id: tool-subagent-fork - name: '@deepseek-ai/dsh-tool-subagent' - config: - provider: fork - toolName: subagent_fork - maxDepth: 1 - - -# The worker-thread workflow engine fans a model-written JavaScript script's -# `agent()` calls out through the spawn backend; the adjacent tool exposes it to the model. -- id: workflow-workerthread - name: '@deepseek-ai/dsh-workflow-workerthread' - config: - provider: spawn - -- id: tool-workflow - name: '@deepseek-ai/dsh-tool-workflow' - -- id: tool-ralph - name: '@deepseek-ai/dsh-tool-ralph' -# `todo_write` replaces the logged whole list and renders as a stdio checklist or ACP plan. -- id: tool-todo - name: '@deepseek-ai/dsh-tool-todo' - -# Policy loads before the model-facing filesystem tools so writes and edits require -# an observed file. This single-session app resolves relative paths from the process cwd. -- id: fs-local - name: '@deepseek-ai/dsh-fs-local' - config: - cwd: !!js process.cwd() - -- id: fs-policy - name: '@deepseek-ai/dsh-fs-policy' - -- id: tool-fs - name: '@deepseek-ai/dsh-tool-fs' - -# Bash-backed discovery tools (glob/grep): if the local bash executor above -# can find rg, register fixed ripgrep commands — not ctx.fs. Capped results -# save the complete formatted list through the spill backend below -# (ctx.spillStore, optional). -- id: tool-fs-search - name: '@deepseek-ai/dsh-tool-fs-search' - -# The tool-call timeout enforcer: arms each declared ToolDefinition.timeoutMs -# (the search tools above declare 30s) as a deadline on exec.signal. Without -# it a declared budget is advisory and only the bash executor's own timeout -# backstop applies. -- id: timeout-policy - name: '@deepseek-ai/dsh-timeout-policy' - -# Tool-output spill stack: a local backend that saves oversized tool text under -# a private session-scoped dir, and the tools/post-execute policy that replaces -# an over-budget plain-text result with a preview + the spill locator/retrieval -# hint. A leaf pair after the app (needs ctx.tools). The policy is a no-op until -# a tool returns more than maxInlineBytes of plain text. -- id: spill-local - name: '@deepseek-ai/dsh-spill-local' - -- id: spill-policy - name: '@deepseek-ai/dsh-spill-policy' - config: - maxInlineBytes: 50000 diff --git a/examples/repl-agent/package.json b/examples/repl-agent/package.json deleted file mode 100644 index 34c7db6918..0000000000 --- a/examples/repl-agent/package.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "repl-agent-example", - "private": true, - "version": "0.0.1", - "type": "module", - "description": "Runnable demo: an agent REPL UI with DeepSeek V4 and coding tools" -} diff --git a/examples/repl-agent/tests/code-mode-keyless-smoke.e2e.ts b/examples/repl-agent/tests/code-mode-keyless-smoke.e2e.ts deleted file mode 100644 index dd4239a2c4..0000000000 --- a/examples/repl-agent/tests/code-mode-keyless-smoke.e2e.ts +++ /dev/null @@ -1,27 +0,0 @@ -import { fileURLToPath } from 'node:url' -import { describe, expect, it } from 'vitest' -import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' - -/** - * Keyless Loader-path smoke for the Code Mode overlay: boot the real include - * tree through stdio-agent and `code-mode.cordis.yml`, then close stdin without - * a prompt and assert the banner. No model or `run_code` turn runs. - */ - -const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url)) -const configPath = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url)) -const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) - -describe('code-mode overlay keyless smoke (real code-mode.cordis.yml via the Loader)', () => { - it('boots the Code Mode plugin tree, prints its banner, and exits cleanly on EOF', async () => { - const { stdout } = await runLoaderSmoke({ - label: 'code-mode overlay', - tempDirPrefix: 'code-mode-smoke-', - binScript, - configPath, - tsconfigPath, - env: { DEEPSEEK_API_KEY: 'keyless-smoke-no-call' }, - }) - expect(stdout).toContain('code-mode agent ready.') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) -}) diff --git a/examples/repl-agent/tests/keyless-smoke.e2e.ts b/examples/repl-agent/tests/keyless-smoke.e2e.ts deleted file mode 100644 index 62eb43f55a..0000000000 --- a/examples/repl-agent/tests/keyless-smoke.e2e.ts +++ /dev/null @@ -1,28 +0,0 @@ -import { fileURLToPath } from 'node:url' -import { describe, expect, it } from 'vitest' -import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' - -/** - * Keyless Loader-path smoke for examples/repl-agent: boot the real example - * through the stdio-agent bin and its `cordis.yml`, then close stdin without a - * prompt and assert the banner. The dummy key satisfies adapter construction; - * immediate EOF guarantees there is no model call. - */ - -const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url)) -const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) - -describe('repl-agent keyless smoke (real cordis.yml via the Loader)', () => { - it('boots the full plugin tree, prints its banner, and exits cleanly on EOF', async () => { - const { stdout } = await runLoaderSmoke({ - label: 'repl-agent', - tempDirPrefix: 'repl-smoke-', - binScript, - configPath, - tsconfigPath, - env: { DEEPSEEK_API_KEY: 'keyless-smoke-no-call' }, - }) - expect(stdout).toContain('agent REPL ready.') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) -}) diff --git a/examples/tui-agent/README.md b/examples/tui-agent/README.md index fb8b10e7f4..8cd95e896b 100644 --- a/examples/tui-agent/README.md +++ b/examples/tui-agent/README.md @@ -1,6 +1,6 @@ # tui-agent -The full-screen terminal counterpart to the [`repl-agent`](../repl-agent/README.md) readline REPL and [`acp-agent`](../acp-agent/README.md) server. It reuses the coding agent's backends and tool composition, then fixes the shared terminal app to the `dsh-tui` front door. +The full-screen interactive coding agent: DeepSeek V4, local bash and filesystem tools, compaction, subagents, workflows and fresh-agent Ralph iteration, `todo_write`, timeout/spill policy, and [`@deepseek-ai/dsh-tui-demo`](../../packages/examples/tui-demo). ## Run it @@ -8,16 +8,16 @@ The full-screen terminal counterpart to the [`repl-agent`](../repl-agent/README. pnpm run demo:tui ``` -The command needs `DEEPSEEK_API_KEY` in the environment or the gitignored repository-root `.env`. Set `RESUME_SESSION_ID` to reopen a persisted conversation under `./.sessions`. +The command needs `DEEPSEEK_API_KEY` in the environment or gitignored repository-root `.env`. Set `RESUME_SESSION_ID` to reopen a persisted conversation under `./.sessions`. -The TUI renders Markdown history, reasoning, tool-owned terminal/diff/generic cards, token totals, and the latest todo list. Enter submits or steers while the agent is running; Ctrl+O expands cards, Ctrl+R toggles reasoning, Escape cancels, and `/help` lists commands. `ask_user_question` opens a keyboard-driven overlay. +The TUI renders Markdown history, reasoning, tool-owned terminal/diff/generic cards, token totals, and the latest todo list. Enter submits or steers while the agent runs; Ctrl+O expands cards, Ctrl+R toggles reasoning, Escape cancels, and `/help` lists commands. `ask_user_question` opens a keyboard-driven overlay. -Run `pnpm run demo:code-mode tui` for the sibling Code Mode overlay. +Run `pnpm run demo:code-mode tui` for the Code Mode overlay. ## Composition -[`cordis.yml`](cordis.yml) includes the readline repl-agent leaf so the LLM, bash, filesystem, compaction, subagent, workflow, todo, timeout, and spill choices have one owner. Its asserted patch replaces only the terminal app config and forces `ui.mode: tui`; [`code-mode.cordis.yml`](code-mode.cordis.yml) applies the same front-door patch to the repl-agent Code Mode overlay. +[`cordis.yml`](cordis.yml) owns the interactive coding composition directly. [`code-mode.cordis.yml`](code-mode.cordis.yml) includes that leaf and replaces the tool presentation mode while adding the code runtime. Non-interactive automation uses the sibling [headless-agent](../headless-agent/README.md) composition. ## Snapshot tests -`tests/snapshots//session.jsonl` supplies recorded user prompts and model chunks; sibling child logs drive subagents and workflows. The keyless suite executes those scripts through the real loop and tool implementations, then compares readable expected terminal cell/style output. Use `pnpm run test:snapshot:refresh` for presentation-only changes and `pnpm run test:snapshot:record` with a DeepSeek key when a recorded model journey changes. The implemented [TUI snapshot Agent Note](../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns the scenario matrix and the split between recorded journeys, transient package snapshots, and PTY coverage. +`tests/snapshots//session.jsonl` supplies recorded user prompts and model chunks; sibling child logs drive subagents and workflows. The keyless suite executes those scripts through the real loop and tools, then compares readable terminal cell/style output. Use `pnpm run test:snapshot:refresh` for presentation-only changes and `pnpm run test:snapshot:record` with a DeepSeek key when a recorded model journey changes. The implemented [TUI snapshot Agent Note](../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns the scenario matrix. diff --git a/examples/tui-agent/code-mode.cordis.yml b/examples/tui-agent/code-mode.cordis.yml index 75d2cea38a..45f5a7af04 100644 --- a/examples/tui-agent/code-mode.cordis.yml +++ b/examples/tui-agent/code-mode.cordis.yml @@ -1,12 +1,12 @@ -# Code Mode keeps the TUI front door while reusing the repl-agent overlay's -# worker runtime and one-tool registry composition. +# Code Mode keeps the TUI composition while adding the worker runtime and +# reducing the model-facing registry to the `run_code` transport. - id: base name: '@cordisjs/plugin-include' config: - path: ../repl-agent/code-mode.cordis.yml + path: ./cordis.yml patches: - - id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' + - id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: provider: deepseek model: deepseek-v4-flash @@ -18,13 +18,14 @@ mode: code welcome: 'TUI Code Mode ready. Give it a multi-tool task.' ui: - mode: tui - tui: - showReasoning: true - maxToolOutputLines: 12 + showReasoning: true + maxToolOutputLines: 12 persona: | You are a coding agent powered by the {{model}} model. You work by writing TypeScript programs for run_code: batch related tool work into one program, loop and branch where it helps, and print or return ONLY the findings that matter. + - insert: + - id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' diff --git a/examples/tui-agent/composition.md b/examples/tui-agent/composition.md index 94515c32c4..249d2f6aaf 100644 --- a/examples/tui-agent/composition.md +++ b/examples/tui-agent/composition.md @@ -3,25 +3,91 @@ # TUI Agent App Composition -The TUI agent reuses the repl-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door. +The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package. ```mermaid flowchart LR cfg["examples/tui-agent
cordis.yml"] - plugin_tui_base["base
@deepseek-ai/dsh-stdio-demo"] - cfg --> plugin_tui_base - plugin_tui_base --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"] - plugin_tui_base --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] - plugin_tui_base --> frontdoor_stdio["@deepseek-ai/dsh-tui
pre-created main agent"] + plugin_tui_hmr["hmr
@cordisjs/plugin-hmr"] + cfg --> plugin_tui_hmr + plugin_tui_llm_deepseek["llm-deepseek
@deepseek-ai/dsh-llm-deepseek"] + cfg --> plugin_tui_llm_deepseek + plugin_tui_bash["bash
@deepseek-ai/dsh-bash-local"] + cfg --> plugin_tui_bash + plugin_tui_tui_agent["tui-agent
@deepseek-ai/dsh-tui-demo"] + cfg --> plugin_tui_tui_agent + plugin_tui_tui_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"] + plugin_tui_tui_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] + plugin_tui_tui_agent --> frontdoor_tui["@deepseek-ai/dsh-tui
pre-created main agent"] bundle_agent_core --> spine_llm["ctx.llm"] bundle_agent_core --> spine_sessions["ctx.sessions"] bundle_agent_core --> spine_tools["ctx.tools + tool-bash"] bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"] + plugin_tui_token_meter["token-meter
@deepseek-ai/dsh-token-meter"] + cfg --> plugin_tui_token_meter + plugin_tui_tool_result_prune["tool-result-prune
@deepseek-ai/dsh-compact-tool-result-prune"] + cfg --> plugin_tui_tool_result_prune + plugin_tui_compact_basic["compact-basic
@deepseek-ai/dsh-compact-basic"] + cfg --> plugin_tui_compact_basic + plugin_tui_subagent["subagent
@deepseek-ai/dsh-subagent"] + cfg --> plugin_tui_subagent + plugin_tui_subagent_spawn["subagent-spawn
@deepseek-ai/dsh-subagent-spawn"] + cfg --> plugin_tui_subagent_spawn + plugin_tui_subagent_fork["subagent-fork
@deepseek-ai/dsh-subagent-fork"] + cfg --> plugin_tui_subagent_fork + plugin_tui_tool_subagent["tool-subagent
@deepseek-ai/dsh-tool-subagent"] + cfg --> plugin_tui_tool_subagent + plugin_tui_tool_subagent_fork["tool-subagent-fork
@deepseek-ai/dsh-tool-subagent"] + cfg --> plugin_tui_tool_subagent_fork + plugin_tui_workflow_workerthread["workflow-workerthread
@deepseek-ai/dsh-workflow-workerthread"] + cfg --> plugin_tui_workflow_workerthread + plugin_tui_tool_workflow["tool-workflow
@deepseek-ai/dsh-tool-workflow"] + cfg --> plugin_tui_tool_workflow + plugin_tui_tool_ralph["tool-ralph
@deepseek-ai/dsh-tool-ralph"] + cfg --> plugin_tui_tool_ralph + plugin_tui_tool_todo["tool-todo
@deepseek-ai/dsh-tool-todo"] + cfg --> plugin_tui_tool_todo + plugin_tui_fs_local["fs-local
@deepseek-ai/dsh-fs-local"] + cfg --> plugin_tui_fs_local + plugin_tui_fs_policy["fs-policy
@deepseek-ai/dsh-fs-policy"] + cfg --> plugin_tui_fs_policy + plugin_tui_tool_fs["tool-fs
@deepseek-ai/dsh-tool-fs"] + cfg --> plugin_tui_tool_fs + plugin_tui_tool_fs_search["tool-fs-search
@deepseek-ai/dsh-tool-fs-search"] + cfg --> plugin_tui_tool_fs_search + plugin_tui_timeout_policy["timeout-policy
@deepseek-ai/dsh-timeout-policy"] + cfg --> plugin_tui_timeout_policy + plugin_tui_spill_local["spill-local
@deepseek-ai/dsh-spill-local"] + cfg --> plugin_tui_spill_local + plugin_tui_spill_policy["spill-policy
@deepseek-ai/dsh-spill-policy"] + cfg --> plugin_tui_spill_policy ``` | Plugin id | Package / module | | --- | --- | -| `base` | `@deepseek-ai/dsh-stdio-demo` | +| `hmr` | `@cordisjs/plugin-hmr` | +| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | +| `bash` | `@deepseek-ai/dsh-bash-local` | +| `tui-agent` | `@deepseek-ai/dsh-tui-demo` | +| `token-meter` | `@deepseek-ai/dsh-token-meter` | +| `tool-result-prune` | `@deepseek-ai/dsh-compact-tool-result-prune` | +| `compact-basic` | `@deepseek-ai/dsh-compact-basic` | +| `subagent` | `@deepseek-ai/dsh-subagent` | +| `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` | +| `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` | +| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` | +| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` | +| `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` | +| `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` | +| `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` | +| `tool-todo` | `@deepseek-ai/dsh-tool-todo` | +| `fs-local` | `@deepseek-ai/dsh-fs-local` | +| `fs-policy` | `@deepseek-ai/dsh-fs-policy` | +| `tool-fs` | `@deepseek-ai/dsh-tool-fs` | +| `tool-fs-search` | `@deepseek-ai/dsh-tool-fs-search` | +| `timeout-policy` | `@deepseek-ai/dsh-timeout-policy` | +| `spill-local` | `@deepseek-ai/dsh-spill-local` | +| `spill-policy` | `@deepseek-ai/dsh-spill-policy` | Source config: [`examples/tui-agent/cordis.yml`](cordis.yml). diff --git a/examples/tui-agent/cordis.yml b/examples/tui-agent/cordis.yml index 515274b2a8..7426416204 100644 --- a/examples/tui-agent/cordis.yml +++ b/examples/tui-agent/cordis.yml @@ -1,28 +1,114 @@ -# Full-screen TUI front door over the same repl-agent composition used by the -# readline REPL. The include keeps backends and optional tools aligned; the -# patch owns only the terminal-specific app config. -- id: base - name: '@cordisjs/plugin-include' - config: - path: ../repl-agent/cordis.yml - patches: - - id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' - config: - provider: deepseek - model: deepseek-v4-flash - resumeSessionId: !!js process.env.RESUME_SESSION_ID - persistenceRoot: './.sessions' - workspaceContext: - maxBytes: 65536 - welcome: 'TUI agent ready. Give it a coding task.' - ui: - mode: tui - tui: - showReasoning: true - maxToolOutputLines: 12 - persona: | - You are a coding agent powered by the {{model}} model. +# Full-screen coding agent with swappable DeepSeek and local capability backends. +# `dsh-tui-demo` supplies the spine, workspace instructions, generic task controls, +# JSONL persistence, the TUI front door, and `main`. HMR remains a leaf because +# it requires Loader internals; `demo:tui` passes `--expose-internals`. - Verify your work by running the code or tests. Keep answers brief and - factual. +- id: hmr + name: '@cordisjs/plugin-hmr' + config: + root: ['.'] + +- id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + config: + apiKey: !!js process.env.DEEPSEEK_API_KEY + baseURL: !!js process.env.DEEPSEEK_BASE_URL + +- id: bash + name: '@deepseek-ai/dsh-bash-local' + config: + timeoutMs: 60000 + +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' + config: + provider: deepseek + model: deepseek-v4-flash + resumeSessionId: !!js process.env.RESUME_SESSION_ID + persistenceRoot: './.sessions' + workspaceContext: + maxBytes: 65536 + welcome: 'TUI agent ready. Give it a coding task.' + ui: + showReasoning: true + maxToolOutputLines: 12 + persona: | + You are a coding agent powered by the {{model}} model. + + Verify your work by running the code or tests. Keep answers brief and + factual. + +- id: token-meter + name: '@deepseek-ai/dsh-token-meter' + +- id: tool-result-prune + name: '@deepseek-ai/dsh-compact-tool-result-prune' + +- id: compact-basic + name: '@deepseek-ai/dsh-compact-basic' + +- id: subagent + name: '@deepseek-ai/dsh-subagent' + +- id: subagent-spawn + name: '@deepseek-ai/dsh-subagent-spawn' + config: + providerName: spawn + +- id: subagent-fork + name: '@deepseek-ai/dsh-subagent-fork' + config: + providerName: fork + +- id: tool-subagent + name: '@deepseek-ai/dsh-tool-subagent' + config: + provider: spawn + toolName: subagent + +- id: tool-subagent-fork + name: '@deepseek-ai/dsh-tool-subagent' + config: + provider: fork + toolName: subagent_fork + +- id: workflow-workerthread + name: '@deepseek-ai/dsh-workflow-workerthread' + config: + provider: spawn + +- id: tool-workflow + name: '@deepseek-ai/dsh-tool-workflow' + +# A separate fixed consumer demonstrates fresh-agent Ralph iteration without +# changing the workflow tool or same-session goal behavior. +- id: tool-ralph + name: '@deepseek-ai/dsh-tool-ralph' + +- id: tool-todo + name: '@deepseek-ai/dsh-tool-todo' + +- id: fs-local + name: '@deepseek-ai/dsh-fs-local' + config: + cwd: !!js process.cwd() + +- id: fs-policy + name: '@deepseek-ai/dsh-fs-policy' + +- id: tool-fs + name: '@deepseek-ai/dsh-tool-fs' + +- id: tool-fs-search + name: '@deepseek-ai/dsh-tool-fs-search' + +- id: timeout-policy + name: '@deepseek-ai/dsh-timeout-policy' + +- id: spill-local + name: '@deepseek-ai/dsh-spill-local' + +- id: spill-policy + name: '@deepseek-ai/dsh-spill-policy' + config: + maxInlineBytes: 50000 diff --git a/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml b/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml index e40405524e..f8de00a1a6 100644 --- a/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml +++ b/examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml @@ -12,8 +12,8 @@ config: cwd: !!js process.cwd() -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' config: provider: tui-scripted model: tui-scripted-model @@ -22,6 +22,4 @@ maxBytes: 65536 welcome: 'scripted TUI ready.' ui: - mode: tui - tui: - showReasoning: true + showReasoning: true diff --git a/examples/tui-agent/tests/pty-harness.ts b/examples/tui-agent/tests/pty-harness.ts new file mode 100644 index 0000000000..21d0b4c9d7 --- /dev/null +++ b/examples/tui-agent/tests/pty-harness.ts @@ -0,0 +1,127 @@ +import { spawn } from 'node:child_process' +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' + +const PTY_DRIVER = String.raw` +import errno, json, os, pty, select, signal, sys, time +node, launch_args_json, launch_env_json, cwd, actions_json, expected_exit, timeout_seconds = sys.argv[1:] +env = os.environ.copy() +env.update(json.loads(launch_env_json)) +env.update({"COLUMNS": "100", "LINES": "30"}) +actions = json.loads(actions_json) +pid, fd = pty.fork() +if pid == 0: + os.chdir(cwd) + os.execvpe(node, [node, *json.loads(launch_args_json)], env) + +output = bytearray() +action_index = 0 +deadline = time.monotonic() + float(timeout_seconds) +status = None +while time.monotonic() < deadline: + ready, _, _ = select.select([fd], [], [], 0.05) + if ready: + try: + chunk = os.read(fd, 65536) + except OSError as error: + if error.errno != errno.EIO: + raise + chunk = b"" + if chunk: + output.extend(chunk) + while action_index < len(actions) and actions[action_index]["waitFor"].encode() in output: + os.write(fd, actions[action_index]["send"].encode()) + action_index += 1 + waited, candidate = os.waitpid(pid, os.WNOHANG) + if waited == pid: + status = candidate + break + +if status is None: + os.kill(pid, signal.SIGKILL) + _, status = os.waitpid(pid, 0) +sys.stdout.buffer.write(output) +if action_index != len(actions): + sys.stderr.write(f"completed {action_index}/{len(actions)} PTY actions before timeout\n") + sys.exit(124) +actual_exit = os.waitstatus_to_exitcode(status) +if actual_exit != int(expected_exit): + sys.stderr.write(f"expected exit {expected_exit}, got {actual_exit}\n") + sys.exit(125) +` + +/** One terminal action sent after its marker has rendered. */ +interface TuiPtyAction { + readonly waitFor: string + readonly send: string +} + +/** Inputs for a keyless real-Loader TUI process smoke. */ +export interface TuiPtySmokeOptions { + readonly label: string + readonly tempDirPrefix: string + readonly binScript: string + readonly configPath: string + readonly tsconfigPath: string + readonly actions?: readonly TuiPtyAction[] + readonly env?: Readonly + readonly expectedExitCode?: number + readonly timeoutMs?: number +} + +/** + * Boot an example in a real pseudo-terminal, drive marker-gated input, and + * return the captured terminal bytes after the expected process exit. + * @param options - launch paths, environment, actions, and expected exit code. + * @returns complete pseudo-terminal output. + */ +export async function runTuiPtySmoke(options: TuiPtySmokeOptions): Promise { + const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix)) + const timeoutMs = options.timeoutMs ?? 25_000 + try { + const launch = resolveExampleLaunch({ + srcBin: options.binScript, + configArgs: [options.configPath], + tsconfigPath: options.tsconfigPath, + exposeInternals: true, + env: { + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), + ...options.env, + }, + }) + return await new Promise((resolve, reject) => { + const child = spawn('python3', [ + '-c', + PTY_DRIVER, + launch.command, + JSON.stringify(launch.args), + JSON.stringify(launch.env), + cwd, + JSON.stringify(options.actions ?? []), + String(options.expectedExitCode ?? 0), + String(timeoutMs / 1_000), + ], { stdio: ['ignore', 'pipe', 'pipe'] }) + let stdout = '' + let stderr = '' + child.stdout.setEncoding('utf8') + child.stdout.on('data', (chunk: string) => { stdout += chunk }) + child.stderr.setEncoding('utf8') + child.stderr.on('data', (chunk: string) => { stderr += chunk }) + const timer = setTimeout(() => { + child.kill('SIGKILL') + reject(new Error(`${options.label} PTY driver did not exit. stdout:\n${stdout}\nstderr:\n${stderr}`)) + }, timeoutMs + 5_000) + child.once('error', (error) => { clearTimeout(timer); reject(error) }) + child.once('exit', (code) => { + clearTimeout(timer) + if (code === 0) resolve(stdout) + else reject(new Error(`${options.label} PTY driver exited ${String(code)}. stdout:\n${stdout}\nstderr:\n${stderr}`)) + }) + }) + } finally { + await rm(cwd, { recursive: true, force: true }) + } +} diff --git a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts index 7cc8aebe32..21be35eef5 100644 --- a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts +++ b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts @@ -1,157 +1,43 @@ -import { spawn } from 'node:child_process' -import { mkdtemp, rm } from 'node:fs/promises' -import { tmpdir } from 'node:os' -import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' -import { LOADER_SMOKE_TEST_TIMEOUT_MS, resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' +import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke' +import { runTuiPtySmoke } from './pty-harness.ts' -const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url)) +const binScript = fileURLToPath(new URL('../../../packages/examples/tui-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) const scriptedConfigPath = fileURLToPath(new URL('./fixtures/tui-scripted.cordis.yml', import.meta.url)) const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) -const PTY_DRIVER = String.raw` -import errno, json, os, pty, select, signal, sys, time -node, launch_args_json, launch_env_json, cwd, resume_session_id, scenario = sys.argv[1:] -env = os.environ.copy() -env.update(json.loads(launch_env_json)) -env.update({ - "COLUMNS": "100", - "LINES": "30", -}) -if resume_session_id: - env["RESUME_SESSION_ID"] = resume_session_id -pid, fd = pty.fork() -if pid == 0: - os.chdir(cwd) - os.execvpe(node, [node, *json.loads(launch_args_json)], env) - -output = bytearray() -answered_question = False -sent_prompt = False -sent_exit = False -deadline = time.monotonic() + 25 -status = None -while time.monotonic() < deadline: - ready, _, _ = select.select([fd], [], [], 0.05) - if ready: - try: - chunk = os.read(fd, 65536) - except OSError as error: - if error.errno != errno.EIO: - raise - chunk = b"" - if chunk: - output.extend(chunk) - if scenario == "conversation" and not sent_prompt and b"scripted TUI ready." in output: - os.write(fd, b"exercise the TUI\r") - sent_prompt = True - if scenario == "conversation" and sent_prompt and not answered_question and b"How should the scripted run proceed?" in output: - os.write(fd, b"\r") - answered_question = True - if scenario == "conversation" and answered_question and not sent_exit and b"Decision received. Scripted TUI run complete." in output: - os.write(fd, b"/exit\r") - sent_exit = True - if scenario == "boot" and not sent_exit and b"TUI agent ready." in output: - os.write(fd, b"/exit\r") - sent_exit = True - waited, candidate = os.waitpid(pid, os.WNOHANG) - if waited == pid: - status = candidate - break - -if status is None: - os.kill(pid, signal.SIGKILL) - _, status = os.waitpid(pid, 0) -sys.stdout.buffer.write(output) -if scenario == "resume-failure": - if b'ui-tui: session "missing-session" failed to start:' not in output: - sys.stderr.write("TUI did not render the startup failure before timeout\n") - sys.exit(126) - if not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 1: - sys.stderr.write("TUI startup failure did not exit with status 1\n") - sys.exit(127) -elif scenario == "conversation": - if not sent_prompt: - sys.stderr.write("TUI did not render the scripted welcome marker before timeout\n") - sys.exit(128) - if not answered_question: - sys.stderr.write("TUI did not render the user-question dialog before timeout\n") - sys.exit(129) - if not sent_exit: - sys.stderr.write("TUI did not finish the scripted tool round-trip before timeout\n") - sys.exit(130) - if not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 0: - sys.stderr.write("TUI scripted conversation did not exit cleanly\n") - sys.exit(131) -else: - if not sent_exit: - sys.stderr.write("TUI did not render its welcome marker before timeout\n") - sys.exit(124) - if not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 0: - sys.stderr.write("TUI child did not exit cleanly\n") - sys.exit(125) -` - -interface TuiLoaderSmokeOptions { - config?: string - resumeSessionId?: string - scenario?: 'boot' | 'conversation' | 'resume-failure' -} - -async function runTuiLoaderSmoke(options: TuiLoaderSmokeOptions = {}): Promise { - const cwd = await mkdtemp(join(tmpdir(), 'tui-agent-smoke-')) - try { - const launch = resolveExampleLaunch({ - srcBin: binScript, - configArgs: [options.config ?? configPath], - tsconfigPath, - exposeInternals: true, - env: { - DEEPSEEK_API_KEY: 'keyless-tui-no-call', - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - }, - }) - return await new Promise((resolve, reject) => { - const child = spawn('python3', [ - '-c', - PTY_DRIVER, - launch.command, - JSON.stringify(launch.args), - JSON.stringify(launch.env), - cwd, - options.resumeSessionId ?? '', - options.scenario ?? 'boot', - ], { stdio: ['ignore', 'pipe', 'pipe'] }) - let stdout = '' - let stderr = '' - child.stdout.setEncoding('utf8') - child.stdout.on('data', (chunk: string) => { stdout += chunk }) - child.stderr.setEncoding('utf8') - child.stderr.on('data', (chunk: string) => { stderr += chunk }) - child.once('error', reject) - child.once('exit', (code) => { - if (code === 0) resolve(stdout) - else reject(new Error(`TUI PTY smoke exited ${String(code)}. stdout:\n${stdout}\nstderr:\n${stderr}`)) - }) - }) - } finally { - await rm(cwd, { recursive: true, force: true }) - } -} - -describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => { +// The Python PTY driver imports the POSIX-only pty and termios modules. +describe.skipIf(process.platform === 'win32')('tui-agent keyless smoke (real Loader tree in a PTY)', () => { it('boots pi-tui, renders the configured banner, accepts /exit, and restores the terminal', async () => { - const output = await runTuiLoaderSmoke() + const output = await runTuiPtySmoke({ + label: 'tui-agent boot', + tempDirPrefix: 'tui-agent-smoke-', + binScript, + configPath, + tsconfigPath, + env: { DEEPSEEK_API_KEY: 'keyless-tui-no-call' }, + actions: [{ waitFor: 'TUI agent ready.', send: '/exit\r' }], + }) expect(output).toContain('DEEPSEEK') expect(output).toContain('TUI agent ready.') expect(output).toContain('\u001B[?2004l') }, LOADER_SMOKE_TEST_TIMEOUT_MS) it('streams a response, answers a user-question dialog, completes the tool round-trip, and exits cleanly', async () => { - const output = await runTuiLoaderSmoke({ config: scriptedConfigPath, scenario: 'conversation' }) + const output = await runTuiPtySmoke({ + label: 'tui-agent conversation', + tempDirPrefix: 'tui-agent-conversation-', + binScript, + configPath: scriptedConfigPath, + tsconfigPath, + actions: [ + { waitFor: 'scripted TUI ready.', send: 'exercise the TUI\r' }, + { waitFor: 'How should the scripted run proceed?', send: '\r' }, + { waitFor: 'Decision received. Scripted TUI run complete.', send: '/exit\r' }, + ], + }) expect(output).toContain('I need one decision before I continue.') expect(output).toContain(String.raw`\x1b]2;MODEL_CONTROLLED\x07`) expect(output).toContain(String.raw`\x1b[999CMODEL_CURSOR`) @@ -159,14 +45,23 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => { expect(output).not.toContain('\u001B]2;MODEL_CONTROLLED\u0007') expect(output).not.toContain('\u001B[999CMODEL_CURSOR') expect(output).not.toContain('\u009B31mMODEL_C1') - expect(output).toContain('How should the scripted run proceed?') expect(output).toContain('Safe') - expect(output).toContain('Decision received. Scripted TUI run complete.') expect(output).toContain('\u001B[?2004l') }, LOADER_SMOKE_TEST_TIMEOUT_MS) it('prints a config-resume failure and exits instead of leaving a blank terminal', async () => { - const output = await runTuiLoaderSmoke({ resumeSessionId: 'missing-session', scenario: 'resume-failure' }) + const output = await runTuiPtySmoke({ + label: 'tui-agent resume failure', + tempDirPrefix: 'tui-agent-resume-', + binScript, + configPath, + tsconfigPath, + env: { + DEEPSEEK_API_KEY: 'keyless-tui-no-call', + RESUME_SESSION_ID: 'missing-session', + }, + expectedExitCode: 1, + }) expect(output).toContain('ui-tui: session "missing-session" failed to start:') }, LOADER_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/knip.json b/knip.json index 0e742eb989..9cc4a658be 100644 --- a/knip.json +++ b/knip.json @@ -9,9 +9,10 @@ }, "examples": { "entry": [ - "echo-agent/src/*.ts", - "echo-agent/tests/fixtures/goal/goal/seed-goal.ts", "headless-agent/tests/fixtures/cli-mock-llm.ts", + "headless-agent/tests/fixtures/goal-domain/seed-goal.ts", + "headless-agent/tests/fixtures/time-context-driver.ts", + "headless-agent/tests/fixtures/time-context-mock-llm.ts", "tui-agent/tests/fixtures/tui-scripted-llm.ts", "*/tests/**/*.e2e.ts", "*/tests/**/*.snapshot.ts" @@ -138,18 +139,14 @@ "entry": ["tests/**/*.spec.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, - "packages/examples/stdio-demo": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "packages/examples/tui-demo": { + "entry": ["tests/**/*.spec.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/examples/cli-demo": { "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, - "packages/ui/stdio": { - "entry": ["tests/**/*.spec.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] - }, "packages/ui/tui": { "entry": ["tests/**/*.spec.ts", "tests/**/*.snapshot.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] diff --git a/package.json b/package.json index 995a2bf998..5c831f6497 100644 --- a/package.json +++ b/package.json @@ -78,12 +78,10 @@ "constraints": "tsx scripts/check-workspace-constraints.ts", "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-events && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-agent-note-classification && pnpm run verify-agent-note-format && pnpm run verify-type-equiv && pnpm run verify-translation-prompt && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations && pnpm run docs:check", "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure", - "demo:echo": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml", - "demo:repl": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/repl-agent/cordis.yml", "demo:headless": "node --expose-internals --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml", - "demo:tui": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/tui-agent/cordis.yml", + "demo:tui": "node --expose-internals --import tsx packages/examples/tui-demo/src/bin.ts examples/tui-agent/cordis.yml", "demo:code-mode": "node scripts/demo-code-mode.mjs", - "demo:cordis": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/cordis-agent/cordis.yml", + "demo:cordis": "node --expose-internals --import tsx packages/examples/tui-demo/src/bin.ts examples/cordis-agent/cordis.yml", "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, diff --git a/packages/README.md b/packages/README.md index 4521500d14..c491ab2cc3 100644 --- a/packages/README.md +++ b/packages/README.md @@ -32,7 +32,7 @@ Packages live at `packages///`; groups are containers, while names r | [`session-query/`](session-query/README.md) | Session retrieval: logical corpus, bounded reads, lineage, and event relationships | Product — stable surface | | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface | | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface | -| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/one-shot CLI/ACP/JSON-RPC bins) the leaves load | Support — example infra | +| [`examples/`](examples/README.md) | Demo bundles (agent-spine + TUI/one-shot CLI/ACP/JSON-RPC bins) the leaves load | Support — example infra | | [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations | | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free | diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts index d01167de3d..7d04dfe952 100644 --- a/packages/bash/tool-bash/tests/integration.spec.ts +++ b/packages/bash/tool-bash/tests/integration.spec.ts @@ -23,7 +23,9 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent async function harness(adapter: MockAdapter, sessionRoot?: string, dshHome?: string) { const ctx = new Context() await mountAgentLoopTestDependencies(ctx) - if (sessionRoot !== undefined) await ctx.plugin(SessionPersistenceJsonl, { root: sessionRoot }) + if (sessionRoot !== undefined) { + await ctx.plugin(SessionPersistenceJsonl, { root: sessionRoot, compression: 'none' }) + } await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(TaskService) await ctx.plugin(ToolTasks) diff --git a/packages/context/time-context/tests/time-context.e2e.ts b/packages/context/time-context/tests/time-context.e2e.ts index f14981ea36..2a0c06fe51 100644 --- a/packages/context/time-context/tests/time-context.e2e.ts +++ b/packages/context/time-context/tests/time-context.e2e.ts @@ -1,34 +1,21 @@ -import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process' -import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises' -import { tmpdir } from 'node:os' +import { readFile, readdir } from 'node:fs/promises' import { join } from 'node:path' import { fileURLToPath } from 'node:url' -import { afterEach, describe, expect, it } from 'vitest' +import { describe, expect, it } from 'vitest' import { type SessionEvent } from '@deepseek-ai/dsh-session' -import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' +import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' // Keep the Loader config under examples so both modes exercise the same deployable // topology: local fixture source plus bare plugins owned by the examples workspace. -const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url)) +const driver = fileURLToPath(new URL( + '../../../../examples/headless-agent/tests/fixtures/time-context-driver.ts', + import.meta.url, +)) const configPath = fileURLToPath(new URL( - '../../../../examples/echo-agent/tests/fixtures/context/time-context/cordis.yml', + '../../../../examples/headless-agent/tests/fixtures/time-context.cordis.yml', import.meta.url, )) const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) -const PROCESS_TIMEOUT_MS = 30_000 -const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000 -const FIRST_REPLY = '[main turn 1] You said: "Time sampled while preparing turn 1, step 1:' -const SECOND_REPLY = '[main turn 2] You said: "Time sampled while preparing turn 2, step 1:' - -let child: ChildProcessWithoutNullStreams | undefined -let workdir: string | undefined - -afterEach(async () => { - if (child !== undefined && child.exitCode === null) child.kill('SIGKILL') - child = undefined - if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) - workdir = undefined -}) async function jsonlFiles(dir: string): Promise { const entries = await readdir(dir, { withFileTypes: true }) @@ -40,68 +27,25 @@ async function jsonlFiles(dir: string): Promise { return paths.flat() } -async function runTwoTurns(): Promise<{ stdout: string; stderr: string }> { - workdir = await mkdtemp(join(tmpdir(), 'time-context-e2e-')) - const cwd = workdir - return new Promise((resolve, reject) => { - const launch = resolveExampleLaunch({ - srcBin: binScript, - configArgs: [configPath], +describe('time-context through a real headless cordis.yml', () => { + it('uses the process zone and persists one ordered context event per request', async () => { + let events: SessionEvent[] = [] + const { stderr } = await runLoaderSmoke({ + label: 'time-context headless smoke', + tempDirPrefix: 'time-context-e2e-', + binScript: driver, + libBinScript: driver, + configPath, tsconfigPath: repoTsconfig, - exposeInternals: true, - env: { - TZ: 'Asia/Shanghai', - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), + env: { TZ: 'Asia/Shanghai' }, + inspect: async (cwd) => { + const logs = await jsonlFiles(join(cwd, '.sessions')) + expect(logs).toHaveLength(1) + const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n') + events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent) }, }) - const proc = spawn(launch.command, launch.args, { - cwd, - env: { ...process.env, ...launch.env }, - stdio: ['pipe', 'pipe', 'pipe'], - }) - child = proc - let stdout = '' - let stderr = '' - let sentSecond = false - proc.stdout.setEncoding('utf8') - proc.stdout.on('data', (chunk: string) => { - stdout += chunk - if (!sentSecond && stdout.includes(FIRST_REPLY) && stdout.includes('Try "echo " to see a tool call.\n> ')) { - sentSecond = true - proc.stdin.end('second\n') - } - }) - proc.stderr.setEncoding('utf8') - proc.stderr.on('data', (chunk: string) => { stderr += chunk }) - - const timer = setTimeout(() => { - proc.kill('SIGKILL') - reject(new Error(`time-context e2e did not exit within ${PROCESS_TIMEOUT_MS / 1_000}s. stdout:\n${stdout}\nstderr:\n${stderr}`)) - }, PROCESS_TIMEOUT_MS) - - proc.on('exit', (code) => { - clearTimeout(timer) - if (code === 0) resolve({ stdout, stderr }) - else reject(new Error(`time-context e2e exited ${code}. stdout:\n${stdout}\nstderr:\n${stderr}`)) - }) - proc.on('error', (error) => { clearTimeout(timer); reject(error) }) - proc.stdin.write('first\n') - }) -} - -describe('time-context through a real cordis.yml and stdio process', () => { - it('uses the process zone and persists one ordered context event per request', async () => { - const { stdout, stderr } = await runTwoTurns() expect(stderr).not.toContain('UNHANDLED') - expect(stdout).toContain('time-context e2e ready.') - expect(stdout).toContain(FIRST_REPLY) - expect(stdout).toContain(SECOND_REPLY) - - const logs = await jsonlFiles(join(workdir as string, '.sessions')) - expect(logs).toHaveLength(1) - const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n') - const events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent) expect(events.filter(event => event.type === 'turn/end')).toHaveLength(2) const contexts = events.filter(event => event.type === 'context/message') @@ -127,5 +71,5 @@ describe('time-context through a real cordis.yml and stdio process', () => { const headers = events.filter(event => event.type === 'request/header') expect(JSON.stringify(headers)).not.toContain('Time sampled while preparing') - }, TEST_TIMEOUT_MS) + }, LOADER_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts index 99a68b062f..995881902e 100644 --- a/packages/cordis/tool-cordis/src/sandbox.ts +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -15,7 +15,7 @@ import { sandboxDefineTool, sandboxRegisterTool } from './guard.ts' * A write-through console for one sandbox, tagging every line with the mount * id. Write-through (host stdout/stderr), NOT buffered into the tool result: * a mounted listener fires long after the mount call returned, and its output - * must land somewhere the user can see — for the stdio demo, the terminal. + * must land somewhere the user can see — for a terminal front door, the host terminal. */ function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | 'debug', (...args: unknown[]) => void> { const tag = `[cordis:${id}]` diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 0d39004687..847a15d64f 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -10,7 +10,7 @@ import type { Context } from 'cordis' import { agentEvents } from '@deepseek-ai/dsh-agent' import type { AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' -import { deepFreeze } from '@deepseek-ai/dsh-llm' +import { deepFreeze, errorChain } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm' import { snapshotJsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session' import { Inbox, type InboxMessage } from './inbox.ts' @@ -80,7 +80,6 @@ export function prepareReactLoopAgent( }, } } - /** * Install the concrete agent's scope context exactly once. Construction and * scope minting are mutually referential (the scope key is the agent), so the @@ -290,7 +289,7 @@ export class ReactLoopAgent implements Agent { if (turnRecorded) { // Through the store's flush (the carrier owner), never a raw parallel. const flush = this.loopCtx.sessions.flush(this.session).catch((error: unknown) => { - const rendered = renderThrown(error) + const rendered = errorChain(error) const err = error instanceof Error ? error : new Error(rendered) this.loopCtx.logger.warn(`agent "${this.id}": flush after idle injection failed: ${rendered}`) agentEvents(this.loopCtx, this).emit('agent/error', turn, 0, err) @@ -449,8 +448,3 @@ export class ReactLoopAgent implements Agent { } } } - -/** Render an ordinary thrown value for the error event and log. */ -function renderThrown(value: unknown): string { - return value instanceof Error ? value.message : String(value) -} diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts index 7268182552..bdaa3f2401 100644 --- a/packages/core/agent-loop/src/index.ts +++ b/packages/core/agent-loop/src/index.ts @@ -20,7 +20,7 @@ import type { ResumeAgentOptions, SessionStartSource, } from '@deepseek-ai/dsh-agent' -import type {} from '@deepseek-ai/dsh-llm' +import { errorChain } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { Session, SessionHeader } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-system-prompt' @@ -41,15 +41,6 @@ const INACTIVE_STATES: ReadonlySet = new Set([ FiberState.FAILED, ]) -/** Render an arbitrary thrown value without letting coercion escape containment. */ -function renderThrown(value: unknown): string { - try { - return String(value) - } catch { - return '' - } -} - /** Factory-level ownership of every preparing or live transaction. */ class FactoryOwnership { private accepting = true @@ -475,16 +466,16 @@ export class AgentLoop extends Service implements AgentFactory { error: unknown, ): void { if (!this.ownership.isActive()) return - this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${renderThrown(error)}`) + this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${errorChain(error)}`) const args: unknown[] = ['agent-loop/config-start-failed', sessionId, error] for (const callback of this.ctx.events.dispatch('emit', args)) { try { const returned: unknown = callback(...args) void Promise.resolve(returned).catch((listenerError: unknown) => { - this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${renderThrown(listenerError)}`) + this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${errorChain(listenerError)}`) }) } catch (listenerError: unknown) { - this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${renderThrown(listenerError)}`) + this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${errorChain(listenerError)}`) } } } diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index e8008996a9..f7e907ae83 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -8,7 +8,7 @@ import type { Context } from 'cordis' import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm' import { isDeepStrictEqual } from 'node:util' -import { BlockAssembler, HarnessError, assertNever, deepFreeze, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm' +import { BlockAssembler, HarnessError, assertNever, deepFreeze, errorChain, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm' import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent' import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' @@ -56,9 +56,12 @@ function finishError(finish: FinishReason): RequestError | undefined { /** * Build the `{ message, code? }` part of an error payload, omitting the * `code` key entirely when absent (exactOptionalPropertyTypes-correct). + * The durable message renders the full cause chain: `turn/end` is the single + * durable record of an in-turn failure, so a wrapper message alone (e.g. + * `fetch failed`) would lose the diagnosis the session log exists to keep. */ function errorData(err: RequestError): { message: string; code?: string } { - return { message: err.message, ...typeof err.code === 'string' ? { code: err.code } : {} } + return { message: errorChain(err), ...typeof err.code === 'string' ? { code: err.code } : {} } } /** Map a successful max-token finish onto the turn reason; other successful finishes add nothing. */ @@ -166,7 +169,7 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise { } catch (error: unknown) { // Pre-turn failure has no durable boundary to close; report it without appending outside a turn. const err = toError(error) - ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${err.message}`) + ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${errorChain(err)}`) try { events.emit('agent/error', turn, 0, err) } catch { /* contained: a throwing agent/error listener must not kill the driver */ } @@ -382,7 +385,7 @@ async function runTurn( ) } catch (recoveryError: unknown) { ctx.logger.warn( - `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${toError(recoveryError).message}`, + `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${errorChain(recoveryError)}`, ) } handle.setAbort(undefined) @@ -546,7 +549,7 @@ async function runTurn( } catch (error: unknown) { // The turn is closed, so report the failed flush live rather than append outside a turn. const err = toError(error) - ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${err.message}`) + ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${errorChain(err)}`) try { events.emit('agent/error', turn, step, err) } catch { diff --git a/packages/core/agent-loop/tests/config-session-id.spec.ts b/packages/core/agent-loop/tests/config-session-id.spec.ts index cadc176aea..2103dd6831 100644 --- a/packages/core/agent-loop/tests/config-session-id.spec.ts +++ b/packages/core/agent-loop/tests/config-session-id.spec.ts @@ -47,9 +47,9 @@ describe('config-driven session id', () => { it('accepts one exact fresh id and rejects it alongside a resume id', async () => { const exact = await makeCoreContext() await exact.plugin(AgentLoop, { - agents: [{ id: 'main', sessionId: SessionId('stdio-exact'), model: 'mock' }], + agents: [{ id: 'main', sessionId: SessionId('config-exact'), model: 'mock' }], }) - expect(exact.agents.get(SessionId('stdio-exact'))?.session.id).toBe('stdio-exact') + expect(exact.agents.get(SessionId('config-exact'))?.session.id).toBe('config-exact') await exact.fiber.dispose() const conflicting = await makeCoreContext() @@ -89,13 +89,13 @@ describe('config-driven session id', () => { const ctx = await makeCoreContext() await ctx.plugin(SessionPersistenceJsonl, { root }) ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first'), textResponse('second')])) - const config = { agents: [{ id: 'main', sessionId: SessionId('stdio-exact-reload'), model: 'mock' }] } + const config = { agents: [{ id: 'main', sessionId: SessionId('config-exact-reload'), model: 'mock' }] } const firstLoop = await ctx.plugin(AgentLoop, config) let first: Agent | undefined for (let i = 0; i < 50 && first === undefined; i++) { await new Promise(resolve => setTimeout(resolve, 5)) - first = ctx.agents.get(SessionId('stdio-exact-reload')) + first = ctx.agents.get(SessionId('config-exact-reload')) } expect(first).toBeDefined() first!.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } }) @@ -106,14 +106,14 @@ describe('config-driven session id', () => { let second: Agent | undefined for (let i = 0; i < 50 && second === undefined; i++) { await new Promise(resolve => setTimeout(resolve, 5)) - second = ctx.agents.get(SessionId('stdio-exact-reload')) + second = ctx.agents.get(SessionId('config-exact-reload')) } expect(second).toBeDefined() expect(JSON.stringify(second!.session.deriveMessages())).toContain('remember me') second!.send([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } }) await waitForIdle(ctx, second!) await ctx.sessions.flush(second!.session) - const loaded = await ctx.sessionPersistence.load(SessionId('stdio-exact-reload')) + const loaded = await ctx.sessionPersistence.load(SessionId('config-exact-reload')) expect(loaded.events.filter(event => event.type === 'turn/start')).toHaveLength(2) await secondLoop.dispose() @@ -125,7 +125,7 @@ describe('config-driven session id', () => { dirs.push(root) const ctx = await makeCoreContext() await ctx.plugin(SessionPersistenceJsonl, { root }) - const sessionId = SessionId('stdio-exact-overlap') + const sessionId = SessionId('config-exact-overlap') const config = { agents: [{ id: 'main', sessionId, model: 'mock' }] } const firstLoop = await ctx.plugin(AgentLoop, config) await expect.poll(() => ctx.agents.get(sessionId)).toBeDefined() @@ -169,7 +169,7 @@ describe('config-driven session id', () => { dirs.push(root) const ctx = await makeCoreContext() await ctx.plugin(SessionPersistenceJsonl, { root }) - const sessionId = SessionId('stdio-exact-cancel') + const sessionId = SessionId('config-exact-cancel') const config = { agents: [{ id: 'main', sessionId, model: 'mock' }] } const firstLoop = await ctx.plugin(AgentLoop, config) await expect.poll(() => ctx.agents.get(sessionId)).toBeDefined() @@ -213,20 +213,20 @@ describe('config-driven session id', () => { const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) await ctx.plugin(AgentLoop, { - agents: [{ id: 'main', sessionId: SessionId('stdio-exact-failure'), model: 'mock' }], + agents: [{ id: 'main', sessionId: SessionId('config-exact-failure'), model: 'mock' }], }) await expect.poll(() => warn).toHaveBeenCalledWith(expect.stringContaining( - 'config-driven restore of "stdio-exact-failure" failed: Error: persistence index failed', + 'config-driven restore of "config-exact-failure" failed: persistence index failed', )) - expect(failures).toEqual([{ sessionId: SessionId('stdio-exact-failure'), error: failure }]) + expect(failures).toEqual([{ sessionId: SessionId('config-exact-failure'), error: failure }]) expect(warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener threw: Error: failure observer failed', + 'agent "main": config-start-failed listener threw: failure observer failed', ) await expect.poll(() => warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener rejected: Error: async failure observer failed', + 'agent "main": config-start-failed listener rejected: async failure observer failed', ) - expect(ctx.agents.get(SessionId('stdio-exact-failure'))).toBeUndefined() + expect(ctx.agents.get(SessionId('config-exact-failure'))).toBeUndefined() warn.mockRestore() await ctx.fiber.dispose() }) @@ -251,18 +251,18 @@ describe('config-driven session id', () => { const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) await ctx.plugin(AgentLoop, { - agents: [{ id: 'main', sessionId: SessionId('stdio-exact-unrenderable'), model: 'mock' }], + agents: [{ id: 'main', sessionId: SessionId('config-exact-unrenderable'), model: 'mock' }], }) await expect.poll(() => failures).toEqual([unrenderable]) expect(warn).toHaveBeenCalledWith( - 'agent "main": config-driven restore of "stdio-exact-unrenderable" failed: ', + 'agent "main": config-driven restore of "config-exact-unrenderable" failed: ', ) expect(warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener threw: ', + 'agent "main": config-start-failed listener threw: ', ) await expect.poll(() => warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener rejected: ', + 'agent "main": config-start-failed listener rejected: ', ) await ctx.fiber.dispose() }) @@ -281,7 +281,7 @@ describe('config-driven session id', () => { ctx.on('agent-loop/config-start-failed', (_sessionId, error) => { failures.push(error) }) const loop = await ctx.plugin(AgentLoop, { - agents: [{ id: 'main', sessionId: SessionId('stdio-exact-dispose'), model: 'mock' }], + agents: [{ id: 'main', sessionId: SessionId('config-exact-dispose'), model: 'mock' }], }) let disposed = false const disposal = loop.dispose().then(() => { disposed = true }) @@ -291,7 +291,7 @@ describe('config-driven session id', () => { if (outcome === 'resolve') listing.resolve([]) else listing.reject(new Error('startup cancelled by teardown')) await disposal - expect(ctx.agents.get(SessionId('stdio-exact-dispose'))).toBeUndefined() + expect(ctx.agents.get(SessionId('config-exact-dispose'))).toBeUndefined() expect(failures).toEqual([]) expect(warn).not.toHaveBeenCalled() warn.mockRestore() diff --git a/packages/examples/README.md b/packages/examples/README.md index 32e287456d..c24f1e9173 100644 --- a/packages/examples/README.md +++ b/packages/examples/README.md @@ -5,12 +5,12 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling | Package | npm name | Role | |---|---|---| | `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin, with an opt-in persisted-goal stack | -| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal chat app: the spine + persisted goals + `/goal` command + JSONL persistence + TTY-selected `dsh-tui`/`dsh-stdio` front door + a pre-created `main` agent, with a boot `bin` | +| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | Full-screen terminal app: the spine + persisted goals + `/goal` command + JSONL persistence + `dsh-tui` + a pre-created `main` agent, with a boot `bin` | | `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output | | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + persisted goals + `/goal` command + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` | | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client | -`agent-spine-demo` is the shared bundle; `stdio-demo`, `cli-demo`, and `acp-demo` compose it with terminal, headless one-shot, and ACP front doors and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches. +`agent-spine-demo` is the shared bundle; `tui-demo`, `cli-demo`, and `acp-demo` compose it with full-screen terminal, headless one-shot, and ACP front doors and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches. These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), the bridges/channels/boot-glue in [`ui/`](../ui/README.md), and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely. diff --git a/packages/examples/acp-demo/README.md b/packages/examples/acp-demo/README.md index 3f777b4055..f483532cd5 100644 --- a/packages/examples/acp-demo/README.md +++ b/packages/examples/acp-demo/README.md @@ -2,7 +2,7 @@ The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)) with the front-door cluster an [Agent Client Protocol](../../ui/acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio. -It is the structured counterpart to [`@deepseek-ai/dsh-stdio-demo`](../stdio-demo/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster. +It is the structured counterpart to [`@deepseek-ai/dsh-tui-demo`](../tui-demo/README.md): both consume the same spine, but ACP creates sessions from its client and reserves stdout for its wire protocol. ## What it bakes in — and what it deliberately omits @@ -21,7 +21,7 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it | ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../../ui/acp/README.md)) | | ~~`hmr`~~ | **omitted** — the editor owns the subprocess | -Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends, so the common mistake — copying a console-logger entry from the stdio config — has no place here. (A leaf author technically *can* still add `@cordisjs/plugin-logger-console` as a sibling entry; the package can't forbid that. So the rule stands: never add a stdout logger to an ACP leaf — stdout is the JSON-RPC channel. Use a stderr exporter if you need logs.) +Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends. A leaf author can still add `@cordisjs/plugin-logger-console` as a sibling entry, so the rule remains: never add a stdout logger to an ACP leaf; use a stderr exporter instead. ## Config @@ -40,6 +40,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron | `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` | | `goals` | owner defaults | persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer | | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory | +| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) | The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay), a bash executor, and optionally a `ctx.fs` provider. Workspace context becomes a no-op without `ctx.fs`; the shipped [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) selects `dsh-sandbox-policy`, `dsh-fs-sandbox`, `dsh-fs-policy`, and `dsh-tool-fs` so baseline instructions and model-facing `read`/`write`/`edit` share one provider, sandbox mode, workspace root, and observed-version policy. diff --git a/packages/examples/acp-demo/src/index.ts b/packages/examples/acp-demo/src/index.ts index e44135d8d1..9c74d45878 100644 --- a/packages/examples/acp-demo/src/index.ts +++ b/packages/examples/acp-demo/src/index.ts @@ -17,7 +17,10 @@ import * as commandGoal from '@deepseek-ai/dsh-command-goal' import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo' import * as workspaceContext from '@deepseek-ai/dsh-workspace-context' import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' -import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' +import SessionPersistenceJsonl, { + JsonlCompressionSchema, + type JsonlCompression, +} from '@deepseek-ai/dsh-session-persistence-jsonl' import UserInteractionService from '@deepseek-ai/dsh-user-interaction' export const name = 'acp-demo' @@ -49,6 +52,8 @@ export interface Config { dshHome?: string /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string + /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */ + persistenceCompression?: JsonlCompression /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */ workspaceContext: agentCore.Config['workspaceContext'] /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */ @@ -76,6 +81,7 @@ export const Config: z = z.object({ tools: ToolRegistry.Config, dshHome: z.string(), persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT), + persistenceCompression: JsonlCompressionSchema, workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(), skills: agentCore.SkillConfigSchema, toolBash: agentCore.ToolBashConfigSchema, @@ -97,6 +103,9 @@ export function apply(ctx: Context, config: Config): void { if (goals !== false) ctx.plugin(commandGoal) ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals }) ctx.plugin(UserInteractionService) - ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT }) + ctx.plugin(SessionPersistenceJsonl, { + root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT, + ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }), + }) ctx.plugin(acp, { provider: config.provider, model: config.model }) } diff --git a/packages/examples/acp-demo/tests/acp-agent.spec.ts b/packages/examples/acp-demo/tests/acp-agent.spec.ts index b6886a7e12..52ad60449e 100644 --- a/packages/examples/acp-demo/tests/acp-agent.spec.ts +++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts @@ -12,8 +12,8 @@ import * as acpAgent from '../src/index.ts' /** * In-process unit coverage for the @deepseek-ai/dsh-acp-demo composition: * mounting it brings up the agent-spine-demo spine + JSONL persistence + the ACP - * bridge in one `ctx.plugin`. Unlike the stdio app, this one loads NO - * Loader-only plugin (no hmr), so it mounts in a plain Context. + * bridge in one `ctx.plugin`. It loads no Loader-only plugin (no hmr), so it + * mounts in a plain Context. * * The REAL Loader-path guard (export shape via `unwrapExports`, the headline * ACP operations end-to-end) is the keyless bin smoke in `load-path.e2e.ts`; @@ -70,10 +70,19 @@ async function withIsolatedSkillHomes(run: () => Promise): Promise { describe('dsh-acp-demo composition', () => { it('brings up the spine + persistence + the ACP bridge', async () => { - const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig(), workspaceContext: false }) + const ctx = await mount({ + provider: 'mock', + model: 'mock', + persona: 'hi', + persistenceRoot: '/tmp/dsh-acp-demo-test', + persistenceCompression: 'none', + skills: await isolatedSkillsConfig(), + workspaceContext: false, + }) expect(ctx.get('agents')).toBeDefined() expect(ctx.get('sessions')).toBeDefined() expect(ctx.get('sessionPersistence')).toBeDefined() + expect((ctx.get('sessionPersistence') as unknown as { config: { compression?: string } }).config.compression).toBe('none') expect(ctx.get('agentLoop')).toBeDefined() expect(ctx.get('userInteraction')).toBeDefined() expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined() diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts index 3f90485679..fb6662291e 100644 --- a/packages/examples/acp-demo/tests/built-bin.e2e.ts +++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts @@ -1,5 +1,5 @@ import { spawn } from 'node:child_process' -import { mkdtemp, mkdir, rm, symlink, writeFile, readFile } from 'node:fs/promises' +import { mkdtemp, mkdir, readdir, rm, symlink, writeFile, readFile } from 'node:fs/promises' import { existsSync } from 'node:fs' import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' @@ -15,21 +15,24 @@ import { type SessionNotification, } from '@agentclientprotocol/sdk' import { Readable, Writable } from 'node:stream' +import { promisify } from 'node:util' +import { zstdDecompress } from 'node:zlib' import { afterEach, describe, expect, it } from 'vitest' /** * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and - * require a valid initialize response. This catches built-only settle races and stdout protocol - * leaks that the tsx source-path smoke cannot. It skips before build; initialize is keyless, with a - * dummy key used only to boot the adapter. `--expose-internals` enables Cordis bare-plugin loading. + * complete a mock-backed turn. This catches built-only settle races, stdout protocol leaks, and + * published persistence behavior that the tsx source-path smoke cannot. It skips before build; + * `--expose-internals` enables Cordis bare-plugin loading. */ const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url)) const acpBin = join(repoRoot, 'packages/examples/acp-demo/lib/bin.js') +const decompress = promisify(zstdDecompress) const dshPackages = [ 'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt', - 'core/tools', 'core/agent-loop', 'llm/llm', 'llm/llm-deepseek', 'bash/bash', + 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot', 'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl', 'ui/acp', 'examples/acp-demo', 'util/paths', @@ -73,18 +76,31 @@ async function makeConsumer(): Promise { const resolved = fileURLToPath(import.meta.resolve(`${dep}/package.json`, fromAcp)) await link(dirname(resolved), dep, nm) } + await writeFile(join(dir, 'mock-llm.mjs'), [ + "import { LlmAdapter } from '@deepseek-ai/dsh-llm'", + 'class Mock extends LlmAdapter {', + ' async * stream() {', + " yield { type: 'block-start', index: 0, blockType: 'text' }", + " yield { type: 'text-delta', index: 0, text: 'ACP BUILT OK' }", + " yield { type: 'block-end', index: 0, block: { type: 'text', text: 'ACP BUILT OK' } }", + " yield { type: 'finish', reason: { kind: 'stop' } }", + ' }', + '}', + "export const name = 'built-acp-mock'", + "export const inject = ['llm']", + "export function apply(ctx) { ctx.llm.registerAdapter(['built-acp-mock'], new Mock()) }", + '', + ].join('\n')) await writeFile(join(dir, 'cordis.yml'), [ - '- id: llm-deepseek', - ' name: \'@deepseek-ai/dsh-llm-deepseek\'', - ' config:', - ' apiKey: !!js process.env.DEEPSEEK_API_KEY', + '- id: mock-llm', + ' name: \'./mock-llm.mjs\'', '- id: bash', ' name: \'@deepseek-ai/dsh-bash-local\'', '- id: acp-agent', ' name: \'@deepseek-ai/dsh-acp-demo\'', ' config:', - ' provider: deepseek', - ' model: deepseek-v4-flash', + ' provider: built-acp-mock', + ' model: built-acp-mock', ' persona: \'test agent\'', ' workspaceContext: false', '', @@ -113,14 +129,12 @@ afterEach(async () => { }) describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, no tsx)', () => { - it('boots the published bin and answers an initialize JSON-RPC frame on stdout', async () => { + it('boots the published bin, completes a turn, and writes default Zstandard persistence', async () => { consumer = await makeConsumer() child = spawn(process.execPath, ['--expose-internals', acpBin, '--config', './cordis.yml'], { cwd: consumer, - // Dummy key: initialize never reaches the model, so it is never used. env: { ...process.env, - DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', DSH_HOME: join(consumer, '.dsh'), DSH_AGENTS_HOME: join(consumer, '.agents'), }, @@ -151,6 +165,18 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n // regression would exit before answering); loadSession proves the real app // mounted, not a collapsed export shape. expect(init.agentCapabilities?.loadSession).toBe(true) + const { sessionId } = await client.newSession({ cwd: consumer, mcpServers: [] }) + const result = await client.prompt({ sessionId, prompt: [{ type: 'text', text: 'reply' }] }) + expect(result.stopReason).toBe('end_turn') + const sessionsRoot = join(consumer, '.sessions') + let log: string | undefined + await expect.poll(async () => { + log = (await readdir(sessionsRoot, { recursive: true })).find(file => file.endsWith('.jsonl.zstd')) + return log + }).toBeTypeOf('string') + const compressed = await readFile(join(sessionsRoot, log!)) + expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd') + expect(JSON.parse((await decompress(compressed)).toString())).toMatchObject({ type: 'session', id: sessionId }) expect(stderr.join('')).not.toContain('without inject') // stdout purity: every emitted line is a JSON-RPC frame, no logger leak. for (const line of rawOut.join('').split('\n').filter(l => l.trim().length > 0)) { @@ -182,7 +208,6 @@ function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise cwd, env: { ...process.env, - DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), }, diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md index 7aa5cdf530..452bcfcc36 100644 --- a/packages/examples/agent-spine-demo/README.md +++ b/packages/examples/agent-spine-demo/README.md @@ -37,7 +37,7 @@ The spine is everything COMMON to every front door. The swappable and front-door - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`). - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl). - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings. -- **presentation + per-app infra** — the terminal (`dsh-tui` / `dsh-stdio`) or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-stdio-demo`](../stdio-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside. +- **presentation + per-app infra** — the terminal TUI or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-tui-demo`](../tui-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside. This is the [interface/implementation/consumer seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door. @@ -49,7 +49,7 @@ import type { Config } from '@deepseek-ai/dsh-agent-spine-demo' // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults. ``` -The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — a stdio app pre-creates `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields. +The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields. ## Why a code bundle, not a shared YAML include diff --git a/packages/examples/cli-demo/README.md b/packages/examples/cli-demo/README.md index 760a0f60e1..958dd4c3bb 100644 --- a/packages/examples/cli-demo/README.md +++ b/packages/examples/cli-demo/README.md @@ -1,8 +1,8 @@ # @deepseek-ai/dsh-cli-demo -Headless one-shot app and bin for running one agent task without a readline or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin submits the task, waits for its durable turn ending, renders the selected output, disposes to quiescence, and exits. +Headless one-shot app and bin for running one agent task without an interactive UI or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin submits the task, waits for its durable turn ending, renders the selected output, disposes to quiescence, and exits. -The package mounts no console logger, readline UI, user-interaction service, or `ask_user_question` tool. Stdout is reserved for the selected output format; diagnostics use stderr. +The package mounts no console logger, interactive UI, user-interaction service, or `ask_user_question` tool. Stdout is reserved for the selected output format; diagnostics use stderr. ## Config @@ -19,6 +19,7 @@ The package mounts no console logger, readline UI, user-interaction service, or | `toolBash` | owner defaults | model-facing bash config, including this producer's background opt-in | | `toolTasks` | owner defaults | generic `task_output` wait bounds | | `persistenceRoot` | `./.sessions` | JSONL session root | +| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) | | `workspaceContext` | required | workspace-instruction byte budget, or `false` to disable loading | ## CLI contract @@ -32,7 +33,7 @@ dsh-cli-demo [--config path] [--output-format text|json|stream-json] The root headless-agent example supplies its leaf: ```sh -pnpm run demo:headless -- "inspect the failing test and fix it" +pnpm run demo:headless "inspect the failing test and fix it" ``` Loader configs with bare package specifiers require `node --expose-internals` or the Loader's optional native fallback. The root command supplies the Node flag. diff --git a/packages/examples/cli-demo/src/index.ts b/packages/examples/cli-demo/src/index.ts index e5c77af9ed..d51cc80b23 100644 --- a/packages/examples/cli-demo/src/index.ts +++ b/packages/examples/cli-demo/src/index.ts @@ -11,7 +11,10 @@ import z from 'schemastery' import { SessionId } from '@deepseek-ai/dsh-session' import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo' -import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' +import SessionPersistenceJsonl, { + JsonlCompressionSchema, + type JsonlCompression, +} from '@deepseek-ai/dsh-session-persistence-jsonl' import * as workspaceContext from '@deepseek-ai/dsh-workspace-context' const DEFAULT_PERSISTENCE_ROOT = './.sessions' @@ -36,6 +39,8 @@ export interface Config { dshHome?: string /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string + /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */ + persistenceCompression?: JsonlCompression /** Skill registry, local-provider, and model-facing consumer config. */ skills?: agentCore.SkillConfig /** Model-facing bash tool config forwarded through agent-spine-demo. */ @@ -54,6 +59,7 @@ export const Config: z = z.object({ model: z.string().required(), maxParallelToolCalls: z.number().step(1).min(1), persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT), + persistenceCompression: JsonlCompressionSchema, persona: z.string(), dshHome: z.string(), skills: agentCore.SkillConfigSchema, @@ -78,5 +84,8 @@ export function apply(ctx: Context, config: Config): void { ...agentCore.pickSpineConfig(config), agents: [{ id: SessionId('main'), provider: config.provider, model: config.model, cwd: process.cwd() }], }) - ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT }) + ctx.plugin(SessionPersistenceJsonl, { + root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT, + ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }), + }) } diff --git a/packages/examples/cli-demo/tests/built-bin.e2e.ts b/packages/examples/cli-demo/tests/built-bin.e2e.ts index 25043b40c4..c57f09b006 100644 --- a/packages/examples/cli-demo/tests/built-bin.e2e.ts +++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts @@ -3,11 +3,14 @@ import { existsSync } from 'node:fs' import { mkdtemp, mkdir, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' +import { promisify } from 'node:util' import { fileURLToPath } from 'node:url' +import { zstdDecompress } from 'node:zlib' import { afterEach, describe, expect, it } from 'vitest' const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url)) const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js') +const decompress = promisify(zstdDecompress) const dshPackages = [ 'examples/agent-spine-demo', 'examples/cli-demo', 'core/agent', 'core/session', 'core/system-prompt', 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', @@ -140,8 +143,13 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => { const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record) expect(lines[0]).toMatchObject({ type: 'session_event', event: { type: 'turn/start' } }) expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, result: 'BUILT: stream task' }) - const files = await readdir(join(consumer, '.sessions'), { recursive: true }) - expect(files.filter(file => file.endsWith('.jsonl'))).toHaveLength(3) + const sessionsRoot = join(consumer, '.sessions') + const files = await readdir(sessionsRoot, { recursive: true }) + const logs = files.filter(file => file.endsWith('.jsonl.zstd')) + expect(logs).toHaveLength(3) + const compressed = await readFile(join(sessionsRoot, logs[0]!)) + expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd') + expect(JSON.parse((await decompress(compressed)).toString())).toMatchObject({ type: 'session' }) }, 30_000) it('keeps stdout empty for invalid argv and missing config', async () => { diff --git a/packages/examples/cli-demo/tests/cli-demo.spec.ts b/packages/examples/cli-demo/tests/cli-demo.spec.ts index 2111ff6aa8..c248242ad1 100644 --- a/packages/examples/cli-demo/tests/cli-demo.spec.ts +++ b/packages/examples/cli-demo/tests/cli-demo.spec.ts @@ -51,12 +51,14 @@ describe('dsh-cli-demo app composition', () => { persona: 'Headless.', tools: { mode: 'native' }, persistenceRoot: root, + persistenceCompression: 'none', skills: await skillConfig(), workspaceContext: false, }) const [agent] = ctx.get('agents')?.roots() ?? [] expect(ctx.get('agentLoop')).toBeDefined() expect(ctx.get('sessionPersistence')).toBeDefined() + expect((ctx.get('sessionPersistence') as unknown as { config: { compression?: string } }).config.compression).toBe('none') expect(agent?.session.header.cwd).toBe(process.cwd()) expect(ctx.get('userInteraction')).toBeUndefined() expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined() diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts index fe61a42304..2f9fa32778 100644 --- a/packages/examples/cli-demo/tests/cli.spec.ts +++ b/packages/examples/cli-demo/tests/cli.spec.ts @@ -303,7 +303,7 @@ describe('runOneShot and executeCli', () => { expect(output).toEqual({ code: 0, stdout: 'final answer\n', stderr: '' }) expect(agent.status).toBe('disposed') const files = await readdir(persistenceRoot, { recursive: true }) - expect(files.some(file => file.endsWith('.jsonl'))).toBe(true) + expect(files.some(file => file.endsWith('.jsonl.zstd'))).toBe(true) }) it('sums usage across tool steps and selects the last text-bearing assistant message', async () => { diff --git a/packages/examples/stdio-demo/README.md b/packages/examples/stdio-demo/README.md deleted file mode 100644 index 0f275485b0..0000000000 --- a/packages/examples/stdio-demo/README.md +++ /dev/null @@ -1,116 +0,0 @@ -# @deepseek-ai/dsh-stdio-demo - -The **terminal chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)) with JSONL persistence, human interaction, a pre-created `main` agent, and a TTY-selected pi-tui/readline front door. Its `bin` boots a leaf `cordis.yml`. - -It is the terminal counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, while ACP reserves stdout for JSON-RPC and creates sessions from the client. - -## What it bakes in - -A terminal chat always wants the same cluster, so the package owns it rather than trusting each leaf to re-wire it: - -| Plugin | Why it is here | -|---|---| -| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's provider/model pair with `process.cwd()` as the fresh session cwd and carrying its `persona` | -| `@deepseek-ai/dsh-commands` | the human-command registry consumed by the TUI front door and optional command plugins | -| `@deepseek-ai/dsh-command-goal` | the direct `/goal` producer mounted only for the TUI front door; readline retains the model-mediated goal path | -| `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` | -| `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools | -| `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool | -| `@cordisjs/plugin-logger-console` | readline diagnostics for non-TTY operation; omitted from the fullscreen TUI path | -| `@deepseek-ai/dsh-stdio` | the line-oriented channel for pipes and automation, bound to the exact app-owned agent/session identity | -| `@deepseek-ai/dsh-tui` | the fullscreen interactive channel for TTY pairs, bound to the same exact identity | - -`@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in 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. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`. - -The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-spine-demo`, `hmr`, and the two leaf backends. - -## Config - -| Key | Default | Routed to | -|---|---|---| -| `provider` | (required) | the pre-created `main` agent's registered provider route | -| `model` | (required) | the pre-created `main` agent's model | -| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap shared by the bundled loop's agents; `1` is serial | -| `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` | -| `toolOrder` | — | explicit model-facing tool order (a name list with one `''` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` | -| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery | -| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` | -| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` | -| `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` | -| `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` | -| `goals` | owner defaults | persisted goal-domain and model-tool config; `false` removes the goal stack and the TUI `/goal` producer | -| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory | -| `welcome` | `ready.` | terminal banner / TUI subtitle | -| `ui` | `{ mode: 'auto' }` | terminal mode (`auto` / `readline` / `tui`) and nested TUI presentation config | -| `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) | - -Fresh terminal sessions use the process launch directory as `session.header.cwd` and mint one combined `main-session-` agent/session id, so durable restarts cannot collide. The app passes that exact opaque id to the config-created agent and selected UI before agent-core starts; this lets either front door observe `agent-loop/config-start-failed`, and an AgentLoop-only reload restores materialized history under the same id. Readline buffers startup input until `agent/session-start`; the TUI waits to enter fullscreen until the matching root appears. A resumed run binds both components to the exact `resumeSessionId` and keeps the persisted cwd. - -## The bin - -`dsh-stdio-demo [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`, or install the Loader's optional `node-addon-require-builtin` fallback, so the Loader can resolve the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages). The `demo:echo` / `demo:repl` scripts use `--expose-internals`. - -## Example leaf `cordis.yml` - -```yaml -# A REPL agent demo: hmr + the DeepSeek adapter + local bash, then this app. -- id: hmr - name: '@cordisjs/plugin-hmr' - config: - root: ['.'] -- id: llm-deepseek - name: '@deepseek-ai/dsh-llm-deepseek' - config: - apiKey: !!js process.env.DEEPSEEK_API_KEY -- id: bash - name: '@deepseek-ai/dsh-bash-local' - config: - timeoutMs: 60000 -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-demo' - config: - provider: deepseek - model: deepseek-v4-flash - persona: 'You are a coding assistant powered by the {{model}} model.' - ui: - mode: auto -``` - -Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo — "swap the backend, keep the app". - -## Model Experience - -### Composed terminal agent request - -#### What the model sees - -Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, visible tools, and the enabled goal policy/tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each ordinary terminal submission becomes a user message; submissions made while the agent runs steer the active turn. TUI commands and their direct results remain outside model context, while accepted `/goal` mutations append the goal domain's model-visible snapshot. - -#### Token effect - -Child prompt and schema costs repeat per request; user input and tool history grow until compaction. Terminal banners, logger output, cards, and rendered transcripts add zero model tokens. - -#### KV Cache effect - -User and tool history is append-only while the composed prompt, schemas, child model route, and session prefix remain fixed. A composition change or compaction may invalidate reuse from its first changed token; terminal rendering has no cache effect. - -### Human-answer result - -#### What the model sees - -Through `dsh-tool-ask-user`, successful terminal answers use that package's exact compact JSON shape. Interruption becomes exactly `Error: ask_user_question was interrupted before the user answered`; a closed stdin becomes `Error: ask_user_question cannot be answered because stdin is closed`. - -#### Token effect - -Only a completed or failed tool call adds retained result tokens; prompts printed while waiting are terminal-only. - -#### KV Cache effect - -Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries. - -## Known Limitations and Deferred Work - -- **One pre-created `main` agent drives the selected terminal UI** — there is no multi-session or concurrent-agent surface in this app; a run is one conversation. -- **Direct commands require TUI mode** — the line-oriented fallback does not consume `ctx.commands`; an ordinary `/goal` prompt there may instead be interpreted through the model-facing goal tools. -- **The front-door cluster is fixed in code** — the JSONL persistence backend and the ask-user tooling are baked; a different composition is a leaf-level sibling entry or another app package. -- **The question tool is not an approval answerer** — this app mounts `user-interaction` and `ask_user_question`, but not `ctx.approval`; a `tools/pre-execute` `ask` therefore fails closed unless the leaf composes an approval service and terminal answerer. diff --git a/packages/examples/stdio-demo/src/index.ts b/packages/examples/stdio-demo/src/index.ts deleted file mode 100644 index 5e399a56ca..0000000000 --- a/packages/examples/stdio-demo/src/index.ts +++ /dev/null @@ -1,190 +0,0 @@ -/** - * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}) plus the - * coupled front-door cluster a terminal chat needs — the command registry, - * TTY-selected pi-tui/readline presentation, JSONL session persistence, the - * user-interaction seam with its `ask_user_question` tool, and one pre-created - * agent whose exact shared identity the selected UI drives as `main`. - * Swappable adapters, executors, optional tools, and HMR stay in the leaf. This - * Loader plugin intentionally exposes named exports only; a default export - * would hide its `Config` schema (see docs/postmortem/0001). - * @module @deepseek-ai/dsh-stdio-demo - */ - -import type { Context } from 'cordis' -import { randomUUID } from 'node:crypto' -import ConsoleExporter from '@cordisjs/plugin-logger-console' -import z from 'schemastery' -import { SessionId } from '@deepseek-ai/dsh-session' -import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' -import CommandService from '@deepseek-ai/dsh-commands' -import * as commandGoal from '@deepseek-ai/dsh-command-goal' -import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo' -import * as workspaceContext from '@deepseek-ai/dsh-workspace-context' -import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' -import UserInteractionService from '@deepseek-ai/dsh-user-interaction' -import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' -import * as uiStdio from '@deepseek-ai/dsh-stdio' -import * as uiTui from '@deepseek-ai/dsh-tui' - -export const name = 'stdio-demo' -const DEFAULT_PERSISTENCE_ROOT = './.sessions' -const DEFAULT_WELCOME = 'ready.' - -/** Terminal front door selected by the app bundle. */ -export type TerminalMode = 'auto' | 'readline' | 'tui' - -/** App-level terminal selection with nested TUI presentation settings. */ -export interface UiConfig { - /** Select a concrete front door or infer it from the process streams. */ - mode?: TerminalMode - /** Settings forwarded only when the pi-tui front door is selected. */ - tui?: uiTui.TuiConfig -} - -const terminalModeSchema = z.union(['auto', 'readline', 'tui'] as const).default('auto') - -/** Schemastery schema for app-level terminal selection. */ -export const UiConfigSchema: z = z.object({ - mode: terminalModeSchema, - tui: uiTui.TuiConfigSchema, -}) - -/** - * Resolve the app's terminal front door. - * @param config - app-level terminal selection. - * @param isTTY - whether both process streams are interactive TTYs. - * @returns the concrete UI package to mount. - */ -export function resolveTerminalMode(config: UiConfig | undefined, isTTY: boolean): Exclude { - const mode = config?.mode ?? 'auto' - if (mode === 'auto') return isTTY ? 'tui' : 'readline' - if (mode === 'tui' && !isTTY) { - throw new Error('stdio-demo: TUI mode requires both stdin and stdout to be TTYs; use mode "readline" for pipes') - } - return mode -} - -/** - * App config: the swappable per-demo values, each routed to where the app wires - * it. `provider`/`model`/`resumeSessionId` configure the pre-created `main` agent (through - * {@link @deepseek-ai/dsh-agent-spine-demo}'s forwarded `agents` list); `persona` is - * the deployment persona (forwarded to the system-prompt plugin); `toolOrder` - * is the explicit model-facing tool order (forwarded to the system-prompt plugin); - * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions - * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory; - * `welcome` is the UI banner and `ui` configures terminal mode/presentation. - */ -export interface Config { - /** Provider route for the `main` agent. */ - provider: string - /** Model name for the `main` agent (must have a registered adapter). */ - model: string - /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ - maxParallelToolCalls?: number - /** Deployment persona (the system-prompt plugin's `persona` config). */ - persona?: string - /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ - toolOrder?: string[] - /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */ - tools?: ToolsConfig - /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */ - dshHome?: string - /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ - persistenceRoot?: string - /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */ - welcome?: string - /** Terminal front-door selection and pi-tui presentation settings. */ - ui?: UiConfig - /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */ - skills?: agentCore.SkillConfig - /** Model-facing bash tool config forwarded through agent-core. */ - toolBash?: NonNullable - /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */ - toolTasks?: NonNullable - /** Persisted same-session goals; owner defaults enable them, or false disables the stack and TUI command. */ - goals?: agentCore.GoalConfig | false - /** - * If set, the pre-created agent RESUMES this persisted session id instead of - * starting fresh. Sourced from an env var in the leaf `cordis.yml` - * (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`). - */ - resumeSessionId?: string - /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */ - workspaceContext: agentCore.Config['workspaceContext'] -} - -export const Config: z = z.object({ - provider: z.string().required(), - model: z.string().required(), - maxParallelToolCalls: z.number().step(1).min(1), - persona: z.string(), - // The array default is forced to undefined: ABSENT means "lexicographic - // order" (the owning dsh-system-prompt schema does the same), while - // schemastery's native [] default would read as an invalid configured list. - toolOrder: z.array(z.string()).default(undefined as unknown as string[]), - tools: ToolRegistry.Config, - dshHome: z.string(), - persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT), - welcome: z.string().default(DEFAULT_WELCOME), - ui: UiConfigSchema, - skills: agentCore.SkillConfigSchema, - toolBash: agentCore.ToolBashConfigSchema, - toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]), - goals: z.union([z.const(false), agentCore.GoalConfigSchema]), - resumeSessionId: z.string(), - workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(), -}) - -/** - * Compose the spine with one terminal front door. Persistence and user - * interaction mount first; the selected UI then waits on the exact session id - * and subscribes to config-start failures before agent-core starts it. Console - * logging is readline-only because fullscreen output belongs to pi-tui. The - * ask-user tool waits on the completed spine, and HMR remains a leaf concern. - * @param ctx - context receiving the app's child plugins. - * @param config - app configuration routed to the spine and front door. - * @param isTTY - whether both process streams are interactive TTYs. - */ -export function composeTerminalApp(ctx: Context, config: Config, isTTY: boolean): void { - const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId - const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`) - const mode = resolveTerminalMode(config.ui, isTTY) - const goals = config.goals ?? {} - if (mode === 'readline') ctx.plugin(ConsoleExporter) - ctx.plugin(CommandService) - if (mode === 'tui' && goals !== false) ctx.plugin(commandGoal) - ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT }) - ctx.plugin(UserInteractionService) - if (mode === 'tui') { - ctx.plugin(uiTui, { - ...config.ui?.tui, - welcome: config.welcome ?? DEFAULT_WELCOME, - sessionId, - }) - } else { - ctx.plugin(uiStdio, { - welcome: config.welcome ?? DEFAULT_WELCOME, - sessionId, - }) - } - ctx.plugin(agentCore, { - ...agentCore.pickSpineConfig(config), - goals, - agents: [{ - id: SessionId('main'), - provider: config.provider, - model: config.model, - cwd: process.cwd(), - ...resumeSessionId === undefined ? { sessionId } : { resumeSessionId: sessionId }, - }], - }) - ctx.plugin(toolAskUser) -} - -/** Compose the configured terminal front door with the agent app. */ -/* v8 ignore start -- production stream capability wiring; composeTerminalApp is unit-covered, - and the repl-agent PTY smoke covers the interactive process path */ -export function apply(ctx: Context, config: Config): void { - composeTerminalApp(ctx, config, process.stdin.isTTY && process.stdout.isTTY) -} -/* v8 ignore stop */ diff --git a/packages/examples/stdio-demo/tests/built-bin.e2e.ts b/packages/examples/stdio-demo/tests/built-bin.e2e.ts deleted file mode 100644 index c2bb459cc9..0000000000 --- a/packages/examples/stdio-demo/tests/built-bin.e2e.ts +++ /dev/null @@ -1,218 +0,0 @@ -import { spawn } from 'node:child_process' -import { cp, mkdtemp, mkdir, rm, symlink, writeFile, readFile } from 'node:fs/promises' -import { existsSync } from 'node:fs' -import { tmpdir } from 'node:os' -import { dirname, join } from 'node:path' -import { fileURLToPath } from 'node:url' -import { afterEach, describe, expect, it } from 'vitest' - -/** - * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and - * require the banner plus echo round-trip. This catches built-only early-exit and config-resolution - * failures masked by tsx source smokes. It skips before build; `--expose-internals` enables Cordis - * bare-plugin loading, matching the demo command. - */ - -const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url)) -const stdioBin = join(repoRoot, 'packages/examples/stdio-demo/lib/bin.js') - -// Symlink each required workspace package by package name so plain Node resolves its built `main`, -// matching an installed dependency rather than tsconfig paths. -const dshPackages = [ - 'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt', - 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local', - 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot', - 'session-persistence/session-persistence', - 'session-persistence/session-persistence-jsonl', 'examples/stdio-demo', 'util/paths', - 'ui/stdio', 'ui/tool-ask-user', 'ui/user-interaction', -] -const vendorPackages = [ - 'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console', - 'schemastery', 'cosmokit', -] - -async function pkgName(absDir: string): Promise { - const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string } - return json.name -} - -async function installWorkspacePackageCopy(absDir: string, target: string): Promise { - await mkdir(dirname(target), { recursive: true }) - await cp(absDir, target, { - recursive: true, - filter: source => !source.split('/').includes('node_modules'), - }) -} - -/** - * Build a temporary external consumer with built workspace/vendor links and a mock-backed config. - * The optional missing-but-disabled plugin verifies load guards accept intentionally fiber-less - * entries rather than treating them as import failures. - */ -async function makeConsumer( - welcome: string, - disabledBrokenEntry = false, - extraDshPackages: string[] = [], - extraEntries: string[] = [], -): Promise { - const dir = await mkdtemp(join(tmpdir(), 'stdio-built-bin-')) - const nm = join(dir, 'node_modules') - for (const rel of [...dshPackages, ...extraDshPackages]) { - const abs = join(repoRoot, 'packages', rel) - const name = await pkgName(abs) - const target = join(nm, name) - if (extraDshPackages.includes(rel)) { - await installWorkspacePackageCopy(abs, target) - } else { - await mkdir(dirname(target), { recursive: true }) - await symlink(abs, target) - } - } - for (const v of vendorPackages) { - const abs = join(repoRoot, 'vendor', v) - const name = await pkgName(abs) - const target = join(nm, name) - await mkdir(dirname(target), { recursive: true }) - await symlink(abs, target) - } - // The example's mock model + echo tool are example-local TS plugins (Node - // 22.19+ — the engines floor — strips types natively, so plain `node` loads - // them); they import the workspace packages the symlinked node_modules now - // provides. - await cp(join(repoRoot, 'examples/echo-agent/src'), join(dir, 'src'), { recursive: true }) - await writeFile(join(dir, 'cordis.yml'), [ - '- id: mock-llm', - ' name: \'./src/mock-llm.ts\'', - '- id: echo-tool', - ' name: \'./src/echo-tool.ts\'', - '- id: bash', - ' name: \'@deepseek-ai/dsh-bash-local\'', - '- id: stdio-agent', - ' name: \'@deepseek-ai/dsh-stdio-demo\'', - ' config:', - ' provider: mock', - ' model: mock-echo', - ' persona: \'demo\'', - ' workspaceContext: false', - ` welcome: '${welcome}'`, - ...extraEntries, - ...disabledBrokenEntry - ? ['- id: off', ' name: \'./src/does-not-exist.ts\'', ' disabled: true'] - : [], - '', - ].join('\n')) - return dir -} - -/** Run the built bin in `cwd` against `configArg` with piped stdin; resolve with stdout/stderr + exit code. */ -function runBuiltBin(cwd: string, configArg: string, input: string): Promise<{ stdout: string; code: number; stderr: string }> { - return new Promise((resolve, reject) => { - // --expose-internals: the cordis Loader resolves bare plugin specifiers via - // its internal module loader (active only under this flag); demo:echo passes - // it too. NO tsx — this is the published `node lib/bin.js` path. - const child = spawn(process.execPath, ['--expose-internals', stdioBin, configArg], { - cwd, - // Mock model: never calls the network, so no key needed. - env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') }, - stdio: ['pipe', 'pipe', 'pipe'], - }) - let stdout = '' - let stderr = '' - child.stdout.setEncoding('utf8') - child.stdout.on('data', (c: string) => { stdout += c }) - child.stderr.setEncoding('utf8') - child.stderr.on('data', (c: string) => { stderr += c }) - const timer = setTimeout(() => { - child.kill('SIGKILL') - reject(new Error(`built bin did not exit within 25s. stdout:\n${stdout}\nstderr:\n${stderr}`)) - }, 25_000) - child.on('exit', (code) => { clearTimeout(timer); resolve({ stdout, code: code ?? -1, stderr }) }) - child.on('error', (err) => { clearTimeout(timer); reject(err) }) - child.stdin.write(`${input}\n`) - child.stdin.end() - }) -} - -let consumer: string | undefined - -afterEach(async () => { - // Windows can briefly retain released handles after exit; retry removal. - if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) - consumer = undefined -}) - -describe.skipIf(!existsSync(stdioBin))('dsh-stdio-demo BUILT bin (node lib/bin.js, no tsx)', () => { - it('boots the published bin, prints its banner, and runs the echo tool round-trip', async () => { - consumer = await makeConsumer('BUILT-BIN-OK ready.') - const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi') - expect(stderr).not.toContain('UNHANDLED') - expect(stderr).not.toContain('without inject') - // The banner proves boot() awaited the tree (the settle-race regression would - // exit 0 with empty stdout); the round-trip proves the whole app mounted. - expect(stdout).toContain('BUILT-BIN-OK ready.') - expect(stdout).toContain('[tool call] echo') - expect(stdout).toContain('[tool result] ECHO: HI') - expect(code).toBe(0) - }, 30_000) - - it('boots cleanly when the config disables an (otherwise unresolvable) entry', async () => { - // A `disabled: true` entry settles without a fiber by design; the fail-loud entry-load - // guard must not mistake it for a failed import. The nonexistent path makes that distinction - // observable while the successful round-trip proves boot continued. - consumer = await makeConsumer('DISABLED-OK ready.', true) - const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi') - expect(stderr).not.toContain('failed to load') - expect(stdout).toContain('DISABLED-OK ready.') - expect(stdout).toContain('[tool result] ECHO: HI') - expect(code).toBe(0) - }, 30_000) - - it('runs two synchronously piped lines as two ordinary turns', async () => { - consumer = await makeConsumer('TWO-TURNS ready.') - const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'first\nsecond') - expect(stderr).not.toContain('UNHANDLED') - expect(stdout).toContain('[main turn 1]') - expect(stdout).toContain('You said: "first"') - expect(stdout).toContain('[main turn 2]') - expect(stdout).toContain('You said: "second"') - expect(code).toBe(0) - }, 30_000) - - it('boots when optional spill plugins are loaded from a built consumer install', async () => { - consumer = await makeConsumer( - 'SPILL-OK ready.', - false, - ['spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention'], - [ - '- id: spill-local', - ' name: \'@deepseek-ai/dsh-spill-local\'', - '- id: spill-policy', - ' name: \'@deepseek-ai/dsh-spill-policy\'', - ' config:', - ' maxInlineBytes: 50000', - ], - ) - const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', '') - expect(stderr).not.toContain('failed to load') - expect(stderr).not.toContain('Cannot find package') - expect(stdout).toContain('SPILL-OK ready.') - expect(code).toBe(0) - }, 30_000) - - it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => { - // boot() pre-resolves the bootstrap include to an absolute URL, so a nonexistent config - // directory cannot break its import; the include plugin's own read must fail loud instead. - consumer = await makeConsumer('unused') - const { code, stderr } = await runBuiltBin(consumer, '/nonexistent/dir/cordis.yml', '') - expect(code).not.toBe(0) - expect(stderr).toContain('config file not found') - }, 30_000) - - it('fails LOUD (non-zero exit + stderr) on a missing config file in a real directory', async () => { - // Existing directory plus missing config exercises the include plugin's fail-loud path. - consumer = await makeConsumer('unused') - const { code, stderr } = await runBuiltBin(consumer, './does-not-exist.yml', '') - expect(code).not.toBe(0) - expect(stderr).toContain('config file not found') - }, 30_000) -}) diff --git a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts deleted file mode 100644 index de8481da4f..0000000000 --- a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts +++ /dev/null @@ -1,319 +0,0 @@ -import { describe, it, expect } from 'vitest' -import { mkdtemp } from 'node:fs/promises' -import { join } from 'node:path' -import { tmpdir } from 'node:os' -import { Context } from 'cordis' -import Loader from '@cordisjs/plugin-loader' -import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent' - -import type { Message } from '@deepseek-ai/dsh-llm' -import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt' -import * as stdioAgent from '../src/index.ts' - -/** - * Unit coverage for app composition and config forwarding: pre-created main agent, - * agent-spine-demo spine, JSONL backend, and adaptive terminal UI. HMR is a Loader-only leaf concern covered by the - * keyless echo smoke; this tier pins the export shape because an inject-less app could otherwise - * survive namespace collapse while silently losing its schema. - */ -async function mount(config: stdioAgent.Config, withBash = false): Promise { - const ctx = new Context() - if (withBash) ctx.provide('bash', { sandboxMode: undefined }) - await ctx.plugin(stdioAgent, config) - // The app mounts its children inside apply() (not awaited there); let their - // fibers settle so the spine services + the pre-created agent are ready. - await new Promise(resolve => setTimeout(resolve, 80)) - return ctx -} - -async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise> { - const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-demo-skills-')) - return { - local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') }, - ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {}, - } -} - -async function composePrefix(ctx: Context): Promise { - const agent = { session: { header: { cwd: '/tmp' } } } as unknown as Agent - const empty: Message[] = [] - return await agentEvents(ctx, agent).waterfall( - 'agent/session-prefix', empty, new AbortController().signal, - () => Promise.resolve(empty), - ) -} - -async function withIsolatedSkillHomes(run: () => Promise): Promise { - const oldDshHome = process.env.DSH_HOME - const oldAgentsHome = process.env.DSH_AGENTS_HOME - const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-demo-default-skills-')) - process.env.DSH_HOME = join(home, '.dsh') - process.env.DSH_AGENTS_HOME = join(home, '.agents') - try { - return await run() - } finally { - if (oldDshHome === undefined) { - delete process.env.DSH_HOME - } else { - process.env.DSH_HOME = oldDshHome - } - if (oldAgentsHome === undefined) { - delete process.env.DSH_AGENTS_HOME - } else { - process.env.DSH_AGENTS_HOME = oldAgentsHome - } - } -} - -describe('dsh-stdio-demo app', () => { - it('selects readline for pipes and dsh-tui for interactive terminal pairs', () => { - expect(stdioAgent.resolveTerminalMode(undefined, false)).toBe('readline') - expect(stdioAgent.resolveTerminalMode(undefined, true)).toBe('tui') - expect(stdioAgent.resolveTerminalMode({ mode: 'readline' }, true)).toBe('readline') - expect(stdioAgent.resolveTerminalMode({ mode: 'tui' }, true)).toBe('tui') - expect(() => stdioAgent.resolveTerminalMode({ mode: 'tui' }, false)).toThrow('requires both stdin and stdout') - }) - - it('binds only the selected terminal package to the app-owned exact session identity', () => { - const calls: Array<{ name: string; config: unknown }> = [] - const ctx = { - plugin(plugin: { name?: string }, config?: unknown) { - calls.push({ name: plugin.name ?? '', config }) - }, - } as unknown as Context - - stdioAgent.composeTerminalApp(ctx, { - provider: 'mock', - model: 'mock', - workspaceContext: false, - welcome: 'TUI ready', - ui: { mode: 'tui', tui: { color: false, maxToolOutputLines: 3 } }, - }, true) - expect(calls.map(call => call.name)).toContain('ui-tui') - expect(calls.map(call => call.name)).toContain('command-goal') - expect(calls.map(call => call.name)).not.toContain('ui-stdio') - expect(calls.map(call => call.name)).not.toContain('ConsoleExporter') - const tuiConfig = calls.find(call => call.name === 'ui-tui')?.config as { sessionId: string } - expect(tuiConfig).toMatchObject({ welcome: 'TUI ready', color: false, maxToolOutputLines: 3 }) - expect(tuiConfig.sessionId).toMatch(/^main-session-/) - const spineConfig = calls.find(call => call.name === 'agent-spine-demo')?.config as { - agents: Array<{ id: string; sessionId?: string; resumeSessionId?: string }> - } - expect(spineConfig.agents[0]).toMatchObject({ id: 'main', sessionId: tuiConfig.sessionId }) - expect(spineConfig).toMatchObject({ goals: {} }) - - calls.length = 0 - stdioAgent.composeTerminalApp(ctx, { - provider: 'mock', - model: 'mock', - resumeSessionId: 'persisted-session', - workspaceContext: false, - ui: { mode: 'tui' }, - }, true) - expect(calls.find(call => call.name === 'ui-tui')?.config).toMatchObject({ - sessionId: 'persisted-session', welcome: 'ready.', - }) - expect((calls.find(call => call.name === 'agent-spine-demo')?.config as typeof spineConfig).agents[0]) - .toMatchObject({ id: 'main', resumeSessionId: 'persisted-session' }) - - calls.length = 0 - stdioAgent.composeTerminalApp(ctx, { - provider: 'mock', model: 'mock', workspaceContext: false, goals: false, ui: { mode: 'tui' }, - }, true) - expect(calls.map(call => call.name)).toContain('ui-tui') - expect(calls.map(call => call.name)).not.toContain('command-goal') - expect(calls.find(call => call.name === 'agent-spine-demo')?.config).toMatchObject({ goals: false }) - - calls.length = 0 - stdioAgent.composeTerminalApp(ctx, { - provider: 'mock', model: 'mock', workspaceContext: false, ui: { mode: 'readline' }, - }, false) - expect(calls.map(call => call.name)).toContain('ui-stdio') - expect(calls.map(call => call.name)).toContain('ConsoleExporter') - expect(calls.map(call => call.name)).not.toContain('ui-tui') - expect(calls.map(call => call.name)).not.toContain('command-goal') - expect(calls.find(call => call.name === 'agent-spine-demo')?.config).toMatchObject({ goals: {} }) - }) - - it('composes the spine + front-door cluster and pre-creates the main agent', async () => { - const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig(), workspaceContext: false, ui: { mode: 'readline' } }) - // The spine services (brought up by the agent-spine-demo bundle) are all present. - expect(ctx.get('agents')).toBeDefined() - expect(ctx.get('agentLoop')).toBeDefined() - expect(ctx.get('sessionPersistence')).toBeDefined() - expect(ctx.get('userInteraction')).toBeDefined() - expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined() - expect(ctx.get('goals')).toBeDefined() - expect(ctx.get('tools')?.get('get_goal')).toBeDefined() - // The sole pre-created agent the UI drives. `main` is its stable config - // label; each fresh process mints a durable combined agent/session id. - await expect.poll(() => ctx.get('agents')?.list()).toHaveLength(1) - const agent = ctx.get('agents')?.list()[0] - expect(agent).toBeDefined() - expect(agent?.id).toBe(agent?.session.id) - expect(agent?.id).toMatch(/^main-session-/) - expect(agent?.session.header.cwd).toBe(process.cwd()) - expect(ctx.commands.find(agent!, 'goal')).toBeUndefined() - await ctx.fiber.dispose() - }) - - it('normalizes an empty resume id to a fresh exact app identity', async () => { - const ctx = await mount({ - provider: 'mock', - model: 'mock', - resumeSessionId: '', - persistenceRoot: '/tmp/dsh-stdio-agent-spec-empty-resume', - skills: await isolatedSkillsConfig(), - workspaceContext: false, - }) - await expect.poll(() => ctx.get('agents')?.list()).toHaveLength(1) - const agent = ctx.get('agents')?.list()[0] - expect(agent?.id).toMatch(/^main-session-[0-9a-f-]{36}$/) - expect(agent?.id).toBe(agent?.session.id) - await ctx.fiber.dispose() - }) - - it('defaults persistenceRoot and welcome when omitted', async () => { - // Direct apply (NOT via ctx.plugin, which validates+defaults the config - // first) so the runtime `DEFAULT_PERSISTENCE_ROOT` / `DEFAULT_WELCOME` fallbacks on - // apply()'s last two lines are the ones that fire — covering a - // schema-bypassing direct-mount caller. - const ctx = new Context() - // No persona: covers the omitted-persona forwarding branch too. - stdioAgent.apply(ctx, { provider: 'mock', model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false }) - await expect.poll(() => ctx.get('agents')?.list()).toHaveLength(1) - expect(ctx.get('sessionPersistence')).toBeDefined() - expect(ctx.get('agents')?.list()[0]?.id).toMatch(/^main-session-/) - await ctx.fiber.dispose() - }) - - it('forwards explicit project-instruction controls to the bundled spine', async () => { - const ctx = await mount({ - provider: 'mock', - model: 'mock', - persona: 'hi', - persistenceRoot: '/tmp/dsh-stdio-demo-spec-workspace-context', - workspaceContext: false, - }) - await expect.poll(() => ctx.get('agents')?.list()).toHaveLength(1) - expect(ctx.get('agents')?.list()[0]?.id).toMatch(/^main-session-/) - await ctx.fiber.dispose() - }) - - it('uses default skill config when apply is called directly without skills', async () => { - await withIsolatedSkillHomes(async () => { - const ctx = new Context() - stdioAgent.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false }) - await new Promise(resolve => setTimeout(resolve, 80)) - expect(ctx.skills).toBeDefined() - expect(await ctx.skills.list()).toEqual([]) - await ctx.fiber.dispose() - }) - }) - - it('forwards resumeSessionId onto the pre-created agent when set', async () => { - // A resume id defers agent creation until persistence loads; with no backing - // session the resume is contained + logged, so no agent registers — - // the branch that maps resumeSessionId through is what this covers. - const ctx = await mount({ - provider: 'mock', - model: 'mock', - persona: 'hi', - persistenceRoot: '/tmp/dsh-stdio-demo-spec-resume', - resumeSessionId: 'no-such-session', - skills: await isolatedSkillsConfig(), - workspaceContext: false, - }) - expect(ctx.get('agents')?.list()).toEqual([]) - await ctx.fiber.dispose() - }) - - it('forwards skill config and dshHome into agent-spine-demo', async () => { - const skills = await isolatedSkillsConfig(6) - const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', dshHome: skills.local!.dshHome!, skills, workspaceContext: false }) - ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' }) - expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...') - await ctx.fiber.dispose() - }) - - it('forwards maxParallelToolCalls to the bundled agent loop', async () => { - const ctx = await mount({ - provider: 'mock', - model: 'mock', - maxParallelToolCalls: 3, - persistenceRoot: '/tmp/dsh-stdio-demo-spec-parallel', - skills: await isolatedSkillsConfig(), - workspaceContext: false, - }) - expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3) - await ctx.fiber.dispose() - }) - - it('forwards bundled tool config into agent-core', async () => { - const ctx = await mount({ - provider: 'mock', - model: 'mock', - workspaceContext: false, - toolBash: { enableRunInBackground: false }, - toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 }, - skills: await isolatedSkillsConfig(), - }, true) - const bash = ctx.tools.schemas().find(tool => tool.name === 'bash') - expect(Object.keys((bash!.parameters as { properties: Record }).properties)) - .not.toContain('run_in_background') - await ctx.fiber.dispose() - }) - - it('exposes its name and Config schema', () => { - expect(stdioAgent.name).toBe('stdio-demo') - expect(stdioAgent.Config).toBeDefined() - }) - - it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => { - const ctx = await mount({ - provider: 'mock', - model: 'mock', - toolOrder: ['zulu', TOOL_ORDER_REST], - persistenceRoot: '/tmp/dsh-stdio-demo-spec-tool-order', - workspaceContext: false, - }) - // The bundle's own bash tools pend on the absent `ctx.bash` executor in - // this providerless mount, so register two plain tools to order. - for (const name of ['alpha', 'zulu']) { - ctx.get('tools')!.register({ - name, - description: name, - parameters: {}, - execute: async () => [], - }) - } - const assembly = await ctx.get('systemPrompt')!.assemble() - expect(assembly.tools.map(tool => tool.name)).toEqual([ - 'zulu', - 'alpha', - 'ask_user_question', - 'create_goal', - 'get_goal', - 'skill', - 'task_kill', - 'task_list', - 'task_output', - 'update_goal', - ]) - await ctx.fiber.dispose() - }) - - it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => { - // A default export would make `unwrapExports` collapse this inject-less namespace and silently - // drop `name`/`Config` while the app still boots. Guard the postmortem-0001 shape directly. - expect('default' in stdioAgent).toBe(false) - expect(typeof stdioAgent.apply).toBe('function') - - const loader = Object.create(Loader.prototype) as Loader - const unwrapped = loader.unwrapExports(stdioAgent) as Record - expect(unwrapped).toBe(stdioAgent) - expect(unwrapped.name).toBe('stdio-demo') - expect(unwrapped.Config).toBeDefined() - expect(typeof unwrapped.apply).toBe('function') - }) -}) diff --git a/packages/examples/tui-demo/README.md b/packages/examples/tui-demo/README.md new file mode 100644 index 0000000000..2a10140f18 --- /dev/null +++ b/packages/examples/tui-demo/README.md @@ -0,0 +1,105 @@ +# @deepseek-ai/dsh-tui-demo + +The full-screen terminal app: a Cordis plugin that composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), persisted same-session goals, the human-command registry and `/goal` producer, JSONL persistence, keyboard-backed user interaction, a pre-created `main` agent, and [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md). Its `bin` boots a leaf `cordis.yml`. + +Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and other non-interactive runs. This package requires a TTY pair and has no line-oriented fallback. + +## What it bakes in + +| Plugin | Why it is here | +|---|---| +| `@deepseek-ai/dsh-agent-spine-demo` | Shared services, model-facing tools, and one configured `main` agent | +| `@deepseek-ai/dsh-commands` | Human-only discovery and dispatch consumed by the TUI and command plugins | +| `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack | +| `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` | +| `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service | +| `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays | +| `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool | + +Swappable LLM, bash, filesystem, and other capability providers remain in the leaf config. `@cordisjs/plugin-hmr` also remains a leaf-only development entry because it requires Loader internals. + +## Config + +| Key | Default | Routed to | +|---|---|---| +| `provider` | required | Configured `main` agent provider | +| `model` | required | Configured `main` agent model | +| `maxParallelToolCalls` | agent-loop default | Bundled loop concurrency cap | +| `persona` | — | System-prompt persona template | +| `toolOrder` | lexicographic | Explicit model-facing tool order | +| `tools` | owner default | Tool presentation mode | +| `dshHome` | owner default | Harness home used by bash and skills | +| `skills` | owner defaults | Skill registry, local provider, and tool config | +| `toolBash` | owner defaults | Model-facing bash tool config | +| `toolTasks` | owner defaults | Background-task control-tool config, or `false` | +| `goals` | owner defaults | Persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer | +| `workspaceContext` | required | Workspace-instruction config, or `false` | +| `persistenceRoot` | `./.sessions` | JSONL persistence root | +| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) | +| `welcome` | `ready.` | TUI subtitle | +| `ui` | owner defaults | TUI presentation settings such as reasoning, color, and card height | +| `resumeSessionId` | — | Exact persisted session to resume | + +Fresh runs mint a `main-session-` session id and pass it to both the TUI and configured agent. Resumed runs bind both components to `resumeSessionId`. The TUI mounts before the spine so it can render a matching config-start failure instead of leaving a blank terminal. + +## The bin + +`dsh-tui-demo [path-to-cordis.yml]` defaults to `./cordis.yml`, loads the optional cwd `.env`, boots the Cordis Loader, and waits for the full plugin tree. Bare package specifiers require `node --expose-internals` or the Loader's optional native fallback; the repository scripts use `--expose-internals`. + +## Example leaf + +```yaml +- id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + config: + apiKey: !!js process.env.DEEPSEEK_API_KEY +- id: bash + name: '@deepseek-ai/dsh-bash-local' +- id: tui-agent + name: '@deepseek-ai/dsh-tui-demo' + config: + provider: deepseek + model: deepseek-v4-flash + workspaceContext: + maxBytes: 65536 + welcome: 'Coding agent ready.' + ui: + showReasoning: true +``` + +## Model Experience + +### Interactive terminal turn + +#### What the model sees + +Each non-empty non-command editor submission becomes a user message; a submission during a running turn becomes steering. Slash-command input and output remain human-only, while accepted `/goal` mutations append domain-owned model-visible state. The shared spine contributes the configured persona, workspace instructions, skill catalog, goal controls, and visible tool schemas. TUI rendering itself is not model-visible. + +#### Token effect + +User, assistant, and tool history grows under the normal session and compaction rules. Headers, cards, plans, Markdown styling, and keybindings add no tokens. + +#### KV Cache effect + +Append-only while the composed prompt, schemas, route, and retained history prefix remain stable. Composition changes and compaction can invalidate reuse from the first changed token. + +### Human-question answer + +#### What the model sees + +`ask_user_question` retains the tool call and the compact answer or stable interruption error defined by `dsh-tool-ask-user`. The question overlay is terminal-only. + +#### Token effect + +Only the completed or failed tool result adds retained tokens. + +#### KV Cache effect + +Append-only; the answer follows the reusable request prefix. + +## Known Limitations and Deferred Work + +- **TTY-only** — stdin and stdout must both be terminals; automation uses `dsh-cli-demo`. +- **One configured terminal session** — the transcript and editor bind to one exact session id. +- **The app cluster is fixed** — JSONL persistence and ask-user tooling are baked in; different policy requires another composition. +- **Approval is separate** — this app answers `ctx.userInteraction`, not `ctx.approval`; permission prompts require an approval service and answerer. diff --git a/packages/examples/stdio-demo/package.json b/packages/examples/tui-demo/package.json similarity index 84% rename from packages/examples/stdio-demo/package.json rename to packages/examples/tui-demo/package.json index 17fbe8396d..be1cc01889 100644 --- a/packages/examples/stdio-demo/package.json +++ b/packages/examples/tui-demo/package.json @@ -1,13 +1,13 @@ { - "name": "@deepseek-ai/dsh-stdio-demo", - "description": "Terminal chat app: agent spine + human commands + JSONL persistence + TTY pi-tui/readline front-door selection + pre-created main agent", + "name": "@deepseek-ai/dsh-tui-demo", + "description": "Full-screen terminal app: agent spine + persisted goals + human commands + JSONL persistence + pi-tui front door + pre-created main agent", "version": "0.0.1", "private": true, "type": "module", "main": "lib/index.js", "types": "lib/types/index.d.ts", "bin": { - "dsh-stdio-demo": "lib/bin.js" + "dsh-tui-demo": "lib/bin.js" }, "exports": { ".": { @@ -32,7 +32,6 @@ "peerDependencies": { "@cordisjs/plugin-include": "^1.0.4", "@cordisjs/plugin-loader": "^1.0.0-rc.5", - "@cordisjs/plugin-logger-console": "^1.0.0", "@deepseek-ai/dsh-app-boot": "^0.0.1", "@deepseek-ai/dsh-agent": "^0.0.1", "@deepseek-ai/dsh-agent-loop": "^0.0.1", @@ -43,7 +42,6 @@ "@deepseek-ai/dsh-workspace-context": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1", - "@deepseek-ai/dsh-stdio": "^0.0.1", "@deepseek-ai/dsh-tui": "^0.0.1", "@deepseek-ai/dsh-tool-ask-user": "^0.0.1", "@deepseek-ai/dsh-tools": "^0.0.1", @@ -54,7 +52,6 @@ "devDependencies": { "@cordisjs/plugin-include": "workspace:^", "@cordisjs/plugin-loader": "workspace:^", - "@cordisjs/plugin-logger-console": "workspace:^", "@deepseek-ai/dsh-app-boot": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", @@ -66,7 +63,6 @@ "@deepseek-ai/dsh-workspace-context": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", - "@deepseek-ai/dsh-stdio": "workspace:^", "@deepseek-ai/dsh-tui": "workspace:^", "@deepseek-ai/dsh-tool-ask-user": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", diff --git a/packages/examples/stdio-demo/src/bin.ts b/packages/examples/tui-demo/src/bin.ts similarity index 66% rename from packages/examples/stdio-demo/src/bin.ts rename to packages/examples/tui-demo/src/bin.ts index 3d8a0c2a33..237e4391b5 100644 --- a/packages/examples/stdio-demo/src/bin.ts +++ b/packages/examples/tui-demo/src/bin.ts @@ -1,14 +1,14 @@ #!/usr/bin/env node /** - * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-demo [config]`, defaulting to the + * Boot a TUI app from a leaf `cordis.yml`; usage is `dsh-tui-demo [config]`, defaulting to the * cwd file. Shared `.env` loading, fail-loud Loader guards, and settled-tree boot live in - * dsh-app-boot. The echo-agent and repl-agent demos invoke this bin with their own leaf configs. - * @module @deepseek-ai/dsh-stdio-demo/bin + * dsh-app-boot. The tui-agent and cordis-agent demos invoke this bin with their own leaf configs. + * @module @deepseek-ai/dsh-tui-demo/bin */ import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot' -const NAME = 'dsh-stdio-demo' +const NAME = 'dsh-tui-demo' /* v8 ignore start -- thin self-executing composition over the unit-tested dsh-app-boot helpers; exercised end-to-end by the keyless Loader-path and diff --git a/packages/examples/tui-demo/src/index.ts b/packages/examples/tui-demo/src/index.ts new file mode 100644 index 0000000000..fc6d6cc8ad --- /dev/null +++ b/packages/examples/tui-demo/src/index.ts @@ -0,0 +1,139 @@ +/** + * Full-screen terminal app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}) + * plus persisted goals, human commands, JSONL persistence, keyboard-backed + * user interaction, and one pre-created agent whose exact session identity the + * TUI drives. Swappable adapters, executors, optional tools, and HMR stay in the leaf. This Loader plugin + * intentionally exposes named exports only; a default export would hide its + * `Config` schema (see docs/postmortem/0001). + * @module @deepseek-ai/dsh-tui-demo + */ + +import type { Context } from 'cordis' +import { randomUUID } from 'node:crypto' +import z from 'schemastery' +import { SessionId } from '@deepseek-ai/dsh-session' +import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' +import CommandService from '@deepseek-ai/dsh-commands' +import * as commandGoal from '@deepseek-ai/dsh-command-goal' +import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo' +import * as workspaceContext from '@deepseek-ai/dsh-workspace-context' +import SessionPersistenceJsonl, { + JsonlCompressionSchema, + type JsonlCompression, +} from '@deepseek-ai/dsh-session-persistence-jsonl' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' +import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' +import * as uiTui from '@deepseek-ai/dsh-tui' + +export const name = 'tui-demo' +const DEFAULT_PERSISTENCE_ROOT = './.sessions' +const DEFAULT_WELCOME = 'ready.' + +/** App config routed to the spine, TUI, configured agent, and JSONL backend. */ +export interface Config { + /** Provider route for the `main` agent. */ + provider: string + /** Model name for the `main` agent; a matching adapter must be registered. */ + model: string + /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ + maxParallelToolCalls?: number + /** Deployment persona forwarded to the system-prompt plugin. */ + persona?: string + /** Explicit model-facing tool order forwarded to the system-prompt plugin. */ + toolOrder?: string[] + /** Tool-registry presentation config forwarded through agent-spine-demo. */ + tools?: ToolsConfig + /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */ + dshHome?: string + /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ + persistenceRoot?: string + /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */ + persistenceCompression?: JsonlCompression + /** TUI subtitle rendered on start. Defaults to `ready.`. */ + welcome?: string + /** Full-screen TUI presentation settings. */ + ui?: uiTui.TuiConfig + /** Skill registry, local-provider, and model-facing consumer config. */ + skills?: agentCore.SkillConfig + /** Model-facing bash tool config forwarded through agent-spine-demo. */ + toolBash?: NonNullable + /** Generic background-task controls forwarded through agent-spine-demo; set false to omit them. */ + toolTasks?: NonNullable + /** Persisted same-session goals; owner defaults enable them, or false disables the stack and command. */ + goals?: agentCore.GoalConfig | false + /** Persisted session id to resume instead of creating a fresh session. */ + resumeSessionId?: string + /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */ + workspaceContext: agentCore.Config['workspaceContext'] +} + +// Each front door keeps a complete Loader schema so its deployment contract is +// readable without a cross-package config facade. +/* jscpd:ignore-start */ +export const Config: z = z.object({ + provider: z.string().required(), + model: z.string().required(), + maxParallelToolCalls: z.number().step(1).min(1), + persona: z.string(), + // Absent means lexicographic order; schemastery's native array default is []. + toolOrder: z.array(z.string()).default(undefined as unknown as string[]), + tools: ToolRegistry.Config, + dshHome: z.string(), + persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT), + persistenceCompression: JsonlCompressionSchema, + welcome: z.string().default(DEFAULT_WELCOME), + ui: uiTui.TuiConfigSchema, + skills: agentCore.SkillConfigSchema, + toolBash: agentCore.ToolBashConfigSchema, + toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]), + goals: z.union([z.const(false), agentCore.GoalConfigSchema]), + resumeSessionId: z.string(), + workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(), +}) +/* jscpd:ignore-end */ + +/** + * Compose the spine, TUI, JSONL persistence, and user-question tool around one + * exact fresh or resumed session identity. The TUI subscribes to startup + * failures before the spine creates the agent. + * @param ctx - context receiving the app's child plugins. + * @param config - validated app configuration. + */ +export function composeTuiApp(ctx: Context, config: Config): void { + const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId + const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`) + const goals = config.goals ?? {} + ctx.plugin(CommandService) + if (goals !== false) ctx.plugin(commandGoal) + ctx.plugin(SessionPersistenceJsonl, { + root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT, + ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }), + }) + ctx.plugin(UserInteractionService) + ctx.plugin(uiTui, { + ...config.ui, + welcome: config.welcome ?? DEFAULT_WELCOME, + sessionId, + }) + ctx.plugin(agentCore, { + ...agentCore.pickSpineConfig(config), + goals, + agents: [{ + id: SessionId('main'), + provider: config.provider, + model: config.model, + cwd: process.cwd(), + ...resumeSessionId === undefined ? { sessionId } : { resumeSessionId: sessionId }, + }], + }) + ctx.plugin(toolAskUser) +} + +/** + * Compose the configured full-screen terminal app. + * @param ctx - context receiving the app's child plugins. + * @param config - validated app configuration. + */ +export function apply(ctx: Context, config: Config): void { + composeTuiApp(ctx, config) +} diff --git a/packages/examples/tui-demo/tests/tui-agent.spec.ts b/packages/examples/tui-demo/tests/tui-agent.spec.ts new file mode 100644 index 0000000000..73aa61430a --- /dev/null +++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts @@ -0,0 +1,128 @@ +import { describe, expect, it } from 'vitest' +import type { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt' +import * as tuiAgent from '../src/index.ts' + +interface PluginCall { + readonly name: string + readonly config: unknown +} + +function recordingContext(): { readonly ctx: Context; readonly calls: PluginCall[] } { + const calls: PluginCall[] = [] + const ctx = { + plugin(plugin: { name?: string }, config?: unknown) { + calls.push({ name: plugin.name ?? '', config }) + }, + } as unknown as Context + return { ctx, calls } +} + +describe('dsh-tui-demo app', () => { + it('composes the TUI cluster around one fresh exact session identity', () => { + const { ctx, calls } = recordingContext() + tuiAgent.composeTuiApp(ctx, { + provider: 'mock', + model: 'mock-model', + maxParallelToolCalls: 3, + persona: 'test persona', + toolOrder: ['zulu', TOOL_ORDER_REST], + tools: { mode: 'code' }, + dshHome: '/tmp/dsh-home', + persistenceRoot: '/tmp/tui-sessions', + persistenceCompression: 'none', + welcome: 'TUI ready', + ui: { color: false, maxToolOutputLines: 3 }, + skills: { tool: { catalogDescriptionMaxLength: 8 } }, + toolBash: { enableRunInBackground: false }, + toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 }, + workspaceContext: false, + }) + + expect(calls.map(call => call.name)).toEqual([ + 'CommandService', + 'command-goal', + 'SessionPersistenceJsonl', + 'UserInteractionService', + 'ui-tui', + 'agent-spine-demo', + 'tool-ask-user', + ]) + expect(calls[0]?.config).toBeUndefined() + expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' }) + const tuiConfig = calls[4]?.config as { sessionId: string } + expect(tuiConfig).toMatchObject({ welcome: 'TUI ready', color: false, maxToolOutputLines: 3 }) + expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/) + const spineConfig = calls[5]?.config as { + readonly agents: Array> + readonly goals: Record + readonly maxParallelToolCalls: number + readonly persona: string + readonly toolOrder: string[] + readonly tools: { mode: string } + } + expect(spineConfig).toMatchObject({ + maxParallelToolCalls: 3, + persona: 'test persona', + toolOrder: ['zulu', TOOL_ORDER_REST], + tools: { mode: 'code' }, + goals: {}, + }) + expect(spineConfig.agents[0]).toMatchObject({ + id: 'main', + provider: 'mock', + model: 'mock-model', + cwd: process.cwd(), + sessionId: tuiConfig.sessionId, + }) + }) + + it('resumes the configured session and applies runtime defaults', () => { + const { ctx, calls } = recordingContext() + tuiAgent.composeTuiApp(ctx, { + provider: 'mock', + model: 'mock-model', + resumeSessionId: 'persisted-session', + workspaceContext: false, + }) + + expect(calls[2]?.config).toEqual({ root: './.sessions' }) + expect(calls[4]?.config).toEqual({ welcome: 'ready.', sessionId: 'persisted-session' }) + expect((calls[5]?.config as { agents: Array> }).agents[0]).toMatchObject({ + id: 'main', + resumeSessionId: 'persisted-session', + }) + }) + + it('normalizes an empty resume id and routes apply through the same composition', () => { + const { ctx, calls } = recordingContext() + tuiAgent.apply(ctx, { + provider: 'mock', + model: 'mock-model', + resumeSessionId: '', + goals: false, + workspaceContext: false, + }) + + const tuiConfig = calls[3]?.config as { sessionId: string } + expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/) + expect((calls[4]?.config as { agents: Array> }).agents[0]) + .toMatchObject({ sessionId: tuiConfig.sessionId }) + expect(calls.map(call => call.name)).not.toContain('command-goal') + expect(calls[4]?.config).toMatchObject({ goals: false }) + }) + + it('has the namespace-plugin export shape so the Loader keeps its schema', () => { + expect(tuiAgent.name).toBe('tui-demo') + expect(tuiAgent.Config).toBeDefined() + expect('default' in tuiAgent).toBe(false) + expect(typeof tuiAgent.apply).toBe('function') + + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(tuiAgent) as Record + expect(unwrapped).toBe(tuiAgent) + expect(unwrapped.name).toBe('tui-demo') + expect(unwrapped.Config).toBeDefined() + }) +}) diff --git a/packages/examples/stdio-demo/tsconfig.json b/packages/examples/tui-demo/tsconfig.json similarity index 89% rename from packages/examples/stdio-demo/tsconfig.json rename to packages/examples/tui-demo/tsconfig.json index 16d1108e20..7be6265128 100644 --- a/packages/examples/stdio-demo/tsconfig.json +++ b/packages/examples/tui-demo/tsconfig.json @@ -20,9 +20,6 @@ { "path": "../../ui/app-boot" }, - { - "path": "../../../vendor/logger-console" - }, { "path": "../../core/agent" }, @@ -44,9 +41,6 @@ { "path": "../../ui/user-interaction" }, - { - "path": "../../ui/stdio" - }, { "path": "../../ui/tui" }, diff --git a/packages/examples/stdio-demo/tsdown.config.ts b/packages/examples/tui-demo/tsdown.config.ts similarity index 87% rename from packages/examples/stdio-demo/tsdown.config.ts rename to packages/examples/tui-demo/tsdown.config.ts index 53797cdd79..b3929c6d76 100644 --- a/packages/examples/stdio-demo/tsdown.config.ts +++ b/packages/examples/tui-demo/tsdown.config.ts @@ -1,7 +1,7 @@ import { defineConfig } from 'tsdown' /** - * stdio-agent ships TWO entries: the plugin (`index`) and the CLI `bin` + * tui-demo ships two entries: the plugin (`index`) and the CLI `bin` * (`bin`), the latter referenced by package.json `bin`/`exports["./bin"]`. * The root tsdown builds only `lib/types/index.js`, so this override adds * `lib/types/bin.js`. Declarations come from `tsc -b` (dts: false), diff --git a/packages/goal/command-goal/README.md b/packages/goal/command-goal/README.md index f766cd3ece..d47e5df1e4 100644 --- a/packages/goal/command-goal/README.md +++ b/packages/goal/command-goal/README.md @@ -30,7 +30,7 @@ The producer injects `commands` and `goals`. A custom app mounts their owners pl name: '@deepseek-ai/dsh-command-goal' ``` -The TUI and ACP demo apps enable the complete persisted-goal stack and this command by default; `goals: false` removes both. The terminal app's readline mode keeps the model-mediated goal stack but does not mount this producer because that front door does not consume commands. The UI-less `agent-spine-demo` requires an explicit `goals: {}` so headless one-shot callers do not silently change from one physical turn to a multi-round operation. +The TUI and ACP demo apps enable the complete persisted-goal stack and this command by default; `goals: false` removes both. The UI-less `agent-spine-demo` requires an explicit `goals: {}` so headless one-shot callers do not silently change from one physical turn to a multi-round operation. ## Model Experience @@ -53,4 +53,4 @@ Command discovery and direct output do not affect the cache. A mutation appends - **Plain-text interaction only** — the generic command registry has no modal edit form or replacement-confirmation callback; inline edit and explicit clear keep destructive intent deterministic on both TUI and ACP. - **No per-command round-cap argument** — `defaultMaxGoalRounds` remains deployment config, while a direct human request may ask the model to edit `max_goal_rounds` through the separately authorized goal tool. - **No continuous status widget** — bare `/goal` is the portable observation surface; adapter-specific badges and reconnectable command output remain future UI work. -- **TUI and ACP only** — the line-oriented stdio and JSON-RPC adapters do not consume `ctx.commands`. Their ordinary human prompts can still authorize the model-facing goal tools when those are composed. +- **TUI and ACP only** — the headless CLI and JSON-RPC adapters do not consume `ctx.commands`. Ordinary human prompts can still authorize the model-facing goal tools when those are composed. diff --git a/packages/goal/goal/tests/goal.e2e.ts b/packages/goal/goal/tests/goal.e2e.ts index eb6eae665a..0c582645bc 100644 --- a/packages/goal/goal/tests/goal.e2e.ts +++ b/packages/goal/goal/tests/goal.e2e.ts @@ -1,32 +1,17 @@ -import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process' -import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises' -import { tmpdir } from 'node:os' +import { readFile, readdir } from 'node:fs/promises' import { join } from 'node:path' import { fileURLToPath } from 'node:url' -import { afterEach, describe, expect, it } from 'vitest' +import { describe, expect, it } from 'vitest' import type { SessionEvent } from '@deepseek-ai/dsh-session' import { decodeGoalChange, renderGoalChange } from '@deepseek-ai/dsh-goal' -import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' +import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' -const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url)) +const binScript = fileURLToPath(new URL('../../../examples/cli-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL( - '../../../../examples/echo-agent/tests/fixtures/goal/goal/cordis.yml', + '../../../../examples/headless-agent/tests/fixtures/goal-domain/cordis.yml', import.meta.url, )) const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) -const PROCESS_TIMEOUT_MS = 30_000 -const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000 -const REPLY = 'You said: "hello". Try "echo " to see a tool call.' - -let child: ChildProcessWithoutNullStreams | undefined -let workdir: string | undefined - -afterEach(async () => { - if (child !== undefined && child.exitCode === null) child.kill('SIGKILL') - child = undefined - if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) - workdir = undefined -}) async function jsonlFiles(dir: string): Promise { const entries = await readdir(dir, { withFileTypes: true }) @@ -38,67 +23,32 @@ async function jsonlFiles(dir: string): Promise { return paths.flat() } -async function runOneTurn(): Promise<{ stdout: string; stderr: string }> { - workdir = await mkdtemp(join(tmpdir(), 'goal-domain-e2e-')) - const cwd = workdir - return new Promise((resolve, reject) => { - const launch = resolveExampleLaunch({ - srcBin: binScript, - configArgs: [configPath], +describe('goal domain through a real cordis.yml and headless process', () => { + it('persists the Loader-mounted snapshot without starting a goal round', async () => { + let events: SessionEvent[] = [] + const { stdout, stderr } = await runLoaderSmoke({ + label: 'goal-domain', + tempDirPrefix: 'goal-domain-e2e-', + binScript, + configPath, + binArgs: ['--config', configPath, '--output-format', 'json', 'prove the persisted goal domain'], tsconfigPath: repoTsconfig, - exposeInternals: true, - env: { - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), + inspect: async (cwd) => { + const logs = await jsonlFiles(join(cwd, '.sessions')) + expect(logs).toHaveLength(1) + const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n') + events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent) }, }) - const proc = spawn(launch.command, launch.args, { - cwd, - env: { ...process.env, ...launch.env }, - stdio: ['pipe', 'pipe', 'pipe'], + expect(stderr).toBe('') + const result = JSON.parse(stdout) as Record + expect(result).toMatchObject({ + type: 'result', + success: true, }) - child = proc - let stdout = '' - let stderr = '' - let inputClosed = false - proc.stdout.setEncoding('utf8') - proc.stdout.on('data', (chunk: string) => { - stdout += chunk - if (!inputClosed && stdout.includes(REPLY)) { - inputClosed = true - proc.stdin.end() - } - }) - proc.stderr.setEncoding('utf8') - proc.stderr.on('data', (chunk: string) => { stderr += chunk }) - - const timer = setTimeout(() => { - proc.kill('SIGKILL') - reject(new Error(`goal-domain e2e did not exit within ${PROCESS_TIMEOUT_MS / 1_000}s. stdout:\n${stdout}\nstderr:\n${stderr}`)) - }, PROCESS_TIMEOUT_MS) - - proc.on('exit', (code) => { - clearTimeout(timer) - if (code === 0) resolve({ stdout, stderr }) - else reject(new Error(`goal-domain e2e exited ${String(code)}. stdout:\n${stdout}\nstderr:\n${stderr}`)) - }) - proc.on('error', (error) => { clearTimeout(timer); reject(error) }) - proc.stdin.write('hello\n') - }) -} - -describe('goal domain through a real cordis.yml and stdio process', () => { - it('persists the Loader-created snapshot without starting a goal round', async () => { - const { stdout, stderr } = await runOneTurn() - expect(stderr).not.toContain('UNHANDLED') - expect(stdout).toContain('goal-domain e2e ready.') - expect(stdout).toContain(REPLY) - - const logs = await jsonlFiles(join(workdir as string, '.sessions')) - expect(logs).toHaveLength(1) - const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n') - const events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent) - expect(events.filter(event => event.type === 'turn/end')).toHaveLength(2) + expect(result['result']).toBeTypeOf('string') + expect(result['result']).toContain('CLI tool round trip complete') + expect(events.filter(event => event.type === 'turn/end')).toHaveLength(1) const contexts = events.filter(event => event.type === 'context/message' && event.data.source.kind === 'goal') @@ -121,5 +71,5 @@ describe('goal domain through a real cordis.yml and stdio process', () => { expect(JSON.stringify(context)).not.toContain('activation') expect(events.filter(event => event.type === 'user/message' && event.data.source.kind === 'goal')).toHaveLength(0) - }, TEST_TIMEOUT_MS) + }, LOADER_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md index 27bf4b626a..ee4c705560 100644 --- a/packages/llm/llm-deepseek/README.md +++ b/packages/llm/llm-deepseek/README.md @@ -42,7 +42,7 @@ Every request carries the shared attribution header from dsh-llm's `attributionH ## Errors -Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `CONTEXT_WINDOW_EXCEEDED` (a 400 whose provider code, type, or message identifies context overflow), `INVALID_REQUEST` (other 400s), `SERVER` (5xx), `HTTP_` otherwise. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: }` chunks. +Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `CONTEXT_WINDOW_EXCEEDED` (a 400 whose provider code, type, or message identifies context overflow), `INVALID_REQUEST` (other 400s), `SERVER` (5xx), `HTTP_` otherwise. A transport failure before any response (DNS, refused connection, TLS, proxy) throws `NETWORK` naming the configured endpoint and chaining fetch's `TypeError: fetch failed` as `cause`, so `errorChain` renders the underlying diagnosis; an abort keeps its `DOMException` so the loop classifies it as cancellation. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: }` chunks. ## Testing diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts index 918c8eee82..66520a83d4 100644 --- a/packages/llm/llm-deepseek/src/adapter.ts +++ b/packages/llm/llm-deepseek/src/adapter.ts @@ -81,23 +81,43 @@ export class DeepSeekAdapter extends LlmAdapter { async * stream(options: GenerateOptions): AsyncIterable { const body = serializeRequest(options, this.options.defaults ?? {}) + // Prepared outside the try so the NETWORK label below covers exactly the + // transport boundary, never a serialization failure. + const payload = JSON.stringify(body) + const headers = { + 'authorization': `Bearer ${this.options.apiKey}`, + 'content-type': 'application/json', + 'accept': 'text/event-stream', + ...attributionHeaders(), + ...options.sessionId !== undefined + ? { 'x-deepseek-harness-session-id': String(options.sessionId) } + : {}, + } // TODO(http): adopt the Cordis HTTP service when shared transport configuration // outweighs its additional runtime dependencies. - const response = await fetch(`${this.options.baseURL}/chat/completions`, { - method: 'POST', - headers: { - 'authorization': `Bearer ${this.options.apiKey}`, - 'content-type': 'application/json', - 'accept': 'text/event-stream', - ...attributionHeaders(), - ...options.sessionId !== undefined - ? { 'x-deepseek-harness-session-id': String(options.sessionId) } - : {}, - }, - body: JSON.stringify(body), - ...options.signal ? { signal: options.signal } : {}, - }) + let response: Response + try { + response = await fetch(`${this.options.baseURL}/chat/completions`, { + method: 'POST', + headers, + body: payload, + ...options.signal ? { signal: options.signal } : {}, + }) + } catch (error: unknown) { + // An aborted request rethrows its original rejection (the signal's abort + // reason) so the loop classifies it as cancellation, not a provider failure. + if (options.signal?.aborted) throw error + // fetch wraps every transport failure (DNS, refused connection, TLS, + // proxy) in a bare `TypeError: fetch failed` whose actionable detail + // lives on `cause`. Wrapping with the endpoint and chaining the cause + // lets `errorChain` render the full diagnosis at every reporting seam. + throw new LlmError( + `DeepSeek API request to ${this.options.baseURL} failed`, + 'NETWORK', + { cause: error }, + ) + } if (!response.ok) { let message = `DeepSeek API error (HTTP ${response.status})` diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts index 954a0ecebd..b92f96dbda 100644 --- a/packages/llm/llm-deepseek/tests/adapter.spec.ts +++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts @@ -2,7 +2,7 @@ import { createServer } from 'node:http' import type { IncomingMessage, Server, ServerResponse } from 'node:http' import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, userAgent } from '@deepseek-ai/dsh-llm' +import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, errorChain, LlmError, userAgent } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' import { DeepSeekAdapter } from '@deepseek-ai/dsh-llm-deepseek' @@ -228,6 +228,39 @@ describe('DeepSeekAdapter against a mock server', () => { expect(httpErrorCode(418)).toBe('HTTP_418') }) + it('wraps a transport failure in NETWORK with the fetch cause chain in the message', async () => { + // Port 1 is reserved/unbound: fetch rejects with `TypeError: fetch failed` + // whose actionable detail (ECONNREFUSED) lives on `cause`. + const ctx = await harness('http://127.0.0.1:1') + let caught: unknown + try { + await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] }) + } catch (error: unknown) { + caught = error + } + expect(caught).toBeInstanceOf(LlmError) + const llmError = caught as LlmError + expect(llmError.code).toBe('NETWORK') + expect(llmError.message).toContain('http://127.0.0.1:1') + expect(llmError.cause).toBeInstanceOf(TypeError) + // The chain renderer reaches the transport diagnosis through the cause. + expect(errorChain(llmError)).toMatch(/ECONNREFUSED|EADDRNOTAVAIL|bad port/) + }) + + it('keeps an abort rejection unwrapped so the loop classifies it as cancellation', async () => { + const controller = new AbortController() + controller.abort() + const ctx = await harness('http://127.0.0.1:1') + let caught: unknown + try { + await assemble(ctx, { model: 'deepseek-v4-flash', messages: [], signal: controller.signal }) + } catch (error: unknown) { + caught = error + } + expect(caught).not.toBeInstanceOf(LlmError) + expect((caught as Error).name).toBe('AbortError') + }) + it('throws EMPTY_RESPONSE when the response has no body', async () => { const adapter = new DeepSeekAdapter({ apiKey: 'k', baseURL: 'http://127.0.0.1:1' }) const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue( diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md index f9142dbc52..82ca7f901c 100644 --- a/packages/llm/llm/README.md +++ b/packages/llm/llm/README.md @@ -48,6 +48,7 @@ Every product adapter sends application identity on provider HTTP requests. `att - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history. - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams. - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) is the programmatic failure contract. +- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result. - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail. ### Real adapters diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts index 8c1c736492..c351060ee5 100644 --- a/packages/llm/llm/src/error.ts +++ b/packages/llm/llm/src/error.ts @@ -62,6 +62,51 @@ export function isContextWindowExceededError(detail: string): boolean { || EXCEEDS_MODEL_CONTEXT.test(detail) } +/** + * Render a thrown value with its full `cause` chain and AggregateError + * members, so transport wrappers like undici's `TypeError: fetch failed` + * surface the underlying failure instead of masking it. Diagnostic-surface + * rendering only (messages, notices, logs) — never parse the result; route on + * {@link HarnessError.code}. + * @param value - the caught value (`unknown` in catch clauses). + * @returns the outermost message first, each cause appended with `: ` (skipped + * when it repeats the wrapper message verbatim), and AggregateError members + * bracketed and `; `-joined. + */ +export function errorChain(value: unknown): string { + // Tracks the active recursion path (entries removed on exit), so only true + // cycles are flagged and a diamond-shared cause still renders in full. + const path = new Set() + const render = (current: unknown): string => { + if (path.has(current)) return '' + path.add(current) + try { + if (!(current instanceof Error)) return String(current) + const message = current.message === '' ? current.name : current.message + const members = current instanceof AggregateError && current.errors.length > 0 + ? ` [${current.errors.map(render).join('; ')}]` + : '' + const causeText = current.cause === undefined || current.cause === null + ? '' + : render(current.cause) + // Wrappers like `new HarnessError(String(value), code, { cause: value })` + // repeat their cause verbatim; rendering it again would only add noise. + const cause = causeText === '' || causeText === message ? '' : `: ${causeText}` + return `${message}${members}${cause}` + } catch { + // Only hostile coercion or hostile accessors (a throwing toString / + // Symbol.toPrimitive on a non-Error, or a throwing message/name/cause/ + // errors getter on an Error subclass): this renderer feeds UI notices + // and logs, so nothing may escape. Inner frames catch their own throws, + // so only the hostile node collapses, not the whole chain. + return '' + } finally { + path.delete(current) + } + } + return render(value) +} + /** * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams). * @param value - the caught value (`unknown` in catch clauses). diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts index 6e14d749ba..67b90d1c2f 100644 --- a/packages/llm/llm/tests/service.spec.ts +++ b/packages/llm/llm/tests/service.spec.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import LlmService, { + errorChain, GenerateOptions, HarnessError, isContextWindowExceededError, @@ -80,6 +81,50 @@ describe('LlmService', () => { expect(isContextWindowExceededError('context window size must be positive')).toBe(false) }) + it('errorChain renders the full cause chain of a wrapped transport failure', () => { + const chain = new TypeError('fetch failed', { cause: new Error('connect ECONNREFUSED 127.0.0.1:443') }) + expect(errorChain(chain)).toBe('fetch failed: connect ECONNREFUSED 127.0.0.1:443') + }) + + it('errorChain renders AggregateError members (Happy Eyeballs multi-address failures)', () => { + const aggregate = new AggregateError( + [new Error('connect ECONNREFUSED ::1:443'), new Error('connect ECONNREFUSED 127.0.0.1:443')], + '', + ) + const wrapped = new TypeError('fetch failed', { cause: aggregate }) + expect(errorChain(wrapped)).toBe( + 'fetch failed: AggregateError [connect ECONNREFUSED ::1:443; connect ECONNREFUSED 127.0.0.1:443]', + ) + }) + + it('errorChain survives non-Error values, hostile coercion, and circular causes', () => { + expect(errorChain('plain string')).toBe('plain string') + expect(errorChain({ toString: () => { throw new Error('hostile') } })).toBe('') + const circular = new Error('outer') + circular.cause = circular + expect(errorChain(circular)).toBe('outer: ') + // A hostile accessor collapses only its own node, not the whole chain. + const hostileNode = new Error('node') + Object.defineProperty(hostileNode, 'message', { get() { throw new Error('hostile getter') } }) + expect(errorChain(new Error('outer', { cause: hostileNode }))).toBe('outer: ') + // A diamond-shared (non-cyclic) cause renders in full on both paths. + const shared = new Error('shared') + const diamond = new AggregateError([new Error('a', { cause: shared }), new Error('b', { cause: shared })], 'agg') + expect(errorChain(diamond)).toBe('agg [a: shared; b: shared]') + }) + + it('errorChain falls back to the error name, skips empty aggregates, and stops at null causes', () => { + expect(errorChain(new TypeError('', { cause: null }))).toBe('TypeError') + expect(errorChain(new AggregateError([], 'all failed'))).toBe('all failed') + }) + + it('errorChain collapses a cause that repeats the wrapper message verbatim', () => { + // The `new HarnessError(String(value), code, { cause: value })` normalization + // pattern repeats its cause; rendering it twice would only add noise. + const wrapped = new HarnessError('boom', 'UNKNOWN', { cause: 'boom' }) + expect(errorChain(wrapped)).toBe('boom') + }) + it('routes stream() to the registered adapter', async () => { const ctx = new Context() await ctx.plugin(LlmService) diff --git a/packages/sdk/create-sdk/src/args.ts b/packages/sdk/create-sdk/src/args.ts index 897159bd7c..2b156f7fb5 100644 --- a/packages/sdk/create-sdk/src/args.ts +++ b/packages/sdk/create-sdk/src/args.ts @@ -61,7 +61,7 @@ function createProgram(): Command { .option('--base-url ') .option('--api-key ') .option('--model ') - .addOption(new Option('--interface ').choices(['acp', 'stdio', 'embed'])) + .addOption(new Option('--interface ').choices(['acp', 'tui', 'embed'])) .addOption(new Option('--pm ').choices(['npm', 'pnpm', 'yarn'])) .addOption(new Option('--install').default(undefined)) .addOption(new Option('--no-install').default(undefined)) diff --git a/packages/sdk/create-sdk/src/create-questions.ts b/packages/sdk/create-sdk/src/create-questions.ts index c53e6e227e..193f1fdc25 100644 --- a/packages/sdk/create-sdk/src/create-questions.ts +++ b/packages/sdk/create-sdk/src/create-questions.ts @@ -169,10 +169,10 @@ const PROJECT_QUESTION_STEPS: readonly WizardStep[] = [ message: 'Run interface', options: [ { value: 'acp', label: 'ACP server' }, - { value: 'stdio', label: 'Terminal REPL' }, + { value: 'tui', label: 'Terminal TUI' }, { value: 'embed', label: 'Embedded context' }, ], - initialValue: 'stdio', + initialValue: 'tui', }), prefilled: state => state.args.runInterface, apply: (state, value) => { state.runInterface = value }, diff --git a/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl index 32f4d5c6d2..1842571cdd 100644 --- a/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl +++ b/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl @@ -6,7 +6,7 @@ Options: --base-url --api-key --model - --interface + --interface --pm --install / --no-install --config diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/sdk/create-sdk/tests/create.snapshot.ts index a5ea46db53..08aa4a5a73 100644 --- a/packages/sdk/create-sdk/tests/create.snapshot.ts +++ b/packages/sdk/create-sdk/tests/create.snapshot.ts @@ -179,12 +179,12 @@ describe('create-sdk terminal contract', () => { "message": "DeepSeek API key", }, { - "initialValue": "stdio", + "initialValue": "tui", "kind": "select", "message": "Run interface", "options": [ "ACP server", - "Terminal REPL", + "Terminal TUI", "Embedded context", ], }, diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/sdk/create-sdk/tests/create.spec.ts index c7c74c9659..f6dc8e1709 100644 --- a/packages/sdk/create-sdk/tests/create.spec.ts +++ b/packages/sdk/create-sdk/tests/create.spec.ts @@ -151,7 +151,7 @@ describe('create arguments', () => { expect(() => parseCreateArgs(['--link-packages-workspace'])).toThrow("unknown option '--link-packages-workspace'") expect(parseCreateArgs(['--provider=custom']).provider).toBe('custom') expect(parseCreateArgs(['--help']).help).toBe(true) - expect(() => parseCreateArgs(['--interface=bad'])).toThrow('Allowed choices are acp, stdio, embed') + expect(() => parseCreateArgs(['--interface=bad'])).toThrow('Allowed choices are acp, tui, embed') expect(() => parseCreateArgs(['--unknown'])).toThrow("unknown option '--unknown'") expect(() => parseCreateArgs(['one', 'two'])).toThrow('too many arguments') }) @@ -208,7 +208,7 @@ describe('CreateWizard and scaffolder', () => { '--provider=deepseek', '--api-key=deepseek-key', '--model=deepseek-v4-flash', - '--interface=stdio', + '--interface=tui', '--pm=npm', '--no-install', '--link-workspace', @@ -247,7 +247,7 @@ describe('CreateWizard and scaffolder', () => { const resolved = await new CreateWizard({ args: parseCreateArgs([ 'my-agent', '--description=demo', '--provider=deepseek', '--api-key=deepseek-key', - '--model=deepseek-v4-flash', '--interface=stdio', '--pm=npm', '--no-install', + '--model=deepseek-v4-flash', '--interface=tui', '--pm=npm', '--no-install', ]), port: new HeadlessPromptPort(), cwd, @@ -275,7 +275,7 @@ describe('CreateWizard and scaffolder', () => { await expect(new CreateWizard({ args: parseCreateArgs([ 'my-agent', '--description=demo', '--provider=deepseek', '--api-key=k', - '--model=m', '--interface=stdio', '--pm=npm', '--no-install', + '--model=m', '--interface=tui', '--pm=npm', '--no-install', ]), port: new HeadlessPromptPort(), cwd, diff --git a/packages/sdk/helper/src/features/builtin/app.ts b/packages/sdk/helper/src/features/builtin/app.ts index 4e72ba5a41..835a9a8710 100644 --- a/packages/sdk/helper/src/features/builtin/app.ts +++ b/packages/sdk/helper/src/features/builtin/app.ts @@ -29,7 +29,7 @@ const ID = featureId('app') function appProjectResources( profile: ProjectProfile, - runInterface: 'acp' | 'stdio' | 'embed', + runInterface: 'acp' | 'tui' | 'embed', ): readonly ProjectResource[] { const context = createProjectTemplateContext(profile, runInterface) const scripts = createAppPackageScripts(context) @@ -43,10 +43,10 @@ function appProjectResources( } class AppOption extends FeatureOption { - override readonly id: 'acp' | 'stdio' | 'embed' + override readonly id: 'acp' | 'tui' | 'embed' override readonly label: string - constructor(id: 'acp' | 'stdio' | 'embed', label: string) { + constructor(id: 'acp' | 'tui' | 'embed', label: string) { super() this.id = id this.label = label @@ -56,7 +56,7 @@ class AppOption extends FeatureOption { override markerConfigEntries(): readonly { id: string; name: string }[] { switch (this.id) { case 'acp': return [{ id: 'acp', name: '@deepseek-ai/dsh-acp' }] - case 'stdio': return [{ id: 'stdio', name: '@deepseek-ai/dsh-stdio' }] + case 'tui': return [{ id: 'tui', name: '@deepseek-ai/dsh-tui' }] case 'embed': return [] } } @@ -65,7 +65,7 @@ class AppOption extends FeatureOption { override matchesConfigEntries(entries: readonly { id: string; name: string }[], profile: ProjectProfile): boolean { if (this.id !== 'embed') return super.matchesConfigEntries(entries, profile) return entries.some(entry => entry.id === 'agent-loop' && entry.name === '@deepseek-ai/dsh-agent-loop') - && !entries.some(entry => entry.name === '@deepseek-ai/dsh-acp' || entry.name === '@deepseek-ai/dsh-stdio') + && !entries.some(entry => entry.name === '@deepseek-ai/dsh-acp' || entry.name === '@deepseek-ai/dsh-tui') } override contribution(profile: ProjectProfile): ProjectContribution { @@ -87,7 +87,7 @@ class AppOption extends FeatureOption { config: { model: profile.runtime.model }, }, ['model'], config => requiredString(config, 'model')), ]) - case 'stdio': + case 'tui': return new ProjectContribution([ ...appProjectResources(profile, this.id), ...npmCordisConfigEntry(ID, { @@ -95,10 +95,10 @@ class AppOption extends FeatureOption { name: '@deepseek-ai/dsh-user-interaction', }), ...npmCordisConfigEntry(ID, { - id: 'stdio', - name: '@deepseek-ai/dsh-stdio', + id: 'tui', + name: '@deepseek-ai/dsh-tui', config: { - welcome: 'agent REPL ready. Give it a coding task.', + welcome: 'TUI agent ready. Give it a coding task.', sessionId: new JsExpression('process.env.DSH_SDK_SESSION_ID'), }, }, ['welcome', 'sessionId'], config => [ @@ -112,7 +112,7 @@ class AppOption extends FeatureOption { } } -/** Required app selection represented by acp, stdio, or embed options. */ +/** Required app selection represented by ACP, TUI, or embed options. */ export class AppFeature extends ExclusiveOptionFeature { override readonly id = ID override readonly summary = 'Run interface' @@ -120,7 +120,7 @@ export class AppFeature extends ExclusiveOptionFeature { override readonly requires = [featureId('spine')] override readonly options = [ new AppOption('acp', 'ACP server'), - new AppOption('stdio', 'Terminal REPL'), + new AppOption('tui', 'Terminal TUI'), new AppOption('embed', 'Embedded context'), ] diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/sdk/helper/src/features/builtin/index.ts index c4043e7d59..29889b438e 100644 --- a/packages/sdk/helper/src/features/builtin/index.ts +++ b/packages/sdk/helper/src/features/builtin/index.ts @@ -347,7 +347,7 @@ config: id: 'ask-user', summary: 'Ask the user from the model loop', mode: 'single', - supportedInterfaces: ['acp', 'stdio'], + supportedInterfaces: ['acp', 'tui'], options: [{ id: 'default', label: 'ask_user_question tool', diff --git a/packages/sdk/helper/src/features/define-feature.ts b/packages/sdk/helper/src/features/define-feature.ts index 7c90a2853a..6b726d42d6 100644 --- a/packages/sdk/helper/src/features/define-feature.ts +++ b/packages/sdk/helper/src/features/define-feature.ts @@ -250,7 +250,7 @@ class DefinedFeature extends Feature { this.required = spec.required ?? false this.requires = (spec.requires ?? []).map(requirement => featureId(requirement.id)) this.suggests = (spec.suggests ?? []).map(featureId) - this.supportedInterfaces = spec.supportedInterfaces ?? ['acp', 'stdio', 'embed'] + this.supportedInterfaces = spec.supportedInterfaces ?? ['acp', 'tui', 'embed'] } override defaultOptions(): readonly string[] { diff --git a/packages/sdk/helper/src/features/feature.ts b/packages/sdk/helper/src/features/feature.ts index 1335d8e29b..b77deb8093 100644 --- a/packages/sdk/helper/src/features/feature.ts +++ b/packages/sdk/helper/src/features/feature.ts @@ -113,7 +113,7 @@ export abstract class Feature { /** Features recommended during creation. */ readonly suggests: readonly FeatureId[] = [] /** Front doors under which this feature is meaningful. */ - readonly supportedInterfaces: readonly RunInterface[] = ['acp', 'stdio', 'embed'] + readonly supportedInterfaces: readonly RunInterface[] = ['acp', 'tui', 'embed'] /** * Options selected when installation has no override. diff --git a/packages/sdk/helper/src/project/project-edit-session.ts b/packages/sdk/helper/src/project/project-edit-session.ts index 0d0a1cb6dd..d027d74e08 100644 --- a/packages/sdk/helper/src/project/project-edit-session.ts +++ b/packages/sdk/helper/src/project/project-edit-session.ts @@ -549,7 +549,7 @@ export class ProjectEditSession implements FeatureProjectView { private finalProfile(): ProjectProfile { const runInterface = this.states.get(featureId('app'))?.selection?.options[0] - if (runInterface !== 'acp' && runInterface !== 'stdio' && runInterface !== 'embed') return this.profile + if (runInterface !== 'acp' && runInterface !== 'tui' && runInterface !== 'embed') return this.profile return { ...this.profile, runInterface } } diff --git a/packages/sdk/helper/src/project/sdk-project.ts b/packages/sdk/helper/src/project/sdk-project.ts index cd55ffe2e5..a24a08b3df 100644 --- a/packages/sdk/helper/src/project/sdk-project.ts +++ b/packages/sdk/helper/src/project/sdk-project.ts @@ -42,7 +42,7 @@ const OPTIONAL_DOCUMENTS = [ function runInterface(entries: readonly CordisConfigEntry[]): RunInterface { if (entries.some(entry => entry.name === '@deepseek-ai/dsh-acp')) return 'acp' - if (entries.some(entry => entry.name === '@deepseek-ai/dsh-stdio')) return 'stdio' + if (entries.some(entry => entry.name === '@deepseek-ai/dsh-tui')) return 'tui' return 'embed' } @@ -146,7 +146,7 @@ export class SdkProject { static create(root: string, request: ProjectCreationRequest): SdkProject { const app = request.features.find(selection => selection.id === 'app') const selectedInterface = app?.options[0] - if (selectedInterface !== 'acp' && selectedInterface !== 'stdio' && selectedInterface !== 'embed') { + if (selectedInterface !== 'acp' && selectedInterface !== 'tui' && selectedInterface !== 'embed') { throw new Error('project creation requires one app feature option') } const profile: ProjectProfile = { diff --git a/packages/sdk/helper/src/project/types.ts b/packages/sdk/helper/src/project/types.ts index 44d06d508c..11fca01b8d 100644 --- a/packages/sdk/helper/src/project/types.ts +++ b/packages/sdk/helper/src/project/types.ts @@ -9,7 +9,7 @@ import type { LocalPluginBlueprint } from '../plugins/local-plugin-blueprint.ts' import type { FeatureId } from '../ids.ts' /** Runtime front door selected for a generated project. */ -export type RunInterface = 'acp' | 'stdio' | 'embed' +export type RunInterface = 'acp' | 'tui' | 'embed' /** Values shared by the required provider and app features. */ interface ProjectRuntimeOptions { diff --git a/packages/sdk/helper/src/templates/assets/README.md.tpl b/packages/sdk/helper/src/templates/assets/README.md.tpl index 0033c8e0d4..bdaef06c4e 100644 --- a/packages/sdk/helper/src/templates/assets/README.md.tpl +++ b/packages/sdk/helper/src/templates/assets/README.md.tpl @@ -9,7 +9,7 @@ Built with the DeepSeek Harness SDK using the {{model}} model. Run `{{packageManager}} start` and configure your ACP client to launch this project. Standard output is reserved for ACP JSON-RPC. {{else}} -{{#if isStdio}} +{{#if isTui}} ## Run in a terminal Run `{{packageManager}} start` to start the interactive agent. diff --git a/packages/sdk/helper/src/templates/assets/index.ts.tpl b/packages/sdk/helper/src/templates/assets/index.ts.tpl index a79818908c..311c6746cf 100644 --- a/packages/sdk/helper/src/templates/assets/index.ts.tpl +++ b/packages/sdk/helper/src/templates/assets/index.ts.tpl @@ -8,18 +8,18 @@ import { startSDK, type SdkBootContext } from '@deepseek-ai/dsh-scripts' /** Boot this project's cordis.yml when invoked by dsh-scripts. */ export async function main(boot: SdkBootContext) { -{{#if isStdio}} +{{#if isTui}} const model = boot.args.model - if (typeof model !== 'string' || model.length === 0) throw new Error('stdio startup requires --model=') + if (typeof model !== 'string' || model.length === 0) throw new Error('TUI startup requires --model=') const resume = boot.args.resume if (resume !== undefined && (typeof resume !== 'string' || resume.length === 0)) { - throw new Error('stdio startup requires --resume=') + throw new Error('TUI startup requires --resume=') } const sessionId = SessionId(resume ?? `main-session-${randomUUID()}`) process.env.DSH_SDK_SESSION_ID = sessionId {{/if}} const ctx = await startSDK(new URL('./cordis.yml', import.meta.url)) -{{#if isStdio}} +{{#if isTui}} try { if (resume === undefined) { await ctx.agents.create({ @@ -37,7 +37,7 @@ export async function main(boot: SdkBootContext) { try { await ctx.fiber.dispose() } catch (disposeError) { - throw new AggregateError([error, disposeError], 'stdio startup and cleanup failed') + throw new AggregateError([error, disposeError], 'TUI startup and cleanup failed') } throw error } diff --git a/packages/sdk/helper/src/templates/project-template.ts b/packages/sdk/helper/src/templates/project-template.ts index b214126b6e..afcf820ec2 100644 --- a/packages/sdk/helper/src/templates/project-template.ts +++ b/packages/sdk/helper/src/templates/project-template.ts @@ -20,7 +20,7 @@ export interface ProjectTemplateContext { model: string modelLiteral: string isAcp: boolean - isStdio: boolean + isTui: boolean isEmbed: boolean packageManager: PackageManagerName installArgs: string @@ -60,7 +60,7 @@ export function createProjectTemplateContext( model: profile.runtime.model, modelLiteral: JSON.stringify(profile.runtime.model), isAcp: runInterface === 'acp', - isStdio: runInterface === 'stdio', + isTui: runInterface === 'tui', isEmbed: runInterface === 'embed', packageManager: profile.packageManager.name, installArgs: profile.packageManager.installCommand().join(' '), @@ -105,7 +105,7 @@ export function createAppProjectArtifacts( /** Build package scripts owned by the selected app feature option. */ export function createAppPackageScripts(context: ProjectTemplateContext): Readonly> { - const modelArg = context.isStdio ? ` -- --model=${JSON.stringify(context.model)}` : '' + const modelArg = context.isTui ? ` -- --model=${JSON.stringify(context.model)}` : '' return { dev: `dsh-sdk dev index.ts${modelArg}`, start: `dsh-sdk start index.js${modelArg}`, diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/sdk/helper/tests/documents.spec.ts index 7181820725..1e4b944f00 100644 --- a/packages/sdk/helper/tests/documents.spec.ts +++ b/packages/sdk/helper/tests/documents.spec.ts @@ -243,7 +243,7 @@ overrides: expect(() => loadHelperTemplate('../bad.tpl')).toThrow('must not contain a directory') expect(createBaselineProjectArtifacts({ name: 'demo', description: 'demo', releaseVersion: '0.0.1', model: 'model', modelLiteral: '"model"', packageManager: 'yarn', - isAcp: false, isStdio: false, isEmbed: true, + isAcp: false, isTui: false, isEmbed: true, installArgs: 'install', buildArgs: 'build', }).map(document => document.relativePath)).toContain('.yarnrc.yml') expect(() => new LocalPluginBlueprint('---', 'plugin')).toThrow('invalid local plugin name') diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts index 91199d316b..4df8c5d3f2 100644 --- a/packages/sdk/helper/tests/project.spec.ts +++ b/packages/sdk/helper/tests/project.spec.ts @@ -51,7 +51,7 @@ function selection(id: string, options: readonly string[], secrets?: Record { expect(acp.readEnvironment('.env', 'KEY')).toBe('value') expect(() => acp.readEnvironment('.env.example', 'KEY')).not.toThrow() expect(acp.document('tsconfig.json')).toBeInstanceOf(TextProjectFile) - const stdio = await make('dsh-open-stdio', {}, `- id: provider + const tui = await make('dsh-open-tui', {}, `- id: provider name: '@deepseek-ai/dsh-llm-deepseek' config: { models: [provider-model] } -- id: stdio - name: '@deepseek-ai/dsh-stdio' +- id: tui + name: '@deepseek-ai/dsh-tui' `, { 'yarn.lock': '' }) - expect(stdio.profile.runInterface).toBe('stdio') - expect(stdio.profile.runtime.model).toBe('provider-model') - expect(stdio.profile.packageManager.name).toBe('yarn') - expect(stdio.profile.name).toBe(stdio.root.split('/').at(-1)) + expect(tui.profile.runInterface).toBe('tui') + expect(tui.profile.runtime.model).toBe('provider-model') + expect(tui.profile.packageManager.name).toBe('yarn') + expect(tui.profile.name).toBe(tui.root.split('/').at(-1)) const pnpm = await make('dsh-open-pnpm', { name: 'pnpm' }, '[]\n', { 'pnpm-lock.yaml': '' }) expect(pnpm.profile.packageManager.name).toBe('pnpm') const defaults = await make('dsh-open-default', { name: 'default', packageManager: 'npm@10.0.0' }, '[]\n') @@ -134,8 +134,8 @@ describe('SdkProject and ProjectEditSession', () => { expect(() => SdkProject.create(defaults.root, { ...request(), features: [] })).toThrow('requires one app') await expect(make('dsh-open-invalid-manager', { name: 'bad', packageManager: 'bad' }, '[]\n')) .rejects.toThrow('invalid packageManager field') - const providerFallback = await make('dsh-open-provider-fallback', { name: 'fallback' }, `- id: stdio - name: '@deepseek-ai/dsh-stdio' + const providerFallback = await make('dsh-open-provider-fallback', { name: 'fallback' }, `- id: tui + name: '@deepseek-ai/dsh-tui' config: { model: '' } - id: provider name: '@deepseek-ai/dsh-llm-deepseek' @@ -172,7 +172,7 @@ describe('SdkProject and ProjectEditSession', () => { expect(index).toContain('process.env.DSH_SDK_SESSION_ID = sessionId') expect(index).toContain('resumeSessionId: sessionId') expect(index).toContain('await ctx.fiber.dispose()') - expect(index).toContain("new AggregateError([error, disposeError], 'stdio startup and cleanup failed')") + expect(index).toContain("new AggregateError([error, disposeError], 'TUI startup and cleanup failed')") expect(project.packageManifest().scripts).toEqual({ dev: 'dsh-sdk dev index.ts -- --model="deepseek-v4-flash"', build: 'dsh-sdk build', @@ -181,12 +181,12 @@ describe('SdkProject and ProjectEditSession', () => { config: 'dsh-sdk config', }) expect(await readFile(join(project.root, '.env.example'), 'utf8')).toContain('EXA_API_KEY=') - expect(project.cordis.entry('stdio')?.config?.sessionId).toMatchObject({ + expect(project.cordis.entry('tui')?.config?.sessionId).toMatchObject({ source: 'process.env.DSH_SDK_SESSION_ID', }) expect(await readFile(join(project.root, 'cordis.yml'), 'utf8')) .toContain('sessionId: !!js process.env.DSH_SDK_SESSION_ID') - expect(project.cordis.entry('stdio')?.config).not.toHaveProperty('model') + expect(project.cordis.entry('tui')?.config).not.toHaveProperty('model') expect(project.cordis.entry('agent-loop')?.config).toEqual({ agents: [] }) expect(project.cordis.entry('system-prompt')?.config?.persona).toContain('{{cwd}}') expect(project.packageManifest().dependencies?.['@cordisjs/plugin-timer']).toBe('^1.1.2') @@ -211,13 +211,13 @@ describe('SdkProject and ProjectEditSession', () => { expect(app.selection).toEqual(selection('app', ['embed'])) expect(committed.cordis.entry('agent-loop')?.config).toEqual({ agents: [] }) expect(committed.cordis.entry('acp')).toBeUndefined() - expect(committed.cordis.entry('stdio')).toBeUndefined() + expect(committed.cordis.entry('tui')).toBeUndefined() }) it('emits the sandbox workspace-write example as inactive Cordis config', async () => { const root = await mkdtemp(join(tmpdir(), 'dsh-sandbox-bash-')) temporary.push(root) - const creation = request([], [], 'stdio', 'sandbox') + const creation = request([], [], 'tui', 'sandbox') const project = SdkProject.create(root, creation) const registry = createBuiltinRegistry(project.profile) const edit = project.edit(registry) @@ -307,7 +307,7 @@ describe('SdkProject and ProjectEditSession', () => { const modifiedRegistry = createBuiltinRegistry(modified.profile) expect(() => { modified.edit(modifiedRegistry).configureFeature( modifiedRegistry.get(featureId('app')), - selection('app', ['stdio']), + selection('app', ['tui']), ) }).toThrow('feature-owned file was modified: README.md') const manifest = PackageJsonFile.parse(await readFile(join(embed.root, 'package.json'), 'utf8')) @@ -350,7 +350,7 @@ describe('SdkProject and ProjectEditSession', () => { const edit = project.edit(registry) edit.setCustomPluginDisabled('sample', true) expect(edit.cordisConfigEntries().find(entry => entry.id === 'sample')?.disabled).toBe(true) - expect(() => { edit.setCustomPluginDisabled('stdio', true) }).toThrow('builtin feature') + expect(() => { edit.setCustomPluginDisabled('tui', true) }).toThrow('builtin feature') const next = (await edit.commit()).project const enable = next.edit(createBuiltinRegistry(next.profile)) enable.setCustomPluginDisabled('sample', false) @@ -445,8 +445,8 @@ describe('SdkProject and ProjectEditSession', () => { } const internals = edit as unknown as Internals const collidingEntry: ProjectResource = { - kind: 'cordis-config-entry', key: resourceKey('cordis-config-entry:stdio'), - entry: { id: 'stdio', name: 'other-package' }, ownedConfigKeys: [], + kind: 'cordis-config-entry', key: resourceKey('cordis-config-entry:tui'), + entry: { id: 'tui', name: 'other-package' }, ownedConfigKeys: [], } expect(() => { internals.applyResource(collidingEntry, undefined) }).toThrow('is owned by') const existingFile: ProjectResource = { @@ -798,7 +798,7 @@ describe('extension points', () => { }) expect(exclusive.defaultOptions(profile)).toEqual(['one']) expect(exclusive.isApplicable(profile)).toBe(true) - expect(exclusive.isApplicable({ ...profile, runInterface: 'stdio' })).toBe(false) + expect(exclusive.isApplicable({ ...profile, runInterface: 'tui' })).toBe(false) expect(exclusive.requirements(selection('defined', ['one']))).toEqual([ { id: 'base' }, { id: 'option', options: ['required'] }, ]) @@ -812,7 +812,7 @@ describe('extension points', () => { expect(entry?.validateConfig?.({ nested: { value: 2 }, list: ['a', 'b'], nullable: null })).toEqual([]) expect(entry?.validateConfig?.({ nested: [], list: 'bad' })).toHaveLength(3) expect(() => exclusive.normalizeSelection(selection('other', ['one']), profile)).toThrow('does not belong') - expect(() => exclusive.normalizeSelection(selection('defined', ['one']), { ...profile, runInterface: 'stdio' })) + expect(() => exclusive.normalizeSelection(selection('defined', ['one']), { ...profile, runInterface: 'tui' })) .toThrow('not available') expect(() => exclusive.normalizeSelection(selection('defined', ['missing']), profile)).toThrow('unknown') expect(() => exclusive.normalizeSelection(selection('defined', ['one', 'two']), profile)).toThrow('exactly one') @@ -820,7 +820,7 @@ describe('extension points', () => { id: 'fixed', summary: 'Fixed', mode: 'single', options: [option], }])).toHaveLength(2) expect(() => new FeatureRegistry([], profile).get(featureId('missing'))).toThrow('unknown feature') - expect(new FeatureRegistry([exclusive], profile).ownerOfPackage('one-package', { ...profile, runInterface: 'stdio' })) + expect(new FeatureRegistry([exclusive], profile).ownerOfPackage('one-package', { ...profile, runInterface: 'tui' })) .toBeUndefined() class Unsupported extends FixedFeature { override readonly id = featureId('unsupported') @@ -898,10 +898,10 @@ describe('extension points', () => { resource.kind === 'cordis-config-entry' && resource.entry.id === 'acp') expect(acpEntry?.entry.id).toBe('acp') expect(acpEntry?.validateConfig?.({ model: '' })).toHaveLength(1) - const stdioEntry = builtins.get(featureId('app')).contribution(selection('app', ['stdio']), profile).resources + const tuiEntry = builtins.get(featureId('app')).contribution(selection('app', ['tui']), profile).resources .find((resource): resource is CordisConfigEntryResource => - resource.kind === 'cordis-config-entry' && resource.entry.id === 'stdio') - expect(stdioEntry?.validateConfig?.({ welcome: 'ready', sessionId: 1 })).toEqual([ + resource.kind === 'cordis-config-entry' && resource.entry.id === 'tui') + expect(tuiEntry?.validateConfig?.({ welcome: 'ready', sessionId: 1 })).toEqual([ 'sessionId must be a non-empty string', ]) const embedOption = app.options.find(option => option.id === 'embed') @@ -911,7 +911,7 @@ describe('extension points', () => { ]) expect(embedOption?.matchesConfigEntries([ { id: 'agent-loop', name: '@deepseek-ai/dsh-agent-loop' }, - { id: 'stdio', name: '@deepseek-ai/dsh-stdio' }, + { id: 'tui', name: '@deepseek-ai/dsh-tui' }, ], profile)).toBe(false) const spineAgentLoop = builtins.get(featureId('spine')).contribution(selection('spine', ['default']), profile).resources .find((resource): resource is CordisConfigEntryResource => diff --git a/packages/sdk/helper/tests/questions.spec.ts b/packages/sdk/helper/tests/questions.spec.ts index 5eb205075f..dc9e734ac5 100644 --- a/packages/sdk/helper/tests/questions.spec.ts +++ b/packages/sdk/helper/tests/questions.spec.ts @@ -376,7 +376,7 @@ describe('feature configurator', () => { name: 'demo', description: 'demo', runtime: { model: 'deepseek-v4-flash' }, - runInterface: 'stdio', + runInterface: 'tui', packageManager: new NpmPackageManager('10.0.0'), releaseVersion: '0.0.1', } diff --git a/packages/sdk/scripts/src/config/config-workflow.ts b/packages/sdk/scripts/src/config/config-workflow.ts index 016d9d09b8..408a9b9639 100644 --- a/packages/sdk/scripts/src/config/config-workflow.ts +++ b/packages/sdk/scripts/src/config/config-workflow.ts @@ -56,7 +56,7 @@ function targetRunInterface( desired: ReadonlyMap>, ): RunInterface { const selected = desired.get('feature:app')?.choices[0] - return selected === 'acp' || selected === 'stdio' || selected === 'embed' ? selected : current + return selected === 'acp' || selected === 'tui' || selected === 'embed' ? selected : current } /** Reconcile one tree selection into domain commands, then review and commit once. */ diff --git a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap b/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap index 31e21dd8a9..14f74b0f85 100644 --- a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap +++ b/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap @@ -90,8 +90,8 @@ Change file: package.json }, { "default": true, - "label": "Terminal REPL", - "value": "stdio", + "label": "Terminal TUI", + "value": "tui", }, { "default": false, diff --git a/packages/sdk/scripts/tests/config.snapshot.ts b/packages/sdk/scripts/tests/config.snapshot.ts index 80a79a5f20..e6047c8562 100644 --- a/packages/sdk/scripts/tests/config.snapshot.ts +++ b/packages/sdk/scripts/tests/config.snapshot.ts @@ -94,7 +94,7 @@ async function baseProject(): Promise { features: [ { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'key' } }, { id: featureId('bash'), options: ['local'] }, - { id: featureId('app'), options: ['stdio'] }, + { id: featureId('app'), options: ['tui'] }, { id: featureId('persistence'), options: ['jsonl'] }, ], localPlugins: [], diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts index 8b887d74db..a6ec4f4a4f 100644 --- a/packages/sdk/scripts/tests/scripts.spec.ts +++ b/packages/sdk/scripts/tests/scripts.spec.ts @@ -85,7 +85,7 @@ function commandContext(cwd: string): DshSdkCommandContext & { readStdout: () => function creation( extra: ProjectCreationRequest['features'] = [], localPlugins: readonly LocalPluginBlueprint[] = [], - app: 'acp' | 'stdio' | 'embed' = 'embed', + app: 'acp' | 'tui' | 'embed' = 'embed', ): ProjectCreationRequest { return { name: 'config-agent', @@ -107,7 +107,7 @@ function creation( async function committedProject( extra: ProjectCreationRequest['features'] = [], localPlugins: readonly LocalPluginBlueprint[] = [], - app: 'acp' | 'stdio' | 'embed' = 'embed', + app: 'acp' | 'tui' | 'embed' = 'embed', ): Promise { const root = await mkdtemp(join(tmpdir(), 'dsh-config-workflow-')) temporary.push(root) @@ -525,7 +525,7 @@ describe('ConfigWorkflow', () => { const workflow = new ConfigWorkflow(new QueuePort([ [ { value: 'feature:provider', choices: ['custom'] }, - { value: 'feature:app', choices: ['stdio'] }, + { value: 'feature:app', choices: ['tui'] }, { value: 'feature:persistence', choices: ['jsonl'] }, ], 'https://provider.example/v1', @@ -536,7 +536,7 @@ describe('ConfigWorkflow', () => { const provider = result.commit?.project.cordis.entry('llm-pi-ai') expect(provider?.config?.apiKey).toBeDefined() expect(provider?.config?.baseURL).toBe('https://provider.example/v1') - expect(result.commit?.project.cordis.entry('stdio')).toBeDefined() + expect(result.commit?.project.cordis.entry('tui')).toBeDefined() expect(result.commit?.project.cordis.entry('agent-loop')).toBeDefined() expect(result.commit?.project.cordis.entry('agent-core')).toBeUndefined() }) diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md index d6130d414a..e31650879c 100644 --- a/packages/session-persistence/session-persistence-jsonl/README.md +++ b/packages/session-persistence/session-persistence-jsonl/README.md @@ -1,31 +1,39 @@ # @deepseek-ai/dsh-session-persistence-jsonl -The JSONL durable session-persistence backend — a concrete `SessionPersistence` (the `dsh-session-persistence` seam). One append-only `.jsonl` event log per session. +The JSONL durable session-persistence backend — a concrete `SessionPersistence` (the `dsh-session-persistence` seam). Each session has one append-only logical JSONL log, stored as `.jsonl.zstd` by default or raw `.jsonl` when compression is disabled. ## On-disk layout ``` / cwd-/ # per-project bucket (or _no-cwd/ when no cwd) - .jsonl # header line + one SessionEvent per line (verbatim) + .jsonl.zstd # default: checksummed header frame + append frames + .jsonl # only with compression: 'none' ``` -- The first `.jsonl` line is the immutable `SessionHeader` tagged `{ type: 'session', version, id, cwd?, createdAt, parentSession?, seedLength?, delegationDepth }`. `delegationDepth` is required on disk and is `0` for a top-level session; a missing or invalid value rejects the log. Every subsequent line is one `SessionEvent` JSON, **verbatim including `assistant/chunk`** so `seq` stays contiguous (`events[i].seq === i`). -- Session ids are unvalidated branded strings, so they are percent-encoded to a single safe path segment before use (no traversal, no collision). +- The first logical line is the immutable `SessionHeader` tagged `{ type: 'session', version, id, cwd?, createdAt, parentSession?, seedLength?, delegationDepth }`. `delegationDepth` is required on disk and is `0` for a top-level session; a missing or invalid value rejects the log. Every subsequent line is one `SessionEvent` JSON, **verbatim including `assistant/chunk`** so `seq` stays contiguous (`events[i].seq === i`). +- Session ids are unvalidated branded strings, so they are injectively escaped to a single safe path segment before use (no traversal, no collision). ## Config | Key | Type | Notes | |---|---|---| | `root` | `string` (required) | Root directory for all session files. **No default** — a `process.cwd()` default would scatter files as the process's cwd changes (bash calls, subprocesses). | +| `compression` | `'zstd' \| 'none'` | Defaults to `'zstd'`; `'none'` retains newline-delimited UTF-8 text. | `locate(meta)` returns `{ kind: 'jsonl', path }` using the resolved absolute root and the same cwd-bucket/id encoding as materialization. It performs no filesystem I/O: the target can be returned before the file exists, and an existing file contains only the last flushed prefix. +## Physical encoding + +The default artifact is a standard concatenation of independent [Zstandard frames](../../../.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md): one checksummed frame containing only the header line, followed by one checksummed frame per durable append batch. The backend uses Node's built-in Zstandard API with its default compression level and exposes no level knob. Listing reads and validates only the header frame. `compression: 'none'` keeps the same logical lines in the original raw representation. + +A root belongs to one encoding. Startup discovery and targeted lookup reject the opposite suffix with an error naming the incompatible artifact and instructing the caller to select the matching mode or a separate root. There is no migration, mixed-root fallback, or dual write. + ## Durability and crash semantics - **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s a temporary file, publishes it without overwrite via a hard link, then `fsync`s the directory when the host supports it. A created-but-never-appended session leaves nothing on disk and is absent from `list`. -- **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`. -- **Crash recovery — preserve valid tail work.** `load` keeps the contiguous valid prefix of an interrupted final turn. It truncates from the first unparsable or sequence-gapped uncommitted record, then appends the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md); the same defect at or before the last committed `turn/end` rejects. +- **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent raw batches append lines; compressed batches append one frame. Both paths `fsync`, and a caught write or sync failure rolls the file back to its prior byte length. +- **Crash recovery — preserve valid tail work.** `load` validates every complete compressed frame and scans their decompressed JSONL. If the last frame is structurally incomplete, the reader keeps its complete decoded records, truncates from that frame's start, and re-encodes those records with the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md). Raw mode truncates from its first incomplete line. A checksum/decompression failure in a complete frame, or a defect at or before the last committed `turn/end`, is corruption and rejects. - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type. ## Write path @@ -50,7 +58,8 @@ JSONL storage does not mutate live request prefixes. A resumed loop can reuse pr ## Known Limitations and Deferred Work -- **Only the current `SESSION_FORMAT_VERSION` (v0) loads** — the on-disk format is pre-release/unstable: a breaking format change is absorbed at v0 and non-current logs are rejected; there is no migration. +- **Only the configured encoding and current `SESSION_FORMAT_VERSION` (v0) load** — changing compression requires a separate/fresh root or selecting the legacy raw mode; the pre-release format has no migration. +- **Compressed files are not directly line-readable** — use the backend to load them, or select `compression: 'none'` before writing a fresh root when text fixtures or external line readers are required. - **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface). - **Single-process assumption** — per-session serialization and the write cursor live in this process; two processes appending to the same `root` are not coordinated. - **Initial materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; a filesystem that cannot create hard links cannot host this backend. diff --git a/packages/session-persistence/session-persistence-jsonl/src/format.ts b/packages/session-persistence/session-persistence-jsonl/src/format.ts index 3349eac12e..4c346390a9 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/format.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/format.ts @@ -12,8 +12,20 @@ import { createHash } from 'node:crypto' import { join } from 'node:path' import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session' +/** Physical encoding selected for JSONL session artifacts. */ +export type JsonlCompression = 'zstd' | 'none' + /** - * The first line of a session's `.jsonl` file: the immutable + * Return the artifact suffix for one physical encoding. + * @param compression - configured JSONL artifact encoding. + * @returns `.jsonl.zstd` for Zstandard or `.jsonl` for plaintext. + */ +export function logSuffix(compression: JsonlCompression): '.jsonl.zstd' | '.jsonl' { + return compression === 'zstd' ? '.jsonl.zstd' : '.jsonl' +} + +/** + * The first JSONL record of a session artifact: the immutable * {@link SessionHeader} tagged as a `session` record so a reader can tell it * apart from an event line. */ @@ -126,10 +138,16 @@ export function sessionDir(root: string, cwd: string | undefined): string { * @param root - the backend's session root directory. * @param cwd - the session's project directory (picks the per-cwd bucket; `undefined` → `_no-cwd`). * @param id - the session id, path-encoded via {@link encodeSegment} before filesystem use. - * @returns the session's `.jsonl` log file path. + * @param compression - physical artifact encoding and filename suffix. + * @returns the session's configured JSONL artifact path. */ -export function logPath(root: string, cwd: string | undefined, id: SessionId): string { - return join(sessionDir(root, cwd), `${encodeSegment(id)}.jsonl`) +export function logPath( + root: string, + cwd: string | undefined, + id: SessionId, + compression: JsonlCompression, +): string { + return join(sessionDir(root, cwd), `${encodeSegment(id)}${logSuffix(compression)}`) } /** diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index 4e52cb0b9e..7aaf091038 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -17,8 +17,20 @@ import { } from '@deepseek-ai/dsh-session-persistence' import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session' import { - encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine, + encodeSegment, eventLine, logPath, logSuffix, parseHeaderMeta, scanLog, sessionDir, toHeaderLine, + type JsonlCompression, } from './format.ts' +import { compressZstdFrame, decompressZstdFrame, scanZstdFrames } from './zstd.ts' + +export type { JsonlCompression } from './format.ts' + +const DEFAULT_COMPRESSION: JsonlCompression = 'zstd' + +/** Loader schema for the JSONL artifact's physical encoding. */ +export const JsonlCompressionSchema: z = z.union([ + z.const('zstd'), + z.const('none'), +]).default(DEFAULT_COMPRESSION) /** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */ export interface Config { @@ -28,6 +40,14 @@ export interface Config { * (bash calls, subprocesses). Sessions group under per-cwd subdirectories. */ root: string + /** Physical encoding; defaults to checksummed Zstandard frames. */ + compression?: JsonlCompression +} + +/** Opaque coordinator token for replacing bytes recovered from a torn frame. */ +interface JsonlTornMarker { + truncateTo: number + recoveredEvents: SessionEvent[] } /** Whether a filesystem error means absence; every non-ENOENT failure must surface. */ @@ -38,13 +58,15 @@ function isENOENT(error: unknown): boolean { /** * The JSONL persistence backend. Load as a plugin; it registers as * `ctx.sessionPersistence` and (via the coordinator) installs the write-path - * listeners. Its torn-tail marker is the byte offset to truncate the log to. + * listeners. Its torn-tail marker carries the byte offset and any events + * recovered from an incomplete final Zstandard frame. */ -export class SessionPersistenceJsonl extends SessionPersistence implements PersistenceBackend { +export class SessionPersistenceJsonl extends SessionPersistence implements PersistenceBackend { static inject = ['sessions'] static Config: z = z.object({ root: z.string().required(), + compression: JsonlCompressionSchema, }) /** @@ -55,7 +77,9 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi override readonly name = 'session-persistence-jsonl' private root: string - private coordinator: PersistenceCoordinator + private compression: JsonlCompression + private coordinator: PersistenceCoordinator + private rootEncodingCheck: Promise | undefined /** Runtime host platform used to decide whether directory sync is supported. */ readonly internals: { platform: NodeJS.Platform } = { platform: process.platform } @@ -64,7 +88,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi super(ctx) // Resolve once so later process.cwd() changes cannot split one backend across roots. this.root = resolve(config.root) - this.coordinator = new PersistenceCoordinator(this.ctx, this) + this.compression = config.compression ?? DEFAULT_COMPRESSION + this.coordinator = new PersistenceCoordinator(this.ctx, this) } // Each backend keeps the typed service surface beside its storage hooks; @@ -74,7 +99,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi /** Resolve the absolute target path without touching the filesystem. */ locate(meta: SessionHeader): SessionLocation { - return { kind: 'jsonl', path: logPath(this.root, meta.cwd, meta.id) } + return { kind: 'jsonl', path: logPath(this.root, meta.cwd, meta.id, this.compression) } } create(meta: SessionHeader): Promise { @@ -96,7 +121,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi // --- PersistenceBackend hooks (the file-bytes storage primitives) --- /** Read a stored prefix by id across all cwd buckets when cwd is unknown. */ - async loadStored(id: SessionId): Promise | undefined> { + async loadStored(id: SessionId): Promise | undefined> { + await this.ensureRootEncoding() const file = await this.findLog(id) if (file === undefined) return undefined return this.readPrefix(file.path) @@ -106,28 +132,85 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi * Read a stored prefix within one cwd for HMR adoption. `undefined` names the * no-cwd bucket rather than an unknown cwd, so this never scans other buckets. */ - async loadLive(id: SessionId, cwd: string | undefined): Promise | undefined> { - const path = logPath(this.root, cwd, id) - if (!await this.exists(path)) return undefined + async loadLive(id: SessionId, cwd: string | undefined): Promise | undefined> { + await this.ensureRootEncoding() + const path = logPath(this.root, cwd, id, this.compression) + if (!await this.exists(path)) { + await this.rejectOppositeArtifact(cwd, id) + return undefined + } return this.readPrefix(path) } /** - * Read a stored prefix and convert torn-tail state to the byte offset the - * coordinator can round-trip without knowing the file format. + * Read a stored prefix and convert torn-tail state to the opaque marker the + * coordinator can round-trip without knowing the physical encoding. */ - private async readPrefix(path: string): Promise> { + private async readPrefix(path: string): Promise> { const buffer = await readFile(path) + if (this.compression === 'zstd') return this.readZstdPrefix(buffer) const { meta, events, committedBytes } = scanLog(buffer) return { meta, events, - ...committedBytes < buffer.byteLength ? { tornMarker: committedBytes } : {}, + ...committedBytes < buffer.byteLength + ? { tornMarker: { truncateTo: committedBytes, recoveredEvents: [] } } + : {}, + } + } + + /** Decode complete frames and retain complete JSONL records from a torn final frame. */ + private async readZstdPrefix(buffer: Buffer): Promise> { + const { frames, tornStart } = scanZstdFrames(buffer) + if (frames.length === 0) throw new Error('empty or header-less Zstandard session log') + + const plaintextFrames: Buffer[] = [] + for (const frame of frames) { + try { + plaintextFrames.push(await decompressZstdFrame(buffer.subarray(frame.start, frame.end))) + } catch (error) { + throw new Error(`corrupt Zstandard session log: frame at byte ${frame.start} failed validation`, { cause: error }) + } + } + + const headerFrame = plaintextFrames[0] + if (headerFrame === undefined || headerFrame.length === 0 || headerFrame.indexOf(0x0A) !== headerFrame.length - 1) { + throw new Error('corrupt Zstandard session log: first frame is not exactly one header line') + } + const completePlaintext = Buffer.concat(plaintextFrames) + const completePrefix = scanLog(completePlaintext) + if (completePrefix.committedBytes !== completePlaintext.length) { + throw new Error('corrupt Zstandard session log: complete frame contains a torn JSONL record') + } + if (tornStart === undefined) { + return { meta: completePrefix.meta, events: completePrefix.events } + } + + let recoveredPlaintext: Buffer = Buffer.alloc(0) + try { + recoveredPlaintext = await decompressZstdFrame(buffer.subarray(tornStart)) + } catch { + // A structurally incomplete final frame may end before Node's decoder can + // emit any plaintext; the complete prior frames remain recoverable. + } + const recoveredPrefix = scanLog(Buffer.concat([completePlaintext, recoveredPlaintext])) + /* v8 ignore next 3 -- appending plaintext cannot shorten the already-scanned complete prefix */ + if (recoveredPrefix.events.length < completePrefix.events.length) { + throw new Error('corrupt Zstandard session log: recovered prefix does not extend complete frames') + } + return { + meta: recoveredPrefix.meta, + events: recoveredPrefix.events, + tornMarker: { + truncateTo: tornStart, + recoveredEvents: recoveredPrefix.events.slice(completePrefix.events.length), + }, } } /** Durably append a batch, lazily materializing the file when not yet present. */ async appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise { + await this.ensureRootEncoding() if (isMaterialized) { await this.appendLines(meta, events) } else { @@ -136,22 +219,30 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } /** - * Make a crash repair durable: truncate the torn tail to `tornMarker` bytes (if - * any), then append the synthetic `closers` (if any). Two fsync'd steps — the - * seam does not require this to be atomic. + * Make a crash repair durable: truncate a torn tail, restore complete events + * decoded from it, then append synthetic closers. Two fsync'd steps — the seam + * does not require this to be atomic. */ - async commitRepair(meta: SessionHeader, tornMarker: number | undefined, closers: readonly SessionEvent[]): Promise { - if (tornMarker !== undefined) await this.repair(meta, tornMarker) - if (closers.length > 0) await this.appendLines(meta, closers) + async commitRepair( + meta: SessionHeader, + tornMarker: JsonlTornMarker | undefined, + closers: readonly SessionEvent[], + ): Promise { + if (tornMarker !== undefined) await this.repair(meta, tornMarker.truncateTo) + const repairedEvents = [...(tornMarker?.recoveredEvents ?? []), ...closers] + if (repairedEvents.length > 0) await this.appendLines(meta, repairedEvents) } /** List all stored sessions' metadata (header line only — no full-log parse). */ async list(): Promise { + await this.ensureRootEncoding() const metas: SessionHeader[] = [] for (const dir of await this.listCwdDirs()) { - for (const name of await this.listJsonl(dir)) { + for (const name of await this.listArtifacts(dir)) { // Read only headers so listing scales with session count, not log size. - const first = await this.readFirstLine(`${dir}/${name}`) + const first = this.compression === 'zstd' + ? await this.readFirstZstdLine(`${dir}/${name}`) + : await this.readFirstLine(`${dir}/${name}`) if (first === undefined) continue // empty/half-written file const meta = parseHeaderMeta(first) if (meta === undefined) continue // not a session header @@ -170,15 +261,14 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await this.syncDir(dirname(this.root)) await mkdir(dir, { recursive: true, mode: 0o700 }) await this.syncDir(this.root) - const finalPath = logPath(this.root, meta.cwd, meta.id) + const finalPath = logPath(this.root, meta.cwd, meta.id, this.compression) // Materialization is the first write; an existing log is an id collision. /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */ if (await this.exists(finalPath)) { throw new Error(`refusing to materialize "${meta.id}": a log already exists on disk (load/resume it instead)`) } - const header = JSON.stringify(toHeaderLine(meta)) - const body = events.map(eventLine).join('\n') - const content = header + '\n' + body + '\n' + await this.rejectOppositeArtifact(meta.cwd, meta.id) + const content = await this.encodeMaterialization(meta, events) const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp` const handle = await open(tmp, 'wx', 0o600) @@ -211,6 +301,22 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } + /** Encode the header and first batch without combining their frame boundaries. */ + private async encodeMaterialization(meta: SessionHeader, events: readonly SessionEvent[]): Promise { + const header = JSON.stringify(toHeaderLine(meta)) + '\n' + const body = events.map(eventLine).join('\n') + '\n' + if (this.compression === 'none') return header + body + const headerFrame = await compressZstdFrame(header) + const eventFrame = await compressZstdFrame(body) + return Buffer.concat([headerFrame, eventFrame]) + } + + /** Encode one durable append batch in the configured physical representation. */ + private async encodeEventBatch(events: readonly SessionEvent[]): Promise { + const body = events.map(eventLine).join('\n') + '\n' + return this.compression === 'zstd' ? compressZstdFrame(body) : body + } + /** fsync a directory when the host exposes that durability primitive. */ private async syncDir(dir: string): Promise { const handle = await open(dir, 'r') @@ -234,12 +340,13 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi * batch; leaving partial bytes would create duplicate sequence numbers. */ private async appendLines(meta: SessionHeader, events: readonly SessionEvent[]): Promise { - const path = logPath(this.root, meta.cwd, meta.id) + const content = await this.encodeEventBatch(events) + const path = logPath(this.root, meta.cwd, meta.id, this.compression) const handle = await open(path, 'a') try { const { size: before } = await handle.stat() try { - await handle.writeFile(events.map(eventLine).join('\n') + '\n') + await handle.writeFile(content) await handle.sync() } catch (error) { // Roll back whatever bytes landed so a retry starts from a clean EOF. @@ -254,7 +361,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi /** Truncate the log file to `offset` bytes and fsync (discard the crash tail). */ private async repair(meta: SessionHeader, offset: number): Promise { - const path = logPath(this.root, meta.cwd, meta.id) + const path = logPath(this.root, meta.cwd, meta.id, this.compression) await truncate(path, offset) const handle = await open(path, 'r+') try { @@ -292,17 +399,47 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } + /** Read and validate only the independently compressed header frame. */ + private async readFirstZstdLine(path: string): Promise { + const handle = await open(path, 'r') + try { + let content = Buffer.alloc(0) + const chunk = Buffer.alloc(8192) + for (;;) { + const { bytesRead } = await handle.read(chunk, 0, chunk.length, null) + if (bytesRead === 0) return undefined + content = Buffer.concat([content, chunk.subarray(0, bytesRead)]) + const first = scanZstdFrames(content, 1).frames[0] + if (first === undefined) continue + let plaintext: Buffer + try { + plaintext = await decompressZstdFrame(content.subarray(first.start, first.end)) + } catch (error) { + throw new Error('corrupt Zstandard session log: header frame failed validation', { cause: error }) + } + if (plaintext.length === 0 || plaintext.indexOf(0x0A) !== plaintext.length - 1) { + throw new Error('corrupt Zstandard session log: first frame is not exactly one header line') + } + return plaintext.subarray(0, -1).toString('utf8') + } + } finally { + await handle.close() + } + } + /** * Find a session by id across cwd buckets for resume. Cwd-scoped HMR adoption * bypasses this scan so a no-cwd session cannot claim another bucket. */ private async findLog(id: SessionId): Promise<{ path: string; cwd: string | undefined } | undefined> { - const target = encodeSegment(id) + '.jsonl' + const target = encodeSegment(id) + logSuffix(this.compression) for (const dir of await this.listCwdDirs()) { const path = `${dir}/${target}` + const opposite = `${dir}/${encodeSegment(id)}${logSuffix(this.oppositeCompression())}` + if (await this.exists(opposite)) throw this.encodingMismatch(opposite) if (await this.exists(path)) { // Recover the cwd from the header so the caller has the session's bucket. - const { meta } = scanLog(await readFile(path)) + const { meta } = await this.readPrefix(path) return { path, cwd: meta.cwd } } } @@ -321,9 +458,45 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } - private async listJsonl(dir: string): Promise { + private async listArtifacts(dir: string): Promise { const entries = await readdir(dir) - return entries.filter(n => n.endsWith('.jsonl')) + const oppositeSuffix = logSuffix(this.oppositeCompression()) + const incompatible = entries.find(name => name.endsWith(oppositeSuffix)) + if (incompatible !== undefined) throw this.encodingMismatch(`${dir}/${incompatible}`) + const suffix = logSuffix(this.compression) + return entries.filter(name => name.endsWith(suffix)) + } + + /** Reject a root that already belongs to the other physical encoding. */ + private ensureRootEncoding(): Promise { + this.rootEncodingCheck ??= this.checkRootEncoding() + return this.rootEncodingCheck + } + + private async checkRootEncoding(): Promise { + const oppositeSuffix = logSuffix(this.oppositeCompression()) + for (const dir of await this.listCwdDirs()) { + const entries = await readdir(dir) + const incompatible = entries.find(name => name.endsWith(oppositeSuffix)) + if (incompatible !== undefined) throw this.encodingMismatch(`${dir}/${incompatible}`) + } + } + + private async rejectOppositeArtifact(cwd: string | undefined, id: SessionId): Promise { + const path = logPath(this.root, cwd, id, this.oppositeCompression()) + if (await this.exists(path)) throw this.encodingMismatch(path) + } + + private oppositeCompression(): JsonlCompression { + return this.compression === 'zstd' ? 'none' : 'zstd' + } + + private encodingMismatch(path: string): Error { + return new Error( + `session artifact ${JSON.stringify(path)} uses ${logSuffix(this.oppositeCompression())}, ` + + `but this backend is configured for compression ${JSON.stringify(this.compression)}; ` + + 'use a separate root or select the matching compression mode', + ) } private async exists(path: string): Promise { diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd.ts b/packages/session-persistence/session-persistence-jsonl/src/zstd.ts new file mode 100644 index 0000000000..bba2ef6344 --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/src/zstd.ts @@ -0,0 +1,116 @@ +/** + * Zstandard frame primitives for the JSONL persistence backend. The backend + * owns a concatenated-frame container so it can append and recover batches + * without exposing compression mechanics through the persistence seam. + * @module dsh-session-persistence-jsonl/zstd + */ + +import { constants, zstdCompress, zstdDecompress, type ZstdOptions } from 'node:zlib' +import { promisify } from 'node:util' + +const ZSTD_MAGIC = 0xFD2FB528 +const zstdCompressAsync = promisify(zstdCompress) +const zstdDecompressAsync = promisify(zstdDecompress) +const CHECKSUM_OPTIONS: ZstdOptions = { + params: { [constants.ZSTD_c_checksumFlag]: 1 }, +} + +/** Byte range occupied by one structurally complete Zstandard frame. */ +export interface ZstdFrameRange { + /** Inclusive frame start. */ + start: number + /** Exclusive frame end. */ + end: number +} + +/** Structural scan result for a concatenated Zstandard stream. */ +export interface ZstdFrameScan { + /** Complete frames in file order. */ + frames: ZstdFrameRange[] + /** Start of an incomplete final frame, when EOF interrupts one. */ + tornStart?: number +} + +/** + * Locate complete frames without decompressing their blocks. Invalid complete + * structure rejects; EOF inside the final frame returns its start for repair. + * @param buffer - complete bytes currently present in the session artifact. + * @param maxFrames - optional complete-frame limit for metadata-only readers. + * @returns complete frame ranges and an optional incomplete-final-frame start. + */ +export function scanZstdFrames(buffer: Buffer, maxFrames = Number.POSITIVE_INFINITY): ZstdFrameScan { + const frames: ZstdFrameRange[] = [] + let offset = 0 + + while (offset < buffer.length) { + const start = offset + if (buffer.length - offset < 4) return { frames, tornStart: start } + if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) { + throw new Error(`corrupt Zstandard session log: invalid frame magic at byte ${offset}`) + } + offset += 4 + + if (offset === buffer.length) return { frames, tornStart: start } + const descriptor = buffer.readUInt8(offset) + offset += 1 + if ((descriptor & 0x18) !== 0) { + throw new Error(`corrupt Zstandard session log: reserved frame-header bit at byte ${offset - 1}`) + } + + const contentSizeFlag = descriptor >>> 6 + const singleSegment = (descriptor & 0x20) !== 0 + const checksum = (descriptor & 0x04) !== 0 + const dictionaryFlag = descriptor & 0x03 + const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag + const contentSizeBytes = contentSizeFlag === 0 + ? (singleSegment ? 1 : 0) + : 1 << contentSizeFlag + const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes + if (buffer.length - offset < remainingHeaderBytes) return { frames, tornStart: start } + offset += remainingHeaderBytes + + for (;;) { + if (buffer.length - offset < 3) return { frames, tornStart: start } + const blockHeader = buffer.readUIntLE(offset, 3) + offset += 3 + const lastBlock = (blockHeader & 1) !== 0 + const blockType = (blockHeader >>> 1) & 0x03 + const blockSize = blockHeader >>> 3 + if (blockType === 0x03) { + throw new Error(`corrupt Zstandard session log: reserved block type at byte ${offset - 3}`) + } + const payloadBytes = blockType === 0x01 ? 1 : blockSize + if (buffer.length - offset < payloadBytes) return { frames, tornStart: start } + offset += payloadBytes + if (lastBlock) break + } + + if (checksum) { + if (buffer.length - offset < 4) return { frames, tornStart: start } + offset += 4 + } + frames.push({ start, end: offset }) + if (frames.length === maxFrames) return { frames } + } + + return { frames } +} + +/** + * Compress one independently decodable, checksummed Zstandard frame. + * @param input - JSONL bytes for a header or durable event batch. + * @returns the complete encoded frame. + */ +export async function compressZstdFrame(input: Buffer | string): Promise { + return zstdCompressAsync(input, CHECKSUM_OPTIONS) +} + +/** + * Decompress one complete frame or the available prefix of a torn final frame. + * Complete-frame checksums are validated by Node's decoder. + * @param input - bytes beginning at a Zstandard frame boundary. + * @returns plaintext produced from the available input. + */ +export async function decompressZstdFrame(input: Buffer): Promise { + return zstdDecompressAsync(input) +} diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts index 9a236c5397..90d6fe9e36 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts @@ -40,6 +40,10 @@ async function freshRoot(): Promise { return dir } +function rawLogPath(root: string, cwd: string | undefined, id: SessionId): string { + return logPath(root, cwd, id, 'none') +} + afterEach(async () => { vi.restoreAllMocks() for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) @@ -70,11 +74,11 @@ function appendClosedTurn(session: Session): void { } // Run the shared backend contract against the real JSONL backend. -runPersistenceContract('jsonl', async () => { +runPersistenceContract('jsonl-none', async () => { const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-')) const ctx = new Context() await ctx.plugin(SessionStore) - const fiber = await ctx.plugin(SessionPersistenceJsonl, { root: dir }) + const fiber = await ctx.plugin(SessionPersistenceJsonl, { root: dir, compression: 'none' }) return { persistence: ctx.sessionPersistence, dispose: async () => { @@ -86,18 +90,18 @@ runPersistenceContract('jsonl', async () => { // Two mounts share this temp root to exercise reload. `corruptTail` appends a partial, // newline-less fragment past the committed region so coordinator repair runs on real file bytes. -runCoordinatorContract('jsonl', async (): Promise => { +runCoordinatorContract('jsonl-none', async (): Promise => { const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-coord-')) return { mount: async (ctx) => { - const fiber = await ctx.plugin(SessionPersistenceJsonl, { root: dir }) + const fiber = await ctx.plugin(SessionPersistenceJsonl, { root: dir, compression: 'none' }) return fiber }, corruptTail: async (id, cwd) => { // A half-written record with no trailing newline: scanLog treats it as an // uncommitted crash fragment and reports committedBytes < byteLength, so // the coordinator sees a tornMarker to truncate. - await appendFile(logPath(dir, cwd, id), '{"type":"assistant/chunk","seq":8,"ti') + await appendFile(rawLogPath(dir, cwd, id), '{"type":"assistant/chunk","seq":8,"ti') }, cleanup: async () => { await rm(dir, { recursive: true, force: true }) }, } @@ -134,11 +138,14 @@ describe('SessionPersistenceJsonl: format helpers', () => { const absoluteRoot = await freshRoot() const ctx = new Context() await ctx.plugin(SessionStore) - const fiber = await ctx.plugin(SessionPersistenceJsonl, { root: relative(process.cwd(), absoluteRoot) }) + const fiber = await ctx.plugin(SessionPersistenceJsonl, { + root: relative(process.cwd(), absoluteRoot), + compression: 'none', + }) const m = meta('relative-location', '/work') expect(ctx.sessionPersistence.locate(m)).toEqual({ kind: 'jsonl', - path: logPath(resolve(absoluteRoot), '/work', m.id), + path: rawLogPath(resolve(absoluteRoot), '/work', m.id), }) await fiber.dispose() }) @@ -150,26 +157,26 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { root = await freshRoot() ctx = new Context() await ctx.plugin(SessionStore) - await ctx.plugin(SessionPersistenceJsonl, { root }) + await ctx.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) }) afterEach(async () => { await ctx.fiber.dispose() }) it('lazy materialization: create() writes no file until the first append', async () => { const m = meta('lazy', '/work') const location = ctx.sessionPersistence.locate(m) - expect(location).toEqual({ kind: 'jsonl', path: logPath(root, '/work', m.id) }) + expect(location).toEqual({ kind: 'jsonl', path: rawLogPath(root, '/work', m.id) }) expect(isAbsolute(location!.path)).toBe(true) await ctx.sessionPersistence.create(m) // locate() is a pure target-path calculation: neither it nor create() // materializes a file before the first append. const dir = sessionDir(root, '/work') - await expect(stat(logPath(root, '/work', m.id))).rejects.toThrow() + await expect(stat(rawLogPath(root, '/work', m.id))).rejects.toThrow() expect((await ctx.sessionPersistence.list()).map(h => h.id)).not.toContain(m.id) await ctx.sessionPersistence.append(m.id, oneTurnLog()) // now materialized - expect((await stat(logPath(root, '/work', m.id))).isFile()).toBe(true) + expect((await stat(rawLogPath(root, '/work', m.id))).isFile()).toBe(true) expect((await ctx.sessionPersistence.list()).map(h => h.id)).toContain(m.id) void dir }) @@ -191,7 +198,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { } const childLocation = ctx.sessionPersistence.locate(child) expect(childLocation?.path).not.toBe(parentLocation?.path) - expect(childLocation).toEqual({ kind: 'jsonl', path: logPath(root, '/work', child.id) }) + expect(childLocation).toEqual({ kind: 'jsonl', path: rawLogPath(root, '/work', child.id) }) }) it('round-trip is byte-identical (incl. assistant/chunk verbatim)', async () => { @@ -213,7 +220,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { it('rejects a stored v0 log containing a legacy request/header-delta event', async () => { const m = meta('legacy-header-delta', '/legacy') - const path = logPath(root, m.cwd, m.id) + const path = rawLogPath(root, m.cwd, m.id) await mkdir(sessionDir(root, m.cwd), { recursive: true }) await writeFile(path, [ JSON.stringify(toHeaderLine(m)), @@ -228,7 +235,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { it('rejects a stored v0 full header carrying the legacy fallback reason', async () => { const m = meta('legacy-header-fallback', '/legacy') - const path = logPath(root, m.cwd, m.id) + const path = rawLogPath(root, m.cwd, m.id) await mkdir(sessionDir(root, m.cwd), { recursive: true }) await writeFile(path, [ JSON.stringify(toHeaderLine(m)), @@ -270,7 +277,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { // Simulate a crash mid-second-turn: append raw lines that are NOT closed by // a turn/end (turn/start + step/start are fully written), plus a final // partial line with no newline (a torn fragment never fully flushed). - const path = logPath(root, '/proj', m.id) + const path = rawLogPath(root, '/proj', m.id) await writeFile(path, [ JSON.stringify({ type: 'turn/start', seq: 6, time: 8, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }), JSON.stringify({ type: 'step/start', seq: 7, time: 9, data: { turn: 2, step: 1 } }), @@ -303,17 +310,17 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { const m = meta('append-only') await ctx.sessionPersistence.create(m) await ctx.sessionPersistence.append(m.id, oneTurnLog()) - const before = await readFile(logPath(root, undefined, m.id), 'utf8') + const before = await readFile(rawLogPath(root, undefined, m.id), 'utf8') const committedPrefix = before // the whole committed log // A crash tail then a repair-append. - await writeFile(logPath(root, undefined, m.id), '\n{"partial', { flag: 'a' }) + await writeFile(rawLogPath(root, undefined, m.id), '\n{"partial', { flag: 'a' }) await ctx.sessionPersistence.load(m.id) await ctx.sessionPersistence.append(m.id, [ { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[]) - const after = await readFile(logPath(root, undefined, m.id), 'utf8') + const after = await readFile(rawLogPath(root, undefined, m.id), 'utf8') // the committed prefix is byte-for-byte intact at the head of the file expect(after.startsWith(committedPrefix)).toBe(true) }) @@ -322,12 +329,12 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { const m = meta('truncate-retry') await ctx.sessionPersistence.create(m) await ctx.sessionPersistence.append(m.id, oneTurnLog()) // materialized, seqs 0..5 - const sizeBefore = (await stat(logPath(root, undefined, m.id))).size + const sizeBefore = (await stat(rawLogPath(root, undefined, m.id))).size // Force the NEXT fsync (inside appendLines) to fail once, AFTER writeFile // has already put bytes on disk — simulating an ENOSPC/fsync error // mid-append. The recovery truncate() also fsyncs, so allow that one. - const handle = await (await import('node:fs/promises')).open(logPath(root, undefined, m.id), 'r') + const handle = await (await import('node:fs/promises')).open(rawLogPath(root, undefined, m.id), 'r') const proto = Object.getPrototypeOf(handle) as { sync: () => Promise } await handle.close() const realSync = proto.sync @@ -344,7 +351,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { // The append rejects, but the partial bytes are truncated back: the file is // its pre-append size and the cursor is unchanged. await expect(ctx.sessionPersistence.append(m.id, turn2)).rejects.toThrow(/ENOSPC/) - expect((await stat(logPath(root, undefined, m.id))).size).toBe(sizeBefore) + expect((await stat(rawLogPath(root, undefined, m.id))).size).toBe(sizeBefore) spy.mockRestore() // The retry now succeeds with NO seq gap — the log is contiguous 0..7. @@ -425,7 +432,7 @@ describe('SessionPersistenceJsonl: write path (session/event → flush)', () => root = await freshRoot() const ctx = new Context() await ctx.plugin(SessionStore) - await ctx.plugin(SessionPersistenceJsonl, { root }) + await ctx.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) const a = ctx.sessions.create(SessionId('sa')) const b = ctx.sessions.create(SessionId('sb')) @@ -552,7 +559,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { root = await freshRoot() ctx = new Context() await ctx.plugin(SessionStore) - await ctx.plugin(SessionPersistenceJsonl, { root }) + await ctx.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) }) afterEach(async () => { await ctx.fiber.dispose() }) @@ -572,8 +579,8 @@ describe('SessionPersistenceJsonl: edge cases', () => { await p await ctx.sessionPersistence.append(SessionId('create-snap'), oneTurnLog()) // The log materialized under the ORIGINAL cwd, not the mutated one. - expect((await stat(logPath(root, '/orig', SessionId('create-snap')))).isFile()).toBe(true) - await expect(stat(logPath(root, '/mutated', SessionId('create-snap')))).rejects.toThrow() + expect((await stat(rawLogPath(root, '/orig', SessionId('create-snap')))).isFile()).toBe(true) + await expect(stat(rawLogPath(root, '/mutated', SessionId('create-snap')))).rejects.toThrow() }) it('list discovers sessions across multiple cwd buckets', async () => { @@ -654,7 +661,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { // of grafting no-cwd events onto a log with mismatched cwd. const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root }) + await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) let b!: Session await ctx2.plugin(Object.assign((inner: Context) => { b = inner.sessions.create(SessionId('x')) // no cwd @@ -663,10 +670,10 @@ describe('SessionPersistenceJsonl: edge cases', () => { // The "/w" log is untouched — no no-cwd events were grafted onto it, and no // `_no-cwd` log for "x" was created. - const inW = scanLog(await readFile(logPath(root, '/w', SessionId('x')))) + const inW = scanLog(await readFile(rawLogPath(root, '/w', SessionId('x')))) expect(inW.meta.cwd).toBe('/w') expect(inW.events).toHaveLength(6) - await expect(stat(logPath(root, undefined, SessionId('x')))).rejects.toThrow() + await expect(stat(rawLogPath(root, undefined, SessionId('x')))).rejects.toThrow() await ctx2.fiber.dispose() }) @@ -710,7 +717,10 @@ describe('SessionPersistenceJsonl: edge cases', () => { it('list returns nothing when the root directory does not exist', async () => { const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root: join(root, 'does-not-exist-yet') }) + await ctx2.plugin(SessionPersistenceJsonl, { + root: join(root, 'does-not-exist-yet'), + compression: 'none', + }) expect(await ctx2.sessionPersistence.list()).toEqual([]) await ctx2.fiber.dispose() }) @@ -722,7 +732,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { await writeFile(filePath, 'x') const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root: filePath }) + await ctx2.plugin(SessionPersistenceJsonl, { root: filePath, compression: 'none' }) await expect(ctx2.sessionPersistence.list()).rejects.toThrow(/ENOTDIR/) await ctx2.fiber.dispose() }) @@ -733,7 +743,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { const cwd = '/x' const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root }) + await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) await writeFile(sessionDir(root, cwd), 'x') // bucket path is now a FILE let s!: Session await ctx2.plugin(Object.assign((inner: Context) => { @@ -748,14 +758,14 @@ describe('SessionPersistenceJsonl: edge cases', () => { const m = meta('disk-append', '/d') await ctx.sessionPersistence.create(m) await ctx.sessionPersistence.append(m.id, oneTurnLog()) - await writeFile(logPath(root, '/d', m.id), '\n{"partial crash', { flag: 'a' }) + await writeFile(rawLogPath(root, '/d', m.id), '\n{"partial crash', { flag: 'a' }) // A FRESH backend with no in-memory state: append directly (no prior load) // → append must adopt from disk, and the adopt's load schedules a repair // that the same append then performs before writing. const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root }) + await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) await ctx2.sessionPersistence.append(m.id, [ { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } }, @@ -791,7 +801,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { // nondeterministic. create scans every bucket, not just meta.cwd's. const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root }) + await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) await expect(ctx2.sessionPersistence.create(meta('dup-id', '/projB'))) .rejects.toThrow(/already has a persisted log on disk/) await ctx2.fiber.dispose() @@ -801,7 +811,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { root = await freshRoot() const ctx2 = new Context() await ctx2.plugin(SessionStore) - await ctx2.plugin(SessionPersistenceJsonl, { root }) + await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) const session = ctx2.sessions.create(SessionId('flush-fail')) // A full turn lands in the write-behind buffer. session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts new file mode 100644 index 0000000000..bd552e738e --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts @@ -0,0 +1,24 @@ +import { describe, expect, it } from 'vitest' +import { compressZstdFrame, decompressZstdFrame, scanZstdFrames } from '../src/zstd.ts' + +describe('JSONL Zstandard compatibility', () => { + it('round-trips concatenated checksummed frames through the built-in Node API', async () => { + const encoded = Buffer.concat([ + await compressZstdFrame('{"type":"session","version":0,"id":"compat","createdAt":1}\n'), + await compressZstdFrame('{"type":"turn/start","seq":0,"turn":1}\n'), + ]) + const { frames, tornStart } = scanZstdFrames(encoded) + + expect(tornStart).toBeUndefined() + expect(frames).toHaveLength(2) + expect(frames.map(frame => encoded.subarray(frame.start, frame.start + 4).toString('hex'))) + .toEqual(['28b52ffd', '28b52ffd']) + const decoded = await Promise.all(frames.map(frame => decompressZstdFrame(encoded.subarray(frame.start, frame.end)))) + expect(Buffer.concat(decoded).toString()).toContain('"type":"turn/start"') + + const eventFrame = encoded.subarray(frames[1]!.start, frames[1]!.end) + const missingChecksumByte = eventFrame.subarray(0, -1) + expect(scanZstdFrames(missingChecksumByte)).toEqual({ frames: [], tornStart: 0 }) + expect((await decompressZstdFrame(missingChecksumByte)).toString()).toContain('"type":"turn/start"') + }) +}) diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts new file mode 100644 index 0000000000..830e17ffc7 --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts @@ -0,0 +1,483 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import { appendFile, mkdir, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises' +import type { FileHandle } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' +import { eventLine, logPath, scanLog, sessionDir, toHeaderLine, type JsonlCompression } from '../src/format.ts' +import { compressZstdFrame, decompressZstdFrame, scanZstdFrames } from '../src/zstd.ts' +import { runPersistenceContract, meta, oneTurnLog } from '../../session-persistence/tests/contract.ts' +import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts' + +const MAGIC = Buffer.from([0x28, 0xB5, 0x2F, 0xFD]) +const roots: string[] = [] +const contexts: Context[] = [] + +async function freshRoot(prefix = 'dsh-jsonl-zstd-'): Promise { + const root = await mkdtemp(join(tmpdir(), prefix)) + roots.push(root) + return root +} + +async function mount(root: string, compression?: JsonlCompression): Promise { + const ctx = new Context() + contexts.push(ctx) + await ctx.plugin(SessionStore) + await ctx.plugin(SessionPersistenceJsonl, { + root, + ...(compression === undefined ? {} : { compression }), + }) + return ctx +} + +async function decodeCompleteFrames(buffer: Buffer): Promise { + const { frames, tornStart } = scanZstdFrames(buffer) + expect(tornStart).toBeUndefined() + const plaintext: Buffer[] = [] + for (const frame of frames) { + plaintext.push(await decompressZstdFrame(buffer.subarray(frame.start, frame.end))) + } + return Buffer.concat(plaintext) +} + +async function tornFrame( + plaintext: string, + accepts: (decoded: string) => boolean, +): Promise { + const frame = await compressZstdFrame(plaintext) + const candidateEnds = [ + frame.length - 1, + frame.length - 4, + ...[0.9, 0.75, 0.6, 0.5, 0.4, 0.25].map(ratio => Math.floor(frame.length * ratio)), + ] + for (const end of candidateEnds) { + const candidate = frame.subarray(0, end) + if (scanZstdFrames(candidate).tornStart !== 0) continue + try { + const decoded = (await decompressZstdFrame(candidate)).toString('utf8') + if (accepts(decoded)) return candidate + } catch { + // Some early cuts precede the first decodable block; keep searching for + // a cut that exercises partial-plaintext recovery. + } + } + throw new Error('test fixture could not produce the requested torn Zstandard frame') +} + +function deterministicNoise(length: number): string { + let state = 0x12345678 + let output = '' + for (let index = 0; index < length; index++) { + state = (Math.imul(state, 1_664_525) + 1_013_904_223) >>> 0 + output += String.fromCharCode(33 + (state % 90)) + } + return output +} + +function emptyStructuralFrame(descriptor: number): Buffer { + const contentSizeFlag = descriptor >>> 6 + const singleSegment = (descriptor & 0x20) !== 0 + const dictionaryBytes = [0, 1, 2, 4][descriptor & 0x03]! + const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag + const variableHeader = Buffer.alloc((singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes) + const lastEmptyRawBlock = Buffer.from([1, 0, 0]) + const checksum = (descriptor & 0x04) === 0 ? Buffer.alloc(0) : Buffer.alloc(4) + return Buffer.concat([MAGIC, Buffer.from([descriptor]), variableHeader, lastEmptyRawBlock, checksum]) +} + +afterEach(async () => { + vi.restoreAllMocks() + for (const ctx of contexts.splice(0).reverse()) await ctx.fiber.dispose() + for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) +}) + +runPersistenceContract('jsonl-zstd', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-jsonl-zstd-contract-')) + const ctx = new Context() + await ctx.plugin(SessionStore) + const fiber = await ctx.plugin(SessionPersistenceJsonl, { root }) + return { + persistence: ctx.sessionPersistence, + dispose: async () => { + await fiber.dispose() + await rm(root, { recursive: true, force: true }) + }, + } +}) + +runCoordinatorContract('jsonl-zstd', async (): Promise => { + const root = await mkdtemp(join(tmpdir(), 'dsh-jsonl-zstd-coordinator-')) + return { + mount: async ctx => ctx.plugin(SessionPersistenceJsonl, { root }), + corruptTail: async (id, cwd) => { + const line = JSON.stringify({ + type: 'assistant/chunk', + seq: 8, + time: 9, + data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } }, + }) + '\n' + const partial = await tornFrame(line, decoded => decoded.length > 0 && !decoded.endsWith('\n')) + await appendFile(logPath(root, cwd, id, 'zstd'), partial) + }, + cleanup: async () => { await rm(root, { recursive: true, force: true }) }, + } +}) + +describe('Zstandard frame structure', () => { + it('scans concatenated checksummed frames and honors a frame limit', async () => { + const first = await compressZstdFrame('header\n') + const second = await compressZstdFrame('event\n') + const stream = Buffer.concat([first, second]) + expect(scanZstdFrames(Buffer.alloc(0))).toEqual({ frames: [] }) + expect(scanZstdFrames(stream)).toEqual({ + frames: [{ start: 0, end: first.length }, { start: first.length, end: stream.length }], + }) + expect(scanZstdFrames(stream, 1)).toEqual({ frames: [{ start: 0, end: first.length }] }) + expect(first[4]! & 0x04).toBe(0x04) + expect(second[4]! & 0x04).toBe(0x04) + expect((await decompressZstdFrame(first)).toString()).toBe('header\n') + }) + + it('distinguishes incomplete frame regions from invalid complete structure', () => { + expect(scanZstdFrames(MAGIC.subarray(0, 2))).toEqual({ frames: [], tornStart: 0 }) + expect(scanZstdFrames(MAGIC)).toEqual({ frames: [], tornStart: 0 }) + expect(() => scanZstdFrames(Buffer.alloc(4))).toThrow(/invalid frame magic/) + expect(() => scanZstdFrames(Buffer.concat([MAGIC, Buffer.from([0x08])]))).toThrow(/reserved frame-header bit/) + + // Non-single-segment descriptor with no window descriptor. + expect(scanZstdFrames(Buffer.concat([MAGIC, Buffer.from([0x00])]))).toEqual({ frames: [], tornStart: 0 }) + // Single-segment header followed by only two bytes of the three-byte block header. + expect(scanZstdFrames(Buffer.concat([MAGIC, Buffer.from([0x20, 0x00, 0x01, 0x00])]))).toEqual({ + frames: [], + tornStart: 0, + }) + + const rawFiveBytes = Buffer.from([(5 << 3) | 1, 0, 0]) + expect(scanZstdFrames(Buffer.concat([ + MAGIC, + Buffer.from([0x20, 0x00]), + rawFiveBytes, + Buffer.from([0x01, 0x02]), + ]))).toEqual({ frames: [], tornStart: 0 }) + + const reservedBlock = Buffer.concat([ + MAGIC, + Buffer.from([0x20, 0x00, 0x07, 0x00, 0x00]), + ]) + expect(() => scanZstdFrames(reservedBlock)).toThrow(/reserved block type/) + }) + + it('covers standard header variants, RLE blocks, multiple blocks, and checksums', () => { + for (const descriptor of [0x00, 0x21, 0x42, 0x83, 0xE3]) { + const frame = emptyStructuralFrame(descriptor) + expect(scanZstdFrames(frame)).toEqual({ frames: [{ start: 0, end: frame.length }] }) + } + + const rle = Buffer.concat([ + MAGIC, + Buffer.from([0x20, 0x01]), + Buffer.from([(1 << 3) | (1 << 1) | 1, 0, 0]), + Buffer.from([0x41]), + ]) + expect(scanZstdFrames(rle)).toEqual({ frames: [{ start: 0, end: rle.length }] }) + + const twoBlocks = Buffer.concat([ + MAGIC, + Buffer.from([0x20, 0x00]), + Buffer.from([0, 0, 0]), + Buffer.from([1, 0, 0]), + ]) + expect(scanZstdFrames(twoBlocks)).toEqual({ frames: [{ start: 0, end: twoBlocks.length }] }) + + const checksummed = emptyStructuralFrame(0x24) + expect(scanZstdFrames(checksummed.subarray(0, -1))).toEqual({ frames: [], tornStart: 0 }) + expect(scanZstdFrames(checksummed)).toEqual({ frames: [{ start: 0, end: checksummed.length }] }) + }) +}) + +describe('SessionPersistenceJsonl: default Zstandard encoding', () => { + it('writes .jsonl.zstd by default with one header frame and one first-batch frame', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('default-zstd', '/work') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + + const path = logPath(root, header.cwd, header.id, 'zstd') + const buffer = await readFile(path) + expect(buffer.subarray(0, 4)).toEqual(MAGIC) + await expect(stat(logPath(root, header.cwd, header.id, 'none'))).rejects.toThrow() + expect(ctx.sessionPersistence.locate(header)).toEqual({ kind: 'jsonl', path }) + + const scan = scanZstdFrames(buffer) + expect(scan.frames).toHaveLength(2) + const plaintext = await decodeCompleteFrames(buffer) + expect(plaintext.toString()).toBe([ + JSON.stringify(toHeaderLine(header)), + ...oneTurnLog().map(eventLine), + '', + ].join('\n')) + expect((await ctx.sessionPersistence.load(header.id)).events).toEqual(oneTurnLog()) + }) + + it('resolves the default when a programmatic wrapper bypasses Loader schema normalization', async () => { + const root = await freshRoot() + const ctx = new Context() + contexts.push(ctx) + await ctx.plugin(SessionStore) + let backend!: SessionPersistenceJsonl + await ctx.plugin(Object.assign((inner: Context) => { + backend = new SessionPersistenceJsonl(inner, { root }) + }, { inject: ['sessions'] })) + const header = meta('direct-default') + expect(backend.locate(header)).toEqual({ + kind: 'jsonl', + path: logPath(root, header.cwd, header.id, 'zstd'), + }) + }) + + it('appends one frame per durable batch without rewriting prior bytes', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('append-frame') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + const path = logPath(root, header.cwd, header.id, 'zstd') + const before = await readFile(path) + const secondTurn = [ + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, + ] as SessionEvent[] + await ctx.sessionPersistence.append(header.id, secondTurn) + + const after = await readFile(path) + expect(after.subarray(0, before.length)).toEqual(before) + expect(scanZstdFrames(after).frames).toHaveLength(3) + expect((await ctx.sessionPersistence.load(header.id)).events).toEqual([...oneTurnLog(), ...secondTurn]) + }) + + it('lists from a multi-chunk header frame without decoding a corrupt event frame', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('large-header', `/work/${'x'.repeat(24_000)}`) + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + const path = logPath(root, header.cwd, header.id, 'zstd') + const buffer = Buffer.from(await readFile(path)) + const eventFrame = scanZstdFrames(buffer).frames[1]! + buffer[eventFrame.end - 1] = buffer[eventFrame.end - 1]! ^ 0xFF + await writeFile(path, buffer) + + expect((await ctx.sessionPersistence.list()).map(item => item.id)).toEqual([header.id]) + await expect(ctx.sessionPersistence.load(header.id)).rejects.toThrow(/frame at byte .* failed validation/) + }) + + it('preserves complete records from a torn frame and re-encodes them with crash closers', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('recover-torn', '/proj') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + const path = logPath(root, header.cwd, header.id, 'zstd') + const committed = await readFile(path) + const openTurn = [ + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } }, + { type: 'assistant/chunk', seq: 8, time: 9, data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } } }, + ] as SessionEvent[] + const plaintext = openTurn.map(eventLine).join('\n') + '\n' + const partial = await tornFrame(plaintext, (decoded) => { + const newlines = decoded.match(/\n/g)?.length ?? 0 + return newlines >= 2 && !decoded.endsWith('\n') + }) + await appendFile(path, partial) + + const loaded = await ctx.sessionPersistence.load(header.id) + expect(loaded.events.map(event => event.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) + expect(loaded.events[6]).toEqual(openTurn[0]) + expect(loaded.events[7]).toEqual(openTurn[1]) + expect(loaded.events.some(event => event.type === 'assistant/chunk' && event.seq === 8)).toBe(false) + expect(loaded.events[8]?.type).toBe('step/end') + expect(loaded.events[9]?.type).toBe('turn/end') + + const repaired = await readFile(path) + expect(repaired.subarray(0, committed.length)).toEqual(committed) + expect(scanZstdFrames(repaired).tornStart).toBeUndefined() + expect(scanLog(await decodeCompleteFrames(repaired)).events).toEqual(loaded.events) + }) + + it('drops a frame torn in its header before it has produced plaintext', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('partial-magic') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + const path = logPath(root, header.cwd, header.id, 'zstd') + const committed = await readFile(path) + await appendFile(path, MAGIC.subarray(0, 2)) + + expect((await ctx.sessionPersistence.load(header.id)).events).toEqual(oneTurnLog()) + expect(await readFile(path)).toEqual(committed) + }) + + it('recovers complete events when EOF tears only the final frame checksum', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('partial-checksum') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + const path = logPath(root, header.cwd, header.id, 'zstd') + const secondTurn = [ + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, + ] as SessionEvent[] + const frame = await compressZstdFrame(secondTurn.map(eventLine).join('\n') + '\n') + await appendFile(path, frame.subarray(0, -1)) + + const loaded = await ctx.sessionPersistence.load(header.id) + expect(loaded.events).toEqual([...oneTurnLog(), ...secondTurn]) + const repaired = await readFile(path) + expect(scanZstdFrames(repaired).tornStart).toBeUndefined() + expect(scanLog(await decodeCompleteFrames(repaired)).events).toEqual(loaded.events) + }) + + it('rejects a complete frame containing a torn JSONL record', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('complete-bad-jsonl') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + await appendFile( + logPath(root, header.cwd, header.id, 'zstd'), + await compressZstdFrame('{"type":"turn/start"'), + ) + await expect(ctx.sessionPersistence.load(header.id)).rejects.toThrow(/complete frame contains a torn JSONL record/) + }) + + it('rolls back a checksummed append frame when fsync fails', async () => { + const root = await freshRoot() + const ctx = await mount(root) + const header = meta('zstd-fsync-rollback') + await ctx.sessionPersistence.create(header) + await ctx.sessionPersistence.append(header.id, oneTurnLog()) + const path = logPath(root, header.cwd, header.id, 'zstd') + const before = await readFile(path) + + const handle = await open(path, 'r') + const prototype = Object.getPrototypeOf(handle) as { sync: () => Promise } + await handle.close() + const realSync = prototype.sync + let failed = false + const spy = vi.spyOn(prototype, 'sync').mockImplementation(async function (this: FileHandle) { + if (!failed) { + failed = true + throw new Error('simulated Zstandard fsync failure') + } + return realSync.call(this) + }) + const secondTurn = [ + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, + ] as SessionEvent[] + await expect(ctx.sessionPersistence.append(header.id, secondTurn)).rejects.toThrow(/simulated Zstandard fsync failure/) + expect(await readFile(path)).toEqual(before) + spy.mockRestore() + await ctx.sessionPersistence.append(header.id, secondTurn) + expect((await ctx.sessionPersistence.load(header.id)).events).toEqual([...oneTurnLog(), ...secondTurn]) + }) + + it('skips empty, incomplete, and non-header compressed artifacts while rejecting malformed header frames', async () => { + const root = await freshRoot() + const bucket = sessionDir(root, undefined) + await mkdir(bucket, { recursive: true }) + await writeFile(join(bucket, 'empty.jsonl.zstd'), '') + await writeFile(join(bucket, 'partial.jsonl.zstd'), MAGIC) + await writeFile(join(bucket, 'not-header.jsonl.zstd'), await compressZstdFrame('{"type":"turn/start"}\n')) + const ctx = await mount(root) + expect(await ctx.sessionPersistence.list()).toEqual([]) + + await writeFile(join(bucket, 'two-lines.jsonl.zstd'), await compressZstdFrame([ + JSON.stringify(toHeaderLine(meta('two-lines'))), + JSON.stringify({ type: 'turn/start' }), + '', + ].join('\n'))) + await expect(ctx.sessionPersistence.list()).rejects.toThrow(/first frame is not exactly one header line/) + await expect(ctx.sessionPersistence.load(SessionId('two-lines'))) + .rejects.toThrow(/first frame is not exactly one header line/) + }) + + it('rejects missing, empty, and checksum-corrupt header frames on targeted reads', async () => { + const root = await freshRoot() + const bucket = sessionDir(root, undefined) + await mkdir(bucket, { recursive: true }) + await writeFile(logPath(root, undefined, SessionId('partial-only'), 'zstd'), MAGIC) + await writeFile(logPath(root, undefined, SessionId('empty-header'), 'zstd'), await compressZstdFrame('')) + const corruptHeader = Buffer.from(await compressZstdFrame(`${JSON.stringify(toHeaderLine(meta('bad-checksum')))}\n`)) + corruptHeader[corruptHeader.length - 1] = corruptHeader[corruptHeader.length - 1]! ^ 0xFF + await writeFile(logPath(root, undefined, SessionId('bad-checksum'), 'zstd'), corruptHeader) + const ctx = await mount(root) + + await expect(ctx.sessionPersistence.load(SessionId('partial-only'))) + .rejects.toThrow(/empty or header-less Zstandard session log/) + await expect(ctx.sessionPersistence.load(SessionId('empty-header'))) + .rejects.toThrow(/first frame is not exactly one header line/) + await expect(ctx.sessionPersistence.list()).rejects.toThrow(/header frame failed validation/) + }) +}) + +describe('SessionPersistenceJsonl: encoding selection', () => { + it('rejects roots owned by the opposite encoding in both directions', async () => { + const rawRoot = await freshRoot('dsh-jsonl-raw-mismatch-') + const raw = await mount(rawRoot, 'none') + const rawHeader = meta('raw-log') + await raw.sessionPersistence.create(rawHeader) + await raw.sessionPersistence.append(rawHeader.id, oneTurnLog()) + const defaultBackend = await mount(rawRoot) + await expect(defaultBackend.sessionPersistence.list()).rejects.toThrow(/configured for compression "zstd"/) + + const zstdRoot = await freshRoot('dsh-jsonl-zstd-mismatch-') + const zstd = await mount(zstdRoot) + const zstdHeader = meta('zstd-log') + await zstd.sessionPersistence.create(zstdHeader) + await zstd.sessionPersistence.append(zstdHeader.id, oneTurnLog()) + const rawBackend = await mount(zstdRoot, 'none') + await expect(rawBackend.sessionPersistence.list()).rejects.toThrow(/configured for compression "none"/) + }) + + it('rechecks targeted artifacts and listing after an initially empty root', async () => { + const root = await freshRoot() + const ctx = await mount(root) + expect(await ctx.sessionPersistence.list()).toEqual([]) + + const loadHeader = meta('late-raw-load', '/late') + await mkdir(sessionDir(root, loadHeader.cwd), { recursive: true }) + await writeFile(logPath(root, loadHeader.cwd, loadHeader.id, 'none'), [ + JSON.stringify(toHeaderLine(loadHeader)), + ...oneTurnLog().map(eventLine), + '', + ].join('\n')) + await expect(ctx.sessionPersistence.load(loadHeader.id)).rejects.toThrow(/uses \.jsonl/) + await expect((ctx.sessionPersistence as SessionPersistenceJsonl).loadLive(loadHeader.id, loadHeader.cwd)) + .rejects.toThrow(/uses \.jsonl/) + await expect(ctx.sessionPersistence.list()).rejects.toThrow(/uses \.jsonl/) + }) + + it('refuses materialization when an opposite artifact appears after create', async () => { + const root = await freshRoot() + const ctx = await mount(root) + await ctx.sessionPersistence.list() + const header = meta('late-raw-materialize', '/late') + await ctx.sessionPersistence.create(header) + await mkdir(sessionDir(root, header.cwd), { recursive: true }) + await writeFile(logPath(root, header.cwd, header.id, 'none'), [ + JSON.stringify(toHeaderLine(header)), + ...oneTurnLog().map(eventLine), + '', + ].join('\n')) + await expect(ctx.sessionPersistence.append(header.id, oneTurnLog())).rejects.toThrow(/uses \.jsonl/) + expect((await readdir(sessionDir(root, header.cwd))).some(name => name.endsWith('.jsonl.zstd'))).toBe(false) + }) +}) diff --git a/packages/support/README.md b/packages/support/README.md index 433d6b3cdb..045b69d390 100644 --- a/packages/support/README.md +++ b/packages/support/README.md @@ -10,4 +10,4 @@ Packages that exist to serve development, testing, and the examples rather than | `loader-smoke/` | Shared real-Loader subprocess harness for keyless example smokes | (library — imported by example e2e suites) | | `llm-replay/` | Record/replay adapter: short-circuits `llm/stream` from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) | -`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `agent-loop-testkit` centralizes the mandatory service spine for hand-built AgentLoop tests without owning their loop or scenario. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the ACP subprocess/client boundary plus the snapshot harness, normalizers, and suite machinery, while `loader-smoke` owns the parallel stdio/Loader process boundary used by keyless example e2e suites. A package graduates OUT of `support/` into a product group only when it gains documented product consumers. +`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `agent-loop-testkit` centralizes the mandatory service spine for hand-built AgentLoop tests without owning their loop or scenario. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the ACP subprocess/client boundary plus the snapshot harness, normalizers, and suite machinery, while `loader-smoke` owns the parallel real-Loader launch boundary used by keyless example e2e suites. A package graduates OUT of `support/` into a product group only when it gains documented product consumers. diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 231ba0d6e8..b109ca3afa 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -52,5 +52,5 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work -- **Session harvest is JSONL-only** — `runScenario` collects persisted `.jsonl` logs, so an example composed over the SQLite persistence backend has no snapshot path. +- **Session harvest requires raw JSONL mode** — `runScenario` collects persisted `.jsonl` logs, so snapshot configs set `persistenceCompression: 'none'`; compressed JSONL and SQLite compositions have no snapshot-harvest path. - **The subprocess boots the unbuilt tsx/Loader path only** — the built-bin artifact is guarded by the separate `built-bin` e2e smokes, never by this tier. diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts index 9700f24702..435d352789 100644 --- a/packages/support/acp-snapshot/src/harness.ts +++ b/packages/support/acp-snapshot/src/harness.ts @@ -417,11 +417,11 @@ async function runStep( * header line, and return them ordered primary-first: the top-level session (no * `parentSession`) leads, then each subagent child by ascending `createdAt`. * - * The JSONL backend lays sessions out as `//.jsonl` - * (one bucket per cwd), so a parent and its same-cwd in-process child land in - * the SAME bucket — collecting all files across all buckets catches both (a - * first-match short-circuit would silently drop the child). Returns `[]` if no - * log was produced (a no-session scenario). + * Snapshot configs select the JSONL backend's raw mode, which lays sessions + * out as `//.jsonl` (one bucket per cwd). A + * parent and its same-cwd in-process child land in the SAME bucket, so + * collecting all files across all buckets catches both. Returns `[]` if no log + * was produced (a no-session scenario). */ async function harvestSessionLogs(root: string): Promise { let cwdDirs: string[] diff --git a/packages/support/loader-smoke/tests/example-launch.spec.ts b/packages/support/loader-smoke/tests/example-launch.spec.ts index 20520e6fb6..77a0791516 100644 --- a/packages/support/loader-smoke/tests/example-launch.spec.ts +++ b/packages/support/loader-smoke/tests/example-launch.spec.ts @@ -5,7 +5,7 @@ import { resolveExampleMode, } from '@deepseek-ai/dsh-loader-smoke' -const SRC_BIN = '/repo/packages/examples/stdio-demo/src/bin.ts' +const SRC_BIN = '/repo/packages/examples/tui-demo/src/bin.ts' const TSCONFIG = '/repo/tsconfig.json' const originalMode = process.env[EXAMPLE_MODE_ENV] @@ -66,7 +66,7 @@ describe('resolveExampleLaunch', () => { env: { DSH_HOME: '/tmp/home' }, }) expect(args).not.toContain('--import') - expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js') + expect(args).toContain('/repo/packages/examples/tui-demo/lib/bin.js') expect(args.slice(-2)).toEqual(['--config', './cordis.yml']) expect(env.TSX_TSCONFIG_PATH).toBeUndefined() expect(env.DSH_HOME).toBe('/tmp/home') @@ -106,6 +106,6 @@ describe('resolveExampleLaunch', () => { it('defaults the mode from the environment', () => { process.env[EXAMPLE_MODE_ENV] = 'lib' const { args } = resolveExampleLaunch({ srcBin: SRC_BIN }) - expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js') + expect(args).toContain('/repo/packages/examples/tui-demo/lib/bin.js') }) }) diff --git a/packages/todo/README.md b/packages/todo/README.md index bfe5ec7503..c19fab82d3 100644 --- a/packages/todo/README.md +++ b/packages/todo/README.md @@ -6,4 +6,4 @@ The model-facing todo tool. A single **product** package — there is no interfa |---|---|---| | `tool-todo/` | Model-facing `todo_write` tool; writes the whole list to the session log (`todo/write`) | (registers on `ctx.tools`) | -The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs render off `session/event`: the [terminal app](../examples/stdio-demo) shows a persistent TUI plan or readline checklist, while the [ACP bridge](../ui/acp) maps it to a `plan` sessionUpdate. +The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs render off `session/event`: the [TUI app](../examples/tui-demo) shows a persistent plan, while the [ACP bridge](../ui/acp) maps it to a `plan` sessionUpdate. diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md index 6323d86247..2ccdd7699e 100644 --- a/packages/todo/tool-todo/README.md +++ b/packages/todo/tool-todo/README.md @@ -18,7 +18,7 @@ Beyond the schema's type/required/enum checks, `execute` rejects an empty or dup ## Rendering -The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [terminal app](../../examples/stdio-demo) shows a persistent TUI plan or readline checklist, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires). +The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [TUI app](../../examples/tui-demo) shows a persistent plan, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires). ## Export shape diff --git a/packages/ui/README.md b/packages/ui/README.md index 13e123417e..aad4a9b628 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -10,13 +10,12 @@ Integrations that expose the agent to an external editor or client. These are ** | `permission/` | User-facing permission presets (`workspace-write`/`danger-full-access`): one product-level select bundling the sandbox-mode and approval-policy knobs, written through to their session events | `ctx.permission` | | `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` | | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) | -| `stdio/` | Line-oriented terminal channel for pipes and automation; drives `ctx.agents`, renders `session/event`, and answers `ctx.userInteraction` | (drives `ctx.agents`) | | `tui/` | Interactive pi-tui terminal channel for TTY sessions; renders `session/event`, tool presentation intents, and answers `ctx.userInteraction` | (drives `ctx.agents`) | | `jsonrpc/` | Stdio JSON-RPC server for out-of-process SDK clients | (drives `ctx.agents`) | | `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) | -A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). The [`stdio`](stdio/README.md) and [`tui`](tui/README.md) plugins are the two terminal front doors: one is line-oriented for pipes, the other is interactive for TTYs. [`commands`](commands/README.md) is their human-only discovery and dispatch plane; command input and output do not become model messages. App bundles and SDK projects compose the appropriate channel explicitly with the services and tools their product profile selects. +A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). [`tui`](tui/README.md) is the interactive terminal front door; non-interactive tasks use the headless `cli-demo` app instead of a UI channel. [`commands`](commands/README.md) is the human-only discovery and dispatch plane shared by TUI and ACP; command input and output do not become model messages. `user-approval`, `user-interaction`, and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. `user-approval` owns the one-shot `ctx.approval` decision mechanism and its policy tier; answerers remain with their UI channel owners. `user-interaction` remains provider-neutral (`ctx.userInteraction`), while `tool-ask-user` is its model-facing consumer and the app/bridge packages provide concrete providers. -The runnable app bundles that bake these bridges into boot bins — the terminal chat app, the ACP server app, and the JSON-RPC SDK-runtime bin — live in [`examples/`](../examples/README.md) (`stdio-demo`, `acp-demo`, `jsonrpc-demo`), each composed over the [`agent-spine-demo`](../examples/agent-spine-demo/README.md) bundle. `ui/` keeps the reusable bridge/channel plugins and the `app-boot` glue; each front door owns its stdout policy, and a leaf `cordis.yml` supplies backends and optional tools. +The runnable app bundles that bake these bridges into boot bins — the TUI app, ACP server app, and JSON-RPC SDK-runtime bin — live in [`examples/`](../examples/README.md) (`tui-demo`, `acp-demo`, `jsonrpc-demo`), each composed over the [`agent-spine-demo`](../examples/agent-spine-demo/README.md) bundle. `ui/` keeps the reusable bridge/channel plugins and the `app-boot` glue; each front door owns its stdout policy, and a leaf `cordis.yml` supplies backends and optional tools. diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md index 23bc446d3a..e50df12fb4 100644 --- a/packages/ui/acp/README.md +++ b/packages/ui/acp/README.md @@ -2,7 +2,7 @@ Agent Client Protocol bridge over JSON-RPC stdio. Editors can create or resume agents, stream their events, answer questions and approvals, and render tool calls. One connection supports multiple isolated sessions; Zed is the primary compatibility target. -It is a **client-driver / UI plugin**, the structured analogue of the terminal `dsh-tui`/`dsh-stdio` channels — NOT a loop change and NOT a [capability seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`. +It is a **client-driver / UI plugin**, the structured analogue of the terminal `dsh-tui` channel — NOT a loop change and NOT a [capability seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`. ## Service / plugin diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md index 852b1f9f9c..d874d8c154 100644 --- a/packages/ui/app-boot/README.md +++ b/packages/ui/app-boot/README.md @@ -1,6 +1,6 @@ # `@deepseek-ai/dsh-app-boot` -Shared boot glue for the app bins ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so the loader-failure lore lives once — under the per-file coverage gate — instead of drifting between two published artifacts. +Shared boot glue for the app bins ([`dsh-tui-demo`](../../examples/tui-demo/README.md), [`dsh-cli-demo`](../../examples/cli-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so the loader-failure lore lives once — under the per-file coverage gate — instead of drifting between published artifacts. | Export | Role | |---|---| diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts index 91ab0d3a2f..e2413fa736 100644 --- a/packages/ui/app-boot/src/index.ts +++ b/packages/ui/app-boot/src/index.ts @@ -1,5 +1,5 @@ /** - * Shared boot glue for the app bins (`dsh-stdio-demo`, `dsh-acp-demo`): load the gitignored + * Shared boot glue for the app bins (`dsh-tui-demo`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), and * drive the cordis Loader against a leaf `cordis.yml` until the whole tree has settled. * @module @deepseek-ai/dsh-app-boot diff --git a/packages/ui/stdio/README.md b/packages/ui/stdio/README.md deleted file mode 100644 index 07cc6a5b21..0000000000 --- a/packages/ui/stdio/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# @deepseek-ai/dsh-stdio - -The terminal readline front door for DeepSeek Harness agents. It reads prompts from stdin, sends or steers them through `ctx.agents`, renders the durable `session/event` transcript to stdout, and answers `ctx.userInteraction` requests in the same terminal. - -This package owns the terminal channel only. It injects `agents` and `userInteraction`, then drives an agent created or resumed by app or developer code. The agent spine, agent lifecycle, console logger, and model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries. - -## Config - -| Key | Default | Meaning | -|---|---|---| -| `welcome` | `ready.` | Banner printed before the first prompt | -| `sessionId` | `main` | Exact agent/session identity driven by stdin and observed for EOF shutdown | - -The plugin seeds display labels from the live agent registry, then tracks `agent/created` and `agent/disposed` so HMR and externally managed agents render consistently. While an initial exact identity is pending, it buffers nonblank input until `agent/session-start` and observes live `agent-loop/config-start-failed`; a matching failure drops queued lines, reports the loss, and lets piped EOF finish instead of hanging. The composing app must mount this front door before its config-created agent. Disposal closes readline and unregisters every listener/provider through Cordis effects. - -```yaml -- id: stdio - name: '@deepseek-ai/dsh-stdio' - config: - welcome: 'agent REPL ready. Give it a coding task.' - sessionId: main -``` - -## Model Experience - -### Readline prompt input - -#### What the model sees - -Each non-empty terminal line outside an active question becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. - -#### Token effect - -Submitted text is retained under the agent loop's normal session-history and compaction rules. The welcome banner, `> ` prompt, rendered transcript, and `[tool call]` / `[tool result]` terminal lines add no tokens. A replacement `tool/result` remains model-visible through the session surface but is not rendered as a second execution; stdio keeps the original full-fidelity result line. - -#### KV Cache effect - -Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries. - -### Terminal user-interaction answers - -#### What the model sees - -When a consumer calls `ctx.userInteraction.ask()`, this provider renders the question in the terminal and returns selected option labels or `custom` text. Through `dsh-tool-ask-user`, closed stdin becomes `Error: ask_user_question cannot be answered because stdin is closed`; disposal or abort becomes `Error: ask_user_question was interrupted before the user answered`. - -#### Token effect - -Waiting and terminal prompts add no tokens; the resolved answer or error is model-visible only through the calling tool or plugin's result. - -#### KV Cache effect - -Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries. - -## Known Limitations and Deferred Work - -- **One configured session receives stdin** — the session/event renderer can print output from any session, but input lines always drive the configured `sessionId` rather than routing by the visible label. -- **Terminal questions are text-only and sequential** — the provider queues asks, supports option labels plus custom text, and has no richer UI shapes such as file pickers or diff previews. -- **Closed stdin ends the terminal channel** — EOF rejects active or queued questions and exits after submitted work reaches idle; there is no reconnect path for a long-lived process. diff --git a/packages/ui/stdio/package.json b/packages/ui/stdio/package.json deleted file mode 100644 index e1bffdf171..0000000000 --- a/packages/ui/stdio/package.json +++ /dev/null @@ -1,49 +0,0 @@ -{ - "name": "@deepseek-ai/dsh-stdio", - "description": "Terminal readline front door for driving and rendering DeepSeek Harness agents over stdio", - "version": "0.0.1", - "private": true, - "type": "module", - "main": "lib/index.js", - "types": "lib/types/index.d.ts", - "exports": { - ".": { - "types": "./lib/types/index.d.ts", - "default": "./lib/index.js" - }, - "./src/*": "./src/*", - "./package.json": "./package.json" - }, - "files": [ - "lib/index.js", - "lib/types/**/*.d.ts", - "lib/types/**/*.d.ts.map", - "src" - ], - "license": "BSD-3-Clause", - "peerDependencies": { - "@deepseek-ai/dsh-agent": "^0.0.1", - "@deepseek-ai/dsh-agent-loop": "^0.0.1", - "@deepseek-ai/dsh-llm": "^0.0.1", - "@deepseek-ai/dsh-session": "^0.0.1", - "@deepseek-ai/dsh-user-interaction": "^0.0.1", - "cordis": "^4.0.0-rc.7" - }, - "peerDependenciesMeta": { - "@deepseek-ai/dsh-agent-loop": { - "optional": true - } - }, - "dependencies": { - "schemastery": "^3.18.0" - }, - "devDependencies": { - "@cordisjs/plugin-loader": "workspace:^", - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-agent-loop": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-user-interaction": "workspace:^", - "cordis": "^4.0.0-rc.7" - } -} diff --git a/packages/ui/stdio/src/index.ts b/packages/ui/stdio/src/index.ts deleted file mode 100644 index ac22cf6730..0000000000 --- a/packages/ui/stdio/src/index.ts +++ /dev/null @@ -1,471 +0,0 @@ -/** - * The stdio app's readline UI: reads lines from stdin into `agent.send()` or - * `steer()`, renders the durable event stream to stdout, buffers startup input - * for one exact agent/session identity, and exits piped input only after - * submitted work reaches idle. - * - * This package is the independently composable stdio front door. It establishes - * the terminal channel and drives an agent created or resumed by app or - * developer code. - * @module @deepseek-ai/dsh-stdio - */ - -import { createInterface } from 'node:readline' -import type { Readable, Writable } from 'node:stream' -import type { Context } from 'cordis' -import z from 'schemastery' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type {} from '@deepseek-ai/dsh-agent-loop' -import { SessionId } from '@deepseek-ai/dsh-session' -import { - UserInteractionError, - type AskUserQuestionAnswer, - type AskUserQuestionAnswerItem, - type AskUserQuestionItem, - type AskUserQuestionOption, - type AskUserQuestionRequest, -} from '@deepseek-ai/dsh-user-interaction' - -export const name = 'ui-stdio' -export const inject = ['agents', 'userInteraction'] - -/** Serializable plugin configuration (cordis-native, schemastery). */ -export interface Config { - /** Banner printed once on start, before the first `> ` prompt. */ - welcome?: string - /** Exact shared agent/session identity stdin drives. Defaults to `'main'`. */ - sessionId?: string -} - -export const Config: z = z.object({ - welcome: z.string().default('ready.'), - sessionId: z.string().default('main'), -}) - -/** - * Process-I/O seam — the side-effecting handles the plugin would otherwise - * reach for as globals. Defaulted to the real `process` streams in - * {@link apply}; injected by tests so the EOF, render, and disposal branches - * are exercised without hijacking globals. Deliberately NOT part of the - * serializable {@link Config} (streams/functions don't belong in YAML config). - */ -export interface StdioRuntime { - /** Line source (default `process.stdin`). */ - input: Readable - /** Render sink (default `process.stdout`). */ - output: Writable - /** Process-exit hook (default `process.exit`); called once on stdin EOF. */ - exit: (code: number) => void -} - -function isTTYPair(input: Readable, output: Writable): boolean { - return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY) -} - -/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */ -function renderThrown(value: unknown): string { - try { - return String(value) - } catch { - return '' - } -} - -interface PendingQuestion { - request: AskUserQuestionRequest - questionIndex: number - answers: AskUserQuestionAnswerItem[] - resolve(answer: AskUserQuestionAnswer): void - reject(error: unknown): void - onAbort: () => void -} - -type OptionSelection = - | { kind: 'selected'; options: AskUserQuestionOption[] } - | { kind: 'custom' } - | { kind: 'invalid' } - -/** - * The plugin body, parameterized over its I/O runtime. `apply` is the thin - * production wrapper that binds the real `process` streams; tests call this - * directly with fakes. Returns nothing — all registration is via `ctx.on`/ - * `ctx.effect`, so fiber disposal tears every listener and the readline - * interface down. - * @param ctx - the context supplying the `agents` service and the event feeds. - * @param config - the plugin config; defaults are re-applied here for direct - * callers that bypass Loader validation. - * @param runtime - the process-I/O seam (line source, render sink, exit hook). - */ -export function createStdioChat(ctx: Context, config: Config, runtime: StdioRuntime): void { - // Default here too (not just via schemastery's `.default()`): this helper is - // exported and called directly by tests / programmatic consumers that bypass - // Loader validation, so it must be self-contained rather than trusting the - // cast — `config.welcome as string` would otherwise be `undefined` on `{}`. - const welcome = config.welcome ?? 'ready.' - const sessionId = SessionId(config.sessionId ?? 'main') - const { input, output, exit } = runtime - - // Bind only to the exact identity this app passed to its config-created - // agent. Session ids are opaque: neither a prefix nor registry order can - // identify ownership. The root check rejects a child that somehow preempts - // the configured id; later recreation under the same id supports loop HMR. - const matchesConfiguredIdentity = (agent: Agent): boolean => - agent.id === sessionId && ctx.agents.roots().includes(agent) - let target: Agent | undefined = ctx.agents.roots().find(agent => agent.id === sessionId) - - // Transcript rendering off the durable `session/event` feed — the assistant - // token stream, turn/step boundaries, tool activity, and todos all come from - // the one canonical stream (no agent/* mirrors). A single listener over the - // append order keeps `inReasoning` transitions deterministic across chunk and - // boundary events. - let inReasoning = false - ctx.on('session/event', (session, event) => { - if (event.type === 'assistant/chunk') { - const { chunk } = event.data - if (chunk.type === 'reasoning-delta') { - // Dim the chain-of-thought so the final answer stands out. - if (!inReasoning) output.write('\x1B[2m') - inReasoning = true - output.write(chunk.text) - } else if (chunk.type === 'text-delta') { - if (inReasoning) output.write('\x1B[0m\n') - inReasoning = false - output.write(chunk.text) - } - } else if (event.type === 'turn/start') { - const label = target?.session === session ? 'main' : session.id - output.write(`\n[${label} turn ${event.data.turn}] `) - } else if (event.type === 'turn/end') { - if (inReasoning) output.write('\x1B[0m') - inReasoning = false - output.write('\n> ') - } else if (event.type === 'tool/call') { - const { name: toolName, arguments: args } = event.data - if (inReasoning) output.write('\x1B[0m') - inReasoning = false - output.write(`\n [tool call] ${toolName}(${args})`) - } else if (event.type === 'tool/result') { - // A surface replacement changes future model context; it is not another - // execution. Keep the original full-fidelity terminal presentation and - // suppress duplicate output during live delivery or log replay. - if (event.surfaceOp !== undefined && event.surfaceOp !== 'append') return - const { content } = event.data - const text = content.filter(block => block.type === 'text').map(block => block.text).join('') - output.write(`\n [tool result] ${text}\n `) - } else if (event.type === 'todo/write') { - if (inReasoning) output.write('\x1B[0m') - inReasoning = false - const glyph = (status: string): string => - status === 'completed' ? '[x]' : status === 'in_progress' ? '[~]' : '[ ]' - const lines = event.data.todos.map(todo => ` ${glyph(todo.status)} ${todo.content}`).join('\n') - output.write(`\n [todos]\n${lines}\n `) - } - }) - - ctx.effect(() => { - // Piped-input exit, once stdin reaches EOF: - // - If no line ever submitted work (empty stdin, blank-only lines), exit - // immediately — no turn will ever start, so there is nothing to wait - // for. (Gating on an observed 'running' here would hang forever.) - // - If work WAS submitted, exit the next time the agent settles to idle - // AFTER having run. Later lines may steer the active turn, and consecutive - // queued turns can share one running interval, so we don't count inputs; - // agent.send() also does NOT synchronously flip status to - // 'running', so requiring an observed 'running' first (`sawRunning`) - // avoids exiting in the gap before the turn starts and dropping work. - let stdinClosed = false - let disposed = false - let submittedWork = false - let sawRunning = false - let exitTimer: ReturnType | undefined - let activeQuestion: PendingQuestion | undefined - const questionQueue: PendingQuestion[] = [] - const queuedInput: string[] = [] - let targetReady = target !== undefined - let hadReadyTarget = targetReady - let failedStartup: { error: unknown } | undefined - - const submit = (agent: Agent, text: string): void => { - submittedWork = true - if (agent.status === 'running') { - agent.steer([{ type: 'text', text }]) - } else { - agent.send([{ type: 'text', text }]) - } - } - - const disposeCreatedListener = ctx.on('agent/created', (agent) => { - if (!matchesConfiguredIdentity(agent)) return - target = agent - targetReady = false - failedStartup = undefined - }) - const disposeSessionStartListener = ctx.on('agent/session-start', (agent) => { - if (agent !== target) return - targetReady = true - hadReadyTarget = true - for (const text of queuedInput.splice(0)) submit(agent, text) - }) - const disposeDisposedListener = ctx.on('agent/disposed', (agent) => { - if (target !== agent) return - target = undefined - targetReady = false - }) - const reader = createInterface({ input, output, terminal: isTTYPair(input, output) }) - - const maybeExit = (): void => { - if (disposed || !stdinClosed) return - // No work submitted: nothing will ever run, exit straight away. - // Work submitted: wait until a turn has run and the agent is idle. - if (submittedWork) { - if (!sawRunning) return - const agent = target - if (agent && agent.status !== 'idle') return // a turn is still running - } - // Let any final output flush, then exit. The handle is tracked so the - // disposer can cancel it — a dispose within the flush window must not let - // the process exit out from under HMR. Re-entrant `maybeExit` calls (e.g. - // repeated idle signals) coalesce onto the one pending timer. - if (exitTimer !== undefined) { - return // exit already scheduled — coalesce re-entrant calls - } - exitTimer = setTimeout(() => { exit(0) }, 200) - } - - const disposeStartupFailedListener = ctx.on('agent-loop/config-start-failed', (failedSessionId, error) => { - if (failedSessionId !== sessionId || targetReady) return - failedStartup = { error } - const dropped = queuedInput.length - queuedInput.length = 0 - submittedWork = sawRunning - if (dropped > 0) { - ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (${dropped} line(s)): ${renderThrown(error)}`) - } - maybeExit() - }) - - const disposeStatusListener = ctx.on('agent/status', (subject, status) => { - if (subject !== target) return - if (status === 'running') sawRunning = true - if (status === 'idle') maybeExit() - }) - - const activeQuestionItem = (pending: PendingQuestion): AskUserQuestionItem => - pending.request.questions[pending.questionIndex] as AskUserQuestionItem - - const renderQuestion = (pending: PendingQuestion): void => { - const question = activeQuestionItem(pending) - const options = question.options ?? [] - output.write('\n') - output.write(question.header ? `[${question.header}] ${question.question}\n` : `${question.question}\n`) - options.forEach((option, index) => { - output.write(` ${index + 1}. ${option.label}\n`) - if (option.description) output.write(` ${option.description}\n`) - }) - output.write('> ') - } - - const removeAbortListener = (pending: PendingQuestion): void => { - pending.request.signal?.removeEventListener('abort', pending.onAbort) - } - - const startNextQuestion = (): void => { - if (activeQuestion !== undefined) return - const pending = questionQueue.shift() - if (pending === undefined) return - // The queue never contains an aborted pending ask: the seam rejects an - // already-aborted request synchronously, and queued asks attach their - // abort listener before enqueueing. - activeQuestion = pending - renderQuestion(pending) - } - - const disposeQuestion = (pending: PendingQuestion): void => { - removeAbortListener(pending) - pending.reject(new UserInteractionError('ask_user_question was interrupted before the user answered', 'ASK_ABORTED')) - } - - const disposePendingQuestions = (): void => { - if (activeQuestion !== undefined) { - disposeQuestion(activeQuestion) - activeQuestion = undefined - } - for (const pending of questionQueue.splice(0)) { - disposeQuestion(pending) - } - } - - const finishQuestion = (pending: PendingQuestion): void => { - activeQuestion = undefined - removeAbortListener(pending) - pending.resolve({ answers: pending.answers }) - output.write('\n') - startNextQuestion() - } - - const answerCurrentQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswerItem): void => { - pending.answers.push(answer) - pending.questionIndex += 1 - if (pending.questionIndex >= pending.request.questions.length) { - finishQuestion(pending) - return - } - renderQuestion(pending) - } - - const selectedOptions = (text: string, options: AskUserQuestionOption[], multiSelect: boolean): OptionSelection => { - if (text === '') return { kind: 'invalid' } - if (!multiSelect) { - if (!/^\d+$/.test(text)) return { kind: 'custom' } - const selected = options[Number(text) - 1] - return selected === undefined ? { kind: 'invalid' } : { kind: 'selected', options: [selected] } - } - const indices = text.split(/[,\s]+/).filter(Boolean) - if (indices.length === 0) return { kind: 'invalid' } - if (indices.some(part => !/^\d+$/.test(part))) return { kind: 'custom' } - const uniqueIndices = [...new Set(indices)] - const selected = uniqueIndices.map(part => options[Number(part) - 1]) - return selected.some(option => option === undefined) - ? { kind: 'invalid' } - : { kind: 'selected', options: selected as AskUserQuestionOption[] } - } - - const answerQuestion = (line: string): void => { - const pending = activeQuestion as PendingQuestion - const question = activeQuestionItem(pending) - - const text = line.trim() - const options = question.options ?? [] - const selection = options.length > 0 - ? selectedOptions(text, options, question.multiSelect ?? false) - : { kind: text === '' ? 'invalid' : 'custom' } as OptionSelection - if (selection.kind === 'selected') { - answerCurrentQuestion(pending, { id: question.id, selected: selection.options.map(option => option.label) }) - return - } - - if (selection.kind === 'custom' && text !== '') { - answerCurrentQuestion(pending, { id: question.id, selected: [], custom: text }) - return - } - - output.write(options.length > 0 - ? 'Please enter one of the option numbers' - + (question.multiSelect ? ' (comma or space separated)' : '') - + ' or a custom answer' - + '.\n> ' - : 'Please enter an answer.\n> ') - } - - const disposeUserInteractionProvider = ctx.userInteraction.registerProvider({ - ask(request) { - if (disposed || stdinClosed) { - return Promise.reject( - new UserInteractionError('ask_user_question cannot be answered because stdin is closed', 'ASK_ABORTED'), - ) - } - return new Promise((resolve, reject) => { - const pending: PendingQuestion = { - request, - questionIndex: 0, - answers: [], - resolve, - reject, - onAbort: () => { - if (activeQuestion === pending) { - activeQuestion = undefined - disposeQuestion(pending) - startNextQuestion() - return - } - // If it is not active, this listener can only fire while the ask - // remains queued; settled asks remove the listener first. - questionQueue.splice(questionQueue.indexOf(pending), 1) - disposeQuestion(pending) - }, - } - request.signal?.addEventListener('abort', pending.onAbort, { once: true }) - questionQueue.push(pending) - startNextQuestion() - }) - }, - }) - - reader.on('line', (line) => { - if (activeQuestion !== undefined) { - answerQuestion(line) - return - } - const text = line.trim() - if (!text) return - if (failedStartup !== undefined) { - ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ${renderThrown(failedStartup.error)}`) - return - } - const agent = target - if (agent === undefined || !targetReady) { - // Initial exact-id restoration is asynchronous. Preserve input until - // session-start, the first supported point for queueing agent work. - // After a previously ready target disappears, a line in the HMR gap - // still fails loud unless its exact replacement is already publishing. - if (!hadReadyTarget || agent !== undefined) { - submittedWork = true - queuedInput.push(text) - return - } - ctx.logger.error('ui-stdio: main agent is not running') - return - } - submit(agent, text) - }) - reader.on('close', () => { - // Fires for BOTH stdin EOF and plugin disposal (reader.close() below); - // `disposed` guards teardown so HMR/dispose never exits the process. - stdinClosed = true - if (!disposed) disposePendingQuestions() - maybeExit() - }) - output.write(`${welcome}\n> `) - return () => { - disposed = true - if (exitTimer !== undefined) clearTimeout(exitTimer) - disposePendingQuestions() - disposeUserInteractionProvider() - disposeStatusListener() - disposeCreatedListener() - disposeSessionStartListener() - disposeDisposedListener() - disposeStartupFailedListener() - reader.close() - } - }, 'ui-stdio') -} - -/** - * Open the terminal channel for one exact identity. The chat registers before - * that agent necessarily exists so it can buffer startup input and observe a - * config-start failure instead of leaving piped stdin hanging. - * @param ctx - the context supplying the agent registry and event stream. - * @param config - presentation and target-agent configuration. - * @param runtime - process-I/O seam. - */ -export function mountStdio(ctx: Context, config: Config, runtime: StdioRuntime): void { - createStdioChat(ctx, config, runtime) -} - -/** - * Cordis entry point. Binds the real `process` streams and delegates to - * {@link mountStdio}; the indirection keeps the side-effecting handles out - * of the testable core, which is why the unit suite drives `createStdioChat` - * directly. This thin wrapper is exercised end-to-end by the keyless - * Loader-path e2e smoke in `examples/echo-agent` (the real product entry). - */ -/* v8 ignore start -- production stdio wiring; testable core is createStdioChat() (covered), exercised e2e by echo-agent keyless smoke */ -export function apply(ctx: Context, config: Config): void { - mountStdio(ctx, config, { - input: process.stdin, - output: process.stdout, - exit: code => process.exit(code), - }) -} -/* v8 ignore stop */ diff --git a/packages/ui/stdio/tests/plugin-shape.spec.ts b/packages/ui/stdio/tests/plugin-shape.spec.ts deleted file mode 100644 index 5b2b35f65e..0000000000 --- a/packages/ui/stdio/tests/plugin-shape.spec.ts +++ /dev/null @@ -1,19 +0,0 @@ -import { describe, expect, it } from 'vitest' -import Loader from '@cordisjs/plugin-loader' -import * as stdio from '../src/index.ts' - -/** Real Loader export-path guard for the namespace stdio plugin. */ -describe('dsh-stdio plugin export shape', () => { - it('preserves name, inject, Config, and apply through Loader unwrapping', () => { - expect('default' in stdio).toBe(false) - expect(typeof stdio.apply).toBe('function') - - const loader = Object.create(Loader.prototype) as Loader - const unwrapped = loader.unwrapExports(stdio) as Record - expect(unwrapped).toBe(stdio) - expect(unwrapped.name).toBe('ui-stdio') - expect(unwrapped.inject).toEqual(['agents', 'userInteraction']) - expect(unwrapped.Config).toBeDefined() - expect(typeof unwrapped.apply).toBe('function') - }) -}) diff --git a/packages/ui/stdio/tests/readline.spec.ts b/packages/ui/stdio/tests/readline.spec.ts deleted file mode 100644 index 6a97eab06a..0000000000 --- a/packages/ui/stdio/tests/readline.spec.ts +++ /dev/null @@ -1,54 +0,0 @@ -import { EventEmitter } from 'node:events' -import type { Readable, Writable } from 'node:stream' -import { describe, expect, it, vi } from 'vitest' -import type { Context } from 'cordis' -import type { StdioRuntime } from '../src/index.ts' - -const createInterface = vi.hoisted(() => vi.fn(() => { - const reader = new EventEmitter() as EventEmitter & { close(): void } - reader.close = vi.fn() - return reader -})) - -vi.mock('node:readline', () => ({ createInterface })) - -function fakeContext(): Context { - return { - on: vi.fn(() => vi.fn()), - effect: vi.fn((callback: () => () => void) => callback()), - // The UI seeds its root target from the registry at install; this suite only - // exercises readline terminal-mode selection, so an empty roster suffices. - agents: { roots: vi.fn(() => []) }, - userInteraction: { registerProvider: vi.fn(() => vi.fn()) }, - } as unknown as Context -} - -function fakeRuntime(inputIsTTY: boolean, outputIsTTY: boolean): StdioRuntime { - return { - input: { isTTY: inputIsTTY } as Readable & { isTTY: boolean }, - output: { isTTY: outputIsTTY, write: vi.fn(() => true) } as unknown as Writable & { isTTY: boolean }, - exit: vi.fn(), - } -} - -describe('createStdioChat readline mode', () => { - it('enables terminal editing only when both stdio streams are TTYs', async () => { - const { createStdioChat } = await import('../src/index.ts') - - const tty = fakeRuntime(true, true) - createStdioChat(fakeContext(), {}, tty) - expect(createInterface).toHaveBeenLastCalledWith({ - input: tty.input, - output: tty.output, - terminal: true, - }) - - const piped = fakeRuntime(true, false) - createStdioChat(fakeContext(), {}, piped) - expect(createInterface).toHaveBeenLastCalledWith({ - input: piped.input, - output: piped.output, - terminal: false, - }) - }) -}) diff --git a/packages/ui/stdio/tests/stdio.spec.ts b/packages/ui/stdio/tests/stdio.spec.ts deleted file mode 100644 index 478914849c..0000000000 --- a/packages/ui/stdio/tests/stdio.spec.ts +++ /dev/null @@ -1,1044 +0,0 @@ -import { Readable, Writable } from 'node:stream' -import { describe, expect, it, vi } from 'vitest' -import { Context } from 'cordis' -import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' -import AgentRegistry from '@deepseek-ai/dsh-agent' -import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm' -import { SessionId, type Session, type SessionEvent } from '@deepseek-ai/dsh-session' -import UserInteractionService from '@deepseek-ai/dsh-user-interaction' -import { createStdioChat, mountStdio, type Config, type StdioRuntime } from '../src/index.ts' - -/** - * Unit tests for the stdio UI plugin. They drive the REAL plugin body - * (`createStdioChat`) with an injected {@link StdioRuntime} so every render, - * input, EOF, and disposal branch runs without touching the real `process` - * streams — the I/O seam is what makes the per-file gate reachable. The - * `agents` service is real (`@deepseek-ai/dsh-agent`); a minimal fake `Agent` - * stands in for the loop, since the loop is the genuinely expensive collaborator - * and we only need its `status` + `send`/`steer` surface here. - */ - -/** A controllable stdin: a Readable we push lines into and can end on demand. */ -function makeInput(): Readable & { feed(line: string): void; finish(): void } { - const stream = new Readable({ read() {} }) as Readable & { feed(line: string): void; finish(): void } - stream.feed = (line: string) => stream.push(`${line}\n`) - stream.finish = () => stream.push(null) - return stream -} - -/** A stdout sink that accumulates everything written, for assertions. */ -function makeOutput(): { write: (s: string) => boolean; text: () => string } { - let buf = '' - return { write: (s: string) => { buf += s; return true }, text: () => buf } -} - -function makeRuntime(over: Partial = {}): { - runtime: StdioRuntime - input: ReturnType - out: ReturnType - exit: ReturnType -} { - const input = makeInput() - const out = makeOutput() - const exit = vi.fn() - return { runtime: { input, output: { write: out.write } as never, exit, ...over }, input, out, exit } -} - -/** A minimal Agent fake exposing the surface the UI touches. */ -function makeAgent(id: string, status: AgentStatus = 'idle'): Agent & { - status: AgentStatus - sent: ContentBlock[][] - steered: ContentBlock[][] -} { - const sent: ContentBlock[][] = [] - const steered: ContentBlock[][] = [] - return { - id: id as Agent['id'], - status, - sent, - steered, - // A minimal session stub with the agent's shared durable identity. - session: { id, header: { id } }, - send: (content: ContentBlock[]) => void sent.push(content), - steer: (content: ContentBlock[]) => void steered.push(content), - } as never -} - -/** Register a fake configured agent and cross the supported startup-work boundary. */ -function registerReady(ctx: Context, agent: Agent, source: 'startup' | 'resume' = 'startup'): () => void { - const dispose = ctx.agents.register(agent) - ctx.emit('agent/session-start', agent, source) - return dispose -} - -/** A session stub whose `header.id` matches an agent's, for `session/event` emits. */ -function makeSession(id: string): Session { - return { id, header: { id } } as Session -} - -/** An `assistant/chunk` session event carrying one raw stream chunk. */ -function chunkEvent(chunk: StreamChunk): SessionEvent { - return { type: 'assistant/chunk', seq: 0, time: 0, data: { turn: 1, step: 0, chunk } } -} - -const CONFIG: Config = { welcome: 'hi there', sessionId: 'main' } - -function unrenderableFailure(): unknown { - return { [Symbol.toPrimitive](): never { throw new Error('coercion escaped') } } -} - -async function setup(config: Config = CONFIG, runtimeOver: Partial = {}) { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(UserInteractionService) - const { runtime, input, out, exit } = makeRuntime(runtimeOver) - const fiber = await ctx.plugin(Object.assign((inner: Context) => { - createStdioChat(inner, config, runtime) - }, { inject: ['agents', 'userInteraction'] })) - return { ctx, fiber, input, out, exit } -} - -/** Drive a fake idle timer past the 200ms flush delay. */ -function flushExit(): Promise { - return new Promise(resolve => setTimeout(resolve, 250)) -} - -describe('mountStdio readiness', () => { - it('opens before the configured agent is created so startup input can queue', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(UserInteractionService) - const { runtime, out } = makeRuntime() - const fiber = await ctx.plugin(Object.assign((inner: Context) => { - mountStdio(inner, CONFIG, runtime) - }, { inject: ['agents', 'userInteraction'] })) - - expect(out.text()).toBe('hi there\n> ') - ctx.agents.register(makeAgent('other')) - expect(out.text()).toBe('hi there\n> ') - ctx.agents.register(makeAgent('main')) - expect(out.text()).toBe('hi there\n> ') - await fiber.dispose() - }) - - it('opens immediately when the configured agent already exists', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(UserInteractionService) - ctx.agents.register(makeAgent('main')) - const { runtime, out } = makeRuntime() - const fiber = await ctx.plugin(Object.assign((inner: Context) => { - mountStdio(inner, CONFIG, runtime) - }, { inject: ['agents', 'userInteraction'] })) - - expect(out.text()).toBe('hi there\n> ') - await fiber.dispose() - }) - - it('opens for the default main identity when no target is configured', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(UserInteractionService) - const { runtime, out } = makeRuntime() - const fiber = await ctx.plugin(Object.assign((inner: Context) => { - mountStdio(inner, { welcome: 'ready' }, runtime) - }, { inject: ['agents', 'userInteraction'] })) - - expect(out.text()).toBe('ready\n> ') - ctx.agents.register(makeAgent('other')) - expect(out.text()).toBe('ready\n> ') - ctx.agents.register(makeAgent('main')) - expect(out.text()).toBe('ready\n> ') - await fiber.dispose() - }) -}) - -describe('createStdioChat rendering', () => { - it('writes the welcome banner and prompt on start', async () => { - const { out } = await setup() - expect(out.text()).toBe('hi there\n> ') - }) - - it('falls back to the default welcome when called with empty config', async () => { - // createStdioChat is exported and may be driven directly (bypassing the - // Loader's schemastery validation), so it must default the welcome itself. - const { out } = await setup({}) - expect(out.text()).toBe('ready.\n> ') - }) - - it('detects readline terminal mode from both stream TTY flags', async () => { - for (const [inputTTY, outputTTY] of [[true, false], [true, true]] as const) { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(UserInteractionService) - let text = '' - const output = new Writable({ - write(chunk, _encoding, callback) { - text += String(chunk) - callback() - }, - }) as Writable & { isTTY?: boolean } - const { runtime } = makeRuntime({ output }) - ;(runtime.input as Readable & { isTTY?: boolean }).isTTY = inputTTY - output.isTTY = outputTTY - const fiber = await ctx.plugin(Object.assign((inner: Context) => { - createStdioChat(inner, CONFIG, runtime) - }, { inject: ['agents', 'userInteraction'] })) - - expect(text).toContain('hi there') - await fiber.dispose() - } - }) - - it('renders text-delta chunks verbatim', async () => { - const { ctx, out } = await setup() - ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' })) - expect(out.text()).toContain('hello') - }) - - it('wraps reasoning-delta in the dim SGR and resets on the following text-delta', async () => { - const { ctx, out } = await setup() - const session = makeSession('main') - ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'think' })) - ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'more' })) - ctx.emit('session/event', session, chunkEvent({ type: 'text-delta', index: 0, text: 'answer' })) - expect(out.text()).toContain('\x1B[2mthinkmore\x1B[0m\nanswer') - }) - - it('ignores stream-chunk types it does not render', async () => { - const { ctx, out } = await setup() - const before = out.text() - ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'block-start', index: 0, blockType: 'text' })) - expect(out.text()).toBe(before) - }) - - it('renders turn/start and turn/end markers from the session feed', async () => { - const { ctx, out } = await setup() - const agent = makeAgent('main') - ctx.agents.register(agent) - const session = agent.session - ctx.emit('session/event', session, { - type: 'turn/start', seq: 1, time: 0, data: { turn: 3, trigger: { kind: 'message' } }, - } as SessionEvent) - expect(out.text()).toContain('[main turn 3] ') - ctx.emit('session/event', session, { - type: 'turn/end', seq: 2, time: 0, data: { turn: 3, reason: { kind: 'completed' } }, - } as SessionEvent) - expect(out.text()).toContain('\n> ') - }) - - it('uses the session id as the label for a non-target session', async () => { - const { ctx, out } = await setup() - // No target exists, so the event's durable identity is the label. - ctx.emit('session/event', makeSession('orphan'), { - type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } }, - } as SessionEvent) - expect(out.text()).toContain('[orphan turn 1] ') - }) - - it('uses an agent already registered before the UI installs as its target', async () => { - // The pre-created `main` agent (and any agent surviving an HMR reload of just - // this fiber) fired its `agent/created` before the UI's listener existed, so - // the live listener alone would miss it. Seeding from `ctx.agents.list()` at - // install time preserves the terminal's fixed `[main turn N]` label. - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(UserInteractionService) - const agent = makeAgent('main') - // Durable lineage does not imply runtime child ownership: the stdio app - // may explicitly resume a persisted fork as its one configured agent. - ;(agent.session.header as { parentSession?: string }).parentSession = 'persisted-parent' - ctx.agents.register(agent) // registered BEFORE the UI plugin below - const { runtime, out } = makeRuntime() - await ctx.plugin(Object.assign((inner: Context) => { - createStdioChat(inner, CONFIG, runtime) - }, { inject: ['agents', 'userInteraction'] })) - ctx.emit('session/event', agent.session, { - type: 'turn/start', seq: 1, time: 0, data: { turn: 5, trigger: { kind: 'message' } }, - } as SessionEvent) - expect(out.text()).toContain('[main turn 5] ') - }) - - it('buffers input for a lineage-bearing configured agent until its session starts', async () => { - const { ctx, input } = await setup({ welcome: 'hi there', sessionId: 'resumed' }) - input.feed('continue') - await new Promise(resolve => setImmediate(resolve)) - - const unrelated = makeAgent('unrelated') - ctx.agents.register(unrelated) - ctx.emit('agent/session-start', unrelated, 'startup') - const resumed = makeAgent('resumed') - ;(resumed.session.header as { parentSession?: string }).parentSession = 'persisted-parent' - ctx.agents.register(resumed) - await new Promise(resolve => setImmediate(resolve)) - expect(resumed.sent).toEqual([]) - - ctx.emit('agent/session-start', resumed, 'resume') - await new Promise(resolve => setImmediate(resolve)) - - expect(unrelated.sent).toEqual([]) - expect(resumed.sent).toEqual([[{ type: 'text', text: 'continue' }]]) - }) - - it('resets dim styling at turn/end if a turn ends mid-reasoning', async () => { - const { ctx, out } = await setup() - const session = makeSession('main') - ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'mid' })) - ctx.emit('session/event', session, { - type: 'turn/end', seq: 1, time: 0, data: { turn: 1, reason: { kind: 'completed' } }, - } as SessionEvent) - expect(out.text()).toContain('\x1B[2mmid\x1B[0m') - }) - - it('drops the target object on agent/disposed', async () => { - const { ctx, out } = await setup() - const agent = makeAgent('main') - const dispose = ctx.agents.register(agent) - dispose() - // After disposal the event belongs to a non-target session, so its durable - // identity is rendered directly. - ctx.emit('session/event', agent.session, { - type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } }, - } as SessionEvent) - expect(out.text()).toContain('[main turn 1] ') - }) - - it('keeps the target when a different agent is disposed', async () => { - const { ctx, out } = await setup() - const target = makeAgent('main') - ctx.agents.register(target) - ctx.emit('agent/disposed', makeAgent('other')) - ctx.emit('session/event', target.session, { - type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } }, - } as SessionEvent) - expect(out.text()).toContain('[main turn 1] ') - }) - - it('retargets only the exact identity after loop HMR recreation', async () => { - const { ctx, input } = await setup({ welcome: 'hi there', sessionId: 'main-session-fixed' }) - const oldRoot = makeAgent('main-session-fixed') - const prefixCollision = makeAgent('main-session-unrelated') - const disposeOld = ctx.agents.register(oldRoot) - ctx.agents.register(prefixCollision) - disposeOld() - const replacement = makeAgent('main-session-fixed') - ctx.agents.register(replacement) - input.feed('after hmr') - await new Promise(resolve => setImmediate(resolve)) - expect(replacement.sent).toEqual([]) - ctx.emit('agent/session-start', replacement, 'resume') - await new Promise(resolve => setImmediate(resolve)) - - expect(prefixCollision.sent).toEqual([]) - expect(replacement.sent).toEqual([[{ type: 'text', text: 'after hmr' }]]) - }) - - it('does not retarget stdin to an unrelated root after the configured agent is disposed', async () => { - const { ctx, input } = await setup() - const unrelated = makeAgent('unrelated') - ctx.agents.register(unrelated) - const configured = makeAgent('main') - const disposeConfigured = registerReady(ctx, configured) - const error = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {}) - - disposeConfigured() - input.feed('must not leak') - await new Promise(resolve => setImmediate(resolve)) - - expect(unrelated.sent).toEqual([]) - expect(error).toHaveBeenCalledWith('ui-stdio: main agent is not running') - }) - - it('renders tool/call and tool/result session events', async () => { - const { ctx, out } = await setup() - const session = {} as Session - const callEvent = { - type: 'tool/call', seq: 1, time: 0, - data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{"command":"ls"}' }, - } as SessionEvent - ctx.emit('session/event', session, callEvent) - expect(out.text()).toContain('[tool call] bash({"command":"ls"})') - - const resultEvent = { - type: 'tool/result', seq: 2, time: 0, - data: { turn: 1, step: 0, callId: 'c1', content: [{ type: 'text', text: 'file.txt' }], isError: false }, - } as SessionEvent - ctx.emit('session/event', session, resultEvent) - expect(out.text()).toContain('[tool result] file.txt') - }) - - it('renders one full-fidelity result whether the event feed is live or replayed', async () => { - const { ctx, out } = await setup() - const session = makeSession('main') - const original = { - type: 'tool/result', - seq: 2, - time: 0, - data: { - turn: 1, - step: 1, - callId: 'c1', - content: [{ type: 'text', text: 'full terminal output' }], - isError: false, - meta: { terminal: { output: 'full terminal output' } }, - }, - surfaceOp: 'append', - } as SessionEvent - const replacement = { - ...original, - seq: 3, - data: { - ...original.data, - content: [{ type: 'text', text: '[... tool result middle pruned ...]' }], - }, - surfaceOp: { op: 'replace', start: 2, end: 2 }, - sourceEventSeqs: [2], - } as SessionEvent - - // Stdio consumes the same session/event shape whether a host forwards a - // live append or replays a stored log through the rendering feed. - for (const event of [original, replacement]) ctx.emit('session/event', session, event) - - expect(out.text().match(/\[tool result\]/g)).toHaveLength(1) - expect(out.text()).toContain('full terminal output') - expect(out.text()).not.toContain('tool result middle pruned') - }) - - it('renders a todo/write session event as a glyphed checklist', async () => { - const { ctx, out } = await setup() - const session = {} as Session - ctx.emit('session/event', session, { - type: 'todo/write', seq: 1, time: 0, - data: { todos: [ - { content: 'read the code', status: 'completed' }, - { content: 'write the fix', status: 'in_progress' }, - { content: 'run the tests', status: 'pending' }, - ] }, - } as SessionEvent) - const text = out.text() - expect(text).toContain('[todos]') - expect(text).toContain('[x] read the code') - expect(text).toContain('[~] write the fix') - expect(text).toContain('[ ] run the tests') - }) - - it('resets dim styling when a todo/write interrupts reasoning', async () => { - const { ctx, out } = await setup() - ctx.emit('session/event', {} as Session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' })) - ctx.emit('session/event', {} as Session, { - type: 'todo/write', seq: 1, time: 0, - data: { todos: [{ content: 'a task', status: 'pending' }] }, - } as SessionEvent) - expect(out.text()).toContain('\x1B[2mr\x1B[0m') - }) - - it('resets dim styling when a tool/call interrupts reasoning', async () => { - const { ctx, out } = await setup() - const session = {} as Session - ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' })) - ctx.emit('session/event', session, { - type: 'tool/call', seq: 1, time: 0, - data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{}' }, - } as SessionEvent) - expect(out.text()).toContain('\x1B[2mr\x1B[0m') - }) - - it('ignores session events it does not render', async () => { - const { ctx, out } = await setup() - const before = out.text() - ctx.emit('session/event', {} as Session, { - type: 'user/message', seq: 1, time: 0, - data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, - } as SessionEvent) - expect(out.text()).toBe(before) - }) -}) - -describe('createStdioChat input', () => { - it('answers a pending user question instead of sending the line to the agent', async () => { - const { ctx, input, out } = await setup() - const agent = makeAgent('main', 'idle') - ctx.agents.register(agent) - - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'confirm', - header: 'Confirm', - question: 'Proceed with the edit?', - options: [{ label: 'Yes', description: 'Apply the edit now.' }], - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('Use a smaller change') - - await expect(answer).resolves.toEqual({ answers: [{ id: 'confirm', selected: [], custom: 'Use a smaller change' }] }) - expect(agent.sent).toEqual([]) - expect(out.text()).toContain('[Confirm] Proceed with the edit?') - expect(out.text()).toContain('1. Yes') - expect(out.text()).toContain('Apply the edit now.') - }) - - it('answers a pending user question by numeric option selection', async () => { - const { ctx, input } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'mode', - question: 'Which mode?', - options: [ - { label: 'Safe' }, - { label: 'Fast' }, - ], - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('2') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'mode', selected: ['Fast'] }], - }) - }) - - it('renders options in input order and selects by displayed number', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'topic', - question: 'Which topic?', - options: [ - { label: 'Hobbies' }, - { label: 'Work', description: 'Questions about current projects.' }, - { label: 'Casual', description: 'Easy conversation.' }, - ], - }], - }) - await new Promise(r => setImmediate(r)) - - expect(out.text()).toContain([ - 'Which topic?', - ' 1. Hobbies', - ' 2. Work', - ' Questions about current projects.', - ' 3. Casual', - ' Easy conversation.', - ].join('\n')) - input.feed('3') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'topic', selected: ['Casual'] }], - }) - }) - - it('answers a multi-select question with multiple numeric selections', async () => { - const { ctx, input } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'targets', - question: 'What should I update?', - options: [{ label: 'Tests' }, { label: 'Docs' }, { label: 'Code' }], - multiSelect: true, - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('1 1, 3') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'targets', selected: ['Tests', 'Code'] }], - }) - }) - - it('accepts non-numeric multi-select input as a custom answer', async () => { - const { ctx, input } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'targets', - question: 'What should I update?', - options: [{ label: 'Tests' }, { label: 'Docs' }], - multiSelect: true, - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('the release notes') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'targets', selected: [], custom: 'the release notes' }], - }) - }) - - it('asks every question in a batch and returns answers by id', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [ - { id: 'language', question: 'Which language?', options: [{ label: 'Python' }, { label: 'TypeScript' }] }, - { id: 'note', question: 'Any note?' }, - ], - }) - await new Promise(r => setImmediate(r)) - input.feed('2') - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('\nAny note?\n') - input.feed('ship today') - - await expect(answer).resolves.toEqual({ - answers: [ - { id: 'language', selected: ['TypeScript'] }, - { id: 'note', selected: [], custom: 'ship today' }, - ], - }) - }) - - it('re-prompts when option input is invalid', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'mode', - question: 'Which mode?', - options: [{ label: 'Safe' }], - multiSelect: true, - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('2') - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.') - input.feed('1') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'mode', selected: ['Safe'] }], - }) - }) - - it('re-prompts when single-select option input is out of range', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'mode', - question: 'Which mode?', - options: [{ label: 'Safe' }], - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('2') - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.') - input.feed('1') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'mode', selected: ['Safe'] }], - }) - }) - - it('re-prompts when multi-select input contains no option numbers', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'mode', - question: 'Which mode?', - options: [{ label: 'Safe' }], - multiSelect: true, - }], - }) - await new Promise(r => setImmediate(r)) - input.feed(',') - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.') - input.feed('1') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'mode', selected: ['Safe'] }], - }) - }) - - it('re-prompts when an option question receives an empty answer', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ - questions: [{ - id: 'mode', - question: 'Which mode?', - options: [{ label: 'Safe' }], - }], - }) - await new Promise(r => setImmediate(r)) - input.feed('') - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.') - input.feed('1') - - await expect(answer).resolves.toEqual({ - answers: [{ id: 'mode', selected: ['Safe'] }], - }) - }) - - it('re-prompts when a question receives an empty answer', async () => { - const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ questions: [{ id: 'path', question: 'What should I use?' }] }) - await new Promise(r => setImmediate(r)) - input.feed('') - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('Please enter an answer.') - input.feed('Use defaults') - - await expect(answer).resolves.toEqual({ answers: [{ id: 'path', selected: [], custom: 'Use defaults' }] }) - }) - - it('rejects an active question when its signal aborts', async () => { - const { ctx } = await setup() - const controller = new AbortController() - const answer = ctx.userInteraction.ask({ questions: [{ id: 'continue', question: 'Continue?' }], signal: controller.signal }) - const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - await new Promise(r => setImmediate(r)) - - controller.abort() - - await rejected - }) - - it('continues to the next queued question when the active question aborts', async () => { - const { ctx, input, out } = await setup() - const controller = new AbortController() - const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }], signal: controller.signal }) - const firstRejected = expect(first).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }] }) - await new Promise(r => setImmediate(r)) - - controller.abort() - await firstRejected - await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('\nSecond?\n') - input.feed('second answer') - - await expect(second).resolves.toEqual({ answers: [{ id: 'second', selected: [], custom: 'second answer' }] }) - }) - - it('skips a queued question whose signal aborted before it became active', async () => { - const { ctx, input, out } = await setup() - const controller = new AbortController() - const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] }) - const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal }) - await new Promise(r => setImmediate(r)) - - controller.abort() - - await expect(Promise.race([ - second.then( - () => 'resolved', - (error: unknown) => (error as { code?: string }).code, - ), - new Promise((resolve) => { setImmediate(() => { resolve('pending') }) }), - ])).resolves.toBe('ASK_ABORTED') - expect(out.text()).not.toContain('\nSecond?\n') - input.feed('first answer') - await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] }) - }) - - it('removes an aborted queued question without promoting later queued work early', async () => { - const { ctx, input, out } = await setup() - const controller = new AbortController() - const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] }) - const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal }) - const third = ctx.userInteraction.ask({ questions: [{ id: 'third', question: 'Third?' }] }) - await new Promise(r => setImmediate(r)) - - controller.abort() - - await expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - expect(out.text()).toContain('\nFirst?\n') - expect(out.text()).not.toContain('\nSecond?\n') - expect(out.text()).not.toContain('\nThird?\n') - input.feed('first answer') - await new Promise(r => setImmediate(r)) - - expect(out.text()).toContain('\nThird?\n') - input.feed('third answer') - - await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] }) - await expect(third).resolves.toEqual({ answers: [{ id: 'third', selected: [], custom: 'third answer' }] }) - }) - - it('rejects active and queued questions when the UI is disposed', async () => { - const { ctx, fiber } = await setup() - const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] }) - const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] }) - const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - await new Promise(r => setImmediate(r)) - - await fiber.dispose() - - await activeRejected - await queuedRejected - }) - - it('rejects active and queued questions when stdin closes before the user answers', async () => { - const { ctx, input, exit } = await setup() - const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] }) - const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] }) - const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - await new Promise(r => setImmediate(r)) - - input.finish() - await new Promise(r => setImmediate(r)) - - await activeRejected - await queuedRejected - expect(exit).not.toHaveBeenCalled() - }) - - it('rejects new questions immediately after stdin has closed', async () => { - const { ctx, input, out } = await setup() - input.finish() - await new Promise(r => setImmediate(r)) - const before = out.text() - - const answer = ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Too late?' }] }) - - await expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - expect(out.text()).toBe(before) - }) - - it('sends a typed line to an idle agent', async () => { - const { ctx, input } = await setup() - const agent = makeAgent('main', 'idle') - registerReady(ctx, agent) - input.feed('do a thing') - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([[{ type: 'text', text: 'do a thing' }]]) - expect(agent.steered).toEqual([]) - }) - - it('steers a typed line into a running agent', async () => { - const { ctx, input } = await setup() - const agent = makeAgent('main', 'running') - registerReady(ctx, agent) - input.feed('steer me') - await new Promise(r => setImmediate(r)) - expect(agent.steered).toEqual([[{ type: 'text', text: 'steer me' }]]) - expect(agent.sent).toEqual([]) - }) - - it('ignores blank lines', async () => { - const { ctx, input } = await setup() - const agent = makeAgent('main') - ctx.agents.register(agent) - input.feed(' ') - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([]) - }) - - it('buffers a line until the initial target session starts', async () => { - const { ctx, input } = await setup() - const spy = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {}) - input.feed('nobody home') - await new Promise(r => setImmediate(r)) - expect(spy).not.toHaveBeenCalled() - - const agent = makeAgent('main') - ctx.agents.register(agent) - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([]) - ctx.emit('agent/session-start', agent, 'startup') - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([[{ type: 'text', text: 'nobody home' }]]) - }) - - it('drops later input after the configured startup fails', async () => { - const { ctx, input } = await setup() - const error = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {}) - const failure = unrenderableFailure() - ctx.emit('agent-loop/config-start-failed', SessionId('main'), failure) - - input.feed('cannot run') - await new Promise(r => setImmediate(r)) - - expect(error).toHaveBeenCalledWith( - 'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ', - ) - }) - - it('ignores a stale config-start failure after the exact target is ready', async () => { - const { ctx, input } = await setup() - const agent = makeAgent('main') - registerReady(ctx, agent) - ctx.emit('agent-loop/config-start-failed', SessionId('main'), new Error('stale')) - - input.feed('still live') - await new Promise(r => setImmediate(r)) - - expect(agent.sent).toEqual([[{ type: 'text', text: 'still live' }]]) - }) - - it('drives the exact app-configured resumed session', async () => { - const { ctx, input } = await setup({ welcome: 'w', sessionId: 'worker' }) - const agent = makeAgent('worker') - registerReady(ctx, agent, 'resume') - input.feed('hi') - await new Promise(r => setImmediate(r)) - expect(agent.sent).toHaveLength(1) - }) - -}) - -describe('createStdioChat EOF exit', () => { - it('exits immediately on EOF when no work was submitted', async () => { - const { input, exit } = await setup() - input.finish() - await flushExit() - expect(exit).toHaveBeenCalledWith(0) - }) - - it('waits for the agent to settle idle after running before exiting', async () => { - const { ctx, input, exit } = await setup() - const agent = makeAgent('main', 'idle') - registerReady(ctx, agent) - input.feed('work') - await new Promise(r => setImmediate(r)) - input.finish() - await new Promise(r => setImmediate(r)) - // Work submitted but no 'running' observed yet — must NOT exit. - expect(exit).not.toHaveBeenCalled() - // The turn starts, then settles. - ctx.emit('agent/status', agent, 'running') - ;(agent as { status: AgentStatus }).status = 'idle' - ctx.emit('agent/status', agent, 'idle') - await flushExit() - expect(exit).toHaveBeenCalledWith(0) - }) - - it('keeps piped EOF pending until buffered startup input runs', async () => { - const { ctx, input, exit } = await setup() - input.feed('work') - input.finish() - await flushExit() - expect(exit).not.toHaveBeenCalled() - - const agent = makeAgent('main', 'idle') - ctx.agents.register(agent) - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([]) - ctx.emit('agent/session-start', agent, 'startup') - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([[{ type: 'text', text: 'work' }]]) - ctx.emit('agent/status', agent, 'running') - ;(agent as { status: AgentStatus }).status = 'idle' - ctx.emit('agent/status', agent, 'idle') - await flushExit() - expect(exit).toHaveBeenCalledWith(0) - }) - - it('drains buffered piped input and exits when configured startup fails', async () => { - const { ctx, input, exit } = await setup() - const error = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {}) - input.feed('work') - input.finish() - await new Promise(r => setImmediate(r)) - ctx.emit('agent-loop/config-start-failed', SessionId('other'), new Error('unrelated')) - await flushExit() - expect(exit).not.toHaveBeenCalled() - - ctx.emit('agent-loop/config-start-failed', SessionId('main'), unrenderableFailure()) - await flushExit() - - expect(error).toHaveBeenCalledWith( - 'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ', - ) - expect(exit).toHaveBeenCalledWith(0) - }) - - it('schedules the exit only once when idle fires repeatedly', async () => { - const { ctx, input, exit } = await setup() - const agent = makeAgent('main', 'running') - registerReady(ctx, agent) - input.feed('work') - await new Promise(r => setImmediate(r)) - ctx.emit('agent/status', agent, 'running') // sawRunning = true - input.finish() - await new Promise(r => setImmediate(r)) // let readline 'close' set stdinClosed - ;(agent as { status: AgentStatus }).status = 'idle' - // Two idle signals while stdin is already closed: the first arms the timer, - // the second must hit the already-scheduled guard, not arm a second. - ctx.emit('agent/status', agent, 'idle') - ctx.emit('agent/status', agent, 'idle') - await flushExit() - expect(exit).toHaveBeenCalledTimes(1) - }) - - it('does not exit on an idle transition for a different agent', async () => { - const { ctx, input, exit } = await setup() - const agent = makeAgent('main', 'idle') - registerReady(ctx, agent) - input.feed('work') - await new Promise(r => setImmediate(r)) - input.finish() - const other = makeAgent('other') - ctx.emit('agent/status', other, 'running') - ctx.emit('agent/status', other, 'idle') - await flushExit() - expect(exit).not.toHaveBeenCalled() - }) - - it('does not exit while a turn is still running at EOF', async () => { - const { ctx, input, exit } = await setup() - const agent = makeAgent('main', 'idle') - registerReady(ctx, agent) - input.feed('work') - await new Promise(r => setImmediate(r)) - ctx.emit('agent/status', agent, 'running') - ;(agent as { status: AgentStatus }).status = 'running' - input.finish() - // sawRunning is true, but the agent is still running — the idle gate holds. - ctx.emit('agent/status', agent, 'idle') // a stale/duplicate signal while status stays 'running' - await flushExit() - expect(exit).not.toHaveBeenCalled() - }) -}) - -describe('createStdioChat disposal (HMR safety)', () => { - it('never exits the process when EOF arrives after fiber dispose', async () => { - const { fiber, input, exit } = await setup() - await fiber.dispose() - // A late EOF after disposal (reader.close() also fires 'close') must not exit. - input.finish() - await flushExit() - expect(exit).not.toHaveBeenCalled() - }) - - it('cancels a scheduled exit if disposed within the flush window', async () => { - const { fiber, input, exit } = await setup() - // EOF with no work submitted schedules the 200ms flush-then-exit timer. - input.finish() - await new Promise(r => setImmediate(r)) - expect(exit).not.toHaveBeenCalled() // not yet — still inside the window - // Dispose BEFORE the timer fires: the tracked handle must be cleared. - await fiber.dispose() - await flushExit() - expect(exit).not.toHaveBeenCalled() - }) - - it('stops handling input after dispose', async () => { - const { ctx, fiber, input } = await setup() - const agent = makeAgent('main') - ctx.agents.register(agent) - await fiber.dispose() - // The readline interface is closed on dispose; a late line reaches no handler. - input.feed('too late') - await new Promise(r => setImmediate(r)) - expect(agent.sent).toEqual([]) - }) - - it('removes the agent/status listener on dispose', async () => { - const { ctx, fiber, input, exit } = await setup() - const agent = makeAgent('main', 'idle') - registerReady(ctx, agent) - input.feed('work') - await new Promise(r => setImmediate(r)) - await fiber.dispose() - // After dispose, status transitions must neither throw nor schedule an exit - // (the listener and the EOF-exit path are both torn down). - expect(() => { - ctx.emit('agent/status', agent, 'running') - ctx.emit('agent/status', agent, 'idle') - }).not.toThrow() - await flushExit() - expect(exit).not.toHaveBeenCalled() - }) -}) diff --git a/packages/ui/stdio/tsconfig.json b/packages/ui/stdio/tsconfig.json deleted file mode 100644 index e0c578ed32..0000000000 --- a/packages/ui/stdio/tsconfig.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "extends": "../../../tsconfig.base.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "lib/types" - }, - "include": [ - "src" - ], - "references": [ - { - "path": "../../../vendor/cordis" - }, - { - "path": "../../../vendor/schemastery" - }, - { - "path": "../../core/agent" - }, - { - "path": "../../core/agent-loop" - }, - { - "path": "../../core/session" - }, - { - "path": "../../llm/llm" - }, - { - "path": "../user-interaction" - } - ] -} diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index a4dc37dfa9..5563e9ed22 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-tui -The interactive terminal front door for DeepSeek Harness agents, built on [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui). It requires stdin and stdout TTYs; scripts and Loader pipes should compose [`@deepseek-ai/dsh-stdio`](../stdio/README.md) instead. +The interactive terminal front door for DeepSeek Harness agents, built on [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui). It requires stdin and stdout TTYs; scripts and Loader pipes should use the headless [`@deepseek-ai/dsh-cli-demo`](../../examples/cli-demo/README.md) app instead. The implemented [TUI feature Agent Note](../../../.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md) owns the front-door decision; the [terminal-state snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns its verification strategy. @@ -77,4 +77,4 @@ Append-only; newly visible content follows the reusable request prefix and does - **One configured session owns the transcript and editor** — questions from other agents can still use the shared overlay provider, but session rendering and prompt input remain bound to `sessionId`. - **Tool cards are text terminal presentations** — terminal, diff, and generic cards use tool-owned titles/content, but session content currently has no image block for inline image rendering. -- **Non-TTY operation is intentionally unsupported** — app bundles that need automation must select `dsh-stdio` before mounting this plugin rather than expecting an internal fallback. +- **Non-TTY operation is intentionally unsupported** — automation must use the headless app rather than expecting an internal fallback. diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 83432b91d4..f793d24c16 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -36,6 +36,7 @@ import z from 'schemastery' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-agent-loop' import type {} from '@deepseek-ai/dsh-commands' +import { errorChain } from '@deepseek-ai/dsh-llm' import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm' import { SessionId, type Session, type SessionEvent, type TodoItem } from '@deepseek-ai/dsh-session' import type { @@ -192,15 +193,6 @@ function displayText(text: string): string { `\\x${control.charCodeAt(0).toString(16).padStart(2, '0')}`) } -/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */ -function renderThrown(value: unknown): string { - try { - return String(value) - } catch { - return '' - } -} - /** * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR * attributes, which every terminal remaps to its active color scheme. Body @@ -1231,7 +1223,7 @@ export function createTuiChat( }, (error: unknown) => { if (!disposed) { - appendNotice(`Command failed: ${renderThrown(error)}`, 'error') + appendNotice(`Command failed: ${errorChain(error)}`, 'error') } }, ).finally(() => { commandControllers.delete(controller) }) @@ -1312,7 +1304,9 @@ export function createTuiChat( const disposeError = ctx.on('agent/error', (subject, turn, step, error) => { if (subject !== agent) return liveErrors.add(`${turn}:${step}`) - appendNotice(error.message, 'error') + // Full cause chain: wrapper messages like `fetch failed` carry the + // actionable transport detail on `cause`. + appendNotice(errorChain(error), 'error') }) const disposeAgent = ctx.on('agent/disposed', (subject) => { if (subject !== agent) return @@ -1339,7 +1333,7 @@ export function createTuiChat( void commandFiber.dispose().catch( /* v8 ignore next 2 -- command registration cleanup is non-throwing; this guards a future disposer regression */ (cleanupError: unknown) => { - ctx.logger.warn(`ui-tui: command cleanup after startup failure failed: ${renderThrown(cleanupError)}`) + ctx.logger.warn(`ui-tui: command cleanup after startup failure failed: ${errorChain(cleanupError)}`) }, ) clearStatus() @@ -1387,7 +1381,7 @@ export function mountTui(ctx: Context, config: Config, runtime: TuiRuntime): voi if (settled || failedSessionId !== sessionId) return settled = true stopWaiting() - runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${renderThrown(error)}\n`)) + runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${errorChain(error)}\n`)) runtime.exit(1) } @@ -1399,10 +1393,10 @@ export function mountTui(ctx: Context, config: Config, runtime: TuiRuntime): voi /** Cordis entry point using the process terminal; explicit TUI composition requires a TTY pair. */ /* v8 ignore start -- production process wiring; fake-terminal tests cover mountTui/createTuiChat, - and the repl-agent PTY smoke covers the real entry */ + and the tui-agent PTY smoke covers the real entry */ export function apply(ctx: Context, config: Config): void { if (!process.stdin.isTTY || !process.stdout.isTTY) { - throw new Error('ui-tui: both stdin and stdout must be TTYs; use @deepseek-ai/dsh-stdio for pipes') + throw new Error('ui-tui: both stdin and stdout must be TTYs; use @deepseek-ai/dsh-cli-demo for non-interactive runs') } mountTui(ctx, config, { terminal: new ProcessTerminal(), diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 50280d61b9..de09007d57 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -464,7 +464,7 @@ describe('pi-tui chat lifecycle and transcript', () => { result.terminal.send('/plugin-fail') result.terminal.send('\r') await tick() - expect(result.terminal.output).toContain('Command failed: Error: plugin command exploded') + expect(result.terminal.output).toContain('Command failed: plugin command exploded') result.terminal.send('/help') result.terminal.send('\r') await tick() @@ -970,7 +970,7 @@ describe('terminal mounting', () => { expect(terminal.output).toBe('') expect(exit).not.toHaveBeenCalled() ctx.emit('agent-loop/config-start-failed', SessionId('main-session'), new Error('resume \u001b]2;failure-controlled\u0007')) - expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: Error: resume \\x1b]2;failure-controlled\\x07\n') + expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: resume \\x1b]2;failure-controlled\\x07\n') expect(exit).toHaveBeenCalledWith(1) const session = ctx.sessions.create(SessionId('main-session')) @@ -999,7 +999,7 @@ describe('terminal mounting', () => { }) expect(terminal.started).toBe(0) - expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: \n') + expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: \n') expect(exit).toHaveBeenCalledWith(1) await ctx.fiber.dispose() }) diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md index 2ddf261c3a..c026ff0395 100644 --- a/packages/ui/user-interaction/README.md +++ b/packages/ui/user-interaction/README.md @@ -21,7 +21,7 @@ When an answer includes `custom`, `selected` is empty; custom text is an overrid ## Role -This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; UI front doors such as the interactive `dsh-tui`, line-oriented `dsh-stdio`, and structured `dsh-acp` channels provide the provider. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop. +This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; the interactive `dsh-tui` and structured `dsh-acp` front doors provide the provider. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop. ## Model Experience diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0f75baee42..ddae26da0a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -104,6 +104,9 @@ importers: '@deepseek-ai/dsh-agent-spine-demo': specifier: workspace:* version: link:../packages/examples/agent-spine-demo + '@deepseek-ai/dsh-app-boot': + specifier: workspace:* + version: link:../packages/ui/app-boot '@deepseek-ai/dsh-bash-local': specifier: workspace:* version: link:../packages/bash/bash-local @@ -176,9 +179,6 @@ importers: '@deepseek-ai/dsh-spill-policy': specifier: workspace:* version: link:../packages/spill/spill-policy - '@deepseek-ai/dsh-stdio-demo': - specifier: workspace:* - version: link:../packages/examples/stdio-demo '@deepseek-ai/dsh-subagent': specifier: workspace:* version: link:../packages/subagent/subagent @@ -224,6 +224,9 @@ importers: '@deepseek-ai/dsh-tools': specifier: workspace:* version: link:../packages/core/tools + '@deepseek-ai/dsh-tui-demo': + specifier: workspace:* + version: link:../packages/examples/tui-demo '@deepseek-ai/dsh-user-approval': specifier: workspace:* version: link:../packages/ui/user-approval @@ -865,7 +868,7 @@ importers: specifier: ^4.0.0-rc.7 version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) - packages/examples/stdio-demo: + packages/examples/tui-demo: devDependencies: '@cordisjs/plugin-include': specifier: workspace:^ @@ -873,9 +876,6 @@ importers: '@cordisjs/plugin-loader': specifier: workspace:^ version: link:../../../vendor/loader - '@cordisjs/plugin-logger-console': - specifier: workspace:^ - version: link:../../../vendor/logger-console '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -903,9 +903,6 @@ importers: '@deepseek-ai/dsh-session-persistence-jsonl': specifier: workspace:^ version: link:../../session-persistence/session-persistence-jsonl - '@deepseek-ai/dsh-stdio': - specifier: workspace:^ - version: link:../../ui/stdio '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt @@ -2314,34 +2311,6 @@ importers: specifier: ^4.0.0-rc.7 version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) - packages/ui/stdio: - dependencies: - schemastery: - specifier: ^3.18.0 - version: 3.18.0 - devDependencies: - '@cordisjs/plugin-loader': - specifier: workspace:^ - version: link:../../../vendor/loader - '@deepseek-ai/dsh-agent': - specifier: workspace:^ - version: link:../../core/agent - '@deepseek-ai/dsh-agent-loop': - specifier: workspace:^ - version: link:../../core/agent-loop - '@deepseek-ai/dsh-llm': - specifier: workspace:^ - version: link:../../llm/llm - '@deepseek-ai/dsh-session': - specifier: workspace:^ - version: link:../../core/session - '@deepseek-ai/dsh-user-interaction': - specifier: workspace:^ - version: link:../user-interaction - cordis: - specifier: ^4.0.0-rc.7 - version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@vendor+loader) - packages/ui/tool-ask-user: devDependencies: '@deepseek-ai/dsh-agent': diff --git a/python/sdk/tests/manual_sdk_agent_smoke.py b/python/sdk/tests/manual_sdk_agent_smoke.py index 39a00856b7..751b7fc0bf 100644 --- a/python/sdk/tests/manual_sdk_agent_smoke.py +++ b/python/sdk/tests/manual_sdk_agent_smoke.py @@ -83,15 +83,12 @@ def run_smoke(repo_root: Path, keep_sessions: bool) -> None: assert request["authorization"] == "Bearer sdk-smoke-key" assert request["body"]["model"] == "sdk-smoke-model" - jsonl_files = sorted(session_root.rglob("*.jsonl")) - assert jsonl_files, f"no jsonl sessions were written under {session_root}" - print("session_jsonl_files:") + jsonl_files = sorted(session_root.rglob("*.jsonl.zstd")) + assert jsonl_files, f"no Zstandard JSONL sessions were written under {session_root}" + print("session_jsonl_zstd_files:") for path in jsonl_files: print(f" {path} bytes={path.stat().st_size}") - with path.open("r", encoding="utf-8") as handle: - first_line = handle.readline().strip() - if first_line: - print(f" first_line={first_line[:500]}") + assert path.read_bytes().startswith(bytes.fromhex("28b52ffd")) finally: server.shutdown() server.server_close() diff --git a/scripts/demo-code-mode.mjs b/scripts/demo-code-mode.mjs index 43bff2d4ba..273e6e1b38 100644 --- a/scripts/demo-code-mode.mjs +++ b/scripts/demo-code-mode.mjs @@ -1,23 +1,20 @@ /** - * Boot the REPL, TUI, or ACP Code Mode overlay, defaulting to REPL. Each overlay + * Boot the TUI or ACP Code Mode overlay, defaulting to TUI. Each overlay * includes its base example, selects Code Mode, and adds the worker runtime. * All require a DeepSeek API key; unsupported arguments fail with usage. */ import { spawn } from 'node:child_process' -// Each UI's node invocation, verbatim what its base demo script runs plus -// the overlay config (the stdio bin keeps --expose-internals for the cordis -// Loader's HMR path). +// Each UI's node invocation matches its base demo script plus the overlay config. const UIS = new Map([ - ['repl', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/repl-agent/code-mode.cordis.yml']], - ['tui', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']], + ['tui', ['--expose-internals', '--import', 'tsx', 'packages/examples/tui-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']], ['acp', ['--import', 'tsx', 'packages/examples/acp-demo/src/bin.ts', '--config', 'examples/acp-agent/code-mode.cordis.yml']], ]) -const ui = process.argv[2] ?? 'repl' +const ui = process.argv[2] ?? 'tui' const args = UIS.get(ui) if (!args || process.argv.length > 3) { - console.error('usage: pnpm run demo:code-mode [repl|tui|acp]') + console.error('usage: pnpm run demo:code-mode [tui|acp]') process.exit(2) } diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index efce88be63..e7efe7464f 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -149,8 +149,8 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'user-interaction', title: 'Human question/answer seam', mode: 'seam', - implementations: ['stdio-demo', 'acp'], - consumers: ['tool-ask-user', 'stdio-demo', 'acp'], + implementations: ['tui', 'acp'], + consumers: ['tool-ask-user', 'tui', 'acp'], note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.', }, { @@ -175,7 +175,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'agent', title: 'Agent service', mode: 'core', - consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'stdio-demo', 'invariants'], + consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo', 'invariants'], note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.', }, { @@ -451,29 +451,13 @@ function stripYamlScalar(value: string): string { } const APP_EXAMPLES = [ - { - id: 'echo', - rel: 'examples/echo-agent/composition.md', - title: 'Echo Agent App Composition', - label: 'examples/echo-agent', - config: 'examples/echo-agent/cordis.yml', - summary: 'The echo demo swaps in a local mock LLM and teaching echo tool, then loads the stdio app package for the shared spine and terminal front door.', - }, - { - id: 'repl', - rel: 'examples/repl-agent/composition.md', - title: 'REPL Agent App Composition', - label: 'examples/repl-agent', - config: 'examples/repl-agent/cordis.yml', - summary: 'The REPL agent demo adds the real DeepSeek adapter, filesystem tools, todo_write, tool-result pruning, compaction, and both subagent transports on top of the stdio app package.', - }, { id: 'tui', rel: 'examples/tui-agent/composition.md', title: 'TUI Agent App Composition', label: 'examples/tui-agent', config: 'examples/tui-agent/cordis.yml', - summary: 'The TUI agent reuses the repl-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.', + summary: 'The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package.', }, { id: 'headless', @@ -503,18 +487,13 @@ const APP_EXAMPLES = [ type AppExample = typeof APP_EXAMPLES[number] -function renderAppExpansion(lines: string[], appNode: string, pluginName: string, exampleId: string): void { +function renderAppExpansion(lines: string[], appNode: string, pluginName: string): void { const agentCore = nodeId('bundle', 'agent_core') const jsonl = nodeId('bundle', 'jsonl') lines.push(` ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`) lines.push(` ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`) - if (pluginName === '@deepseek-ai/dsh-stdio-demo') { - const frontDoor = exampleId === 'tui' - ? '@deepseek-ai/dsh-tui
pre-created main agent' - : exampleId === 'repl' - ? '@deepseek-ai/dsh-stdio
pre-created main agent' - : 'dsh-tui (TTY) / dsh-stdio (pipes)
pre-created main agent' - lines.push(` ${appNode} --> ${nodeId('frontdoor', 'stdio')}["${frontDoor}"]`) + if (pluginName === '@deepseek-ai/dsh-tui-demo') { + lines.push(` ${appNode} --> ${nodeId('frontdoor', 'tui')}["@deepseek-ai/dsh-tui
pre-created main agent"]`) } else if (pluginName === '@deepseek-ai/dsh-cli-demo') { lines.push(` ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver
format-pure stdout
fresh top-level agent"]`) } else if (pluginName === '@deepseek-ai/dsh-acp-demo') { @@ -543,8 +522,8 @@ function renderAppComposition(example: AppExample): string { const pluginNode = nodeId(`plugin_${example.id}`, plugin.id) lines.push(` ${pluginNode}["${escLabel(plugin.id)}
${escLabel(plugin.name)}"]`) lines.push(` cfg --> ${pluginNode}`) - if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') { - renderAppExpansion(lines, pluginNode, plugin.name, example.id) + if (plugin.name === '@deepseek-ai/dsh-tui-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') { + renderAppExpansion(lines, pluginNode, plugin.name) } } lines.push( @@ -1042,8 +1021,6 @@ function renderDocs(): GraphDoc[] { function renderIndex(docs: GraphDoc[]): string { const labels: Record = { 'docs/capability-seams.md': 'capability seams and core services', - 'examples/echo-agent/composition.md': 'echo-agent app composition', - 'examples/repl-agent/composition.md': 'repl-agent app composition', 'examples/headless-agent/composition.md': 'headless-agent app composition', 'examples/tui-agent/composition.md': 'tui-agent app composition', 'examples/cordis-agent/composition.md': 'cordis-agent app composition', @@ -1055,8 +1032,6 @@ function renderIndex(docs: GraphDoc[]): string { } const modes: Record = { 'docs/capability-seams.md': 'hybrid generated', - 'examples/echo-agent/composition.md': 'hybrid generated', - 'examples/repl-agent/composition.md': 'hybrid generated', 'examples/headless-agent/composition.md': 'hybrid generated', 'examples/tui-agent/composition.md': 'hybrid generated', 'examples/cordis-agent/composition.md': 'hybrid generated', diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 50ca419107..0e7e5aa8e1 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -285,7 +285,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolSubagent, { provider: 'mock' }) }, note: - 'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/repl-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.', + 'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/tui-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.', }, { pkg: '@deepseek-ai/dsh-tool-tasks', diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index a91af85f2e..61aae60297 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -5,9 +5,8 @@ * independent commands can overlap and which commands wait for built artifacts. */ import { spawn } from 'node:child_process' -import { readdir, rm } from 'node:fs/promises' import { availableParallelism } from 'node:os' -import { join, resolve } from 'node:path' +import { resolve } from 'node:path' import { performance } from 'node:perf_hooks' type Mode = @@ -181,6 +180,11 @@ function gatesForMode(selected: Mode): Gate[] { 'run', 'packages/workflow/workflow-workerthread/tests/source-worker.compat.spec.ts', ], { label: 'source worker smoke' }), + pnpmExec('jsonl-zstd-smoke', [ + 'vitest', + 'run', + 'packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts', + ], { label: 'JSONL Zstandard smoke' }), ] case 'pre-push': return [ @@ -210,7 +214,6 @@ function ciPrimaryGates(): Gate[] { pnpmScript('duplication', 'duplication'), coverageGate(), snapshotGate(), - demoSmokeGate({ needs: ['lint'] }), ...docSyncLeafGates(), pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }), pnpmScript('knip', 'knip'), @@ -229,18 +232,12 @@ function ciStaticGates(): Gate[] { pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }), pnpmScript('constraints', 'constraints'), pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }), - ...staticDemoSmokeGates(), ...docSyncLeafGates(), pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }), pnpmScript('knip', 'knip'), ] } -function staticDemoSmokeGates(): Gate[] { - // Native Windows session persistence is outside the gates-only support scope. - return process.platform === 'win32' ? [] : [demoSmokeGate()] -} - function ciArtifactGates(): Gate[] { return [ pnpmScript('build', 'build'), @@ -353,50 +350,14 @@ function docSyncLeafGates(options: { ] } -function demoSmokeGate(options: { needs?: string[] } = {}): Gate { - const dependencyOptions = options.needs === undefined ? {} : { needs: options.needs } - return { - id: 'demo-smoke', - label: 'demo smoke', - displayCommand: 'pnpm run demo:echo', - ...pnpmInvocation(['run', 'demo:echo']), - input: 'echo ci smoke\n', - ...dependencyOptions, - verify: async (result) => { - const output = result.stdout + result.stderr - const sessionsRoot = join(root, '.sessions') - try { - if (!output.includes('[tool call] echo({"text":"ci smoke"})')) { - throw new Error('demo smoke did not show the echo tool call.') - } - if (!output.includes('[tool result] ECHO: CI SMOKE')) { - throw new Error('demo smoke did not show the echo tool result.') - } - const buckets = await readdir(sessionsRoot, { withFileTypes: true }) - let found = false - for (const bucket of buckets) { - if (!bucket.isDirectory() || !bucket.name.startsWith('cwd-')) continue - const entries = await readdir(join(sessionsRoot, bucket.name)) - if (entries.some(entry => /^main-session-.+\.jsonl$/.test(entry))) { - found = true - break - } - } - if (!found) throw new Error('demo smoke did not create a main-session JSONL log in a cwd bucket.') - } finally { - await rm(sessionsRoot, { recursive: true, force: true }) - } - }, - } -} - function builtBinSmokeGate(): Gate { return pnpmExec('built-bin-smoke', [ 'vitest', 'run', '--config', 'vitest.e2e.config.ts', - 'packages/examples/stdio-demo/tests/built-bin.e2e.ts', + 'examples/headless-agent/tests/keyless-smoke.e2e.ts', + 'examples/tui-agent/tests/tui-keyless-smoke.e2e.ts', 'packages/examples/cli-demo/tests/built-bin.e2e.ts', 'packages/examples/acp-demo/tests/built-bin.e2e.ts', 'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts', @@ -408,6 +369,7 @@ function builtBinSmokeGate(): Gate { ], { label: 'built-bin smoke', needs: ['build'], + env: { DSH_EXAMPLE_MODE: 'lib' }, }) } diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index 6061d945e7..6d8890aa2e 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -64,6 +64,7 @@ CUSTOM_CORDIS = """\ name: '@deepseek-ai/dsh-session-persistence-jsonl' config: root: !!js process.env.DSH_SESSION_ROOT + compression: 'none' - id: bash name: '@deepseek-ai/dsh-bash-local' config: @@ -391,7 +392,7 @@ def smoke_sdk_default(base_url: str) -> None: result = harness.run("reply with the smoke text", session_id="default-smoke") assert result.status == "ok", result assert result.final_response == EXPECTED_TEXT, result.final_response - assert_session_log(sessions, root, EXPECTED_TEXT) + assert_zstd_session_log(sessions) def smoke_sdk_custom(base_url: str, executable: Path) -> None: @@ -585,6 +586,14 @@ def assert_session_log(sessions: Path, cwd: Path, *expected_texts: str) -> None: raise AssertionError(f"session log has no {expected!r} response: {logs[0]}") +def assert_zstd_session_log(sessions: Path) -> None: + logs = list(sessions.rglob("*.jsonl.zstd")) + if len(logs) != 1: + raise AssertionError(f"expected one Zstandard JSONL session log under {sessions}, found {logs}") + if not logs[0].read_bytes().startswith(bytes.fromhex("28b52ffd")): + raise AssertionError(f"session log has no Zstandard magic: {logs[0]}") + + def read_session_logs(sessions: Path) -> dict[str, list[dict[str, object]]]: """Parse every persisted JSONL session into a map keyed by header id.""" logs: dict[str, list[dict[str, object]]] = {} diff --git a/skills/create-dsh-sdk-project/SKILL.md b/skills/create-dsh-sdk-project/SKILL.md index 5b984f3b86..d05cae182a 100644 --- a/skills/create-dsh-sdk-project/SKILL.md +++ b/skills/create-dsh-sdk-project/SKILL.md @@ -30,7 +30,7 @@ block. "provider": "deepseek", "apiKey": "", "model": "deepseek-v4-flash", - "interface": "stdio", + "interface": "tui", "pm": "npm", "install": false, "features": [ diff --git a/tsconfig.build.json b/tsconfig.build.json index 188b699534..4ee1ec5843 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -80,8 +80,7 @@ { "path": "./packages/ui/jsonrpc" }, { "path": "./packages/examples/jsonrpc-demo" }, { "path": "./packages/ui/tui" }, - { "path": "./packages/ui/stdio" }, - { "path": "./packages/examples/stdio-demo" }, + { "path": "./packages/examples/tui-demo" }, { "path": "./packages/support/llm-replay" }, { "path": "./packages/support/acp-snapshot" }, { "path": "./packages/support/loader-smoke" }, diff --git a/tsconfig.json b/tsconfig.json index e4745fb987..0cd16698a1 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -94,8 +94,7 @@ { "path": "./packages/ui/jsonrpc" }, { "path": "./packages/examples/jsonrpc-demo" }, { "path": "./packages/ui/tui" }, - { "path": "./packages/ui/stdio" }, - { "path": "./packages/examples/stdio-demo" }, + { "path": "./packages/examples/tui-demo" }, { "path": "./packages/support/llm-replay" }, { "path": "./packages/support/acp-snapshot" }, { "path": "./packages/support/loader-smoke" },