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,
+})