Merge remote-tracking branch 'origin/fix/web-agent-runtime-context' into worktree/pr830-retarget-review-20260801

# Conflicts: # apps/cli/src/web.ts
2026-08-15 21:04:50 +00:00 · 2026-08-02 00:56:14 +08:00
parent 0758839b00 6cd9fefe88
commit 00f156fcde
7 changed files with 94 additions and 38 deletions
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
-2026-07-28-web-agent-runtime-context.md: 8423f2d5542b7f9c841ecbf354fbea2e25699d13
-2026-07-28-web-agent-runtime-context.zh.md: cfb754bd92836142556638e9195050dfc282146e
+2026-07-28-web-agent-runtime-context.md: 449c9d4ba2b144d02dee4b98ae80c86815aec5c1
+2026-07-28-web-agent-runtime-context.zh.md: def1674be5f193739bfb214a24f34590ee075d5f
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
@@ -10,13 +10,13 @@ The shared CLI base configured an empty deployment persona, the Web overlay did

 ## Decision

-The shared Web/headless overlay (`apps/cli/config/web.cordis.yml`) supplies a concise coding-agent persona containing the resolved `{{model}}` and session `{{cwd}}`. `dsh web` additionally resolves the harness checkout from the launcher's module URL, installs the existing `harness:source` section, and adds an `app:web-surface` section before serving requests. The [source-checkout/workdir decision](2026-07-30-source-checkout-workdir-distinction.md) owns the source section's wording and its warning not to infer one path from the other.
+The shared Web/headless overlay (`apps/cli/config/web.cordis.yml`) supplies a concise coding-agent persona containing the resolved `{{model}}` and session `{{cwd}}`. `dsh web` additionally resolves the harness checkout from the launcher's module URL, installs the existing `harness:source` section, and adds an `app:web-surface` section before serving requests. The launcher registers that setup before mounting the config tree; its `systemPrompt` injection therefore installs both sections before later prompt consumers such as the agent loop can activate and emit a request header. The [source-checkout/workdir decision](2026-07-30-source-checkout-workdir-distinction.md) owns the source section's wording and its warning not to infer one path from the other.

 The Web section treats unqualified references to “this page,” “this GUI,” or “this app” as references to the DeepSeek Harness Web GUI. It also states that the browser provides no implicit DOM, route, or screenshot context, so the model can identify the product without claiming visual state it did not receive. The assembled text is logged in `request/header`, preserving the model-visible/logged invariant.

 ## Verification

-The keyless fresh-round-trip Web scenario boots the shipped base plus Web overlay, installs the same launcher context as `dsh web`, runs a real session through the HTTP/SSE application, and snapshots the first four system-prompt sections with source and working-directory paths normalized. The snapshot pins the harness identity, source checkout, Web orientation, and resolved coding-agent persona in request order.
+The focused startup-order test registers a later `systemPrompt` consumer and proves that it observes both launcher sections on its first activation. The keyless fresh-round-trip Web scenario boots the shipped base plus Web overlay, registers the same launcher context as `dsh web`, runs a real session through the HTTP/SSE application, and snapshots the first four system-prompt sections with source and working-directory paths normalized. The snapshot pins the harness identity, source checkout, Web orientation, and resolved coding-agent persona in request order.

 ## Alternatives considered

--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
@@ -10,13 +10,13 @@ CLI 共享 base 配置了空的部署 persona，Web overlay 没有替换它，

 ## 决策

-`apps/cli/config/web.cordis.yml` 这份 Web／无头共享 overlay 提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`。`dsh web` 还会根据启动器模块的 URL 解析 harness checkout，安装现有的 `harness:source` 提示词段，并在对外提供请求服务前添加 `app:web-surface` 提示词段。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
+`apps/cli/config/web.cordis.yml` 这份 Web／无头共享 overlay 提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`。`dsh web` 还会根据启动器模块的 URL 解析 harness checkout，安装现有的 `harness:source` 提示词段，并在对外提供请求服务前添加 `app:web-surface` 提示词段。启动器会在挂载配置树前注册这项设置；因此，它的 `systemPrompt` 注入会在 agent loop（智能体循环）等后续提示词消费方激活并发出 request header 之前安装这两个提示词段。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。

 Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应用」解释为 DeepSeek Harness Web GUI。同时，它会明确说明浏览器不会隐式提供 DOM、路由或截图上下文，使模型能够识别产品，但不会声称掌握未收到的视觉状态。组装后的文本会记录在 `request/header` 中，从而保持「模型可见内容必须有日志记录」这一不变量。

 ## 验证

-无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web overlay，安装与 `dsh web` 相同的启动器上下文，并通过 HTTP／SSE 应用运行一个真实会话。测试会把源码路径和工作目录规范化，然后对系统提示词的前四个段落生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。
+聚焦启动顺序的测试会注册一个后续的 `systemPrompt` 消费方，并证明该消费方首次激活时就能观察到启动器的两个提示词段。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web overlay，注册与 `dsh web` 相同的启动器上下文，并通过 HTTP／SSE 应用运行一个真实会话。测试会把源码路径和工作目录规范化，然后对系统提示词的前四个段落生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。

 ## 考虑过的替代方案

--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -155,6 +155,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 +182,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 }> {
@@ -246,7 +248,7 @@ 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
@@ -260,6 +262,7 @@ export class AppCLIEntry {
      ...this.patches,
    ]
    this.ctx = await boot('dsh', resolve(this.options.configPath), patches, async (ctx) => {
+      await this.options.prepare?.(ctx)
      if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
    })
  }
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -9,6 +9,7 @@
 import { fileURLToPath } from 'node:url'
 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'
@@ -23,6 +24,10 @@ 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'
@@ -40,36 +45,50 @@ function webSurfacePrompt(webUrl: string, mode: WebMode): string {
    + '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)}`
+}
+
 /**
- * Add launcher-owned source, Web-surface orientation, and the shell-visible
- * canonical URL after the shared config tree settles. The request header logs
- * the model-visible sections; each bash execution receives the same URL through
- * the managed environment.
- * @param ctx - settled Web application context.
+ * 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 webUrl - canonical loopback URL printed by this Web process.
 * @param mode - whether this process mounted the client-plugin HMR receiver.
 */
-export function installWebPromptContext(ctx: Context, sourceRoot: string, webUrl: string, mode: WebMode): void {
-  const systemPrompt = ctx.get('systemPrompt')
-  if (systemPrompt === undefined) throw new Error('dsh web: systemPrompt service missing after settled boot')
-  const bashEnv = ctx.get('bashEnv')
-  if (bashEnv === undefined) throw new Error('dsh web: bashEnv service missing after settled boot')
-  addHarnessSourceSection(ctx, sourceRoot)
-  systemPrompt.section({ name: 'app:web-surface', order: -98, text: webSurfacePrompt(webUrl, mode) })
-  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]: webUrl, [DSH_WEB_MODE]: mode }),
+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 }),
+    })
  })
 }

-// 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'
+/**
+ * Fail a settled Web boot whose composition omitted the managed Bash environment registry.
+ * @param ctx - settled Web application context.
+ */
+export function assertWebRuntimeContext(ctx: Context): void {
+  if (ctx.get('bashEnv') === undefined) throw new Error('dsh web: bashEnv service missing after settled boot')
+}

 /**
 * Serve the browser UI from the shipped config tree. `host`/`port` are passed
@@ -91,20 +110,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) },
    ...host !== undefined && { host },
    ...port !== undefined && { port },
    ...workspaceRoot !== undefined && { workspaceRoot },
    ...trustedHosts !== undefined && { trustedHosts },
  })
  const { ctx, port: boundPort } = await entry.run()
-  const localUrl = `http://${LOOPBACK_HOST}:${boundPort}`
-  const mode: WebMode = dev ? 'development' : 'production'
-  installWebPromptContext(ctx, SOURCE_ROOT, localUrl, mode)
+  assertWebRuntimeContext(ctx)
+  const resolvedLocalWebUrl = localWebUrl(ctx)

  let exiting = false
  const shutdown = (code: number): void => {
@@ -121,5 +141,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]
-  console.log(`dsh web: ${localUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${boundPort})`}`)
+  console.log(`dsh web: ${resolvedLocalWebUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${boundPort})`}`)
 }
--- a/apps/cli/tests/web-prompt-context.spec.ts
+++ b/apps/cli/tests/web-prompt-context.spec.ts
@@ -0,0 +1,32 @@
+import { sep } from 'node:path'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import { HARNESS_SOURCE_SECTION } from '@deepseek-ai/dsh-app-boot'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { prepareWebRuntimeContext } from '../src/web.ts'
+
+describe('prepareWebRuntimeContext', () => {
+  it('installs both sections before a later systemPrompt consumer activates', async () => {
+    const ctx = new Context()
+    const sourceRoot = `${sep}opt${sep}harness-src`
+    let observedSections: { name: string; text: string }[] | undefined
+    try {
+      prepareWebRuntimeContext(ctx, sourceRoot, 'production')
+      ctx.provide('httpServer', { port: 3080 } as Context['httpServer'])
+      const consumer = ctx.inject(['systemPrompt'], async (promptCtx) => {
+        const assembly = await promptCtx.systemPrompt.assemble()
+        observedSections = assembly.sections
+      })
+
+      await ctx.plugin(SystemPrompt, { persona: 'You are a coding agent.' })
+      await consumer
+
+      expect(observedSections?.map(section => section.name)).toContain(HARNESS_SOURCE_SECTION)
+      expect(observedSections?.find(section => section.name === 'app:web-surface')?.text)
+        .toContain('http://127.0.0.1:3080')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -53,7 +53,7 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 // Empty type imports carry the httpServer/agents/sessionPersistence Context merges.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-agent'
-import { installWebPromptContext } from '../../cli/src/web.ts'
+import { assertWebRuntimeContext, prepareWebRuntimeContext } from '../../cli/src/web.ts'
 import { DIST_INDEX, REPO_ROOT, requireDist } from './support.ts'

 /** Snapshot mode for the lane, from $DSH_SNAPSHOT (same vocabulary as the ACP/TUI suites). */
@@ -301,6 +301,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
    // The shipped CLI deliberately has no dependency on this opt-in package.
    // Keep the Loader row real without broadening the product installation.
    if (options.cordisTools === true) ctx.loader.builtins['tool-cordis'] = ToolCordis
+    prepareWebRuntimeContext(ctx, REPO_ROOT, 'production')
    await ctx.loader.create({
      name: 'cordis:include',
      config: { path: pathToFileURL(resolve(CONFIG_PATH)).href, patches },
@@ -317,7 +318,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
      throw new Error('web e2e scaffold: httpServer service missing after settled boot')
    }
    port = boundPort
-    installWebPromptContext(ctx, REPO_ROOT, `http://127.0.0.1:${String(port)}`, 'production')
+    assertWebRuntimeContext(ctx)

    // Fill the open llm seam on the settled root ctx. Ordinary keyless modes
    // disable llm-deepseek; the first-run lane keeps it mounted but has no