refactor(examples): give TUI its own agent leaf

examples/tui-agent/README.md

@@ -0,0 +1,19 @@
+# tui-agent
+
+The full-screen terminal counterpart to the [`coding-agent`](../coding-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.
+
+## Run it
+
+```sh
+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 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.
+
+Run `pnpm run demo:code-mode tui` for the sibling Code Mode overlay.
+
+## Composition
+
+[`cordis.yml`](cordis.yml) includes the readline coding-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 coding agent's Code Mode overlay.

examples/tui-agent/code-mode.cordis.yml

@@ -0,0 +1,30 @@
+# Code Mode keeps the TUI front door while reusing the coding-agent overlay's
+# worker runtime and one-tool registry composition.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ../coding-agent/code-mode.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: 'TUI Code Mode ready. Give it a multi-tool task.'
+          ui:
+            mode: tui
+            tui:
+              showReasoning: true
+              maxToolOutputLines: 12
+          persona: |
+            You are coding-agent, a coding assistant 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.

examples/tui-agent/composition.md

@@ -0,0 +1,28 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# TUI Agent App Composition
+
+The TUI agent reuses the coding-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.
+
+```mermaid
+flowchart LR
+  cfg["examples/tui-agent<br/>cordis.yml"]
+  plugin_tui_base["base<br/>@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<br/>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 |
+| --- | --- |
+| `base` | `@deepseek-ai/dsh-stdio-demo` |
+
+Source config: [`examples/tui-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.

examples/tui-agent/cordis.yml

@@ -0,0 +1,28 @@
+# Full-screen TUI front door over the same coding-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: ../coding-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 coding-agent, a coding assistant powered by the {{model}} model.
+
+            Verify your work by running the code or tests. Keep answers brief and
+            factual.

examples/tui-agent/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "tui-agent-example",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Runnable demo: the coding agent through the full-screen terminal UI"
+}

examples/tui-agent/tests/fixtures/tui-scripted-llm.ts

@@ -0,0 +1,60 @@
+import type { Context } from 'cordis'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
+
+const INITIAL_TEXT = 'I need one decision before I continue.'
+const FINAL_TEXT = 'Decision received. Scripted TUI run complete.'
+
+function textChunks(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    ...Array.from(text, (char): StreamChunk => ({ type: 'text-delta', index: 0, text: char })),
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'usage', usage: { inputTokens: 20, outputTokens: text.length } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+/** Keyless two-step adapter for the real-PTY TUI conversation test. */
+class ScriptedTuiAdapter extends LlmAdapter {
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const hasToolResult = options.messages.at(-1)?.content.some(block => block.type === 'tool-result') ?? false
+    if (hasToolResult) {
+      for (const chunk of textChunks(FINAL_TEXT)) yield chunk
+      return
+    }
+
+    const args = JSON.stringify({
+      questions: [{
+        id: 'mode',
+        header: 'Execution mode',
+        question: 'How should the scripted run proceed?',
+        options: [
+          { label: 'Safe', description: 'Use the guarded path.' },
+          { label: 'Fast', description: 'Use the shorter path.' },
+        ],
+      }],
+    })
+    const callId = CallId('call-ask-mode')
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    for (const char of INITIAL_TEXT) yield { type: 'text-delta', index: 0, text: char }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: INITIAL_TEXT } }
+    yield { type: 'block-start', index: 1, blockType: 'tool-call' }
+    yield { type: 'tool-call-delta', index: 1, id: callId, name: 'ask_user_question', argumentsDelta: args }
+    yield {
+      type: 'block-end',
+      index: 1,
+      block: { type: 'tool-call', id: callId, name: 'ask_user_question', arguments: args },
+    }
+    yield { type: 'usage', usage: { inputTokens: 20, outputTokens: 10 } }
+    yield { type: 'finish', reason: { kind: 'tool-calls' } }
+  }
+}
+
+export const name = 'tui-scripted-llm'
+export const inject = ['llm']
+
+/** Register the network-free adapter used by the PTY fixture. */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter(['tui-scripted'], new ScriptedTuiAdapter())
+}

examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml

@@ -0,0 +1,27 @@
+# Real Loader composition for the keyless conversational PTY test. The app
+# bundle supplies the production agent/TUI/user-question stack; only the model
+# is scripted so the terminal interaction is deterministic and network-free.
+- id: scripted-llm
+  name: './tui-scripted-llm.ts'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-demo'
+  config:
+    provider: tui-scripted
+    model: tui-scripted-model
+    persistenceRoot: './.sessions'
+    workspaceContext:
+      maxBytes: 65536
+    welcome: 'scripted TUI ready.'
+    ui:
+      mode: tui
+      tui:
+        showReasoning: true

examples/tui-agent/tests/tui-keyless-smoke.e2e.ts

@@ -0,0 +1,167 @@
+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'
+
+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 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: agent "main" 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<string> {
+  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)', () => {
+  it('boots pi-tui, renders the configured banner, accepts /exit, and restores the terminal', async () => {
+    const output = await runTuiLoaderSmoke()
+    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' })
+    expect(output).toContain('I need one decision before I continue.')
+    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' })
+    expect(output).toContain('ui-tui: agent "main" failed to start:')
+    expect(output).toContain('missing-session')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})