Merge origin/master into skill system branch

Resolve documentation split, tool presentation, and generated catalog changes from master while preserving the skill system integration.

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

@@ -2,139 +2,24 @@
 /**
  * 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). Owns the boot glue the three `examples/*` once
- * duplicated in their `start.ts`: load the gitignored repo-root `.env`, then
- * drive the cordis Loader against the config path (default `./cordis.yml`).
+ * 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]`. The `demo:echo` / `demo:coding`
- * scripts invoke it with the example's config.
+ * Usage: `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`). The
+ * `demo:echo` / `demo:repl` scripts invoke it with the example's config.
  *
  * @module @deepseek-ai/dsh-stdio-agent/bin
  */
 
-import { pathToFileURL } from 'node:url'
-import { dirname, resolve } from 'node:path'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 
-/**
- * Load `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL` from a gitignored `.env` in the
- * CURRENT WORKING DIRECTORY (Node native `process.loadEnvFile`). An absent file
- * is fine — the environment may already carry the variables; the leaf
- * `cordis.yml` reads them via the `!!js` tag. A present-but-unreadable/malformed
- * `.env` is a real misconfiguration: surface it on stderr rather than silently
- * running with the wrong environment. The mock-model demo (echo) ships no key
- * and simply has no `.env`.
- */
-function loadEnv(): void {
-  try {
-    process.loadEnvFile(resolve(process.cwd(), '.env'))
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
-      process.stderr.write(`dsh-stdio-agent: failed to load .env: ${String(error)}\n`)
-    }
-    // ENOENT (no .env) is fine — rely on the ambient environment.
-  }
-}
+const NAME = 'dsh-stdio-agent'
 
-/**
- * Make a load failure fail loud with a clear message on stderr. Covers the
- * failure path the entry-tree check below cannot: when the include's
- * `[Service.init]` throws (e.g. a config FILE that does not exist in a real
- * directory), the cordis Loader surfaces it as an unhandled promise rejection
- * AFTER `boot()` has resolved — `loader.await()` does NOT rethrow it, because
- * `EntryTree.await()` uses `Promise.allSettled`, which swallows rejections.
- * Node's default handler already exits non-zero on an unhandled rejection, so
- * this does not change the exit code; it replaces Node's noisy stack dump with a
- * single labelled line and guarantees `process.exit(1)`. Install before `boot()`.
- */
-export function installFailLoud(): void {
-  process.on('unhandledRejection', (err: unknown) => {
-    process.stderr.write(`dsh-stdio-agent: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
-    process.exit(1)
-  })
-}
-
-/**
- * After the tree settles, assert every loader entry actually started. This is
- * the load-bearing guard against the SILENT-exit-0 bug: when a plugin module
- * fails to IMPORT (e.g. a config path in a non-existent directory, so the include
- * plugin itself cannot be resolved), the cordis Loader catches the import error
- * and only LOGS it (`entry._init`), leaving the entry with no `fiber` and
- * producing no rejection — so the process would otherwise exit 0 with a usable
- * config typo reported only as a log line. A started entry has a `fiber`; an
- * entry with `fiber === undefined` after the tree settled never loaded. Throw on
- * any such entry so `boot()` rejects (and the top-level `await` fails the process
- * non-zero) instead of returning a half-empty context.
- *
- * A `disabled` entry is the one legitimate fiber-less state: `Entry.refresh()`
- * deliberately skips `init()` for it, so it settles without a fiber by design.
- * That is a valid config (a consumer turning an optional plugin off), not a
- * failed import — exclude it so the guard catches only real load failures.
- */
-function assertEntriesLoaded(ctx: Context): void {
-  const failed = [...ctx.loader.entries()].filter(entry => entry.fiber === undefined && !entry.disabled)
-  if (failed.length > 0) {
-    const names = failed.map(entry => entry.options.name).join(', ')
-    throw new Error(`dsh-stdio-agent: plugin(s) failed to load: ${names} (see the error(s) logged above)`)
-  }
-}
-
-/**
- * Boot the Loader against `configPath` (resolved from the CWD). The include is
- * handed the config's ABSOLUTE `file://` URL as its `path`, so resolution never
- * depends on `ctx.baseUrl` (an absolute URL ignores the base) and can never fall
- * back to the cwd. `baseUrl` is still pinned to the config's directory so the
- * config's OWN relative plugin/include paths (e.g. `./src/mock-llm.ts`) resolve
- * against it. Returns the root context once the whole tree has settled.
- *
- * The `await ctx.loader.await()` is load-bearing: `loader.create()` returns once
- * the include ENTRY is registered, but the include then loads its child plugins
- * asynchronously. Without awaiting the tree, `boot()` (and `main()`) would
- * resolve while the app plugins — the stdin reader, the agent loop — are still
- * mounting, and a CLI process with no attached handles yet exits 0 silently.
- * Awaiting the tree keeps the process alive until the app's handles are attached.
- *
- * `loader.await()` does NOT, however, rethrow load errors (`EntryTree.await()`
- * uses `Promise.allSettled`), so failures are surfaced two ways: a plugin that
- * fails to IMPORT leaves an entry with no fiber, caught here by
- * {@link assertEntriesLoaded} (this `boot()` rejects); a plugin whose init
- * THROWS surfaces as an unhandled rejection caught by {@link installFailLoud}
- * (installed by `main()` before this runs). Together they make any load failure
- * exit non-zero with a clear message.
- *
- * Bare plugin specifiers in the config (`@deepseek-ai/dsh-*`, npm packages) are
- * resolved by the cordis Loader's internal module loader, which is only active
- * under `node --expose-internals` (the flag the `demo:echo`/`demo:coding` scripts
- * pass). Without it the Loader falls back to resolving relative to its own module
- * and cannot find the config's plugins, so a consumer running the built bin must
- * pass `--expose-internals` (or install the plugins where node hoists them).
- */
-export async function boot(configPath: string): Promise<Context> {
-  const absolute = resolve(process.cwd(), configPath)
-  const ctx = new Context()
-  ctx.baseUrl = pathToFileURL(dirname(absolute)).href + '/'
-  await ctx.plugin(Loader)
-  await ctx.loader.create({
-    name: '@cordisjs/plugin-include',
-    config: { path: pathToFileURL(absolute).href },
-  })
-  await ctx.loader.await()
-  assertEntriesLoaded(ctx)
-  return ctx
-}
-
-/**
- * Entry point: install the fail-loud guard, load `.env`, then boot the config
- * named on argv (default `./cordis.yml`). Awaited at the module top level by the
- * published bin (`#!/usr/bin/env node` shebang via the package's `bin` field).
- */
-export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
-  installFailLoud()
-  loadEnv()
-  await boot(argv[0] ?? './cordis.yml')
-}
-
-/* v8 ignore start -- top-level CLI invocation; the testable core is boot()/main(), driven by the keyless Loader-path smoke */
-await main()
+/* 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
+   built-bin smokes */
+installFailLoud(NAME)
+loadEnv(NAME)
+await boot(NAME, resolveConfigPath(process.argv[2] ?? './cordis.yml', undefined))
 /* v8 ignore stop */

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

@@ -1,12 +1,13 @@
 /**
  * The stdio chat app: the providerless agent spine ({@link
  * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
- * chat needs — a console logger, the readline `ui-stdio` UI, JSONL session
+ * 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
- * `ui-stdio` sends to. The leaf supplies the swappable backends (the LLM
+ * 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).
@@ -29,8 +30,10 @@
  * 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). The keyless Loader-path smoke in the
- * echo example guards this end-to-end.
+ * 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.
  *
  * @module @deepseek-ai/dsh-stdio-agent
  */
@@ -42,7 +45,7 @@ import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import * as agentCore from '@deepseek-ai/dsh-agent-core'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import * as uiStdio from '@deepseek-ai/dsh-ui-stdio'
+import * as uiStdio from './stdio-chat.ts'
 
 export const name = 'stdio-agent'
 
@@ -83,7 +86,7 @@ export const Config: z<Config> = z.object({
  * Compose the spine with the stdio front door. The console logger comes first
  * (infra), then the agent-core bundle pre-creating the `main` agent from this
  * app's `model`/`systemPrompt`/`resumeSessionId`, then the JSONL backend, then
- * the `ui-stdio` UI bound to `main`. The `hmr` dev-reload plugin is a leaf
+ * the readline UI bound to `main`. The `hmr` dev-reload plugin is a leaf
  * concern (see the module doc), so it is not mounted here.
  */
 export function apply(ctx: Context, config: Config): void {

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

@@ -0,0 +1,225 @@
+/**
+ * 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.
+ *
+ * @module @deepseek-ai/dsh-stdio-agent/stdio-chat
+ */
+
+import { createInterface } from 'node:readline'
+import type { Readable, Writable } from 'node:stream'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+
+export const name = 'ui-stdio'
+export const inject = ['agents']
+
+/** Serializable plugin configuration (cordis-native, schemastery). */
+export interface Config {
+  /** Banner printed once on start, before the first `> ` prompt. */
+  welcome?: string
+  /** Id of the agent stdin drives (`send`/`steer`) and whose status gates the EOF exit; rendering is global. Defaults to `'main'`. */
+  agent?: string
+}
+
+export const Config: z<Config> = z.object({
+  welcome: z.string().default('ready.'),
+  agent: 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)
+}
+
+/**
+ * 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.
+ */
+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 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.
+  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.
+  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 = labelBySession.get(session.header.id) ?? session.header.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') {
+      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(() => {
+    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.
+    let stdinClosed = false
+    let disposed = false
+    let submittedWork = false
+    let sawRunning = false
+    let exitTimer: ReturnType<typeof setTimeout> | undefined
+
+    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 = 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.
+      if (exitTimer !== undefined) {
+        return // exit already scheduled — coalesce re-entrant calls
+      }
+      exitTimer = setTimeout(() => { exit(0) }, 200)
+    }
+
+    const disposeStatusListener = ctx.on('agent/status', (subject, status) => {
+      if (subject.id !== agentId) return
+      if (status === 'running') sawRunning = true
+      if (status === 'idle') maybeExit()
+    })
+
+    reader.on('line', (line) => {
+      const text = line.trim()
+      if (!text) return
+      const agent = ctx.agents.get(agentId)
+      if (!agent) {
+        ctx.logger.error('ui-stdio: agent "%s" is not running', agentId)
+        return
+      }
+      submittedWork = true
+      if (agent.status === 'running') {
+        agent.steer([{ type: 'text', text }])
+      } else {
+        agent.send([{ type: 'text', 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
+      maybeExit()
+    })
+    output.write(`${welcome}\n> `)
+    return () => {
+      disposed = true
+      if (exitTimer !== undefined) clearTimeout(exitTimer)
+      disposeStatusListener()
+      reader.close()
+    }
+  }, 'ui-stdio')
+}
+
+/**
+ * Cordis entry point. Binds the real `process` streams and delegates to
+ * {@link createStdioChat}; 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 {
+  createStdioChat(ctx, config, {
+    input: process.stdin,
+    output: process.stdout,
+    exit: code => process.exit(code),
+  })
+}
+/* v8 ignore stop */