docs: trim generated prose

packages/ui/stdio-agent/src/bin.ts

@@ -1,14 +1,7 @@
 #!/usr/bin/env node
 /**
- * The `dsh-stdio-agent` bin: boot a Cordis app from a leaf `cordis.yml` that
- * loads the {@link @deepseek-ai/dsh-stdio-agent} app plugin (plus a backend LLM
- * adapter and a bash executor). The boot glue — `.env` loading, the fail-loud
- * Loader guards, the settle-the-tree boot sequence — lives in
- * {@link @deepseek-ai/dsh-app-boot}, shared with the ACP bin.
- *
- * Usage: `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`). The
- * `demo:echo` / `demo:repl` scripts invoke it with the example's config.
- *
+ * The `dsh-stdio-agent` bin: boot a Cordis app from a leaf `cordis.yml` that loads the {@link
+ * @deepseek-ai/dsh-stdio-agent} app plugin (plus a backend LLM adapter and a bash executor).
  * @module @deepseek-ai/dsh-stdio-agent/bin
  */
 

packages/ui/stdio-agent/src/index.ts

@@ -1,40 +1,8 @@
 /**
- * The stdio chat app: the default agent spine ({@link
- * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
- * chat needs — a console logger, the readline UI (the in-package `stdio-chat`
- * module), JSONL session
- * persistence, and a pre-created `main` agent the UI drives.
- *
- * The cluster is BAKED IN, not left to the leaf: a stdio app always logs to the
- * console (stdout is just the terminal) and always pre-creates the `main` agent
- * the readline UI sends to. The leaf supplies the swappable backends (the LLM
- * adapter, the bash executor), optional product tools, the optional `hmr`
- * dev-reload plugin, and this app's {@link Config} (model, prompt, persistence
- * root, welcome banner).
- *
- * `hmr` is deliberately a LEAF entry, not baked in here: it is a Loader-only,
- * subprocess-only dev plugin (its constructor throws without `--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 be unit-tested or
- * 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, while
- * baking the LOGGER in (the real coupling) keeps stdout-vs-no-stdout a property
- * of the artifact.
- *
- * Counterpart to {@link @deepseek-ai/dsh-acp-agent}, which bakes in the OPPOSITE
- * cluster (no stdout logger, no pre-created agents — the ACP bridge reserves
- * stdout for JSON-RPC and creates agents on demand). Splitting the two front
- * doors into two packages makes each cluster a property of the artifact: there
- * is no logger entry in the ACP leaf to get wrong.
- *
- * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
- * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
- * default would collapse the module to the bare `apply` and drop the `Config`
- * namespace (see docs/postmortem/0001). This app carries no `inject`, so a
- * collapsed shape would BOOT rather than crash a smoke — the shape is pinned by
- * the explicit `unwrapExports` assertion in this package's unit suite, and the
- * keyless echo smoke proves the composed tree runs through the real Loader.
- *
+ * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-core}) plus the
+ * coupled front-door cluster a terminal chat needs — a console logger, the readline UI (the
+ * in-package `stdio-chat` module), JSONL session persistence, and a pre-created `main` agent
+ * the UI drives.
  * @module @deepseek-ai/dsh-stdio-agent
  */
 

packages/ui/stdio-agent/src/stdio-chat.ts

@@ -1,17 +1,6 @@
 /**
- * The stdio app's readline UI: reads lines from stdin → `agent.send()`/
- * `steer()`, and renders the durable transcript to stdout. A UI is "just a
- * plugin" — it consumes the `session/event` feed (the assistant token stream,
- * turn/step boundaries, tool activity, todos) plus a few `agent/*` control
- * events (`agent/status`, `agent/created`/`agent/disposed`) and the `agents`
- * service. Dimmed chain-of-thought rendering plus robust piped-stdin EOF→idle
- * exit handling, configured via {@link Config}.
- *
- * An internal module of the stdio app, not a package of its own: the app's
- * front-door cluster always includes this UI, and nothing else composes it.
- * The export shape stays named `name`/`inject`/`Config`/`apply` — the plugin
- * contract the app's `ctx.plugin(uiStdio, …)` mount consumes.
- *
+ * The stdio app's readline UI: reads lines from stdin → `agent.send()`/ `steer()`, and renders
+ * the durable transcript to stdout.
  * @module @deepseek-ai/dsh-stdio-agent/stdio-chat
  */
 
@@ -80,15 +69,10 @@ type OptionSelection =
   | { 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).
+ * Register stdio chat against an injectable I/O runtime.
+ * @param ctx - agent and event context.
+ * @param config - plugin config, defaulted for direct callers.
+ * @param runtime - line source, render sink, and exit hook.
  */
 export function createStdioChat(ctx: Context, config: Config, runtime: StdioRuntime): void {
   // Default here too (not just via schemastery's `.default()`): this helper is
@@ -99,26 +83,16 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
   const agentId = AgentId(config.agent ?? 'main')
   const { input, output, exit } = runtime
 
-  // Render label lookup: the `turn/start` session event carries only the turn
-  // number, so to print the short agent id (`[main turn 1]`) we map the
-  // session's id to its agent's id. The session id is not reliably the agent id
-  // (a session can be created with an explicit/client-supplied id), so build the
-  // map from `agent/created` rather than parsing the id string. Seed from the
-  // registry's current agents first: an agent registered before this plugin
-  // installed (e.g. the pre-created `main` agent, or any agent surviving an HMR
-  // reload of just this fiber) already fired its `agent/created`, so the live
-  // listener alone would miss it and its turns would fall back to the raw
-  // session id.
+  // Render label lookup: the `turn/start` session event carries only the turn number, so to
+  // print the short agent id (`[main turn 1]`) we map the session's id to its agent's id.
   const labelBySession = new Map<string, string>()
   for (const agent of ctx.agents.list()) labelBySession.set(agent.session.header.id, agent.id)
   ctx.on('agent/created', (agent) => { labelBySession.set(agent.session.header.id, agent.id) })
   ctx.on('agent/disposed', (agent) => { labelBySession.delete(agent.session.header.id) })
 
-  // 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.
+  // 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).
   let inReasoning = false
   ctx.on('session/event', (session, event) => {
     if (event.type === 'assistant/chunk') {
@@ -161,16 +135,9 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
 
   ctx.effect(() => {
     const reader = createInterface({ input, output, terminal: isTTYPair(input, output) })
-    // 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. Two subtleties this handles: the loop batches
-    //    several queued messages into ONE turn (one idle), so we don't count
-    //    sends; and agent.send() 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.
+    // 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.
     let stdinClosed = false
     let disposed = false
     let submittedWork = false
@@ -188,10 +155,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
         const agent = ctx.agents.get(agentId)
         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.
+      // Let any final output flush, then exit.
       if (exitTimer !== undefined) {
         return // exit already scheduled — coalesce re-entrant calls
       }

packages/ui/stdio-agent/tests/built-bin.e2e.ts

@@ -7,31 +7,13 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 
 /**
- * BUILT-ARTIFACT smoke for the published `dsh-stdio-agent` bin. The other smokes
- * boot `src/bin.ts` under tsx — but the package's `bin` field points at
- * `lib/bin.js`, run under plain `node` by a real consumer. tsx masks two failure
- * modes the built bin had: (1) `boot()` returned before the loader tree settled,
- * so the process exited 0 with no output and load errors surfaced as unhandled
- * rejections AFTER boot; (2) config-path resolution could fall back to the cwd.
- * This test runs the REAL `lib/bin.js` under `node` (NOT tsx) and asserts the
- * banner + echo round-trip, so a regression in the published entry fails here.
- *
- * It build-gates: if `lib/bin.js` is absent (suite run without `pnpm run build`)
- * the test SKIPS with a note. CI runs it after the build step. Setup mirrors a
- * real install: a temp dir whose `node_modules/@deepseek-ai/*` (and the vendored
- * `cordis`/`@cordisjs/*`) are symlinked to the built packages, a `cordis.yml`
- * that loads the app + the example's mock backend, and `node --expose-internals`
- * (the cordis Loader resolves bare plugin specifiers via its internal module
- * loader, active only under that flag — the same flag `demo:echo` passes).
+ * Built-ARTIFACT smoke for the published `dsh-stdio-agent` bin.
  */
 
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
 const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js')
 
-// Workspace packages the stdio app's tree needs, by repo-relative path. Each is
-// symlinked into the temp consumer's node_modules under its package name, so
-// plain `node` resolves the bare `@deepseek-ai/dsh-*` specifiers in cordis.yml
-// to the built `lib/` (package.json `main`), exactly as an installed dep would.
+// Workspace packages the stdio app's tree needs, by repo-relative path.
 const dshPackages = [
   'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local',
@@ -153,9 +135,8 @@ describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.
   }, 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. Even though its
-    // plugin path does not exist, the app boots and the round-trip works.
+    // A `disabled: true` entry settles without a fiber by design; the fail-loud entry-load
+    // guard must not mistake it for a failed import.
     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')
@@ -165,10 +146,7 @@ describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.
   }, 30_000)
 
   it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
-    // A consumer who typos the config path must get a clear failure, not silent
-    // success. This dir does not exist, so the include PLUGIN itself fails to
-    // import; the cordis Loader logs that and leaves the entry with no fiber (no
-    // rejection), which `boot()`'s entry-load check turns into a thrown error.
+    // A consumer who typos the config path must get a clear failure, not silent success.
     consumer = await makeConsumer('unused')
     const { code, stderr } = await runBuiltBin(consumer, '/nonexistent/dir/cordis.yml', '')
     expect(code).not.toBe(0)
@@ -176,9 +154,7 @@ describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.
   }, 30_000)
 
   it('fails LOUD (non-zero exit + stderr) on a missing config file in a real directory', async () => {
-    // The config DIRECTORY exists (the include plugin imports), but the file does
-    // not — the include's init throws "config file not found", which surfaces as
-    // an unhandled rejection the fail-loud guard turns into a non-zero exit.
+    // 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)

packages/ui/stdio-agent/tests/stdio-agent.spec.ts

@@ -10,20 +10,9 @@ import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as stdioAgent from '../src/index.ts'
 
 /**
- * Unit coverage for the @deepseek-ai/dsh-stdio-agent app plugin: mounting it
- * composes the console logger, the agent-core spine (pre-creating the `main`
- * agent from the app config), the JSONL backend, and the readline UI in one
- * `ctx.plugin`. The forwarded `model` reaches the pre-created agent and
- * `persona` the system-prompt plugin; `persistenceRoot`/`welcome`/
- * `resumeSessionId` route to their backends.
- *
- * `hmr` is NOT part of this plugin (it is a leaf entry — a Loader-only dev
- * plugin the in-process tier cannot import); the keyless echo smoke in
- * `examples/echo-agent` proves the whole subprocess tree (incl. `hmr`) boots
- * through the real Loader, while the export SHAPE is pinned by this suite's
- * explicit `unwrapExports` assertion (an inject-less app would boot past a
- * stray default rather than crash). Here we assert the composition + config
- * forwarding the unit tier can reach.
+ * Unit coverage for the @deepseek-ai/dsh-stdio-agent app plugin: mounting it composes the
+ * console logger, the agent-core spine (pre-creating the `main` agent from the app config),
+ * the JSONL backend, and the readline UI in one `ctx.plugin`.
  */
 async function mount(config: stdioAgent.Config): Promise<Context> {
   const ctx = new Context()
@@ -163,14 +152,7 @@ describe('dsh-stdio-agent app', () => {
   })
 
   it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
-    // Postmortem 0001 guard: a stray `export default apply` makes the Loader's
-    // `unwrapExports` (`exports.default ?? exports`) collapse the module to the
-    // bare `apply` function, DROPPING the named `name`/`Config`. This package has
-    // no `inject` export, so that collapse would NOT crash at load (the keyless
-    // echo smoke would still boot the tree) — it would silently lose its config
-    // schema. So guard the shape directly here: assert no `default` export, and
-    // that the real `unwrapExports` leaves `name`/`Config`/`apply` intact. Adding
-    // `export default` to src/index.ts fails this test.
+    // Loader must retain the namespace so name, Config, and apply survive unwrapping.
     expect('default' in stdioAgent).toBe(false)
     expect(typeof stdioAgent.apply).toBe('function')
 

packages/ui/stdio-agent/tests/stdio-chat.spec.ts

@@ -179,11 +179,9 @@ describe('createStdioChat rendering', () => {
   })
 
   it('seeds labels for agents already registered before the UI installs', 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 is what keeps its turn header showing `[main turn N]` instead
-    // of the raw session id.
+    // 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.
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)