refactor(cli)!: one shared base config with per-surface overlays

`dsh` shipped two config trees that were 43 rows the same: apps/cli/cordis.yml composed web as 74 flat rows, while the TUI booted examples/tui-agent/cordis.yml whose single `@deepseek-ai/dsh-tui-demo` row mounted twelve plugins behind a twenty-key pass-through Config. Neither file was what its location claimed — apps/cli hardcoded the "example" as the product default and the "demo" bundle was the application — and every capability change had to be made twice. - apps/cli/base.cordis.yml holds the 43 shared rows; tui.cordis.yml and web.cordis.yml are patch lists stating only what differs per surface - overlays apply as SIBLING patch lists at one include level, because include patches never cross an include boundary. Precedence: base < surface < (--config | personal ~/.dsh/config.yaml) < launcher flag/profile patches - `--config` now applies an overlay INSTEAD OF the personal one, so a demo or test tree never inherits the user's route; new `--config-replace` boots a file as the entire tree (the old `--config` behaviour). Both survive /resume - vendor/include: index each `insert`ed row as it is added so a later patch can configure or disable it. Upstream built the id index once before the patch loop, leaving every surface-only row — the whole TUI front door — silently unpatchable from user config. Logged as local modification 8 - session identity moves to dsh-agent-loop's CONFIGURED_AGENT_IDENTITIES_KEY; dsh-tui's MAIN_SESSION_ID_KEY is deleted (only the bundle read it) - delete examples/tui-agent, examples/cordis-agent, packages/examples/tui-demo; TUI tests → apps/cli/tests, cordis e2e → packages/cordis/tool-cordis/tests, examples/code-mode survives as an overlay leaf - `dsh web` gains --config, threaded into AppCLIEntry as an extra overlay Three latent defects surfaced and are fixed here: the TUI captured the optional sessionQuery service once at construction and could permanently disable /resume when it won the mount race; the session-store root silently reverted to a project-local ./.sessions; --config-replace was dropped by the resume handoff. Verified by booting each tree through the real Loader (TUI 55 entries, web 75, zero unsettled) rather than reading YAML. All eight terminal snapshots replay byte-identically; 14/14 PTY smoke, 112/112 snapshots, 25/25 doc-sync, hygiene and lint clean.
2026-08-15 21:04:50 +00:00 · 2026-07-29 13:58:21 +08:00
parent e7c0a5b794
commit f290a8b851
182 changed files with 1659 additions and 2400 deletions
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -17,7 +17,7 @@ import type { FiberState } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include, { type PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
-import { assertEntriesLoaded, installFailLoud, loadEnv } from '@deepseek-ai/dsh-app-boot'
+import { assertEntriesLoaded, installFailLoud, loadEnv, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome, resolveSessionsRoot } from '@deepseek-ai/dsh-paths'
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'
@@ -100,8 +100,21 @@ const FIBER_PENDING = 0 as FiberState.PENDING

 /** Constructor facts for one dsh invocation over the shared composition (argv already parsed by the surface bin). */
 export interface AppCLIEntryOptions {
-  /** Absolute path of the shipped cordis.yml. */
+  /** Absolute path of the shared base config the Loader includes. */
  configPath: string
+  /**
+   * Absolute path of this surface's overlay: a patch list applied over
+   * {@link configPath} before this entry's own profile/flag patches. Its rows
+   * are also merge inputs, so a flag override preserves the overlay's other
+   * fields on the same row.
+   */
+  overlayPath: string
+  /**
+   * Optional extra overlay applied after {@link overlayPath} and before this
+   * entry's own profile/flag patches — the `--config` escape for demos and
+   * tests that need a row this surface does not ship.
+   */
+  extraOverlayPath?: string
  /** Whether to append the HMR row (the whole prod/dev difference; web surface only). */
  dev: boolean
  /** --host when explicitly passed; undefined keeps the yml engineering default. */
@@ -223,11 +236,22 @@ export class AppCLIEntry {
    ctx.baseUrl = pathToFileURL(join(resolve(this.options.configPath), '..')).href + '/'
    await ctx.plugin(Loader)
    ctx.loader.builtins.include = Include
+    // One include of the shared base with every overlay as a sibling patch
+    // list: patches never cross an include boundary, so nesting them would
+    // silently stop reaching base rows. The surface overlay applies first, then
+    // this entry's profile-json and CLI-flag patches, which therefore win.
+    const patches = [
+      ...loadOverlayPatches('dsh', this.options.overlayPath),
+      ...this.options.extraOverlayPath === undefined
+        ? []
+        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+      ...this.patches,
+    ]
    await ctx.loader.create({
      name: 'cordis:include',
      config: {
        path: pathToFileURL(resolve(this.options.configPath)).href,
-        ...this.patches.length > 0 ? { patches: this.patches } : {},
+        ...patches.length > 0 ? { patches } : {},
      },
    })
    if (this.options.dev) {
@@ -262,17 +286,39 @@ export class AppCLIEntry {
    }
  }

-  /** Bypass parse of the shipped yml (id → row) for patch-merge inputs; Loader still reads the file itself. */
+  /**
+   * Bypass parse of the base and this surface's overlay (id → row) for
+   * patch-merge inputs; the Loader still reads both files itself. The overlay
+   * wins per row, matching the order its patches are applied in, and its
+   * `insert` rows are indexed too because a flag may target one of them.
+   */
  private parseYmlRows(): Map<string, { config?: unknown }> {
-    const doc = yaml.load(readFileSync(this.options.configPath, 'utf8'), { schema: includeYamlSchema })
-    if (!Array.isArray(doc)) throw new Error(`dsh: ${this.options.configPath} is not a top-level entry list`)
    const rows = new Map<string, { config?: unknown }>()
-    for (const row of doc as { id?: string; config?: unknown }[]) {
-      if (typeof row.id === 'string') rows.set(row.id, row)
+    const files = [this.options.configPath, this.options.overlayPath]
+    if (this.options.extraOverlayPath !== undefined) files.push(this.options.extraOverlayPath)
+    for (const file of files) {
+      for (const row of this.parseRowList(file)) {
+        if (typeof row.id === 'string') rows.set(row.id, row)
+        for (const inserted of row.insert ?? []) {
+          if (typeof inserted.id === 'string') rows.set(inserted.id, inserted)
+        }
+      }
    }
    return rows
  }

+  /**
+   * Parse one entry or patch list, rejecting anything that is not a top-level
+   * array so a malformed file fails here rather than at row lookup.
+   * @param file - absolute path of the config or overlay file.
+   * @returns the parsed top-level entries.
+   */
+  private parseRowList(file: string): { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[] {
+    const doc = yaml.load(readFileSync(file, 'utf8'), { schema: includeYamlSchema })
+    if (!Array.isArray(doc)) throw new Error(`dsh: ${file} is not a top-level entry list`)
+    return doc as { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[]
+  }
+
  /** Profile json under cwd; read-only — never created here, absent = no user config. */
  private readProfile(): Record<string, unknown> {
    let raw: string
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -11,10 +11,15 @@

 import { Command, CommanderError } from 'commander'

-/** Interactive TUI: the default mode. `--config` swaps the tree; `--resume <id>` rehydrates a session. */
+/**
+ * Interactive TUI: the default mode. `--config` applies an overlay over the
+ * shipped composition in place of the personal one, `--config-replace` boots a
+ * file as the whole tree instead, and `--resume <id>` rehydrates a session.
+ */
 interface TuiInvocation {
  mode: 'tui'
  config?: string
+  configReplace?: string
  resume?: string
 }

@@ -69,6 +74,8 @@ interface ListSessionsInvocation {
 */
 interface WebInvocation {
  mode: 'web'
+  /** Overlay of loader patches applied over the shipped web composition. */
+  config?: string
  host?: string
  port?: number
  dev: boolean
@@ -88,6 +95,7 @@ export type DshInvocation =

 /** Raw web-subcommand options straight from Commander. */
 interface WebOptions {
+  config?: string
  host?: string
  port?: string
  dev?: boolean
@@ -104,6 +112,7 @@ interface WebOptions {
 function resolveWeb(options: WebOptions): WebInvocation {
  return {
    mode: 'web',
+    ...options.config !== undefined && { config: options.config },
    ...options.host !== undefined && { host: options.host },
    ...options.port !== undefined && { port: Number(options.port) },
    dev: options.dev === true,
@@ -140,15 +149,16 @@ Examples:
    // subcommand without a positional collision.
    .option('-p, --prompt <task>', 'answer this task without the interactive UI, then exit')
    .option('--resume <id>', 'continue a past session by id (list ids with `dsh ps`)')
-    .option('--config <path>', 'start with an alternate plugin configuration file')
-    .action((options: { config?: string; prompt?: string; resume?: string }) => {
+    .option('--config <path>', 'apply this overlay of loader patches instead of the personal one')
+    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped and personal configuration')
+    .action((options: { config?: string; configReplace?: string; prompt?: string; resume?: string }) => {
      if (options.prompt !== undefined) {
        // A headless prompt owns the invocation; an empty task has nothing to
        // run, and --config/--resume are TUI inputs that must not silently
        // vanish from a headless run.
        if (options.prompt === '') program.error('error: --prompt needs a task')
-        if (options.config !== undefined || options.resume !== undefined) {
-          program.error('error: --prompt takes no --config or --resume')
+        if (options.config !== undefined || options.configReplace !== undefined || options.resume !== undefined) {
+          program.error('error: --prompt takes no --config, --config-replace, or --resume')
        }
        resolved = { mode: 'headless', prompt: options.prompt }
        return
@@ -156,9 +166,15 @@ Examples:
      // An empty --resume= id would silently start a fresh session downstream
      // (agent-loop treats '' as no-resume), so a mistyped resume must fail loud.
      if (options.resume === '') program.error('error: --resume needs a session id')
+      // The two config flags are mutually exclusive: one layers over the shipped
+      // tree, the other discards it, so accepting both would silently drop one.
+      if (options.config !== undefined && options.configReplace !== undefined) {
+        program.error('error: --config and --config-replace are mutually exclusive')
+      }
      resolved = {
        mode: 'tui',
        ...options.config !== undefined && { config: options.config },
+        ...options.configReplace !== undefined && { configReplace: options.configReplace },
        ...options.resume !== undefined && { resume: options.resume },
      }
    })
@@ -168,8 +184,9 @@ Examples:
  // a leaked `--config`/`-p`/`--resume` is a mistyped invocation that must fail
  // loud rather than silently run and drop the input.
  const rejectParentOptions = (command: string): void => {
-    const parent = program.opts<{ config?: string; prompt?: string; resume?: string }>()
-    if (parent.config !== undefined || parent.prompt !== undefined || parent.resume !== undefined) {
+    const parent = program.opts<{ config?: string; configReplace?: string; prompt?: string; resume?: string }>()
+    if (parent.config !== undefined || parent.configReplace !== undefined
+      || parent.prompt !== undefined || parent.resume !== undefined) {
      program.error(`error: ${command} takes none of --config, -p/--prompt, or --resume`)
    }
  }
@@ -208,6 +225,7 @@ Examples:
  // would duplicate a fact this file does not own.
  const web = program.command('web').description('serve the browser UI on the configured host and port')
  web
+    .option('--config <path>', 'apply this overlay of loader patches over the shipped configuration')
    .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
    .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
    .option('--dev', 'developer mode: hot-reload the browser client')
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -30,7 +30,7 @@ const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 switch (invocation.mode) {
  case 'web': {
    const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts)
+    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts, invocation.config)
    break
  }
  case 'headless': {
@@ -40,7 +40,7 @@ switch (invocation.mode) {
  }
  case 'tui': {
    const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, invocation.resume)
+    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
    break
  }
  case 'meta': {
--- a/apps/cli/src/headless.ts
+++ b/apps/cli/src/headless.ts
@@ -76,7 +76,8 @@ async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>,
 export async function runHeadless(task: string): Promise<void> {
  // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
  const entry = new AppCLIEntry({
-    configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
+    configPath: fileURLToPath(new URL('../base.cordis.yml', import.meta.url)),
+    overlayPath: fileURLToPath(new URL('../web.cordis.yml', import.meta.url)),
    dev: false,
    port: 0,
  })
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -25,11 +25,13 @@ import {
  boot,
  installFailLoud,
  loadEnv,
+  loadOverlayPatches,
  loadPersonalPatches,
  resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome, resolveSessionsRoot } from '@deepseek-ai/dsh-paths'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import { CONFIGURED_AGENT_IDENTITIES_KEY } from '@deepseek-ai/dsh-agent-loop'
 import type { Context } from 'cordis'
 import { registerLiveSessions } from './register-session.ts'
 import {
@@ -46,7 +48,18 @@ const NAME = 'dsh'
 // 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 shared core every `dsh` surface mounts, and the TUI's own overlay over
+// it. Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib)
+// sit one directory under apps/cli, so each resolves with the same hop.
+const BASE_CONFIG = fileURLToPath(new URL('../base.cordis.yml', import.meta.url))
+const TUI_OVERLAY = fileURLToPath(new URL('../tui.cordis.yml', import.meta.url))
+
+// The `agents` entry in tui.cordis.yml the TUI drives; the launcher binds its
+// session identity by this config id.
+const MAIN_AGENT_ID = 'main'
+
+/** Filename of the derived `/resume` index, kept beside the session logs. */
+const SESSION_QUERY_DB = 'session-query.db'

 // 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
@@ -93,24 +106,31 @@ export async function runSkillSession(skill: string): Promise<void> {

 /**
 * Run the interactive TUI from the invoking directory.
- * @param config - a config path to boot instead of the shipped default, or
- * `undefined` for the default; already parsed from `--config`.
+ * @param config - an overlay patch list applied over the shared base and the
+ * TUI overlay, REPLACING the personal `~/.dsh/config.yaml` so a named tree never
+ * inherits the user's route, or `undefined` to use the personal overlay;
+ * already parsed from `--config`.
 * @param resumeSessionId - a persisted session id to resume, or `undefined` to
 * mint a fresh one; already parsed and non-empty-validated from `--resume`.
 * Either way the resulting identity reaches the booted app through
- * {@link MAIN_SESSION_ID_KEY}, so no config key selects the session.
+ * {@link CONFIGURED_AGENT_IDENTITIES_KEY}, so no config key selects the session
+ * and an overlay replacing the agent row cannot drop it.
 * @param workspace - a directory to make the workspace instead of the invoking
 * one, or `undefined` to keep the cwd. Only `dsh meta` passes it.
 * @param initialSkill - a bundled skill to auto-invoke as a fresh session's
 * first turn, or `undefined`. Set only by {@link runSkillSession} and ignored
 * on a resume, so it never re-fires; reaches the app through
 * {@link INITIAL_SKILL_KEY}.
+ * @param configReplace - a config path to boot as the ENTIRE tree, bypassing the
+ * shared base, the TUI overlay, and the personal overlay alike, or `undefined`
+ * to compose them; already parsed from `--config-replace`.
 */
 export async function runTui(
  config: string | undefined,
  resumeSessionId: string | undefined,
  workspace?: string,
  initialSkill?: string,
+  configReplace?: 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
@@ -150,7 +170,13 @@ export async function runTui(
  const resumeArgs = (sessionId: string, targetCwd?: string): string[] =>
    workspace !== undefined && (targetCwd === undefined || targetCwd === workspace)
      ? ['meta', `--resume=${sessionId}`]
-      : [`--resume=${sessionId}`, ...config !== undefined ? ['--config', config] : []]
+      : [
+        `--resume=${sessionId}`,
+        // Both config flags must survive the handoff: resuming into a different
+        // tree than the session was created in would silently change the agent.
+        ...config !== undefined ? ['--config', config] : [],
+        ...configReplace !== undefined ? ['--config-replace', configReplace] : [],
+      ]
  // Mint the fresh id here rather than in the app bundle: the exit line names
  // the session to resume, so the launcher must know it before the tree boots.
  const identity: MainSessionIdentity = resumeSessionId === undefined
@@ -186,10 +212,25 @@ export async function runTui(
      }
    },
  }
+  // One include of the shared base, with every overlay applied as a sibling
+  // patch list: patches never cross an include boundary, so stacking these as
+  // nested includes would silently stop reaching base rows. Later lists win.
+  //
+  // `--config` REPLACES the personal overlay rather than layering under it: an
+  // explicitly named tree must not inherit `~/.dsh/config.yaml`'s route, or a
+  // demo or test config would silently run on the user's provider and model.
+  // `--config-replace` additionally discards the base and the surface overlay.
+  const replaceTree = configReplace !== undefined
+  const patches = replaceTree ? [] : [
+    ...loadOverlayPatches(NAME, TUI_OVERLAY),
+    ...config === undefined
+      ? loadPersonalPatches(NAME) ?? []
+      : loadOverlayPatches(NAME, resolveConfigPath(config, undefined)),
+  ]
  const ctx = await boot(
    NAME,
-    resolveConfigPath(config ?? DEFAULT_CONFIG, undefined),
-    loadPersonalPatches(NAME),
+    replaceTree ? resolveConfigPath(configReplace, undefined) : BASE_CONFIG,
+    patches,
    (hostCtx) => {
      // The launcher owns session identity and the exit line: a config-mounted
      // app bundle reads both from these slots, so no cordis.yml key can drop
@@ -200,6 +241,13 @@ export async function runTui(
      // the Harness home across every cwd, so /resume and list-sessions see
      // every workspace. The bundle treats the slot as opaque.
      hostCtx.provide(SESSIONS_ROOT_KEY, launcherSessionsRoot())
+      // The agent-loop row reads this to bind `main`, and the tui row reads the
+      // same id, so a personal overlay repointing the model route cannot drop
+      // the session identity or desynchronise the two.
+      hostCtx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, { [MAIN_AGENT_ID]: identity })
+      // The launcher owns the session store location, so it also owns the
+      // derived index path that must sit beside those logs.
+      hostCtx.provide('launcherSessionQueryPath', join(launcherSessionsRoot(), SESSION_QUERY_DB))
      if (resumeHost !== undefined) hostCtx.provide('tuiResumeHost', resumeHost)
      // Seed the first turn only for a fresh session, so resuming never
      // re-invokes the skill.
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -7,10 +7,13 @@
 */

 import { fileURLToPath } from 'node:url'
+import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { AppCLIEntry } from './app-cli-entry.ts'
 import { registerLiveSessions } from './register-session.ts'

-const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+// The shared core every `dsh` surface mounts, plus this surface's overlay over it.
+const BASE_CONFIG = fileURLToPath(new URL('../base.cordis.yml', import.meta.url))
+const WEB_OVERLAY = fileURLToPath(new URL('../web.cordis.yml', import.meta.url))

 // Display-only mirror of the webserver schema's loopback host: the address the
 // local URL always prints. Not a source of truth — the schema is.
@@ -24,6 +27,8 @@ const LOOPBACK_HOST = '127.0.0.1'
 * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
 * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
 * @param trustedHosts - extra authorities for the /api browser-trust fence, or `undefined` for the derived LAN literals alone.
+ * @param config - an overlay of loader patches applied over the shipped web
+ * composition, or `undefined` for none; already parsed from `--config`.
 */
 export async function runWeb(
  host: string | undefined,
@@ -31,9 +36,12 @@ export async function runWeb(
  dev: boolean,
  workspaceRoot: string | undefined,
  trustedHosts: string[] | undefined,
+  config?: string,
 ): Promise<void> {
  const entry = new AppCLIEntry({
-    configPath: CONFIG_PATH,
+    configPath: BASE_CONFIG,
+    overlayPath: WEB_OVERLAY,
+    ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
    dev,
    ...host !== undefined && { host },
    ...port !== undefined && { port },