Merge remote-tracking branch 'origin/master' into worktree/web-bind-address

# Conflicts:
#	apps/cli/src/bin.ts

apps/cli/README.md

@@ -0,0 +1,21 @@
+# `@deepseek-ai/dsh`
+
+The `dsh` command-line entry, following the `apps/` assembly tier proposed by the `dsh web` PR (#443): `apps/*` are product assemblies over `packages/*` libraries. This branch ships one surface — plain `dsh [config.yml]` boots the interactive TUI coding agent — and reserves the `web` and `-p`/`--prompt` subcommands for that PR so the dispatch merges as a union.
+
+The TUI surface:
+
+- boots the shipped default config (`examples/tui-agent/cordis.yml`) or an explicit config argument, through [`dsh-app-boot`](../../packages/ui/app-boot/README.md);
+- resumes a persisted session with `dsh --resume <session-id>` — the form the TUI prints on exit and lists under `/resume`; the flag sets `RESUME_SESSION_ID` before boot so the shipped config rehydrates that session, and a missing or unreadable id fails loud and exits nonzero;
+- treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd;
+- tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
+- applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `.env` fills environment gaps (ambient > project `.env` > personal `.env`), `config.yaml` patches the booted tree.
+
+## Install (developer machine)
+
+Symlink the source-running launcher onto your PATH; it resolves the checkout through its own real path, so code changes apply on the next launch with no build step:
+
+```sh
+ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh
+```
+
+`pnpm run demo:tui` runs the same entry from the repo root. The built form (`lib/bin.js`, via `pnpm run build`) needs `node --expose-internals` for the shipped config's HMR entry, exactly like the demo bins.

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh",
-  "description": "dsh CLI: `dsh web` serves the built web UI over HTTP; `dsh -p` runs one headless task through the in-process ApiProxy carrier",
+  "description": "dsh CLI: interactive TUI, headless task, and browser UI surfaces",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -18,6 +18,7 @@
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-host-runtime": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^"
   }
 }

apps/cli/src/bin.ts

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 /**
- * dsh — command-line entry. Coarse dispatch only; each subcommand module owns
- * its parseArgs. Dynamic imports keep the shapes independent: `web` never
- * loads the headless consumer, `-p` never loads node:http or the static server.
+ * dsh — command-line entry. Coarse dispatch only; each surface module owns its
+ * argument handling. Dynamic imports keep unrelated surfaces out of each
+ * dispatch path; everything except `web` and headless prompts opens the TUI.
+ * @module @deepseek-ai/dsh/bin
  */
 
+/* v8 ignore file -- built-bin and PTY tests exercise this self-executing dispatch. */
+
 import { loadEnv } from '@deepseek-ai/dsh-app-boot'
 
 loadEnv('dsh')
@@ -17,6 +20,6 @@ if (argv[0] === 'web') {
   const { runHeadless } = await import('./headless.ts')
   await runHeadless(argv)
 } else {
-  process.stderr.write('usage: dsh web [--host HOST] [--port N] | dsh -p "task"\n')
-  process.exit(1)
+  const { runTui } = await import('./tui.ts')
+  await runTui(argv)
 }

apps/cli/src/headless.ts

@@ -81,7 +81,7 @@ export async function runHeadless(argv: string[]): Promise<void> {
   const host = await startHost({ boot: { persistenceRoot: './.sessions' } })
   const api = new InProcessApiClient(host.handler)
 
-  const created = await unwrap(await api.sessions.create({}), host.dispose)
+  const created = await unwrap(await api.sessions.create({}), () => host.dispose())
 
   // Open the stream before prompting so no frame is lost — kept in this order
   // even though in-process delivery has no race, so the code survives a move
@@ -94,7 +94,7 @@ export async function runHeadless(argv: string[]): Promise<void> {
     sessionId: created.sessionId,
     mode: 'queue',
     content: [{ type: 'text', text: task }],
-  }), host.dispose)
+  }), () => host.dispose())
 
   const outcome = await done
   process.stdout.write(outcome.text + '\n')

apps/cli/src/tui.ts

@@ -0,0 +1,71 @@
+/**
+ * `dsh` default surface — the interactive TUI coding agent. Boots the shipped
+ * tui-agent config (or an explicit config argument) with the personal overlay
+ * from the Harness home (`~/.dsh`): its `.env` fills environment gaps (precedence:
+ * ambient environment, then the invoking directory's `.env`, then the personal one)
+ * and its `config.yaml` patches the booted tree. The workspace is the invoking
+ * directory: sessions, relative paths, and workspace instructions resolve from
+ * the cwd, so `dsh` acts on whatever project it is launched in. After boot, the
+ * agent's system prompt is told the path to this harness checkout so it can find
+ * its own source.
+ * @module @deepseek-ai/dsh/tui
+ */
+
+import { fileURLToPath } from 'node:url'
+import {
+  addHarnessSourceSection,
+  boot,
+  installFailLoud,
+  loadEnv,
+  loadPersonalPatches,
+  parseResumeArg,
+  resolveConfigPath,
+} from '@deepseek-ai/dsh-app-boot'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+
+const NAME = 'dsh'
+
+// The env var the shipped tui-agent config reads (`resumeSessionId: !!js
+// process.env.RESUME_SESSION_ID`) to rehydrate a persisted session. The
+// `--resume <id>` flag is CLI sugar that sets it before boot, so the printed
+// `dsh --resume <id>` exit hint runs back through this same intake.
+const RESUME_SESSION_ID_ENV = 'RESUME_SESSION_ID'
+
+// Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
+// one directory under apps/cli, so the shipped default config resolves with
+// the same relative hop from either artifact.
+const DEFAULT_CONFIG = fileURLToPath(new URL('../../../examples/tui-agent/cordis.yml', import.meta.url))
+
+// The harness checkout root: three hops up from apps/cli/{src,lib}, resolved
+// from this bin's location so it holds however `dsh` is launched (a PATH
+// symlink, an arbitrary cwd). The agent is told where its own source lives.
+const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+
+/* v8 ignore start -- composition over the unit-tested dsh-app-boot helpers;
+   the tui-agent PTY smoke drives this path end to end, personal overlay included */
+/**
+ * Run the interactive TUI from the invoking directory.
+ * @param argv - arguments after the subcommand dispatch; a `--resume <id>` flag
+ * resumes that persisted session, and the first non-flag argument may name a
+ * config to boot instead of the shipped default.
+ */
+export async function runTui(argv: string[]): Promise<void> {
+  // Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree
+  // is logged per-entry rather than rethrown, so a piped launch would
+  // otherwise settle into an idle UI-less process instead of exiting nonzero.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    process.stderr.write(`${NAME}: the TUI requires stdin and stdout to be interactive TTYs\n`)
+    process.exit(1)
+  }
+  installFailLoud(NAME)
+  // The bin already loaded the invoking directory's .env; the personal .env
+  // only fills what is still unset (process.loadEnvFile never overrides).
+  loadEnv(NAME, resolveDshHome())
+  // An explicit `--resume` flag beats any ambient RESUME_SESSION_ID, so set it
+  // after loadEnv and before boot reads it through the config's `!!js`.
+  const { resumeSessionId, rest } = parseResumeArg(argv)
+  if (resumeSessionId !== undefined) process.env[RESUME_SESSION_ID_ENV] = resumeSessionId
+  const ctx = await boot(NAME, resolveConfigPath(rest[0] ?? DEFAULT_CONFIG, undefined), loadPersonalPatches(NAME))
+  addHarnessSourceSection(ctx, SOURCE_ROOT)
+}
+/* v8 ignore stop */

apps/cli/tsconfig.json

@@ -13,6 +13,7 @@
     { "path": "../../packages/host/runtime" },
     { "path": "../../packages/host/webserver" },
     { "path": "../../packages/core/session" },
-    { "path": "../../packages/ui/app-boot" }
+    { "path": "../../packages/ui/app-boot" },
+    { "path": "../../packages/util/paths" }
   ]
 }

apps/cli/tsdown.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * The dsh CLI ships one entry: the `bin` referenced by package.json `bin`.
+ * The root tsdown builds only `lib/types/index.js`, so this override points at
+ * `lib/types/bin.js` instead; the statically imported surface modules bundle
+ * into it. Declarations come from `tsc -b` (dts: false), matching every package.
+ */
+export default defineConfig({
+  entry: ['lib/types/bin.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})

apps/web/tests/smoke-fixture.e2e.ts

@@ -50,12 +50,12 @@ describe('web boot chain (keyless, real carrier)', () => {
       apiHandler,
       webPlugins: {
         snapshot: () => ROWS,
-        clientPath: (id) => (id === ROWS[0]!.id ? LAYOUT_BUNDLE : undefined),
+        clientPath: id => (id === ROWS[0]!.id ? LAYOUT_BUNDLE : undefined),
       },
     }, (err) => { pageErrors.push(`server: ${String(err)}`) })
     browser = await chromium.launch()
     page = await browser.newPage()
-    page.on('pageerror', (e) => pageErrors.push(String(e)))
+    page.on('pageerror', e => pageErrors.push(String(e)))
     await page.goto(`http://127.0.0.1:${port}/`, { waitUntil: 'load' })
   })
 
@@ -92,7 +92,7 @@ describe('web boot chain (keyless, real carrier)', () => {
 })
 
 describe('web boot chain success pass (keyless, five real bundles, ?fixture)', () => {
-  const missing = REAL_PLUGINS.filter((p) => !existsSync(bundlePath(p.dir)))
+  const missing = REAL_PLUGINS.filter(p => !existsSync(bundlePath(p.dir)))
   let server: Awaited<ReturnType<typeof startWebServer>>
   let browser: Browser
   let page: Page
@@ -100,14 +100,14 @@ describe('web boot chain success pass (keyless, five real bundles, ?fixture)', (
 
   beforeAll(async () => {
     requireDist()
-    if (missing.length > 0) throw new Error(`client bundles not built (pnpm --filter <pkg> bundle): ${missing.map((m) => m.dir).join(', ')}`)
+    if (missing.length > 0) throw new Error(`client bundles not built (pnpm --filter <pkg> bundle): ${missing.map(m => m.dir).join(', ')}`)
     const port = await probeFreePort()
     const rows: WebPluginBootEntry[] = REAL_PLUGINS.map((p) => {
       const row: WebPluginBootEntry = { id: p.id, url: `/plugins/${p.id}/client.js`, inject: p.inject }
       if (p.immediately === true) row.immediately = true
       return row
     })
-    const byId = new Map(REAL_PLUGINS.map((p) => [p.id, bundlePath(p.dir)]))
+    const byId = new Map(REAL_PLUGINS.map(p => [p.id, bundlePath(p.dir)]))
     // ?fixture never opens HTTP streams; /api is a tripwire like the first describe.
     const apiHandler = { fetch: () => Promise.resolve(new Response('fixture mode must not call /api', { status: 500 })) }
     server = await startWebServer({
@@ -115,11 +115,11 @@ describe('web boot chain success pass (keyless, five real bundles, ?fixture)', (
       port,
       distIndex: DIST_INDEX,
       apiHandler,
-      webPlugins: { snapshot: () => rows, clientPath: (id) => byId.get(id) },
+      webPlugins: { snapshot: () => rows, clientPath: id => byId.get(id) },
     }, (err) => { pageErrors.push(`server: ${String(err)}`) })
     browser = await chromium.launch()
     page = await browser.newPage()
-    page.on('pageerror', (e) => pageErrors.push(String(e)))
+    page.on('pageerror', e => pageErrors.push(String(e)))
     await page.goto(`http://127.0.0.1:${port}/?fixture`, { waitUntil: 'load' })
   })
 
@@ -133,13 +133,13 @@ describe('web boot chain success pass (keyless, five real bundles, ?fixture)', (
     await page.waitForSelector('[class*="frame"]', { timeout: 15_000 })
     // Loading page is gone; the grid carries the three tracks.
     expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
-    const template = await page.locator('[class*="frame"]').evaluate((el) => getComputedStyle(el).gridTemplateColumns)
+    const template = await page.locator('[class*="frame"]').evaluate(el => getComputedStyle(el).gridTemplateColumns)
     expect(template.split(' ').length).toBe(3)
   })
 
   it('every plugin CSS landed with its ownership tag', async () => {
     const owners = await page.evaluate(() =>
-      [...document.querySelectorAll('style[data-plugin]')].map((s) => (s as HTMLElement).dataset['plugin']))
+      [...document.querySelectorAll('style[data-plugin]')].map(s => (s as HTMLElement).dataset['plugin']))
     expect(owners).toContain('@deepseek-ai/dsh-client-ui-layout')
   })
 

apps/web/tests/smoke-real.e2e.ts

@@ -39,7 +39,7 @@ loadRootEnv()
 function waitForReadyLine(child: ChildProcess): Promise<string> {
   return new Promise((resolveReady, reject) => {
     let out = ''
-    const timer = setTimeout(() => reject(new Error(`dsh web not ready in 90s; output:\n${out}`)), 90_000)
+    const timer = setTimeout(() => { reject(new Error(`dsh web not ready in 90s; output:\n${out}`)) }, 90_000)
     const onData = (chunk: Buffer): void => {
       out += chunk.toString()
       const match = /dsh web: (http:\/\/[^\s]+)/.exec(out)
@@ -65,13 +65,13 @@ async function screen(page: Page, name: string): Promise<void> {
 /** First column track (px string) of the frame grid. */
 async function firstTrack(page: Page): Promise<string> {
   return (await page.locator('[class*="frame"]').evaluate(
-    (el) => getComputedStyle(el).gridTemplateColumns)).split(' ')[0]!
+    el => getComputedStyle(el).gridTemplateColumns)).split(' ')[0]!
 }
 
 /** Last column track (details) as a number of pixels. */
 async function detailsTrack(page: Page): Promise<number> {
   const cols = await page.locator('[class*="frame"]').evaluate(
-    (el) => getComputedStyle(el).gridTemplateColumns)
+    el => getComputedStyle(el).gridTemplateColumns)
   return Number(cols.split(' ').pop()!.replace('px', ''))
 }
 
@@ -146,16 +146,16 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     baseUrl = (await waitForReadyLine(child)).replace('0.0.0.0', '127.0.0.1')
     browser = await chromium.launch()
     page = await browser.newPage({ viewport: { width: 1680, height: 1000 } })
-    page.on('pageerror', (e) => pageErrors.push(String(e)))
+    page.on('pageerror', e => pageErrors.push(String(e)))
     await page.goto(baseUrl, { waitUntil: 'load' })
   }, 120_000)
 
   afterAll(async () => {
     await browser?.close()
     if (child !== undefined && child.exitCode === null) {
-      const gone = new Promise<void>((resolveExit) => child.once('exit', () => resolveExit()))
+      const gone = new Promise<void>(resolveExit => child.once('exit', () => { resolveExit() }))
       child.kill('SIGTERM')
-      await Promise.race([gone, new Promise((r) => setTimeout(r, 10_000).unref())])
+      await Promise.race([gone, new Promise(r => setTimeout(r, 10_000).unref())])
       if (child.exitCode === null) child.kill('SIGKILL')
     }
     if (sessionsDir !== undefined) rmSync(sessionsDir, { recursive: true, force: true })
@@ -165,7 +165,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     onTestFailed(() => saveFailureShot(page, 'w5-cold-start'))
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
     expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
-    const template = await page.locator('[class*="frame"]').evaluate((el) => getComputedStyle(el).gridTemplateColumns)
+    const template = await page.locator('[class*="frame"]').evaluate(el => getComputedStyle(el).gridTemplateColumns)
     expect(template.split(' ').length).toBe(3)
     await screen(page, '01-cold-start')
   })

apps/web/tests/support.ts

@@ -27,10 +27,10 @@ export function probeFreePort(): Promise<number> {
     probe.listen(0, '127.0.0.1', () => {
       const address = probe.address()
       if (address === null || typeof address === 'string') {
-        probe.close(() => reject(new Error('port probe returned no address')))
+        probe.close(() => { reject(new Error('port probe returned no address')) })
         return
       }
-      probe.close(() => resolvePort(address.port))
+      probe.close(() => { resolvePort(address.port) })
     })
   })
 }