Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml # .agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/core.md # docs/core-data-structures/core.zh.md # docs/event-producer-consumer.md # docs/module-graph.md # docs/persistence-catalog.md # examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # examples/acp-agent/tests/snapshots/skill-load/session.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl # examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl # examples/acp-agent/tests/snapshots/workspace-context/session.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl # examples/headless-agent/tests/snapshots/pty-tools/session.jsonl # examples/headless-agent/tests/subagent-inheritance-snapshots/parent-override/child.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/session.1.jsonl # packages/acp/acp/README.i18n.yaml # packages/acp/acp/src/index.ts # packages/client/connection/src/client/index.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/README.md # packages/client/runtime/README.zh.md # packages/client/runtime/src/client/sessions/conversation.ts # packages/client/runtime/src/client/sessions/session.ts # packages/client/runtime/tests/queue-store.spec.ts # packages/client/ui-conversation/src/client/input/contract.ts # packages/client/ui-goal/README.i18n.yaml # packages/compact/compact-basic/src/index.ts # packages/context/time-context/tests/time-context.spec.ts # packages/context/tmux-context/tests/tmux-context.spec.ts # packages/context/workspace-context/tests/workspace-context.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-loop/README.i18n.yaml # packages/core/agent-loop/README.md # packages/core/agent-loop/README.zh.md # packages/core/agent-loop/src/agent.ts # packages/core/agent-loop/tests/agent.spec.ts # packages/core/agent-loop/tests/loop.spec.ts # packages/core/agent/README.i18n.yaml # packages/core/agent/README.md # packages/core/agent/README.zh.md # packages/core/agent/src/types.ts # packages/core/session/README.i18n.yaml # packages/core/session/README.md # packages/core/session/README.zh.md # packages/goal/command-goal/tests/command-goal.spec.ts # packages/goal/goal/tests/goal.spec.ts # packages/goal/tool-goal/README.i18n.yaml # packages/goal/tool-goal/README.md # packages/goal/tool-goal/README.zh.md # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.md # packages/host/apiproxy/README.zh.md # packages/host/apiproxy/src/api-proxy.ts # packages/host/apiproxy/src/api/events.schema.ts # packages/host/apiproxy/src/api/events.ts # packages/host/apiproxy/src/api/rpc.ts # packages/host/apiproxy/tests/api-proxy-commands.spec.ts # packages/host/apiproxy/tests/api-proxy-projections.spec.ts # packages/host/apiproxy/tests/rpc-schemas.spec.ts # packages/pty/pty-local/tests/index.spec.ts # packages/pty/pty-local/tests/local.spec.ts # packages/pty/tool-pty/tests/loader-composition.spec.ts # packages/pty/tool-pty/tests/tools.spec.ts # packages/session-persistence/session-checkpoint-policy/src/index.ts # packages/session-persistence/session-persistence/tests/coordinator-contract.ts # packages/skill/tool-skill/tests/tool-skill.spec.ts # packages/subagent/subagent-inprocess/README.i18n.yaml # packages/subagent/subagent-inprocess/README.md # packages/subagent/subagent-inprocess/README.zh.md # packages/subagent/subagent-inprocess/src/index.ts # packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts # packages/support/acp-snapshot/src/harness.ts # packages/ui/tui/tests/tui.spec.ts
2026-08-03 10:56:09 +08:00
parent b4258a2c4a 8bf606ba80
commit dc1d542092
605 changed files with 25740 additions and 2265 deletions
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -1,6 +1,6 @@
 /**
 * AppCLIEntry — the pre-cordis boot glue the config-tree dsh surfaces share
- * for the Web/headless surface.
+ * (`dsh web` and `dsh -p`; the TUI composes dsh-app-boot directly).
 * Everything here is what must exist before the Loader runs: the patch
 * composition over the shipped base and surface overlay (profile json + CLI
 * flags + the resolved frontend dist), and the fail-loud activation audit after the tree
@@ -16,7 +16,13 @@ import { join, resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
-import { boot, installFailLoud, loadOverlayPatches, loadPersonalPatches } from '@deepseek-ai/dsh-app-boot'
+import {
+  boot,
+  installFailLoud,
+  loadOverlayPatches,
+  loadPersonalPatches,
+  watchPersonalPatches,
+} from '@deepseek-ai/dsh-app-boot'
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'

@@ -140,8 +146,10 @@ export interface AppCLIEntryOptions {
   * `$DSH_HOME/config.yaml` overlay is applied instead.
   */
  extraOverlayPath?: string
-  /** Whether to append the HMR row (the whole prod/dev difference; web surface only). */
+  /** Whether to append client-bundle HMR (the Web surface's prod/dev difference). */
  dev: boolean
+  /** Whether `$DSH_HOME/config.yaml` remains live after the initial boot. */
+  watchPersonalConfig: boolean
  /** --host when explicitly passed; undefined keeps the yml engineering default. */
  host?: string
  /**
@@ -155,6 +163,8 @@ export interface AppCLIEntryOptions {
  workspaceRoot?: string
  /** Extra authorities for the /api browser-trust fence (`host` or `host:port`), appended to the derived LAN IP literals. */
  trustedHosts?: string[]
+  /** Surface setup registered after Loader installation and before any config-tree entry mounts. */
+  prepare?: (ctx: Context) => Promise<void> | void
 }

 /**
@@ -180,8 +190,8 @@ export class AppCLIEntry {
  constructor(private readonly options: AppCLIEntryOptions) {}

  /**
-   * Run the boot chain: patch composition → Loader include boot (dev row
-   * before await) → fail-loud triple.
+   * Run the boot chain: patch composition → Loader installation → surface
+   * preparation → config-tree boot (dev row before await) → fail-loud triple.
   * @returns the settled root context and the listening port.
   */
  async run(): Promise<{ ctx: Context; port: number }> {
@@ -233,11 +243,12 @@ export class AppCLIEntry {
    // user config. Workspace knowledge stays here.
    put('webserver', 'distIndex', this.resolveDistIndex())

-    this.patches = [...overrides.entries()].map(([id, bag]) => {
+    const generated = [...overrides.entries()].map(([id, bag]) => {
      const yml = rows.get(id)
      if (yml === undefined) throw new Error(`dsh: patch target row "${id}" not found in ${this.options.configPath}`)
      return { id, config: { ...(yml.config ?? {}) as Record<string, unknown>, ...bag } }
    })
+    this.patches = generated

    // Telemetry opt-out: a row can only be turned off at the patch layer
    // (config cannot disable an entry), and the switch must hold BEFORE the
@@ -246,22 +257,36 @@ export class AppCLIEntry {
    if (telemetryPatch !== undefined) this.patches.push(telemetryPatch)
  }

-  /** Shared Loader boot; the dev HMR row mounts before await so the activation audit covers it. */
+  /** Shared Loader boot; surface preparation precedes the tree, and the dev HMR row precedes the activation audit. */
  private async bootTree(): Promise<void> {
    // 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 = [
+    const compose = (overlay: PatchOptions[]): PatchOptions[] => [
      ...loadOverlayPatches('dsh', this.options.overlayPath),
-      ...this.options.extraOverlayPath === undefined
-        ? loadPersonalPatches('dsh') ?? []
-        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+      ...overlay,
      ...this.patches,
    ]
+    // An explicit --config overlay REPLACES the personal overlay, so there is
+    // then no personal layer to keep live — the watcher is personal-only.
+    const watchPersonal = this.options.watchPersonalConfig && this.options.extraOverlayPath === undefined
+    const patches = compose(
+      this.options.extraOverlayPath === undefined
+        ? loadPersonalPatches('dsh') ?? []
+        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+    )
    this.ctx = await boot('dsh', resolve(this.options.configPath), patches, async (ctx) => {
+      await this.options.prepare?.(ctx)
+      // Config-only HMR for the personal overlay: module reload stays off for
+      // this surface (web.cordis.yml disables the shared `hmr` row until its
+      // reload lifecycle is tested), so this row watches no module roots.
+      if (watchPersonal) await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
      if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
    })
+    if (watchPersonal) {
+      await watchPersonalPatches(this.ctx, { binName: 'dsh', compose })
+    }
  }

  /** Install the diagnostic for plugin rejections that happen after settled boot. */
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -285,7 +285,7 @@ Examples:
    .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')
+    .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
    .option('--workspace-root <path>', 'parent directory for workspaces created from the browser UI')
    .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
    .option('--dump-config', 'print the composed config tree (base + web + --config/personal overlay) and exit')
--- a/apps/cli/src/headless.ts
+++ b/apps/cli/src/headless.ts
@@ -78,6 +78,7 @@ export async function runHeadless(task: string): Promise<void> {
    configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
    overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
    dev: false,
+    watchPersonalConfig: false,
    port: 0,
  })
  const { ctx, port } = await entry.run()
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -28,8 +28,10 @@ import {
  loadOverlayPatches,
  loadPersonalPatches,
  resolveConfigPath,
+  watchPersonalPatches,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type { PatchOptions } from '@cordisjs/plugin-include'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
 import { SESSION_QUERY_SQLITE_PATH_KEY } from '@deepseek-ai/dsh-session-query-sqlite'
@@ -201,15 +203,16 @@ export async function runTui(
  // presence is checked against the tree actually booting, so a
  // --config-replace tree is judged on its own rows, not the shipped base's.
  const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, configHasTelemetryRow(bootConfig))
-  const patches = [
+  const composePatches = (personalPatches: PatchOptions[]): PatchOptions[] => [
    ...replaceTree ? [] : [
      ...loadOverlayPatches(NAME, TUI_OVERLAY),
      ...resolvedConfig === undefined
-        ? loadPersonalPatches(NAME) ?? []
+        ? personalPatches
        : loadOverlayPatches(NAME, resolveConfigPath(resolvedConfig, undefined)),
    ],
    ...telemetryPatch === undefined ? [] : [telemetryPatch],
  ]
+  const patches = composePatches(loadPersonalPatches(NAME) ?? [])
  const queryIndexPath = join(tmpdir(), SESSION_QUERY_DB)
  const ctx = await boot(
    NAME,
@@ -246,6 +249,14 @@ export async function runTui(
      }
    },
  )
+  // The shipped tree includes HMR and keeps personal config live. An explicit
+  // --config tree replaces the personal overlay (so there is nothing to keep
+  // live), and a --config-replace or HMR-less tree remains a valid composition
+  // that still receives the startup overlay but deliberately has no hidden
+  // watcher.
+  if (resolvedConfig === undefined && !replaceTree && ctx.get('hmr') !== undefined) {
+    await watchPersonalPatches(ctx, { binName: NAME, compose: composePatches })
+  }
  app.current = ctx
  addHarnessSourceSection(ctx, SOURCE_ROOT)
  if (showFirstRunWelcome) {
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -7,23 +7,87 @@
 */

 import { fileURLToPath } from 'node:url'
-import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type { Context } from 'cordis'
+import { addHarnessSourceSection, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tool-bash'
 import { AppCLIEntry } from './app-cli-entry.ts'

 // The shared core every `dsh` surface mounts, plus this surface's overlay over it.
 const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
 const WEB_OVERLAY = fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url))
+const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+
+const DSH_WEB_URL = 'DSH_WEB_URL' as const
+const DSH_WEB_MODE = 'DSH_WEB_MODE' as const
+
+type WebMode = 'production' | 'development'

 // 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.
 const LOOPBACK_HOST = '127.0.0.1'

+/** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
+function webSurfacePrompt(webUrl: string, mode: WebMode): string {
+  const updateContract = mode === 'development'
+    ? 'This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. '
+      + 'No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. '
+      + 'Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. '
+    : 'This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. '
+      + 'If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. '
+  return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. `
+    + 'When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. '
+    + 'The browser provides no implicit DOM, route, or screenshot context. '
+    + updateContract
+    + 'Starting another server does not update this GUI. '
+    + 'The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. '
+    + 'Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.'
+}
+
+/** Resolve the canonical loopback URL from the active Web server. */
+function localWebUrl(ctx: Context): string {
+  const port = ctx.get('httpServer')?.port
+  if (port === undefined) throw new Error('dsh web: httpServer service missing while resolving Web runtime')
+  return `http://${LOOPBACK_HOST}:${String(port)}`
+}
+
+/**
+ * Register the launcher-owned prompt and shell runtime context before the
+ * shared config tree mounts. The earlier injections install the prompt
+ * sections and managed Bash contributor when their owning services activate;
+ * dynamic values read the bound server only when consumed.
+ * @param ctx - Web root context with Loader installed but no config tree mounted.
+ * @param sourceRoot - absolute checkout root resolved from the launcher module.
+ * @param mode - whether this process mounted the client-plugin HMR receiver.
+ */
+export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode: WebMode): void {
+  ctx.inject(['systemPrompt'], (promptCtx) => {
+    addHarnessSourceSection(promptCtx, sourceRoot)
+    promptCtx.systemPrompt.section({
+      name: 'app:web-surface',
+      order: -98,
+      text: () => webSurfacePrompt(localWebUrl(promptCtx), mode),
+    })
+  })
+  ctx.inject(['bashEnv'], (runtimeCtx) => {
+    runtimeCtx.bashEnv.register({
+      name: 'web-runtime',
+      variables: {
+        [DSH_WEB_URL]: { description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session.' },
+        [DSH_WEB_MODE]: { description: 'Web runtime mode: production, or development when the client-plugin HMR receiver is active.' },
+      },
+      resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx), [DSH_WEB_MODE]: mode }),
+    })
+  })
+}
+
 /**
 * Serve the browser UI from the shipped config tree. `host`/`port` are passed
 * through only when the flag was given; absent, the shipped Web overlay value stands.
 * @param host - the bind host, or `undefined` to keep the config default.
 * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
- * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
+ * @param dev - mount the client HMR receiver; `pnpm run dev:web` separately rebuilds watched plugin bundles.
 * @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
@@ -38,17 +102,21 @@ export async function runWeb(
  trustedHosts: string[] | undefined,
  config?: string,
 ): Promise<void> {
+  const mode: WebMode = dev ? 'development' : 'production'
  const entry = new AppCLIEntry({
    configPath: BASE_CONFIG,
    overlayPath: WEB_OVERLAY,
    ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
    dev,
+    prepare: (ctx) => { prepareWebRuntimeContext(ctx, SOURCE_ROOT, mode) },
+    watchPersonalConfig: true,
    ...host !== undefined && { host },
    ...port !== undefined && { port },
    ...workspaceRoot !== undefined && { workspaceRoot },
    ...trustedHosts !== undefined && { trustedHosts },
  })
  const { ctx, port: boundPort } = await entry.run()
+  const resolvedLocalWebUrl = localWebUrl(ctx)

  let exiting = false
  const shutdown = (code: number): void => {
@@ -65,6 +133,5 @@ export async function runWeb(
  // The entry's boot-time snapshot, not a fresh sample: the printed LAN URL
  // must name an address the /api trust fence was configured with.
  const lanCandidate = entry.lanAddresses[0]
-  const localUrl = `http://${LOOPBACK_HOST}:${boundPort}`
-  console.log(`dsh web: ${localUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${boundPort})`}`)
+  console.log(`dsh web: ${resolvedLocalWebUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${boundPort})`}`)
 }