From 568866d5a8d28223ba266ddeb9d6d7792be9aad5 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 17:20:20 +0800 Subject: [PATCH 001/689] fix(web): orient agents to the running GUI --- ...-07-28-web-agent-runtime-context.i18n.yaml | 6 ++++ .../2026-07-28-web-agent-runtime-context.md | 33 +++++++++++++++++++ ...2026-07-28-web-agent-runtime-context.zh.md | 33 +++++++++++++++++++ apps/cli/README.i18n.yaml | 6 ++-- apps/cli/README.md | 2 +- apps/cli/README.zh.md | 2 +- apps/cli/cordis.yml | 3 +- apps/cli/src/web.ts | 24 ++++++++++++++ apps/web/tests/replay-round-trip.e2e.ts | 22 +++++++++++-- apps/web/tests/scaffold.ts | 2 ++ .../system-prompt.expected.md | 7 ++++ 11 files changed, 131 insertions(+), 9 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md create mode 100644 apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md diff --git 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 new file mode 100644 index 0000000000..fdf6fbca4e --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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: 7e2e0beb4057db2533d8360e39b46199900f067b +2026-07-28-web-agent-runtime-context.zh.md: add98653d24b7bde84982ca23bb60cdb234f98d0 diff --git 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 new file mode 100644 index 0000000000..7e2e0beb40 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md @@ -0,0 +1,33 @@ +# Agent Note: Web agents receive explicit runtime context + +Status: implemented + +English | [中文](2026-07-28-web-agent-runtime-context.zh.md) + +## Problem + +The Web composition configured an empty deployment persona and added no launcher-owned source or interaction-surface section. A session header recorded its working directory for tools and persistence, but the model prompt did not state that directory or identify the DeepSeek Harness Web GUI. A request such as “change this page's theme” therefore made the agent search the selected project for an unspecified page, even when the user meant the GUI running the session. + +## Decision + +The shared Web/headless composition 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 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 composition, 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. + +## Alternatives considered + +**Send URL, DOM, or screenshots with every prompt.** The observed failure needed stable product orientation, while the current root URL does not identify a selected component and no visual capture exists in the message contract. Adding dynamic page state would require a separate logged model-input design and is not implied by this fix. + +**Require the session Workspace to be the harness checkout.** Workspace cwd is the user's task target and may legitimately be an empty project or another repository. Conflating it with the application's source location would break that boundary and leave installed or externally launched sessions ambiguous. + +**Put Web wording in the global harness identity.** `dsh-system-prompt` serves TUI, ACP, SDK, and custom deployments that do not run in a browser. The composing Web app owns this surface fact. + +**Change the existing source-location section for every CLI surface.** The source section is shared with TUI and states only the checkout fact. Keeping Web orientation separate preserves that reusable contract and avoids telling headless or terminal agents that they are in a browser. + +## Consequences + +Web requests gain a short stable prompt prefix and may invalidate provider prefix caches once when this change is deployed. Agents can distinguish the GUI source checkout from the selected Workspace and resolve ordinary references to the current app without a clarification round trip. References to a specific visual state remain bounded by the explicit no-DOM/no-route/no-screenshot statement and may still require a path, description, or attachment. diff --git 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 new file mode 100644 index 0000000000..add98653d2 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md @@ -0,0 +1,33 @@ +# Agent Note: Web agent 获得显式运行时上下文 + +Status: implemented + +[English](2026-07-28-web-agent-runtime-context.md) | 中文 + +## 问题 + +Web 组合把部署 persona 配置为空，也没有添加由启动器拥有的源码位置或交互界面提示词段。会话 header 会记录工作目录，供工具与持久化使用，但模型提示词既不说明该目录，也不标识 DeepSeek Harness Web GUI。因此，当用户提出「修改这个页面的主题」之类的请求时，即使用户指的是承载当前会话的 GUI，agent 也只能在所选项目中搜索一个未明确说明的页面。 + +## 决策 + +Web／无头共享组合提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`。`dsh web` 还会根据启动器模块的 URL 解析 harness checkout，安装现有的 `harness:source` 提示词段，并在对外提供请求服务前添加 `app:web-surface` 提示词段。 + +Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应用」解释为 DeepSeek Harness Web GUI。同时，它会明确说明浏览器不会隐式提供 DOM、路由或截图上下文，使模型能够识别产品，但不会声称掌握未收到的视觉状态。组装后的文本会记录在 `request/header` 中，从而保持「模型可见内容必须有日志记录」这一不变量。 + +## 验证 + +无密钥的 Web fresh-round-trip 场景会启动已交付组合，安装与 `dsh web` 相同的启动器上下文，并通过 HTTP／SSE 应用运行一个真实会话。测试会把源码路径和工作目录规范化，然后对系统提示词的前四个段落生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。 + +## 考虑过的替代方案 + +**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息契约中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。 + +**要求会话 Workspace 必须是 harness checkout。** Workspace cwd 是用户任务的目标，可以合理地指向空项目或其他仓库。将其与应用源码位置混为一谈会破坏这一边界，并且仍无法消除已安装版本或外部启动会话中的歧义。 + +**把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。 + +**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用契约，避免错误地告诉无头或终端 agent 它们正处于浏览器中。 + +## 影响 + +Web 请求会增加一段较短且稳定的提示词前缀；部署此变更时，模型提供方的前缀缓存可能失效一次。agent 可以区分 GUI 源码 checkout 与所选 Workspace，并且无需再经过一轮澄清即可解析对当前应用的一般指代。对特定视觉状态的指代仍受「无 DOM／无路由／无截图」这一显式边界约束，必要时仍需用户提供路径、描述或附件。 diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml index abe51abc2f..d1c6290a08 100644 --- a/apps/cli/README.i18n.yaml +++ b/apps/cli/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -README.md: 42d2a9641cf5d497c9aae45d9f60fce4498addb9 -README.zh.md: 0a62f8bb72e2cf2dbe045d28b81768bf4df800de +# pnpm run verify-translation-pairing --write apps/cli/README.md +README.md: 87cf1597fbb1ce91a7d61f912c42b0d6a68b2eea +README.zh.md: b3743f57a4dafda71e437a04ee0148b32dba2dca diff --git a/apps/cli/README.md b/apps/cli/README.md index 42d2a9641c..87cf1597fb 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -14,7 +14,7 @@ The TUI surface: - 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. -The Web and headless surfaces boot one shared composition (`cordis.yml`): both treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). +The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface and this checkout as its own source location; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). `DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode). diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md index 0a62f8bb72..b3743f57a4 100644 --- a/apps/cli/README.zh.md +++ b/apps/cli/README.zh.md @@ -14,7 +14,7 @@ TUI 界面： - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它； - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`.env` 填补环境缺口（环境中已有的值 > 项目 `.env` > 个人 `.env`），`config.yaml` 则修补已启动的树。 -Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root ` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。 +Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root ` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI，并把当前 checkout 标记为自身源码位置；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。 `DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。 diff --git a/apps/cli/cordis.yml b/apps/cli/cordis.yml index 5397c08746..b54200247b 100644 --- a/apps/cli/cordis.yml +++ b/apps/cli/cordis.yml @@ -40,7 +40,8 @@ - id: system-prompt name: '@deepseek-ai/dsh-system-prompt' config: - persona: '' + persona: >- + You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}. - id: tools name: '@deepseek-ai/dsh-tools' diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts index 31282c8f5f..599d788d89 100644 --- a/apps/cli/src/web.ts +++ b/apps/cli/src/web.ts @@ -8,9 +8,32 @@ import { networkInterfaces } from 'node:os' import { fileURLToPath } from 'node:url' +import type { Context } from 'cordis' +import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot' +import type {} from '@deepseek-ai/dsh-system-prompt' import { AppCLIEntry } from './app-cli-entry.ts' const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url)) +const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url)) + +/** Stable model-visible orientation for sessions created through `dsh web`. */ +export const WEB_SURFACE_PROMPT = 'You are interacting with the user through the DeepSeek Harness Web GUI. ' + + '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.' + +/** + * Add the launcher-owned source location and Web-surface orientation after the + * shared config tree settles. The request header logs both sections with every + * model-visible prompt. + * @param ctx - settled Web application context. + * @param sourceRoot - absolute checkout root resolved from the launcher module. + */ +export function installWebPromptContext(ctx: Context, sourceRoot: string): void { + const systemPrompt = ctx.get('systemPrompt') + if (systemPrompt === undefined) throw new Error('dsh web: systemPrompt service missing after settled boot') + addHarnessSourceSection(ctx, sourceRoot) + systemPrompt.section({ name: 'app:web-surface', order: -98, text: WEB_SURFACE_PROMPT }) +} // Display-only mirrors of the webserver schema's allowed hosts: the loopback // address the local URL always prints, and the all-interfaces value that gates @@ -40,6 +63,7 @@ export async function runWeb( ...workspaceRoot !== undefined && { workspaceRoot }, }) const { ctx, port: boundPort } = await entry.run() + installWebPromptContext(ctx, SOURCE_ROOT) let exiting = false const shutdown = (code: number): void => { diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts index f4cf960cda..222bb28580 100644 --- a/apps/web/tests/replay-round-trip.e2e.ts +++ b/apps/web/tests/replay-round-trip.e2e.ts @@ -9,20 +9,22 @@ // Record: DSH_SNAPSHOT=record rewrites session.jsonl, then a keyless // DSH_SNAPSHOT=refresh regenerates ui.expected.md. import { readFile } from 'node:fs/promises' +import { join } from 'node:path' import { fileURLToPath } from 'node:url' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' -import type { SessionEvent } from '@deepseek-ai/dsh-session' +import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session' import { assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold, } from './scaffold.ts' -import { connectFreshWorkspace, saveFailureShot } from './support.ts' +import { connectFreshWorkspace, REPO_ROOT, saveFailureShot } from './support.ts' const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/fresh-round-trip', import.meta.url)) const FIXTURE = fileURLToPath(new URL('./snapshots/fresh-round-trip/session.jsonl', import.meta.url)) const UI_EXPECTED = fileURLToPath(new URL('./snapshots/fresh-round-trip/ui.expected.md', import.meta.url)) +const SYSTEM_PROMPT_EXPECTED = fileURLToPath(new URL('./snapshots/fresh-round-trip/system-prompt.expected.md', import.meta.url)) const MODE = webSnapshotMode() // The scenario's one drive prompt. Record sends it; replay asserts the @@ -35,6 +37,7 @@ describe('web e2e: fresh round trip through the real assembly', () => { let browser: Browser let page: Page let tripwire: ReturnType + let settledSessionId: SessionId | undefined const sessionEvents: SessionEvent[] = [] beforeAll(async () => { @@ -69,11 +72,24 @@ describe('web e2e: fresh round trip through the real assembly', () => { await input.fill(PROMPT) await input.press('Enter') const sessionId = await settled + settledSessionId = sessionId if (MODE === 'record') { await recordFixture(scaffold, sessionId, FIXTURE) } }, 200_000) + it('records the Web surface, source checkout, and session cwd in the request header', async () => { + if (settledSessionId === undefined) throw new Error('the drive turn did not publish a session id') + const agent = scaffold.ctx.agents.get(settledSessionId) + if (agent === undefined) throw new Error(`the settled Web agent ${settledSessionId} is no longer live`) + const system = agent.session.requestHeader()?.system + if (system === undefined) throw new Error('the settled Web request has no system prompt') + const prefix = system.split('\n\n').slice(0, 4).join('\n\n') + .split(REPO_ROOT).join('{{sourceRoot}}') + .split(join(scaffold.workspaceCwd, 'workspace')).join('{{cwd}}') + await compareOrRefreshGolden(SYSTEM_PROMPT_EXPECTED, prefix, MODE) + }) + it.skipIf(MODE === 'record')('rendered the settled turn: markdown, tool row, composer restore', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-round-trip-settled')) // Browser settled-poll after host completion (host strictly precedes render). @@ -129,6 +145,6 @@ describe('web e2e: fresh round trip through the real assembly', () => { it.skipIf(MODE === 'record')('stayed clean: no pageerrors, no reconnect self-healing, no server errors', async () => { expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl', 'ui.expected.md']) + await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl', 'system-prompt.expected.md', 'ui.expected.md']) }) }) diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index f722ead61b..ac360f38f2 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -44,6 +44,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 { DIST_INDEX, REPO_ROOT, requireDist } from './support.ts' /** Snapshot mode for the lane, from $DSH_SNAPSHOT (same vocabulary as the ACP/TUI suites). */ @@ -202,6 +203,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise Date: Tue, 28 Jul 2026 17:31:48 +0800 Subject: [PATCH 002/689] fix(web): keep surface prompt module-private --- apps/cli/src/web.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts index 599d788d89..67da6c73e8 100644 --- a/apps/cli/src/web.ts +++ b/apps/cli/src/web.ts @@ -17,7 +17,7 @@ const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url)) const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url)) /** Stable model-visible orientation for sessions created through `dsh web`. */ -export const WEB_SURFACE_PROMPT = 'You are interacting with the user through the DeepSeek Harness Web GUI. ' +const WEB_SURFACE_PROMPT = 'You are interacting with the user through the DeepSeek Harness Web GUI. ' + '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.' From 544d543ad168312353457e785bf4851df4aed4fc Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 18:04:21 +0800 Subject: [PATCH 003/689] fix(web): close the GUI update feedback loop --- ...2026-07-28-web-gui-feedback-loop.i18n.yaml | 6 +++ .../2026-07-28-web-gui-feedback-loop.md | 37 +++++++++++++++++ .../2026-07-28-web-gui-feedback-loop.zh.md | 37 +++++++++++++++++ apps/cli/README.i18n.yaml | 4 +- apps/cli/README.md | 2 +- apps/cli/README.zh.md | 2 +- apps/cli/src/web.ts | 41 ++++++++++++++----- apps/cli/tsconfig.json | 3 ++ apps/web/package.json | 2 +- apps/web/tests/replay-round-trip.e2e.ts | 21 ++++++++++ apps/web/tests/scaffold.ts | 2 +- .../system-prompt.expected.md | 2 +- apps/web/tests/vite-entry.e2e.ts | 29 +++++++++++++ apps/web/vite.config.ts | 17 +++++++- .../host/webserver/tests/webserver.spec.ts | 2 + 15 files changed, 188 insertions(+), 19 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md create mode 100644 apps/web/tests/vite-entry.e2e.ts diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml new file mode 100644 index 0000000000..22390d728f --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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-gui-feedback-loop.md +2026-07-28-web-gui-feedback-loop.md: 27295704d7b0cde3a46a6a28891545bfe31ed275 +2026-07-28-web-gui-feedback-loop.zh.md: 06367b09bd889bfb7a4052c46369720c4ec6d358 diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md new file mode 100644 index 0000000000..27295704d7 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md @@ -0,0 +1,37 @@ +# Agent Note: Web GUI changes close the loop on the existing URL + +Status: implemented + +English | [中文](2026-07-28-web-gui-feedback-loop.zh.md) + +## Problem + +The Web agent could identify neither the GUI hosting its session nor the URL the user was viewing. The [runtime-context decision](2026-07-28-web-agent-runtime-context.md) supplies the first fact, but a GUI edit still had no executable acceptance target: source edits, artifact builds, a listening process, and the user's existing page were unrelated observations. Repository affordances made a wrong substitute look valid because `apps/web/package.json` exposed `vite` as its `dev` script and bare Vite returned HTTP 200 even though it could not inject `window.__DSH_BOOT__`. + +The incident session recorded three consecutive failures. After changing the theme, turn 2 delegated acceptance to the user with `pnpm run demo:tui` or an unspecified browser application and ran no assembled Web check. Turn 3 read the frontend package script, launched bare Vite on port 5173, treated HTTP 200 as readiness, and reported success; the user instead received the expected missing-`__DSH_BOOT__` white screen. Turn 4 found `dsh web`, rebuilt the shell, started an unmanaged shell-background process on port 3334, and checked only that the new page returned 200 with a boot manifest. It never probed the existing port 3081. In fact, the port-3081 process predated the build, and its static host read the rebuilt dist on the next request, so refreshing the original page already showed the change. Only after the user reported that fact did turn 5 inspect port 3081 and remove the redundant server. + +## Decision + +`dsh web` publishes one canonical loopback URL as both model-visible orientation and a managed shell fact. The `app:web-surface` prompt section says that unqualified references identify this GUI, names the URL, and defines acceptance as rebuilding the affected Web artifacts and verifying that existing URL after refresh. `DSH_WEB_URL` carries the same value into every foreground or managed background bash call, so the agent can query the target without parsing prose or process listings. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address. + +The `apps/web` development script and Vite configuration reject serve mode before opening a port. Their diagnostics identify `apps/web` as a build-only shell, explain that only `dsh web` injects `window.__DSH_BOOT__`, and name the production and HMR entry paths. Vite build mode remains unchanged. + +No server restart or replacement is required merely because static artifacts changed. The host reads `index.html` and static assets on each request, while client bundles are also served from their current files with `no-cache`; a refresh of the existing URL is therefore the acceptance path after the relevant shell and plugin bundles are rebuilt. Starting a separate server proves only that a separate server works. If the user explicitly requests another long-running server, the existing managed background-task contract owns its lifecycle and completion notices; shell `&` is not an alternative lifecycle. + +## Verification + +The keyless fresh-round-trip browser scenario boots the shipped Web composition, drives a real replayed session, snapshots the URL-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` equals the scaffold's actual bound URL. A real Vite subprocess test requires serve mode to exit nonzero with the full-host correction. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, and HTTP bytes rather than an agent's success statement. + +## Alternatives considered + +**Extend only the system prompt.** Rejected because it would leave the target unavailable to tools, preserve the misleading bare-Vite path, and fail to prove how an existing process observes rebuilt artifacts. + +**Remove the `apps/web` development script without guarding Vite.** Rejected because `npx vite`, the exact incident command, bypasses package scripts. Serve mode itself must fail. + +**Automatically restart or replace the current Web process after every edit.** Rejected because the static server already reads current artifacts per request, a restart would interrupt the session that requested the edit, and plugin HMR has a separate explicit `dsh web --dev` composition. + +**Send DOM, route, or screenshots with each request.** Deferred to a separate logged-input design. Stable URL identity closes this feedback loop without claiming browser state the host does not receive. + +## Consequences + +Web prompts gain a dynamic URL paragraph, so provider prefix reuse now varies by bound port. Bash processes gain one non-secret managed environment variable. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the unsupported startup path fails before a white screen, and a second port can no longer masquerade as proof that the user's current page changed. diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md new file mode 100644 index 0000000000..06367b09bd --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md @@ -0,0 +1,37 @@ +# Agent Note: Web GUI 改动在现有 URL 上闭环 + +Status: implemented + +[English](2026-07-28-web-gui-feedback-loop.md) | 中文 + +## 问题 + +Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道用户正在查看哪个 URL。[运行时上下文决策](2026-07-28-web-agent-runtime-context.md)提供前一项事实，但 GUI 编辑仍然没有可执行的验收目标：源码编辑、产物构建、监听中的进程与用户已打开的页面只是互不关联的观察结果。仓库提供的入口让错误的替代方案显得合理，因为 `apps/web/package.json` 将 `vite` 暴露为 `dev` 脚本，而裸 Vite 即使无法注入 `window.__DSH_BOOT__`，仍会返回 HTTP 200。 + +事故会话记录了连续三次失败。修改主题后，第 2 轮把验收交给用户，要求用户运行 `pnpm run demo:tui` 或打开某个未指明的浏览器应用，自己没有执行任何真实组装的 Web 验证。第 3 轮读取前端包脚本，在 5173 端口启动裸 Vite，把 HTTP 200 当作就绪并报告成功；用户看到的却是符合预期的缺少 `__DSH_BOOT__` 的白屏。第 4 轮找到 `dsh web`，重新构建 Web 外壳，在 3334 端口启动了一个不受管理的 shell 后台进程，并且只检查新页面是否能返回 200 和启动 manifest（元数据清单），始终没有探测现有的 3081 端口。事实上，3081 端口的进程早于此次构建启动，其静态宿主会在下一次请求时读取重新构建的 dist，因此刷新原页面就已经能看到改动。直到用户报告这一事实，第 5 轮才检查 3081 端口并移除冗余服务。 + +## 决策 + +`dsh web` 发布一个规范的回环 URL，同时将其作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 系统提示词段说明：未加限定的指代指向此 GUI；该段会给出 URL，并把验收定义为重新构建受影响的 Web 产物，然后刷新并验证现有 URL。`DSH_WEB_URL` 会把同一个值传入每次前台或受管后台 bash 调用，使 agent 无需解析提示词或进程列表即可查询目标。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。 + +`apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR（热模块替换）入口路径。Vite 构建模式保持不变。 + +静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。 + +## 验证 + +无密钥的 fresh-round-trip 浏览器场景会启动已交付的 Web 组合，驱动真实的回放会话，对包含 URL 的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 等于测试脚手架实际绑定的 URL。真实 Vite 子进程测试要求服务模式以非零状态退出，并给出改用完整宿主的纠正信息。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出和 HTTP 字节，而不是 agent 的成功声明。 + +## 考虑过的替代方案 + +**仅扩展系统提示词。** 不予采纳，因为这样会让工具仍然无法获得目标，保留具有误导性的裸 Vite 路径，并且无法证明现有进程如何观察重新构建的产物。 + +**删除 `apps/web` 开发脚本，但不为 Vite 添加防护。** 不予采纳，因为事故中实际使用的命令 `npx vite` 会绕过包脚本。服务模式本身必须失败。 + +**每次编辑后自动重启或替换当前 Web 进程。** 不予采纳，因为静态服务器本就会在每次请求时读取当前产物，重启还会中断发起编辑请求的会话，而插件 HMR 已有独立且显式的 `dsh web --dev` 组合。 + +**每次请求都发送 DOM、路由或截图。** 推迟到另行设计的已记录输入机制。稳定的 URL 身份足以闭合本次反馈循环，同时不会声称宿主掌握其未接收的浏览器状态。 + +## 影响 + +Web 提示词会增加一个动态 URL 段落，因此模型提供方的前缀复用会随绑定端口变化。Bash 进程会增加一个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，不受支持的启动路径会在出现白屏前失败，另一个端口也无法再冒充用户当前页面已经改动的证据。 diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml index d1c6290a08..bd14674ff9 100644 --- a/apps/cli/README.i18n.yaml +++ b/apps/cli/README.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 apps/cli/README.md -README.md: 87cf1597fbb1ce91a7d61f912c42b0d6a68b2eea -README.zh.md: b3743f57a4dafda71e437a04ee0148b32dba2dca +README.md: 3ec427a0bca501d70c9bca938692d6ef9557a2dd +README.zh.md: e0cf7cd399858822df613a98890c0872554a5085 diff --git a/apps/cli/README.md b/apps/cli/README.md index 87cf1597fb..3ec427a0bc 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -14,7 +14,7 @@ The TUI surface: - 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. -The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface and this checkout as its own source location; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). +The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL in both the prompt and `$DSH_WEB_URL`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. The Web host reads frontend dist and client bundles when requests arrive, so rebuilding the affected artifacts and refreshing the existing URL updates that GUI without replacing its process; bare `apps/web` Vite serving fails because it cannot inject `window.__DSH_BOOT__`. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). `DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode). diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md index b3743f57a4..e0cf7cd399 100644 --- a/apps/cli/README.zh.md +++ b/apps/cli/README.zh.md @@ -14,7 +14,7 @@ TUI 界面： - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它； - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`.env` 填补环境缺口（环境中已有的值 > 项目 `.env` > 个人 `.env`），`config.yaml` 则修补已启动的树。 -Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root ` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI，并把当前 checkout 标记为自身源码位置；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。 +Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root ` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词和 `$DSH_WEB_URL` 中提供该进程的规范本地 URL；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。Web 宿主会在收到请求时读取前端 dist 和客户端 bundle，因此重新构建受影响的产物并刷新现有 URL 即可更新该 GUI，无须替换其进程；直接使用裸 `apps/web` Vite 服务会失败，因为它无法注入 `window.__DSH_BOOT__`。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。 `DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。 diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts index 67da6c73e8..97e5f94e18 100644 --- a/apps/cli/src/web.ts +++ b/apps/cli/src/web.ts @@ -11,28 +11,47 @@ import { fileURLToPath } from 'node:url' import type { Context } from 'cordis' import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot' import type {} from '@deepseek-ai/dsh-system-prompt' +import type {} from '@deepseek-ai/dsh-tool-bash' import { AppCLIEntry } from './app-cli-entry.ts' const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url)) const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url)) -/** Stable model-visible orientation for sessions created through `dsh web`. */ -const WEB_SURFACE_PROMPT = 'You are interacting with the user through the DeepSeek Harness Web GUI. ' - + '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.' +const DSH_WEB_URL = 'DSH_WEB_URL' as const + +/** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */ +function webSurfacePrompt(webUrl: string): string { + 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. ' + + 'For changes to this GUI, rebuild the affected Web artifacts and verify this existing URL after a refresh; 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.' +} /** - * Add the launcher-owned source location and Web-surface orientation after the - * shared config tree settles. The request header logs both sections with every - * model-visible prompt. + * 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. * @param sourceRoot - absolute checkout root resolved from the launcher module. + * @param webUrl - canonical loopback URL printed by this Web process. */ -export function installWebPromptContext(ctx: Context, sourceRoot: string): void { +export function installWebPromptContext(ctx: Context, sourceRoot: string, webUrl: string): 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: WEB_SURFACE_PROMPT }) + systemPrompt.section({ name: 'app:web-surface', order: -98, text: webSurfacePrompt(webUrl) }) + bashEnv.register({ + name: 'web-runtime', + variables: { + [DSH_WEB_URL]: { description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session.' }, + }, + resolve: () => ({ [DSH_WEB_URL]: webUrl }), + }) } // Display-only mirrors of the webserver schema's allowed hosts: the loopback @@ -63,7 +82,8 @@ export async function runWeb( ...workspaceRoot !== undefined && { workspaceRoot }, }) const { ctx, port: boundPort } = await entry.run() - installWebPromptContext(ctx, SOURCE_ROOT) + const localUrl = `http://${LOOPBACK_HOST}:${boundPort}` + installWebPromptContext(ctx, SOURCE_ROOT, localUrl) let exiting = false const shutdown = (code: number): void => { @@ -76,7 +96,6 @@ export async function runWeb( ? Object.values(networkInterfaces()).flat() .find(iface => iface !== undefined && iface.family === 'IPv4' && !iface.internal) : undefined - const localUrl = `http://${LOOPBACK_HOST}:${boundPort}` console.log(`dsh web: ${localUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate.address}:${boundPort})`}`) process.on('SIGTERM', () => { shutdown(0) }) diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json index 05947889b2..f56e97cb60 100644 --- a/apps/cli/tsconfig.json +++ b/apps/cli/tsconfig.json @@ -23,6 +23,9 @@ { "path": "../../packages/ui/app-boot" }, + { + "path": "../../packages/bash/tool-bash" + }, { "path": "../../packages/ui/tui" }, diff --git a/apps/web/package.json b/apps/web/package.json index 3c8f90b6a0..722ebe5342 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -10,7 +10,7 @@ }, "scripts": { "build": "vite build", - "dev": "vite", + "dev": "node -e \"console.error('apps/web is build-only; run dsh web or dsh web --dev with pnpm run dev:web') ; process.exit(1)\"", "watch": "vite build --watch" }, "license": "BSD-3-Clause", diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts index 222bb28580..a6434cd0d1 100644 --- a/apps/web/tests/replay-round-trip.e2e.ts +++ b/apps/web/tests/replay-round-trip.e2e.ts @@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { CallId } from '@deepseek-ai/dsh-llm' import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session' import { assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, @@ -87,9 +88,29 @@ describe('web e2e: fresh round trip through the real assembly', () => { const prefix = system.split('\n\n').slice(0, 4).join('\n\n') .split(REPO_ROOT).join('{{sourceRoot}}') .split(join(scaffold.workspaceCwd, 'workspace')).join('{{cwd}}') + .split(scaffold.baseUrl).join('{{webUrl}}') await compareOrRefreshGolden(SYSTEM_PROMPT_EXPECTED, prefix, MODE) }) + it('exposes the assembled Web URL to the real bash tool', async () => { + if (settledSessionId === undefined) throw new Error('the drive turn did not publish a session id') + const agent = scaffold.ctx.agents.get(settledSessionId) + if (agent === undefined) throw new Error(`the settled Web agent ${settledSessionId} is no longer live`) + const result = await scaffold.ctx.tools.execute({ + signal: AbortSignal.timeout(5_000), + callId: CallId('web-url-probe'), + name: 'bash', + arguments: { + command: 'printf \'%s\\n\' "$DSH_WEB_URL"', + description: 'Print current Web URL', + }, + agent, + }) + expect(result.isError).toBe(false) + expect(result.content.filter(block => block.type === 'text').map(block => block.text).join('')) + .toBe(`${scaffold.baseUrl}\n`) + }) + it.skipIf(MODE === 'record')('rendered the settled turn: markdown, tool row, composer restore', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-round-trip-settled')) // Browser settled-poll after host completion (host strictly precedes render). diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index ac360f38f2..8c9ec1dd30 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -203,12 +203,12 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise { + it('rejects the package dev alias with the full-host correction', async () => { + const result = await execa('pnpm', ['run', 'dev'], { cwd: WEB_ROOT, reject: false }) + expect(result.exitCode).not.toBe(0) + expect(result.stderr).toContain('apps/web is build-only') + expect(result.stderr).toContain('dsh web') + }) + + it('rejects the standalone Vite server with the full-host correction', async () => { + const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', '0'], { + cwd: WEB_ROOT, + reject: false, + timeout: 2_000, + }) + expect(result.exitCode).not.toBe(0) + expect(result.stderr).toContain('apps/web is not a standalone application') + expect(result.stderr).toContain('dsh web') + expect(result.stderr).toContain('window.__DSH_BOOT__') + }) +}) diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index 7043de4911..659dfa7ebd 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -1,11 +1,26 @@ import { fileURLToPath } from 'node:url' import { defineConfig } from 'vite' +import type { Plugin } from 'vite' import react from '@vitejs/plugin-react' const src = (rel: string): string => fileURLToPath(new URL(rel, import.meta.url)) +const STANDALONE_ERROR = 'apps/web is not a standalone application: bare Vite cannot inject window.__DSH_BOOT__. ' + + 'Build with `pnpm run build && pnpm run build:web`, then run `dsh web` (repository checkout: `pnpm run dsh -- web`). ' + + 'For client-plugin HMR, run `pnpm run dsh -- web --dev` together with `pnpm run dev:web`.' + +/** Fail before a Vite dev or preview server can expose the boot-manifest-free shell. */ +function rejectStandaloneServe(): Plugin { + const reject = (): never => { throw new Error(STANDALONE_ERROR) } + return { + name: 'dsh-reject-standalone-web-serve', + apply: 'serve', + configureServer: reject, + configurePreviewServer: reject, + } +} export default defineConfig({ - plugins: [react()], + plugins: [rejectStandaloneServe(), react()], resolve: { // Workspace packages resolve to SOURCE: package.json exports point at lib // for Node/type consumers, but the browser bundle must compile src directly diff --git a/packages/host/webserver/tests/webserver.spec.ts b/packages/host/webserver/tests/webserver.spec.ts index c4373d2e50..017fedba1a 100644 --- a/packages/host/webserver/tests/webserver.spec.ts +++ b/packages/host/webserver/tests/webserver.spec.ts @@ -111,6 +111,8 @@ describe('real Loader composition', () => { // Static fallback semantics: real asset served, traversal 403, non-GET/ // HEAD without a matching route 405. expect(await request(port, '/app.js')).toMatchObject({ status: 200, body: 'export {}' }) + await writeFile(join(root!, 'dist', 'app.js'), 'export const rebuilt = true') + expect(await request(port, '/app.js')).toMatchObject({ status: 200, body: 'export const rebuilt = true' }) expect((await request(port, '/..%2f..%2fetc%2fpasswd')).status).toBe(403) expect((await request(port, '/nowhere', { method: 'POST' })).status).toBe(405) From d8004e9956cc11a3678991db9dbbd87385602c1a Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 22:12:00 +0800 Subject: [PATCH 004/689] test(web): prove Vite never binds a port --- apps/web/tests/vite-entry.e2e.ts | 31 +++++++++++++++++++++++++++++-- apps/web/vite.config.ts | 7 +++---- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/apps/web/tests/vite-entry.e2e.ts b/apps/web/tests/vite-entry.e2e.ts index 80b9e2e683..131526819f 100644 --- a/apps/web/tests/vite-entry.e2e.ts +++ b/apps/web/tests/vite-entry.e2e.ts @@ -2,11 +2,28 @@ import { fileURLToPath } from 'node:url' import { join } from 'node:path' +import { createServer } from 'node:net' import { execa } from 'execa' import { describe, expect, it } from 'vitest' const WEB_ROOT = fileURLToPath(new URL('..', import.meta.url)) +/** Reserve an available loopback port, then release it for the child invocation. */ +async function freePort(): Promise { + const server = createServer() + await new Promise((resolve, reject) => { + server.once('error', reject) + server.listen(0, '127.0.0.1', resolve) + }) + const address = server.address() + if (address === null || typeof address === 'string') throw new Error('port probe returned no address') + await new Promise((resolve, reject) => server.close((error) => { + if (error === undefined) resolve() + else reject(error) + })) + return address.port +} + describe('Web development entry', () => { it('rejects the package dev alias with the full-host correction', async () => { const result = await execa('pnpm', ['run', 'dev'], { cwd: WEB_ROOT, reject: false }) @@ -16,14 +33,24 @@ describe('Web development entry', () => { }) it('rejects the standalone Vite server with the full-host correction', async () => { - const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', '0'], { + const port = await freePort() + const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', String(port)], { cwd: WEB_ROOT, reject: false, - timeout: 2_000, + timeout: 10_000, }) + expect(result.timedOut).toBe(false) expect(result.exitCode).not.toBe(0) expect(result.stderr).toContain('apps/web is not a standalone application') expect(result.stderr).toContain('dsh web') expect(result.stderr).toContain('window.__DSH_BOOT__') + await expect(new Promise((resolve, reject) => { + const probe = createServer() + probe.once('error', reject) + probe.listen(port, '127.0.0.1', () => probe.close((error) => { + if (error === undefined) resolve() + else reject(error) + })) + })).resolves.toBeUndefined() }) }) diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index 659dfa7ebd..d624fc2472 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -10,12 +10,11 @@ const STANDALONE_ERROR = 'apps/web is not a standalone application: bare Vite ca /** Fail before a Vite dev or preview server can expose the boot-manifest-free shell. */ function rejectStandaloneServe(): Plugin { - const reject = (): never => { throw new Error(STANDALONE_ERROR) } return { name: 'dsh-reject-standalone-web-serve', - apply: 'serve', - configureServer: reject, - configurePreviewServer: reject, + config(_config, env) { + if (env.command === 'serve') throw new Error(STANDALONE_ERROR) + }, } } From cd88a339fa885be82194e1881f49bf8be46190fe Mon Sep 17 00:00:00 2001 From: NI0317 Date: Wed, 29 Jul 2026 11:22:48 +0800 Subject: [PATCH 005/689] fix(web): verify current GUI updates end to end --- ...2026-07-28-web-gui-feedback-loop.i18n.yaml | 4 +- .../2026-07-28-web-gui-feedback-loop.md | 10 +- .../2026-07-28-web-gui-feedback-loop.zh.md | 12 +- apps/cli/README.i18n.yaml | 4 +- apps/cli/README.md | 2 +- apps/cli/README.zh.md | 2 +- apps/cli/src/args.ts | 2 +- apps/cli/src/web.ts | 27 +++- apps/web/package.json | 2 +- apps/web/tests/hmr-live.e2e.ts | 132 ++++++++++++++++++ apps/web/tests/replay-round-trip.e2e.ts | 6 +- apps/web/tests/scaffold.ts | 2 +- apps/web/tests/smoke-real.e2e.ts | 12 +- .../system-prompt.expected.md | 2 +- .../development-prompt.expected.md | 1 + apps/web/tests/support/listen-probe.mjs | 9 ++ apps/web/tests/vite-entry.e2e.ts | 47 ++++--- apps/web/tsconfig.json | 1 + ...0003-web-agent-gui-feedback-loop.i18n.yaml | 6 + .../0003-web-agent-gui-feedback-loop.md | 53 +++++++ .../0003-web-agent-gui-feedback-loop.zh.md | 53 +++++++ docs/postmortem/README.i18n.yaml | 6 +- docs/postmortem/README.md | 1 + docs/postmortem/README.zh.md | 1 + scripts/dev-web.spec.ts | 42 ++++++ scripts/dev-web.ts | 87 +++++++----- tsconfig.host.json | 1 + 27 files changed, 438 insertions(+), 89 deletions(-) create mode 100644 apps/web/tests/hmr-live.e2e.ts create mode 100644 apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md create mode 100644 apps/web/tests/support/listen-probe.mjs create mode 100644 docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml create mode 100644 docs/postmortem/0003-web-agent-gui-feedback-loop.md create mode 100644 docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md create mode 100644 scripts/dev-web.spec.ts diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml index 22390d728f..1e22fa79fb 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.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-gui-feedback-loop.md -2026-07-28-web-gui-feedback-loop.md: 27295704d7b0cde3a46a6a28891545bfe31ed275 -2026-07-28-web-gui-feedback-loop.zh.md: 06367b09bd889bfb7a4052c46369720c4ec6d358 +2026-07-28-web-gui-feedback-loop.md: 039d2aebeeef903d10838a46b48e5172f0195126 +2026-07-28-web-gui-feedback-loop.zh.md: ddf748654788811aa19e2a8a295c3ff6df033fef diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md index 27295704d7..039d2aebee 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md @@ -8,11 +8,13 @@ English | [中文](2026-07-28-web-gui-feedback-loop.zh.md) The Web agent could identify neither the GUI hosting its session nor the URL the user was viewing. The [runtime-context decision](2026-07-28-web-agent-runtime-context.md) supplies the first fact, but a GUI edit still had no executable acceptance target: source edits, artifact builds, a listening process, and the user's existing page were unrelated observations. Repository affordances made a wrong substitute look valid because `apps/web/package.json` exposed `vite` as its `dev` script and bare Vite returned HTTP 200 even though it could not inject `window.__DSH_BOOT__`. -The incident session recorded three consecutive failures. After changing the theme, turn 2 delegated acceptance to the user with `pnpm run demo:tui` or an unspecified browser application and ran no assembled Web check. Turn 3 read the frontend package script, launched bare Vite on port 5173, treated HTTP 200 as readiness, and reported success; the user instead received the expected missing-`__DSH_BOOT__` white screen. Turn 4 found `dsh web`, rebuilt the shell, started an unmanaged shell-background process on port 3334, and checked only that the new page returned 200 with a boot manifest. It never probed the existing port 3081. In fact, the port-3081 process predated the build, and its static host read the rebuilt dist on the next request, so refreshing the original page already showed the change. Only after the user reported that fact did turn 5 inspect port 3081 and remove the redundant server. +The [incident post-mortem](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md) owns the event-log timeline and why the original checks accepted the wrong page, process, and port. ## Decision -`dsh web` publishes one canonical loopback URL as both model-visible orientation and a managed shell fact. The `app:web-surface` prompt section says that unqualified references identify this GUI, names the URL, and defines acceptance as rebuilding the affected Web artifacts and verifying that existing URL after refresh. `DSH_WEB_URL` carries the same value into every foreground or managed background bash call, so the agent can query the target without parsing prose or process listings. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address. +`dsh web` publishes one canonical loopback URL and its actual runtime mode as both model-visible orientation and managed shell facts. The `app:web-surface` prompt section says that unqualified references identify this GUI and names the URL; `DSH_WEB_URL` and `DSH_WEB_MODE=production|development` carry the same facts into every foreground or managed background bash call. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address. + +The mode-specific prompt makes the agent, rather than the user, own the hidden startup contract. Production mode defines acceptance as rebuilding the affected artifacts and refreshing the existing URL. Development mode states that `dsh web --dev` activates only the HMR receiver: automatic client-plugin reload additionally requires a same-checkout `pnpm run dev:web` watcher, which the agent verifies before promising no-refresh updates. Shell and other plain-package changes still require rebuild plus refresh. An agent in production mode explains both commands when a user requests no-refresh updates; it does not launch a replacement GUI unless asked. The `apps/web` development script and Vite configuration reject serve mode before opening a port. Their diagnostics identify `apps/web` as a build-only shell, explain that only `dsh web` injects `window.__DSH_BOOT__`, and name the production and HMR entry paths. Vite build mode remains unchanged. @@ -20,7 +22,7 @@ No server restart or replacement is required merely because static artifacts cha ## Verification -The keyless fresh-round-trip browser scenario boots the shipped Web composition, drives a real replayed session, snapshots the URL-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` equals the scaffold's actual bound URL. A real Vite subprocess test requires serve mode to exit nonzero with the full-host correction. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, and HTTP bytes rather than an agent's success statement. +The keyless fresh-round-trip browser scenario boots the shipped production Web composition, drives a real replayed session, snapshots the URL/mode-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` and `$DSH_WEB_MODE` match the actual bound runtime. The real CLI smoke launches `dsh web --dev` and captures the provider request, pinning the complete two-command development contract. The `dev:web` watcher test rebuilds an isolated client bundle after a source change; the browser HMR scenario launches `dsh web --dev`, changes an initial production-roster bundle, and observes the new DOM under the same page identity. A real Vite subprocess test requires serve mode to exit naturally with the full-host correction and instruments `Server.listen()` to prove it was never called. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, DOM identity, and HTTP bytes rather than an agent's success statement. ## Alternatives considered @@ -34,4 +36,4 @@ The keyless fresh-round-trip browser scenario boots the shipped Web composition, ## Consequences -Web prompts gain a dynamic URL paragraph, so provider prefix reuse now varies by bound port. Bash processes gain one non-secret managed environment variable. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the unsupported startup path fails before a white screen, and a second port can no longer masquerade as proof that the user's current page changed. +Web prompts gain a dynamic URL-and-mode paragraph, so provider prefix reuse now varies by bound port and mode. Bash processes gain two non-secret managed environment variables. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the agent can teach the user the exact update behavior of the process actually serving their session, and the unsupported startup path fails before a white screen. The URL/mode contract guides the agent away from replacement ports; it does not prohibit arbitrary shell commands from starting one. diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md index 06367b09bd..ddf7486547 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md @@ -8,19 +8,21 @@ Status: implemented Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道用户正在查看哪个 URL。[运行时上下文决策](2026-07-28-web-agent-runtime-context.md)提供前一项事实，但 GUI 编辑仍然没有可执行的验收目标：源码编辑、产物构建、监听中的进程与用户已打开的页面只是互不关联的观察结果。仓库提供的入口让错误的替代方案显得合理，因为 `apps/web/package.json` 将 `vite` 暴露为 `dev` 脚本，而裸 Vite 即使无法注入 `window.__DSH_BOOT__`，仍会返回 HTTP 200。 -事故会话记录了连续三次失败。修改主题后，第 2 轮把验收交给用户，要求用户运行 `pnpm run demo:tui` 或打开某个未指明的浏览器应用，自己没有执行任何真实组装的 Web 验证。第 3 轮读取前端包脚本，在 5173 端口启动裸 Vite，把 HTTP 200 当作就绪并报告成功；用户看到的却是符合预期的缺少 `__DSH_BOOT__` 的白屏。第 4 轮找到 `dsh web`，重新构建 Web 外壳，在 3334 端口启动了一个不受管理的 shell 后台进程，并且只检查新页面是否能返回 200 和启动 manifest（元数据清单），始终没有探测现有的 3081 端口。事实上，3081 端口的进程早于此次构建启动，其静态宿主会在下一次请求时读取重新构建的 dist，因此刷新原页面就已经能看到改动。直到用户报告这一事实，第 5 轮才检查 3081 端口并移除冗余服务。 +[事故复盘](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)记录事件日志时间线，以及原有检查为何会接受错误的页面、进程和端口。 ## 决策 -`dsh web` 发布一个规范的回环 URL，同时将其作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 系统提示词段说明：未加限定的指代指向此 GUI；该段会给出 URL，并把验收定义为重新构建受影响的 Web 产物，然后刷新并验证现有 URL。`DSH_WEB_URL` 会把同一个值传入每次前台或受管后台 bash 调用，使 agent 无需解析提示词或进程列表即可查询目标。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。 +`dsh web` 发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。 -`apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR（热模块替换）入口路径。Vite 构建模式保持不变。 +按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。 + +`apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。 静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。 ## 验证 -无密钥的 fresh-round-trip 浏览器场景会启动已交付的 Web 组合，驱动真实的回放会话，对包含 URL 的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 等于测试脚手架实际绑定的 URL。真实 Vite 子进程测试要求服务模式以非零状态退出，并给出改用完整宿主的纠正信息。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出和 HTTP 字节，而不是 agent 的成功声明。 +无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发契约。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。 ## 考虑过的替代方案 @@ -34,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道 ## 影响 -Web 提示词会增加一个动态 URL 段落，因此模型提供方的前缀复用会随绑定端口变化。Bash 进程会增加一个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，不受支持的启动路径会在出现白屏前失败，另一个端口也无法再冒充用户当前页面已经改动的证据。 +Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。 diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml index bd14674ff9..c82ea34050 100644 --- a/apps/cli/README.i18n.yaml +++ b/apps/cli/README.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 apps/cli/README.md -README.md: 3ec427a0bca501d70c9bca938692d6ef9557a2dd -README.zh.md: e0cf7cd399858822df613a98890c0872554a5085 +README.md: 22bcd3e7dc8fafdf5c9608ef56230b3bd62e4a80 +README.zh.md: c28989de2b19c172998c876574eeb893a3aa4f92 diff --git a/apps/cli/README.md b/apps/cli/README.md index 3ec427a0bc..22bcd3e7dc 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -14,7 +14,7 @@ The TUI surface: - 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. -The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL in both the prompt and `$DSH_WEB_URL`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. The Web host reads frontend dist and client bundles when requests arrive, so rebuilding the affected artifacts and refreshing the existing URL updates that GUI without replacing its process; bare `apps/web` Vite serving fails because it cannot inject `window.__DSH_BOOT__`. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). +The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL and mode in both the prompt and managed `$DSH_WEB_URL`/`$DSH_WEB_MODE`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. In production mode the host reads rebuilt frontend dist and client bundles on the next request, so refreshing the existing URL updates that GUI without replacing its process. `dsh web --dev` mounts the client-plugin HMR receiver, but no-refresh updates additionally require `pnpm run dev:web` in the same checkout to watch and rebuild plugin bundles; shell and plain-package changes still require a rebuild and page refresh. Bare `apps/web` Vite serving fails because it cannot inject `window.__DSH_BOOT__`. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). `DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode). diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md index e0cf7cd399..c28989de2b 100644 --- a/apps/cli/README.zh.md +++ b/apps/cli/README.zh.md @@ -14,7 +14,7 @@ TUI 界面： - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它； - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`.env` 填补环境缺口（环境中已有的值 > 项目 `.env` > 个人 `.env`），`config.yaml` 则修补已启动的树。 -Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root ` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词和 `$DSH_WEB_URL` 中提供该进程的规范本地 URL；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。Web 宿主会在收到请求时读取前端 dist 和客户端 bundle，因此重新构建受影响的产物并刷新现有 URL 即可更新该 GUI，无须替换其进程；直接使用裸 `apps/web` Vite 服务会失败，因为它无法注入 `window.__DSH_BOOT__`。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。 +Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root ` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词及受管的 `$DSH_WEB_URL`/`$DSH_WEB_MODE` 中提供该进程的规范本地 URL 和模式；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。在生产模式下，宿主会在下次请求时读取重新构建的前端 dist 和客户端 bundle，因此刷新现有 URL 即可更新该 GUI，无须替换其进程。`dsh web --dev` 会挂载客户端插件的 HMR（热模块替换）接收端，但要实现无刷新更新，还需在同一 checkout 中运行 `pnpm run dev:web`，以监视并重新构建插件 bundle；shell 和普通包（package）的更改仍需重新构建并刷新页面。直接使用裸 `apps/web` Vite 服务会失败，因为它无法注入 `window.__DSH_BOOT__`。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。 `DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。 diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts index 9fd0f4d9bf..0ea3c7e21c 100644 --- a/apps/cli/src/args.ts +++ b/apps/cli/src/args.ts @@ -115,7 +115,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc web .option('--host ', 'override the config bind host (127.0.0.1 or 0.0.0.0)') .option('--port ', 'override the config listen port (0 requests an OS-assigned port)') - .option('--dev', 'mount the client HMR driver and watch plugin bundles for rebuilds') + .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)') .option('--workspace-root ', 'parent directory for name-created workspaces') .action((options: WebOptions) => { // Commander parses the parent (default-surface) options on either side of diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts index 97e5f94e18..a801929e16 100644 --- a/apps/cli/src/web.ts +++ b/apps/cli/src/web.ts @@ -18,13 +18,23 @@ const CONFIG_PATH = fileURLToPath(new URL('../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' /** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */ -function webSurfacePrompt(webUrl: string): string { +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. ' - + 'For changes to this GUI, rebuild the affected Web artifacts and verify this existing URL after a refresh; starting another server does not update this GUI. ' + + 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.' } @@ -37,20 +47,22 @@ function webSurfacePrompt(webUrl: string): string { * @param ctx - settled Web application context. * @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): void { +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) }) + 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 }), + resolve: () => ({ [DSH_WEB_URL]: webUrl, [DSH_WEB_MODE]: mode }), }) } @@ -65,7 +77,7 @@ const ALL_INTERFACES_HOST = '0.0.0.0' * through only when the flag was given; absent, the `cordis.yml` 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. */ export async function runWeb( @@ -83,7 +95,8 @@ export async function runWeb( }) const { ctx, port: boundPort } = await entry.run() const localUrl = `http://${LOOPBACK_HOST}:${boundPort}` - installWebPromptContext(ctx, SOURCE_ROOT, localUrl) + const mode: WebMode = dev ? 'development' : 'production' + installWebPromptContext(ctx, SOURCE_ROOT, localUrl, mode) let exiting = false const shutdown = (code: number): void => { diff --git a/apps/web/package.json b/apps/web/package.json index 722ebe5342..3c8f90b6a0 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -10,7 +10,7 @@ }, "scripts": { "build": "vite build", - "dev": "node -e \"console.error('apps/web is build-only; run dsh web or dsh web --dev with pnpm run dev:web') ; process.exit(1)\"", + "dev": "vite", "watch": "vite build --watch" }, "license": "BSD-3-Clause", diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts new file mode 100644 index 0000000000..244dc0293d --- /dev/null +++ b/apps/web/tests/hmr-live.e2e.ts @@ -0,0 +1,132 @@ +/** Published dsh web --dev + pnpm dev:web → browser HMR, with no page reload. */ + +import { existsSync } from 'node:fs' +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { chromium } from 'playwright' +import { expect, it } from 'vitest' +import { Context } from 'cordis' +import type { Fiber } from 'cordis' +import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local' +import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { REPO_ROOT } from './support.ts' + +function spawnSpec(argv: readonly string[], cwd: string, env?: Record): SubprocessSpawnSpec { + return { + argv, + cwd, + stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' }, + graceMs: 5_000, + ...env === undefined ? {} : { env }, + } +} + +function waitForOutput(child: SubprocessHandle, pattern: RegExp, label: string): Promise { + return new Promise((resolveReady, reject) => { + let output = '' + let settled = false + const cleanup = (): void => { + clearTimeout(timer) + child.stdout?.off('data', onData) + child.stderr?.off('data', onData) + } + const resolveOnce = (value: string): void => { + if (settled) return + settled = true + cleanup() + resolveReady(value) + } + const rejectOnce = (error: Error): void => { + if (settled) return + settled = true + cleanup() + reject(error) + } + const onData = (chunk: Buffer): void => { + output += chunk.toString() + const match = pattern.exec(output) + if (match === null) return + resolveOnce(match[1] ?? match[0]) + } + const timer = setTimeout(() => { rejectOnce(new Error(`${label} not ready:\n${output}`)) }, 60_000) + child.stdout?.on('data', onData) + child.stderr?.on('data', onData) + void child.done.then((outcome) => { + rejectOnce(new Error(`${label} exited before ready (${JSON.stringify(outcome)}):\n${output}`)) + }, (error: unknown) => { + rejectOnce(new Error(`${label} failed before ready:\n${output}`, { cause: error })) + }) + }) +} + +async function stopTree(child: SubprocessHandle): Promise { + child.terminate() + const stopped = await child.waitForExit(AbortSignal.timeout(15_000)) + if (!stopped) throw new Error(`process tree ${String(child.pid)} did not stop after termination escalation`) + await child.done +} + +it('hot-reloads a real client-plugin source edit without refreshing the page', async () => { + const world = await mkdtemp(join(tmpdir(), 'dsh-web-hmr-world-')) + const sourcePath = join(REPO_ROOT, 'packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx') + const bundlePath = join(REPO_ROOT, 'packages/client/ui-conversation/lib/client.js') + const binPath = join(REPO_ROOT, 'apps/cli/lib/bin.js') + if (!existsSync(binPath)) throw new Error('HMR browser test needs the built dsh bin; run pnpm run build first') + const originalSource = await readFile(sourcePath) + const originalBundle = await readFile(bundlePath) + const oldText = "Let's start building" + const sourceNeedle = 'Let's start building' + const newText = `HMR UPDATED ${'x'.repeat(80)}` + const updatedSource = originalSource.toString().replace(sourceNeedle, newText) + if (updatedSource === originalSource.toString()) throw new Error(`HMR source lacks ${JSON.stringify(sourceNeedle)}`) + + const subprocessCtx = new Context() + let subprocessFiber: Fiber | undefined + let watcher: SubprocessHandle | undefined + let host: SubprocessHandle | undefined + let browser: Awaited> | undefined + const failures: unknown[] = [] + try { + subprocessFiber = await subprocessCtx.plugin(LocalSubprocessService) + watcher = subprocessCtx.subprocess.spawn(spawnSpec(['pnpm', 'run', 'dev:web'], REPO_ROOT)) + await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web') + host = subprocessCtx.subprocess.spawn(spawnSpec( + [process.execPath, binPath, 'web', '--dev', '--port', '0'], + world, + { + DEEPSEEK_API_KEY: 'keyless-hmr-no-call', + DSH_HOME: join(world, '.dsh'), + }, + )) + const baseUrl = await waitForOutput(host, /dsh web: (http:\/\/[^\s]+)/, 'built dsh web --dev') + browser = await chromium.launch() + const page = await browser.newPage() + const pageErrors: string[] = [] + page.on('pageerror', error => pageErrors.push(String(error))) + await page.goto(baseUrl, { waitUntil: 'load' }) + await page.getByText(oldText, { exact: true }).waitFor({ timeout: 15_000 }) + const pageIdentity = await page.evaluate(() => { + const identity = crypto.randomUUID() + Object.defineProperty(window, '__dshHmrPageIdentity', { value: identity }) + return identity + }) + + await writeFile(sourcePath, updatedSource) + await page.getByText(newText, { exact: true }).waitFor({ timeout: 30_000 }) + expect(await page.evaluate(() => (window as Window & { __dshHmrPageIdentity?: string }).__dshHmrPageIdentity)) + .toBe(pageIdentity) + expect(pageErrors).toEqual([]) + } catch (error) { + failures.push(error) + } finally { + await writeFile(sourcePath, originalSource).catch((error: unknown) => failures.push(error)) + if (watcher !== undefined) await stopTree(watcher).catch((error: unknown) => failures.push(error)) + await writeFile(bundlePath, originalBundle).catch((error: unknown) => failures.push(error)) + if (host !== undefined) await stopTree(host).catch((error: unknown) => failures.push(error)) + await browser?.close().catch((error: unknown) => failures.push(error)) + await subprocessFiber?.dispose().catch((error: unknown) => failures.push(error)) + await rm(world, { recursive: true, force: true }).catch((error: unknown) => failures.push(error)) + } + if (failures.length > 0) throw new AggregateError(failures, 'HMR browser test or cleanup failed') +}, 120_000) diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts index a6434cd0d1..e427d8def2 100644 --- a/apps/web/tests/replay-round-trip.e2e.ts +++ b/apps/web/tests/replay-round-trip.e2e.ts @@ -101,14 +101,14 @@ describe('web e2e: fresh round trip through the real assembly', () => { callId: CallId('web-url-probe'), name: 'bash', arguments: { - command: 'printf \'%s\\n\' "$DSH_WEB_URL"', - description: 'Print current Web URL', + command: 'printf \'%s\\n%s\\n\' "$DSH_WEB_URL" "$DSH_WEB_MODE"', + description: 'Print current Web runtime', }, agent, }) expect(result.isError).toBe(false) expect(result.content.filter(block => block.type === 'text').map(block => block.text).join('')) - .toBe(`${scaffold.baseUrl}\n`) + .toBe(`${scaffold.baseUrl}\nproduction\n`) }) it.skipIf(MODE === 'record')('rendered the settled turn: markdown, tool row, composer restore', async () => { diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index 8c9ec1dd30..f6c6a106d4 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -208,7 +208,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise { return new Promise((resolveReady, reject) => { let out = '' @@ -180,7 +182,7 @@ describe('dsh web keyless CLI smoke', () => { } }) - it('injects the invoking workspace AGENTS.md into the provider request', async () => { + it('routes --dev runtime context and workspace instructions through the real CLI request', async () => { requireDist() const workspace = mkdtempSync(join(tmpdir(), 'dsh-web-workspace-')) mkdirSync(join(workspace, '.git')) @@ -212,7 +214,7 @@ describe('dsh web keyless CLI smoke', () => { const tsxLoader = pathToFileURL(createRequire(join(REPO_ROOT, 'package.json')).resolve('tsx')).href const child = spawn( process.execPath, - ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', '0'], + ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', '0', '--dev'], { cwd: workspace, env: { @@ -241,6 +243,10 @@ describe('dsh web keyless CLI smoke', () => { ]) const workspaceMessage = captured.messages?.find(message => message.role === 'user' && message.content?.includes('web-workspace-context-probe')) + const systemMessage = captured.messages?.find(message => message.role === 'system') + const expectedWebSection = readFileSync(DEVELOPMENT_PROMPT, 'utf8').trimEnd() + .replace('{{webUrl}}', baseUrl) + expect(systemMessage?.content).toContain(expectedWebSection) expect(workspaceMessage).toMatchInlineSnapshot(` { "content": " diff --git a/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md b/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md index 352f164eb5..481b3d759c 100644 --- a/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md +++ b/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md @@ -2,6 +2,6 @@ You are an AI agent powered by the DeepSeek Harness SDK. Your own source code is the checkout at {{sourceRoot}}; you can read it there to learn how dsh works and how to extend it. -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. For changes to this GUI, rebuild the affected Web artifacts and verify this existing URL after a refresh; 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. +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. 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. 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. You are a coding agent powered by the deepseek-v4-flash model. Your working directory is {{cwd}}. diff --git a/apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md b/apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md new file mode 100644 index 0000000000..58157d4437 --- /dev/null +++ b/apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md @@ -0,0 +1 @@ +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. 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. 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. diff --git a/apps/web/tests/support/listen-probe.mjs b/apps/web/tests/support/listen-probe.mjs new file mode 100644 index 0000000000..c4708199c3 --- /dev/null +++ b/apps/web/tests/support/listen-probe.mjs @@ -0,0 +1,9 @@ +import { appendFileSync } from 'node:fs' +import { Server } from 'node:net' + +const marker = process.env.DSH_LISTEN_PROBE_MARKER +const listen = Server.prototype.listen +Server.prototype.listen = function (...args) { + if (marker !== undefined) appendFileSync(marker, 'listen\n') + return listen.apply(this, args) +} diff --git a/apps/web/tests/vite-entry.e2e.ts b/apps/web/tests/vite-entry.e2e.ts index 131526819f..1854cff948 100644 --- a/apps/web/tests/vite-entry.e2e.ts +++ b/apps/web/tests/vite-entry.e2e.ts @@ -1,7 +1,9 @@ /** Bare Vite must fail before it can present a bootless shell as a working GUI. */ -import { fileURLToPath } from 'node:url' +import { fileURLToPath, pathToFileURL } from 'node:url' import { join } from 'node:path' +import { existsSync, mkdtempSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' import { createServer } from 'node:net' import { execa } from 'execa' import { describe, expect, it } from 'vitest' @@ -28,29 +30,34 @@ describe('Web development entry', () => { it('rejects the package dev alias with the full-host correction', async () => { const result = await execa('pnpm', ['run', 'dev'], { cwd: WEB_ROOT, reject: false }) expect(result.exitCode).not.toBe(0) - expect(result.stderr).toContain('apps/web is build-only') + expect(result.stderr).toContain('apps/web is not a standalone application') expect(result.stderr).toContain('dsh web') }) it('rejects the standalone Vite server with the full-host correction', async () => { + const probeRoot = mkdtempSync(join(tmpdir(), 'dsh-vite-listen-probe-')) + const marker = join(probeRoot, 'listen-called') const port = await freePort() - const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', String(port)], { - cwd: WEB_ROOT, - reject: false, - timeout: 10_000, - }) - expect(result.timedOut).toBe(false) - expect(result.exitCode).not.toBe(0) - expect(result.stderr).toContain('apps/web is not a standalone application') - expect(result.stderr).toContain('dsh web') - expect(result.stderr).toContain('window.__DSH_BOOT__') - await expect(new Promise((resolve, reject) => { - const probe = createServer() - probe.once('error', reject) - probe.listen(port, '127.0.0.1', () => probe.close((error) => { - if (error === undefined) resolve() - else reject(error) - })) - })).resolves.toBeUndefined() + try { + const probeModule = fileURLToPath(new URL('./support/listen-probe.mjs', import.meta.url)) + const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', String(port)], { + cwd: WEB_ROOT, + reject: false, + timeout: 10_000, + env: { + ...process.env, + DSH_LISTEN_PROBE_MARKER: marker, + NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --import ${pathToFileURL(probeModule).href}`.trim(), + }, + }) + expect(result.timedOut).toBe(false) + expect(result.exitCode).not.toBe(0) + expect(result.stderr).toContain('apps/web is not a standalone application') + expect(result.stderr).toContain('dsh web') + expect(result.stderr).toContain('window.__DSH_BOOT__') + expect(existsSync(marker), 'Vite called Server.listen before rejecting standalone serve mode').toBe(false) + } finally { + rmSync(probeRoot, { recursive: true, force: true }) + } }) }) diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 559e72618b..4b26ec3d9b 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -31,6 +31,7 @@ "tests/settings-chrome.e2e.ts", "tests/workspace-management.e2e.ts", "tests/replay-round-trip.e2e.ts", + "tests/hmr-live.e2e.ts", "tests/seeded-history.e2e.ts", "tests/code-mode-round.e2e.ts", "tests/cordis-tool-round.e2e.ts" diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml new file mode 100644 index 0000000000..838d489178 --- /dev/null +++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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 docs/postmortem/0003-web-agent-gui-feedback-loop.md +0003-web-agent-gui-feedback-loop.md: 13d13a607babfe7f5ddfdb6773c94f973bbef0db +0003-web-agent-gui-feedback-loop.zh.md: b3d35db9092304fcbca1106c0289fef441a2bad3 diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.md b/docs/postmortem/0003-web-agent-gui-feedback-loop.md new file mode 100644 index 0000000000..13d13a607b --- /dev/null +++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.md @@ -0,0 +1,53 @@ +# Post-mortem 0003: Web agent validated a replacement server instead of its current GUI + +English | [中文](0003-web-agent-gui-feedback-loop.zh.md) + +Status: resolved + +## Executive summary + +A Web agent changed the GUI source but did not know which URL and process hosted its session. It delegated acceptance to the user, then treated a bare Vite HTTP 200 as success despite a missing `window.__DSH_BOOT__` white screen, and finally validated a replacement `dsh web` server on another port while the original page had already picked up rebuilt artifacts. The fix makes the current URL and runtime mode model-visible and shell-queryable, rejects standalone Vite before listen, and verifies production refresh and development HMR against external state. + +## Summary + +The session ran inside the DeepSeek Harness Web GUI at port 3081 while its selected Workspace was an empty `test/` directory. The model request named neither the GUI nor its source checkout, URL, process, or update mode. Repository affordances exposed `apps/web` with a Vite development script, while the full browser composition lived behind `dsh web`. + +The resulting actions were individually plausible but did not share one acceptance target. A source edit, a successful build, an HTTP 200, an injected boot manifest, and the user's existing page were treated as interchangeable facts. + +The evidence source is the persisted event log for `session-3eb796c2-5159-4686-affe-df8719f6f987`, whose header records cwd `/Users/tn.shen/Documents/deepseek-harness-gui-master/test`. Its initial request header is sequence 6; the user-facing handoff, bare-Vite launch, replacement-host launch, boot-manifest probe, and first 3081 process probe are sequences 30939, 31865, 34309, 34441, and 34681 respectively. The timeline below follows those events rather than reconstructing intent from the later report. + +## Impact + +The user had to identify three consecutive mistakes: acceptance was delegated back to them; the proposed preview was a blank page; and the reported successful URL was not the page they were using. An unmanaged replacement server also outlived the turn until the user challenged it. + +No change in this investigation restarted or modified the read-only 3081 and 3082 trial services. + +## Timeline + +- In turn 2, after editing the theme, the agent's sequence-30939 message told the user to run `pnpm run demo:tui` or open an unspecified Web application. It ran no assembled Web acceptance. +- In turn 3, the agent read `apps/web/package.json`, launched bare Vite on port 5173 at sequence 31865, observed HTTP 200, and declared success. The browser instead threw `client-modules: window.__DSH_BOOT__ is missing or not an object` and rendered a white page. +- In turn 4, the agent found the full `dsh web` path, rebuilt the shell, launched an unmanaged process on port 3334 at sequence 34309, and checked only that this replacement returned 200 with a boot manifest at sequence 34441. It never probed port 3081. +- In turn 5, the user reported at sequence 34556 that 3081 already showed the new theme. Only then, at sequence 34681, did the agent inspect the existing process and remove the redundant server. + +## Root cause + +The Web assembly had no model-visible identity for the current GUI, canonical URL, or runtime mode. The session cwd correctly represented the user's selected Workspace, but the model mistook that project boundary for the application boundary. No durable contract related the GUI source checkout, built artifacts, serving process, target origin, and browser acceptance. + +The wrong startup path looked legitimate because bare Vite returned HTTP 200. `window.__DSH_BOOT__` is injected only by the full host, so transport readiness did not imply application readiness. The first regression test repeated this mistake in another form: a timeout killed Vite and satisfied a nonzero-exit assertion. Live reproduction exposed that false positive. + +Background process semantics were also bypassed with shell `&`, so task identity, completion notices, collection, and cleanup did not apply. Verifying port 3334 therefore proved only that a second service worked. + +## Guardrails added + +- The Web launcher publishes the canonical loopback URL and actual production/development mode in the logged `app:web-surface` prompt section and managed `$DSH_WEB_URL`/`$DSH_WEB_MODE` environment. +- Production guidance requires rebuilding artifacts and verifying the existing URL after refresh. Development guidance explains that `dsh web --dev` mounts only the HMR receiver; `pnpm run dev:web` in the same checkout must also rebuild client-plugin bundles, while shell and plain-package changes still require refresh. +- `apps/web` standalone Vite serve mode rejects during configuration. Its subprocess test proves natural exit and instruments `Server.listen()` so a transient bind cannot pass unnoticed. +- Layered real-path tests cover the CLI request, exact production/development prompts, shell runtime facts, same-port static replacement, source watcher rebuild, host stat polling, and browser HMR under an unchanged page identity. +- PR evidence preserves screenshots from the original 3081 session and a real-model before/after GUI run; external browser, HTTP, process, and session-log observations carry acceptance. + +## Lessons + +- The agent must know hidden runtime prerequisites before it can guide the user; startup mode is application context, not tribal knowledge. +- HTTP readiness, build success, and a boot manifest are different facts. Acceptance names the exact origin and externally observes the requested change there. +- A replacement service cannot prove that an existing page changed. Long-running processes use managed task lifecycles when they are actually requested. +- A regression test must be able to fail for the reported mechanism. Process timeout is not equivalent to fail-fast, and post-exit port availability does not prove the port was never bound. diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md new file mode 100644 index 0000000000..b3d35db909 --- /dev/null +++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md @@ -0,0 +1,53 @@ +# 事故复盘（postmortem） 0003：Web agent（智能体）验收了替代服务器，而非其当前 GUI + +[English](0003-web-agent-gui-feedback-loop.md) | 中文 + +Status: resolved + +## 摘要 + +Web agent 修改了 GUI 源码，却不知道由哪个 URL 和进程承载当前会话。它把验收交还给用户，随后在 `window.__DSH_BOOT__` 缺失导致白屏的情况下，仍把裸 Vite 返回的 HTTP 200 当作成功；最后，原页面其实已经加载了重建产物，它却去验收另一个端口上的替代 `dsh web` 服务器。修复让当前 URL 和运行模式对模型可见且可由 shell 查询，在独立 Vite 开始监听前拒绝启动，并依据外部状态验收生产模式刷新与开发模式 HMR（热模块替换）。 + +## 概述 + +该会话运行在端口 3081 的 DeepSeek Harness Web GUI 中，而用户选择的 Workspace 是空的 `test/` 目录。模型请求既未指明该 GUI，也未提供它的源码检出目录、URL、进程或更新模式。仓库在 `apps/web` 中提供了 Vite 开发脚本，完整的浏览器组合则由 `dsh web` 提供。 + +由此产生的各个动作单看都合理，却没有指向同一个验收目标。源码修改、成功构建、HTTP 200、注入的启动 manifest（元数据清单）和用户原本打开的页面，被当成了可以相互替代的事实。 + +证据源是 `session-3eb796c2-5159-4686-affe-df8719f6f987` 的持久化事件日志，其头部记录的 cwd 为 `/Users/tn.shen/Documents/deepseek-harness-gui-master/test`。初始请求头位于序列 6；面向用户的交接、裸 Vite 启动、替代宿主启动、启动 manifest 探测，以及首次探测 3081 进程，分别位于序列 30939、31865、34309、34441 和 34681。下方时间线以这些事件为依据，而不是根据后续报告反推意图。 + +## 影响 + +用户不得不连续指出三个错误：agent 把验收交还给用户；建议预览的页面一片空白；报告成功的 URL 并不是用户正在使用的页面。一个不受管理的替代服务器还持续运行到下一轮，直到用户提出质疑。 + +本次调查没有重启或修改只读的 3081 和 3082 试验服务。 + +## 时间线 + +- 在第 2 轮中，agent 修改主题后，在序列 30939 的消息中让用户运行 `pnpm run demo:tui` 或打开一个未明确指定的 Web 应用。它没有对组装后的 Web 应用执行任何验收。 +- 在第 3 轮中，agent 读取 `apps/web/package.json`，在序列 31865 于端口 5173 上启动裸 Vite，观察到 HTTP 200 后便宣布成功。浏览器却抛出 `client-modules: window.__DSH_BOOT__ is missing or not an object`，并显示白屏。 +- 在第 4 轮中，agent 找到了完整的 `dsh web` 启动路径，重新构建 shell，在序列 34309 于端口 3334 上启动一个不受管理的进程，并且只在序列 34441 检查了这个替代服务是否返回 200 和启动 manifest。它从未探测端口 3081。 +- 在第 5 轮中，用户在序列 34556 报告 3081 已经显示新主题。直到序列 34681，agent 才检查既有进程并移除冗余服务器。 + +## 根因 + +Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久契约将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。 + +裸 Vite 返回 HTTP 200，使错误的启动路径看似合理。`window.__DSH_BOOT__` 只由完整宿主注入，因此传输层就绪不代表应用已就绪。首个回归测试以另一种方式重复了同样的错误：超时机制终止 Vite 后，非零退出断言仍会通过。真实复现暴露了这一误报。 + +agent 还通过 shell `&` 绕过了后台进程语义，因此任务身份、完成通知、结果收集和清理机制均未生效。验证端口 3334 只能证明第二个服务可以工作。 + +## 已添加的防护措施 + +- Web 启动器在记录到日志的 `app:web-surface` 提示词区段，以及受管的 `$DSH_WEB_URL`/`$DSH_WEB_MODE` 环境变量中，发布规范环回 URL 和实际的生产／开发模式。 +- 生产模式指南要求重新构建产物，并在刷新后验证既有 URL。开发模式指南说明，`dsh web --dev` 只挂载 HMR 接收端；同一源码检出目录中的 `pnpm run dev:web` 还必须重新构建客户端插件 bundle，而 Web shell 和普通包的改动仍然需要刷新页面。 +- `apps/web` 的独立 Vite 服务模式会在配置阶段拒绝启动。其子进程测试验证进程自然退出，并插桩 `Server.listen()`，确保短暂绑定端口也不会漏检。 +- 分层的真实路径测试覆盖 CLI（命令行界面）请求、精确的生产／开发模式提示词、shell 运行时事实、同端口静态产物替换、源码 watcher 重建、宿主 stat 轮询，以及页面 identity 不变的浏览器 HMR。 +- PR（Pull Request）证据保留了原始 3081 会话的截图，以及真实模型驱动的 GUI 修改前后对比；验收以外部浏览器、HTTP、进程和会话日志的观测结果为准。 + +## 教训 + +- agent 必须先知道隐藏的运行时前置条件，才能指导用户；启动模式属于应用上下文，不应依赖团队口口相传。 +- HTTP 就绪、构建成功和启动 manifest 是不同的事实。验收必须明确指定确切的 origin，并从外部观察所请求的改动是否在该 origin 生效。 +- 替代服务无法证明既有页面已经改变。确实需要长时间运行的进程时，应使用受管的任务生命周期。 +- 回归测试必须能够针对所报告的机制失败。进程超时不等同于快速失败，进程退出后端口可用也不能证明该端口从未被绑定。 diff --git a/docs/postmortem/README.i18n.yaml b/docs/postmortem/README.i18n.yaml index e68d3a1a07..cbdfd07055 100644 --- a/docs/postmortem/README.i18n.yaml +++ b/docs/postmortem/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -README.md: df0e2fcb8540aeed005153dbecc451d781ca5ff1 -README.zh.md: 2ce6de475c705b02cd9dabfb2181929d81478e2c +# pnpm run verify-translation-pairing --write docs/postmortem/README.md +README.md: 4858f8841e92a895f2d1a840b59b42758e83d952 +README.zh.md: f2f69e44448df8e7016fbe5672a0c0d5a522c47a diff --git a/docs/postmortem/README.md b/docs/postmortem/README.md index df0e2fcb85..4858f8841e 100644 --- a/docs/postmortem/README.md +++ b/docs/postmortem/README.md @@ -14,3 +14,4 @@ Every post-mortem opens with an **Executive summary**: one short paragraph a bus |---|---| | [0001](0001-acp-default-export-drops-inject.md) | ACP server crashed on connect: `export default` dropped the plugin's `inject` | | [0002](0002-js-expression-disabled-filesystem-tools.md) | Filesystem snapshot tools were permanently disabled by a literal `!!js` object | +| [0003](0003-web-agent-gui-feedback-loop.md) | Web agent validated a replacement server instead of the GUI hosting its session | diff --git a/docs/postmortem/README.zh.md b/docs/postmortem/README.zh.md index 2ce6de475c..f2f69e4444 100644 --- a/docs/postmortem/README.zh.md +++ b/docs/postmortem/README.zh.md @@ -14,3 +14,4 @@ |---|---| | [0001](0001-acp-default-export-drops-inject.md) | ACP（Agent Client Protocol）服务器在连接时崩溃：`export default` 丢失了插件的 `inject` | | [0002](0002-js-expression-disabled-filesystem-tools.md) | 文件系统快照工具被一个字面量 `!!js` 对象永久禁用 | +| [0003](0003-web-agent-gui-feedback-loop.md) | Web agent 验证了替代服务器，而非承载其会话的 GUI | diff --git a/scripts/dev-web.spec.ts b/scripts/dev-web.spec.ts new file mode 100644 index 0000000000..2edbc652ab --- /dev/null +++ b/scripts/dev-web.spec.ts @@ -0,0 +1,42 @@ +import { mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it } from 'vitest' +import type { TsdownBundle } from 'tsdown' +import { watchClientPlugins } from './dev-web.ts' + +it('rebuilds a client-plugin bundle after its source changes', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-watch-')) + let bundles: TsdownBundle[] = [] + try { + await symlink(join(import.meta.dirname, '..', 'node_modules'), join(root, 'node_modules'), 'dir') + await writeFile(join(root, 'package.json'), JSON.stringify({ name: '@dsh-test/dev-web-watch', private: true, type: 'module' })) + await writeFile(join(root, 'tsdown.config.ts'), ` +import { defineConfig } from 'tsdown' +export default defineConfig({ + entry: { client: 'src.ts' }, outDir: 'lib', format: 'cjs', platform: 'browser', dts: false, clean: false, + outputOptions: { entryFileNames: 'client.js' }, +}) +`) + const sourcePath = join(root, 'src.ts') + const bundlePath = join(root, 'lib/client.js') + await writeFile(sourcePath, 'export const version = "watch-v1"\n') + bundles = await watchClientPlugins(root, ['.'], 50) + await expect.poll(async () => { + try { + return (await readFile(bundlePath, 'utf8')).includes('watch-v1') + } catch { + return false + } + }, { timeout: 10_000 }).toBe(true) + + await new Promise(resolve => setTimeout(resolve, 1_000)) + await writeFile(sourcePath, `export const version = "watch-v2-${'x'.repeat(100)}"\n`) + await expect.poll(async () => (await readFile(bundlePath, 'utf8')).includes('watch-v2-'), { + timeout: 10_000, + }).toBe(true) + } finally { + for (const bundle of bundles) await bundle[Symbol.asyncDispose]() + await rm(root, { recursive: true, force: true }) + } +}, 20_000) diff --git a/scripts/dev-web.ts b/scripts/dev-web.ts index 38b1cffde1..aee7146487 100644 --- a/scripts/dev-web.ts +++ b/scripts/dev-web.ts @@ -18,9 +18,10 @@ * keys under each package's file config, and no package config defines it). */ import { globSync, readFileSync } from 'node:fs' -import { dirname, join, sep } from 'node:path' -import { fileURLToPath } from 'node:url' +import { dirname, join, resolve, sep } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' import { build } from 'tsdown' +import type { TsdownBundle } from 'tsdown' const repoRoot = fileURLToPath(new URL('..', import.meta.url)) @@ -29,46 +30,64 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url)) * whose package.json carries `dshClient` with platform "web" is a client * plugin bundle emitter. Scanned once at startup — a package added while * watching means restarting this script. + * @param root - repository root containing the grouped package directories. * @returns workspace-relative plugin package directories. */ -function discoverPluginDirs(): string[] { +export function discoverPluginDirs(root = repoRoot): string[] { const dirs: string[] = [] - for (const manifestPath of globSync('packages/*/*/package.json', { cwd: repoRoot }).sort()) { - const manifest = JSON.parse(readFileSync(join(repoRoot, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } } + for (const manifestPath of globSync('packages/*/*/package.json', { cwd: root }).sort()) { + const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } } if (manifest.dshClient?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/')) } return dirs } -const PLUGIN_DIRS = discoverPluginDirs() -if (PLUGIN_DIRS.length === 0) { - console.error('dev-web: no dshClient (platform "web") packages found under packages/') - process.exit(1) +/** + * Start the tsdown watch build used by `pnpm run dev:web`. + * @param root - repository or fixture root passed to tsdown. + * @param pluginDirs - workspace-relative package directories to watch. + * @param pollInterval - optional source-watcher polling interval in milliseconds. + * @returns live bundles whose async disposers stop every watcher. + */ +export async function watchClientPlugins( + root: string, + pluginDirs: readonly string[], + pollInterval?: number, +): Promise { + return build({ + cwd: root, + workspace: [...pluginDirs], + watch: true, + ...pollInterval !== undefined + ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } } + : {}, + }) } -const args = process.argv.slice(2) -const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll=')) -if (args.some(a => a !== pollArg)) { - console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]') - process.exit(1) -} -const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500') -if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) { - console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`) - process.exit(1) -} +const invokedPath = process.argv[1] +const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href +if (isMain) { + const pluginDirs = discoverPluginDirs() + if (pluginDirs.length === 0) { + console.error('dev-web: no dshClient (platform "web") packages found under packages/') + process.exit(1) + } -await build({ - cwd: repoRoot, - workspace: PLUGIN_DIRS, - watch: true, - // Rolldown watch options ride through inputOptions (tsdown has no watcher - // tuning of its own); polling is opt-in for network mounts without inotify. - ...pollInterval !== undefined - ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } } - : {}, -}) -console.log( - `dev-web: watching ${String(PLUGIN_DIRS.length)} dshClient plugin packages` - + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n ${PLUGIN_DIRS.join('\n ')}`, -) + const args = process.argv.slice(2) + const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll=')) + if (args.some(a => a !== pollArg)) { + console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]') + process.exit(1) + } + const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500') + if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) { + console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`) + process.exit(1) + } + + await watchClientPlugins(repoRoot, pluginDirs, pollInterval) + console.log( + `dev-web: watching ${String(pluginDirs.length)} dshClient plugin packages` + + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n ${pluginDirs.join('\n ')}`, + ) +} diff --git a/tsconfig.host.json b/tsconfig.host.json index 9cf2a86bda..920f776876 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -18,6 +18,7 @@ "apps/web/tests/settings-chrome.e2e.ts", "apps/web/tests/workspace-management.e2e.ts", "apps/web/tests/replay-round-trip.e2e.ts", + "apps/web/tests/hmr-live.e2e.ts", "apps/web/tests/seeded-history.e2e.ts", "apps/web/tests/code-mode-round.e2e.ts", "apps/web/tests/cordis-tool-round.e2e.ts", From a777000512d2947e3c28e6f86ee7501acd3e248d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 00:21:47 +0800 Subject: [PATCH 006/689] fix(user-interaction): preserve multi-select custom answers --- ...select-custom-answer-composition.i18n.yaml | 6 + ...-multi-select-custom-answer-composition.md | 25 ++++ ...lti-select-custom-answer-composition.zh.md | 25 ++++ .../user-interaction.i18n.yaml | 6 +- docs/core-data-structures/user-interaction.md | 4 +- .../user-interaction.zh.md | 4 +- .../tests/fixtures/tui-scripted-llm.ts | 7 ++ .../tui-agent/tests/tui-keyless-smoke.e2e.ts | 9 +- packages/client/ui-question/README.i18n.yaml | 4 +- packages/client/ui-question/README.md | 2 +- packages/client/ui-question/README.zh.md | 2 +- .../src/client/QuestionComposer.tsx | 24 ++-- .../tests/question-composer.spec.tsx | 11 +- packages/host/apiproxy/README.i18n.yaml | 4 +- packages/host/apiproxy/README.md | 2 + packages/host/apiproxy/README.zh.md | 2 + packages/host/apiproxy/src/api-proxy.ts | 2 +- .../apiproxy/tests/api-proxy-question.spec.ts | 116 ++++++++++++++++++ packages/ui/tool-ask-user/README.i18n.yaml | 6 +- packages/ui/tool-ask-user/README.md | 2 +- packages/ui/tool-ask-user/README.zh.md | 2 +- .../tool-ask-user/tests/tool-ask-user.spec.ts | 6 +- packages/ui/tui/README.i18n.yaml | 4 +- packages/ui/tui/README.md | 2 +- packages/ui/tui/README.zh.md | 2 +- packages/ui/tui/src/components/dialogs.ts | 20 ++- packages/ui/tui/tests/tui.spec.ts | 6 +- packages/ui/user-interaction/README.i18n.yaml | 6 +- packages/ui/user-interaction/README.md | 2 +- packages/ui/user-interaction/README.zh.md | 2 +- packages/ui/user-interaction/src/types.ts | 2 +- 31 files changed, 269 insertions(+), 48 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md create mode 100644 packages/host/apiproxy/tests/api-proxy-question.spec.ts diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml new file mode 100644 index 0000000000..bb081e4be8 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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-30-multi-select-custom-answer-composition.md +2026-07-30-multi-select-custom-answer-composition.md: 7194f4a79f1dd49eba4a9b626d75203fced06544 +2026-07-30-multi-select-custom-answer-composition.zh.md: fac09c8db0ebf2dd4a84ade7aa7868128656025d diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md new file mode 100644 index 0000000000..7194f4a79f --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md @@ -0,0 +1,25 @@ +# Agent Note: Multi-select custom answer composition + +Status: implemented + +English | [中文](2026-07-30-multi-select-custom-answer-composition.zh.md) + +## Problem + +The user-interaction result vocabulary carries selected option labels and optional custom text in separate fields, but its original semantics made them mutually exclusive for every question. On a multi-select question, opening or typing the custom answer discarded labels the user had already selected. The TUI returned only the custom text, and the Web host rejected a client response that preserved both fields. + +## Decision + +For a question with `multiSelect: true`, one answer item may contain both a non-empty `selected` array and non-empty `custom` text. Web drafts preserve both values regardless of whether the user selects an option or types custom text first; the TUI projects its checked option set when custom text is submitted; and the Web host accepts the combined response after applying its existing id, label, uniqueness, batch, and non-empty-text validation. + +Single-select and optionless questions keep exclusive semantics: custom text overrides any selected option. The result shape remains `{ id, selected, custom? }`, so no wire or tool-output schema changes. + +## Alternatives considered + +**Encode custom text as another `selected` label.** Rejected because it would erase the distinction between caller-provided option labels and human-authored text, weakening validation and forcing consumers to infer which value was custom. + +**Allow `selected` and `custom` together for every question.** Rejected because a single-select question represents one answer; permitting a selected option plus custom text would make its cardinality ambiguous. The combined form is limited to questions that explicitly opt into multiple answers. + +## Consequences + +Multi-select UIs can represent the user's complete answer without discarding either source. Providers and consumers retain the existing DTO, while request-aware validators interpret the allowed combination from `multiSelect`. Web, TUI, host-response, tool-projection, and assembled keyless TUI coverage pin the combined result; single-select host coverage pins the remaining exclusivity rule. diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md new file mode 100644 index 0000000000..fac09c8db0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md @@ -0,0 +1,25 @@ +# Agent Note: 多选题自定义答案组合 + +Status: implemented + +[English](2026-07-30-multi-select-custom-answer-composition.md) | 中文 + +## 问题 + +用户交互结果的词汇分别通过不同字段携带选中的选项标签和可选的自定义文本，但最初的语义要求每个问题的这两个字段互斥。对于多选题，打开自定义答案或输入文本会丢弃用户已选中的标签。TUI 只返回自定义文本，而 Web 宿主会拒绝同时保留两个字段的客户端响应。 + +## 决策 + +对于 `multiSelect: true` 的问题，一个回答项可以同时包含非空 `selected` 数组与非空 `custom` 文本。无论用户先选择选项还是先输入自定义文本，Web 草稿都会保留两个值；提交自定义文本时，TUI 会投影其已勾选的选项集合；Web 宿主则在应用现有的 id、标签、唯一性、批次和非空文本校验后接受组合响应。 + +单选题和无选项问题仍保持互斥语义：自定义文本会覆盖任何已选中的选项。结果形状仍为 `{ id, selected, custom? }`，因此协议或工具输出 schema 均无需变更。 + +## 考虑过的替代方案 + +**把自定义文本编码为另一个 `selected` 标签。** 不予采纳，因为这样会抹去调用方提供的选项标签与用户填写文本之间的区别，削弱校验，并迫使消费方推断哪个值属于自定义内容。 + +**允许所有问题同时使用 `selected` 与 `custom`。** 不予采纳，因为单选题只表示一个回答；允许选中选项与自定义文本并存会使其基数含义模糊。组合形式仅适用于显式选择多项回答的问题。 + +## 后果 + +多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web、TUI、宿主响应、工具投影和组装后的无密钥 TUI 覆盖会固定组合结果；单选题的宿主覆盖则固定其余的互斥规则。 diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml index 66cb12815e..f764e9ca23 100644 --- a/docs/core-data-structures/user-interaction.i18n.yaml +++ b/docs/core-data-structures/user-interaction.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -user-interaction.md: 798a9790f424683775284a98421be08e6e1399e3 -user-interaction.zh.md: 12bfcffe4fe4caaacb54e90126eac55e333d64a5 +# pnpm run verify-translation-pairing --write docs/core-data-structures/user-interaction.md +user-interaction.md: db6ac5010ada9d02319bf148566792659711d2e4 +user-interaction.zh.md: a8306b421a03563ba9ae2ee48d04898d00eb668e diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md index 798a9790f4..db6ac5010a 100644 --- a/docs/core-data-structures/user-interaction.md +++ b/docs/core-data-structures/user-interaction.md @@ -60,14 +60,14 @@ interface AskUserQuestionRequest { ## Answer -Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. When `custom` is present, `selected` is empty; custom text is an answer override, not a supplement to selected choices. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch. +Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch. ```ts type-equiv /** Answer to one question. */ interface AskUserQuestionAnswerItem { /** The answered question id. */ id: string - /** Selected option labels. Empty for custom or unanswered choices. */ + /** Selected option labels. May accompany custom text for a multi-select question. */ selected: string[] /** Optional free-text "Other" answer. */ custom?: string diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md index 12bfcffe4f..a8306b421a 100644 --- a/docs/core-data-structures/user-interaction.zh.md +++ b/docs/core-data-structures/user-interaction.zh.md @@ -60,14 +60,14 @@ interface AskUserQuestionRequest { ## 回答 -提供方为每个问题 id 返回一个回答项。`selected` 包含选中的选项标签，`custom` 在用户输入自由文本时携带「其他」回答。当 `custom` 存在时，`selected` 为空；自定义文本是对选中项的覆盖，而非补充。UI 也可以使用 `selected` 为空且不含 `custom` 的回答项，在其余问题均已完成的批次中保留被跳过的问题。 +提供方为每个问题 id 返回一个回答项。`selected` 包含选中的选项标签，`custom` 在用户输入自由文本时携带「其他」回答。对于单选题，`custom` 会覆盖选中的选项，且 `selected` 为空。对于多选题，`custom` 可以补充 `selected` 中的标签。UI 也可以使用 `selected` 为空且不含 `custom` 的回答项，在其余问题均已完成的批次中保留被跳过的问题。 ```ts type-equiv /** Answer to one question. */ interface AskUserQuestionAnswerItem { /** The answered question id. */ id: string - /** Selected option labels. Empty for custom or unanswered choices. */ + /** Selected option labels. May accompany custom text for a multi-select question. */ selected: string[] /** Optional free-text "Other" answer. */ custom?: string diff --git a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts index 517fa6adab..121bde9278 100644 --- a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts +++ b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts @@ -110,6 +110,12 @@ class ScriptedTuiAdapter extends LlmAdapter { const hasToolResult = lastMessage?.content.some(block => block.type === 'tool-result') ?? false if (hasToolResult) { + const toolResultText = lastMessage?.content.flatMap(block => block.type === 'tool-result' + ? block.content.flatMap(content => content.type === 'text' ? [content.text] : []) + : []).join('\n') ?? '' + if (toolResultText !== '{"answers":[{"id":"mode","selected":["Safe"],"custom":"Release notes"}]}') { + throw new Error(`the scripted TUI request received an unexpected question answer: ${toolResultText}`) + } for (const chunk of textChunks(FINAL_TEXT)) yield chunk return } @@ -119,6 +125,7 @@ class ScriptedTuiAdapter extends LlmAdapter { id: 'mode', header: 'Execution mode', question: 'How should the scripted run proceed?', + multi_select: true, options: [ { label: 'Safe', description: 'Use the guarded path.' }, { label: 'Fast', description: 'Use the shorter path.' }, diff --git a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts index 7ae98167de..0201ccebe8 100644 --- a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts +++ b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts @@ -138,6 +138,7 @@ const SELECT_PRO_MODEL = [ { waitFor: 'scripted TUI ready.', send: '/model\r' }, { waitFor: 'Select model', send: '\x1b[B\x1b[Z\r' }, ] as const +const ANSWER_MULTI_WITH_CUSTOM = ' \tRelease notes\r' describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => { it('boots pi-tui, sweeps the borderless banner in, enters plan mode, and restores the terminal', async () => { @@ -174,7 +175,10 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => { // The question text first appears in the streamed tool-call card. Wait // for the dialog's input legend so Enter cannot arrive before it owns // terminal input when pre-dispatch policy yields. - { waitFor: 'Tab custom answer • ↑/↓ navigate • Enter submit • Esc interrupt', send: '\r' }, + { + waitFor: 'Tab custom answer • ↑/↓ navigate • Space toggle • Enter submit • Esc interrupt', + send: ANSWER_MULTI_WITH_CUSTOM, + }, { waitFor: 'Decision received. Scripted TUI run complete.', send: '' }, // Session title: the first user message drives the first-message-llm // provider's tool-less title call; the scripted adapter answers it, the @@ -200,6 +204,7 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => { expect(output).not.toContain('\u001B[999CMODEL_CURSOR') expect(output).not.toContain('\u009B31mMODEL_C1') expect(output).toContain('Safe') + expect(output).toContain('Release notes') expect(output).toContain('\u001B]0;scripted session title — DeepSeek Harness\u0007') expect(output).toContain('Session status') expect(output).toContain('Title') @@ -395,7 +400,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { actions: [ ...SELECT_PRO_MODEL, { waitFor: 'Model selected: tui-scripted/tui-scripted-model-pro.', send: 'exercise the TUI\r' }, - { waitFor: 'How should the scripted run proceed?', send: '\r' }, + { waitFor: 'How should the scripted run proceed?', send: ANSWER_MULTI_WITH_CUSTOM }, { waitFor: 'Decision received. Scripted TUI run complete.', send: '/exit\r' }, ], inspect: async (cwd) => { context = await readLoggedRequestContext(cwd) }, diff --git a/packages/client/ui-question/README.i18n.yaml b/packages/client/ui-question/README.i18n.yaml index a58cd055a7..7657062501 100644 --- a/packages/client/ui-question/README.i18n.yaml +++ b/packages/client/ui-question/README.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 packages/client/ui-question/README.md -README.md: 3a3cd639fc2834685230aca7c8087583e0a48c71 -README.zh.md: 1330578577da7ed7d0890595f675fd272fd5ebc7 +README.md: c36f1474e175b52c7d35af6b479ab5bfeabcd9ff +README.zh.md: 8986dee718a98920a20757aafb1bd4b54ac8f782 diff --git a/packages/client/ui-question/README.md b/packages/client/ui-question/README.md index 3a3cd639fc..c36f1474e1 100644 --- a/packages/client/ui-question/README.md +++ b/packages/client/ui-question/README.md @@ -4,7 +4,7 @@ English | [中文](README.zh.md) Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user` only when the Web feature is selected; its browser half registers the `question` entry in the conversation-owned `conversation.composer` keyed slot. -The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`. +The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. A multi-select draft keeps its selected labels while the user opens or edits the custom answer, so its submitted item may carry both `selected` and `custom`; a single-select custom answer remains exclusive. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`. Selection state is local to a component keyed by the request rpcId. A replay with the same id preserves a still-mounted draft, while `question/resolved` from the host removes the composer. The host remains authoritative: successful HTTP delivery does not remove pending state locally. diff --git a/packages/client/ui-question/README.zh.md b/packages/client/ui-question/README.zh.md index 1330578577..8986dee718 100644 --- a/packages/client/ui-question/README.zh.md +++ b/packages/client/ui-question/README.zh.md @@ -4,7 +4,7 @@ Web `ask_user_question` 功能插件。只有选择 Web 功能时，其主机侧才会挂载 `dsh-tool-ask-user`；浏览器侧会把 `question` 配置项注册到会话拥有的 `conversation.composer` 键控 slot 中。 -组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信内容策略。封顶卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。单选选项会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 输入法组合期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。 +组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。用户打开或编辑自定义答案时，多选题草稿会保留已选中的标签，因此提交项可以同时携带 `selected` 与 `custom`；单选题的自定义答案仍保持互斥。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信内容策略。封顶卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。单选选项会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 输入法组合期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。 选择状态只存在于以请求 rpcId 为 key 的组件本地。使用相同 id 回放时，只要组件仍挂载，就会保留草稿；主机发出的 `question/resolved` 则会移除编辑器。主机仍具有最终决定权：HTTP 交付成功不会在本地移除待处理状态。 diff --git a/packages/client/ui-question/src/client/QuestionComposer.tsx b/packages/client/ui-question/src/client/QuestionComposer.tsx index 542a24b935..ebf2caf22f 100644 --- a/packages/client/ui-question/src/client/QuestionComposer.tsx +++ b/packages/client/ui-question/src/client/QuestionComposer.tsx @@ -86,12 +86,13 @@ function QuestionFlow({ pending }: { pending: PendingQuestion }) { const choose = (label: string): void => { updateDraft((current) => { - const selected = question.multiSelect === true - ? current.selected.includes(label) + if (question.multiSelect === true) { + const selected = current.selected.includes(label) ? current.selected.filter(item => item !== label) : [...current.selected, label] - : [label] - return { selected, custom: '', customOpen: false, skipped: false } + return { ...current, selected, skipped: false } + } + return { selected: [label], custom: '', customOpen: false, skipped: false } }) if (question.multiSelect !== true && index < questions.length - 1) { setIndex(current => current + 1) @@ -99,7 +100,12 @@ function QuestionFlow({ pending }: { pending: PendingQuestion }) { } const openCustom = (): void => { - updateDraft(current => ({ ...current, selected: [], customOpen: true, skipped: false })) + updateDraft(current => ({ + ...current, + selected: question.multiSelect === true ? current.selected : [], + customOpen: true, + skipped: false, + })) } const answered = (item: DraftAnswer): boolean => @@ -121,7 +127,7 @@ function QuestionFlow({ pending }: { pending: PendingQuestion }) { const custom = value.custom.trim() return { id: item.id, - selected: custom === '' ? value.selected : [], + selected: custom === '' || item.multiSelect === true ? value.selected : [], ...(custom === '' ? {} : { custom }), } }), @@ -269,7 +275,11 @@ function QuestionFlow({ pending }: { pending: PendingQuestion }) { onChange={(event) => { const value = event.target.value updateDraft(current => ({ - ...current, selected: [], custom: value, customOpen: true, skipped: false, + ...current, + selected: question.multiSelect === true ? current.selected : [], + custom: value, + customOpen: true, + skipped: false, })) }} onKeyDown={(event) => { diff --git a/packages/client/ui-question/tests/question-composer.spec.tsx b/packages/client/ui-question/tests/question-composer.spec.tsx index 7df9f2bde9..3154eba0ee 100644 --- a/packages/client/ui-question/tests/question-composer.spec.tsx +++ b/packages/client/ui-question/tests/question-composer.spec.tsx @@ -96,13 +96,20 @@ describe('QuestionComposer', () => { fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' })) fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' })) fireEvent.click(screen.getByRole('checkbox', { name: '代码质量' })) - fireEvent.keyDown(screen.getByRole('checkbox', { name: '代码质量' }), { key: 'Enter' }) + fireEvent.click(screen.getByRole('button', { name: '其他，请填写自定义答案' })) + const multiCustom = screen.getByPlaceholderText('输入你的答案') + fireEvent.change(multiCustom, { target: { value: '沟通能力' } }) + fireEvent.click(screen.getByRole('checkbox', { name: '产品判断' })) + expect(screen.getByRole('checkbox', { name: '系统设计' }).getAttribute('aria-checked')).toBe('true') + expect(screen.getByRole('checkbox', { name: '代码质量' }).getAttribute('aria-checked')).toBe('true') + expect((multiCustom as HTMLTextAreaElement).value).toBe('沟通能力') + fireEvent.keyDown(multiCustom, { key: 'Enter' }) // The domain face encoded the whole batch into one carrier envelope. expect(respond).toHaveBeenCalledWith(answeredEnvelope('question-1', [ { id: 'profile', selected: ['工程落地型 (Recommended)'] }, { id: 'detail', selected: [], custom: '要能独立排查线上问题' }, - { id: 'signals', selected: ['系统设计', '代码质量'] }, + { id: 'signals', selected: ['系统设计', '代码质量', '产品判断'], custom: '沟通能力' }, ])) expect(screen.getByRole('button', { name: '正在提交…' }).disabled).toBe(true) }) diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml index 73b0845370..258ee74183 100644 --- a/packages/host/apiproxy/README.i18n.yaml +++ b/packages/host/apiproxy/README.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 packages/host/apiproxy/README.md -README.md: ca4471454f5be5d3fcba38ce665d4fb3fbd85e74 -README.zh.md: 953539e1198a52b2bf7cdd9ca1b0d263cc2ae6f9 +README.md: d517608404239809df03b089e150dbbecbf6d7cc +README.zh.md: f37427205fc72ef60f923d9d938adee0d4aa241c diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md index ca4471454f..d517608404 100644 --- a/packages/host/apiproxy/README.md +++ b/packages/host/apiproxy/README.md @@ -10,6 +10,8 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md). +Question responses are validated against their pending request before the first answer claims it. A multi-select item may carry both requested option labels in `selected` and non-empty `custom` text; a single-select item must use one or the other. Duplicate labels, unknown labels, mismatched ids, incomplete batches, and empty custom text are rejected as `bad-response`. + `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface. Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md index 953539e119..f37427205f 100644 --- a/packages/host/apiproxy/README.zh.md +++ b/packages/host/apiproxy/README.zh.md @@ -10,6 +10,8 @@ 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。 +首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。 + `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。 diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index f178bfefd0..585a6df305 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -275,7 +275,7 @@ function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQues if (new Set(answer.selected).size !== answer.selected.length) return false const custom = answer.custom?.trim() if (custom !== undefined && custom === '') return false - if (custom !== undefined && answer.selected.length > 0) return false + if (custom !== undefined && answer.selected.length > 0 && question.multiSelect !== true) return false if (question.multiSelect !== true && answer.selected.length > 1) return false const labels = new Set(question.options?.map(option => option.label) ?? []) return answer.selected.every(label => labels.has(label)) diff --git a/packages/host/apiproxy/tests/api-proxy-question.spec.ts b/packages/host/apiproxy/tests/api-proxy-question.spec.ts new file mode 100644 index 0000000000..e8eaae813f --- /dev/null +++ b/packages/host/apiproxy/tests/api-proxy-question.spec.ts @@ -0,0 +1,116 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import SessionStore from '@deepseek-ai/dsh-session' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' +import type { ApiProxy, MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api' +import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc' +import { createApiProxy } from '../src/api-proxy.ts' + +async function harness(): Promise<{ ctx: Context; api: ApiProxy }> { + const ctx = new Context() + await ctx.plugin(SessionStore) + await ctx.plugin(UserInteractionService) + return { + ctx, + api: createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }), + } +} + +function agent(id: string): Agent { + return { id } as unknown as Agent +} + +function openMux(api: ApiProxy, abort: AbortController): { + envelopes: RpcRequest[] + waitForQuestion(): Promise>> +} { + const envelopes: RpcRequest[] = [] + let resolveQuestion!: (value: RpcRequest>) => void + const question = new Promise>>((resolve) => { + resolveQuestion = resolve + }) + void (async () => { + for await (const envelope of api.events.mux({ rpcId: RpcId('question-mux'), payload: {} }, abort.signal)) { + envelopes.push(envelope) + if (envelope.payload.type === 'question/requested') { + resolveQuestion(envelope as RpcRequest>) + } + } + })() + return { envelopes, waitForQuestion: () => question } +} + +function answer( + envelope: RpcRequest>, + selected: string[], + custom?: string, +): Parameters[0] { + return { + type: 'client-response', + rpcId: envelope.rpcId, + result: { + ok: true, + value: { + sessionId: envelope.payload.sessionId, + answer: { + answers: [{ + id: envelope.payload.questions[0]?.id, + selected, + ...custom === undefined ? {} : { custom }, + }], + }, + }, + }, + } +} + +describe('question response validation', () => { + it('accepts selected options with custom text for multi-select questions', async () => { + const { ctx, api } = await harness() + const abort = new AbortController() + const mux = openMux(api, abort) + const asked = ctx.userInteraction.ask({ + agent: agent('session-multi'), + questions: [{ + id: 'targets', + question: 'Choose targets and add another', + multiSelect: true, + options: [{ label: 'Code' }, { label: 'Docs' }], + }], + }) + const envelope = await mux.waitForQuestion() + + expect(await api.respond(answer(envelope, ['Code', 'Docs'], 'Release notes'))) + .toEqual({ accepted: true }) + await expect(asked).resolves.toEqual({ + answers: [{ id: 'targets', selected: ['Code', 'Docs'], custom: 'Release notes' }], + }) + expect(mux.envelopes.some(item => item.payload.type === 'question/resolved')).toBe(true) + abort.abort() + }) + + it('keeps selected options and custom text mutually exclusive for single-select questions', async () => { + const { ctx, api } = await harness() + const abort = new AbortController() + const mux = openMux(api, abort) + const asked = ctx.userInteraction.ask({ + agent: agent('session-single'), + questions: [{ + id: 'target', + question: 'Choose one target', + options: [{ label: 'Code' }, { label: 'Docs' }], + }], + }) + const envelope = await mux.waitForQuestion() + + expect(await api.respond(answer(envelope, ['Code'], 'Release notes'))) + .toEqual({ accepted: false, reason: 'bad-response' }) + expect(await api.respond(answer(envelope, [], 'Release notes'))) + .toEqual({ accepted: true }) + await expect(asked).resolves.toEqual({ + answers: [{ id: 'target', selected: [], custom: 'Release notes' }], + }) + abort.abort() + }) +}) diff --git a/packages/ui/tool-ask-user/README.i18n.yaml b/packages/ui/tool-ask-user/README.i18n.yaml index a03a7326fa..09c111ba9d 100644 --- a/packages/ui/tool-ask-user/README.i18n.yaml +++ b/packages/ui/tool-ask-user/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -README.md: 8e779f4025c20cd200344efb7cb8cd6bc09ba64d -README.zh.md: fe1dc5559882532c4f44e705cc6daa2c7f4f8905 +# pnpm run verify-translation-pairing --write packages/ui/tool-ask-user/README.md +README.md: 64da4d75d01a0df0ae51b1557ed1c796317b906f +README.zh.md: 8a1eb3ee4f9e9ccc2ea2fe433bf85158c76d3549 diff --git a/packages/ui/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md index 8e779f4025..64da4d75d0 100644 --- a/packages/ui/tool-ask-user/README.md +++ b/packages/ui/tool-ask-user/README.md @@ -15,7 +15,7 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo - `options` — optional choices with `label` and `description`. If recommending a choice, put it first and append `(Recommended)` to that label. - `multi_select` — whether that question may return more than one selected option. -The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices. The Native renderer preserves the compact JSON text shape `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. +The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `custom` carries a free-form answer, supplementing `selected` for a multi-select question and overriding it for a single-select question. The Native renderer preserves the compact JSON text shape `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. ## Role diff --git a/packages/ui/tool-ask-user/README.zh.md b/packages/ui/tool-ask-user/README.zh.md index fe1dc55598..8a1eb3ee4f 100644 --- a/packages/ui/tool-ask-user/README.zh.md +++ b/packages/ui/tool-ask-user/README.zh.md @@ -15,7 +15,7 @@ - `options`：可选选项，包含 `label` 和 `description`。如需推荐某个选项，请将其置于首位，并在该标签末尾追加 `(Recommended)`。 - `multi_select`：该问题是否可以返回多个选中的选项。 -工具调用 `ctx.userInteraction.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；仅当用户自由填写回答时才会出现 `custom`，并覆盖选中的选项。Native renderer 会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。 +工具调用 `ctx.userInteraction.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；`custom` 携带自由填写的回答，对于多选题会补充 `selected`，对于单选题则会覆盖它。Native renderer 会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。 ## 职责 diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts index 395986aed1..7d019a520a 100644 --- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts +++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts @@ -140,7 +140,7 @@ describe('ask_user_question tool', () => { async ask() { return { answers: [ - { id: 'targets', selected: ['tests', 'docs'] }, + { id: 'targets', selected: ['tests', 'docs'], custom: 'release notes' }, { id: 'notes', selected: [], custom: 'ship today' }, ], } @@ -168,13 +168,13 @@ describe('ask_user_question tool', () => { if (result.isError) throw new Error('expected ask_user_question success') expect(result.value).toEqual({ answers: [ - { id: 'targets', selected: ['tests', 'docs'] }, + { id: 'targets', selected: ['tests', 'docs'], custom: 'release notes' }, { id: 'notes', selected: [], custom: 'ship today' }, ], }) expect(result.content).toEqual([{ type: 'text', - text: '{"answers":[{"id":"targets","selected":["tests","docs"]},{"id":"notes","selected":[],"custom":"ship today"}]}', + text: '{"answers":[{"id":"targets","selected":["tests","docs"],"custom":"release notes"},{"id":"notes","selected":[],"custom":"ship today"}]}', }]) }) diff --git a/packages/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml index 8ab63910fa..b62fb70da3 100644 --- a/packages/ui/tui/README.i18n.yaml +++ b/packages/ui/tui/README.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 packages/ui/tui/README.md -README.md: 0b358520b863f0b9ee7a128cf4807f582fc46d8d -README.zh.md: 7e89197bd82d16dfbabeb715e953275e2f6dd68b +README.md: 3c847828a3d560b85e74809f984bc9ea581e417f +README.zh.md: 8872484a5de376e41564756332200198e587d2b3 diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index 0b358520b8..3c847828a3 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -153,7 +153,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels or `custom` text. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`. +When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels, `custom` text, or both for a multi-select question. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`. #### Token effect diff --git a/packages/ui/tui/README.zh.md b/packages/ui/tui/README.zh.md index 7e89197bd8..8872484a5d 100644 --- a/packages/ui/tui/README.zh.md +++ b/packages/ui/tui/README.zh.md @@ -153,7 +153,7 @@ Paths prefixed with @ are files explicitly referenced by the user. Use the read #### 模型看到的内容 -消费方调用 `ctx.userInteraction.ask()` 时，此提供方会按顺序显示各个问题，并返回选中选项标签或 `custom` 文本。中止、取消或 UI dispose 会变为 `Error: ask_user_question was interrupted before the user answered`；该转换由 `dsh-tool-ask-user` 完成。 +消费方调用 `ctx.userInteraction.ask()` 时，此提供方会按顺序显示各个问题，并返回选中选项标签、`custom` 文本，或为多选题同时返回两者。中止、取消或 UI dispose 会变为 `Error: ask_user_question was interrupted before the user answered`；该转换由 `dsh-tool-ask-user` 完成。 #### Token 影响 diff --git a/packages/ui/tui/src/components/dialogs.ts b/packages/ui/tui/src/components/dialogs.ts index 5e9237574a..ffdfb83c5a 100644 --- a/packages/ui/tui/src/components/dialogs.ts +++ b/packages/ui/tui/src/components/dialogs.ts @@ -799,12 +799,14 @@ export class QuestionDialog implements Component, Focusable { if (this.selected.has(this.selectedIndex)) this.selected.delete(this.selectedIndex) else this.selected.add(this.selectedIndex) } else if (matchesKey(data, Key.enter)) { - const indices = this.question.multiSelect ? [...this.selected].sort((a, b) => a - b) : [this.selectedIndex] - if (indices.length === 0) { + const selected = this.question.multiSelect + ? this.selectedOptionLabels() + : [options[this.selectedIndex]?.label].filter((label): label is string => label !== undefined) + if (selected.length === 0) { this.error = 'Select at least one option, or press Tab for a custom answer.' return } - this.done({ selected: indices.map(index => options[index]?.label).filter((label): label is string => label !== undefined) }) + this.done({ selected }) } else if (matchesKey(data, Key.tab) || data.toLowerCase() === 'c') { this.mode = 'custom' this.error = '' @@ -819,7 +821,17 @@ export class QuestionDialog implements Component, Focusable { this.error = 'Enter an answer before submitting.' return } - this.done({ selected: [], custom }) + this.done({ + selected: this.question.multiSelect ? this.selectedOptionLabels() : [], + custom, + }) + } + + private selectedOptionLabels(): string[] { + return [...this.selected] + .sort((a, b) => a - b) + .map(index => this.options[index]?.label) + .filter((label): label is string => label !== undefined) } render(width: number): string[] { diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index e918f9b299..1ee0b4fe38 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -4436,8 +4436,12 @@ describe('TUI user-interaction dialogs', () => { result.terminal.send(' ') result.terminal.send('\x1b[B') result.terminal.send(' ') + result.terminal.send('\t') + result.terminal.send('Tests') result.terminal.send('\r') - await expect(multi).resolves.toEqual({ answers: [{ id: 'targets', selected: ['Code', 'Docs'] }] }) + await expect(multi).resolves.toEqual({ + answers: [{ id: 'targets', selected: ['Code', 'Docs'], custom: 'Tests' }], + }) const custom = result.ctx.userInteraction.ask({ questions: [{ id: 'other', question: 'Choose or type', options: [{ label: 'Default' }] }], diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml index 2a3b525012..c9ff2845e5 100644 --- a/packages/ui/user-interaction/README.i18n.yaml +++ b/packages/ui/user-interaction/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32 -README.zh.md: b70a61d6491e0bb0e52215cdeaeea3d728f7f153 +# pnpm run verify-translation-pairing --write packages/ui/user-interaction/README.md +README.md: 2ff29f5fd6244ebcf7e29b86f5de1cde30944532 +README.zh.md: 7d0d1b06db5be4353e42d1905c71d5dff963b97d diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md index d234d6677b..2ff29f5fd6 100644 --- a/packages/ui/user-interaction/README.md +++ b/packages/ui/user-interaction/README.md @@ -19,7 +19,7 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod - `UserInteractionProvider` — UI implementation with `ask(request)`. - `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`. -When an answer includes `custom`, `selected` is empty; custom text is an override rather than a supplement to selected choices. A UI may preserve a skipped item as `{ id, selected: [] }`, keeping the existing answer shape while retaining other answers in the batch. +For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may preserve a skipped item as `{ id, selected: [] }`, keeping the existing answer shape while retaining other answers in the batch. ## Role diff --git a/packages/ui/user-interaction/README.zh.md b/packages/ui/user-interaction/README.zh.md index b70a61d649..7d0d1b06db 100644 --- a/packages/ui/user-interaction/README.zh.md +++ b/packages/ui/user-interaction/README.zh.md @@ -19,7 +19,7 @@ - `UserInteractionProvider`：包含 `ask(request)` 的 UI 实现。 - `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。 -当回答包含 `custom` 时，`selected` 为空；自定义文本会覆盖所选选项，而不是补充它们。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。 +对于单选题，`custom` 会覆盖选中的选项，且 `selected` 为空。对于多选题，`custom` 可以补充 `selected` 中的标签。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。 ## 职责 diff --git a/packages/ui/user-interaction/src/types.ts b/packages/ui/user-interaction/src/types.ts index ddf3e43489..435782a8f5 100644 --- a/packages/ui/user-interaction/src/types.ts +++ b/packages/ui/user-interaction/src/types.ts @@ -33,7 +33,7 @@ export interface AskUserQuestionItem { export interface AskUserQuestionAnswerItem { /** The answered question id. */ id: string - /** Selected option labels. Empty for custom or unanswered choices. */ + /** Selected option labels. May accompany custom text for a multi-select question. */ selected: string[] /** Optional free-text "Other" answer. */ custom?: string From f2e20c1ef04b27501016dabda696fe6891781489 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 13:49:57 +0800 Subject: [PATCH 007/689] refactor(agent-loop): simplify message machine --- ...nt-lifecycle-and-ownership-seams.i18n.yaml | 6 +- ...-18-agent-lifecycle-and-ownership-seams.md | 2 +- ...-agent-lifecycle-and-ownership-seams.zh.md | 2 +- ...-21-bounded-llm-request-recovery.i18n.yaml | 4 +- ...2026-06-21-bounded-llm-request-recovery.md | 12 +- ...6-06-21-bounded-llm-request-recovery.zh.md | 12 +- ...n-pressure-and-overflow-recovery.i18n.yaml | 4 +- ...mpaction-pressure-and-overflow-recovery.md | 4 +- ...ction-pressure-and-overflow-recovery.zh.md | 4 +- ...send-and-coalesced-user-messages.i18n.yaml | 4 +- ...nified-send-and-coalesced-user-messages.md | 11 +- ...ied-send-and-coalesced-user-messages.zh.md | 11 +- ...xt-injection-from-turn-execution.i18n.yaml | 4 +- ...e-context-injection-from-turn-execution.md | 8 +- ...ontext-injection-from-turn-execution.zh.md | 8 +- ...ntified-immutable-message-values.i18n.yaml | 4 +- ...-28-identified-immutable-message-values.md | 6 +- ...-identified-immutable-message-values.zh.md | 6 +- ...-29-terminal-llm-stream-failures.i18n.yaml | 6 + ...2026-07-29-terminal-llm-stream-failures.md | 37 + ...6-07-29-terminal-llm-stream-failures.zh.md | 37 + ...cated-full-screen-tui-front-door.i18n.yaml | 4 +- ...17-dedicated-full-screen-tui-front-door.md | 2 +- ...dedicated-full-screen-tui-front-door.zh.md | 2 +- ...26-07-19-model-facing-goal-tools.i18n.yaml | 6 +- .../2026-07-19-model-facing-goal-tools.md | 2 +- .../2026-07-19-model-facing-goal-tools.zh.md | 2 +- ...7-19-plugin-command-registration.i18n.yaml | 6 +- .../2026-07-19-plugin-command-registration.md | 2 +- ...26-07-19-plugin-command-registration.zh.md | 2 +- ...9-same-session-goal-round-driver.i18n.yaml | 6 +- ...26-07-19-same-session-goal-round-driver.md | 4 +- ...07-19-same-session-goal-round-driver.zh.md | 4 +- ...6-07-21-cross-session-references.i18n.yaml | 4 +- .../2026-07-21-cross-session-references.md | 6 +- .../2026-07-21-cross-session-references.zh.md | 6 +- ...26-07-21-tui-skill-slash-command.i18n.yaml | 6 +- .../2026-07-21-tui-skill-slash-command.md | 2 +- .../2026-07-21-tui-skill-slash-command.zh.md | 2 +- ...-06-20-public-agent-stop-surface.i18n.yaml | 6 +- .../2026-06-20-public-agent-stop-surface.md | 2 +- ...2026-06-20-public-agent-stop-surface.zh.md | 2 +- .../2026-07-17-one-send-one-turn.i18n.yaml | 4 +- .../2026-07-17-one-send-one-turn.md | 8 +- .../2026-07-17-one-send-one-turn.zh.md | 8 +- ...nt-loop-observable-state-machine.i18n.yaml | 4 +- ...-24-agent-loop-observable-state-machine.md | 2 +- ...-agent-loop-observable-state-machine.zh.md | 2 +- ...07-27-request-error-retry-action.i18n.yaml | 4 +- .../2026-07-27-request-error-retry-action.md | 2 +- ...026-07-27-request-error-retry-action.zh.md | 2 +- .../2026-07-30-private-agent-send.i18n.yaml | 6 + .../2026-07-30-private-agent-send.md | 27 + .../2026-07-30-private-agent-send.zh.md | 27 + apps/cli/src/headless.ts | 2 +- apps/web/tests/cordis-tool-round.e2e.ts | 4 +- apps/web/tests/scaffold.ts | 17 +- docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 6 +- docs/architecture.zh.md | 6 +- docs/cordis-catalog/events.md | 178 ++--- docs/cordis-catalog/services.md | 20 +- docs/core-data-structures/core.i18n.yaml | 4 +- docs/core-data-structures/core.md | 70 +- docs/core-data-structures/core.zh.md | 70 +- docs/defensive-patterns.i18n.yaml | 6 +- docs/defensive-patterns.md | 2 +- docs/defensive-patterns.zh.md | 2 +- .../tests/semantic-checkpoint.snapshot.ts | 2 +- .../tests/subagent-inheritance.snapshot.ts | 2 +- .../tui-agent/tests/tui-keyless-smoke.e2e.ts | 2 +- packages/acp/acp/src/codec.ts | 1 - packages/acp/acp/tests/approval.spec.ts | 2 +- packages/acp/acp/tests/codec.spec.ts | 5 +- packages/acp/acp/tests/turns.spec.ts | 2 +- .../client/connection/src/client/fixture.ts | 8 +- .../runtime/src/client/sessions/session.ts | 30 +- packages/client/runtime/tests/event-script.ts | 2 +- .../client/runtime/tests/queue-store.spec.ts | 34 +- packages/compact/compact-basic/src/index.ts | 12 +- .../compact-basic/tests/compact-basic.spec.ts | 22 +- .../tests/compact-loop-repro.spec.ts | 1 - .../tests/tool-result-prune.spec.ts | 5 - .../compact/compact/tests/invariant.spec.ts | 6 +- .../time-context/tests/invariant.spec.ts | 12 +- .../time-context/tests/time-context.spec.ts | 5 +- .../tests/workspace-context.spec.ts | 1 - .../cordis/tool-cordis/src/api-catalog.ts | 81 +- packages/core/agent-loop/README.i18n.yaml | 4 +- packages/core/agent-loop/README.md | 4 +- packages/core/agent-loop/README.zh.md | 4 +- packages/core/agent-loop/src/agent.ts | 753 ++++++------------ packages/core/agent-loop/src/index.ts | 15 +- packages/core/agent-loop/tests/cancel.spec.ts | 82 +- .../agent-loop/tests/coverage-edges.spec.ts | 18 - .../core/agent-loop/tests/invariant.spec.ts | 6 +- packages/core/agent-loop/tests/loop.spec.ts | 11 +- .../agent-loop/tests/request-error.spec.ts | 12 +- packages/core/agent-loop/tests/resume.spec.ts | 8 +- .../agent-loop/tests/scope-lifecycle.spec.ts | 2 +- packages/core/agent/README.i18n.yaml | 4 +- packages/core/agent/README.md | 7 +- packages/core/agent/README.zh.md | 7 +- packages/core/agent/src/invariant.ts | 21 - packages/core/agent/src/types.ts | 265 ++---- packages/core/agent/tests/agent.spec.ts | 5 - packages/core/agent/tsdown.config.ts | 2 +- .../core/scope/src/scoped-events.generated.ts | 7 +- packages/core/scope/tests/invariant.spec.ts | 2 - packages/core/session/README.i18n.yaml | 4 +- packages/core/session/README.md | 1 - packages/core/session/README.zh.md | 1 - packages/core/session/src/index.ts | 21 - packages/core/session/src/types.ts | 47 +- .../core/session/tests/derived-cache.spec.ts | 12 +- packages/core/session/tests/fork.spec.ts | 16 +- packages/core/session/tests/invariant.spec.ts | 59 +- .../core/session/tests/properties.spec.ts | 2 +- packages/core/session/tests/repair.spec.ts | 2 +- .../core/session/tests/request-header.spec.ts | 4 +- packages/core/session/tests/scoped.spec.ts | 4 +- packages/core/session/tests/session.spec.ts | 94 +-- packages/core/session/tests/surface.spec.ts | 20 +- packages/core/tools/tests/invariant.spec.ts | 4 +- .../agent-spine-demo/tests/agent-core.spec.ts | 5 +- packages/examples/cli-demo/tests/cli.spec.ts | 12 +- .../command-goal/tests/command-goal.spec.ts | 3 +- packages/goal/goal-session/src/index.ts | 104 +-- packages/goal/goal-session/src/outcome.ts | 8 +- .../goal-session/tests/goal-session.spec.ts | 36 +- .../goal/goal-session/tests/invariant.spec.ts | 12 +- packages/goal/goal/tests/goal.spec.ts | 13 +- packages/goal/goal/tests/invariant.spec.ts | 6 +- packages/goal/goal/tests/projection.spec.ts | 3 +- .../goal/tool-goal/tests/tool-goal.spec.ts | 3 +- .../hook-protocol/tests/invariant.spec.ts | 6 +- packages/hooks/hooks-claude/src/index.ts | 13 +- packages/hooks/hooks-codex/src/index.ts | 12 +- packages/host/apiproxy/src/api-proxy.ts | 33 +- .../host/apiproxy/src/api/events.schema.ts | 2 +- packages/host/apiproxy/src/api/events.ts | 8 +- .../apiproxy/tests/api-proxy-blank.spec.ts | 2 +- .../tests/api-proxy-projections.spec.ts | 2 +- .../apiproxy/tests/api-proxy-view.spec.ts | 8 +- .../tests/api-proxy-workspace.spec.ts | 1 - packages/llm/llm-retry/src/index.ts | 37 +- packages/llm/llm-retry/src/invariant.ts | 32 +- .../llm/llm-retry/tests/invariant.spec.ts | 16 +- .../llm/llm-retry/tests/persistence.spec.ts | 2 +- packages/llm/llm/README.i18n.yaml | 4 +- packages/llm/llm/README.md | 8 +- packages/llm/llm/README.zh.md | 8 +- packages/llm/llm/src/adapter-failure.ts | 110 +-- packages/llm/llm/src/assembler.ts | 10 +- packages/llm/llm/src/index.ts | 92 +-- packages/llm/llm/src/invariant.ts | 4 +- packages/llm/llm/src/types.ts | 5 +- .../llm/token-meter/tests/token-meter.spec.ts | 2 +- .../plan/plan-mode/tests/invariant.spec.ts | 8 +- .../plan/plan-mode/tests/plan-mode.spec.ts | 2 +- .../plan/plan-mode/tests/projection.spec.ts | 2 +- packages/pty/pty-local/tests/index.spec.ts | 10 +- packages/pty/pty-local/tests/local.spec.ts | 2 +- packages/pty/pty/tests/service.spec.ts | 1 - .../tool-pty/tests/loader-composition.spec.ts | 2 +- packages/pty/tool-pty/tests/tools.spec.ts | 2 +- .../tests/session-checkpoint-policy.spec.ts | 2 +- .../tests/jsonl.spec.ts | 46 +- .../tests/zstd.spec.ts | 8 +- .../tests/sqlite.spec.ts | 26 +- .../session-persistence/tests/contract.ts | 16 +- .../tests/coordinator-contract.ts | 44 +- .../tests/persistence.spec.ts | 24 +- .../tests/cache.spec.ts | 2 +- .../session-projection/tests/registry.spec.ts | 10 +- .../session-query/src/extraction.ts | 5 +- .../tests/search-helpers.spec.ts | 2 +- .../session-query/tests/session-query.spec.ts | 8 +- .../session-query/tests/tracing.spec.ts | 8 +- .../tests/sqlite-integration.spec.ts | 2 +- .../tests/tool-session-query.spec.ts | 2 +- .../tests/provider.spec.ts | 4 +- .../tests/loader-composition.spec.ts | 1 - .../tests/provider.e2e.ts | 1 - .../tests/provider.spec.ts | 2 +- .../session-title-llm/tests/llm.spec.ts | 1 - .../session-title/tests/persistence.spec.ts | 1 - .../session-title/tests/projection.spec.ts | 2 +- .../session-title/tests/provider.spec.ts | 10 - .../tests/service-contracts.spec.ts | 4 - .../session-title/tests/session-title.spec.ts | 3 - .../skill/tool-skill/tests/tool-skill.spec.ts | 2 - .../subagent/subagent-inprocess/src/index.ts | 13 +- .../tests/subagent-inprocess.spec.ts | 33 +- .../llm-replay/tests/llm-replay.spec.ts | 2 +- .../tasks/tasks-local/tests/tasks.spec.ts | 1 - .../session-telemetry-otel/tests/otel.spec.ts | 8 +- .../session-telemetry/tests/telemetry.spec.ts | 10 +- .../todo/tool-todo/tests/invariant.spec.ts | 2 +- .../todo/tool-todo/tests/projection.spec.ts | 2 +- packages/ui/commands/tests/commands.spec.ts | 2 +- packages/ui/jsonrpc/src/server.ts | 21 +- packages/ui/jsonrpc/tests/server.spec.ts | 8 +- packages/ui/tui/src/components/dialogs.ts | 1 - packages/ui/tui/src/index.ts | 111 +-- packages/ui/tui/tests/harness.ts | 12 - packages/ui/tui/tests/tui.snapshot.ts | 9 +- packages/ui/tui/tests/tui.spec.ts | 38 +- .../ui/user-approval/tests/approval.spec.ts | 6 +- .../ui/user-approval/tests/invariant.spec.ts | 6 +- scripts/gen-cordis-catalog.ts | 4 +- scripts/type-equiv.manifest.json | 10 - 212 files changed, 1326 insertions(+), 2382 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md create mode 100644 .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md create mode 100644 .agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml create mode 100644 .agents/notes/implemented/simplification/2026-07-30-private-agent-send.md create mode 100644 .agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml index 3b07958faa..a9795ab9fc 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-06-18-agent-lifecycle-and-ownership-seams.md: f190b4ba2b7f22d29f473c8a2725401ff371488e -2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: dcaa319232baa8951a4f515abc6bce5611da5576 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md +2026-06-18-agent-lifecycle-and-ownership-seams.md: 93247a6da7446a5a67db33423d2b766ce4cf3308 +2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: 0705862c6091be0143750e5a518688dec4995156 diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md index f190b4ba2b..93247a6da7 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md +++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md @@ -47,4 +47,4 @@ The bash owner-token comparison relies on the shared `Agent.id`/`SessionId` bein ## Consequences -This touched public interfaces (`Agent`, `AgentFactory`, the bash seam) deliberately, not as a local ACP patch. The simple synchronous `Agent.send()` ergonomics were preserved; the async lifecycle path is additive, for owners that need it. +This touched public interfaces (`Agent`, `AgentFactory`, the bash seam) deliberately, not as a local ACP patch. Synchronous agent delivery remains simple; the async lifecycle path is additive for owners that need it. diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md index dcaa319232..0705862c60 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md @@ -47,4 +47,4 @@ bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agen ## 后果 -本变更有意触及公开接口（`Agent`、`AgentFactory`、bash seam），而非作为 ACP 的局部补丁。同步 `Agent.send()` 的简洁易用性得以保留；异步生命周期路径是增量添加的，供需要它的所有者使用。 +本变更有意触及公开接口（`Agent`、`AgentFactory`、bash seam），而非作为 ACP 的局部补丁。同步 agent 交付仍然简单；异步生命周期路径是增量添加的，供需要它的所有者使用。 diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml index 0d6a23bebe..8372358c88 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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/architecture/2026-06-21-bounded-llm-request-recovery.md -2026-06-21-bounded-llm-request-recovery.md: 83d47e3a7d91bbcd2ceaf7b11cf13316142eb3ed -2026-06-21-bounded-llm-request-recovery.zh.md: 00dcbad3d1023ad33a22297bfe938b94bce839d4 +2026-06-21-bounded-llm-request-recovery.md: 3efb0bb62e10b3ee34af6358902a48f15b835245 +2026-06-21-bounded-llm-request-recovery.zh.md: 5477c8ea3bb4fc019fb99d4da616b3cc15f72044 diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md index 83d47e3a7d..3efb0bb62e 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md +++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md @@ -4,11 +4,11 @@ Status: implemented English | [中文](2026-06-21-bounded-llm-request-recovery.zh.md) -The [per-provider request retry policy](../feature/2026-07-24-provider-retry-policies.md) extends this foundation with exact-provider configuration and an explicit unbounded mode. This note continues to own structured failure facts, the closed-step recovery boundary, normal mode's transient defaults, visible single attempts, and durable retry status. +The [per-provider request retry policy](../feature/2026-07-24-provider-retry-policies.md) extends this foundation with exact-provider configuration and an explicit unbounded mode. This note continues to own structured failure facts, the closed-step recovery boundary, normal mode's transient defaults, visible single attempts, and durable retry status. [Terminal LLM stream failures](2026-07-29-terminal-llm-stream-failures.md) supersedes its thrown-error identity and stream-sidecar mechanism. ## Problem -`dsh-llm` can report provider failures either by throwing during adapter dispatch or iteration or by ending with `finish { kind: 'error' | 'aborted' }`. The final adapter boundary tags thrown failures so `dsh-agent-loop` can distinguish them from middleware and result-processing defects, and the loop normalizes both delivery forms into `agent/request-error` after closing the failed step. An unhandled failure is terminal; a handling listener repairs policy-owned state, returns `{ kind: 'retry' }`, and stops waterfall delegation. The [retry-action decision](../simplification/2026-07-27-request-error-retry-action.md) owns this return contract. +Provider adapters can fail by throwing during dispatch or iteration or by ending with `finish { kind: 'error' | 'aborted' }`. The final adapter boundary normalizes thrown values to that terminal finish protocol before `dsh-agent-loop` receives them; middleware and result-processing defects remain thrown. The loop offers a terminal model-request failure to `agent/request-error`. An unhandled failure is terminal; a handling listener repairs policy-owned state, returns `{ kind: 'retry' }`, and stops waterfall delegation. The [retry-action decision](../simplification/2026-07-27-request-error-retry-action.md) owns this return contract. That boundary is already safe for another request attempt. Raw `assistant/chunk` events carry the failed `turn` and `step`, message derivation ignores them unless a successful `assistant/message` cites them, tool calls are dispatched only after a successful terminal finish and assembly, and a retry opens a new numbered turn from the durable log. The harness therefore does not need a second response lifecycle or tentative-output protocol to keep two attempts separate. @@ -40,9 +40,9 @@ interface LlmFailure { `code` remains the provider-neutral machine-routing taxonomy established by `HarnessError`; the new fields are observations from the provider boundary. `ProviderRequestId` is owned and constructed by `dsh-llm`, then serializes as its provider-issued string. The payload deliberately has no `retryable`, `failover`, `partialOutput`, provider, model, phase, or route id fields. Retryability belongs to policy, provider/model are already in the durable request header, and partial output is derived from the failed step's `assistant/chunk` events. -`LlmError` carries `failure: LlmFailure` and preserves `failure.code === error.code`. `FinishReasonMap.error` and `FinishReasonMap.aborted` carry the same payload instead of parallel failure shapes. An adapter-thrown `Error` keeps its exact object identity: the final-adapter scope associates the normalized facts with that object in call-local sidecar state and rethrows it unchanged; a non-`Error` throw is wrapped as today. `llmFailureOf(stream, error)` retrieves those facts alongside the existing provenance check, while an in-band finish without an error object becomes a new `LlmError`. This preserves listeners that key on error type or identity while giving all final-adapter failures, including unknown SDK exceptions, an `UNKNOWN` terminal payload. +`LlmError` carries `failure: LlmFailure` and preserves `failure.code === error.code`. `FinishReasonMap.error` and `FinishReasonMap.aborted` carry the same payload instead of parallel failure shapes. The final adapter boundary detaches those facts from adapter-thrown values and emits the appropriate terminal finish; unknown SDK exceptions receive an `UNKNOWN` payload. Exact thrown-object identity does not cross the LLM stream seam. -The agent loop keeps `RequestError` as that exact error object and passes `LlmFailure` as a separate argument to `agent/request-error`; it does not mutate possibly frozen third-party errors. It also uses the payload when converting an in-band finish and when recording an unrecovered `turn/end.reason`. +The agent loop passes the terminal finish's `LlmFailure` to `agent/request-error` and uses the same payload when recording an unrecovered `turn/end.reason`. Adapters extract structured facts before falling back to message inspection. They validate HTTP status, parse `Retry-After` seconds or dates into a positive finite millisecond delay, brand the provider request id when exposed, and distinguish their own timeout from the caller's abort. Provider-specific codes and messages may refine a mapping, but no recovery listener parses them. @@ -106,8 +106,8 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason` ## Verification -- `LlmFailure` is the single serializable payload for thrown, error-finish, and aborted-finish final-adapter failures; normalization preserves stable code, status, retry delay, branded provider request id, error cause, and caller-abort versus adapter-timeout classification where available. -- An adapter-thrown `Error` reaches `agent/request-error` as the exact same object while its sidecar `LlmFailure` reaches the adjacent argument; tests retain the existing identity assertion for extensible and frozen third-party errors. +- `LlmFailure` is the single serializable payload for adapter throws, error finishes, and aborted finishes; normalization preserves stable code, status, retry delay, branded provider request id, and caller-abort versus adapter-timeout classification where available. +- Adapter throws become terminal failure chunks before reaching consumers; middleware and consumer exceptions remain thrown outside model-request recovery. - DeepSeek and pi-ai adapter tests cover representative 400, 401/403, 429, 5xx, connection, malformed/truncated stream, timeout, abort, retry-after seconds/date, request-id, and unknown-SDK-error paths without recovery policy parsing message text. - Pi-ai pins the SDK option to zero retries and performs one observed wire attempt for a retryable provider response; separate tests make removing either boundary fail. - `agent/request-error` carries current failure facts, immutable prior-retried failure facts, and the serving registration's immutable retry policy; a success clears the history, and alternating transient/context-overflow integration tests prove the two policies consume only their own finite budgets. diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md index 00dcbad3d1..5477c8ea3b 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md @@ -4,11 +4,11 @@ Status: implemented [English](2026-06-21-bounded-llm-request-recovery.md) | 中文 -[按提供方配置的请求重试策略](../feature/2026-07-24-provider-retry-policies.md)在此基础上增加了确切提供方配置与显式无界 mode。本说明继续负责结构化失败事实、已关闭步骤的恢复边界、normal mode 的暂时性默认值、可见的单次尝试和持久重试状态。 +[按提供方配置的请求重试策略](../feature/2026-07-24-provider-retry-policies.md)在此基础上增加了确切提供方配置与显式无界 mode。本说明继续负责结构化失败事实、已关闭步骤的恢复边界、normal mode 的暂时性默认值、可见的单次尝试和持久重试状态。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)取代了其中关于抛出错误身份和 stream sidecar 的机制。 ## 问题 -`dsh-llm` 可能在适配器分发或迭代时抛出异常，也可能以 `finish { kind: 'error' | 'aborted' }` 结束，以这两种形式报告提供方失败。最终适配器边界会标记抛出的失败，使 `dsh-agent-loop` 能将其与中间件和结果处理缺陷区分开。循环关闭失败步骤后，会把两种交付形式统一规范化为 `agent/request-error`。未被处理的失败是终态；处理失败的监听器修复策略自有状态，返回 `{ kind: 'retry' }`，并停止 waterfall 委托。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回契约。 +提供方适配器可能在分发或迭代时抛出异常，也可能以 `finish { kind: 'error' | 'aborted' }` 结束。最终适配器边界会在 `dsh-agent-loop` 接收前把抛出值规范化为该终止 finish 协议；middleware 与结果处理缺陷仍会抛出。loop 会将终止模型请求失败交给 `agent/request-error`。未被处理的失败是终态；处理失败的监听器修复策略自有状态，返回 `{ kind: 'retry' }`，并停止 waterfall 委托。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回契约。 该边界已能安全地再次发起请求。原始 `assistant/chunk` 事件携带失败的 `turn` 和 `step`；除非某条成功的 `assistant/message` 引用这些事件，否则消息派生会忽略它们。只有终止性 finish 成功且组装完成后，系统才会分发工具调用；重试则会从持久日志开启新的编号轮次。因此，harness 无需引入第二套响应生命周期或暂定输出协议，即可分隔两次尝试。 @@ -40,9 +40,9 @@ interface LlmFailure { `code` 仍是 `HarnessError` 建立的提供方无关机器路由分类体系；新字段是在提供方边界观测到的事实。`ProviderRequestId` 由 `dsh-llm` 拥有并构造，序列化后为提供方发放的字符串。该载荷有意不包含 `retryable`、`failover`、`partialOutput`、提供方、模型、阶段或路由 id 字段。是否可重试属于策略，提供方／模型已位于持久请求头中，部分输出则从失败步骤的 `assistant/chunk` 事件派生。 -`LlmError` 携带 `failure: LlmFailure`，并保持 `failure.code === error.code`。`FinishReasonMap.error` 和 `FinishReasonMap.aborted` 携带同一载荷，而不是并行的失败形状。适配器抛出的 `Error` 保留其精确的对象标识：最终适配器 scope 在调用局部的伴随状态中把规范化事实与该对象关联，然后原样重新抛出；非 `Error` 抛出值则依旧被包装。`llmFailureOf(stream, error)` 会在现有来源检查旁取回这些事实，而没有错误对象的带内 finish 则会成为新的 `LlmError`。这既保留了按错误类型或标识分流的监听器，又使所有最终适配器失败（包括未知 SDK 异常）都获得 `UNKNOWN` 终止载荷。 +`LlmError` 携带 `failure: LlmFailure`，并保持 `failure.code === error.code`。`FinishReasonMap.error` 和 `FinishReasonMap.aborted` 携带同一载荷，而不是并行的失败形状。最终适配器边界会从适配器抛出值中分离这些事实，并发出相应的终止 finish；未知 SDK 异常会获得 `UNKNOWN` 载荷。精确的抛出对象身份不会跨越 LLM stream seam。 -agent loop（智能体循环）会保留 `RequestError` 作为该精确的错误对象，并将 `LlmFailure` 作为独立参数传给 `agent/request-error`；它不会改动可能已冻结的第三方错误。在转换带内 finish 以及记录未恢复的 `turn/end.reason` 时，循环也会使用该载荷。 +agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agent/request-error`，并在记录未恢复的 `turn/end.reason` 时使用同一载荷。 适配器会先提取结构化事实，再回退到消息检查。它们会验证 HTTP 状态，将 `Retry-After` 的秒数或日期解析为正的有限毫秒延迟，在提供方公开请求 id 时将其品牌化，并区分自身超时与调用方中止。提供方专用 code 和消息可以细化映射，但恢复监听器不会解析它们。 @@ -106,8 +106,8 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次 ## 验证 -- `LlmFailure` 是最终适配器抛出失败、错误 finish 和中止 finish 使用的唯一可序列化载荷；在可用时，规范化保留稳定 code、状态、重试延迟、品牌化的提供方请求 id、错误原因，以及调用方中止与适配器超时之间的分类。 -- 适配器抛出的 `Error` 会以完全相同的对象抵达 `agent/request-error`，其伴随的 `LlmFailure` 则抵达相邻参数；测试保留针对可扩展及冻结第三方错误的现有对象标识断言。 +- `LlmFailure` 是适配器抛出、错误 finish 和中止 finish 使用的唯一可序列化载荷；在可用时，规范化保留稳定 code、状态、重试延迟、品牌化的提供方请求 id，以及调用方中止与适配器超时之间的分类。 +- 适配器抛出值会在抵达消费方前成为终止失败 chunk；middleware 与消费方异常仍在模型请求恢复之外抛出。 - DeepSeek 和 pi-ai 适配器测试覆盖具有代表性的 400、401/403、429、5xx、连接、格式错误／截断流、超时、中止、Retry-After 秒数／日期、请求 id 和未知 SDK 错误路径，恢复策略无需解析消息文本。 - Pi 将 SDK 选项固定为零次重试，并针对可重试的提供方响应执行一次可观测的实际网络请求；独立测试确保移除任一边界都会失败。 - `agent/request-error` 携带当前失败事实、不可变的先前已重试失败事实，以及实际服务注册所对应的不可变重试策略；成功会清除历史，暂时性失败／上下文溢出交替发生的集成测试证明两种策略只消耗各自的有限预算。 diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml index 1904a25158..3d45205e46 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.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/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md -2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 51d488db28c57426c75c9ed1cfc90892261c0224 -2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: ae33cf5c2e944e584cd3d3c6ff76d93619adf7dc +2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 04f11d0a2b33d1a2ddd9c782489622a4f9e76d13 +2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 981ed87864cc82821a411a3a0ac1f511e3ac514b diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md index 51d488db28..04f11d0a2b 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md +++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md @@ -22,7 +22,7 @@ The loop fires awaited serial `agent/post-step(agent, turn, step, signal)` after ### Request recovery is limited to the final model boundary -`RequestError` and the `agent/request-error` waterfall represent failures after the final adapter has been selected. Each returned stream handle owns a private failure set that preserves the original thrown error identity across dispatch, iterator construction, and iteration without leaking nested-call provenance into an outer call. Terminal in-band `error` or `aborted` finishes enter the same path. Prompt assembly, request middleware, request logging, result processing, tools, step listeners, and cleanup remain ordinary failures. +`agent/request-error` represents terminal failures from the final adapter boundary. Adapter selection, dispatch, iterator construction, and iteration throws become terminal `error` or `aborted` finishes before the agent loop consumes them; adapter-emitted terminal finishes enter the same path. Prompt assembly, request middleware, request logging, result processing, tools, step listeners, and cleanup remain ordinary failures. [Terminal LLM stream failures](2026-07-29-terminal-llm-stream-failures.md) owns this normalization boundary. The failed step closes before recovery runs. A handling listener repairs durable state, returns `{ kind: 'retry' }`, and stops waterfall delegation. The loop then closes the failed turn and opens one retry turn from the durable log without an intervening idle notification. Retry policy and attempt counts remain plugin-owned; compact-basic clears its per-agent overflow count when the chain reaches terminal `agent/settled`. Both DeepSeek adapters normalize recognized provider context-limit failures to `CONTEXT_WINDOW_EXCEEDED`. The [retry-action decision](../simplification/2026-07-27-request-error-retry-action.md) owns the return boundary. @@ -42,7 +42,7 @@ The default summarizer resolves explicit configuration, then the latest logged r ## Testing -Unit tests cover final-adapter failure provenance and identity, closed-turn retry numbering and reset, cancellation and disposal, step-boundary ordering, routed-envelope pressure, pressure-gated pruning, pruning-only relief, pruned-input summarization, balanced overflow reduction, durable prune progress before later failure, generation proof, caps, delegation, and auxiliary-call routing. Real-loop tests cover thrown and in-band overflow through pruning or summary compaction to a reconstructed retry request. +Unit tests cover the final-adapter normalization boundary, closed-turn retry numbering and reset, cancellation and disposal, step-boundary ordering, routed-envelope pressure, pressure-gated pruning, pruning-only relief, pruned-input summarization, balanced overflow reduction, durable prune progress before later failure, generation proof, caps, delegation, and auxiliary-call routing. Real-loop tests cover thrown and in-band overflow through pruning or summary compaction to a reconstructed retry request. ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md index ae33cf5c2e..981ed87864 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md @@ -22,7 +22,7 @@ Status: implemented ### 请求恢复只覆盖最终模型边界 -`RequestError` 与 `agent/request-error` waterfall 表示最终适配器已经选定之后的失败。每个返回的流句柄都绑定一个私有失败集合；该集合在分发、异步迭代器构造与迭代过程中保留原始抛出错误的身份，同时防止把嵌套调用的错误来源误归到外层调用。终止性的带内 `error` 或 `aborted` finish 进入同一路径。提示词装配、请求中间件、请求日志、结果处理、工具、step 监听器与清理仍属于普通失败。 +`agent/request-error` 表示来自最终适配器边界的终止失败。适配器选择、分发、iterator 构造与迭代抛出会在 agent loop 消费前成为终止 `error` 或 `aborted` finish；适配器直接发出的终止 finish 进入同一路径。提示词装配、请求 middleware、请求日志、结果处理、工具、step 监听器与清理仍属于普通失败。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)规定这一规范化边界。 恢复运行前，失败 step 已经关闭。负责处理的监听器修复持久状态、返回 `{ kind: 'retry' }`，并停止 waterfall 委托。循环随后关闭失败 turn，并从持久日志开启一个重试 turn，中间不发布空闲通知。重试策略与尝试计数由插件自己拥有；compact-basic 在链路到达终态 `agent/settled` 时清除对应 agent 的溢出计数。两个 DeepSeek 适配器都把识别出的提供方上下文限制错误规范化为 `CONTEXT_WINDOW_EXCEEDED`。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回边界。 @@ -42,7 +42,7 @@ Status: implemented ## 测试 -单元测试覆盖最终适配器失败的来源与身份、已关闭 turn 的重试编号与重置、取消与销毁、step 边界顺序、已路由信封压力、压力门控剪枝、剪枝独立解除压力、从已剪枝输入生成摘要、平衡溢出缩减、后续失败前已落盘的剪枝进展、generation 证明、上限、委托与辅助调用路由。真实循环测试覆盖抛出式和带内溢出，并验证剪枝或摘要压缩后的重试请求从替换表层重建。 +单元测试覆盖最终适配器规范化边界、已关闭 turn 的重试编号与重置、取消与销毁、step 边界顺序、已路由信封压力、压力门控剪枝、剪枝独立解除压力、从已剪枝输入生成摘要、平衡溢出缩减、后续失败前已落盘的剪枝进展、generation 证明、上限、委托与辅助调用路由。真实循环测试覆盖抛出式和带内溢出，并验证剪枝或摘要压缩后的重试请求从替换表层重建。 ## 考虑过的替代方案 diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml index 46b84213b9..75cdc976cb 100644 --- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.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/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md -2026-07-22-unified-send-and-coalesced-user-messages.md: ed171735cf483938c70291963a6e68dc02d7bde2 -2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 8b2a3ebabb493954e653255e876255b9c0810c19 +2026-07-22-unified-send-and-coalesced-user-messages.md: d4e5b4ba3de023ca08496073c81731c2c2456036 +2026-07-22-unified-send-and-coalesced-user-messages.zh.md: c5da61184b4b4c39924a4795aa86fd9b3848c3b8 diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md index ed171735cf..d4e5b4ba3d 100644 --- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md +++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md @@ -1,4 +1,4 @@ -# Agent Note: Unify agent delivery on send(target × wakeup) and coalesce injected context into user/message +# Agent Note: Unify agent delivery routing and coalesce injected context into user/message Status: implemented @@ -12,7 +12,7 @@ Separately, `context/message` and `user/message` had converged: the surface proj ## Decision -**One primitive, three preset aliases.** The `Agent` interface's `send(message, { target, wakeup })` covers the (`target` × `wakeup`) matrix. Its complete `UserMessage` owns identity, role, model-facing `content`, and producer `source`; the complete `SendOptions` owns only routing policy. `followup` (`next-turn`/wakeup), `steer` (`next-step`/wakeup), and `inject` (`next-step`/no-wakeup) each accept that one message and fix the policy. `wakeup` means "make the model run": wake a parked driver for a `next-turn` item, or force a continuation for a running `next-step` item. `next-turn`/no-wakeup (queue without waking) is representable with no alias and no current caller. +**One private primitive, three public operations.** `ReactLoopAgent` routes `followup` (queued turn), `steer` (nearest step), and `inject` (context without execution) through one private `send` helper. Each public method accepts a complete `UserMessage` that owns identity, role, model-facing `content`, and producer `source`. The plugin-facing `Agent` interface exposes semantic intent rather than the underlying (`target` × `wakeup`) matrix; the [private-routing decision](../simplification/2026-07-30-private-agent-send.md) owns that public-surface boundary. **inject keeps its mechanism.** The `next-step`/no-wakeup path is exactly the old `inject`: durable model-facing context appended at the current log position, deferred while prompt admission or a turn owns the next safe boundary, and appended directly outside that window. It bypasses the FIFOs entirely, while its required `UserMessage.source` preserves the caller's explicit provenance. @@ -20,7 +20,7 @@ Separately, `context/message` and `user/message` had converged: the surface proj **Goal replay disambiguates by round, not type.** A goal state change is a round-zero goal-sourced `user/message` whose source carries the complete change; a positive round is an admitted continuation prompt. `decodeGoalEvent` takes a `user/message` and fails loud when goal-state content and its typed source disagree. -**`send` does not return identity.** Callers already own the complete message and its opaque `MessageId`; creation and freezing are owned by the [identified immutable message decision](2026-07-28-identified-immutable-message-values.md), not by routing. +**Delivery does not return identity.** Callers already own the complete message and its opaque `MessageId`; creation and freezing are owned by the [identified immutable message decision](2026-07-28-identified-immutable-message-values.md), not by routing. **Three inbox events replace agent/queued.** `agent/inbox/enqueue` (an item entered a FIFO), `agent/inbox/dequeue` (the driver claimed one), and `agent/inbox/discard` (`cancel()` dropped pending items) carry the accepted `UserMessage`. Enqueue and dequeue also carry the resolved `queued | steering` placement captured at acceptance, so observers and reconnect mirrors retire repeated message identities from the correct FIFO without reconstructing routing from later status or session history. Injection never touches a FIFO and emits none of these. Every FIFO entry publishes an enqueue, including steering submitted by an `agent/turn-stopping` listener, so the ledger stays balanced with its later dequeue or discard. The `dsh-agent` invariant companion asserts FIFO conservation: a per-agent outstanding count that dequeue and discard can never drive negative. @@ -41,9 +41,9 @@ Separately, `context/message` and `user/message` had converged: the surface proj ## Consequences -The delivery surface is now one primitive plus three self-documenting presets, and the (`target` × `wakeup`) matrix makes previously-unreachable combinations explicit. One durable message type serves prompts, injected context, and goal rounds, so the surface projection and every "human prompt?" check simplify to a `source` test. The `Agent` contract remains an interface, so alternate implementations and object-literal test fakes implement the same minimal structural surface. The goal fold's channel split moved from event type to `source.round`, and every consumer that filtered `context/message` now filters `user/message` by source. An idle injection appends `user/message` between turns without opening a turn or running the model. +The concrete driver keeps one routing primitive while the public interface exposes three self-documenting operations. One durable message type serves prompts, injected context, and goal rounds, so the surface projection and every "human prompt?" check simplify to a `source` test. The `Agent` contract remains an interface, so alternate implementations and object-literal test fakes implement the same minimal structural surface. The goal fold's channel split moved from event type to `source.round`, and every consumer that filtered `context/message` now filters `user/message` by source. An idle injection appends `user/message` between turns without opening a turn or running the model. -`wakeup` is the "should the model run" signal, so the inbox distinguishes waking queued work from anything available to dequeue: a lone `next-turn`/no-wakeup item stays parked at idle and rides along the next waking send, and `whenIdle`/`cancel` settle quiescence off the waking signal. Every FIFO exit publishes exactly one lifecycle event, while domain-specific durable facts travel in typed message sources rather than a parallel metadata channel. The direct pending-item representation keeps public lifecycle events correlated without maintaining a second steering wrapper or allowing its durable data to diverge. +The private `wakeup` flag records whether delivery requests model execution; public follow-ups and steering wake the driver, while injection does not. Every FIFO exit publishes exactly one lifecycle event, while domain-specific durable facts travel in typed message sources rather than a parallel metadata channel. The direct pending-item representation keeps public lifecycle events correlated without maintaining a second steering wrapper or allowing its durable data to diverge. ## Related @@ -51,3 +51,4 @@ The delivery surface is now one primitive plus three self-documenting presets, a - [remove-agent-steering-mirror](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md) — the precedent for collapsing a mirrored live event. - [explicit-turn-cancellation](2026-07-16-explicit-turn-cancellation.md) — the cancel-cause signal `keepInbox` extends. - [identified immutable message values](2026-07-28-identified-immutable-message-values.md) — the message identity and representation contract that now underlies this routing decision. +- [private agent routing](../simplification/2026-07-30-private-agent-send.md) — the public-surface simplification that keeps the routing matrix inside the concrete driver. diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md index 8b2a3ebabb..c5da61184b 100644 --- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md @@ -1,4 +1,4 @@ -# Agent Note: 将 agent 投递统一到 send(target × wakeup) 并把注入的上下文合并进 user/message +# Agent Note: 统一 agent 投递路由并把注入的上下文合并进 user/message Status: implemented @@ -12,7 +12,7 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send` ## 决策 -**一个原语，三个预设别名。** `Agent` 接口的 `send(message, { target, wakeup })` 覆盖 (`target` × `wakeup`) 矩阵。完整的 `UserMessage` 持有标识、角色、模型可见 `content` 与生产方 `source`；完整的 `SendOptions` 只持有路由策略。`followup`（`next-turn`/wakeup）、`steer`（`next-step`/wakeup）和 `inject`（`next-step`/no-wakeup）都接收这一条消息并固定策略。`wakeup` 意为“让模型运行”：为一个 `next-turn` 队列项唤醒处于停泊状态的驱动器，或为一个运行中的 `next-step` 队列项强制继续执行。`next-turn`/no-wakeup（入队但不唤醒）可以表达，只是没有别名，也没有当前调用方。 +**一个私有原语，三个公开操作。** `ReactLoopAgent` 通过一个私有 `send` 辅助方法路由 `followup`（排队轮次）、`steer`（最近的步骤）和 `inject`（不执行模型的上下文）。每个公开方法都接收一条完整的 `UserMessage`，由它持有标识、角色、模型可见 `content` 与生产方 `source`。面向插件的 `Agent` 接口公开语义意图，而不是底层的（`target` × `wakeup`）矩阵；该公开接口边界由[私有路由决策](../simplification/2026-07-30-private-agent-send.md)规定。 **inject 保留其机制。** `next-step`/no-wakeup 路径正是旧的 `inject`：持久的面向模型上下文会追加到当前日志位置；提示词准入或一个轮次占有下一个安全边界时，它会延迟处理，而在该窗口之外则直接追加。它完全绕过 FIFO 队列，而必填的 `UserMessage.source` 会保留调用方显式提供的来源信息。 @@ -20,7 +20,7 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send` **goal 回放靠轮次而非类型来区分。** 一次 goal 状态变更是一条第 0 轮、来源为 goal 的 `user/message`，其 source 携带完整变更；正数轮次则是一条已准入的继续执行提示词。`decodeGoalEvent` 接收一条 `user/message`，并在 goal 状态内容与其类型化 source 不一致时立即报错。 -**`send` 不返回标识。** 调用方已经持有完整消息及其不透明的 `MessageId`；消息的创建与冻结由[带标识的不可变消息值决策](2026-07-28-identified-immutable-message-values.md)负责，而不是由路由负责。 +**投递不返回标识。** 调用方已经持有完整消息及其不透明的 `MessageId`；消息的创建与冻结由[带标识的不可变消息值决策](2026-07-28-identified-immutable-message-values.md)负责，而不是由路由负责。 **三个 inbox 事件取代 agent/queued。** `agent/inbox/enqueue`（一个队列项进入某个 FIFO）、`agent/inbox/dequeue`（驱动器认领了一个）和 `agent/inbox/discard`（`cancel()` 丢弃了待处理项）都会携带已接受的 `UserMessage`。enqueue 和 dequeue 还会携带生产方在接受消息时捕获的已解析 `queued | steering` 放置方式，因此观察方和重连镜像可以从正确的 FIFO 中结算重复出现的消息标识，无需根据后续状态或会话历史重建路由。注入从不触及 FIFO，也不发出这些事件中的任何一个。每一次 FIFO 入队都会发布一个 enqueue 事件，包括 `agent/turn-stopping` 监听器提交的 steering，因此账目会与其后的 dequeue 或 discard 保持平衡。`dsh-agent` 的不变量配套断言 FIFO 守恒：一个按 agent 计的未结算计数，dequeue 和 discard 永远无法把它压到负数。 @@ -41,9 +41,9 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send` ## 后果 -投递接口现在是一个原语加三个自解释的预设，(`target` × `wakeup`) 矩阵把此前无法表达的组合显式化。一种持久消息类型同时服务提示词、注入的上下文和 goal 轮次，因此对外接口的投影和每一处“是否人类提示词？”检查都简化为一次 `source` 判断。`Agent` 契约仍是接口，因此其他实现和对象字面量形式的测试替身只需实现同一个最小结构接口。goal 折叠的通道区分从事件类型改到了 `source.round`；此前过滤 `context/message` 的每个消费方现在改为按来源过滤 `user/message`。空闲状态下的注入会在两个轮次之间追加 `user/message`，既不打开轮次，也不运行模型。 +具体驱动器保留一个路由原语，公开接口则提供三个自解释的操作。一种持久消息类型同时服务提示词、注入的上下文和 goal 轮次，因此对外接口的投影和每一处“是否人类提示词？”检查都简化为一次 `source` 判断。`Agent` 契约仍是接口，因此其他实现和对象字面量形式的测试替身只需实现同一个最小结构接口。goal 折叠的通道区分从事件类型改到了 `source.round`；此前过滤 `context/message` 的每个消费方现在改为按来源过滤 `user/message`。空闲状态下的注入会在两个轮次之间追加 `user/message`，既不打开轮次，也不运行模型。 -`wakeup` 是“模型是否应当运行”的信号，因此 inbox 会区分能唤醒的排队工作与任何可 dequeue 的项：一个孤立的 `next-turn`/no-wakeup 队列项会停泊在空闲状态，并随下一次唤醒 send 一同带出，而 `whenIdle`/`cancel` 依据唤醒信号来结算静默。每一次 FIFO 退出都恰好发布一个生命周期事件，特定于领域的持久事实则通过类型化消息 source 传递，而非通过平行的元数据通道。直接使用待处理项的表示方式，使公开生命周期事件保持可关联，既无需维护第二个 steering 包装层，也避免其持久数据发生分歧。 +私有 `wakeup` 标志记录投递是否要求执行模型；公开的后续消息与 steering 会唤醒驱动器，注入则不会。每一次 FIFO 退出都恰好发布一个生命周期事件，特定于领域的持久事实则通过类型化消息 source 传递，而非通过平行的元数据通道。直接使用待处理项的表示方式，使公开生命周期事件保持可关联，既无需维护第二个 steering 包装层，也避免其持久数据发生分歧。 ## 相关 @@ -51,3 +51,4 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send` - [remove-agent-steering-mirror](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)——折叠镜像实时事件的先例。 - [explicit-turn-cancellation](2026-07-16-explicit-turn-cancellation.md)——`keepInbox` 所扩展的取消原因信号。 - [带标识的不可变消息值](2026-07-28-identified-immutable-message-values.md)——本路由决策现在所依托的消息标识与表示契约。 +- [private agent routing](../simplification/2026-07-30-private-agent-send.md)——把路由矩阵保留在具体驱动器内的公开接口简化决策。 diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml index 397258fe18..f654a8d4e1 100644 --- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.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/architecture/2026-07-24-separate-context-injection-from-turn-execution.md -2026-07-24-separate-context-injection-from-turn-execution.md: bf3ae2ecbd2205a4c49e8004ffc694f89a2460a3 -2026-07-24-separate-context-injection-from-turn-execution.zh.md: a805eb651c5c77f3d37c92dacd116bb41f154ed7 +2026-07-24-separate-context-injection-from-turn-execution.md: 83eb542cb78bf38042d79015153f55622fe46d43 +2026-07-24-separate-context-injection-from-turn-execution.zh.md: cd748e5cf9a9019427f862b3127d36256fc4e4f4 diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md index bf3ae2ecbd..83eb542cb7 100644 --- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md +++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md @@ -18,7 +18,7 @@ Idle `inject()` exposed a second mismatch. Injection did not request model execu `inject()` is the only caller-facing operation for supplementary model-facing input, and a turn means one execution of the model loop. -`SendOptions` contains only `target` and `wakeup`. A caller that owns context delivers an identified, frozen `UserMessage` through `inject()` and submits the direct message independently with `send()` or `steer()`. +A caller that owns context delivers an identified, frozen `UserMessage` through `inject()` and submits the direct message independently with `followup()` or `steer()`. Prompt and tool extension points still return `additionalContexts`. These values are outputs of the extension point, not attachments captured from a caller's inbox item. Prompt admission runs before `run()` opens a turn. An allowed prompt and its returned additional contexts enter the new turn as separate messages; a blocked prompt writes neither and opens no turn. Tool-produced additional contexts enter the outbox after the corresponding tool results. @@ -38,7 +38,7 @@ The session invariant permits `user/message` between turns while continuing to r `PromptDecision.content` continues to replace only the direct prompt. `PromptDecision.additionalContexts` and tool-result `additionalContexts` retain FIFO order and individual provenance, but no longer select placement. A waterfall listener that delegates with `next()` must preserve downstream prompt content and additional contexts unless it intentionally returns replacements. -Caller-driven injection and hook-produced additional context deliberately have different admission ownership. A hook's additional contexts materialize only after that hook allows the prompt or tool result. Outside a next-step acceptance window, a caller that invokes `inject(context)` and then `send(prompt)` commits context independently; callers requiring all-or-nothing behavior use a domain-specific admission wrapper. +Caller-driven injection and hook-produced additional context deliberately have different admission ownership. A hook's additional contexts materialize only after that hook allows the prompt or tool result. Outside a next-step acceptance window, a caller that invokes `inject(context)` and then `followup(prompt)` commits context independently; callers requiring all-or-nothing behavior use a domain-specific admission wrapper. Cross-session references use that domain composition: TUI prepares the snapshot, then either adds it to the prompt's admission decision outside an acceptance window or injects it beside steering during one. The target log contains two simple messages, so later source mutation cannot change replay and transcript consumers do not need a prompt envelope. This supersedes the attachment mechanism in the [cross-session reference decision](../feature/2026-07-21-cross-session-references.md) while retaining its snapshot and trust-boundary rules. @@ -58,7 +58,7 @@ This decision preserves the caller-owned framing decision from [unwrapped inject ## Verification -- `SendOptions` and steering inbox records contain no attached contexts; `agent/inbox/enqueue` reports only the message plus its resolved queued-or-steering placement. +- Delivery inputs and steering inbox records contain no attached contexts; `agent/inbox/enqueue` reports only the message plus its resolved queued-or-steering placement. - `UserMessage` is the shared identified, frozen shape across prompt interception, tool execution, hook bridges, guards, and context producers. - Prompt-prefix placement, prompt envelopes, and `context/message` are absent from public types, durable events, projection, and UI replay. - Idle `inject()` appends one sourced `user/message` without a turn or model call. @@ -70,5 +70,5 @@ This decision preserves the caller-owned framing decision from [unwrapped inject - One surface event is valid outside turns, so persistence scanning, crash repair, forking, compaction, and session queries distinguish execution enclosure from session history. - Consecutive user-role messages replace one baked prompt message; provider adapters preserve that ordering. -- Outside an acceptance window, `inject()` followed by a blocked `send()` leaves context without its intended direct prompt unless the caller supplies domain-specific admission ownership. +- Outside an acceptance window, `inject()` followed by a blocked `followup()` leaves context without its intended direct prompt unless the caller supplies domain-specific admission ownership. - The public delivery contract and inbox records remain small: no context attachment, context-placement metadata, prompt envelope, or duplicate durable event type. diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md index a805eb651c..cd748e5cf9 100644 --- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md @@ -18,7 +18,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入： `inject()` 是调用方交付补充模型输入的唯一操作，而轮次表示一次模型循环执行。 -`SendOptions` 只包含 `target` 和 `wakeup`。拥有上下文的调用方通过 `inject()` 交付带标识且冻结的 `UserMessage`，再独立使用 `send()` 或 `steer()` 提交直接消息。 +拥有上下文的调用方通过 `inject()` 交付带标识且冻结的 `UserMessage`，再独立使用 `followup()` 或 `steer()` 提交直接消息。 提示词和工具扩展点仍可返回 `additionalContexts`。这些值是扩展点的输出，而不是从调用方收件箱条目捕获的附件。提示词准入在 `run()` 打开轮次之前执行。获准的提示词及其返回的额外上下文会作为独立消息进入新轮次；提示词被阻止时，两者都不写入，也不打开轮次。工具产生的额外上下文则在对应工具结果之后进入 outbox。 @@ -38,7 +38,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入： `PromptDecision.content` 仍只替换直接提示词。`PromptDecision.additionalContexts` 和工具结果的 `additionalContexts` 保留 FIFO 顺序及各自来源，但不再选择放置方式。waterfall（瀑布式事件）监听器调用 `next()` 委托时，必须保留下游返回的提示词内容和额外上下文，除非它有意返回替代值。 -调用方主动注入与钩子产生的额外上下文具有不同的准入归属。钩子的额外上下文只会在该钩子允许提示词或工具结果后落入日志。在 next-step 接受窗口之外，调用方执行 `inject(context)` 后再执行 `send(prompt)` 时，会独立提交上下文；需要全有或全无语义的调用方应使用领域专用的准入包装层。 +调用方主动注入与钩子产生的额外上下文具有不同的准入归属。钩子的额外上下文只会在该钩子允许提示词或工具结果后落入日志。在 next-step 接受窗口之外，调用方执行 `inject(context)` 后再执行 `followup(prompt)` 时，会独立提交上下文；需要全有或全无语义的调用方应使用领域专用的准入包装层。 跨会话引用采用这种领域组合方式：TUI 先准备快照，然后在接受窗口之外将其加入提示词准入决策，或在窗口期间将其注入到 steering 旁。目标日志包含两条简单消息，因此来源会话后续变化不会改变回放，transcript 消费方也不需要提示词封套。本决策取代[跨会话引用决策](../feature/2026-07-21-cross-session-references.md)中的附件机制，但保留其快照与信任边界规则。 @@ -58,7 +58,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入： ## 验证 -- `SendOptions` 与 steering 收件箱记录不包含附加上下文；`agent/inbox/enqueue` 只报告消息及其已解析的 queued 或 steering 放置方式。 +- 投递输入与 steering 收件箱记录不包含附加上下文；`agent/inbox/enqueue` 只报告消息及其已解析的 queued 或 steering 放置方式。 - `UserMessage` 是提示词拦截、工具执行、hook bridge、guard 和上下文生产方共享的带标识且冻结的形状。 - 公共类型、持久事件、投影和 UI 回放中均不存在 prompt-prefix 放置方式、提示词封套与 `context/message`。 - 空闲 `inject()` 在不产生轮次或模型调用的情况下，追加一条带来源的 `user/message`。 @@ -70,5 +70,5 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入： - 一个表层事件可以合法位于轮次之外，因此持久化扫描、崩溃恢复、fork、压缩和会话查询需要区分执行封闭与会话历史。 - 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器会保留这一顺序。 -- 在接受窗口之外，`inject()` 后跟一个被阻止的 `send()` 会留下缺少预期直接提示词的上下文，除非调用方提供领域专用的准入归属。 +- 在接受窗口之外，`inject()` 后跟一个被阻止的 `followup()` 会留下缺少预期直接提示词的上下文，除非调用方提供领域专用的准入归属。 - 公共投递契约和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。 diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml index 4c701a99f3..85ccc38306 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.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/architecture/2026-07-28-identified-immutable-message-values.md -2026-07-28-identified-immutable-message-values.md: cdb0f1aadc4796b5aa0642a3994d3e3e4ab67bd9 -2026-07-28-identified-immutable-message-values.zh.md: 3e1732cb5b7f49fb9349b2e1790cf5b3ec1474be +2026-07-28-identified-immutable-message-values.md: 66c11cfddae2ce122e248032af6b0349dde8995e +2026-07-28-identified-immutable-message-values.zh.md: c0ed3bd87b1dfc411896868a2e0f8014a6af0a22 diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md index cdb0f1aadc..66c11cfdda 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md +++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md @@ -18,7 +18,7 @@ This made identity a routing side effect rather than a message invariant. Produc The helpers live in `dsh-llm` beside the base message vocabulary because their complete contracts depend only on that vocabulary. `createToolResultMessage()` belongs with the other creation helpers: it couples a tool call id to the exact user-role tool-result block and source without depending on session state or events. `dsh-session` consumes complete messages rather than owning their construction. -The `Agent` interface accepts a complete `UserMessage`. `send`, `followup`, `steer`, and `inject` never allocate or return identity; they freeze an imported value whose id the caller already holds. Prompt admission receives that message directly. A content rewrite creates a frozen replacement with the same id, while an additional context is a separately created `UserMessage` with its own id. +The `Agent` interface accepts a complete `UserMessage` through `followup`, `steer`, and `inject`. These operations never allocate or return identity; they freeze an imported value whose id the caller already holds. Prompt admission receives that message directly. A content rewrite creates a frozen replacement with the same id, while an additional context is a separately created `UserMessage` with its own id. Durable message-producing events store complete messages. `user/message` stores its `UserMessage` directly; `assistant/message`, `tool/result`, and `steering/message` wrap their role-specialized message beside event-local position, usage, failure, or presentation facts. Session derivation returns those frozen values instead of reconstructing anonymous messages. Assistant assembly creates a model-sourced message when a response completes, and tool execution creates a tool-sourced message when a result is committed. @@ -28,7 +28,7 @@ Any operation that changes only the representation of an existing semantic messa **Keep ids optional on the base message.** This would minimize fixture migration and allow provider or persistence shapes to remain anonymous. It would also preserve the original ambiguity: every consumer would need to branch on whether identity exists, and no type would prove that admission, logging, or projection retained it. -**Let `Agent.send()` allocate the id.** This keeps identity scoped to inbox correlation but makes the agent call the earliest point at which a producer can name its own message. Prompt construction, UI attachments, and synchronous enqueue/discard coordination then need content matching or an out-of-band token before `send()` returns. +**Let agent delivery allocate the id.** This keeps identity scoped to inbox correlation but makes the agent call the earliest point at which a producer can name its own message. Prompt construction, UI attachments, and synchronous enqueue/discard coordination then need content matching or an out-of-band token before delivery returns. **Let each durable event allocate a new id.** This gives persisted messages identities but deliberately breaks correlation with the live input and makes replayed requests appear to contain different messages. Identity belongs to the semantic value, not to each envelope that carries it. @@ -46,5 +46,5 @@ The message and helper unit tests pin immediate identity, detachment, deep immut ## Related -- [Unify agent delivery on send(target × wakeup) and coalesce injected context into user/message](2026-07-22-unified-send-and-coalesced-user-messages.md) — this note supersedes its input-representation and agent-assigned-id details while retaining its routing decision. +- [Unified agent delivery routing and coalesced injected context](2026-07-22-unified-send-and-coalesced-user-messages.md) — this note supersedes its input-representation and agent-assigned-id details while retaining its routing decision. - [Reconstructable requests](2026-07-05-reconstructable-requests.md) — the session log remains the authority for every model-visible input. diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md index 3e1732cb5b..c0ed3bd87b 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md @@ -18,7 +18,7 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则 这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整契约只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。 -`Agent` 接口接收完整的 `UserMessage`。`send`、`followup`、`steer` 和 `inject` 绝不会分配或返回标识；它们会冻结导入的值，而调用方已经持有该值的 id。提示词准入会直接接收该消息。改写内容时会创建具有相同 id 的冻结替代值，而每个附加上下文都是单独创建的 `UserMessage`，拥有自己的 id。 +`Agent` 接口通过 `followup`、`steer` 和 `inject` 接收完整的 `UserMessage`。这些操作绝不会分配或返回标识；它们会冻结导入的值，而调用方已经持有该值的 id。提示词准入会直接接收该消息。改写内容时会创建具有相同 id 的冻结替代值，而每个附加上下文都是单独创建的 `UserMessage`，拥有自己的 id。 产生持久消息的事件会存储完整消息。`user/message` 直接存储其 `UserMessage`；`assistant/message`、`tool/result` 和 `steering/message` 则将各自角色专用的消息与事件本地的位置、用量、失败或呈现事实包装在一起。会话派生会返回这些冻结值，而不是重建匿名消息。assistant 组装会在响应完成时创建模型来源的消息，工具执行会在提交结果时创建工具来源的消息。 @@ -28,7 +28,7 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则 **让基础消息的 id 保持可选。** 这能减少 fixture（测试前置数据）迁移，并允许提供方或持久化形状继续保持匿名，但也会保留原有歧义：每个消费方都必须根据标识是否存在执行分支，且没有任何类型能证明准入、记录或投影保留了标识。 -**让 `Agent.send()` 分配 id。** 这会将标识限定在 inbox 关联范围内，却也会让 agent 调用成为生产方可以标识自身消息的最早时机。这样一来，在 `send()` 返回前，提示词构造、UI 附件和同步入队／丢弃协调都需要进行内容匹配，或使用带外 token。 +**让 agent 交付分配 id。** 这会将标识限定在 inbox 关联范围内，却也会让 agent 调用成为生产方可以标识自身消息的最早时机。这样一来，在交付返回前，提示词构造、UI 附件和同步入队／丢弃协调都需要进行内容匹配，或使用带外 token。 **让每个持久事件分配新 id。** 这能为持久消息提供标识，却会有意切断它与实时输入的关联，并让回放请求表现得像包含了不同消息。标识属于语义值，而不是承载它的每个封装。 @@ -46,5 +46,5 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则 ## 相关 -- [统一通过 send(target × wakeup) 交付 agent 消息，并将注入上下文合并到 user/message](2026-07-22-unified-send-and-coalesced-user-messages.md)——本记录取代其中的输入表示和由 agent 分配 id 的细节，同时保留其路由决策。 +- [统一 agent 交付路由，并合并注入上下文](2026-07-22-unified-send-and-coalesced-user-messages.md)——本记录取代其中的输入表示和由 agent 分配 id 的细节，同时保留其路由决策。 - [可重建的请求](2026-07-05-reconstructable-requests.md)——会话日志仍是每项模型可见输入的权威来源。 diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml new file mode 100644 index 0000000000..2bef24442d --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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/architecture/2026-07-29-terminal-llm-stream-failures.md +2026-07-29-terminal-llm-stream-failures.md: 1e26973360f07c212016c6a44103448a3510a75b +2026-07-29-terminal-llm-stream-failures.zh.md: d3eeb0534f6cb8d4d1ad167cca089314eb02b513 diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md new file mode 100644 index 0000000000..1e26973360 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md @@ -0,0 +1,37 @@ +# Agent Note: Terminal LLM stream failures + +Status: implemented + +English | [中文](2026-07-29-terminal-llm-stream-failures.zh.md) + +This note supersedes only the thrown-error identity and call-local sidecar mechanism in [bounded LLM request recovery](2026-06-21-bounded-llm-request-recovery.md) and [after-call context-overflow recovery](2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md). Those notes continue to own structured failure facts, retry policy, durable attempts, and compaction recovery. + +## Problem + +An adapter failure had two public representations: an exception from selection, dispatch, iterator construction, or iteration, and an in-band `finish { kind: 'error' | 'aborted' }`. `LlmService` tagged thrown objects in a stream-keyed sidecar so the agent loop could distinguish them from middleware and consumer failures. The consumer still needed a catch around iteration, signal checks, chunk logging, and assembly; correctness therefore depended on proving which statement threw and consulting metadata attached to the exact returned iterable. + +Retry policy had the same indirect ownership. It was discovered through the stream sidecar after dispatch even though `prepareCall()` had already captured the serving registration. A wrapper-owned route and an adapter-owned route consequently shared one opaque lookup API despite having different authority. + +## Decision + +`LlmService` is the normalization boundary for one adapter attempt. It catches only final-adapter selection, synchronous dispatch, iterator construction, and `next()` failures, converts the thrown value to immutable `LlmFailure`, and emits one terminal `finish`. Caller cancellation or an `ABORTED` failure selects the aborted reason; every other adapter failure selects error. An adapter may also emit either terminal reason directly. + +The adapter-owned catch ends before each yielded chunk. Errors from `llm/stream` middleware, nested calls, adapter cleanup, chunk consumers, logging, signal checks, and assembly remain thrown as defects or lifecycle failures; they never enter model-request recovery. A transport failure after partial deltas may leave blocks open, so the stream invariant permits open blocks only for terminal error or aborted finishes. No assistant message or tool call is assembled from that incomplete output. + +`PreparedLlmCall` exposes the immutable retry policy captured with its config and registration. One-shot reuse and config mismatch remain synchronous `INVALID_PREPARED_CALL` misuse errors. A route served entirely by `llm/stream` middleware has no prepared registration and therefore no serving policy. + +The agent loop consumes one failure representation. It iterates and logs chunks without a classification catch, inspects the terminal finish, and passes its failure facts plus the prepared policy to `agent/request-error`. The public `isLlmAdapterFailure`, `llmFailureOf`, and `llmRetryPolicyOf` sidecar APIs are absent. + +## Alternatives considered + +**Keep call-local error tagging.** This preserves thrown object identity, but makes every consumer catch a region containing its own fallible work and couples classification to the identity of an iterable wrapper. The original error object has no durable role in recovery; normalized facts are the useful boundary value. + +**Require every adapter to emit failure chunks and forbid throws.** Library iterators, transports, and JavaScript dispatch can still throw. Requiring every adapter to reproduce the same catch boundary duplicates ownership and does not protect a direct `LlmService` consumer from an incomplete implementation. + +**Catch every iteration error in the agent loop.** The loop cannot reliably distinguish provider failure from middleware, session append, cancellation, or assembly failure without restoring the same sidecar provenance mechanism. Classification belongs where the adapter call is made. + +**Return a `Result` before streaming.** A pre-stream result cannot represent a transport failure after partial output without adding a second response lifecycle. The existing terminal chunk already represents both early and late attempt outcomes. + +## Consequences + +All `LlmService.stream()` consumers receive adapter operational failures through one typed terminal protocol, while programming and lifecycle failures retain ordinary exception semantics. Recovery gives up exact thrown-object identity and exposes only detached provider-neutral facts. The stream service owns slightly more adapter plumbing, but consumers delete provenance catches and stream-keyed metadata. Prepared calls carry their policy explicitly, and middleware-only routing remains visibly policy-free. diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md new file mode 100644 index 0000000000..d3eeb0534f --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md @@ -0,0 +1,37 @@ +# Agent Note: LLM 流的终止失败 + +Status: implemented + +[English](2026-07-29-terminal-llm-stream-failures.md) | 中文 + +本说明仅取代[有界 LLM 请求恢复](2026-06-21-bounded-llm-request-recovery.md)与[调用后上下文溢出恢复](2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)中关于抛出错误身份和调用局部 sidecar 的机制。上述说明继续规定结构化失败事实、重试策略、持久尝试与压缩恢复。 + +## Problem + +适配器失败曾有两种公共表示：选择、分发、iterator 构造或迭代抛出的异常，以及带内的 `finish { kind: 'error' | 'aborted' }`。`LlmService` 会在以 stream 为 key 的 sidecar 中标记抛出对象，使 agent loop 能将其与 middleware 和消费方失败区分开。消费方仍需用 catch 包围迭代、signal 检查、chunk 日志记录和组装；正确性因此取决于证明是哪条语句抛错，并查询附着于精确返回 iterable 的元数据。 + +重试策略也采用同样的间接归属。尽管 `prepareCall()` 已捕获服务注册，策略仍要在分发后通过 stream sidecar 查找。因此，由 wrapper 提供服务的路由与由适配器提供服务的路由共用一个不透明查询 API，尽管两者的权威不同。 + +## Decision + +`LlmService` 是一次适配器尝试的规范化边界。它只捕获最终适配器选择、同步分发、iterator 构造与 `next()` 失败，将抛出值转换为不可变 `LlmFailure`，并发出一个终止 `finish`。调用方取消或 `ABORTED` 失败选择 aborted reason；其他适配器失败选择 error。适配器也可以直接发出这两种终止 reason。 + +适配器所属的 catch 会在每个 chunk 被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、chunk 消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能留下未关闭块，因此流 invariant 只允许终止 error 或 aborted finish 带有未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。 + +`PreparedLlmCall` 公开随其配置和注册捕获的不可变重试策略。一次性句柄复用与配置不匹配仍是同步的 `INVALID_PREPARED_CALL` 误用错误。完全由 `llm/stream` middleware 提供服务的路由没有准备完成的注册，因此也没有服务策略。 + +agent loop 只消费一种失败表示。它不再使用分类 catch，而是直接迭代并记录 chunk、检查终止 finish，再把其中的失败事实与准备完成的策略传给 `agent/request-error`。公共的 `isLlmAdapterFailure`、`llmFailureOf` 和 `llmRetryPolicyOf` sidecar API 不再存在。 + +## Alternatives considered + +**保留调用局部错误标记。** 这会保留抛出对象身份，但要求每个消费方捕获一段包含自身易失败工作的区域，并让分类依赖 iterable wrapper 的身份。原始错误对象在持久恢复中没有作用；规范化事实才是有用的边界值。 + +**要求所有适配器发出失败 chunk，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会重复归属，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。 + +**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。 + +**在流式输出前返回 `Result`。** 流前结果无法表示部分输出之后的传输失败，除非增加第二套响应生命周期。现有终止 chunk 已能表示早期和后期尝试结果。 + +## Consequences + +所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。 diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml index 3df1059e1f..cd70acc0c9 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.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/feature/2026-07-17-dedicated-full-screen-tui-front-door.md -2026-07-17-dedicated-full-screen-tui-front-door.md: a3f3d6b51e85ad20218ce5aebf526bd96946be55 -2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 6a0c2f12815e9418a2b5bcb237d3db3616ccd133 +2026-07-17-dedicated-full-screen-tui-front-door.md: f8fa05383edc3f2abcbf9b5dd8b98e3a15c9a4a3 +2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 12bf3b1633bcb3d958549be3a74bca3c1bdaa816 diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md index a3f3d6b51e..f8fa05383e 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md @@ -22,7 +22,7 @@ The selected front door receives the exact generated or resumed `SessionId` used The TUI rebuilds the transcript from the active `session.surface` and reprojects it whenever an event carries a `surfaceOp`, so resumed and compacted history matches the model-visible conversation. It renders Markdown text and reasoning, including fenced code with hidden Markdown markers, a dim optional language label, and a code-colored body, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. Pending chunks and tool calls update the same components that completed events settle. -Editor input calls `agent.send()` while idle and `agent.steer()` while a turn is running. Cancellation, reasoning visibility, tool-card expansion, redraw, transcript clearing, and exit are terminal-only controls. `/exit` and `/quit` share the same exit path: they cancel an active turn, wait for idle, and then restore and close the terminal. The idle footer derives context occupancy from `tokenMeter` and shows the selected model and explicit reasoning effort; during a run, elapsed activity and the Escape interrupt hint replace that summary. `/status` remains available in either state and appends a detailed terminal-only snapshot: session identity and timestamps, selected model, reasoning effort/default state and reasoning visibility, lifecycle counts folded from the event log, the same deduplicated usage buckets and KV-cache rate as the footer, and context use from `tokenMeter` plus the selected model's advertised capacity. The plugin registers the shared `userInteraction` provider and presents queued questions in a wide bottom-left keyboard panel with batch progress, numbered options, and aligned descriptions; the panel's controls hint lists only actions meaningful for the current option count, omitting navigation when exactly one option is shown; agent behavior and answer logging remain owned by their existing services. +Editor input calls `agent.steer()` so it targets the nearest step whether the agent is idle or running. Cancellation, reasoning visibility, tool-card expansion, redraw, transcript clearing, and exit are terminal-only controls. `/exit` and `/quit` share the same exit path: they cancel an active turn, wait for idle, and then restore and close the terminal. The idle footer derives context occupancy from `tokenMeter` and shows the selected model and explicit reasoning effort; during a run, elapsed activity and the Escape interrupt hint replace that summary. `/status` remains available in either state and appends a detailed terminal-only snapshot: session identity and timestamps, selected model, reasoning effort/default state and reasoning visibility, lifecycle counts folded from the event log, the same deduplicated usage buckets and KV-cache rate as the footer, and context use from `tokenMeter` plus the selected model's advertised capacity. The plugin registers the shared `userInteraction` provider and presents queued questions in a wide bottom-left keyboard panel with batch progress, numbered options, and aligned descriptions; the panel's controls hint lists only actions meaningful for the current option count, omitting navigation when exactly one option is shown; agent behavior and answer logging remain owned by their existing services. The `/model` command presents the advisory `ctx.llm` catalog as a keyboard selector and changes only this TUI session's target; argument forms remain available for direct selection. Each model row owns the adapter-advertised reasoning-effort order and default: Shift+Tab cycles that row's efforts, includes provider-default behavior when the adapter advertises no default, and leaves models without selectable metadata unchanged. Agent-scoped prompt-assembly and request waterfalls snapshot one provider/model/reasoning-effort target per step, so `{{provider}}` / `{{model}}` interpolation and request routing cannot split when a command arrives during assembly. The latest logged request header restores a used target; a selection that never reaches a request remains process-local. diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md index 6a0c2f1281..12bf3b1633 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md @@ -22,7 +22,7 @@ DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README TUI 从活跃的 `session.surface` 重建 transcript（文本记录），并在事件携带 `surfaceOp` 时重新投影，因此恢复或压缩后的历史与模型可见会话保持一致。TUI 渲染 Markdown 文本与推理（其中围栏代码块隐藏 Markdown 标记、保留一个暗色的可选语言标签，并使用代码配色的正文）、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。 -agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调用 `agent.steer()`。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。`/exit` 和 `/quit` 共用同一条退出路径：先取消进行中的轮次，等待 agent 空闲，然后恢复并关闭终端。空闲态页脚根据 `tokenMeter` 得出上下文占用率，并显示所选模型和显式选定的推理强度；agent 运行期间，该摘要会替换为带已用时长的活动指示和 Escape 中断提示。`/status` 在这两种状态下均可用，并会追加一份仅在终端显示的详细快照，其中包括会话标识与时间戳、所选模型、推理强度（或默认状态）及推理显隐状态、从事件日志归并得出的生命周期计数、与页脚一致的去重用量分项和 KV 缓存命中率，以及 `tokenMeter` 给出的上下文用量和所选模型公布的容量。插件注册共享的 `userInteraction` 提供方，在左下角宽幅键盘操作面板中呈现排队的问题，面板显示批次进度、带编号的选项和对齐的描述；面板的操作提示只列出在当前选项数量下有意义的操作，仅有一个选项时不显示导航项；agent 行为和答案日志仍由既有服务负责。 +编辑器输入调用 `agent.steer()`，使其无论 agent 空闲还是运行中都以最近的步骤为目标。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。`/exit` 和 `/quit` 共用同一条退出路径：先取消进行中的轮次，等待 agent 空闲，然后恢复并关闭终端。空闲态页脚根据 `tokenMeter` 得出上下文占用率，并显示所选模型和显式选定的推理强度；agent 运行期间，该摘要会替换为带已用时长的活动指示和 Escape 中断提示。`/status` 在这两种状态下均可用，并会追加一份仅在终端显示的详细快照，其中包括会话标识与时间戳、所选模型、推理强度（或默认状态）及推理显隐状态、从事件日志归并得出的生命周期计数、与页脚一致的去重用量分项和 KV 缓存命中率，以及 `tokenMeter` 给出的上下文用量和所选模型公布的容量。插件注册共享的 `userInteraction` 提供方，在左下角宽幅键盘操作面板中呈现排队的问题，面板显示批次进度、带编号的选项和对齐的描述；面板的操作提示只列出在当前选项数量下有意义的操作，仅有一个选项时不显示导航项；agent 行为和答案日志仍由既有服务负责。 `/model` 命令将建议性的 `ctx.llm` 目录呈现为键盘选择器，并且只更改当前 TUI 会话的目标；带参数的形式仍可直接选择目标。每个模型行都持有适配器公布的推理强度顺序和默认值：按 Shift+Tab 可循环切换该行的推理强度；如果适配器没有公布默认值，循环中还会包含提供方默认行为；没有可选元数据的模型则保持不变。agent 作用域内的 prompt 组装和请求两条 waterfall（瀑布式事件）会为每个步骤快照一次同一个提供方/模型/推理强度目标，因此即使命令在组装期间到达，`{{provider}}` / `{{model}}` 插值与请求路由也不会分裂。系统通过日志中最新的请求头恢复已经使用过的目标；未被请求使用的选择只保留在当前进程中。 diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml index 6cf16c04ad..43d32ebb80 100644 --- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-07-19-model-facing-goal-tools.md: bc4305af80bb13ceeff1888d489dcd8a00132f94 -2026-07-19-model-facing-goal-tools.zh.md: b07f62aa526902c4b2e9c081777a76ca53783d31 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md +2026-07-19-model-facing-goal-tools.md: 19b413235052d37c58a65aefa33aba39e0e08812 +2026-07-19-model-facing-goal-tools.zh.md: 91eb7c2fa202a3781176afb8261ea484dbd46fda diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md index bc4305af80..19b4132350 100644 --- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md +++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md @@ -28,7 +28,7 @@ An autonomous goal round that successfully reports completion or blocking marks Every call requires an `exec.agent` that is the exact running object in `AgentRegistry`, is the current inherited driver initiator, and has an open turn. These are execution-time checks and cannot be bypassed by prompt injection or hand-authored tool arguments. -Create, edit, pause, and resume additionally require an accepted user message or user steering event in the current turn of a runtime-root agent. Root ownership is derived from the live agent graph rather than durable fork ancestry: a resumed fork can receive direct human authority, while a live child remains a subagent and cannot mutate these states. User source is a host attestation: every `Agent.send()` or `steer()` input requires an explicit source, so the host labels direct human content `{ kind: 'user' }` and non-human producers label their own provenance. The runtime proves provenance, not whether the human's wording semantically warrants creation or resumption; that interpretation remains with the model. +Create, edit, pause, and resume additionally require an accepted user message or user steering event in the current turn of a runtime-root agent. Root ownership is derived from the live agent graph rather than durable fork ancestry: a resumed fork can receive direct human authority, while a live child remains a subagent and cannot mutate these states. User source is a host attestation: every `Agent.followup()` or `steer()` input requires an explicit source, so the host labels direct human content `{ kind: 'user' }` and non-human producers label their own provenance. The runtime proves provenance, not whether the human's wording semantically warrants creation or resumption; that interpretation remains with the model. Complete and blocked accept either direct-human authority or the exact current goal round. Goal-round authority requires a goal-sourced `user/message` whose goal id, revision, and round all equal the folded current goal. It grants only the two terminal reports. Direct human authority may stop a goal immediately. diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md index b07f62aa52..91eb7c2fa2 100644 --- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md @@ -28,7 +28,7 @@ Status: implemented 每次调用都要求存在 `exec.agent`，且它必须是 `AgentRegistry` 中完全相同的运行中对象、当前继承的驱动发起者，并处于开放轮次内。这些检查在执行时进行，不能通过提示词注入或手写工具参数绕过。 -创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.send()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则标注自己的来源信息。运行时证明来源，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。 +创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.followup()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则标注自己的来源信息。运行时证明来源，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。 完成与阻塞既接受直接人类权限，也接受准确的当前目标回合。目标回合权限要求存在一条来源为目标的 `user/message`，其中目标 id、修订号和回合都与折叠后的当前目标相等。它只授予这两种终止报告权限。直接人类权限可以立即停止目标。 diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml index 8b2ddb5ac1..a17ee41ccf 100644 --- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-07-19-plugin-command-registration.md: 343cb5d946dba9fb881adf12c197961dfd6a359b -2026-07-19-plugin-command-registration.zh.md: 27757f05afe04d7cbd4ceaf9380b6f73441cc4b9 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md +2026-07-19-plugin-command-registration.md: 5233ce511dc9798733513ccbf6824f3e1b68d2e6 +2026-07-19-plugin-command-registration.zh.md: 67ac497ff91d42900b89fbbe40e4cc0856f939bc diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md index 343cb5d946..5233ce511d 100644 --- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md +++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md @@ -36,7 +36,7 @@ Expected handler failures return `CommandResult.error`. Thrown or malformed resu ### TUI mapping -The TUI registers its built-in slash commands as agent-scoped command definitions instead of switching on strings. Its autocomplete and help view read the live catalog, so plugin commands appear and disappear with their effects. Any submitted line beginning with `/` stays in the command plane; unknown input produces a terminal warning rather than falling through to `Agent.send()` or `Agent.steer()`. +The TUI registers its built-in slash commands as agent-scoped command definitions instead of switching on strings. Its autocomplete and help view read the live catalog, so plugin commands appear and disappear with their effects. Any submitted line beginning with `/` stays in the command plane; unknown input produces a terminal warning rather than falling through to `Agent.steer()`. Each submitted command owns an `AbortController`. TUI disposal aborts outstanding dispatches, removes the local definitions, and waits for the command-producing fiber before completing teardown. diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md index 27757f05af..67ac497ff9 100644 --- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md @@ -36,7 +36,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派 ### TUI 映射 -TUI 把内置斜杠命令注册为智能体作用域命令定义，不再对字符串执行 switch。自动补全与帮助视图读取实时目录，因此插件命令会随其副作用出现和消失。任何以 `/` 开头的提交行都留在命令平面；未知输入产生终端警告，不会落入 `Agent.send()` 或 `Agent.steer()`。 +TUI 把内置斜杠命令注册为智能体作用域命令定义，不再对字符串执行 switch。自动补全与帮助视图读取实时目录，因此插件命令会随其副作用出现和消失。任何以 `/` 开头的提交行都留在命令平面；未知输入产生终端警告，不会落入 `Agent.steer()`。 每个提交的命令拥有一个 `AbortController`。TUI 释放会中止未完成的分派、移除本地定义，并等待命令生产者 fiber（纤程）后再完成清理。 diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml index b354999813..ca0518d268 100644 --- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-07-19-same-session-goal-round-driver.md: 0e6be9fe3109336d47867ab52c585dc267309fb4 -2026-07-19-same-session-goal-round-driver.zh.md: cfd9d1aa8cbc3c17cd046df4f57a8f79a6877f5c +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md +2026-07-19-same-session-goal-round-driver.md: 6f0059e8f4a09c979e3411ecde1b643f95819c26 +2026-07-19-same-session-goal-round-driver.zh.md: 871c8c13772eeab7b91ff2be6154ce798d4aced4 diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md index 0e6be9fe31..6f0059e8f4 100644 --- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md +++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md @@ -8,7 +8,7 @@ English | [中文](2026-07-19-same-session-goal-round-driver.zh.md) The goal domain can retain an objective and the model-facing tools can mutate its lifecycle, but neither should decide when another model turn begins. A continuation driver must bridge active goal state to the ordinary agent loop without adding goal-specific branches to `dsh-agent-loop`, inventing a second conversation, or treating every human turn as an autonomous iteration. -That bridge has concurrency and durability obligations. Human input, cancellation, a goal edit, persistence failure, session restart, plugin unload, and a downstream prompt policy can all race a pending continuation. A naive `goal/changed -> agent.send()` listener can admit obsolete work, run alongside a human prompt, spend beyond the cap, or restart from replay without new authority. +That bridge has concurrency and durability obligations. Human input, cancellation, a goal edit, persistence failure, session restart, plugin unload, and a downstream prompt policy can all race a pending continuation. A naive `goal/changed -> agent.followup()` listener can admit obsolete work, run alongside a human prompt, spend beyond the cap, or restart from replay without new authority. ## Decision @@ -20,7 +20,7 @@ The plugin has no configuration. `maxGoalRounds` is resolved and persisted by `d ### Reservation and admission -When an agent is idle, has no competing queued work, and its current goal is `active` plus `armed`, the driver checkpoints pending goal mutations and rechecks every predicate after the await. If `roundsStarted` already equals `maxGoalRounds`, it records `blocked` with code `round-limit`. Otherwise it reserves the exact identity `{ goalId, revision, round: roundsStarted + 1 }` and the complete rendered prompt before calling `Agent.send()` with `GoalMessageSource`. The prompt JSON-quotes the objective so multiline or tag-like text remains an unambiguous data value inside the familiar frame. +When an agent is idle, has no competing queued work, and its current goal is `active` plus `armed`, the driver checkpoints pending goal mutations and rechecks every predicate after the await. If `roundsStarted` already equals `maxGoalRounds`, it records `blocked` with code `round-limit`. Otherwise it reserves the exact identity `{ goalId, revision, round: roundsStarted + 1 }` and the complete rendered prompt before calling `Agent.followup()` with `GoalMessageSource`. The prompt JSON-quotes the objective so multiline or tag-like text remains an unambiguous data value inside the familiar frame. The `agent/prompt-submit` waterfall is the admission fence. A positive goal source is allowed only when it exactly matches the driver's pending identity and content, the live goal still has that id and revision, activation remains armed, and the round is still the next number. The plugin checks once before delegating and again after downstream hooks return. This second check prevents an async hook from editing or pausing the goal while still admitting the old prompt. diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md index cfd9d1aa8c..871c8c1377 100644 --- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md @@ -8,7 +8,7 @@ Status: implemented 目标领域可以保留目标，模型可见工具也可以变更其生命周期，但两者都不应决定下一个模型轮次何时开始。继续执行驱动器必须把活跃目标状态连接到普通 agent（智能体）循环，同时不能向 `dsh-agent-loop` 添加目标专用分支、创建第二段对话，也不能把每个人类轮次都视为自主迭代。 -这层连接还承担并发与持久性义务。人类输入、取消、目标编辑、持久化失败、会话重启、插件卸载以及下游提示词策略都可能与待处理的继续执行发生竞争。简单的 `goal/changed -> agent.send()` 监听器可能接纳过期工作、与人类提示词同时运行、超出上限消耗资源，或在回放后未经新授权自行重启。 +这层连接还承担并发与持久性义务。人类输入、取消、目标编辑、持久化失败、会话重启、插件卸载以及下游提示词策略都可能与待处理的继续执行发生竞争。简单的 `goal/changed -> agent.followup()` 监听器可能接纳过期工作、与人类提示词同时运行、超出上限消耗资源，或在回放后未经新授权自行重启。 ## 决策 @@ -20,7 +20,7 @@ Status: implemented ### 预留与接纳 -当 agent 空闲、没有竞争中的排队工作，且当前目标为 `active` 加 `armed` 时，驱动器会先检查点持久化待处理的目标变更，并在等待之后重新校验所有条件。若 `roundsStarted` 已等于 `maxGoalRounds`，它会记录代码为 `round-limit` 的 `blocked`；否则，它会先预留精确身份 `{ goalId, revision, round: roundsStarted + 1 }` 和完整渲染提示词，再以 `GoalMessageSource` 调用 `Agent.send()`。提示词用 JSON 引号编码目标描述，使多行或类似标签的文本在熟悉框架中仍是无歧义的数据值。 +当 agent 空闲、没有竞争中的排队工作，且当前目标为 `active` 加 `armed` 时，驱动器会先检查点持久化待处理的目标变更，并在等待之后重新校验所有条件。若 `roundsStarted` 已等于 `maxGoalRounds`，它会记录代码为 `round-limit` 的 `blocked`；否则，它会先预留精确身份 `{ goalId, revision, round: roundsStarted + 1 }` 和完整渲染提示词，再以 `GoalMessageSource` 调用 `Agent.followup()`。提示词用 JSON 引号编码目标描述，使多行或类似标签的文本在熟悉框架中仍是无歧义的数据值。 `agent/prompt-submit` 瀑布是接纳栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会获准。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步钩子编辑或暂停目标后，旧提示词仍被接纳。 diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml index 1b9aa60021..8266581269 100644 --- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.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/feature/2026-07-21-cross-session-references.md -2026-07-21-cross-session-references.md: 61ea30cabb2abf4d4a9b4391891b5987affb91d0 -2026-07-21-cross-session-references.zh.md: 6fba44103942d29428fd820591815743dfb5d96d +2026-07-21-cross-session-references.md: fb6ee48a5f0c4bd89660ff24cfc523d744dacbe8 +2026-07-21-cross-session-references.zh.md: a35a44e9cf031a76947a5a662c62c27da72aba6c diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md index 61ea30cabb..fb6ee48a5f 100644 --- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md +++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md @@ -18,7 +18,7 @@ The service uses `ctx.sessionQuery.readSurface(sessionId)`, which loads one live ## Snapshot and projection -Preparation deduplicates in first-appearance order, rejects the target id, enforces a configurable limit with a hard maximum of three references, and performs all reads in parallel. It returns no partially prepared context: any read, cancellation, validation, or budget error rejects the operation before `send()` or `steer()`. Cancellation races in-flight discovery and exact reads, so a host settles promptly even when a persistence backend cannot interrupt its pending operation; any late backend settlement is observed but cannot enqueue the message. A source is read before enqueue, so later source messages, compaction, deletion, or persistence replacement cannot change the target session. +Preparation deduplicates in first-appearance order, rejects the target id, enforces a configurable limit with a hard maximum of three references, and performs all reads in parallel. It returns no partially prepared context: any read, cancellation, validation, or budget error rejects the operation before `followup()` or `steer()`. Cancellation races in-flight discovery and exact reads, so a host settles promptly even when a persistence backend cannot interrupt its pending operation; any late backend settlement is observed but cannot enqueue the message. A source is read before enqueue, so later source messages, compaction, deletion, or persistence replacement cannot change the target session. Projection retains direct-user messages and steering, completed assistant text, and checkpoint user messages carrying the canonical source exported by `dsh-compact`. That marker is part of the compaction capability contract rather than a backend package name. When a source prompt already contains baked prefix context, projection reads only its model-hidden display content, so referencing that target later does not recursively propagate an earlier snapshot. Projection excludes shadowed pre-compaction nodes, tools and results, reasoning, injected context, other plugin user messages, log-only records, and incomplete assistant chunks. Repeated compaction therefore exposes only the latest folded checkpoint lineage still on the current surface plus its retained tail; there is no raw/current switch and no shadow recovery. @@ -43,10 +43,10 @@ Each of at most three references is independently capped at 65,536 UTF-8 bytes b ## Alternatives considered - **Wait for SQLite FTS5** — rejected because snapshot correctness requires exact id reads and canonical surface folding, not content search. FTS improves discovery only. -- **Put mention syntax in `Agent.send()`** — rejected because it would make the core protocol parse one host's presentation syntax and prevent typed non-text hosts from sharing the semantic layer. +- **Put mention syntax in agent delivery methods** — rejected because it would make the core protocol parse one host's presentation syntax and prevent typed non-text hosts from sharing the semantic layer. - **Implement references separately in each host** — rejected because projection, security warning, retention, and persistence would drift across hosts. - **Attach context to `SendOptions` and the inbox record** — rejected because generic delivery would own a domain transaction through admission, steering, cancellation, and observation. A domain-specific admission wrapper and the existing next-step outbox preserve the required pairing without enlarging every message. -- **Bake the prefix host-side before `send()`** — rejected because `agent/prompt-submit` must inspect and rewrite only the direct prompt. Keeping the snapshot as a separate sourced message preserves that boundary and lets TUI hide background bytes from the direct user bubble. +- **Bake the prefix host-side before `followup()`** — rejected because `agent/prompt-submit` must inspect and rewrite only the direct prompt. Keeping the snapshot as a separate sourced message preserves that boundary and lets TUI hide background bytes from the direct user bubble. - **Replay the raw source log or restore shadowed events** — rejected because compact defines the current model surface and may intentionally retire sensitive or expensive history. - **Resume or fork the source** — rejected because the feature supplies read-only background for one target message, not identity or lifecycle continuity. - **Inject at request time by rereading the source** — rejected because the reference would become nondeterministic, cancellation races could alter its bytes, and target replay would depend on external mutable state. diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md index 6fba441039..a35a44e9cf 100644 --- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md +++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md @@ -18,7 +18,7 @@ TUI 用户需要把另一场对话中的相关工作带入一条新消息，但 ## 快照与投影 -准备过程按首次出现的顺序去重、拒绝目标会话自身的 id，并且执行可配置的数量限制，但引用硬上限为三个，所有读取均并行执行。该过程不会返回部分完成的上下文：任何读取、取消、校验或预算错误都会在调用 `send()` 或 `steer()` 前拒绝本次操作。取消会与进行中的候选发现和精确读取竞速，因此即使持久化后端无法中断待处理操作，宿主也能及时结束等待；后端迟到的完成结果仍会被观察，但不能让消息入队。源会话在入队前完成读取，因此源会话后续新增消息、执行压缩、被删除或替换持久化内容，都无法改变目标会话中的快照。 +准备过程按首次出现的顺序去重、拒绝目标会话自身的 id，并且执行可配置的数量限制，但引用硬上限为三个，所有读取均并行执行。该过程不会返回部分完成的上下文：任何读取、取消、校验或预算错误都会在调用 `followup()` 或 `steer()` 前拒绝本次操作。取消会与进行中的候选发现和精确读取竞速，因此即使持久化后端无法中断待处理操作，宿主也能及时结束等待；后端迟到的完成结果仍会被观察，但不能让消息入队。源会话在入队前完成读取，因此源会话后续新增消息、执行压缩、被删除或替换持久化内容，都无法改变目标会话中的快照。 投影会保留直接用户消息与 steering（中途引导）、已完成的 assistant 文本，以及携带由 `dsh-compact` 导出的规范来源标记的检查点用户消息。该标记属于压缩功能契约的一部分，而非某个后端包名称。当源提示词已包含合并写入的前缀上下文时，投影只读取其模型不可见的显示内容，因此后续引用该目标不会递归传播先前的快照。投影会排除压缩前已被遮蔽的节点、工具及其结果、推理（reasoning）、注入的上下文、其他插件用户消息、仅用于日志的记录，以及尚未完成的 assistant 分片。因此，重复压缩只会暴露当前表层仍保留的最新折叠检查点谱系及其尾部消息；系统不提供 raw/current 开关，也不恢复被遮蔽的内容。 @@ -43,10 +43,10 @@ TUI 把会话候选与现有 `@` 文件提供方组合在一起。候选查询 ## 考虑过的替代方案 - **等待 SQLite FTS5**：不予采纳，因为快照正确性依赖按准确 id 读取和规范表层折叠，而不是内容搜索。FTS 只改进候选发现。 -- **把提及标记语法放入 `Agent.send()`**：不予采纳，因为这会迫使核心协议解析某个宿主的展示语法，并阻止带类型的非文本宿主复用同一语义层。 +- **把提及标记语法放入 agent 投递方法**：不予采纳，因为这会迫使核心协议解析某个宿主的展示语法，并阻止带类型的非文本宿主复用同一语义层。 - **在每个宿主中分别实现引用**：不予采纳，因为投影、安全警告、保留策略和持久化会在不同宿主之间逐渐偏离。 - **把上下文附加到 `SendOptions` 和收件箱记录**：不予采纳，因为通用投递将不得不负责贯穿准入、steering、取消和观察的领域事务。领域专用的准入包装层和现有 next-step outbox 可以保持所需配对，而无需扩大每条消息。 -- **在调用 `send()` 前由宿主合并前缀**：不予采纳，因为 `agent/prompt-submit` 必须只检查和改写直接提示词。将快照保留为独立的带来源消息，可以维持该边界，并让 TUI 从直接用户气泡中隐藏背景字节。 +- **在调用 `followup()` 前由宿主合并前缀**：不予采纳，因为 `agent/prompt-submit` 必须只检查和改写直接提示词。将快照保留为独立的带来源消息，可以维持该边界，并让 TUI 从直接用户气泡中隐藏背景字节。 - **回放原始源日志或恢复被遮蔽的事件**：不予采纳，因为压缩定义了当前模型表层，并且可能有意淘汰敏感或开销高昂的历史内容。 - **恢复或 fork 源会话**：不予采纳，因为本功能只为一条目标消息提供只读背景，不提供身份或生命周期连续性。 - **在请求时重新读取源会话并注入**：不予采纳，因为这会让引用变得不确定，取消竞态可能改变其字节内容，目标回放也会依赖可变的外部状态。 diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml index 6d9112d663..f641718506 100644 --- a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-07-21-tui-skill-slash-command.md: 8370ab61f552a6a60177b6da0b598dd142d21960 -2026-07-21-tui-skill-slash-command.zh.md: 66edec6ecd5c2a974b56e08bd9e924729302cc4a +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md +2026-07-21-tui-skill-slash-command.md: d4fd0e5dc1532e45c49b543d1411f371cfa270f8 +2026-07-21-tui-skill-slash-command.zh.md: 9db48619f23d4170eea673d4144986a16e0a2f1f diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md index 8370ab61f5..d4fd0e5dc1 100644 --- a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md +++ b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md @@ -10,7 +10,7 @@ The [skill system](2026-07-05-skill-system.md) shipped with model-initiated load ## Decision -The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill: [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool and changes no skill-system package contract. +The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill: [instructions]` command. On submit it loads the named skill and delivers one text block through `agent.steer()`, the same path as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool and changes no skill-system package contract. The TUI reads the skill service through `ctx.get('skills')`, not a declared injection, because skills mount conditionally: a deployment without the registry keeps a working front door, and `/skill:` there reports that skills are unavailable rather than failing to mount. `createTuiChat` is synchronous while `ctx.skills.list()` is async, so autocomplete seeds the static slash commands immediately and rebuilds the provider with `skill:` entries once the catalog resolves; a resolution that arrives after disposal is dropped, and a rejected lookup keeps the base commands. diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md index 66edec6ecd..9db48619f2 100644 --- a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md +++ b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md @@ -10,7 +10,7 @@ Status: implemented ## Decision -[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill: [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的能力；它不新增任何面向模型的工具，也不改动任何 skill 系统包的契约。 +[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill: [instructions]` 命令。提交时它加载指定的 skill，并通过 `agent.steer()` 投递一个文本块，与普通编辑器输入走同一条路径。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的能力；它不新增任何面向模型的工具，也不改动任何 skill 系统包的契约。 TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。 diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml index f6cc14538d..e3f93ba1f6 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-06-20-public-agent-stop-surface.md: e22c4389df18f3c9ca96763fc097eabefcc5b761 -2026-06-20-public-agent-stop-surface.zh.md: e2647b498a8c906579b4fd2b50f94d1c326fe784 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md +2026-06-20-public-agent-stop-surface.md: 95c00f886360b94584f17c4221e0795be8ec1a61 +2026-06-20-public-agent-stop-surface.zh.md: 983833b53c123d0e384ad1d356808c6ca2f37edc diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md index e22c4389df..95c00f8863 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md +++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md @@ -36,4 +36,4 @@ A future plugin cannot abort only the current model/tool step while preserving q ## Related -This Agent Note only removes the redundant stop verb. Mid-turn steering remains an intentional message path; quiescence observation remains via `whenIdle()`. The resulting public surface is `send()`, `steer()`, `inject()`, `cancel()`, `whenIdle()`, status, options, session, and identity. +This Agent Note only removes the redundant stop verb. Mid-turn steering remains an intentional message path; quiescence observation remains via `whenIdle()`. The resulting delivery surface is `followup()`, `steer()`, and `inject()`; stopping and observation remain with `cancel()` and `whenIdle()`. diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md index e2647b498a..983833b53c 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md +++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md @@ -36,4 +36,4 @@ Status: implemented ## 相关 -本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终公共表面包括 `send()`、`steer()`、`inject()`、`cancel()`、`whenIdle()`、status、options、会话和 identity。 +本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终交付接口包括 `followup()`、`steer()` 和 `inject()`；停止与观察仍通过 `cancel()` 和 `whenIdle()` 完成。 diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml index 60181a2ddb..63a6333e01 100644 --- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.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/simplification/2026-07-17-one-send-one-turn.md -2026-07-17-one-send-one-turn.md: dcc6c0aa483a0e53205dbaeef4e2b903f5f6a215 -2026-07-17-one-send-one-turn.zh.md: 8c12481defe6608c13ee81132b432b4d8b17b681 +2026-07-17-one-send-one-turn.md: 4787a25042f3b002d6c247202d5614a0f7bfa673 +2026-07-17-one-send-one-turn.zh.md: c44c99771b22f7ecb1b802f8758a103d2774a140 diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md index dcc6c0aa48..4787a25042 100644 --- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md +++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md @@ -6,7 +6,7 @@ English | [中文](2026-07-17-one-send-one-turn.zh.md) ## Problem -Suppose a caller submits message A and then message B with two `Agent.send()` calls. Implicit batching can put A and B in one turn simply because both are waiting when the driver reads its queue. The caller made two calls, but the loop silently turns them into one unit of work. +Suppose a caller submits message A and then message B with two `Agent.followup()` calls. Implicit batching can put A and B in one turn simply because both are waiting when the driver reads its queue. The caller made two calls, but the loop silently turns them into one unit of work. That grouping depends on timing rather than caller intent. Calls from one synchronous stack, neighboring microtasks, event listeners, and model callbacks could be grouped differently even though every caller used the same API. @@ -14,15 +14,15 @@ This grouping changes behavior, not just the number of model calls. One ordinary ## Decision -The rule is simple: each successful `send()` creates one independent FIFO queue item. If that item runs, it is the only ordinary message in its turn. An item can be dropped before it starts, so the precise guarantee is at most one turn rather than exactly one; two sends are never silently combined. +The rule is simple: each successful `followup()` creates one independent FIFO queue item. If that item runs, it is the only ordinary message in its turn. An item can be dropped before it starts, so the precise guarantee is at most one turn rather than exactly one; two follow-ups are never silently combined. -Before enqueueing an item, `send()` checks the agent state and makes a detached, deeply frozen snapshot of the content and resolved source. After enqueueing it, `send()` publishes `agent/queued`. +Before enqueueing an item, `followup()` checks the agent state and makes a detached, deeply frozen snapshot of the content and resolved source. After enqueueing it, the agent publishes `agent/queued`. If messages A and B are both processed, B's turn starts only after A records `turn/end` and A's durability checkpoint settles. B's request therefore sees whatever closed result A left in the same session log. A checkpoint error is reported, but settlement only releases this ordering barrier; it does not make a failed write durable. Broad `cancel()`, disposal, or a failure before `turn/start` can instead discard an unstarted item without opening an empty turn. Prompt admission decides one message at a time before a turn opens. An allowed prompt becomes that turn's `user/message`; a blocked prompt is discarded without opening a turn or writing session history. Mixed-batch and all-blocked-batch branches do not exist. -The no-batching rule applies only to ordinary `send()`. Running `steer()` puts input in the outbox. While a turn remains open, the loop records that input at the next step boundary and steering makes another step the default. A failure before that boundary leaves the steering staged without waking the agent; a request-error retry action or a later prompt takes it, while cancellation or disposal can discard it. When the agent is idle, `steer()` delegates to `send()`, so it creates an independent ordinary queue item. +The no-batching rule applies only to ordinary `followup()`. Running `steer()` puts input in the outbox. While a turn remains open, the loop records that input at the next step boundary and steering makes another step the default. A failure before that boundary leaves the steering staged without waking the agent; a request-error retry action or a later prompt takes it, while cancellation or disposal can discard it. When the agent is idle, `steer()` creates an independent ordinary queue item. `inject()` continues to add model-facing context without submitting an ordinary message. During a turn it waits in the outbox for a safe step boundary; while idle it appends a `user/message` directly, without opening a turn or running the model. Persistence owns the resulting eager drain. `cancel()` remains a whole-agent operation that can clear all unstarted ordinary and steering input and abort the current step. `status` and `whenIdle()` also describe the whole agent, not one message. Several one-message turns can share one `running` interval, so `running` does not prove that a turn is open. diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md index 8c12481def..c44c99771b 100644 --- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md +++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md @@ -6,7 +6,7 @@ Status: implemented ## 问题 -假设调用方连续两次调用 `Agent.send()`，先提交消息 A，再提交消息 B。隐式批处理可能只因为驱动器读取队列时两条消息都在等待，就把 A、B 放进同一个轮次。调用方明明调用了两次，agent loop（智能体循环）却悄悄把它们变成一个工作单元。 +假设调用方连续两次调用 `Agent.followup()`，先提交消息 A，再提交消息 B。隐式批处理可能只因为驱动器读取队列时两条消息都在等待，就把 A、B 放进同一个轮次。调用方明明调用了两次，agent loop（智能体循环）却悄悄把它们变成一个工作单元。 这种分组取决于运行时机，而不是调用方的意图。因此，即使所有调用方使用相同 API，来自同一个同步调用栈、相邻微任务、事件监听器和模型回调的调用也可能产生不同分组。 @@ -14,15 +14,15 @@ Status: implemented ## 决策 -规则很简单：一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。 +规则很简单：一次成功的 `followup()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 follow-up 绝不会被悄悄合并。 -队列项入队之前，`send()` 会检查 agent 状态，并为内容和解析后的来源创建一份脱离调用方对象、经过深度冻结的快照。队列项入队之后，`send()` 发布 `agent/queued`。 +队列项入队之前，`followup()` 会检查 agent 状态，并为内容和解析后的来源创建一份脱离调用方对象、经过深度冻结的快照。队列项入队之后，agent 发布 `agent/queued`。 如果消息 A、B 都进入处理，B 的轮次只能在 A 记录 `turn/end` 且 A 的持久性检查点处理结束后开始。因此，B 的请求能看到 A 在同一会话日志中留下的已关闭结果。检查点错误会照常报告，但处理结束只表示解除这道顺序屏障，不表示失败的写入已经持久化。广义 `cancel()`、dispose（资源释放）或 `turn/start` 之前的失败也可能丢弃尚未启动的队列项，而不打开一个空轮次。 提示词准入会在轮次打开前，每次只决定一条消息。获准提示词成为该轮次的 `user/message`；被阻止的提示词会被丢弃，不打开轮次，也不写入会话历史。实现中不存在混合批次或全阻止批次分支。 -上述不合批规则只适用于普通 `send()`。agent 运行时，`steer()` 会把输入放入 outbox。只要当前轮次仍然打开，agent loop 就会在下一个步骤边界记录该输入，而 steering（中途引导）会默认让循环再执行一个步骤。在到达该边界前发生失败，会让 steering 保持暂存且不唤醒 agent；请求错误的重试动作或后续提示词会取走它，而取消或 dispose 可以将其丢弃。agent 空闲时，`steer()` 委托给 `send()`，因此会创建一个独立的普通队列项。 +上述不合批规则只适用于普通 `followup()`。agent 运行时，`steer()` 会把输入放入 outbox。只要当前轮次仍然打开，agent loop 就会在下一个步骤边界记录该输入，而 steering（中途引导）会默认让循环再执行一个步骤。在到达该边界前发生失败，会让 steering 保持暂存且不唤醒 agent；请求错误的重试动作或后续提示词会取走它，而取消或 dispose 可以将其丢弃。agent 空闲时，`steer()` 会创建一个独立的普通队列项。 `inject()` 继续添加面向模型的上下文，而不提交普通消息。轮次打开时，该上下文会留在 outbox 中，等待安全的步骤边界；agent 空闲时，系统会直接追加一条 `user/message`，既不打开轮次，也不运行模型。持久化层独立负责由此产生的即时排空。`cancel()` 仍是面向整个 agent 的操作，可以清空所有尚未启动的普通输入和 steering，并中止当前步骤。`status` 和 `whenIdle()` 描述的也是整个 agent，而不是某一条消息。多个单消息轮次可以共用一个 `running` 区间，因此 `running` 不表示轮次一定处于打开状态。 diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml index b524e96a02..376c763206 100644 --- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.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/simplification/2026-07-24-agent-loop-observable-state-machine.md -2026-07-24-agent-loop-observable-state-machine.md: a25657c6a41e2c0989db620046f44ea3254be151 -2026-07-24-agent-loop-observable-state-machine.zh.md: 058d89d3cb9e3d30963f95fda1510ef3c5bf281e +2026-07-24-agent-loop-observable-state-machine.md: 2024662495d8396e946e7c43f010164cd9414b83 +2026-07-24-agent-loop-observable-state-machine.zh.md: dc83a310ff2d7945e6b7e79625224102f0f4871c diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md index a25657c6a4..2024662495 100644 --- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md +++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md @@ -51,7 +51,7 @@ The inbox lifecycle complements, rather than replaces, the durable session log. ## Related -- [Unify agent delivery on send(target × wakeup) and coalesce injected context into user/message](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) +- [Unify agent delivery routing and coalesce injected context into user/message](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) - [Remove implicit batching from ordinary sends](2026-07-17-one-send-one-turn.md) - [Microkernel event taxonomy](../architecture/2026-06-11-microkernel-event-taxonomy.md) - [Bounded LLM request recovery](../architecture/2026-06-21-bounded-llm-request-recovery.md) diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md index 058d89d3cb..dc83a310ff 100644 --- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md +++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md @@ -51,7 +51,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及 ## 相关内容 -- [统一通过 send(target × wakeup) 交付 agent 消息，并将注入上下文合并到 user/message](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) +- [统一 agent 交付路由，并将注入上下文合并到 user/message](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) - [移除普通发送中的隐式批处理](2026-07-17-one-send-one-turn.md) - [微内核事件分类体系](../architecture/2026-06-11-microkernel-event-taxonomy.md) - [有界 LLM 请求恢复](../architecture/2026-06-21-bounded-llm-request-recovery.md) diff --git a/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.i18n.yaml index e22645e088..b6ed2513b2 100644 --- a/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.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/simplification/2026-07-27-request-error-retry-action.md -2026-07-27-request-error-retry-action.md: 3057b9fa28cf203c9374930fe97421918b4c1a6f -2026-07-27-request-error-retry-action.zh.md: bcb4e592f0c3d86f896e279cf0e3ea400741a1bb +2026-07-27-request-error-retry-action.md: 18ae9bc4ba26d1ad3cb7d1328d9e9d3e8de8377c +2026-07-27-request-error-retry-action.zh.md: a4092033eba236c95dbd237fbd93bf750f1055ab diff --git a/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.md b/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.md index 3057b9fa28..18ae9bc4ba 100644 --- a/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.md +++ b/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.md @@ -14,7 +14,7 @@ Model-request recovery was decided inside `agent/request-error` but communicated The loop reads the action after the waterfall settles, closes the failed turn, and opens one retry turn from durable history. It rechecks the turn signal when consuming the action, so cancellation or disposal during recovery prevents the retry even if a listener returns it afterward. A thrown recovery never produces an action. -`Agent` and `ReactLoopAgent` expose no `retry()` method. Ordinary new work enters through `send()` and its `followup()`, `steer()`, and `inject()` presets; only a handled model-request failure can open a promptless retry turn. +`Agent` and `ReactLoopAgent` expose no `retry()` method. Ordinary new work enters through `followup()`, `steer()`, and `inject()`; only a handled model-request failure can open a promptless retry turn. ## Alternatives considered diff --git a/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.zh.md b/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.zh.md index bcb4e592f0..a4092033eb 100644 --- a/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.zh.md +++ b/.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.zh.md @@ -14,7 +14,7 @@ Status: implemented waterfall 结算后，循环读取该动作，关闭失败轮次，并从持久历史开启一个重试轮次。循环在使用该动作时会再次检查轮次信号，因此即使监听器随后返回重试动作，恢复期间发生的取消或资源释放仍会阻止重试。抛出异常的恢复不会产生动作。 -`Agent` 与 `ReactLoopAgent` 均不暴露 `retry()` 方法。普通新工作通过 `send()` 及其 `followup()`、`steer()` 和 `inject()` 预设进入；只有已处理的模型请求失败才能开启没有提示词的重试轮次。 +`Agent` 与 `ReactLoopAgent` 均不暴露 `retry()` 方法。普通新工作通过 `followup()`、`steer()` 和 `inject()` 进入；只有已处理的模型请求失败才能开启没有提示词的重试轮次。 ## 曾考虑的替代方案 diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml new file mode 100644 index 0000000000..3245b307e5 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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/simplification/2026-07-30-private-agent-send.md +2026-07-30-private-agent-send.md: 43353c309f98eab1bff91b8fbe0c9cfaa2bbc69b +2026-07-30-private-agent-send.zh.md: 49f7c999ec60c7305bdca570a4d59039c7c1923b diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.md b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.md new file mode 100644 index 0000000000..43353c309f --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.md @@ -0,0 +1,27 @@ +# Agent Note: Keep agent routing private + +Status: implemented + +English | [中文](2026-07-30-private-agent-send.zh.md) + +## Problem + +The public `Agent.send()` method exposed the concrete loop's routing matrix even though production callers use only the semantic `followup()`, `steer()`, and `inject()` operations. Its fourth combination, `next-turn` with `wakeup: false`, had no consumer beyond tests. Keeping that latent capability public also required alternate `Agent` implementations and test fakes to accept implementation-level routing policy. + +## Decision + +`Agent` exposes `followup()`, `steer()`, and `inject()` as its complete delivery contract. `ReactLoopAgent` keeps a private `send()` helper that shares routing mechanics among those methods, while `SendTarget` and `SendOptions` are no longer exported from `dsh-agent`. + +The public interface cannot queue a turn without waking the driver. A follow-up always requests execution, steering requests the nearest step, and injection supplies model-facing context without requesting execution. This partially supersedes the public-surface portion of the [unified delivery decision](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) while retaining its internal routing and unified `user/message` representation. + +## Alternatives considered + +**Keep the routing matrix public.** This preserves the unused quiet-queue combination, but exposes mechanism instead of caller intent and imposes it on every alternate driver. + +**Add a public quiet-queue method.** A named method would be clearer than raw routing flags, but no production workflow currently needs work that remains parked until an unrelated delivery wakes it. + +## Consequences + +Plugins choose among three semantic operations instead of constructing routing options. Alternate drivers and structural test fakes implement a smaller contract, and the Cordis API catalog no longer advertises `send`, `SendTarget`, or `SendOptions`. + +The removed quiet-queue capability can return only with a named consumer and explicit lifecycle semantics. `cancel({ keepInbox: true })` still preserves work already pending through the supported delivery paths. diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md new file mode 100644 index 0000000000..49f7c999ec --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md @@ -0,0 +1,27 @@ +# Agent Note: 将 agent 路由保留为私有实现 + +Status: implemented + +[English](2026-07-30-private-agent-send.md) | 中文 + +## 问题 + +公开的 `Agent.send()` 方法暴露了实体循环的路由矩阵，但生产调用方只使用语义明确的 `followup()`、`steer()` 和 `inject()` 操作。第四种组合，即 `next-turn` 配合 `wakeup: false`，除测试外没有消费方。将这项潜在能力保留为公开接口，还会迫使其他 `Agent` 实现和测试替身接受实现层的路由策略。 + +## 决策 + +`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付契约公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。 + +公开接口无法在不唤醒驱动器的情况下让一个轮次入队。`followup()` 始终请求执行，`steer()` 请求最近的步骤，`inject()` 则提供面向模型的上下文而不请求执行。本决策部分取代[统一交付决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)中关于公开接口的内容，同时保留其内部路由与统一的 `user/message` 表示。 + +## 曾考虑的替代方案 + +**让路由矩阵保持公开。** 这会保留未使用的无唤醒排队组合，但也会暴露机制而非调用方意图，并要求每个替代驱动器都支持该机制。 + +**添加公开的无唤醒排队方法。** 使用具名方法会比原始路由标志更清晰，但目前没有生产工作流需要让工作持续处于等待状态，直到无关的交付将其唤醒。 + +## 后果 + +插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的契约，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。 + +只有出现明确的消费方并定义显式的生命周期语义后，才能恢复已移除的无唤醒排队能力。`cancel({ keepInbox: true })` 仍会保留已通过受支持交付路径进入待处理状态的工作。 diff --git a/apps/cli/src/headless.ts b/apps/cli/src/headless.ts index d7588ccae4..1d29403ee6 100644 --- a/apps/cli/src/headless.ts +++ b/apps/cli/src/headless.ts @@ -49,7 +49,7 @@ async function consumeUntilTurnEnd(frames: AsyncIterable>, if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue const event = payload.event if (targetTurn === undefined) { - if (event.type === 'turn/start' && event.data.trigger.kind === 'message') targetTurn = event.data.turn + if (event.type === 'turn/start') targetTurn = event.data.turn continue } if (event.type === 'assistant/message' && event.data.turn === targetTurn) { diff --git a/apps/web/tests/cordis-tool-round.e2e.ts b/apps/web/tests/cordis-tool-round.e2e.ts index 558fa1bfc3..c67ff03021 100644 --- a/apps/web/tests/cordis-tool-round.e2e.ts +++ b/apps/web/tests/cordis-tool-round.e2e.ts @@ -29,9 +29,7 @@ function assertCompleteCordisLifecycle(events: readonly SessionEvent[]): void { (event): event is Extract => event.type === 'turn/end', ) const reason = turnEnd?.data.reason - const reasonSummary = reason?.kind === 'error' - ? { kind: reason.kind, code: reason.failure?.code, status: reason.failure?.status } - : { kind: reason?.kind } + const reasonSummary = { kind: reason?.kind } expect(reasonSummary).toEqual({ kind: 'completed' }) const calls = events.filter( diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index f722ead61b..8b4796ce68 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -237,26 +237,21 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise { return new Promise((resolveSettled, reject) => { const timer = setTimeout(() => { off() reject(new Error(`no turn/end within ${timeoutMs}ms`)) }, timeoutMs) - const off = ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => { + const off = ctx.on('session/event', (session: Session, event: SessionEvent) => { if (event.type !== 'turn/end') return clearTimeout(timer) off() - const agent = ctx.agents.get(session.id) - if (agent === undefined) { - reject(new Error(`turn/end for ${session.id} but no live agent`)) - return - } - agent.whenIdle().then(() => { resolveSettled(session.id) }, reject) + ctx.sessions.flush(session) + .then(() => { resolveSettled(session.id) }, reject) }) }) }, diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index c296e10fb1..bfc5a70656 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: 2ae982eba49b6dbd2365496915f9917071167813 -architecture.zh.md: abaef961504ff64dbcd1e8e8ba9bd002406fa7f4 +architecture.md: e7861cb5e59c30b3a20e0811fc1c644b300d8bfe +architecture.zh.md: b0b7bed4780cb3442076f874ba98503cd1255482 diff --git a/docs/architecture.md b/docs/architecture.md index 2ae982eba4..e7861cb5e5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -65,7 +65,7 @@ Waterfalls are around-middleware: listeners delegate with `next()`; returning wi ## Default Loop Lifecycle -A **session** is append-only. An ordinary **turn** claims one queued `send()` item; injection claims none. A successor awaits its predecessor's checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A turn ends when model or plugins stop it; a **step** is one model request plus tools. Quotes in the [sequence below](agent-lifecycle.md) mark durable events. +A **session** is append-only. An ordinary **turn** claims one queued follow-up; injection claims none. A successor awaits its predecessor's checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A turn ends when model or plugins stop it; a **step** is one model request plus tools. Quotes in the [sequence below](agent-lifecycle.md) mark durable events. Creation without an id mints `-session-`; `sessionId` resumes or creates, while `resumeSessionId` requires history. Resume restores lineage and delegation depth before publication. Setup failures emit `agent-loop/config-start-failed`; teardown is silent. @@ -122,7 +122,7 @@ Pruning precedes summaries; overflow retries require durable progress. `agent/re ### Failure Boundaries -Adapter failures close their step before `agent/request-error` receives the exact `Error`, normalized `LlmFailure`, and signal. A handled failure closes its turn and opens a retry turn from durable history without an idle notification; exhaustion leaves terminal `turn/end`. Failed chunks commit neither messages nor tool calls. +Final-adapter selection, dispatch, and iteration failures become terminal `finish { kind: 'error' | 'aborted', failure }` chunks before the loop handles them. `agent/request-error` receives request coordinates, normalized `LlmFailure`, the prepared registration's retry policy when available, and the signal; middleware and consumer errors remain thrown outside request recovery. Failed chunks commit neither messages nor tool calls. Other failures use `agent/error`. Cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels asynchronous model-capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` emits its cause before queue clearing and abort; observers cannot veto; idle calls emit nothing. Durability records user or parent cancellation as `aborted`, teardown as `disposed`; teardown awaits quiescence. The cause affects reporting, not late result-context handling ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)). @@ -130,7 +130,7 @@ Turn and step events are turn-enclosed; idle injected `user/message` events may ### Agent Handles -`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins use full `send()` options or `followup()`, `steer()`, and `inject()` presets; `cancel()` and `whenIdle()` control lifecycle. One awaited disposer coordinates teardown ownership. +`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. ### Agent Scope diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index abaef96150..b0b7bed478 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -65,7 +65,7 @@ waterfall（瀑布式事件）是环绕中间件：监听器通过 `next()` 委 ## 默认循环生命周期 -**会话**采用仅追加方式。普通**轮次**领取一项已排队的 `send()` 输入；注入不领取输入。后续轮次会等待前一轮次的检查点，但可以与其共用同一个 `running` 区间（[决策](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)）。模型或插件停止轮次时，该轮次结束；一个**步骤**包含一次模型请求及其工具。[下文时序](agent-lifecycle.md)中的引号标记持久事件。 +**会话**采用仅追加方式。普通**轮次**领取一条已排队的后续消息；注入不领取输入。后续轮次会等待前一轮次的检查点，但可以与其共用同一个 `running` 区间（[决策](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)）。模型或插件停止轮次时，该轮次结束；一个**步骤**包含一次模型请求及其工具。[下文时序](agent-lifecycle.md)中的引号标记持久事件。 创建时若未提供 id，流程会生成 `-session-`；`sessionId` 用于恢复或创建会话，而 `resumeSessionId` 要求已有历史。恢复流程在发布前还原沿袭关系和委托深度。初始化失败会发出 `agent-loop/config-start-failed`；拆卸过程保持静默。 @@ -122,7 +122,7 @@ idle inject: ### 失败边界 -适配器故障会先关闭自身步骤，再由 `agent/request-error` 接收准确的 `Error`、标准化的 `LlmFailure` 和信号。已处理的失败会关闭所在轮次，并从持久历史开启重试轮次，不发出空闲通知；重试耗尽则留下终态 `turn/end`。失败分片既不提交消息，也不提交工具调用。 +最终适配器选择、分发与迭代失败会在 loop 处理前成为终止 `finish { kind: 'error' | 'aborted', failure }` chunk。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用时的准备注册重试策略以及信号；middleware 与消费方错误仍在请求恢复之外抛出。失败分片既不提交消息，也不提交工具调用。 其他故障使用 `agent/error`。取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消异步模型能力准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 在清空队列和中止前发出原因；观察方不能否决；空闲调用不发事件。持久化层将用户或父级取消记录为 `aborted`，拆卸记录为 `disposed`；拆卸会等待完全停稳。原因只影响报告方式，不影响延迟完成的结果上下文处理（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。 @@ -130,7 +130,7 @@ idle inject: ### Agent 句柄 -`ctx.agents` 拥有活跃 agent，并返回 `AgentHandle { agent, dispose() }`。插件使用全部 `send()` 选项，或 `followup()`、`steer()` 和 `inject()` 预设；`cancel()` 与 `whenIdle()` 控制生命周期。一个需等待完成的 disposer 协调拆卸归属。 +`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。 ### Agent 作用域 diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 967241fbf6..ac630fd39c 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -13,27 +13,6 @@ Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `n ## `agent/*` -### `agent/cancel-requested` — emit - -Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained. - -```ts cordis-catalog -/** - * Effective broad cancellation was requested, before queued/outbox work - * is cleared or the active turn is aborted. This observe-only notification - * cannot veto cancellation; listener failures are contained. - * @param agent - the agent whose current work is being cancelled. - * @param cause - the explicit typed cancellation cause. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/cancel-requested'(this: Scoped, agent: Agent, cause: AgentCancelCause): void -``` - -Types: [Agent](../core-data-structures/core.md) · [AgentCancelCause](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) - -Source: [`packages/core/agent/src/types.ts:286`](../../packages/core/agent/src/types.ts) - ### `agent/created` — emit A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry. @@ -54,7 +33,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:218`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:148`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -74,7 +53,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:227`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:157`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -96,98 +75,70 @@ A step or turn errored. The machine reports a failure here (plus the logger) eve Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:400`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:276`](../../packages/core/agent/src/types.ts) -### `agent/inbox/dequeue` — emit +### `agent/inbox/admitted` — emit -The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message. +The driver admitted one inbox item for model-visible history. ```ts cordis-catalog /** - * The driver claimed one item out of the inbox: a queued item at a turn - * boundary, or steering drained between steps. Fires after the item leaves - * its FIFO and before it becomes a durable message. + * The driver admitted one inbox item for model-visible history. * @param agent - the agent whose inbox item was claimed. - * @param message - the claimed message. - * @param placement - the FIFO that claimed this occurrence; together with - * `message.id`, it matches the earliest outstanding enqueue in that FIFO. + * @param message - the admitted message. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode emit */ -'agent/inbox/dequeue'( this: Scoped, agent: Agent, message: UserMessage, placement: InboxPlacement, ): void -``` - -Types: [Agent](../core-data-structures/core.md) · [InboxPlacement](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) - -Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts) - -### `agent/inbox/discard` — emit - -Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item. - -```ts cordis-catalog -/** - * Pending inbox items were dropped without delivering them, so every - * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR - * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, - * emits this after `agent/cancel-requested` when applicable and before - * aborting the active work. Fires once per drop with every dropped item. - * @param agent - the agent whose inbox items were dropped. - * @param messages - the discarded messages in FIFO order (queued then steering); never empty. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/inbox/discard'(this: Scoped, agent: Agent, messages: UserMessage[]): void +'agent/inbox/admitted'(this: Scoped, agent: Agent, message: UserMessage): void ``` Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) -Source: [`packages/core/agent/src/types.ts:276`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:175`](../../packages/core/agent/src/types.ts) -### `agent/inbox/enqueue` — emit +### `agent/inbox/canceled` — emit -An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state. +One pending inbox item was dropped without entering model-visible history. `cancel()` without `keepInbox`, including disposal, emits this once for each dropped item before aborting active work. ```ts cordis-catalog /** - * An item entered the queued or steering inbox. `placement` is the - * acceptance-time routing result; listeners must not reconstruct it from - * later agent or session state. - * @param agent - the owning agent. - * @param message - accepted content, source, and correlation identity. - * @param placement - resolved queued or steering placement. + * One pending inbox item was dropped without entering model-visible + * history. `cancel()` without `keepInbox`, including disposal, emits this + * once for each dropped item before aborting active work. + * @param agent - the agent whose inbox items were dropped. + * @param message - the dropped message. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode emit */ -'agent/inbox/enqueue'(this: Scoped, agent: Agent, message: UserMessage, placement: InboxPlacement): void +'agent/inbox/canceled'(this: Scoped, agent: Agent, message: UserMessage): void ``` -Types: [Agent](../core-data-structures/core.md) · [InboxPlacement](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) +Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) -Source: [`packages/core/agent/src/types.ts:247`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall -Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn. +Allow, rewrite, or block one claimed inbox batch before it becomes model-visible or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn. ```ts cordis-catalog /** - * Allow, rewrite, or block one claimed prompt before it becomes a user - * message or opens a turn. Call `next()` for the unchanged default. The + * Allow, rewrite, or block one claimed inbox batch before it becomes + * model-visible or opens a turn. Call `next()` for the unchanged default. The * signal controls only this admission attempt; listeners may cooperate with * it but must not retain it for a later attempt or turn. - * @param agent - the agent whose turn claimed the message. - * @param message - the frozen claimed message, including identity and source. + * @param agent - the agent whose driver claimed the batch. + * @param messages - the claimed messages. * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ -'agent/prompt-submit'(this: Scoped, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise): Promise +'agent/prompt-submit'(this: Scoped, agent: Agent, messages: UserMessage[], signal: AbortSignal, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) -Source: [`packages/core/agent/src/types.ts:313`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:211`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall @@ -211,37 +162,30 @@ Replace the frozen call configuration. `await next()` yields the config the mach Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:339`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:237`](../../packages/core/agent/src/types.ts) ### `agent/request-error` — waterfall -Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal. +Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal. ```ts cordis-catalog /** - * Handle a model-request failure after its failed step has closed but - * before the failed turn closes. A listener returns `{ kind: 'retry' }` - * without calling `next()` when it owns the error, or calls `next()` to - * delegate. The default `undefined` leaves the failure terminal. + * Handle one failed model-request attempt before the loop retries or closes + * its step. A listener returns `{ kind: 'retry' }` without calling `next()` + * when it owns recovery, or calls `next()` to delegate. The default + * `undefined` leaves the failure terminal. * @param agent - the agent whose request failed. - * @param turn - the open turn number. - * @param step - the failed step number. - * @param error - the original model-request failure. - * @param failure - serializable facts normalized at the final adapter boundary. - * @param priorFailures - immutable failures that already authorized another - * retry turn in this consecutive sequence. - * @param retryPolicy - immutable policy of the adapter registration that served - * the failed request, or `undefined` if no final adapter served it. + * @param context - request coordinates, provider, normalized failure, and serving policy. * @param signal - the turn abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ -'agent/request-error'(this: Scoped, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise): Promise +'agent/request-error'(this: Scoped, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestError](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [RequestFailureContext](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:358`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:249`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -263,41 +207,17 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:299`](../../packages/core/agent/src/types.ts) - -### `agent/settled` — emit - -One drain chain reached its terminal turn: that turn's `turn/end` is already committed. Automatically recovered failed turns do not emit this notification, and neither does a run that aborts or fails before its `turn/start` commits — there is no durable turn to settle against. `reason` says why; model-request recovery is exhausted when an error reaches it. - -```ts cordis-catalog -/** - * One drain chain reached its terminal turn: that turn's `turn/end` is - * already committed. Automatically recovered failed turns do not emit this - * notification, and neither does a run that aborts or fails before its - * `turn/start` commits — there is no durable turn to settle against. - * `reason` says why; model-request recovery is exhausted when an error - * reaches it. - * @param agent - the agent whose turn closed. - * @param turn - the terminal turn number. - * @param reason - why the terminal turn ended, with live error facts when it failed. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/settled'(this: Scoped, agent: Agent, turn: number, reason: SettleReason): void -``` - -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SettleReason](../core-data-structures/core.md) - -Source: [`packages/core/agent/src/types.ts:387`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:197`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit -Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event. +Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active. ```ts cordis-catalog /** - * Agent status changed (`idle` ⇄ `running`). `send()` does not enter - * `running` synchronously; drive lifecycle from this event. + * Agent status changed (`idle` ⇄ `running`). A waking delivery enters + * `running` synchronously after reserving cancellation; `idle` means no + * driver remains scheduled or active. * @param agent - the agent whose status flipped. * @param status - the status just entered (the transition's destination). * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. @@ -308,7 +228,7 @@ Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` s Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:236`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts) ### `agent/step` — serial @@ -332,7 +252,7 @@ Awaited serial checkpoint before EVERY request of a turn is built (the first as Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:326`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:224`](../../packages/core/agent/src/types.ts) ### `agent/turn-stopping` — serial @@ -358,7 +278,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:373`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts) ## `agent-loop/*` @@ -550,7 +470,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md) -Source: [`packages/llm/llm/src/index.ts:58`](../../packages/llm/llm/src/index.ts) +Source: [`packages/llm/llm/src/index.ts:56`](../../packages/llm/llm/src/index.ts) ## `session/*` @@ -575,7 +495,7 @@ Creation announcement during session publication. A synchronous throw vetoes and Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) -Source: [`packages/core/session/src/index.ts:71`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:50`](../../packages/core/session/src/index.ts) ### `session/disposed` — emit @@ -596,7 +516,7 @@ Emitted once when an announced session leaves the store, including publication r Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) -Source: [`packages/core/session/src/index.ts:81`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:60`](../../packages/core/session/src/index.ts) ### `session/event` — emit @@ -619,7 +539,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) -Source: [`packages/core/session/src/index.ts:93`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:72`](../../packages/core/session/src/index.ts) ### `session/flush` — parallel @@ -640,7 +560,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) -Source: [`packages/core/session/src/index.ts:103`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:82`](../../packages/core/session/src/index.ts) ## `slash/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index e0dd17fa02..f976556305 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -803,15 +803,13 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise /** - * Stream one model call as raw chunks (token-level deltas). Throws - * `LlmError` with code `NO_ADAPTER` if no adapter is registered for - * `options.provider`. Replay state is retained only when the same adapter - * instance owns its historical provider and the target provider. Final - * adapter selection remains fixed through asynchronous exact-model resolution - * and dispatch. Selection, dispatch, and iteration failures retain their - * original Error identity and are tagged in a call-local scope for narrow - * agent-loop request recovery; middleware and nested-call failures remain - * untagged for the outer call. + * Stream one model call as raw chunks (token-level deltas). Replay state is + * retained only when the same adapter instance owns its historical provider + * and the target provider. Final adapter selection remains fixed through + * asynchronous exact-model resolution and dispatch. Adapter selection, + * dispatch, and iteration failures become terminal `error` or `aborted` + * finish chunks; middleware, nested-call, cleanup, and consumer failures + * remain thrown. * @param options - the full request; `options.provider` selects the adapter. * @returns the chunk stream, possibly wrapped by `llm/stream` listeners. */ @@ -1582,7 +1580,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) -Source: [`packages/core/session/src/index.ts:694`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:673`](../../packages/core/session/src/index.ts) ## `ctx.sessionTitle` — `SessionTitleService` @@ -2166,7 +2164,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession ``` -Source: [`packages/ui/tui/src/index.ts:247`](../../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:234`](../../packages/ui/tui/src/index.ts) ## `ctx.userInteraction` — `UserInteractionService` diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index 9f6970d88d..a0804e3991 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md -core.md: b9df539136c2661537775ba9a425bdf7ef1fd958 -core.zh.md: 1c75e8484dd1184077fe0194b2b6088230d1bbf5 +core.md: d837fc0977615a3afe307c56f5c97065af4a3a26 +core.zh.md: 797ec67ca0100cc44a088d453394c39cc1e343b0 diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index b9df539136..d837fc0977 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -414,46 +414,12 @@ The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, ` Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) -```ts type-equiv -/** - * Which inbox queue a {@link Agent.send} item joins: - * - `next-turn` — the item becomes its own turn, claimed at a turn boundary. - * - `next-step` — during prompt admission or an open turn, the item stages for - * the next safe step boundary; otherwise it is promoted per its `wakeup` - * flag. - */ -type SendTarget = 'next-turn' | 'next-step' -``` - ```ts type-equiv /** Resolved inbox placement reported when an accepted message is enqueued. */ type InboxPlacement = 'queued' | 'steering' ``` -```ts type-equiv -/** - * Options for the unified {@link Agent.send} primitive over the - * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup} - * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and - * {@link Agent.inject} (`next-step`/no-wakeup). - * - * The object is complete so routing policy is explicit. - */ -interface SendOptions { - /** Queue the item joins. */ - target: SendTarget - /** - * Whether this item makes the model run: wake a parked driver (`next-turn`) - * or force a continuation step (`next-step` while running). A `false` - * `next-turn` item queues without waking; a `false` - * `next-step` item attaches durable context without forcing another step - * (the injection preset). - */ - wakeup: boolean -} -``` - -The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable across that message's `agent/inbox/*` events without being returned by the delivery methods. Injection bypasses the FIFOs and never appears on those events. +The delivery methods accept an already identified `UserMessage` carrying role, content, and provenance. Its `MessageId` remains stable across that message's `agent/inbox/*` events without being returned by the delivery methods. Injection bypasses the FIFOs and never appears on those events. ```ts type-equiv /** Options for {@link Agent.cancel}. */ @@ -474,10 +440,10 @@ type AgentCancelCause = | { readonly kind: 'parent' } ``` -`Agent` is an interface over the public live-agent contract. Concrete drivers own the `followup`/`steer`/`inject` aliases and route them through `send`'s (`target` × `wakeup`) matrix. +`Agent` is an interface over the public live-agent contract. Concrete drivers implement `followup`, `steer`, and `inject`; routing policy remains private to the driver. ```ts type-equiv -/** Public live-agent handle with aliases over the unified delivery primitive. */ +/** Public live-agent handle. */ interface Agent { /** The single identity shared with {@link session}. */ readonly id: SessionId @@ -496,28 +462,6 @@ interface Agent { /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */ readonly ctx: Context - /** - * The unified delivery primitive over the (`target` × `wakeup`) matrix. - * It routes the caller's typed content and source as follows: - * - * - `next-turn` queues an item that becomes the sole ordinary message of its - * own FIFO-ordered turn; `wakeup:true` wakes a - * parked driver, while `wakeup:false` queues without waking. - * - `next-step` with `wakeup:true` stages steering during prompt admission - * or an open turn; outside that window it falls back to a woken - * `next-turn`. - * - `next-step` with `wakeup:false` injects durable model-facing context - * without running the model: admission or an open turn stages it for the - * next safe log position, while an injection outside that window appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside - * steering remains pending with it. - * The agent publishes or queues the identified frozen message as-is. - * @param message - identified model-facing content and its producer provenance. - * @param options - target queue and wakeup decision. - */ - send(message: UserMessage, options: SendOptions): void - /** * Clear queued and steering work — unless `keepInbox` — and abort the active * turn. An effective call first emits `agent/cancel-requested` with the @@ -533,16 +477,14 @@ interface Agent { whenIdle(): Promise /** - * Queue an ordinary follow-up turn and wake the driver — the - * `next-turn`/wakeup preset of {@link send}. The item becomes the sole - * ordinary message of its own turn. + * Queue an ordinary follow-up turn and wake the driver. The item becomes the + * sole ordinary message of its own turn. * @param message - identified prompt content and its producer provenance. */ followup(message: UserMessage): void /** - * Submit steering during prompt admission or an open turn — the - * `next-step`/wakeup preset of {@link send}. It stages for the next steering + * Submit steering during prompt admission or an open turn. It stages for the next steering * checkpoint before a request or stop decision. If the activity fails before * that boundary, the remainder stays staged without waking the agent; retry * or a later prompt takes it. Outside that window steering falls back to a diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 1c75e8484d..797ec67ca0 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -422,46 +422,12 @@ type SessionEvent = { 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) -```ts type-equiv -/** - * Which inbox queue a {@link Agent.send} item joins: - * - `next-turn` — the item becomes its own turn, claimed at a turn boundary. - * - `next-step` — during prompt admission or an open turn, the item stages for - * the next safe step boundary; otherwise it is promoted per its `wakeup` - * flag. - */ -type SendTarget = 'next-turn' | 'next-step' -``` - ```ts type-equiv /** Resolved inbox placement reported when an accepted message is enqueued. */ type InboxPlacement = 'queued' | 'steering' ``` -```ts type-equiv -/** - * Options for the unified {@link Agent.send} primitive over the - * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup} - * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and - * {@link Agent.inject} (`next-step`/no-wakeup). - * - * The object is complete so routing policy is explicit. - */ -interface SendOptions { - /** Queue the item joins. */ - target: SendTarget - /** - * Whether this item makes the model run: wake a parked driver (`next-turn`) - * or force a continuation step (`next-step` while running). A `false` - * `next-turn` item queues without waking; a `false` - * `next-step` item attaches durable context without forcing another step - * (the injection preset). - */ - wakeup: boolean -} -``` - -固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。投递方法不会返回其 `MessageId`，但该 id 在这条消息的各个 `agent/inbox/*` 事件中保持稳定。注入绕过两个 FIFO，从不出现在这些事件中。 +投递方法接收已有标识的 `UserMessage`，由它携带角色、内容与 provenance。投递方法不会返回其 `MessageId`，但该 id 在这条消息的各个 `agent/inbox/*` 事件中保持稳定。注入绕过两个 FIFO，从不出现在这些事件中。 ```ts type-equiv /** Options for {@link Agent.cancel}. */ @@ -482,10 +448,10 @@ type AgentCancelCause = | { readonly kind: 'parent' } ``` -`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器拥有 `followup`/`steer`/`inject` 别名方法，并将它们经由 `send` 的（`target` × `wakeup`）矩阵路由。 +`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器实现 `followup`、`steer` 和 `inject`；路由策略仍为驱动器私有。 ```ts type-equiv -/** Public live-agent handle with aliases over the unified delivery primitive. */ +/** Public live-agent handle. */ interface Agent { /** The single identity shared with {@link session}. */ readonly id: SessionId @@ -504,28 +470,6 @@ interface Agent { /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */ readonly ctx: Context - /** - * The unified delivery primitive over the (`target` × `wakeup`) matrix. - * It routes the caller's typed content and source as follows: - * - * - `next-turn` queues an item that becomes the sole ordinary message of its - * own FIFO-ordered turn; `wakeup:true` wakes a - * parked driver, while `wakeup:false` queues without waking. - * - `next-step` with `wakeup:true` stages steering during prompt admission - * or an open turn; outside that window it falls back to a woken - * `next-turn`. - * - `next-step` with `wakeup:false` injects durable model-facing context - * without running the model: admission or an open turn stages it for the - * next safe log position, while an injection outside that window appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside - * steering remains pending with it. - * The agent publishes or queues the identified frozen message as-is. - * @param message - identified model-facing content and its producer provenance. - * @param options - target queue and wakeup decision. - */ - send(message: UserMessage, options: SendOptions): void - /** * Clear queued and steering work — unless `keepInbox` — and abort the active * turn. An effective call first emits `agent/cancel-requested` with the @@ -541,16 +485,14 @@ interface Agent { whenIdle(): Promise /** - * Queue an ordinary follow-up turn and wake the driver — the - * `next-turn`/wakeup preset of {@link send}. The item becomes the sole - * ordinary message of its own turn. + * Queue an ordinary follow-up turn and wake the driver. The item becomes the + * sole ordinary message of its own turn. * @param message - identified prompt content and its producer provenance. */ followup(message: UserMessage): void /** - * Submit steering during prompt admission or an open turn — the - * `next-step`/wakeup preset of {@link send}. It stages for the next steering + * Submit steering during prompt admission or an open turn. It stages for the next steering * checkpoint before a request or stop decision. If the activity fails before * that boundary, the remainder stays staged without waking the agent; retry * or a later prompt takes it. Outside that window steering falls back to a diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml index 96c938a74f..448b386615 100644 --- a/docs/defensive-patterns.i18n.yaml +++ b/docs/defensive-patterns.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -defensive-patterns.md: c69094db461048f5dbca5f8bdd1fb5581b08a962 -defensive-patterns.zh.md: eb57f035ad0bd67e62e285d451502d41e4efc2bc +# pnpm run verify-translation-pairing --write docs/defensive-patterns.md +defensive-patterns.md: 4f256b2db6eee13af52c07e58a5d9d39d71694b8 +defensive-patterns.zh.md: 4e4c2cab645fcde71b969e1bda5e32b7fd472155 diff --git a/docs/defensive-patterns.md b/docs/defensive-patterns.md index c69094db46..4f256b2db6 100644 --- a/docs/defensive-patterns.md +++ b/docs/defensive-patterns.md @@ -10,7 +10,7 @@ A result can be several things at once — a process can time out AND exit 0 bec ## Honor cross-seam contracts on BOTH sides -When an interface documents two valid ways to signal something — an adapter may report failure by THROWING from `stream()` or by ending the stream with a `finish {kind:'error'|'aborted'}` chunk — the consumer handles both, not just the one the first implementation used. A library-backed adapter that can't throw mid-stream relies on the in-band path; a loop that only catches throws turns a provider 401 into a normal completed turn. Document the contract where the type is defined; exercise every branch through the real consumer. +When an implementation boundary receives several representations of one outcome, normalize them before crossing the public seam. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmService.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer. ## Async state is not synchronous state diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md index eb57f035ad..4e4c2cab64 100644 --- a/docs/defensive-patterns.zh.md +++ b/docs/defensive-patterns.zh.md @@ -10,7 +10,7 @@ ## 跨 seam 契约两侧都要遵守 -当一个接口文档记录了两种合法的信号方式时——例如适配器可以通过从 `stream()` 抛出异常来报告失败，也可以通过以 `finish {kind:'error'|'aborted'}` 分片结束流来报告——消费方必须同时处理两种路径，而不是只处理第一个实现恰好使用的那种。依赖库的适配器可能无法在流中途抛出异常，只能走带内路径；如果 agent loop（智能体循环）只捕获抛出的异常，就会把提供方的 401 错误变成一个正常完成的轮次。请在类型定义处记录契约；通过真实消费方测试每个分支。 +当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止 finish chunk 暴露模型请求失败；middleware 与消费方缺陷仍会抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化契约；通过真实消费方覆盖每种来源形式。 ## 异步状态不是同步状态 diff --git a/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts b/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts index 6c5c7a5404..a6802ae391 100644 --- a/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts +++ b/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts @@ -32,7 +32,7 @@ async function seedInterruptedSession(root: string, cwd: string): Promise { delegationDepth: 0, } const events: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 10, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } }, { type: 'user/message', seq: 1, time: 11, data: createUserMessage({ content: [{ type: 'text', text: 'Tighten this session to read-only.' }], source: { kind: 'user' } }), surfaceOp: 'append' }, { type: 'sandbox/mode', seq: 2, time: 12, data: { mode: 'read-only' } }, { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'completed' } } }, diff --git a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts index 7ae98167de..0e620bbbdd 100644 --- a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts +++ b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts @@ -53,7 +53,7 @@ async function seedResumeSession(cwd: string): Promise { const id = SessionId('resume-target') const meta: SessionHeader = { version: 0, id, createdAt: 1_700_000_000_000, cwd: sessionCwd } const events: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1_700_000_000_001, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1_700_000_000_001, data: { turn: 1 } }, { type: 'user/message', seq: 1, time: 1_700_000_000_002, data: createUserMessage({ content: [{ type: 'text', text: 'persisted prompt' }], source: { kind: 'user' }, }), surfaceOp: 'append' }, diff --git a/packages/acp/acp/src/codec.ts b/packages/acp/acp/src/codec.ts index 8d4693d9d5..bdfa44bba5 100644 --- a/packages/acp/acp/src/codec.ts +++ b/packages/acp/acp/src/codec.ts @@ -18,7 +18,6 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason { case 'max-tokens': return 'max_tokens' case 'aborted': - case 'disposed': case 'interrupted': return 'cancelled' case 'error': diff --git a/packages/acp/acp/tests/approval.spec.ts b/packages/acp/acp/tests/approval.spec.ts index 01bcd83249..ea1ec994a4 100644 --- a/packages/acp/acp/tests/approval.spec.ts +++ b/packages/acp/acp/tests/approval.spec.ts @@ -20,7 +20,7 @@ describe('ACP machine permission policy', () => { await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) const agent = harness.ctx.agents.get(SessionId(sessionId))! - agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + agent.session.append('turn/start', { turn: 1 }) return { agent, toolName: 'bash', callId: CallId('call-9'), ...overrides } } diff --git a/packages/acp/acp/tests/codec.spec.ts b/packages/acp/acp/tests/codec.spec.ts index 7f5441e4df..0136ae7a94 100644 --- a/packages/acp/acp/tests/codec.spec.ts +++ b/packages/acp/acp/tests/codec.spec.ts @@ -7,10 +7,9 @@ describe('ACP automation codec', () => { const cases: [TurnEndReason, string][] = [ [{ kind: 'completed' }, 'end_turn'], [{ kind: 'max-tokens' }, 'max_tokens'], - [{ kind: 'aborted' }, 'cancelled'], - [{ kind: 'disposed' }, 'cancelled'], + [{ kind: 'aborted', reason: { kind: 'user' } }, 'cancelled'], [{ kind: 'interrupted' }, 'cancelled'], - [{ kind: 'error', step: 1, message: 'boom' }, 'end_turn'], + [{ kind: 'error', error: new Error('boom') }, 'end_turn'], ] for (const [reason, expected] of cases) expect(turnEndToStopReason(reason)).toBe(expected) }) diff --git a/packages/acp/acp/tests/turns.spec.ts b/packages/acp/acp/tests/turns.spec.ts index db2234317b..867db15577 100644 --- a/packages/acp/acp/tests/turns.spec.ts +++ b/packages/acp/acp/tests/turns.spec.ts @@ -91,7 +91,7 @@ describe('ACP prompt lifecycle', () => { if (subject !== agent || message.source.kind !== 'user' || inserted) return inserted = true const source = { kind: 'plugin', plugin: 'test' } as const - agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source } }) + agent.session.append('turn/start', { turn: 1 }) agent.session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'autonomous work' }], source, diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts index be9ba79347..7ce14b075a 100644 --- a/packages/client/connection/src/client/fixture.ts +++ b/packages/client/connection/src/client/fixture.ts @@ -114,7 +114,7 @@ function buildAlphaLog(): SessionEvent[] { return seq } for (let turn = 0; turn < 60; turn++) { - push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }) + push({ type: 'turn/start', data: { turn } }) const userSeq = push({ type: 'user/message', surfaceOp: 'append', data: userMessage(text(turn === 59 ? USER_MARKDOWN_LITERAL : `问题 ${turn}：fixture 历史消息，用于翻页与渲染验收。`)), @@ -158,7 +158,7 @@ function buildAlphaLog(): SessionEvent[] { // stays presenter-less as the unknown fallback. const toolTurn = (turn: number, name: string, args: string, resultText: string): void => { const callId = `fx-call-${turn}` - push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }) + push({ type: 'turn/start', data: { turn } }) push({ type: 'user/message', surfaceOp: 'append', data: userMessage(text(`问题 ${turn}：${name} 样本。`)) }) push({ type: 'step/start', data: { turn, step: 0 } }) push({ @@ -186,7 +186,7 @@ function buildAlphaLog(): SessionEvent[] { + 'await tools.read({ path: "notes/missing.txt" }).catch(() => "tolerated")\n' + 'return { listing, demo }' const args = JSON.stringify({ code: program, description: 'Read the notes files and summarize' }) - push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }) + push({ type: 'turn/start', data: { turn } }) push({ type: 'user/message', surfaceOp: 'append', data: userMessage(text(`问题 ${turn}：run_code 样本。`)) }) push({ type: 'step/start', data: { turn, step: 0 } }) push({ @@ -975,7 +975,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy { const turn = nextTurn.get(id) ?? 0 nextTurn.set(id, turn + 1) setRunning(id, true) - append(id, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }) + append(id, { type: 'turn/start', data: { turn } }) // Boundary flush parallel (the host's agent/step seam): an outstanding // /plan selection commits as plan/mode inside the opened turn. const plan = foldPlan(logOf(id)) diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts index 77af4601ab..25a3393caa 100644 --- a/packages/client/runtime/src/client/sessions/session.ts +++ b/packages/client/runtime/src/client/sessions/session.ts @@ -1,6 +1,7 @@ // Sessions remain resident after creation so they continue consuming mux frames off-screen. import type { Context } from 'cordis' +import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type { @@ -51,9 +52,8 @@ const QUEUE_PREVIEW_CHARS = 200 /** Internal inbox-mirror entry: the snapshot row plus the retirement-matching fields the frames carry. */ interface QueuedEntry { row: QueuedMessage - steering: boolean - /** JSON-serialized MessageSource (steering retirement matches by source, the host-mirror precedent). */ - sourceJson: string + /** Stable message identity used when an admitted message retires the row. */ + messageId: MessageId } /** Single-line queue-row preview: text blocks flattened, non-text as tags, capped by code point. */ @@ -370,8 +370,7 @@ export class Session implements SessionFace { const key = 'rpcId' in message.source ? String(message.source.rpcId) : `f:${rpcId}` this.queued.push({ row: { key, preview: queuePreviewOf(message.content) }, - steering: frame.steering, - sourceJson: JSON.stringify(message.source), + messageId: message.id, }) this.queueRev++ this.notifier.markDirty() @@ -598,21 +597,16 @@ export class Session implements SessionFace { } } - /** Consumption-event retirement, mirroring the host queuedMirror rules: a message-triggered - * turn/start claims the oldest non-steering entry; a steering/message drains the oldest - * steering entry with the same source (loop-authored steering matches nothing and drops none). */ + /** Retire the oldest queued occurrence of an admitted identified message. */ private retireQueued(event: SessionEvent): void { if (this.queued.length === 0) return - let index = -1 - if (event.type === 'turn/start') { - if (event.data.trigger.kind !== 'message') return - index = this.queued.findIndex(entry => !entry.steering) - } else if (event.type === 'steering/message') { - const source = JSON.stringify(event.data.message.source) - index = this.queued.findIndex(entry => entry.steering && entry.sourceJson === source) - } else { - return - } + const id = event.type === 'user/message' + ? event.data.id + : event.type === 'steering/message' + ? event.data.message.id + : undefined + if (id === undefined) return + const index = this.queued.findIndex(entry => entry.messageId === id) if (index < 0) return this.queued.splice(index, 1) this.queueRev++ diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts index 53f80e0e69..74897468d3 100644 --- a/packages/client/runtime/tests/event-script.ts +++ b/packages/client/runtime/tests/event-script.ts @@ -12,7 +12,7 @@ const at = (seq: number, e: Record): SessionEvent => export const ev = { turnStart: (seq: number, turn: number): SessionEvent => - at(seq, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }), + at(seq, { type: 'turn/start', data: { turn } }), user: (seq: number, body: string): SessionEvent => at(seq, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({ content: text(body), source: { kind: 'user' }, diff --git a/packages/client/runtime/tests/queue-store.spec.ts b/packages/client/runtime/tests/queue-store.spec.ts index 7a734ef393..5f221b7e87 100644 --- a/packages/client/runtime/tests/queue-store.spec.ts +++ b/packages/client/runtime/tests/queue-store.spec.ts @@ -1,6 +1,6 @@ /** * Queue mirror semantics (web input-triggers queue cut 1): session/queued - * intake, host-rule retirement (message turn/start claims oldest non-steering; + * intake, host-rule retirement (identified user/message claims its non-steering row; * steering/message drains by source), leave-running sweep, reconnect reset, * pre-instantiation buffering, and snapshot reference stability. */ @@ -18,7 +18,11 @@ const text = (t: string): ContentBlock[] => [{ type: 'text', text: t }] const rid = (id: string): RpcId => id as RpcId /** session/queued frame with the wire-sourced rpcId key (the host prompt path). */ -function queuedFrame(body: string, rpcId: string, steering = false): MuxFrame { +function queuedFrame( + body: string, + rpcId: string, + steering = false, +): Extract { return { type: 'session/queued', sessionId: SID, @@ -74,22 +78,30 @@ describe('queue intake', () => { }) describe('queue retirement (host queuedMirror rules)', () => { - it('a message-triggered turn/start claims the oldest non-steering row', () => { + it('an admitted user/message claims its identified non-steering row', () => { const session = makeSession() - session.handleMuxEnvelope(rid('e1'), queuedFrame('先', 'p-1')) + const first = queuedFrame('先', 'p-1') + session.handleMuxEnvelope(rid('e1'), first) session.handleMuxEnvelope(rid('e2'), queuedFrame('后', 'p-2')) - session.handleMuxEnvelope(rid('e3'), { type: 'session/event', sessionId: SID, event: ev.turnStart(0, 0) }) + session.handleMuxEnvelope(rid('e3'), { + type: 'session/event', + sessionId: SID, + event: { + ...ev.user(0, '先'), + data: first.message, + }, + }) expect(session.getSnapshot().queue.map(r => r.key)).toEqual(['p-2']) }) - it('an injection-triggered turn/start claims nothing', () => { + it('a turn/start alone claims nothing', () => { const session = makeSession() session.handleMuxEnvelope(rid('e1'), queuedFrame('留', 'p-1')) - const injection = { - ...ev.turnStart(0, 0), - data: { turn: 0, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'x' } } }, - } as never - session.handleMuxEnvelope(rid('e2'), { type: 'session/event', sessionId: SID, event: injection }) + session.handleMuxEnvelope(rid('e2'), { + type: 'session/event', + sessionId: SID, + event: ev.turnStart(0, 0), + }) expect(session.getSnapshot().queue).toHaveLength(1) }) diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts index 4d417fb78e..ffdb1bbf33 100644 --- a/packages/compact/compact-basic/src/index.ts +++ b/packages/compact/compact-basic/src/index.ts @@ -155,8 +155,8 @@ export class BasicCompactService extends CompactService { } }) - ctx.on('agent/settled', (agent) => { - this.overflowRetries.delete(agent) + ctx.on('agent/status', (agent, status) => { + if (status === 'idle') this.overflowRetries.delete(agent) }) // A successful response starts a fresh overflow-recovery sequence even @@ -169,15 +169,11 @@ export class BasicCompactService extends CompactService { ctx.on('agent/request-error', async ( agent, - _turn, - _step, - _error, - failure, - _priorFailures, - _retryPolicy, + context, signal, next, ) => { + const { failure } = context if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next() this.overflowAgents.set(agent.session, agent) const target = routedTarget(agent.session) diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index a368a3631d..332b76ef08 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -104,7 +104,7 @@ function promptInput(text: string): SummarizationInput { function conversation(turns = 4, text = 'fixture '.repeat(40).trim()): Session { const session = new Session(SessionId(`conversation-${turns}`)) for (let turn = 1; turn <= turns; turn += 1) { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `${text} user ${turn}` }], source: { kind: 'user' }, @@ -133,7 +133,6 @@ function conversation(turns = 4, text = 'fixture '.repeat(40).trim()): Session { } session.append('turn/start', { turn: turns + 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) return session } @@ -142,7 +141,7 @@ function toolConversation(): Session { const session = new Session(SessionId('tools')) for (let turn = 1; turn <= 3; turn += 1) { const callId = CallId(`call-${turn}`) - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `request ${turn} `.repeat(300) }], source: { kind: 'user' }, @@ -182,7 +181,7 @@ function toolConversation(): Session { session.append('step/end', { turn, step: 1 }) session.append('turn/end', { turn, reason: { kind: 'completed' } }) } - session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 4 }) return session } @@ -190,7 +189,7 @@ function toolConversation(): Session { function oversizedToolResult(chars = 3_000, withCompactablePrompt = false): Session { const session = new Session(SessionId(`oversized-tool-${chars}`)) const callId = CallId('oversized') - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) if (withCompactablePrompt) { session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'older history '.repeat(200) }], @@ -227,7 +226,7 @@ function oversizedToolResult(chars = 3_000, withCompactablePrompt = false): Sess }, { surfaceOp: 'append' }) session.append('step/end', { turn: 1, step: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 2 }) return session } @@ -474,7 +473,7 @@ describe('pressure measurement and retention', () => { it('skips when no durable routed model exists instead of using AgentOptions fallback', async () => { const compact = service(compactConfig) const session = new Session(SessionId('headerless')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await expect(compact.compactIfNeeded(agent(session, MODEL), 'pressure', SIGNAL)) .resolves.toBeNull() expect(compact.calls).toHaveLength(0) @@ -557,7 +556,7 @@ describe('pressure measurement and retention', () => { const compact = service(compactConfig) const session = new Session(SessionId('single-tool-pair')) const callId = CallId('single-call') - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('request/header', { header: { config: { provider: MODEL, model: MODEL } }, @@ -647,7 +646,7 @@ describe('pressure measurement and retention', () => { it('declines when envelope pressure is high but the surface has no compactable range', async () => { const compact = service(compactConfig) const empty = new Session(SessionId('empty')) - empty.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + empty.append('turn/start', { turn: 1 }) empty.append('request/header', { header: { config: { provider: MODEL, model: MODEL }, system: 'x'.repeat(100_000) }, reason: 'initial', @@ -723,7 +722,7 @@ describe('pressure measurement and retention', () => { const ctx = createContext() const session = new Session(SessionId('one-tool-pair')) const callId = CallId('only') - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('assistant/message', { turn: 1, @@ -1058,7 +1057,7 @@ describe('compaction region transaction', () => { it('lets a model-independent custom summarizer compact without a conversation model', async () => { const compact = service() const session = new Session(SessionId('model-less-region')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'history '.repeat(100) }], source: { kind: 'user' }, @@ -1665,7 +1664,6 @@ describe('automatic listener and loader composition', () => { const session = new Session(SessionId('headerless-overflow')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) await expect(recover(ctx, agent(session, MODEL), overflow())).resolves.toBe(false) diff --git a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts index 4e9c24f667..84f51375b3 100644 --- a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts +++ b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts @@ -190,7 +190,6 @@ function overflowHistorySeed(): SessionEvent[] { const sentinel = turn === 1 ? 'OLD HISTORY SENTINEL' : 'RECENT HISTORY' session.append('turn/start', { turn, - trigger: { kind: 'message', source: { kind: 'user' } }, }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `${sentinel} ${'old context '.repeat(200)}` }], diff --git a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts index aa8997179e..bd347e6d1e 100644 --- a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts +++ b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts @@ -38,7 +38,6 @@ function appendToolStep( const callId = CallId(call) session.append('turn/start', { turn, - trigger: { kind: 'message', source: { kind: 'user' } }, }) session.append('step/start', { turn, step: 1 }) session.append('assistant/message', { @@ -165,7 +164,6 @@ describe('ToolResultPruneService session transaction', () => { }) session.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const result = service().pruneSession(session) @@ -214,7 +212,6 @@ describe('ToolResultPruneService session transaction', () => { appendToolStep(session, 3, 'c', [{ type: 'text', text: 'C'.repeat(80) }]) session.append('turn/start', { turn: 4, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const prune = service() const first = prune.pruneSession(session) @@ -231,7 +228,6 @@ describe('ToolResultPruneService session transaction', () => { appendToolStep(session, 1, 'a', [{ type: 'text', text: 'A'.repeat(100) }]) session.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, }) service().pruneSession(session) const replay = new Session(session.id, [...session.events]) @@ -250,7 +246,6 @@ describe('ToolResultPruneService session transaction', () => { expect(() => prune.pruneSession(session)).toThrow(/outside any open turn/) session.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, }) expect(() => prune.pruneSession(session)).not.toThrow() }) diff --git a/packages/compact/compact/tests/invariant.spec.ts b/packages/compact/compact/tests/invariant.spec.ts index f5fc5c87c7..b4f6d258ba 100644 --- a/packages/compact/compact/tests/invariant.spec.ts +++ b/packages/compact/compact/tests/invariant.spec.ts @@ -23,7 +23,7 @@ const summary = (overrides: Record = {}) => ({ }) function startTurn(session: ReturnType, turn = 1): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) } describe('compaction invariants', () => { @@ -45,7 +45,7 @@ describe('compaction invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('compact/start', { turn: 1 }) await ctx.plugin(InvariantService) await ctx.plugin(CompactInvariant) @@ -59,7 +59,7 @@ describe('compaction invariants', () => { expect(() => { ctx.emit('session/event', session, { type: 'turn/start', seq: 0, time: 0, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }) ctx.emit('session/event', session, { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 }, diff --git a/packages/context/time-context/tests/invariant.spec.ts b/packages/context/time-context/tests/invariant.spec.ts index 59daf23904..f117df5081 100644 --- a/packages/context/time-context/tests/invariant.spec.ts +++ b/packages/context/time-context/tests/invariant.spec.ts @@ -46,10 +46,10 @@ function reading( function preparing(turn: number, step: number): Session { const session = new Session(SessionId(`time-invariant-${turn}-${step}`)) for (let priorTurn = 1; priorTurn < turn; priorTurn += 1) { - session.append('turn/start', { turn: priorTurn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: priorTurn }) session.append('turn/end', { turn: priorTurn, reason: { kind: 'completed' } }) } - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `turn ${turn}` }], source: { kind: 'user' }, @@ -87,7 +87,7 @@ describe('time-context invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('time-invariant-late-valid')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'prepare' }], source: { kind: 'user' }, @@ -103,7 +103,7 @@ describe('time-context invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('time-invariant-late-invalid')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'prepare' }], source: { kind: 'user' }, @@ -125,7 +125,7 @@ describe('time-context invariants', () => { it('rejects a reading after cancellation closes the turn', async () => { const ctx = await setup() const session = preparing(1, 2) - session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) + session.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: { kind: 'user' } } }) expect(() => { ctx.emit('session/event', session, event(reading('1', '2', 'step context'))) }) .toThrow(/inside an open turn/) }) @@ -180,7 +180,7 @@ describe('time-context invariants', () => { expect(() => { ctx.emit('session/event', preparing(1, 1), user) }).not.toThrow() expect(() => { ctx.emit('session/event', preparing(1, 1), { - type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + type: 'turn/start', seq: 0, time: 0, data: { turn: 1 }, }) ctx.emit('tools/change') }).not.toThrow() diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts index ef2abf1a45..9e6efb032b 100644 --- a/packages/context/time-context/tests/time-context.spec.ts +++ b/packages/context/time-context/tests/time-context.spec.ts @@ -48,14 +48,13 @@ function sessionAgent(session: Session, id = 'agent'): Agent { inject(input) { session.append('user/message', input, { surfaceOp: 'append' }) }, - send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } function openMessageTurn(session: Session, turn: number): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `turn ${turn}` }], source: { kind: 'user' }, @@ -159,7 +158,7 @@ describe('durable step context', () => { it('reports an unavailable first-step baseline when no model-visible message precedes it', async () => { const { ctx } = await mount() const session = new Session(SessionId('unavailable')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await fire(ctx, sessionAgent(session), 1, 1) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index 3ff6b9b310..9b4089c146 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -183,7 +183,6 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent { inject(input) { session.append('user/message', input, { surfaceOp: 'append' }) }, - send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 629653d459..18c15fc605 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -412,7 +412,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: 'stream(options: GenerateOptions): AsyncIterable', - jsDoc: '/**\n * Stream one model call as raw chunks (token-level deltas). Throws\n * `LlmError` with code `NO_ADAPTER` if no adapter is registered for\n * `options.provider`. Replay state is retained only when the same adapter\n * instance owns its historical provider and the target provider. Final\n * adapter selection remains fixed through asynchronous exact-model resolution\n * and dispatch. Selection, dispatch, and iteration failures retain their\n * original Error identity and are tagged in a call-local scope for narrow\n * agent-loop request recovery; middleware and nested-call failures remain\n * untagged for the outer call.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */', + jsDoc: '/**\n * Stream one model call as raw chunks (token-level deltas). Replay state is\n * retained only when the same adapter instance owns its historical provider\n * and the target provider. Final adapter selection remains fixed through\n * asynchronous exact-model resolution and dispatch. Adapter selection,\n * dispatch, and iteration failures become terminal `error` or `aborted`\n * finish chunks; middleware, nested-call, cleanup, and consumer failures\n * remain thrown.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */', }, ], }, @@ -1073,13 +1073,6 @@ export const EVENT_API: readonly EventApiEntry[] = [ jsDoc: '/**\n * A declarative agent entry failed before it could publish a live agent.\n * Consumers that buffer work for the configured identity use this\n * transient signal to reject that work instead of waiting forever. Normal\n * factory teardown suppresses failures from the cancelled startup attempt.\n * @param sessionId - exact shared agent/session identity that failed startup.\n * @param error - persistence, setup, or publication failure.\n * @mode emit\n */', summary: 'A declarative agent entry failed before it could publish a live agent.', }, - { - name: 'agent/cancel-requested', - mode: 'emit', - signature: '\'agent/cancel-requested\'(this: Scoped, agent: Agent, cause: AgentCancelCause): void', - jsDoc: '/**\n * Effective broad cancellation was requested, before queued/outbox work\n * is cleared or the active turn is aborted. This observe-only notification\n * cannot veto cancellation; listener failures are contained.\n * @param agent - the agent whose current work is being cancelled.\n * @param cause - the explicit typed cancellation cause.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted.', - }, { name: 'agent/created', mode: 'emit', @@ -1102,32 +1095,25 @@ export const EVENT_API: readonly EventApiEntry[] = [ summary: 'A step or turn errored.', }, { - name: 'agent/inbox/dequeue', + name: 'agent/inbox/admitted', mode: 'emit', - signature: '\'agent/inbox/dequeue\'( this: Scoped, agent: Agent, message: UserMessage, placement: InboxPlacement, ): void', - jsDoc: '/**\n * The driver claimed one item out of the inbox: a queued item at a turn\n * boundary, or steering drained between steps. Fires after the item leaves\n * its FIFO and before it becomes a durable message.\n * @param agent - the agent whose inbox item was claimed.\n * @param message - the claimed message.\n * @param placement - the FIFO that claimed this occurrence; together with\n * `message.id`, it matches the earliest outstanding enqueue in that FIFO.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps.', + signature: '\'agent/inbox/admitted\'(this: Scoped, agent: Agent, message: UserMessage): void', + jsDoc: '/**\n * The driver admitted one inbox item for model-visible history.\n * @param agent - the agent whose inbox item was claimed.\n * @param message - the admitted message.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', + summary: 'The driver admitted one inbox item for model-visible history.', }, { - name: 'agent/inbox/discard', + name: 'agent/inbox/canceled', mode: 'emit', - signature: '\'agent/inbox/discard\'(this: Scoped, agent: Agent, messages: UserMessage[]): void', - jsDoc: '/**\n * Pending inbox items were dropped without delivering them, so every\n * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR\n * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,\n * emits this after `agent/cancel-requested` when applicable and before\n * aborting the active work. Fires once per drop with every dropped item.\n * @param agent - the agent whose inbox items were dropped.\n * @param messages - the discarded messages in FIFO order (queued then steering); never empty.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`.', - }, - { - name: 'agent/inbox/enqueue', - mode: 'emit', - signature: '\'agent/inbox/enqueue\'(this: Scoped, agent: Agent, message: UserMessage, placement: InboxPlacement): void', - jsDoc: '/**\n * An item entered the queued or steering inbox. `placement` is the\n * acceptance-time routing result; listeners must not reconstruct it from\n * later agent or session state.\n * @param agent - the owning agent.\n * @param message - accepted content, source, and correlation identity.\n * @param placement - resolved queued or steering placement.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'An item entered the queued or steering inbox.', + signature: '\'agent/inbox/canceled\'(this: Scoped, agent: Agent, message: UserMessage): void', + jsDoc: '/**\n * One pending inbox item was dropped without entering model-visible\n * history. `cancel()` without `keepInbox`, including disposal, emits this\n * once for each dropped item before aborting active work.\n * @param agent - the agent whose inbox items were dropped.\n * @param message - the dropped message.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', + summary: 'One pending inbox item was dropped without entering model-visible history.', }, { name: 'agent/prompt-submit', mode: 'waterfall', - signature: '\'agent/prompt-submit\'(this: Scoped, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise): Promise', - jsDoc: '/**\n * Allow, rewrite, or block one claimed prompt before it becomes a user\n * message or opens a turn. Call `next()` for the unchanged default. The\n * signal controls only this admission attempt; listeners may cooperate with\n * it but must not retain it for a later attempt or turn.\n * @param agent - the agent whose turn claimed the message.\n * @param message - the frozen claimed message, including identity and source.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', - summary: 'Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn.', + signature: '\'agent/prompt-submit\'(this: Scoped, agent: Agent, messages: UserMessage[], signal: AbortSignal, next: () => Promise): Promise', + jsDoc: '/**\n * Allow, rewrite, or block one claimed inbox batch before it becomes\n * model-visible or opens a turn. Call `next()` for the unchanged default. The\n * signal controls only this admission attempt; listeners may cooperate with\n * it but must not retain it for a later attempt or turn.\n * @param agent - the agent whose driver claimed the batch.\n * @param messages - the claimed messages.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', + summary: 'Allow, rewrite, or block one claimed inbox batch before it becomes model-visible or opens a turn.', }, { name: 'agent/request', @@ -1139,9 +1125,9 @@ export const EVENT_API: readonly EventApiEntry[] = [ { name: 'agent/request-error', mode: 'waterfall', - signature: '\'agent/request-error\'(this: Scoped, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise): Promise', - jsDoc: '/**\n * Handle a model-request failure after its failed step has closed but\n * before the failed turn closes. A listener returns `{ kind: \'retry\' }`\n * without calling `next()` when it owns the error, or calls `next()` to\n * delegate. The default `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param turn - the open turn number.\n * @param step - the failed step number.\n * @param error - the original model-request failure.\n * @param failure - serializable facts normalized at the final adapter boundary.\n * @param priorFailures - immutable failures that already authorized another\n * retry turn in this consecutive sequence.\n * @param retryPolicy - immutable policy of the adapter registration that served\n * the failed request, or `undefined` if no final adapter served it.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', - summary: 'Handle a model-request failure after its failed step has closed but before the failed turn closes.', + signature: '\'agent/request-error\'(this: Scoped, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise): Promise', + jsDoc: '/**\n * Handle one failed model-request attempt before the loop retries or closes\n * its step. A listener returns `{ kind: \'retry\' }` without calling `next()`\n * when it owns recovery, or calls `next()` to delegate. The default\n * `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param context - request coordinates, provider, normalized failure, and serving policy.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', + summary: 'Handle one failed model-request attempt before the loop retries or closes its step.', }, { name: 'agent/session-start', @@ -1150,18 +1136,11 @@ export const EVENT_API: readonly EventApiEntry[] = [ jsDoc: '/**\n * The session lifecycle began, once before the first turn. Use\n * `agent.inject()` to seed model-facing context. This is a notification, not\n * a veto; disposal requested by a lifecycle owner is rechecked before the\n * driver starts.\n * @param agent - the agent whose session lifecycle began.\n * @param source - why the session started (fresh startup, resume, …).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', summary: 'The session lifecycle began, once before the first turn.', }, - { - name: 'agent/settled', - mode: 'emit', - signature: '\'agent/settled\'(this: Scoped, agent: Agent, turn: number, reason: SettleReason): void', - jsDoc: '/**\n * One drain chain reached its terminal turn: that turn\'s `turn/end` is\n * already committed. Automatically recovered failed turns do not emit this\n * notification, and neither does a run that aborts or fails before its\n * `turn/start` commits — there is no durable turn to settle against.\n * `reason` says why; model-request recovery is exhausted when an error\n * reaches it.\n * @param agent - the agent whose turn closed.\n * @param turn - the terminal turn number.\n * @param reason - why the terminal turn ended, with live error facts when it failed.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'One drain chain reached its terminal turn: that turn\'s `turn/end` is already committed.', - }, { name: 'agent/status', mode: 'emit', signature: '\'agent/status\'(this: Scoped, agent: Agent, status: AgentStatus): void', - jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`). `send()` does not enter\n * `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', + jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`). A waking delivery enters\n * `running` synchronously after reserving cancellation; `idle` means no\n * driver remains scheduled or active.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', summary: 'Agent status changed (`idle` ⇄ `running`).', }, { @@ -1429,11 +1408,11 @@ export const EVENT_API: readonly EventApiEntry[] = [ export const TYPE_API: readonly TypeApiEntry[] = [ { name: 'Agent', - declaration: 'export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly acceptsNextStep: boolean;\n readonly ctx: Context;\n send(message: UserMessage, options: SendOptions): void;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n}', + declaration: 'export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly ctx: Context;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n}', }, { name: 'AgentCancelCause', - declaration: 'export type AgentCancelCause = {\n readonly kind: \'user\';\n} | {\n readonly kind: \'parent\';\n};', + declaration: 'export type AgentCancelCause = {\n readonly kind: \'user\';\n} | {\n readonly kind: \'parent\';\n} | {\n readonly kind: \'hook\';\n readonly reason: string;\n} | {\n readonly kind: \'disposed\';\n};', }, { name: 'AgentFactory', @@ -1549,7 +1528,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'CancelOptions', - declaration: 'export interface CancelOptions {\n keepInbox?: boolean;\n}', + declaration: 'export interface CancelOptions {\n keepInbox?: boolean | undefined;\n}', }, { name: 'CodeBindingErrorClass', @@ -1917,7 +1896,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'PreparedLlmCall', - declaration: 'export interface PreparedLlmCall {\n readonly config: LlmCallConfig;\n stream(options: GenerateOptions): AsyncIterable;\n}', + declaration: 'export interface PreparedLlmCall {\n readonly config: LlmCallConfig;\n readonly retryPolicy: ResolvedRetryPolicy;\n stream(options: GenerateOptions): AsyncIterable;\n}', }, { name: 'PreparedReferencedMessage', @@ -2103,14 +2082,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ScopeKey', declaration: 'export type ScopeKey = object;', }, - { - name: 'SendOptions', - declaration: 'export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n}', - }, - { - name: 'SendTarget', - declaration: 'export type SendTarget = \'next-turn\' | \'next-step\';', - }, { name: 'Session', declaration: 'export class Session {\n get surface(): SessionSurface;\n readonly header: SessionHeader;\n get id(): SessionId;\n readonly firstLiveSeq: number;\n constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n get events(): readonly SessionEvent[];\n get seq(): number;\n append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n opts: SurfaceIntent\n ] : [\n ]): SessionEvent;\n requestHeader(): EpochHeader | undefined;\n deriveMessages(): Message[];\n deriveEventMessage(event: SessionEvent): Message | null;\n}', @@ -2125,7 +2096,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionEventMap', - declaration: 'export interface SessionEventMap {\n \'turn/start\': {\n turn: number;\n trigger: TurnTrigger;\n };\n \'turn/end\': {\n turn: number;\n reason: TurnEndReason;\n };\n \'step/start\': {\n turn: number;\n step: number;\n };\n \'step/end\': {\n turn: number;\n step: number;\n };\n \'user/message\': UserMessage;\n \'assistant/chunk\': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n \'assistant/message\': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n \'tool/call\': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n \'tool/result\': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n \'steering/message\': {\n turn: number;\n message: UserMessage;\n };\n \'todo/write\': {\n todos: TodoItem[];\n };\n \'request/header\': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n}', + declaration: 'export interface SessionEventMap {\n \'turn/start\': {\n turn: number;\n };\n \'turn/end\': {\n turn: number;\n reason: TurnEndReason;\n };\n \'step/start\': {\n turn: number;\n step: number;\n };\n \'step/end\': {\n turn: number;\n step: number;\n };\n \'user/message\': UserMessage;\n \'assistant/chunk\': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n \'assistant/message\': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n \'tool/call\': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n \'tool/result\': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n \'steering/message\': {\n turn: number;\n message: UserMessage;\n };\n \'todo/write\': {\n todos: TodoItem[];\n };\n \'request/header\': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n}', }, { name: 'SessionEventMetadataFilter', @@ -2645,15 +2616,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'TurnEndReasonMap', - declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n };\n error: {\n kind: \'error\';\n step: number;\n } & ({\n failure: LlmFailure;\n message?: never;\n code?: never;\n } | {\n message: string;\n code?: string;\n failure?: never;\n });\n disposed: {\n kind: \'disposed\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', - }, - { - name: 'TurnTrigger', - declaration: 'export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];', - }, - { - name: 'TurnTriggerMap', - declaration: 'export interface TurnTriggerMap {\n message: {\n kind: \'message\';\n source: MessageSource;\n };\n retry: {\n kind: \'retry\';\n };\n injection: {\n kind: \'injection\';\n source: MessageSource;\n };\n}', + declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n reason: AgentCancelCause;\n };\n error: {\n kind: \'error\';\n error: unknown;\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', }, { name: 'UserInteractionProvider', diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml index 75edc1357f..c11b692347 100644 --- a/packages/core/agent-loop/README.i18n.yaml +++ b/packages/core/agent-loop/README.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 packages/core/agent-loop/README.md -README.md: 6bb8b12af69f54c2a75cd672e4d3802887808c76 -README.zh.md: f9eb8aa3cdead427a88492e35c00eab80ba12f91 +README.md: 33e349f8945b45bf322171d4c02b9a940a68f2c2 +README.zh.md: 65a81ea82a02ea81bc3e0a8892fd23b281477df2 diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index 6bb8b12af6..33e349f894 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -55,7 +55,7 @@ Configured agents start automatically. A model call requires both `provider` and The concrete `ReactLoopAgent`, its queued input, outbox, and run controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy. -The unified `send()` primitive routes content and source by (`target` × `wakeup`); `followup`/`steer`/`inject` are its fixed-preset aliases. A `next-turn` item joins the queued FIFO, waking the driver unless `wakeup: false`; admission happens before any turn opens. The loop opens a private next-step acceptance window before `agent/prompt-submit` and closes it before `turn/end`. During that window, `steer()` and `inject()` stage in one outbox; an allowed admission opens the turn, records the prompt and returned `additionalContexts`, then drains the staged input before the first request. A blocked or failed admission writes no prompt or hook-produced context. A caller-staged context-only batch then takes idle injection's immediate append, while steering and context staged beside it remain pending for retry or a later admitted prompt. Outside the window, steering becomes a waking queued prompt and injection immediately appends `user/message` without opening a turn or running the model. Every inbox enqueue publishes `agent/inbox/enqueue` with the resolved queued-or-steering placement; taking it publishes `agent/inbox/dequeue` with the same placement, and `cancel()` without `keepInbox` publishes `agent/inbox/discard`. +The concrete driver routes `followup()`/`steer()`/`inject()` through one private `send()` primitive. A follow-up joins the queued FIFO and wakes the driver; admission happens before any turn opens. The loop opens a private next-step acceptance window before `agent/prompt-submit` and closes it before `turn/end`. During that window, `steer()` and `inject()` stage in one outbox; an allowed admission opens the turn, records the prompt and returned `additionalContexts`, then drains the staged input before the first request. A blocked or failed admission writes no prompt or hook-produced context. A caller-staged context-only batch then takes idle injection's immediate append, while steering and context staged beside it remain pending for retry or a later admitted prompt. Outside the window, steering becomes a waking queued prompt and injection immediately appends `user/message` without opening a turn or running the model. Every inbox enqueue publishes `agent/inbox/enqueue` with the resolved queued-or-steering placement; taking it publishes `agent/inbox/dequeue` with the same placement, and `cancel()` without `keepInbox` publishes `agent/inbox/discard`. ### Loop lifecycle (`agent.ts`) @@ -65,7 +65,7 @@ Every provider call that reaches a successful finish appends exactly one `assist After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate any adapter-owned reasoning effort and materialize its configured default under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The effective config is logged before dispatch, so a listener can change effort between steps without hidden request drift. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance restores the last effort only when its initial provider/model route exactly matches the logged route; a route change discards that opaque model-owned ID and resolves the new model independently. -Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter `agent/request-error`; middleware, result processing, tools, and other extension failures close directly. Recovery receives the exact live error, immutable provider facts, immutable prior failures, the immutable retry policy of the adapter registration that served the request, and the turn signal after the failed step closes; the policy is absent if no final adapter served it. A handling listener returns `{ kind: 'retry' }`; the loop closes the failed turn with its error and opens one numbered retry turn without an intervening idle notification. Success clears the consecutive history, and an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract. +Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract. Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, and retains their finalized result context without distinguishing the cancellation cause. diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md index f9eb8aa3cd..65a81ea82a 100644 --- a/packages/core/agent-loop/README.zh.md +++ b/packages/core/agent-loop/README.zh.md @@ -55,7 +55,7 @@ interface Config { 实体 `ReactLoopAgent`、其排队输入、outbox 与运行控制均为包内部实现。包根只导出插件／服务／配置契约，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个实体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。 -统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`next-turn` 项加入排队 FIFO，除非 `wakeup: false`，否则会唤醒驱动器；接纳发生在任何轮次开启之前。循环在 `agent/prompt-submit` 之前打开一个私有的 next-step 接收窗口，并在 `turn/end` 之前关闭它。在该窗口内，`steer()` 与 `inject()` 会暂存到同一个 outbox；接纳获准后会开启轮次，记录提示词及其返回的 `additionalContexts`，再于首次请求前排空暂存输入。接纳被阻止或失败时，不会写入提示词或钩子生成的上下文。之后，仅含调用方暂存上下文的批次会采用空闲注入的立即追加行为，而 steering（中途引导）及与其一同暂存的上下文则继续待处理，以供重试或之后获准的提示词使用。窗口之外，steering 会成为唤醒驱动器的排队提示词，而注入会立即追加 `user/message`，不开启轮次也不运行模型。每次 inbox 入队都会发布 `agent/inbox/enqueue`，并携带解析出的 queued 或 steering 路由归类；取走它会发布 `agent/inbox/dequeue`，并携带相同的路由归类；`cancel()` 在不带 `keepInbox` 时会发布 `agent/inbox/discard`。 +具体驱动器通过一个私有 `send()` 原语路由 `followup()`/`steer()`/`inject()`。后续消息加入排队 FIFO 并唤醒驱动器；接纳发生在任何轮次开启之前。循环在 `agent/prompt-submit` 之前打开一个私有的 next-step 接收窗口，并在 `turn/end` 之前关闭它。在该窗口内，`steer()` 与 `inject()` 会暂存到同一个 outbox；接纳获准后会开启轮次，记录提示词及其返回的 `additionalContexts`，再于首次请求前排空暂存输入。接纳被阻止或失败时，不会写入提示词或钩子生成的上下文。之后，仅含调用方暂存上下文的批次会采用空闲注入的立即追加行为，而 steering（中途引导）及与其一同暂存的上下文则继续待处理，以供重试或之后获准的提示词使用。窗口之外，steering 会成为唤醒驱动器的排队提示词，而注入会立即追加 `user/message`，不开启轮次也不运行模型。每次 inbox 入队都会发布 `agent/inbox/enqueue`，并携带解析出的 queued 或 steering 路由归类；取走它会发布 `agent/inbox/dequeue`，并携带相同的路由归类；`cancel()` 在不带 `keepInbox` 时会发布 `agent/inbox/discard`。 ### 循环生命周期（`agent.ts`） @@ -65,7 +65,7 @@ interface Config { 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的推理（reasoning）强度，并填入其配置默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。生效配置会在分派前写入日志，因此监听器可以在步骤之间更改推理强度，而不会产生未记录的请求变化。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例仅在初始提供方／模型路由与日志路由完全一致时恢复上次的推理强度；路由变化会丢弃由前一模型持有的不透明 ID，并单独解析新模型。 -插件失败会结束当前轮次，而不是结束循环。只有最终适配器分发／迭代失败以及带内的终止错误或中止结束才进入 `agent/request-error`；中间件、结果处理、工具及其他扩展失败会直接关闭轮次。失败步骤关闭后，恢复逻辑会接收确切的实时错误、不可变的提供方事实、不可变的先前失败、为请求提供服务的适配器注册所对应的不可变重试策略，以及轮次信号；如果没有最终适配器为其提供服务，则该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；循环用其错误关闭失败轮次，并在不插入空闲通知的情况下开启一个编号重试轮次。成功会清除连续失败历史；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。 +插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。 diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 949e9801c4..d42c2790d3 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -7,47 +7,41 @@ * @module dsh-agent-loop/agent */ -import type { Context } from 'cordis' -import { agentCarrier, assembleContextFor, emitAgentEvent } from '@deepseek-ai/dsh-agent' -import { createScope } from '@deepseek-ai/dsh-scope' -import type { Scope } from '@deepseek-ai/dsh-scope' import type { Agent, - CancelOptions, - AgentInterruptReason, - InboxPlacement, + AgentCancelCause, AgentOptions, AgentStatus, - SettleReason, - PromptDecision, - RequestError, + CancelOptions, RequestErrorAction, - SendOptions, } from '@deepseek-ai/dsh-agent' +import { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from '@deepseek-ai/dsh-agent' +import type { GenerateOptions, LlmCallConfig, Message, PreparedLlmCall } from '@deepseek-ai/dsh-llm' import { BlockAssembler, LlmError, - assertNever, createAssistantMessage, deepFreeze, errorChain, - freezeMessage, - isHarnessError, - llmFailureOf, - llmRetryPolicyOf, markAgentLoopRequest, } from '@deepseek-ai/dsh-llm' -import type { GenerateOptions, LlmCallConfig, LlmFailure, Message, PreparedLlmCall, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm' +import type { Scope } from '@deepseek-ai/dsh-scope' +import { createScope } from '@deepseek-ai/dsh-scope' +import type { AssistantMessage, Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session' import { canonicalHeader, headerEquals } from '@deepseek-ai/dsh-session' -import type { AssistantMessage, Session, SessionId, TurnEndReason, TurnTrigger, UserMessage } from '@deepseek-ai/dsh-session' import { renderPrompt } from '@deepseek-ai/dsh-system-prompt' -import type {} from '@deepseek-ai/dsh-tools' +import type { Context } from 'cordis' import { executeToolCalls } from './tool-calls.ts' -/** One completed step or a final-adapter failure eligible for recovery. */ -type StepOutcome = - | { kind: 'completed'; continueTurn: boolean; concluded: boolean; maxTokens: boolean } - | { kind: 'request-failed'; error: RequestError; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined } +type Phase = + | { kind: 'idle'; lastTurn: number } + | { kind: 'collecting'; abort: AbortController; lastTurn: number } + | { kind: 'running'; abort: AbortController; turn: number; step: number } + +type Admission = + | { kind: 'empty' } + | { kind: 'admitted'; claimed: UserMessage[]; messages: UserMessage[] } + | { kind: 'blocked' } /** * The concrete {@link Agent}: each `run()` owns one turn and repeats model @@ -55,31 +49,18 @@ type StepOutcome = */ export class ReactLoopAgent implements Agent { /** Prompts awaiting individual turns. */ - private queued: { message: UserMessage; wakeup: boolean }[] = [] + private queued: UserMessage[] = [] /** Input taken into the session log at step boundaries. */ - private outbox: { message: UserMessage; steering: boolean }[] = [] + private outbox: UserMessage[] = [] - /** Whether observers see a running interval; consecutive turns share it. */ - private busy = false - /** Whether an idle waking send has deferred driver admission. */ - private wakeScheduled = false - /** Whether next-step input belongs to the current admission or open turn. */ - acceptsNextStep = false - /** Abort owner for the current admission or turn. */ - private abort: AbortController | undefined - /** Resolves when the current admission and turn exit. */ - done: Promise = Promise.resolve() + private phase: Phase + private driverDone: Promise = Promise.resolve() - /** The agent-scoped registration boundary; the lifecycle owner unwinds it after {@link done}. */ + /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */ readonly scope: Scope /** The agent's scoped composition context ({@link Agent.ctx}). */ readonly ctx: Context - /** Last turn number opened by this loop or present in its seeded log. */ - private lastTurn: number - /** Whether the session log is owed a matching turn end event. */ - private turnOpen = false - private stepOpen = false /** Whether this loop instance has appended its initial/resume request anchor. */ private requestHeaderLogged = false @@ -89,474 +70,282 @@ export class ReactLoopAgent implements Agent { public readonly options: AgentOptions, public readonly session: Session, ) { - this.lastTurn = session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 0 + const lastTurn = session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 0 + this.phase = { kind: 'idle', lastTurn } this.scope = createScope(loopCtx, this) this.ctx = this.scope.ctx.extend({ agent: this }) } /** Last activity state published to observers. */ get status(): AgentStatus { - return this.busy ? 'running' : 'idle' + return this.phase.kind === 'idle' ? 'idle' : 'running' + } + + /** Commit a phase and publish its externally visible status transition. */ + private setPhase(next: Phase): void { + const previousStatus = this.status + this.phase = next + const status = this.status + if (status !== previousStatus) { + emitAgentEvent(this.loopCtx, this, 'agent/status', status) + } } /** Accept and route one unified send item. */ - send( - message: UserMessage, - options: SendOptions, - ): void { - const { target, wakeup } = options - if (target === 'next-step' && !wakeup) { - if (this.acceptsNextStep) { - this.outbox.push({ message, steering: false }) - return - } - this.session.append('user/message', message, { surfaceOp: 'append' }) - return + private send(message: UserMessage, target: 'next-turn' | 'next-step', wakeup: boolean): void { + this.session.append('agent/inbox/added', message) + // Waking input cannot join an aborted admission or turn, so it starts the next turn. + const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted + const inbox = target === 'next-turn' || wakingAfterAbort ? this.queued : this.outbox + inbox.push(message) + if (wakeup) { + this.scheduleKick() } - - const placement: InboxPlacement = target === 'next-step' && this.acceptsNextStep ? 'steering' : 'queued' - if (placement === 'steering') { - this.outbox.push({ message, steering: true }) - } else { - this.queued.push({ message, wakeup }) - } - // Preserve the routing decision for every send in this synchronous caller - // stack, while installing quiescence ownership before enqueue observers - // can cancel or dispose. - if (placement === 'queued' && wakeup) this.scheduleKick() - emitAgentEvent(this.loopCtx, this, 'agent/inbox/enqueue', message, placement) } /** Queue one ordinary prompt turn and wake the driver. */ followup(input: UserMessage): void { - this.send(input, { - target: 'next-turn', - wakeup: true, - }) + this.send(input, 'next-turn', true) } /** Steer the open turn, falling back to a waking prompt while idle. */ steer(input: UserMessage): void { - this.send(input, { - target: 'next-step', - wakeup: true, - }) + this.send(input, 'next-step', true) } /** Append model-facing context without waking the driver. */ inject(input: UserMessage): void { - this.send(input, { - target: 'next-step', - wakeup: false, - }) + this.send(input, 'next-step', false) } /** * Clear all pending work and abort the active turn; the first cause wins. * The cause is signal payload for observers and the durable turn/end * classification — it selects no machine behavior. Teardown is just - * `cancel({kind:'disposed'})` + await {@link done} + {@link scope} dispose, - * all owned by the factory. + * `cancel({kind:'disposed'})` + driver join + {@link scope} dispose, all + * owned by the factory. */ - cancel(cause: AgentInterruptReason, options: CancelOptions = {}): void { - // Effective only when it aborts the active turn or actually discards - // pending work: a keepInbox call with no active turn is a documented - // no-op, so it must not emit cancel-requested for consumers to misread. - const discards = !options.keepInbox && (this.queued.length > 0 || this.outbox.length > 0) - if (this.abort !== undefined || discards) { - // Observe-only: coordination consumers update their state before the - // inboxes clear; listener failures are contained by the dispatcher. - if (cause.kind !== 'disposed') emitAgentEvent(this.loopCtx, this, 'agent/cancel-requested', cause) - } + cancel(cause: AgentCancelCause, options: CancelOptions = {}): void { if (!options.keepInbox) { - const discarded = this.queued.map(item => item.message) - for (const item of this.outbox) { - if (item.steering) discarded.push(item.message) + for (const message of [...this.outbox.splice(0), ...this.queued.splice(0)]) { + emitAgentEvent(this.loopCtx, this, 'agent/inbox/canceled', message) } - // Clear before abort observers run: replacement work belongs to the next turn. - this.queued.length = 0 - this.outbox.length = 0 - if (discarded.length > 0) emitAgentEvent(this.loopCtx, this, 'agent/inbox/discard', discarded) } - const reason = Object.freeze({ kind: cause.kind }) - this.abort?.abort(reason) - } - - /** Resolve at idle quiescence: no run driving and no waking prompt waiting. */ - async whenIdle(): Promise { - // `done` is replaced per activity, so re-reading it follows chained turns. - // Every driver failure today is contained before it can reject `done`, - // but the waiter must not gamble quiescence on that: a future escape - // still counts as settled activity. - /* v8 ignore next 3 -- the catch arm backstops rejection paths that are all currently contained */ - while (this.busy || this.wakeScheduled || this.abort !== undefined || this.queued.some(item => item.wakeup)) { - await this.done.catch(() => undefined) + if (this.phase.kind !== 'idle') { + this.phase.abort.abort(cause) } } - /** Defer idle admission while keeping {@link done} as its quiescence owner. */ + /** Reserve a driver before deferring idle admission. */ private scheduleKick(): void { - if (this.abort !== undefined || this.wakeScheduled) return - this.wakeScheduled = true - const pending = Promise.withResolvers() - const scheduled = pending.promise + if (this.phase.kind !== 'idle') return + const driver = Promise.withResolvers() + this.driverDone = driver.promise + this.setPhase({ kind: 'collecting', abort: new AbortController(), lastTurn: this.phase.lastTurn }) queueMicrotask(() => { - this.wakeScheduled = false - this.kick() - const activity = this.done - if (activity === scheduled) { - pending.resolve() - } else { - void activity.then( - () => { pending.resolve() }, - () => { pending.resolve() }, - ) - } + this.loopCtx.agents.withInitiator(this, () => this.kick()).then(driver.resolve, driver.reject) }) - this.done = scheduled + } + + /** Resolve after the current driver and synchronous replacement chain exits. */ + async whenIdle(): Promise { + let driver: Promise + do { + await (driver = this.driverDone) + } while (driver !== this.driverDone) + } + + private async kick(): Promise { + try { + while (await this.turn()) {} + } catch (error: unknown) { + if (this.phase.kind !== 'idle') { + const turn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn + this.setPhase({ kind: 'idle', lastTurn: turn }) + emitAgentEvent(this.loopCtx, this, 'agent/error', turn, 0, error) + } + } finally { + if (this.phase.kind === 'running') { + this.setPhase({ kind: 'idle', lastTurn: this.phase.turn }) + } + } } /** Claim and admit the next queued prompt, then start its turn. */ - private kick(): void { - if (this.abort !== undefined || !this.queued.some(item => item.wakeup)) return - // The some() guard above proves the queue is non-empty; the non-null - // assertion expresses that invariant. - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - const { message } = this.queued.shift()! - const inheritedOutboxLength = this.outbox.length - - const admission = new AbortController() - this.abort = admission - this.acceptsNextStep = true - // Claimed admission is part of the running interval: it is cancellable - // activity, so observers (and their cancel routing) must see it. - if (!this.busy) { - this.busy = true - emitAgentEvent(this.loopCtx, this, 'agent/status', 'running') + private async admit(onTurnBoundary: boolean): Promise { + if (this.phase.kind !== 'running') throw new Error() + const signal = this.phase.abort.signal + const claimed = this.outbox.slice() + const outboxLength = this.outbox.length + const queued = onTurnBoundary ? this.queued[0] : undefined + if (queued !== undefined) claimed.push(queued) + if (claimed.length === 0) return { kind: 'empty' } + const decision = await agentEvents(this.loopCtx, this).waterfall( + 'agent/prompt-submit', claimed, signal, + () => Promise.resolve({ kind: 'allow', messages: claimed }), + ) + signal.throwIfAborted() + if (decision.kind === 'allow') { + this.outbox.splice(0, outboxLength) + if (queued !== undefined) this.queued.shift() + return { kind: 'admitted', claimed, messages: decision.messages } + } else { + this.cancel({ kind: 'hook', reason: decision.reason }, { keepInbox: decision.keepInbox }) + return { kind: 'blocked' } } - // The admission body runs synchronously up to the prompt-submit - // waterfall's first await, so the waterfall snapshots its listeners - // before a disposal initiated by the running-status emit above can - // unregister a vetoing plugin. - this.done = this.loopCtx.agents.withInitiator(this, async () => { - const signal = admission.signal - const trigger: TurnTrigger = { kind: 'message', source: message.source } - // Admitted input stays on the stack until its turn/start commits: the - // turn owns it only once the turn exists in the log. - let admitted: UserMessage[] | undefined - try { - signal.throwIfAborted() - const decision = await this.loopCtx.waterfall( - agentCarrier(this), 'agent/prompt-submit', this, message, signal, - () => Promise.resolve({ kind: 'allow' }), - ) - signal.throwIfAborted() - - if (decision.kind === 'allow') { - admitted = [decision.content === undefined - ? message - : freezeMessage({ ...message, content: decision.content })] - for (const context of decision.additionalContexts ?? []) { - admitted.push(freezeMessage(context)) - } - } - } catch (error: unknown) { - if (!signal.aborted) { - this.loopCtx.logger.warn(`agent "${this.id}": prompt admission failed: ${errorChain(error)}`) - } - } - - // cancel() aborts but never clears the slot, and kick()/run() - // all refuse to install a new owner while one exists, so the admission - // still owns the slot here and releasing it unconditionally is exact. - this.abort = undefined - if (admitted === undefined) { - this.acceptsNextStep = false - try { - this.flushRejectedAdmissionContexts() - } catch (error: unknown) { - // No turn exists for agent/error coordinates. Preserve the - // uncommitted suffix for a later boundary and report locally. - this.loopCtx.logger.warn( - `agent "${this.id}": committing rejected-admission context failed: ${errorChain(error)}`, - ) - } - // A synchronously aborted admission would otherwise publish idle - // inside send()'s own synchronous extent, before any post-send - // subscriber could observe the transition. - await Promise.resolve() - this.continueOrIdle() - return - } - await this.run(trigger, admitted, inheritedOutboxLength) - }) - // Published only after the abort owner and pending done are installed: a - // dequeue listener that cancels or disposes must find live cancellation - // and quiescence ownership, not the previous activity's settled state. - emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', message, 'queued') } /** * Run one turn and any request-error retry. `admitted` input enters the log * only after `turn/start` commits; until then it has no owner state to unwind. */ - private async run( - trigger: TurnTrigger, - admitted: UserMessage[] = [], - inheritedOutboxLength = 0, - priorFailures: readonly LlmFailure[] = Object.freeze([]), - ): Promise { - // Both entries hold the invariant: kick() clears the admission slot before - // awaiting run(), and a retry is entered only after the prior run clears it. - /* v8 ignore next -- unreachable guard: every caller clears or checks the abort slot first */ - if (this.abort !== undefined) throw new Error(`agent "${this.id}" is already running`) - const controller = new AbortController() - this.abort = controller - this.acceptsNextStep = true - const signal = controller.signal - const turn = this.lastTurn + 1 - let step = 0 - let opened = false - let reason: TurnEndReason = { kind: 'completed' } - let settleReason: SettleReason = { kind: 'completed' } - let requestFailureHistory = priorFailures - let retryFailures: readonly LlmFailure[] | undefined - const cancelRetry = (): void => { retryFailures = undefined } - signal.addEventListener('abort', cancelRetry, { once: true }) - + private async turn(): Promise { + if (this.phase.kind === 'idle') throw new Error() + const abort = this.phase.kind === 'collecting' ? this.phase.abort : new AbortController() + const lastTurn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn + const phase = { kind: 'running' as const, abort, turn: lastTurn, step: 0 } + this.setPhase(phase) + if (abort.signal.aborted) return this.outbox.length > 0 || this.queued.length > 0 + let admission: Admission try { - signal.throwIfAborted() - this.session.append('turn/start', { turn, trigger }) - // Committed: publish the turn to the machine's own bookkeeping and let - // the admitted input enter the log it now belongs to. - this.turnOpen = true - opened = true - this.lastTurn = turn - // Context or steering retained by an earlier rejected admission happened - // before this prompt and must occupy the same order in durable history. - this.drainOutbox(turn, inheritedOutboxLength) - for (const input of admitted) { - this.session.append('user/message', input, { surfaceOp: 'append' }) - } - signal.throwIfAborted() - - this.drainOutbox(turn) - - steps: while (true) { - step += 1 - const outcome = await this.step(turn, step, signal) - switch (outcome.kind) { - case 'completed': - requestFailureHistory = Object.freeze([]) - if (outcome.maxTokens) reason = { kind: 'max-tokens' } - // A concluding tool result is terminal: steering already in the - // log waits for the next turn's request instead of reopening this - // one, and the agent/turn-stopping drain below is skipped for the same - // reason. - if (outcome.concluded) break steps - if (outcome.continueTurn || this.outbox.some(item => item.steering)) continue - break - case 'request-failed': { - // step() reports request failures only after step/start commits - // and before its own step/end, so the step is always open here. - this.stepOpen = false - this.session.append('step/end', { turn, step }) - if (!signal.aborted) { - try { - const action = await this.loopCtx.waterfall( - agentCarrier(this), 'agent/request-error', this, turn, step, outcome.error, - outcome.failure, requestFailureHistory, outcome.retryPolicy, signal, - () => Promise.resolve(undefined), - ) - // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- signal can abort while recovery is awaited. - if (action?.kind === 'retry' && !signal.aborted) { - retryFailures = Object.freeze([...requestFailureHistory, outcome.failure]) - } - } catch (recoveryError: unknown) { - this.loopCtx.logger.warn( - `agent "${this.id}": request recovery failed at turn ${turn}, step ${step}: ${errorChain(recoveryError)}`, - ) - } - } - const settlement = this.settle(turn, step, outcome.error, signal, outcome.failure) - reason = settlement.reason - settleReason = settlement.settleReason - break steps + admission = await this.admit(true) + if (admission.kind !== 'admitted') return false + abort.signal.throwIfAborted() + } catch (error: unknown) { + // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- cancel may abort while admission awaits + if (abort.signal.aborted) return this.outbox.length > 0 || this.queued.length > 0 + throw error + } + const turn = ++phase.turn + this.session.append('turn/start', { turn }) + let turnEnds: TurnEndReason | null = null + try { + while (true) { + if (admission.kind === 'admitted') { + for (const message of admission.claimed) { + emitAgentEvent(this.loopCtx, this, 'agent/inbox/admitted', message) + } + for (const message of admission.messages) { + this.session.append('user/message', message, { surfaceOp: 'append' }) } - /* v8 ignore next 2 -- closed-union exhaustiveness guard */ - default: - assertNever(outcome) } - await this.loopCtx.serial(agentCarrier(this), 'agent/turn-stopping', this, turn, signal) - signal.throwIfAborted() - if (!this.drainOutbox(turn)) break - } - } catch (caught: unknown) { - try { - if (this.stepOpen) { - this.stepOpen = false + abort.signal.throwIfAborted() + const step = ++phase.step + this.session.append('step/start', { turn, step }) + try { + turnEnds = await this.step() + } finally { this.session.append('step/end', { turn, step }) } - } catch (closeError: unknown) { - // Contained like the finally's turn close: a persistently rejecting - // step boundary must not escape run(), or the post-finally tail would - // never publish the terminal status and observers would see a - // permanently running agent whose whenIdle() already resolved. - this.loopCtx.logger.warn(`agent "${this.id}": closing step ${turn}/${step} failed: ${errorChain(closeError)}`) - emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, closeError) - } - ({ reason, settleReason } = this.settle(turn, step, caught, signal)) - } finally { - // Every step-close happens before this point on both success and - // failure paths (step(), the request-failed branch, the catch), so the - // finally owes only the turn boundary. - this.acceptsNextStep = false - try { - if (this.turnOpen) { - // Re-entrant turn/end listeners must route new input to a later turn. - this.turnOpen = false - this.session.append('turn/end', { turn, reason }) + abort.signal.throwIfAborted() + if (turnEnds && this.outbox.length === 0) { + await this.loopCtx.serial(agentCarrier(this), 'agent/turn-stopping', this, turn, abort.signal) + abort.signal.throwIfAborted() } - } catch (error: unknown) { - retryFailures = undefined - this.loopCtx.logger.warn(`agent "${this.id}": closing turn ${turn} failed: ${errorChain(error)}`) - emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error) + admission = await this.admit(false) + if (admission.kind === 'blocked') { + turnEnds = { kind: 'aborted', reason: abort.signal.reason as AgentCancelCause } + return false + } + abort.signal.throwIfAborted() + if (admission.kind === 'empty' && turnEnds) break } - // cancel() aborts but never clears the slot, and no second run can - // install a controller while this one is still unwinding, so the slot - // is still this run's controller here. - this.abort = undefined - signal.removeEventListener('abort', cancelRetry) - } - - if (opened) { - try { - await this.loopCtx.sessions.flush(this.session) - } catch (error: unknown) { - this.loopCtx.logger.warn(`agent "${this.id}": session/flush failed at turn ${turn}: ${errorChain(error)}`) - emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error) - } - } - - if (retryFailures !== undefined) { - await this.run({ kind: 'retry' }, [], 0, retryFailures) - } else { - // agent/settled names only committed turns: a run aborted or rejected - // before turn/start has no durable turn/end for consumers to settle - // against, so it exits without the notification. - if (opened) emitAgentEvent(this.loopCtx, this, 'agent/settled', turn, settleReason) - this.continueOrIdle() + } catch (error: unknown) { + // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- cancel may abort during any awaited turn operation + if (abort.signal.aborted) turnEnds = { kind: 'aborted', reason: abort.signal.reason as AgentCancelCause } + else turnEnds = { kind: 'error', error: errorChain(error) } + } finally { + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the turn is always ended in this block + this.session.append('turn/end', { turn, reason: turnEnds! }) } + return this.outbox.length > 0 || this.queued.length > 0 } /** * Run the `agent/step` extension point, commit pending input, derive one * request, and execute its tool calls inside one durable step boundary. */ - private async step( - turn: number, - step: number, - signal: AbortSignal, - ): Promise { - const { session } = this - - // The single between-steps extension point: listeners inject, steer, or - // edit the log here; the request derives from the log after this settles. + private async step(): Promise { + if (this.phase.kind !== 'running') throw new Error() + const { turn, step, abort: { signal } } = this.phase + signal.throwIfAborted() await this.loopCtx.serial(agentCarrier(this), 'agent/step', this, turn, step, signal) signal.throwIfAborted() - - // Take the outbox whole — same-boundary steering and context leave in - // this request together. - this.drainOutbox(turn) - - // Assemble the system prompt fresh each step (it may depend on log state). const assembly = await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal)) signal.throwIfAborted() const system = renderPrompt(assembly) - // Snapshot the exact log prefix: the reconstruction boundary. Appends - // after this synchronous snapshot join the next request. - const boundaryMessages = session.deriveMessages() - - session.append('step/start', { turn, step }) - this.stepOpen = true - signal.throwIfAborted() - - const { request, preparedCall } = await this.buildRequest( - turn, step, assembly.tools, system, boundaryMessages, signal, - ) - - const assembler = new BlockAssembler() - const chunkSeqs: number[] = [] - const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request) - try { + let message: AssistantMessage + while (true) { + const boundaryMessages = this.session.deriveMessages() + const { request, preparedCall } = await this.buildRequest( + turn, step, assembly.tools, system, boundaryMessages, signal, + ) + const assembler = new BlockAssembler() + const chunkSeqs: number[] = [] + const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request) + signal.throwIfAborted() for await (const chunk of stream) { signal.throwIfAborted() - const chunkEvent = session.append('assistant/chunk', { turn, step, chunk }) + const chunkEvent = this.session.append('assistant/chunk', { turn, step, chunk }) chunkSeqs.push(chunkEvent.seq) assembler.push(chunk) } - } catch (error: unknown) { - const facts = llmFailureOf(stream, error) - if (facts !== undefined && error instanceof Error) { - return { kind: 'request-failed', error, failure: facts, retryPolicy: llmRetryPolicyOf(stream) } + signal.throwIfAborted() + const finish = assembler.finish + if (finish.kind === 'error' || finish.kind === 'aborted') { + const action = await this.loopCtx.waterfall( + agentCarrier(this), 'agent/request-error', this, { + turn, + step, + provider: request.provider, + failure: finish.failure, + retryPolicy: preparedCall?.retryPolicy, + }, signal, + () => Promise.resolve(undefined), + ) + signal.throwIfAborted() + if (action?.kind !== 'retry') { + return { kind: 'error', error: finish.failure } + } + } else { + message = createAssistantMessage({ + content: assembler.blocks(), + source: { + provider: request.provider, + model: request.model, + ...assembler.replayState !== undefined ? { replayState: assembler.replayState } : {}, + }, + }) + this.session.append( + 'assistant/message', + { + turn, + step, + message, + ...assembler.usage === undefined ? {} : { usage: assembler.usage }, + }, + { surfaceOp: 'append', sourceEventSeqs: chunkSeqs }, + ) + if (finish.kind === 'max-tokens') { + return { kind: 'max-tokens' } + } + break } - throw error - } - signal.throwIfAborted() - - // Failure finish chunks take the same path as thrown stream errors. - const finish = assembler.finish - if (finish.kind === 'error' || finish.kind === 'aborted') { - const error = new LlmError(finish.failure.message, finish.failure.code, finish.failure) - return { kind: 'request-failed', error, failure: finish.failure, retryPolicy: llmRetryPolicyOf(stream) } } - // Truncated (max-tokens) output cannot owe tool calls. - const assembled = assembler.blocks() - const content = finish.kind === 'max-tokens' - ? assembled.filter(block => block.type !== 'tool-call') - : assembled - const message: AssistantMessage = createAssistantMessage({ - content, - source: { - provider: request.provider, - model: request.model, - ...assembler.replayState !== undefined ? { replayState: assembler.replayState } : {}, - }, - }) - - session.append( - 'assistant/message', - { - turn, - step, - message, - ...assembler.usage === undefined ? {} : { usage: assembler.usage }, - }, - { surfaceOp: 'append', sourceEventSeqs: chunkSeqs }, - ) - - const toolCalls = content.filter(block => block.type === 'tool-call') - let concluded = false + const toolCalls = message.content.filter(block => block.type === 'tool-call') + let result: TurnEndReason | null if (toolCalls.length > 0) { - ({ concluded } = await executeToolCalls( + const { concluded } = await executeToolCalls( this.loopCtx, turn, step, toolCalls, signal, - context => this.outbox.push({ message: freezeMessage(context), steering: false }), - )) - } - - // Tool results stay adjacent to their calls; input accepted during the - // request enters the log only after the complete result batch. - const steered = this.drainOutbox(turn) - session.append('step/end', { turn, step }) - this.stepOpen = false - return { - kind: 'completed', - continueTurn: (toolCalls.length > 0 && !concluded) || steered, - concluded, - maxTokens: finish.kind === 'max-tokens', + context => this.outbox.push(context), + ) + result = concluded ? { kind: 'completed' } : null + } else { + result = { kind: 'completed' } } + return result } /** @@ -571,11 +360,9 @@ export class ReactLoopAgent implements Agent { boundaryMessages: Message[], signal: AbortSignal, ): Promise<{ request: GenerateOptions; preparedCall?: PreparedLlmCall }> { - const { session } = this - // A loop instance starts from its declared route, restoring only an opaque // effort owned by that exact model. Later steps fold the config it logged. - const persistedConfig = session.requestHeader()?.config + const persistedConfig = this.session.requestHeader()?.config const route = { provider: this.options.provider ?? '', model: this.options.model ?? '' } const reasoningEffort = persistedConfig?.provider === route.provider && persistedConfig.model === route.model @@ -618,113 +405,23 @@ export class ReactLoopAgent implements Agent { ...system ? { system } : {}, ...tools.length > 0 ? { tools } : {}, }) - const baseline = session.requestHeader() + const baseline = this.session.requestHeader() if (!this.requestHeaderLogged) { - session.append('request/header', { header, reason: baseline === undefined ? 'initial' : 'resume' }) + this.session.append('request/header', { header, reason: baseline === undefined ? 'initial' : 'resume' }) this.requestHeaderLogged = true } else if (baseline === undefined || !headerEquals(baseline, header)) { - session.append('request/header', { header, reason: 'change' }) + this.session.append('request/header', { header, reason: 'change' }) } + signal.throwIfAborted() const request = markAgentLoopRequest(deepFreeze({ ...header.config, messages: boundaryMessages, ...header.system !== undefined ? { system: header.system } : {}, ...header.tools !== undefined ? { tools: header.tools } : {}, - sessionId: session.id, + sessionId: this.session.id, signal, })) return { request, ...preparedCall === undefined ? {} : { preparedCall } } } - - /** Commit the outbox and report whether it contained steering. */ - private drainOutbox(turn: number, limit = this.outbox.length): boolean { - let steered = false - for (const item of this.outbox.splice(0, limit)) { - if (item.steering) { - steered = true - emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', item.message, 'steering') - this.session.append( - 'steering/message', - { turn, message: item.message }, - { surfaceOp: 'append' }, - ) - } else { - this.session.append('user/message', item.message, { surfaceOp: 'append' }) - } - } - return steered - } - - /** - * Give context-only input its ordinary idle placement when admission - * produces no turn. Steering keeps the whole boundary staged so context - * accepted beside it cannot split from the request it accompanies. - */ - private flushRejectedAdmissionContexts(): void { - if (this.outbox.some(item => item.steering)) return - const contexts = this.outbox.splice(0) - for (let index = 0; index < contexts.length; index += 1) { - const item = contexts[index] - /* v8 ignore next 2 -- the steering precheck proves this batch is context-only */ - if (item === undefined || item.steering) throw new Error('rejected-admission context batch changed') - try { - this.session.append('user/message', item.message, { surfaceOp: 'append' }) - } catch (error: unknown) { - this.outbox.unshift(...contexts.slice(index)) - throw error - } - } - } - - /** - * The single settlement funnel: classify one turn failure (interruption - * beats error) into the durable turn/end reason and live settlement report. - */ - private settle( - turn: number, - step: number, - error: unknown, - signal: AbortSignal, - failure?: LlmFailure, - ): { reason: TurnEndReason; settleReason: SettleReason } { - if (signal.aborted) { - // Slot invariant, stated rather than re-validated: the turn controller - // is machine-private and cancel() is its only aborter, always with one - // frozen canonical cause as the reason. - const interrupt = signal.reason as AgentInterruptReason - return { - reason: { kind: interrupt.kind === 'disposed' ? 'disposed' : 'aborted' }, - settleReason: { kind: 'aborted' }, - } - } - if (failure !== undefined) { - emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error) - // The durable record renders the full cause chain: turn/end is the one - // durable trace of the failure, so a wrapper message alone would lose - // the transport detail the log exists to keep. - const rendered = errorChain(error) - return { - reason: { kind: 'error', step, failure: { ...failure, ...rendered === '' ? {} : { message: rendered } } }, - settleReason: { kind: 'error', error, failure }, - } - } - emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error) - return { - reason: { kind: 'error', step, message: errorChain(error), ...isHarnessError(error) ? { code: error.code } : {} }, - settleReason: { kind: 'error', error }, - } - } - - /** Continue with a waking prompt, or publish the idle status. */ - private continueOrIdle(): void { - if (this.queued.some(item => item.wakeup)) { - this.kick() - } else { - // Every caller sits inside an admission or run whose install marked the - // interval busy, so the flag is still set here. - this.busy = false - emitAgentEvent(this.loopCtx, this, 'agent/status', 'idle') - } - } } diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts index ca6b83dadb..b2b025965a 100644 --- a/packages/core/agent-loop/src/index.ts +++ b/packages/core/agent-loop/src/index.ts @@ -384,18 +384,7 @@ export class AgentLoop extends Service implements AgentFactory { if (machine === undefined) await machineReady.promise if (machine !== undefined) { machine.cancel({ kind: 'disposed' }) - // Drain to TRUE quiescence: cancel's own synchronous event chain - // (running→idle) can legitimately re-enter through an automation - // listener (goal-session's idle drive) and replace `done` with a - // fresh admission before this await captures it. The replacement - // work is cancelled and drained in turn until the slot stabilizes. - let done = machine.done - while (true) { - await Promise.allSettled([done]) - if (machine.done === done) break - done = machine.done - machine.cancel({ kind: 'disposed' }) - } + await machine.whenIdle() await machine.scope.dispose() } } finally { @@ -452,7 +441,7 @@ export class AgentLoop extends Service implements AgentFactory { loopCtx.agents.announce(agent) assertLive() // A synchronous announce/session-start listener may have started - // teardown; the machine is already live (send() works from the + // teardown; the machine is already live (delivery works from the // session-start seam), so only the liveness recheck is owed. emitAgentEvent(loopCtx, agent, 'agent/session-start', source) assertLive() diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 1636998094..1bc9d58406 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -7,7 +7,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm' * @module dsh-agent-loop/tests/cancel */ -import { describe, expect, it, vi } from 'vitest' +import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import LlmService from '@deepseek-ai/dsh-llm' import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' @@ -55,33 +55,6 @@ function userTexts(agent: Agent): string[] { } describe('Agent.cancel()', () => { - it('notifies every observer before clearing work and contains listener failures', async () => { - const adapter = new MockAdapter([textResponse('must remain unused')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('cancel-event'), { provider: 'mock', model: 'mock' }) - const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) - const seen: string[] = [] - ctx.on('agent/cancel-requested', (subject, cause) => { - if (subject !== agent) return - seen.push(`first:${cause.kind}`) - subject.followup(createUserMessage({ content: [{ type: 'text', text: 'queued by cancel observer' }], source: { kind: 'user' } })) - throw new Error('observer failed') - }) - ctx.on('agent/cancel-requested', (subject, cause) => { - if (subject === agent) seen.push(`second:${cause.kind}`) - }) - - send(agent, 'drop me') - agent.cancel({ kind: 'user' }) - await new Promise(resolve => setTimeout(resolve, 30)) - agent.cancel({ kind: 'parent' }) - - expect(seen).toEqual(['first:user', 'second:user']) - expect(userTexts(agent)).toEqual([]) - expect(adapter.requests).toHaveLength(0) - expect(warned).toHaveBeenCalledWith(expect.stringContaining('agent/cancel-requested')) - }) - it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => { const adapter = new MockAdapter([textResponse('reply')]) const ctx = await harness(adapter) @@ -103,62 +76,29 @@ describe('Agent.cancel()', () => { const adapter = new MockAdapter([textResponse('reply')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const discards: unknown[] = [] - ctx.on('agent/inbox/discard', (subject, items) => { if (subject === agent) discards.push(items) }) - const cancelRequests: unknown[] = [] - ctx.on('agent/cancel-requested', (subject, cause) => { if (subject === agent) cancelRequests.push(cause) }) + const canceled: unknown[] = [] + ctx.on('agent/inbox/canceled', (subject, message) => { if (subject === agent) canceled.push(message) }) - // Queue a turn WITHOUT waking the driver, so it sits in the inbox. - agent.send(createUserMessage({ content: [{ type: 'text', text: 'preserved' }], source: { kind: 'user' } }), { target: 'next-turn', wakeup: false }) - // keepInbox cancel: no active turn, work preserved, no discard event. With - // nothing to abort and nothing discarded, the call is a documented no-op, - // so it emits no cancel-requested either. + agent.followup(createUserMessage({ + content: [{ type: 'text', text: 'preserved' }], + source: { kind: 'user' }, + })) + // Abort the collecting activity while preserving its queued item. agent.cancel({ kind: 'user' }, { keepInbox: true }) - expect(discards).toEqual([]) - expect(cancelRequests).toEqual([]) + expect(canceled).toEqual([]) - // The preserved item still runs once the driver is woken by a later send. + // The preserved item still runs once a later follow-up wakes the driver. send(agent, 'wake it') await waitForIdle(ctx, agent) expect(userTexts(agent)).toEqual(['preserved', 'wake it']) }) - it('a lone quiet (wakeup:false) send leaves the agent parked at idle', async () => { - const adapter = new MockAdapter([textResponse('reply')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - - // A quiet item alone must NOT wake the driver: no turn runs and whenIdle - // resolves (the agent is quiescent), leaving the item queued. - agent.send(createUserMessage({ content: [{ type: 'text', text: 'quiet' }], source: { kind: 'user' } }), { target: 'next-turn', wakeup: false }) - await agent.whenIdle() - expect(agent.status).toBe('idle') - expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false) - - // A later waking send drives the loop, and the quiet item rides along first. - send(agent, 'wake') - await waitForIdle(ctx, agent) - expect(userTexts(agent)).toEqual(['quiet', 'wake']) - }) - - it('cancelling a parked quiet item settles a pending whenIdle() without a later send', async () => { - const adapter = new MockAdapter([textResponse('reply')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - - agent.send(createUserMessage({ content: [{ type: 'text', text: 'quiet' }], source: { kind: 'user' } }), { target: 'next-turn', wakeup: false }) - const idle = agent.whenIdle() - agent.cancel({ kind: 'user' }) - await idle - expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false) - }) - it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => { const adapter = new MockAdapter([textResponse('should not run')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - // send() queues synchronously (status still idle, loop microtask not yet + // followup() queues synchronously (status still idle, loop microtask not yet // resumed). Cancel in that pre-step window: the queued turn must not run. send(agent, 'drop me first') send(agent, 'drop me second') diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts index 8c31c4121e..5a2ef01b7e 100644 --- a/packages/core/agent-loop/tests/coverage-edges.spec.ts +++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts @@ -506,24 +506,6 @@ describe('driver bookkeeping edges', () => { expect(agent.session.events).toEqual([]) }) - it('a whenIdle waiter survives a rejected driver promise', async () => { - const adapter = new MockAdapter([textResponse('ok')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('waiter-chain'), { provider: 'mock', model: 'mock' }) - // A throwing terminal-notification listener rejects the driver promise - // (the run's containment covers only session appends); the waiter's - // catch arm must treat that rejection as quiescence instead of - // propagating it. - ctx.on('agent/settled', (subject) => { - if (subject === agent) throw new Error('settled listener exploded') - }) - - send(agent, 'one') - // Entered while the run owns the abort slot, the waiter awaits the - // driver promise; its rejection must count as quiescence and resolve. - await expect(agent.whenIdle()).resolves.toBeUndefined() - }) - it('a request failure that concludes recovery after step/end closed keeps the boundary balanced', async () => { const { LlmError } = await import('@deepseek-ai/dsh-llm') // The failure finish-chunk path returns request-failed AFTER step() has diff --git a/packages/core/agent-loop/tests/invariant.spec.ts b/packages/core/agent-loop/tests/invariant.spec.ts index d3381cd524..3abdf04aa0 100644 --- a/packages/core/agent-loop/tests/invariant.spec.ts +++ b/packages/core/agent-loop/tests/invariant.spec.ts @@ -25,7 +25,7 @@ function loopRequest(options: T): Readonly { async function requestSetup() { const ctx = await setup() const session = ctx.sessions.create(SessionId('req-check')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -74,7 +74,7 @@ describe('request-reconstruction invariant', () => { it('rejects loop requests with no boundary or header', async () => { const ctx = await setup() const session = ctx.sessions.create(SessionId('req-bare')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const bare = loopRequest({ model: 'm', messages: Object.freeze([]), sessionId: session.id }) expect(() => { dispatch(ctx, bare) }).toThrow(/no step\/start/) session.append('step/start', { turn: 1, step: 1 }) @@ -122,7 +122,7 @@ describe('request-reconstruction invariant', () => { await ctx.plugin(InvariantService) await ctx.plugin(AgentLoopInvariant) const session = ctx.sessions.create(SessionId('prepend-check')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index e051642dfd..ee2159c0d0 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -433,8 +433,6 @@ describe('agent loop', () => { // split the assistant tool call from the provider's tool-result message. const turnStarts = agent.session.events.filter(e => e.type === 'turn/start') expect(turnStarts).toHaveLength(1) - const ts0 = turnStarts[0]! - expect(ts0.type === 'turn/start' && ts0.data.trigger.kind).toBe('message') const result = agent.session.events.find(e => e.type === 'tool/result')! const contexts = agent.session.events.filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin') expect(contexts).toHaveLength(2) @@ -1031,16 +1029,11 @@ describe('agent loop', () => { agent.followup(createUserMessage({ content: [{ type: 'text', text: 'plugin message' }], source: { kind: 'plugin', plugin: 'test' } })) await idle - const triggers = agent.session.events - .filter(event => event.type === 'turn/start') - .map(event => event.data.trigger) + const turns = agent.session.events.filter(event => event.type === 'turn/start') const sources = agent.session.events .filter(event => event.type === 'user/message') .map(event => event.data.source) - expect(triggers).toEqual([ - { kind: 'message', source: { kind: 'user' } }, - { kind: 'message', source: { kind: 'plugin', plugin: 'test' } }, - ]) + expect(turns).toHaveLength(2) expect(sources).toEqual([ { kind: 'user' }, { kind: 'plugin', plugin: 'test' }, diff --git a/packages/core/agent-loop/tests/request-error.spec.ts b/packages/core/agent-loop/tests/request-error.spec.ts index c0e151016d..afd62f7d20 100644 --- a/packages/core/agent-loop/tests/request-error.spec.ts +++ b/packages/core/agent-loop/tests/request-error.spec.ts @@ -63,13 +63,9 @@ describe('agent/request-error', () => { retryPolicy: ResolvedRetryPolicy | undefined }[] = [] const statuses: string[] = [] - const settledTurns: number[] = [] ctx.on('agent/status', (subject, status) => { if (subject === agent) statuses.push(status) }) - ctx.on('agent/settled', (subject, turn) => { - if (subject === agent) settledTurns.push(turn) - }) ctx.on('agent/request-error', async ( subject, turn, step, _error, failure, priorFailures, retryPolicy, ) => { @@ -101,12 +97,7 @@ describe('agent/request-error', () => { code: 'SERVICE_UNAVAILABLE', }, ]) - expect(agent.session.events.filter(event => event.type === 'turn/start').map(event => event.data.trigger)) - .toEqual([ - { kind: 'message', source: { kind: 'user' } }, - { kind: 'retry' }, - { kind: 'retry' }, - ]) + expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) expect(seen.map(item => item.priorFailures.map(failure => failure.code))) .toEqual([[], ['RATE_LIMIT']]) expect(seen.map(item => item.retryPolicy)).toEqual([ @@ -114,7 +105,6 @@ describe('agent/request-error', () => { expect.objectContaining({ mode: 'normal' }), ]) expect(statuses).toEqual(['running', 'idle']) - expect(settledTurns).toEqual([3]) }) it('lets cancellation win over a retry action', async () => { diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts index f133f1979c..197688031f 100644 --- a/packages/core/agent-loop/tests/resume.spec.ts +++ b/packages/core/agent-loop/tests/resume.spec.ts @@ -43,7 +43,7 @@ async function persistSession(sessionId: SessionId): Promise { // balanced completed turn is the smallest resumable log and avoids running // the model merely to construct this lifecycle fixture. const seed: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }, ] const session = ctx.sessions.create(sessionId, { seed }) @@ -86,7 +86,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume', createdAt: 1, }) await first.ctx.sessionPersistence.append(sessionId, [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message', seq: 1, @@ -175,7 +175,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume', const { ctx } = await persistentHarness(new MockAdapter([textResponse('unused')])) const sessionId = SessionId('live-resume-race') const first = (await ctx.agents.create({ sessionId })).agent - first.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + first.session.append('turn/start', { turn: 1 }) await ctx.sessions.flush(first.session) await expect(ctx.agents.resume({ resumeSessionId: sessionId })) @@ -494,7 +494,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume', // in its header) by creating it with a complete-turn seed — the write path // materializes the fork (header + seed) on disk. const seed: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }, ] const adapter1 = new MockAdapter([textResponse('a')]) diff --git a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts index 5f4e51784a..315d7f5b6f 100644 --- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts +++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts @@ -147,7 +147,7 @@ describe('agent scope lifecycle', () => { expect(agent.ctx.agent).toBe(agent) // The root accessor default: a plain context answers undefined, not a throw. expect(ctx.agent).toBeUndefined() - await ctx.agents.get(SessionId('a1'))?.whenIdle() + await agent.whenIdle() }) it('records agents created through an agent context as non-root runtime children', async () => { diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml index 59dcdac249..a0facf83d0 100644 --- a/packages/core/agent/README.i18n.yaml +++ b/packages/core/agent/README.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 packages/core/agent/README.md -README.md: 9ca79f28506b133a555bd7d1e984386c715fd9d6 -README.zh.md: 165f71f1b395bdf0c229e2c4b1a30e89347b6be1 +README.md: 2d373487b7ae17a68edfaa4c45d8479f869276a5 +README.zh.md: 9e3b043baa4832721c66d6d0752c8601ea9d817c diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 9ca79f2850..2d373487b7 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -50,7 +50,7 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves. -Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives the exact error, normalized failure facts, and signal after the failed step closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery; the loop closes the failed turn and opens one numbered retry turn. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement. +Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery; the loop closes the failed turn and opens one numbered retry turn. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement. `PromptDecision.additionalContexts` is an array of identified, frozen `UserMessage` values so every context keeps its own identity and source. The admitted prompt and every additional context become separate model-facing `user/message` events before the turn runs. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; replacing admitted content preserves the prompt's identity. @@ -60,11 +60,10 @@ Turn and step boundaries and the model token stream are durable `session/event` The handle every plugin programs against: -- `agent.send(message, options)` — the one delivery primitive over the (`target` × `wakeup`) matrix. `message` is an already identified, frozen `UserMessage`; callers normally create it with `createUserMessage()` before routing begins. `SendOptions` owns only the `target` and `wakeup` policy. The agent publishes or queues the complete value as-is without minting or replacing its identity. The message's `agent/inbox/enqueue`/`dequeue`/`discard` events carry it so callers can correlate a queued item with its lifecycle; enqueue and dequeue also carry the resolved `queued | steering` placement so repeated message identities retire from the correct FIFO. `target: 'next-turn'` queues one independent FIFO item that, if admitted, becomes the sole ordinary prompt in its turn. `target: 'next-step'` with `wakeup: true` submits steering, while `target: 'next-step'` with `wakeup: false` injects durable context without running the model. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale. -- `agent.followup(input)` — the `next-turn`/wakeup preset of `send()`: queue an ordinary follow-up turn and wake the driver. +- `agent.followup(input)` — queue an ordinary follow-up turn and wake the driver. Each admitted item becomes the sole ordinary prompt in its turn; the [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale. - `agent.steer(input)` — the `next-step`/wakeup preset: during prompt admission or an open turn, stage steering for the next safe boundary without dispatching `agent/prompt-submit`; outside that acceptance window, delegate to a woken follow-up. Admission failure leaves staged steering for retry or a later admitted prompt, while cancellation or disposal may discard it. - `agent.inject(input)` — the `next-step`/no-wakeup preset: append model-facing context without running the model; the next request sees a verbatim user-role message whose provenance is carried by the required `input.source`. During prompt admission or an open turn, injection waits in the outbox for the next safe boundary. Outside that acceptance window, it appends immediately without opening a turn; a context-only admission batch takes this fallback if admission closes without a turn, while context staged beside steering remains pending with it. Persistence reacts to `session/event` independently. Injection emits no `agent/inbox/*` event. -- `agent.acceptsNextStep` — whether a `next-step` send would currently join prompt admission or the open turn. Use this narrower routing predicate when a caller must choose between steering and a fresh admitted prompt; `status === 'running'` also covers admission exit and turn settlement. +- `agent.acceptsNextStep` — whether steering would currently join prompt admission or the open turn. Use this narrower routing predicate when a caller must choose between steering and a fresh admitted prompt; `status === 'running'` also covers admission exit and turn settlement. - `agent.cancel(cause, options?)` — cancel the active turn and, unless `options.keepInbox`, ALL pending work. Callers must choose the `user | parent` cause explicitly; an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; dropped items are reported on `agent/inbox/discard`, and observers may synchronize state but cannot veto cancellation. `keepInbox: true` aborts the turn but preserves queued and steering items (no discard, and un-started work is not dropped). The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`. - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly. - `agent.session`, `agent.status`, `agent.options`, `agent.id` diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md index 165f71f1b3..9e3b043baa 100644 --- a/packages/core/agent/README.zh.md +++ b/packages/core/agent/README.zh.md @@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供， 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器静默后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。 -大多数拦截点都是协作式 waterfall。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：失败步骤关闭后，它接收确切错误、规范化失败事实和信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。 +大多数拦截点都是协作式 waterfall。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时的服务注册重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。 `PromptDecision.additionalContexts` 是由带标识且冻结的 `UserMessage` 值组成的数组，因此每个上下文都保留自己的标识和来源。获准的提示词与每个附加上下文都会在轮次运行前成为各自独立、面向模型的 `user/message` 事件。包装下游允许决策的监听器会保留其 `content` 与 `additionalContexts`，除非有意替换任一字段；替换获准内容时仍会保留提示词的标识。 @@ -60,11 +60,10 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供， 每个插件面向的 handle： -- `agent.send(message, options)`：覆盖（`target` × `wakeup`）矩阵的唯一投递原语。`message` 是已有标识且已冻结的 `UserMessage`；调用方通常会在开始路由前使用 `createUserMessage()` 创建它。`SendOptions` 只持有 `target` 与 `wakeup` 策略。agent 会原样发布或排队完整值，不会生成或替换其标识。该消息的 `agent/inbox/enqueue`/`dequeue`/`discard` 事件会携带完整消息，调用方可据此把排队项与其生命周期关联；入队与出队事件还会携带解析出的 `queued | steering` 路由归类，使重复出现的消息标识能在正确的 FIFO 中完成结算。`target: 'next-turn'` 排队一条独立 FIFO 项，获准后成为其轮次中唯一的普通提示词。`target: 'next-step'` 且 `wakeup: true` 提交 steering（中途引导），而 `target: 'next-step'` 且 `wakeup: false` 注入持久上下文，不运行模型。轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。 -- `agent.followup(input)`：`send()` 的 `next-turn`／wakeup 预设：排队一个普通后续轮次并唤醒驱动器。 +- `agent.followup(input)`：排队一个普通后续轮次并唤醒驱动器。每个获准项都会成为其轮次中唯一的普通提示词；轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。 - `agent.steer(input)`：`next-step`／wakeup 预设：提示词接纳期间或轮次打开时，为下一个安全边界暂存 steering，且不分发 `agent/prompt-submit`；该接收窗口之外则委托给会唤醒的后续轮次。接纳失败会保留暂存的 steering，以供重试或之后获准的提示词使用，而取消或 dispose 可能丢弃它。 - `agent.inject(input)`：`next-step`／不唤醒预设：追加面向模型的上下文而不运行模型；下一次请求会看到一条逐字的 user role 消息，其来源由必填的 `input.source` 携带。提示词接纳期间或轮次打开时，注入会在 outbox 中等待下一个安全边界。该接收窗口之外，它会立即追加而不开启轮次；如果接纳结束却未开启轮次，仅含上下文的接纳批次会采用这一回退，而与 steering 一同暂存的上下文则会随其继续待处理。持久化独立地响应 `session/event`。注入不发出 `agent/inbox/*` 事件。 -- `agent.acceptsNextStep`：当前发送 `next-step` 时，是否会加入提示词接纳或已打开的轮次。当调用方必须在 steering 与新接纳的提示词之间选择时，应使用这一更窄的路由判定；`status === 'running'` 还涵盖接纳收尾与轮次结算阶段。 +- `agent.acceptsNextStep`：steering 当前是否会加入提示词接纳或已打开的轮次。当调用方必须在 steering 与新接纳的提示词之间选择时，应使用这一更窄的路由判定；`status === 'running'` 还涵盖接纳收尾与轮次结算阶段。 - `agent.cancel(cause, options?)`：取消活动轮次，并在未设置 `options.keepInbox` 时取消全部待处理工作。调用方必须显式选择 `user | parent` 原因；活动持有者会在中止前把其判别字段复制为已分离、冻结的信号原因。有效调用会在清除排队与 steering 工作前，随原因发出 `agent/cancel-requested`；丢弃项在 `agent/inbox/discard` 上报告，观察方可以同步状态，但不能 veto 取消。`keepInbox: true` 会中止轮次，但保留排队与 steering 项（不丢弃，且不删除尚未开始的工作）。同进程类型化 seam 不会为无类型调用方添加运行时校验或兼容回退。重复取消活动轮次时，首个信号生效；空闲取消是安全空操作，不发通知。ACP 映射到 `user`，进程内父传播映射到 `parent`。原因只存在于运行时；持久 `turn/end` 保持粗粒度的 `aborted`。 - `agent.whenIdle()`：agent 从 `running` 结算后达到静默时解析（idle ⇒ 立即；disposed ⇒ 等待循环退出）。这是非拥有者的静默观测钩子：观察工作结算，但不 teardown agent。Teardown 独立存在；生命周期拥有者通过 `AgentHandle.dispose()` 停止并注销，并直接等待循环退出。 - `agent.session`、`agent.status`、`agent.options`、`agent.id` diff --git a/packages/core/agent/src/invariant.ts b/packages/core/agent/src/invariant.ts index 5051ac4e31..f2d9a69539 100644 --- a/packages/core/agent/src/invariant.ts +++ b/packages/core/agent/src/invariant.ts @@ -21,27 +21,6 @@ const install: InvariantInstaller = (ctx, fail) => { } lastStatus.set(agent, status) }, { global: true }) - - // Inbox FIFO conservation: an item leaves the inbox (dequeue) or is dropped - // (discard) only after it entered (enqueue), so the live outstanding count - // per agent can never go negative. Injection bypasses the FIFOs entirely and - // never appears on these events. - const outstanding = new WeakMap() - ctx.on('agent/inbox/enqueue', (agent) => { - outstanding.set(agent, (outstanding.get(agent) ?? 0) + 1) - }, { global: true }) - ctx.on('agent/inbox/dequeue', (agent) => { - const count = outstanding.get(agent) ?? 0 - if (count <= 0) fail('agent/inbox/dequeue without a matching prior enqueue') - outstanding.set(agent, count - 1) - }, { global: true }) - ctx.on('agent/inbox/discard', (agent, items) => { - const count = outstanding.get(agent) ?? 0 - if (items.length > count) { - fail(`agent/inbox/discard dropped ${items.length} items but only ${count} were outstanding`) - } - outstanding.set(agent, count - items.length) - }, { global: true }) } /** diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 28b4ca4c71..a7512037c4 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -7,8 +7,9 @@ import type { Context } from 'cordis' import type { Scoped } from '@deepseek-ai/dsh-scope' -import type { ContentBlock, LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm' -import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session' +import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm' +import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session' +export type { AgentCancelCause } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-system-prompt' declare module '@deepseek-ai/dsh-system-prompt' { interface AssembleContext { @@ -27,95 +28,55 @@ export interface AgentOptions { maxTokens?: number } -/** - * Which inbox queue a {@link Agent.send} item joins: - * - `next-turn` — the item becomes its own turn, claimed at a turn boundary. - * - `next-step` — during prompt admission or an open turn, the item stages for - * the next safe step boundary; otherwise it is promoted per its `wakeup` - * flag. - */ -export type SendTarget = 'next-turn' | 'next-step' - -/** Resolved inbox placement reported when an accepted message is enqueued. */ -export type InboxPlacement = 'queued' | 'steering' - -/** - * Options for the unified {@link Agent.send} primitive over the - * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup} - * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and - * {@link Agent.inject} (`next-step`/no-wakeup). - * - * The object is complete so routing policy is explicit. - */ -export interface SendOptions { - /** Queue the item joins. */ - target: SendTarget - /** - * Whether this item makes the model run: wake a parked driver (`next-turn`) - * or force a continuation step (`next-step` while running). A `false` - * `next-turn` item queues without waking; a `false` - * `next-step` item attaches durable context without forcing another step - * (the injection preset). - */ - wakeup: boolean -} - /** Options for {@link Agent.cancel}. */ export interface CancelOptions { /** * Preserve queued and steering inbox items instead of discarding them. The * active turn is still aborted, but un-started and pending work survives for a - * later turn and no `agent/inbox/discard` fires. + * later turn and no `agent/inbox/canceled` fires. */ - keepInbox?: boolean + keepInbox?: boolean | undefined } /** * An agent's lifecycle state, emitted on every transition as `agent/status`: - * `idle` (parked, waiting for queued work), `running` (the driver is draining - * work and may be closing or checkpointing a turn). Disposal removes the - * agent from its registry; it is not a third observable status. + * `idle` means no driver is scheduled or active; `running` begins when a + * cancellable admission is scheduled and lasts while the driver drains, + * closes, or checkpoints turns. Disposal removes the agent from its registry; + * it is not a third observable status. */ export type AgentStatus = 'idle' | 'running' /** - * Prompt interception result. `allow.content` replaces the prompt, while - * `additionalContexts` appends model-facing context before the turn starts. - * An `allow` returned by a listener is authoritative: a listener wrapping - * `next()` preserves both fields unless it intentionally replaces them. + * Prompt interception result. An allowed batch replaces the submitted + * messages. A listener wrapping `next()` preserves the returned batch unless + * it intentionally replaces it. */ export type PromptDecision = - | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] } - | { kind: 'block'; reason: string } + | { kind: 'allow'; messages: UserMessage[] } + | { kind: 'block'; reason: string; keepInbox?: boolean } -/** Model-request failure with an optional machine-routable provider code. */ -export type RequestError = Error & { code?: string } +/** One failed model-request attempt presented to recovery listeners. */ +export interface RequestFailureContext { + /** Turn containing the failed request. */ + readonly turn: number + /** Step containing the failed request attempt. */ + readonly step: number + /** Provider selected for the failed request. */ + readonly provider: string + /** Serializable facts normalized at the final adapter boundary. */ + readonly failure: LlmFailure + /** Policy of the adapter registration that served the failed request. */ + readonly retryPolicy: ResolvedRetryPolicy | undefined +} /** Action returned by a listener that owns model-request recovery. */ export type RequestErrorAction = { kind: 'retry' } | undefined -/** - * Why a turn ended, reported live on `agent/settled` right after the turn's - * durable `turn/end`. `error` carries the thrown value verbatim for observers; - * model-request recovery runs earlier through `agent/request-error`. - */ -export type SettleReason = - | { kind: 'completed' } - | { kind: 'aborted' } - | { kind: 'error'; error: unknown; failure?: LlmFailure } - /** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */ export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact' -/** Stable runtime cause accepted by {@link Agent.cancel}. */ -export type AgentCancelCause = - | { readonly kind: 'user' } - | { readonly kind: 'parent' } - -/** Runtime reason carried by the signal that controls one live turn. */ -export type AgentInterruptReason = AgentCancelCause | { readonly kind: 'disposed' } - -/** Public live-agent handle with aliases over the unified delivery primitive. */ +/** Public live-agent handle. */ export interface Agent { /** The single identity shared with {@link session}. */ readonly id: SessionId @@ -125,77 +86,46 @@ export interface Agent { readonly session: Session /** The current lifecycle state, mirrored on every `agent/status` transition. */ readonly status: AgentStatus - /** - * Whether a `next-step` send currently stages for prompt admission or the - * open turn. Unlike {@link status}, this excludes admission exit and turn - * settlement, when a waking `next-step` send becomes a queued follow-up. - */ - readonly acceptsNextStep: boolean /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */ readonly ctx: Context - /** - * The unified delivery primitive over the (`target` × `wakeup`) matrix. - * It routes the caller's typed content and source as follows: - * - * - `next-turn` queues an item that becomes the sole ordinary message of its - * own FIFO-ordered turn; `wakeup:true` wakes a - * parked driver, while `wakeup:false` queues without waking. - * - `next-step` with `wakeup:true` stages steering during prompt admission - * or an open turn; outside that window it falls back to a woken - * `next-turn`. - * - `next-step` with `wakeup:false` injects durable model-facing context - * without running the model: admission or an open turn stages it for the - * next safe log position, while an injection outside that window appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside - * steering remains pending with it. - * The agent publishes or queues the identified frozen message as-is. - * @param message - identified model-facing content and its producer provenance. - * @param options - target queue and wakeup decision. - */ - send(message: UserMessage, options: SendOptions): void - /** * Clear queued and steering work — unless `keepInbox` — and abort the active - * turn. An effective call first emits `agent/cancel-requested` with the - * resolved typed cause. The first cause wins for the active turn, and - * `whenIdle()` resolves after cancellation reaches quiescence. Idle - * cancellation is a no-op and does not arm later work. + * turn. The first cause wins for the active turn. Idle cancellation is a + * no-op and does not arm later work. * @param cause - the stable caller intent carried by the current turn signal. * @param options - cancellation options; `keepInbox` preserves pending work. */ cancel(cause: AgentCancelCause, options?: CancelOptions): void - /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */ + /** + * Resolve after the current whole-agent activity reaches quiescence. This + * follows replacement work scheduled before the observed driver retires, + * but does not identify the settlement of any particular message. + * @returns fulfillment after no scheduled or active driver remains. + */ whenIdle(): Promise /** - * Queue an ordinary follow-up turn and wake the driver — the - * `next-turn`/wakeup preset of {@link send}. The item becomes the sole - * ordinary message of its own turn. + * Queue an ordinary follow-up turn and wake the driver. The item becomes the + * sole ordinary message of its own turn. * @param message - identified prompt content and its producer provenance. */ followup(message: UserMessage): void /** - * Submit steering during prompt admission or an open turn — the - * `next-step`/wakeup preset of {@link send}. It stages for the next steering - * checkpoint before a request or stop decision. If the activity fails before - * that boundary, the remainder stays staged without waking the agent; retry - * or a later prompt takes it. Outside that window steering falls back to a - * woken follow-up turn, while cancellation or disposal may discard pending - * steering. + * Submit steering for the nearest step. An idle driver schedules a turn; + * collecting and running drivers consume it at their next step boundary. + * Cancellation or disposal may discard pending steering. * @param message - identified steering content and its producer provenance. */ steer(message: UserMessage): void /** - * Append model-facing context without running the model — the - * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn - * stages it at the next safe log position; outside that window it appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside + * Append model-facing context without running the model. Admission or an + * open turn stages it at the next safe log position; outside that window it + * appends immediately without opening a turn. If admission closes without a + * turn, a context-only boundary appends immediately; context staged beside * steering remains pending with it. * @param message - identified injected context and its producer provenance. */ @@ -226,8 +156,9 @@ declare module 'cordis' { */ 'agent/disposed'(this: Scoped, agent: Agent): void /** - * Agent status changed (`idle` ⇄ `running`). `send()` does not enter - * `running` synchronously; drive lifecycle from this event. + * Agent status changed (`idle` ⇄ `running`). A waking delivery enters + * `running` synchronously after reserving cancellation; `idle` means no + * driver remains scheduled or active. * @param agent - the agent whose status flipped. * @param status - the status just entered (the transition's destination). * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. @@ -235,56 +166,23 @@ declare module 'cordis' { */ 'agent/status'(this: Scoped, agent: Agent, status: AgentStatus): void /** - * An item entered the queued or steering inbox. `placement` is the - * acceptance-time routing result; listeners must not reconstruct it from - * later agent or session state. - * @param agent - the owning agent. - * @param message - accepted content, source, and correlation identity. - * @param placement - resolved queued or steering placement. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/inbox/enqueue'(this: Scoped, agent: Agent, message: UserMessage, placement: InboxPlacement): void - /** - * The driver claimed one item out of the inbox: a queued item at a turn - * boundary, or steering drained between steps. Fires after the item leaves - * its FIFO and before it becomes a durable message. + * The driver admitted one inbox item for model-visible history. * @param agent - the agent whose inbox item was claimed. - * @param message - the claimed message. - * @param placement - the FIFO that claimed this occurrence; together with - * `message.id`, it matches the earliest outstanding enqueue in that FIFO. + * @param message - the admitted message. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode emit */ - 'agent/inbox/dequeue'( - this: Scoped, - agent: Agent, - message: UserMessage, - placement: InboxPlacement, - ): void + 'agent/inbox/admitted'(this: Scoped, agent: Agent, message: UserMessage): void /** - * Pending inbox items were dropped without delivering them, so every - * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR - * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, - * emits this after `agent/cancel-requested` when applicable and before - * aborting the active work. Fires once per drop with every dropped item. + * One pending inbox item was dropped without entering model-visible + * history. `cancel()` without `keepInbox`, including disposal, emits this + * once for each dropped item before aborting active work. * @param agent - the agent whose inbox items were dropped. - * @param messages - the discarded messages in FIFO order (queued then steering); never empty. + * @param message - the dropped message. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode emit */ - 'agent/inbox/discard'(this: Scoped, agent: Agent, messages: UserMessage[]): void - /** - * Effective broad cancellation was requested, before queued/outbox work - * is cleared or the active turn is aborted. This observe-only notification - * cannot veto cancellation; listener failures are contained. - * @param agent - the agent whose current work is being cancelled. - * @param cause - the explicit typed cancellation cause. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/cancel-requested'(this: Scoped, agent: Agent, cause: AgentCancelCause): void - + 'agent/inbox/canceled'(this: Scoped, agent: Agent, message: UserMessage): void // ---- session lifecycle (emit) ---- /** * The session lifecycle began, once before the first turn. Use @@ -300,17 +198,17 @@ declare module 'cordis' { // ---- the machine's extension seams ---- /** - * Allow, rewrite, or block one claimed prompt before it becomes a user - * message or opens a turn. Call `next()` for the unchanged default. The + * Allow, rewrite, or block one claimed inbox batch before it becomes + * model-visible or opens a turn. Call `next()` for the unchanged default. The * signal controls only this admission attempt; listeners may cooperate with * it but must not retain it for a later attempt or turn. - * @param agent - the agent whose turn claimed the message. - * @param message - the frozen claimed message, including identity and source. + * @param agent - the agent whose driver claimed the batch. + * @param messages - the claimed messages. * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ - 'agent/prompt-submit'(this: Scoped, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise): Promise + 'agent/prompt-submit'(this: Scoped, agent: Agent, messages: UserMessage[], signal: AbortSignal, next: () => Promise): Promise /** * Awaited serial checkpoint before EVERY request of a turn is built (the * first as well as each post-tools continuation). The single "between @@ -338,24 +236,17 @@ declare module 'cordis' { */ 'agent/request'(this: Scoped, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise): Promise /** - * Handle a model-request failure after its failed step has closed but - * before the failed turn closes. A listener returns `{ kind: 'retry' }` - * without calling `next()` when it owns the error, or calls `next()` to - * delegate. The default `undefined` leaves the failure terminal. + * Handle one failed model-request attempt before the loop retries or closes + * its step. A listener returns `{ kind: 'retry' }` without calling `next()` + * when it owns recovery, or calls `next()` to delegate. The default + * `undefined` leaves the failure terminal. * @param agent - the agent whose request failed. - * @param turn - the open turn number. - * @param step - the failed step number. - * @param error - the original model-request failure. - * @param failure - serializable facts normalized at the final adapter boundary. - * @param priorFailures - immutable failures that already authorized another - * retry turn in this consecutive sequence. - * @param retryPolicy - immutable policy of the adapter registration that served - * the failed request, or `undefined` if no final adapter served it. + * @param context - request coordinates, provider, normalized failure, and serving policy. * @param signal - the turn abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ - 'agent/request-error'(this: Scoped, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise): Promise + 'agent/request-error'(this: Scoped, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise): Promise /** * The turn is about to close: the model owes no response (no live tool * calls, no fresh steering). Awaited before the boundary commits — a @@ -371,21 +262,6 @@ declare module 'cordis' { * @mode serial */ 'agent/turn-stopping'(this: Scoped, agent: Agent, turn: number, signal: AbortSignal): Promise | void - /** - * One drain chain reached its terminal turn: that turn's `turn/end` is - * already committed. Automatically recovered failed turns do not emit this - * notification, and neither does a run that aborts or fails before its - * `turn/start` commits — there is no durable turn to settle against. - * `reason` says why; model-request recovery is exhausted when an error - * reaches it. - * @param agent - the agent whose turn closed. - * @param turn - the terminal turn number. - * @param reason - why the terminal turn ended, with live error facts when it failed. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/settled'(this: Scoped, agent: Agent, turn: number, reason: SettleReason): void - // ---- error notifications (emit) ---- /** * A step or turn errored. The machine reports a failure here (plus the @@ -400,3 +276,10 @@ declare module 'cordis' { 'agent/error'(this: Scoped, agent: Agent, turn: number, step: number, error: unknown): void } } + +declare module '@deepseek-ai/dsh-session' { + interface SessionEventMap { + /** One message was accepted into the agent inbox. */ + 'agent/inbox/added': UserMessage + } +} diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts index bd560c7c99..b2178aea7e 100644 --- a/packages/core/agent/tests/agent.spec.ts +++ b/packages/core/agent/tests/agent.spec.ts @@ -1,6 +1,5 @@ import { describe, expect, expectTypeOf, it } from 'vitest' import { Context, Service, symbols } from 'cordis' -import type { Events } from 'cordis' import { Session, SessionId } from '@deepseek-ai/dsh-session' import AgentRegistry, { agentEvents, @@ -21,14 +20,11 @@ function stubAgent(rawId: string, overrides: Partial = {}): Agent { options: {}, session: new Session(id), status: 'idle', - acceptsNextStep: false, ctx: new Context(), - send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, - whenIdle() { return Promise.resolve() }, } return Object.assign(agent, overrides) } @@ -188,7 +184,6 @@ describe('agentEvents()', () => { describe('explicit cancellation contract', () => { it('exposes the closed typed cancellation cause at the Agent seam', () => { expectTypeOf[0]>().toEqualTypeOf() - expectTypeOf[1]>().toEqualTypeOf() }) }) diff --git a/packages/core/agent/tsdown.config.ts b/packages/core/agent/tsdown.config.ts index e92275a7f5..3a0934ccf8 100644 --- a/packages/core/agent/tsdown.config.ts +++ b/packages/core/agent/tsdown.config.ts @@ -1,6 +1,6 @@ import { defineConfig } from 'tsdown' -/** Build the package root and optional invariant companion as independent bundles. */ +/** Build the package root and companions as independent bundles. */ export default defineConfig([ { entry: ['lib/types/index.js'], diff --git a/packages/core/scope/src/scoped-events.generated.ts b/packages/core/scope/src/scoped-events.generated.ts index 89515bf3c2..cdcf706fd2 100644 --- a/packages/core/scope/src/scoped-events.generated.ts +++ b/packages/core/scope/src/scoped-events.generated.ts @@ -8,18 +8,15 @@ type ScopedSubjectResolver = (args: readonly unknown[]) => unknown const scopedSubjectResolvers: Readonly> = Object.freeze({ - 'agent/cancel-requested': args => args[0], 'agent/created': args => args[0], 'agent/disposed': args => args[0], 'agent/error': args => args[0], - 'agent/inbox/dequeue': args => args[0], - 'agent/inbox/discard': args => args[0], - 'agent/inbox/enqueue': args => args[0], + 'agent/inbox/admitted': args => args[0], + 'agent/inbox/canceled': args => args[0], 'agent/prompt-submit': args => args[0], 'agent/request': args => args[0], 'agent/request-error': args => args[0], 'agent/session-start': args => args[0], - 'agent/settled': args => args[0], 'agent/status': args => args[0], 'agent/step': args => args[0], 'agent/turn-stopping': args => args[0], diff --git a/packages/core/scope/tests/invariant.spec.ts b/packages/core/scope/tests/invariant.spec.ts index 54f2e1e17b..da30844c2a 100644 --- a/packages/core/scope/tests/invariant.spec.ts +++ b/packages/core/scope/tests/invariant.spec.ts @@ -51,7 +51,6 @@ describe('scoped-dispatch invariants', () => { 'agent/inbox/enqueue': [agent, message, 'queued'], 'agent/inbox/dequeue': [agent, message, 'queued'], 'agent/inbox/discard': [agent, []], - 'agent/cancel-requested': [agent, { kind: 'user' }], 'agent/session-start': [agent, 'startup'], 'agent/step': [agent, 1, 1, signal], 'agent/prompt-submit': [agent, message, signal, () => Promise.resolve({ kind: 'allow' })], @@ -68,7 +67,6 @@ describe('scoped-dispatch invariants', () => { () => Promise.resolve(undefined), ], 'agent/turn-stopping': [agent, 1, signal], - 'agent/settled': [agent, 1, { kind: 'completed' }], 'agent/error': [agent, 1, 0, new Error('x')], } satisfies { [K in AgentEventName]: EventArgs } const rows: Array<[string, unknown[]]> = [ diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml index 9fb097d9fb..56895397fc 100644 --- a/packages/core/session/README.i18n.yaml +++ b/packages/core/session/README.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 packages/core/session/README.md -README.md: a9b6905dcf2b8ef1f75595e567273f7a3150a412 -README.zh.md: f1a5e97e32d1ad1abcd6ad96e6c621af9972e989 +README.md: af93791dfc17f66b79b376ba32ec657761ec63bc +README.zh.md: ed9bba76d307a764a20c7cc4a3d2716c55a1acc0 diff --git a/packages/core/session/README.md b/packages/core/session/README.md index a9b6905dcf..af93791dfc 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -14,7 +14,6 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall - `ctx.sessions.create(id?, { seed?, meta? }?)` validates and detaches durable seed/header data, fills the version and id, defaults `createdAt` to now, publishes the session, and binds it to the calling fiber. Persisted reconstruction supplies its original `createdAt`, `seedLength`, and `delegationDepth`. - `ctx.sessions.flush(session)` dispatches the awaited parallel durability checkpoint through the session's captured scope. Every listener starts and the call waits for all to settle before reporting failure; unpublished, detached, and stale objects reject. -- `findLastMessageTurnEnd(events)` pairs message-triggered starts with their ends and returns the latest matched `turn/end`. Outcome consumers use this fold instead of the raw latest log event because between-turn records and non-message turns have no prompt outcome. - `ctx.sessions.fork(source, boundary?, childSessionId?): Session` — Resolve a live session object or id, select a seed through the inclusive `boundary` event seq (default: current last event), require that prefix to end outside an open turn, and create a live child session with lineage metadata. - `ctx.sessions.get(id: SessionId): Session | undefined` - `ctx.sessions.list(): Session[]` diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md index f1a5e97e32..ed9bba76d3 100644 --- a/packages/core/session/README.zh.md +++ b/packages/core/session/README.zh.md @@ -14,7 +14,6 @@ - `ctx.sessions.create(id?, { seed?, meta? }?)` 校验持久种子／头部数据并生成脱离副本，补齐版本和 id，在未提供 `createdAt` 时使用当前时间，发布会话并将其绑定到调用方 fiber。持久化重建会提供原始的 `createdAt`、`seedLength` 和 `delegationDepth`。 - `ctx.sessions.flush(session)` 通过会话捕获的作用域分发受等待的并行持久性检查点。每个监听器都会启动；调用会等待全部结算后才报告失败。未发布、已脱离和陈旧的对象会被拒绝。 -- `findLastMessageTurnEnd(events)` 将由消息触发的开始与结束配对，并返回最近匹配的 `turn/end`。结果消费方使用该折叠逻辑，而不直接取日志中最近的事件，因为轮次间记录和非消息轮次没有提示词结果。 - `ctx.sessions.fork(source, boundary?, childSessionId?): Session`：解析实时会话对象或 id，选取截至 `boundary` 事件序号（含该事件）的种子（默认为当前最后一个事件），要求所选前缀结束时没有开放轮次，再创建带谱系元数据的实时子会话。 - `ctx.sessions.get(id: SessionId): Session | undefined` - `ctx.sessions.list(): Session[]` diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index e42414503b..5ff000f7fa 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -30,27 +30,6 @@ export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from ' export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts' export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts' -/** - * Find the latest closed message-triggered turn, ignoring other triggers and - * between-turn events. - * @param events - session events, or an owned suffix, to inspect. - * @returns the latest matching turn end, or `undefined`. - */ -export function findLastMessageTurnEnd( - events: readonly SessionEvent[], -): SessionEvent<'turn/end'> | undefined { - const messageTurns = new Set() - let latest: SessionEvent<'turn/end'> | undefined - for (const event of events) { - if (event.type === 'turn/start') { - if (event.data.trigger.kind === 'message') messageTurns.add(event.data.turn) - continue - } - if (event.type === 'turn/end' && messageTurns.delete(event.data.turn)) latest = event - } - return latest -} - declare module 'cordis' { interface Context { sessions: SessionStore diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index 7f3a12b54e..495791f410 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -3,8 +3,6 @@ import type { AssistantMessage, CallId, LlmCallConfig, - LlmFailure, - MessageSource, StreamChunk, TokenUsage, ToolResultMessage, @@ -87,24 +85,12 @@ export interface CreateSessionOptions { } } -/** - * What started a turn. - * Merge-extensible sum type (same pattern as MessageSourceMap). - */ -export interface TurnTriggerMap { - message: { kind: 'message'; source: MessageSource } - /** Recovery turn reopened over the repaired current session log. */ - retry: { kind: 'retry' } - /** - * An out-of-band producer explicitly enclosed injected context in a one-shot - * turn. `Agent.inject()` appends idle context directly and does not use this - * trigger; the source mirrors the producer of the enclosed `user/message`. - */ - injection: { kind: 'injection'; source: MessageSource } -} - -/** The union over {@link TurnTriggerMap} — what started a turn; plugins extend it by merging variants into the map. */ -export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap] +/** Why an active agent driver was cancelled. */ +export type AgentCancelCause = + | { readonly kind: 'user' } + | { readonly kind: 'parent' } + | { readonly kind: 'hook'; readonly reason: string } + | { readonly kind: 'disposed' } /** * Why a turn ended. Merge-extensible sum type. @@ -112,20 +98,11 @@ export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap] export interface TurnEndReasonMap { completed: { kind: 'completed' } /** A cancellation request interrupted the live turn. */ - aborted: { kind: 'aborted' } + aborted: { kind: 'aborted'; reason: AgentCancelCause } /** - * The turn failed: a step threw or the model reported a failure. `step` is the - * step number the failure occurred on (the operational error's location — the - * single durable record of an in-turn failure; live diagnostics also fire via - * `agent/error`). Final model-request failures retain their normalized facts - * as one `failure`; other thrown values retain their rendered message and a - * real `HarnessError` code when present. + * The turn failed. */ - error: { kind: 'error'; step: number } & ( - | { failure: LlmFailure; message?: never; code?: never } - | { message: string; code?: string; failure?: never } - ) - disposed: { kind: 'disposed' } + error: { kind: 'error'; error: unknown } /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */ 'max-tokens': { kind: 'max-tokens' } /** @@ -185,9 +162,11 @@ export type RequestHeaderReason = 'initial' | 'resume' | 'change' */ export interface SessionEventMap { /** - * Opens turn `turn`. `trigger` records what started the model loop. + * Opens turn `turn`. Every turn begins when the loop admits queued input; + * the following identified `user/message` event or batch records the + * admitted input. */ - 'turn/start': { turn: number; trigger: TurnTrigger } + 'turn/start': { turn: number } /** * Closes turn `turn` with the {@link TurnEndReason} that ended it. The loop * awaits `session/flush` after an ordinary turn ends before claiming the next diff --git a/packages/core/session/tests/derived-cache.spec.ts b/packages/core/session/tests/derived-cache.spec.ts index 2c87c0d98e..f44ca3be02 100644 --- a/packages/core/session/tests/derived-cache.spec.ts +++ b/packages/core/session/tests/derived-cache.spec.ts @@ -22,7 +22,7 @@ function scratch(session: Session): unknown { describe('derived-message cache', () => { it('stays deep-equal to a from-scratch replay derivation as the log grows', () => { const session = new Session(SessionId('cache-grow')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) userText(session, 'one') expect(session.deriveMessages()).toEqual(scratch(session)) userText(session, 'two') @@ -55,7 +55,7 @@ describe('derived-message cache', () => { it('rebuilds on a surface replace and still matches scratch', () => { const session = new Session(SessionId('cache-replace')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) userText(session, 'one') userText(session, 'two') const beforeReplace = session.deriveMessages() @@ -73,7 +73,7 @@ describe('derived-message cache', () => { it('returns a fresh array per call: later appends never grow a held snapshot', () => { const session = new Session(SessionId('cache-snapshot')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) userText(session, 'one') const first = session.deriveMessages() userText(session, 'two') @@ -90,7 +90,7 @@ describe('derived-message cache', () => { describe('Session.deriveEventMessage — the per-event projection', () => { it('projects one appended event exactly as the full derivation projects its node', () => { const session = new Session(SessionId('per-event')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const event = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -100,7 +100,7 @@ describe('Session.deriveEventMessage — the per-event projection', () => { it('reuses the logged event\'s already frozen content', () => { const session = new Session(SessionId('per-event-clone')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const event = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'orig' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -114,7 +114,7 @@ describe('Session.deriveEventMessage — the per-event projection', () => { it('projects null for events that produce no message (boundaries, empty assistant)', () => { const session = new Session(SessionId('per-event-null')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const boundary = session.append('step/start', { turn: 1, step: 1 }) expect(session.deriveEventMessage(boundary)).toBeNull() const empty = session.append('assistant/message', { diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts index a317ec565b..dc22ec6512 100644 --- a/packages/core/session/tests/fork.spec.ts +++ b/packages/core/session/tests/fork.spec.ts @@ -22,7 +22,7 @@ function appendClosedTurn( text = `hello ${turn}`, reason: TurnEndReason = { kind: 'completed' }, ): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' }, @@ -31,7 +31,7 @@ function appendClosedTurn( } function appendOpenTurn(session: Session, turn: number): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `open ${turn}` }], source: { kind: 'user' }, @@ -205,23 +205,23 @@ describe('SessionStore.fork', () => { const { ctx, sessions } = await setup() const cases: [string, (session: Session) => number][] = [ ['turn/start', (session) => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) return lastSeq(session) }], ['step/start', (session) => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) return lastSeq(session) }], ['user/message', (session) => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'open' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) return lastSeq(session) }], ['assistant/message', (session) => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('assistant/message', { turn: 1, step: 1, @@ -238,7 +238,7 @@ describe('SessionStore.fork', () => { }], ['tool/call', (session) => { const callId = CallId('call-open') - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('assistant/message', { turn: 1, @@ -279,7 +279,7 @@ describe('SessionStore.fork', () => { it('rejects a duplicate child session id before validating the boundary', async () => { const { ctx, sessions } = await setup() const source = ctx.sessions.create(SessionId('open-parent')) - source.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + source.append('turn/start', { turn: 1 }) ctx.sessions.create(SessionId('child')) expect(() => sessions.fork(source, undefined, SessionId('child'))) diff --git a/packages/core/session/tests/invariant.spec.ts b/packages/core/session/tests/invariant.spec.ts index aa0cd5bd64..d4b71e0da2 100644 --- a/packages/core/session/tests/invariant.spec.ts +++ b/packages/core/session/tests/invariant.spec.ts @@ -26,7 +26,7 @@ describe('session-log invariants', () => { await scopedCtx.plugin(SessionInvariant) const session = ctx.sessions.create(SessionId('global-under-scoped-invariants')) expect(() => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }).not.toThrow() }) @@ -35,7 +35,7 @@ describe('session-log invariants', () => { const { ctx } = await setup() const session = ctx.sessions.create() expect(() => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -78,11 +78,10 @@ describe('session-log invariants', () => { }) expect(() => session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, })).toThrow('later dispatch veto') expect(session.events).toEqual([]) expect(() => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }).not.toThrow() }) @@ -94,7 +93,7 @@ describe('session-log invariants', () => { const session = ctx.sessions.create(SessionId('postcommit-peer')) ctx.on('session/event', () => { throw new Error('hostile observer') }, { prepend: true }) expect(() => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }).not.toThrow() expect(warnings).toHaveLength(2) @@ -107,7 +106,7 @@ describe('session-log invariants', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, } as never) expect(() => { ctx.emit(scopeTarget(session, undefined), 'session/event', session, { type: 'turn/end', @@ -120,16 +119,16 @@ describe('session-log invariants', () => { it('enforces turn numbering and core execution enclosure', async () => { const first = await setup() const open = first.ctx.sessions.create() - open.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - expect(() => open.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })) + open.append('turn/start', { turn: 1 }) + expect(() => open.append('turn/start', { turn: 2 })) .toThrow(/turn 1 is still open/) expect(() => open.append('turn/end', { turn: 2, reason: { kind: 'completed' } })) .toThrow(/does not match open turn 1/) const second = (await setup()).ctx.sessions.create() - second.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + second.append('turn/start', { turn: 1 }) second.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - expect(() => second.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })) + expect(() => second.append('turn/start', { turn: 3 })) .toThrow(/expected turn 2, got 3/) const outside = (await setup()).ctx.sessions.create() @@ -149,17 +148,16 @@ describe('session-log invariants', () => { expect(() => { appendUnknown('plugin/marker', {}) }).not.toThrow() expect(() => outside.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, })).not.toThrow() }) it('enforces open-step identity and numbering', async () => { const wrongTurn = (await setup()).ctx.sessions.create() - wrongTurn.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + wrongTurn.append('turn/start', { turn: 1 }) expect(() => wrongTurn.append('step/start', { turn: 2, step: 1 })).toThrow(/open turn is 1/) const nested = (await setup()).ctx.sessions.create() - nested.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + nested.append('turn/start', { turn: 1 }) nested.append('step/start', { turn: 1, step: 1 }) expect(() => nested.append('step/start', { turn: 1, step: 2 })).toThrow(/while step 1 is still open/) expect(() => nested.append('turn/end', { turn: 1, reason: { kind: 'completed' } })) @@ -179,7 +177,7 @@ describe('session-log invariants', () => { }, { surfaceOp: 'append' })).toThrow(/open is turn 1\/step 1/) const skipped = (await setup()).ctx.sessions.create() - skipped.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + skipped.append('turn/start', { turn: 1 }) skipped.append('step/start', { turn: 1, step: 1 }) skipped.append('step/end', { turn: 1, step: 1 }) expect(() => skipped.append('step/start', { turn: 1, step: 3 })) @@ -188,7 +186,7 @@ describe('session-log invariants', () => { it('requires step-scoped stream and tool events to name the open step', async () => { const chunk = (await setup()).ctx.sessions.create() - chunk.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + chunk.append('turn/start', { turn: 1 }) expect(() => chunk.append('assistant/chunk', { turn: 1, step: 1, @@ -196,7 +194,7 @@ describe('session-log invariants', () => { })).toThrow(/open is turn 1\/step null/) const tool = (await setup()).ctx.sessions.create() - tool.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + tool.append('turn/start', { turn: 1 }) tool.append('step/start', { turn: 1, step: 1 }) expect(() => tool.append('tool/result', { turn: 1, @@ -212,7 +210,7 @@ describe('session-log invariants', () => { it('keeps fresh tool-result appends open-step checked', async () => { const { ctx } = await setup() const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) expect(() => session.append('tool/result', { turn: 1, step: 1, @@ -227,7 +225,7 @@ describe('session-log invariants', () => { it('treats a validated tool-result replacement as a turn-enclosed rewrite', async () => { const { ctx } = await setup() const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('tool/call', { turn: 1, @@ -248,7 +246,7 @@ describe('session-log invariants', () => { session.append('step/end', { turn: 1, step: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 2 }) expect(() => session.append('tool/result', { ...original.data, message: freezeMessage({ @@ -267,7 +265,7 @@ describe('session-log invariants', () => { it('rejects a tool-result replacement outside a turn', async () => { const { ctx } = await setup() const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('tool/call', { turn: 1, @@ -306,7 +304,7 @@ describe('session-log invariants', () => { it('allows not-started repair results and unresolved calls at step end', async () => { const repaired = (await setup()).ctx.sessions.create() expect(() => { - repaired.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + repaired.append('turn/start', { turn: 1 }) repaired.append('step/start', { turn: 1, step: 1 }) repaired.append('tool/result', { turn: 1, @@ -324,7 +322,7 @@ describe('session-log invariants', () => { const unresolved = (await setup()).ctx.sessions.create() expect(() => { - unresolved.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + unresolved.append('turn/start', { turn: 1 }) unresolved.append('step/start', { turn: 1, step: 1 }) unresolved.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' }) unresolved.append('step/end', { turn: 1, step: 1 }) @@ -335,7 +333,7 @@ describe('session-log invariants', () => { it('does not let a result in a later step satisfy an earlier call', async () => { const { ctx } = await setup() const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' }) session.append('step/end', { turn: 1, step: 1 }) @@ -354,22 +352,22 @@ describe('session-log invariants', () => { it('replays seeded sessions and tracks each session independently', async () => { const { ctx } = await setup() const badSeed = [ - { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } }, - { type: 'turn/start' as const, seq: 1, time: 0, data: { turn: 2, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } }, + { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1 } }, + { type: 'turn/start' as const, seq: 1, time: 0, data: { turn: 2 } }, ] expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(InvariantError) const a = ctx.sessions.create(SessionId('a')) const b = ctx.sessions.create(SessionId('b')) - a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - expect(() => b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })) + a.append('turn/start', { turn: 1 }) + expect(() => b.append('turn/start', { turn: 1 })) .not.toThrow() }) it('rebuilds trace state for sessions that exist when the companion reloads', async () => { const { ctx, fiber } = await setup() const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) await fiber.dispose() await ctx.plugin(SessionInvariant) @@ -378,18 +376,17 @@ describe('session-log invariants', () => { step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' }, })).not.toThrow() - expect(() => session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })) + expect(() => session.append('turn/start', { turn: 2 })) .toThrow(/turn 1 is still open/) }) it('removes all listeners when the companion is disposed', async () => { const { ctx, fiber } = await setup() const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await fiber.dispose() expect(() => session.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, })).not.toThrow() }) }) diff --git a/packages/core/session/tests/properties.spec.ts b/packages/core/session/tests/properties.spec.ts index 1449f3684e..365408861d 100644 --- a/packages/core/session/tests/properties.spec.ts +++ b/packages/core/session/tests/properties.spec.ts @@ -70,7 +70,7 @@ const messageEventArb: fc.Arbitrary = fc.oneof( // A non-message event (trace/replay data — must NOT affect derived history). const nonMessageEventArb: fc.Arbitrary = fc.oneof( - fc.constant({ type: 'turn/start', data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + fc.constant({ type: 'turn/start', data: { turn: 1 } }), fc.constant({ type: 'turn/end', data: { turn: 1, reason: { kind: 'completed' } } }), fc.constant({ type: 'step/start', data: { turn: 1, step: 1 } }), fc.constant({ type: 'step/end', data: { turn: 1, step: 1 } }), diff --git a/packages/core/session/tests/repair.spec.ts b/packages/core/session/tests/repair.spec.ts index 645d7d6921..941819c0af 100644 --- a/packages/core/session/tests/repair.spec.ts +++ b/packages/core/session/tests/repair.spec.ts @@ -13,7 +13,7 @@ import type { SessionEvent, SurfaceEvent } from '../src/index.ts' */ const userTurnStart = (turn: number, seq: number): SessionEvent => - ({ type: 'turn/start', seq, time: seq, data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }) + ({ type: 'turn/start', seq, time: seq, data: { turn } }) describe('interruptedTurnClosers', () => { it('returns nothing for a balanced log (ends on turn/end)', () => { diff --git a/packages/core/session/tests/request-header.spec.ts b/packages/core/session/tests/request-header.spec.ts index 53c76a5298..f795a8a79c 100644 --- a/packages/core/session/tests/request-header.spec.ts +++ b/packages/core/session/tests/request-header.spec.ts @@ -45,7 +45,7 @@ describe('foldRequestHeader', () => { it('returns the supplied baseline when no snapshot follows', () => { const from: EpochHeader = { config: CONFIG, system: 'baseline' } const unrelated: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, ] expect(foldRequestHeader(unrelated)).toBeUndefined() expect(foldRequestHeader(unrelated, from)).toBe(from) @@ -53,7 +53,7 @@ describe('foldRequestHeader', () => { it('takes the latest full snapshot and skips unrelated events', () => { const session = new Session(SessionId('fold')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('request/header', { header: { config: CONFIG, system: 'first' }, reason: 'initial' }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, diff --git a/packages/core/session/tests/scoped.spec.ts b/packages/core/session/tests/scoped.spec.ts index 7a5e617254..ad58f07ddd 100644 --- a/packages/core/session/tests/scoped.spec.ts +++ b/packages/core/session/tests/scoped.spec.ts @@ -40,7 +40,7 @@ describe('session dispatch carriers', () => { otherScope.ctx.on('session/created', session => void heard.push(`other-created:${session.id}`)) const session = scope.ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) expect(heard).toEqual([ `owner-created:${session.id}`, @@ -57,7 +57,7 @@ describe('session dispatch carriers', () => { scope.ctx.on('session/event', (_s, event) => void heard.push(`owner:${event.type}`)) const bare = ctx.sessions.create() - bare.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + bare.append('turn/start', { turn: 1 }) expect(heard).toEqual(['global:turn/start']) }) diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts index 7152dd5d41..ab4c84b1e7 100644 --- a/packages/core/session/tests/session.spec.ts +++ b/packages/core/session/tests/session.spec.ts @@ -2,7 +2,6 @@ import { describe, expect, expectTypeOf, it, vi } from 'vitest' import { Context } from 'cordis' import { createUserMessage, CallId, createMessage, createToolResultMessage, MessageId, ReasoningEffortId } from '@deepseek-ai/dsh-llm' import SessionStore, { - findLastMessageTurnEnd, SESSION_FORMAT_VERSION, Session, SessionEvent, @@ -22,7 +21,7 @@ describe('Session', () => { it('derives message history from the event log', () => { const session = new Session(SessionId('s1')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -62,7 +61,7 @@ describe('Session', () => { // The max-tokens TurnEndReason variant carries no extra data, so it must // append and persist like any other reason (JSON-serializable, no fields). const session = new Session(SessionId('s1')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'max-tokens' } }) const turnEnd = session.events.findLast(e => e.type === 'turn/end')! @@ -71,45 +70,9 @@ describe('Session', () => { expect(structuredClone(turnEnd.data.reason)).toEqual({ kind: 'max-tokens' }) }) - it('finds the latest message-turn outcome past later non-message turns', () => { - const session = new Session(SessionId('message-turn-outcome')) - expect(findLastMessageTurnEnd(session.events)).toBeUndefined() - session.append('turn/start', { - turn: 1, - trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'before' } }, - }) - session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'before' }], - source: { kind: 'plugin', plugin: 'before' }, - }), { surfaceOp: 'append' }) - session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - expect(findLastMessageTurnEnd(session.events)).toBeUndefined() - - session.append('turn/start', { - turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, - }) - session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'bounded prompt' }], - source: { kind: 'user' }, - }), { surfaceOp: 'append' }) - const messageEnd = session.append('turn/end', { turn: 2, reason: { kind: 'max-tokens' } }) - session.append('turn/start', { - turn: 3, - trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'after' } }, - }) - session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'after' }], - source: { kind: 'plugin', plugin: 'after' }, - }), { surfaceOp: 'append' }) - session.append('turn/end', { turn: 3, reason: { kind: 'completed' } }) - - expect(findLastMessageTurnEnd(session.events)).toBe(messageEnd) - }) - it('round-trips the coarse aborted turn outcome', () => { const session = new Session(SessionId('aborted')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) const replayed = new Session(SessionId('aborted-replay'), structuredClone(session.events)) expect(replayed.events).toEqual(session.events) @@ -121,7 +84,7 @@ describe('Session', () => { const legacy = [ { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }, { type: 'turn/end', seq: 1, time: 2, @@ -169,7 +132,7 @@ describe('Session', () => { it('replays identically from a seeded event log', () => { const original = new Session(SessionId('s3')) - original.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + original.append('turn/start', { turn: 1 }) original.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -346,13 +309,13 @@ describe('Session', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }) expect(boundary).toEqual({ type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }) const extended = snapshotSessionEvent({ @@ -463,7 +426,7 @@ describe('Session', () => { it('rejects a surface-eligible append with no surfaceOp marker (runtime guard for the union-widening loophole)', () => { const session = new Session(SessionId('s5b')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) // A widened SessionEventType bypasses the overload's conditional requirement, // so the runtime guard must still reject the missing surface marker. const widenedType = 'user/message' as SessionEventType @@ -492,7 +455,7 @@ describe('Session', () => { it('validates seed events: rejects a non-contiguous seq', () => { const gapSeed = [ - { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } }, + { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1 } }, { type: 'turn/end' as const, seq: 5, time: 2, data: { turn: 1, reason: { kind: 'completed' as const } } }, // gap: expected seq 1 ] as SessionEvent[] expect(() => new Session(SessionId('seed-gap'), gapSeed)).toThrow(/contiguous|seq/) @@ -504,7 +467,7 @@ describe('Session', () => { // so a resume/fork would silently lose history. append() forbids this at // compile time; a raw seed must be rejected at runtime to match. const markerlessSeed = [ - { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } }, + { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message' as const, seq: 1, time: 2, data: createUserMessage({ content: [{ type: 'text' as const, text: 'hi' }], source: { kind: 'user' as const }, }) }, @@ -515,7 +478,7 @@ describe('Session', () => { it('accepts a well-formed contiguous serializable seed', () => { const goodSeed = [ - { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } }, + { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message' as const, seq: 1, time: 2, data: createUserMessage({ content: [{ type: 'text' as const, text: 'hi' }], source: { kind: 'user' as const }, }), surfaceOp: 'append' as const }, @@ -530,7 +493,7 @@ describe('Session', () => { type: 'turn/start' as const, seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } }, + data: { turn: 1 }, } const drifted = { ...accepted, seq: 99, data: { invalid: 1n } } let reads = 0 @@ -606,7 +569,7 @@ describe('Session', () => { readonly type = 'turn/start' as const readonly seq = 0 readonly time = 1 - readonly data = { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } + readonly data = { turn: 1 } } const seed: SessionEvent[] = [new SeedEvent()] @@ -619,7 +582,7 @@ describe('Session', () => { type: 'turn/start' as const, seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } }, + data: { turn: 1 }, }) as unknown as SessionEvent const session = new Session(SessionId('seed-null-prototype'), [event]) @@ -701,7 +664,7 @@ describe('Session', () => { it('snapshots the seed: mutating the original after construction does not affect session.events', () => { const seed = [ - { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } }, + { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message' as const, seq: 1, time: 2, data: { id: MessageId('seed-input'), role: 'user' as const, @@ -852,14 +815,14 @@ describe('Session', () => { expect(() => appendRaw( 'turn/start', - { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + { turn: 1 }, { surfaceOp: 'append' }, )).toThrow(/not surface-eligible and cannot carry surfaceOp/) expect(() => new Session(SessionId('non-surface-metadata-seed'), [{ type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, surfaceOp: 'append', } as unknown as SessionEvent])).toThrow(/invalid seed event.*not surface-eligible/) expect(session.events).toEqual([]) @@ -870,13 +833,12 @@ describe('Session', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }]) const seededEvent = seeded.events[0]! if (seededEvent.type !== 'turn/start') throw new Error('test fixture must remain a turn/start') expect(Object.isFrozen(seededEvent)).toBe(true) expect(Object.isFrozen(seededEvent.data)).toBe(true) - expect(Object.isFrozen(seededEvent.data.trigger)).toBe(true) expect(() => { seededEvent.data.turn = 99 }).toThrow(TypeError) const appended = new Session(SessionId('append-frozen')) @@ -892,7 +854,7 @@ describe('Session', () => { it('returns cached frozen event-array snapshots that do not grow after append', () => { const session = new Session(SessionId('events-snapshot')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const before = session.events const beforeEvent = before[0]! if (beforeEvent.type !== 'turn/start') throw new Error('test fixture must remain a turn/start') @@ -989,7 +951,7 @@ describe('Session', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, } const cases: unknown[] = [ { ...base, extra: true }, @@ -1028,7 +990,7 @@ describe('SessionStore', () => { // may create an unrelated property with the old implementation's name, // but cannot suppress the durable event feed. expect(Reflect.set(session, 'onAppend', undefined)).toBe(true) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -1046,7 +1008,7 @@ describe('SessionStore', () => { const a = ctx.sessions.create(SessionId('fixed')) expect(() => ctx.sessions.create(SessionId('fixed'))).toThrow('already exists') - a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + a.append('turn/start', { turn: 1 }) a.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -1295,7 +1257,7 @@ describe('SessionStore', () => { ctx.on('session/event', (_session, event) => void events.push(event)) const session = ctx.sessions.create(SessionId('fixed')) expect(ctx.sessions.get(SessionId('fixed'))).toBe(session) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -1321,7 +1283,6 @@ describe('SessionStore', () => { expect(() => { appended = session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) }).not.toThrow() expect(committedBeforeNotify).toBe(true) @@ -1360,14 +1321,12 @@ describe('SessionStore', () => { expect(() => session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, })).toThrow('reject first candidate') expect(session.events).toEqual([]) expect(observed).toEqual([]) const appended = session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) expect(validations.map(({ logLength, frozen }) => ({ logLength, frozen }))).toEqual([ { logLength: 0, frozen: true }, @@ -1383,7 +1342,7 @@ describe('SessionStore', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('surface-dispatch-veto')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'source' }], @@ -1438,7 +1397,6 @@ describe('SessionStore', () => { expect(() => session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, })).toThrow('dispatch instrumentation rejected the carrier') expect(session.events).toEqual([]) expect(observed).toEqual([]) @@ -1458,7 +1416,6 @@ describe('SessionStore', () => { const appended = session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) expect(session.events).toEqual([appended]) expect(heard).toEqual([appended]) @@ -1489,7 +1446,6 @@ describe('SessionStore', () => { const appended = session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) expect(session.events).toEqual([appended]) @@ -1640,7 +1596,7 @@ describe('todo/write event', () => { it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => { const original = new Session(SessionId('t4')) - original.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + original.append('turn/start', { turn: 1 }) original.append('todo/write', { todos: [{ content: 'only', status: 'completed' }] }) original.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) // Seeding a non-surface event with no surfaceOp must not throw. diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts index 4078f526e6..c4901f113e 100644 --- a/packages/core/session/tests/surface.spec.ts +++ b/packages/core/session/tests/surface.spec.ts @@ -19,7 +19,7 @@ import { /** Build a minimal session with turn boundaries and a single user message. */ function surfaceSession(): Session { const s = new Session(SessionId('ss')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s.append('turn/start', { turn: 1 }) s.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -93,7 +93,7 @@ describe('foldSurface provenance', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, sourceEventSeqs: [0], } as unknown as SessionEvent expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/) @@ -378,7 +378,7 @@ describe('SurfaceManager', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, surfaceOp: 'append', } as unknown as SessionEvent @@ -396,7 +396,7 @@ describe('SurfaceManager', () => { it('empty surface yields empty nodes', () => { const s = new Session(SessionId('empty')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s.append('turn/start', { turn: 1 }) s.append('step/start', { turn: 1, step: 1 }) s.append('step/end', { turn: 1, step: 1 }) s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) @@ -665,7 +665,7 @@ describe('deriveMessages with surface', () => { it('surface path skips non-surface events (chunks, boundaries)', () => { const s = new Session(SessionId('filter')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s.append('turn/start', { turn: 1 }) s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } }) s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 1, text: 'i' } }) s.append('user/message', createUserMessage({ @@ -731,7 +731,7 @@ describe('deriveMessages with surface', () => { describe('Session.append surface opts', () => { it('records sourceEventSeqs and surfaceOp on the event', () => { const s = new Session(SessionId('opts')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s.append('turn/start', { turn: 1 }) s.append('step/start', { turn: 1, step: 1 }) const event = s.append('assistant/message', { @@ -759,7 +759,7 @@ describe('Session.append surface opts', () => { // but _deriveOneMessage returns null for it, so the surface derivation path's // null-check is exercised — the node is on the surface yet produces no message. const seed: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } }, { type: 'assistant/message', seq: 2, time: 3, data: { turn: 1, step: 1, @@ -782,7 +782,7 @@ describe('Session.append surface opts', () => { it('a non-surface event carries no surface fields', () => { const s = new Session(SessionId('noopts')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s.append('turn/start', { turn: 1 }) expect((s.events[0] as SessionEvent).sourceEventSeqs).toBeUndefined() expect((s.events[0] as SessionEvent).surfaceOp).toBeUndefined() }) @@ -816,7 +816,7 @@ describe('Session.append surface opts', () => { } expect(isSurfaceEvent(noMarker)).toBe(false) // A non-surface type is rejected too (the type gate). - const boundary: SessionEvent = { type: 'turn/start', seq: 1, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } } + const boundary: SessionEvent = { type: 'turn/start', seq: 1, time: 1, data: { turn: 1 } } expect(isSurfaceEvent(boundary)).toBe(false) // A properly-marked surface event narrows. const marked = { ...noMarker, surfaceOp: 'append' } as SurfaceEvent @@ -866,7 +866,7 @@ describe('surface type guards', () => { describe('SurfaceManager.replaceGeneration', () => { it('folds the pending log delta on access and counts replaces', () => { const s = new Session(SessionId('gen')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s.append('turn/start', { turn: 1 }) s.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'one' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) diff --git a/packages/core/tools/tests/invariant.spec.ts b/packages/core/tools/tests/invariant.spec.ts index f703934a5d..80ae299da7 100644 --- a/packages/core/tools/tests/invariant.spec.ts +++ b/packages/core/tools/tests/invariant.spec.ts @@ -98,7 +98,7 @@ describe('tool-pipeline invariants', () => { arguments: {}, } expect(() => session.append('tool/code-dispatch-start', data)).toThrow(/outside any open turn/) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) expect(() => session.append('tool/code-dispatch-start', data)).not.toThrow() session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }) @@ -107,7 +107,7 @@ describe('tool-pipeline invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('tool/code-dispatch', { parentCallId: CallId('parent'), subCallId: CallId('child'), diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts index 5a6f89525c..8f555c0238 100644 --- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts +++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts @@ -163,7 +163,6 @@ describe('dsh-agent-spine-demo bundle', () => { const session = ctx.sessions.create(SessionId('configured-title-limits')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'One two three four' }], @@ -206,8 +205,8 @@ describe('dsh-agent-spine-demo bundle', () => { it('mounts package companions and forwards invariant selection config', async () => { const nestedTurn = (ctx: Context): void => { const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) + session.append('turn/start', { turn: 2 }) } const enabled = await mount({ workspaceContext: false }) diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts index 370379fb55..fc77b11331 100644 --- a/packages/examples/cli-demo/tests/cli.spec.ts +++ b/packages/examples/cli-demo/tests/cli.spec.ts @@ -388,14 +388,14 @@ describe('runOneShot and executeCli', () => { if (subject !== agent || injected) return injected = true agent.inject(createUserMessage({ content: [{ type: 'text', text: 'startup injection' }], source: { kind: 'plugin', plugin: 'test' } })) - other.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'test' } } }) + other.append('turn/start', { turn: 1 }) other.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }) const output = await invoke(ctx, ['--output-format', 'stream-json', 'task']) const lines = output.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record) const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent) expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, turn: 1, result: 'streamed' }) - expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 1, trigger: { kind: 'message' } } }) + expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 1 } }) expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 1 } }) expect(lines.slice(0, -1).every(line => line['sessionId'] === agent.session.id)).toBe(true) expect(events.some(event => event.type === 'user/message' @@ -510,11 +510,9 @@ describe('formatTurnFailure', () => { it('diagnoses every durable reason and preserves merge-extensible unknowns', () => { const cases: [TurnEndReason, string][] = [ [{ kind: 'completed' }, 'completed'], - [{ kind: 'aborted' }, 'was aborted'], - [{ kind: 'aborted' }, 'was aborted'], - [{ kind: 'error', step: 2, message: 'bad' }, 'failed at step 2: bad'], - [{ kind: 'error', step: 3, failure: { message: 'provider bad', code: 'SERVER' } }, 'failed at step 3: provider bad'], - [{ kind: 'disposed' }, 'was disposed'], + [{ kind: 'aborted', reason: { kind: 'user' } }, 'was aborted'], + [{ kind: 'error', error: new Error('bad') }, 'failed: bad'], + [{ kind: 'error', error: { message: 'provider bad', code: 'SERVER' } }, 'provider bad'], [{ kind: 'max-tokens' }, 'output-token limit'], [{ kind: 'interrupted' }, 'persistence recovery'], ] diff --git a/packages/goal/command-goal/tests/command-goal.spec.ts b/packages/goal/command-goal/tests/command-goal.spec.ts index 61734ada01..ed3a1f6b2d 100644 --- a/packages/goal/command-goal/tests/command-goal.spec.ts +++ b/packages/goal/command-goal/tests/command-goal.spec.ts @@ -20,7 +20,7 @@ interface Harness { function appendInjection(session: Session, input: UserMessage): void { const lastStart = session.events.findLast(event => event.type === 'turn/start') const turn = (lastStart?.data.turn ?? 0) + 1 - session.append('turn/start', { turn, trigger: { kind: 'injection', source: input.source } }) + session.append('turn/start', { turn }) session.append('user/message', input, { surfaceOp: 'append' }) session.append('turn/end', { turn, reason: { kind: 'completed' } }) } @@ -37,7 +37,6 @@ function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } ctx: new Context(), get status() { return status }, get acceptsNextStep() { return status === 'running' }, - send: () => {}, followup: () => {}, steer: () => {}, inject(input) { appendInjection(session, input) }, diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index 31dbe9c4e6..fe2f01b0e4 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -9,7 +9,7 @@ import type { Context } from 'cordis' import type { Agent, PromptDecision } from '@deepseek-ai/dsh-agent' import type { GoalMessageSource, GoalRef, GoalView } from '@deepseek-ai/dsh-goal' import { createUserMessage, assertNever } from '@deepseek-ai/dsh-llm' -import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm' +import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm' import type { Session, SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' import { classifyGoalRound } from './outcome.ts' import type { GoalRoundOutcome } from './outcome.ts' @@ -33,6 +33,7 @@ interface RoundIdentity { /** One queued or admitted attempt, retained until its physical turn settles. */ interface RoundAttempt extends RoundIdentity { + readonly messageId: MessageId readonly content: ContentBlock[] phase: 'queued' | 'admitted' turn: number | undefined @@ -214,10 +215,15 @@ export function apply(ctx: Context): void { const round = goal.roundsStarted + 1 const content = renderGoalRoundPrompt(goal, round) + const message = createUserMessage({ + content, + source: { kind: 'goal', goalId: goal.id, revision: goal.revision, round }, + }) const reservation: RoundAttempt = { goalId: goal.id, revision: goal.revision, round, + messageId: message.id, content, phase: 'queued', turn: undefined, @@ -226,7 +232,7 @@ export function apply(ctx: Context): void { } state.attempt = reservation try { - agent.followup(createUserMessage({ content, source: { kind: 'goal', goalId: goal.id, revision: goal.revision, round } })) + agent.followup(message) } catch (error: unknown) { state.attempt = undefined ctx.logger.warn(`goal-session: could not queue round ${round} for agent "${agent.id}": ${renderThrown(error)}`) @@ -277,9 +283,8 @@ export function apply(ctx: Context): void { }) } - // One composite effect owns every listener and the quiescent close. Cordis - // unloads sibling effects concurrently; nesting makes the close run first - // and keeps the admission fence installed until its drain settles. + // One composite effect keeps the admission fence installed until this + // plugin's own scheduling tasks settle. ctx.effect(function* () { /** Mark a post-turn persistence failure before idle scheduling can run. */ ctx.on('agent/error', (agent, turn) => { @@ -304,40 +309,21 @@ export function apply(ctx: Context): void { const state = stateFor(agent) if (status === 'idle') { state.competingQueued = false + const attempt = state.attempt + const goal = currentGoal(state) + if (attempt !== undefined && attempt.turn === undefined && attempt.reason === undefined + && goal?.phase === 'active' && goal.activation === 'armed') { + state.attempt = undefined + try { + applyOutcome(state, goal, { kind: 'pause', reason: 'cancelled' }) + } catch (error: unknown) { + ctx.logger.warn(`goal-session: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`) + disarm(state) + } + } requestDrive(state) } }) - ctx.on('agent/inbox/enqueue', (agent, info) => { - const state = stateFor(agent) - const attempt = state.attempt - if (attempt !== undefined && sameQueued(info.content, info.source, attempt)) return - state.competingQueued = true - if (attempt?.phase === 'queued') attempt.stale = true - }) - ctx.on('agent/cancel-requested', (agent, cause) => { - const state = stateFor(agent) - const attempt = state.attempt - state.competingQueued = false - const goal = currentGoal(state) - if (goal?.phase === 'active' && goal.activation === 'armed') { - if (attempt === undefined) { - disarm(state) - return - } - // An admitted round closes durably as aborted; retain it so the normal - // turn outcome path appends pause after cancellation reaches idle. - // Pausing here would stage context into the active outbox only for this - // same cancel() call to discard it. - if (attempt.turn !== undefined || attempt.phase === 'admitted') return - state.attempt = undefined - try { - applyOutcome(state, goal, { kind: 'pause', reason: cause.kind }) - } catch (error: unknown) { - ctx.logger.warn(`goal-session: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`) - disarm(state) - } - } - }) ctx.on('goal/changed', (agent) => { const state = stateFor(agent) state.needsCheckpoint = true @@ -349,35 +335,22 @@ export function apply(ctx: Context): void { if (agent === undefined || agent.session !== session) return const state = stateFor(agent) switch (event.type) { - case 'turn/start': + case 'agent/inbox/added': { + const attempt = state.attempt + const { content, source } = event.data + if (attempt !== undefined && sameQueued(content, source, attempt)) return + state.competingQueued = true + if (attempt?.phase === 'queued') attempt.stale = true + return + } + case 'turn/start': { state.openTurn = event.data.turn - switch (event.data.trigger.kind) { - case 'message': - if (state.attempt !== undefined && isGoalRoundSource(event.data.trigger.source) - && sameRound(event.data.trigger.source, state.attempt)) { - state.attempt.turn = event.data.turn - } - return - case 'retry': - // A recovery policy (llm-retry) closed the round's failed turn - // and reopened its history: the attempt rides the retry turn, - // and the failed turn's provisional reason no longer settles - // the round — the retry's own outcome does. - if (state.attempt !== undefined && state.attempt.reason !== undefined - && state.attempt.reason.kind === 'error') { - state.attempt.turn = event.data.turn - state.attempt.reason = undefined - } - return - default: - // Injection and merge-extensible plugin triggers cannot admit a queued goal message. - return - } + return + } case 'user/message': - if (state.attempt !== undefined && isGoalRoundSource(event.data.source) - && sameRound(event.data.source, state.attempt)) { + if (state.attempt !== undefined && event.data.id === state.attempt.messageId) { state.attempt.phase = 'admitted' - /* v8 ignore next -- this driver's admitted message always follows its observed turn/start */ + /* v8 ignore next -- the loop logs admitted input inside an open turn */ if (state.openTurn !== undefined) state.attempt.turn = state.openTurn } return @@ -407,8 +380,10 @@ export function apply(ctx: Context): void { && source.round === goal.roundsStarted + 1 } - ctx.on('agent/prompt-submit', async (agent, message, _signal, next): Promise => { - const { content, source } = message + ctx.on('agent/prompt-submit', async (agent, messages, _signal, next): Promise => { + const submitted = messages.find(message => isGoalRoundSource(message.source)) + if (submitted === undefined) return next() + const { content, source } = submitted if (!isGoalRoundSource(source)) return next() const state = stateFor(agent) let valid = false @@ -494,7 +469,6 @@ export function apply(ctx: Context): void { if (attempt.phase === 'admitted' && state.agent.status === 'running') { state.agent.cancel({ kind: 'parent' }) } - waits.push(state.agent.whenIdle()) } if (state.run !== undefined) waits.push(state.run) } diff --git a/packages/goal/goal-session/src/outcome.ts b/packages/goal/goal-session/src/outcome.ts index e138bf2030..29615231a0 100644 --- a/packages/goal/goal-session/src/outcome.ts +++ b/packages/goal/goal-session/src/outcome.ts @@ -28,15 +28,17 @@ export function classifyGoalRound(reason: TurnEndReason, durable: boolean): Goal case 'aborted': return { kind: 'pause', reason: 'cancelled' } case 'error': { - const { code, message } = reason.failure ?? reason + const error = reason.error + const code = typeof error === 'object' && error !== null && 'code' in error + ? error.code + : undefined + const message = error instanceof Error ? error.message : String(error) return code === 'RATE_LIMIT' || code === 'QUOTA' ? { kind: 'blocked', code: 'usage-limited', message } : { kind: 'blocked', code: 'turn-error', message } } case 'max-tokens': return { kind: 'blocked', code: 'max-tokens', message: 'model output reached max tokens' } - case 'disposed': - return { kind: 'disarm', reason: 'disposed' } case 'interrupted': return { kind: 'disarm', reason: 'interrupted' } // TurnEndReason is merge-extensible. An unknown producer cannot opt into diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index 6a11633384..6766f25e95 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -12,13 +12,6 @@ import { SessionId } from '@deepseek-ai/dsh-session' import type { TurnEndReason } from '@deepseek-ai/dsh-session' import * as goalSession from '../src/index.ts' -declare module '@deepseek-ai/dsh-session' { - interface TurnTriggerMap { - /** Test-only plugin turn with no message source. */ - 'test-metadata': { kind: 'test-metadata' } - } -} - type ScriptEntry = StreamChunk[] | Error | 'hang' | ((options: GenerateOptions) => StreamChunk[]) /** Small request-recording adapter with controllable failure and cancellation. */ @@ -334,31 +327,6 @@ describe('same-session goal driving', () => { expect(requestText(test.adapter.requests[1]!)).toContain('') }) - it('ignores plugin-owned turn triggers while a goal round is queued', async () => { - const test = await harness([textResponse('goal answer')]) - const warnings: string[] = [] - test.ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof test.ctx.logger.warn - let inserted = false - test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent !== test.agent || info.source.kind !== 'goal' || inserted) return - inserted = true - const lastStart = agent.session.events.findLast(event => event.type === 'turn/start') - const turn = (lastStart?.data.turn ?? 0) + 1 - agent.session.append('turn/start', { - turn, - trigger: { kind: 'test-metadata' }, - }) - agent.session.append('turn/end', { turn, reason: { kind: 'completed' } }) - }) - test.ctx.goals.create(test.agent, { objective: 'ignore metadata', maxGoalRounds: 1 }) - - await waitForGoal(test.ctx, test.agent, goal => goal?.phase === 'blocked') - - expect(inserted).toBe(true) - expect(test.adapter.requests).toHaveLength(1) - expect(warnings.some(warning => warning.includes('session/event listener threw'))).toBe(false) - }) - it('makes a reserved round stale when a listener queues human work behind it', async () => { const test = await harness([textResponse('human batch'), textResponse('later goal')]) let inserted = false @@ -908,8 +876,7 @@ describe('same-session goal driving', () => { let queued = false test.ctx.on('session/event', (session, event) => { if (session !== test.agent.session || queued) return - if (event.type === 'turn/start' && event.data.trigger.kind === 'message' - && event.data.trigger.source.kind === 'goal') { + if (event.type === 'user/message' && event.data.source.kind === 'goal') { queued = true test.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'human interleaved' }], source: { kind: 'user' } })) } @@ -997,7 +964,6 @@ describe('same-session goal driving', () => { const orphan = test.ctx.sessions.create(SessionId('goal-session-orphan')) orphan.append('turn/start', { turn: 1, - trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'test' } }, }) orphan.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) diff --git a/packages/goal/goal-session/tests/invariant.spec.ts b/packages/goal/goal-session/tests/invariant.spec.ts index 4303f79c20..e35f87dfc8 100644 --- a/packages/goal/goal-session/tests/invariant.spec.ts +++ b/packages/goal/goal-session/tests/invariant.spec.ts @@ -41,7 +41,7 @@ function view(roundsStarted: number): GoalView { } function appendChange(session: Session): void { - session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: renderGoalChange(change), source: changeSource, @@ -51,7 +51,7 @@ function appendChange(session: Session): void { function appendRound(session: Session, turn: number, content = renderGoalRoundPrompt(view(turn - 2), turn - 1)): void { const source = { kind: 'goal', goalId: change.goal.id, revision: 1, round: turn - 1 } as const - session.append('turn/start', { turn, trigger: { kind: 'message', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content, source, }), { surfaceOp: 'append' }) @@ -82,7 +82,7 @@ describe('goal-session prompt invariants', () => { ctx.sessions.create(SessionId('goal-session-invariant-dispatch')) const userSource = { kind: 'user' } as const - session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: userSource } }) + session.append('turn/start', { turn: 4 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'ordinary human message' }], source: userSource, @@ -90,7 +90,7 @@ describe('goal-session prompt invariants', () => { session.append('turn/end', { turn: 4, reason: { kind: 'completed' } }) const stateSource = { ...changeSource, round: 0 } as const - session.append('turn/start', { turn: 5, trigger: { kind: 'message', source: stateSource } }) + session.append('turn/start', { turn: 5 }) expect(() => { session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'round zero is not a driver continuation' }], @@ -114,7 +114,7 @@ describe('goal-session prompt invariants', () => { it('rejects a goal round without a reconstructable active goal', async () => { const { session } = await mount() const source = { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 } as const - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source } }) + session.append('turn/start', { turn: 1 }) expect(() => { session.append('user/message', createUserMessage({ @@ -128,7 +128,7 @@ describe('goal-session prompt invariants', () => { it('attributes an invalid durable prefix during late loading', async () => { const { ctx, session } = await mount(true) - session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'counterfeit goal state' }], source: changeSource, diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts index c681c307e5..806f546a83 100644 --- a/packages/goal/goal/tests/goal.spec.ts +++ b/packages/goal/goal/tests/goal.spec.ts @@ -47,7 +47,6 @@ function stubAgentForSession(session: Session): StubAgent { ctx: new Context(), get status() { return status }, get acceptsNextStep() { return status === 'running' }, - send: () => {}, followup: () => {}, steer: () => {}, inject(input) { @@ -88,7 +87,7 @@ async function harness(config: { defaultMaxGoalRounds?: number } = {}) { function appendRound(session: Session, ref: GoalRef, round: number): void { const source = { kind: 'goal', goalId: ref.id, revision: ref.revision, round } as const const turn = nextTurn(session) - session.append('turn/start', { turn, trigger: { kind: 'message', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `round ${round}` }], source, }), { surfaceOp: 'append' }) @@ -503,7 +502,7 @@ describe('GoalService mutations', () => { } const source = { kind: 'goal', goalId: change.goal.id, revision: 1, round: 0, change } as const const turn = nextTurn(session) - session.append('turn/start', { turn, trigger: { kind: 'injection', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: renderGoalChange(change), source, }), { surfaceOp: 'append' }) @@ -584,7 +583,7 @@ describe('goal replay validation', () => { change, } const turn = nextTurn(session) - session.append('turn/start', { turn, trigger: { kind: 'injection', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: overrides.content ?? renderGoalChange(change), source, @@ -640,7 +639,7 @@ describe('goal replay validation', () => { expect(foldGoal(session.events)).toEqual({ roundsStarted: 0 }) const source = { kind: 'plugin', plugin: 'ordinary-user-message' } as const const turn = nextTurn(session) - session.append('turn/start', { turn, trigger: { kind: 'message', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'ordinary' }], source, }), { surfaceOp: 'append' }) @@ -782,7 +781,7 @@ describe('goal replay validation', () => { const session = new Session(SessionId('goal-source-without-meta')) const source = { kind: 'goal', goalId: GoalId('goal-missing-meta'), revision: 1, round: 0 } as const const turn = nextTurn(session) - session.append('turn/start', { turn, trigger: { kind: 'injection', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'missing' }], source, }), { surfaceOp: 'append' }) @@ -850,7 +849,7 @@ describe('goal replay validation', () => { } const source = { kind: 'goal', goalId: change.goal.id, revision: 2, round: 0, change: clear } as const const turn = nextTurn(session) - session.append('turn/start', { turn, trigger: { kind: 'injection', source } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: renderGoalChange(clear), source, }), { surfaceOp: 'append' }) diff --git a/packages/goal/goal/tests/invariant.spec.ts b/packages/goal/goal/tests/invariant.spec.ts index 2e953ce1e6..805c98fdcf 100644 --- a/packages/goal/goal/tests/invariant.spec.ts +++ b/packages/goal/goal/tests/invariant.spec.ts @@ -46,7 +46,7 @@ describe('goal stream invariants', () => { it('accepts canonical goal snapshots and sequential admitted rounds', async () => { const ctx = await setup() const session = ctx.sessions.create(SessionId('goal-invariant-valid')) - session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: renderGoalChange(change), source: changeSource, @@ -70,7 +70,7 @@ describe('goal stream invariants', () => { it('rejects model-visible drift before committing it and keeps the fold reusable', async () => { const ctx = await setup() const session = ctx.sessions.create(SessionId('goal-invariant-invalid')) - session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } }) + session.append('turn/start', { turn: 1 }) expect(() => { session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'counterfeit' }], @@ -93,7 +93,7 @@ describe('goal stream invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('goal-invariant-late-load')) - session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: renderGoalChange(change), source: changeSource, diff --git a/packages/goal/goal/tests/projection.spec.ts b/packages/goal/goal/tests/projection.spec.ts index 75c01295ce..27488a313e 100644 --- a/packages/goal/goal/tests/projection.spec.ts +++ b/packages/goal/goal/tests/projection.spec.ts @@ -38,7 +38,6 @@ function liveAgent(ctx: Context, session: Session): Agent { ctx, get status() { return status }, get acceptsNextStep() { return false }, - send: () => {}, followup: () => {}, steer: () => {}, inject(input: UserMessage) { @@ -145,7 +144,7 @@ describe('goal projection unit', () => { // A non-message event (the registry drives EVERY committed event through // apply): early same-reference return. - const turnStart = { type: 'turn/start', seq: 3, time: 4, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } } as never + const turnStart = { type: 'turn/start', seq: 3, time: 4, data: { turn: 1 } } as never expect(applyGoalProjection(state, turnStart)).toBe(state) // A round-zero goal source whose change carries a foreign kind: same posture. diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts index 1293b8642b..4bf4ef3c2c 100644 --- a/packages/goal/tool-goal/tests/tool-goal.spec.ts +++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts @@ -32,7 +32,6 @@ function stubAgent(rawId: string, supplied?: Session): StubAgent { get status() { return status }, get acceptsNextStep() { return status === 'running' }, ctx: new Context(), - send: () => {}, followup: () => {}, steer: () => {}, inject(input) { @@ -49,7 +48,7 @@ function openTurn(stub: StubAgent, source: MessageSource, text = 'prompt'): numb const turn = stub.session.events .filter(event => event.type === 'turn/start') .reduce((max, event) => Math.max(max, event.data.turn), 0) + 1 - stub.session.append('turn/start', { turn, trigger: { kind: 'message', source } }) + stub.session.append('turn/start', { turn }) stub.session.append('user/message', createUserMessage({ content: [{ type: 'text', text }], source, diff --git a/packages/hooks/hook-protocol/tests/invariant.spec.ts b/packages/hooks/hook-protocol/tests/invariant.spec.ts index 5092758e74..4efaae36c6 100644 --- a/packages/hooks/hook-protocol/tests/invariant.spec.ts +++ b/packages/hooks/hook-protocol/tests/invariant.spec.ts @@ -30,7 +30,7 @@ const result = (overrides: Record = {}) => ({ }) function startTurn(session: Session, turn = 1): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) } describe('hook-protocol invariants', () => { @@ -49,7 +49,7 @@ describe('hook-protocol invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('hook/invoked', invoked()) await ctx.plugin(InvariantService) await ctx.plugin(HookInvariant) @@ -63,7 +63,7 @@ describe('hook-protocol invariants', () => { expect(() => { ctx.emit('session/event', session, { type: 'turn/start', seq: 0, time: 0, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }) ctx.emit('session/event', session, { type: 'hook/invoked', seq: 1, time: 1, data: invoked(), diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts index 8552598818..bd3d979a14 100644 --- a/packages/hooks/hooks-claude/src/index.ts +++ b/packages/hooks/hooks-claude/src/index.ts @@ -197,6 +197,11 @@ export function apply(ctx: Context, config: Config): void { return [ours, ...theirs ?? []] } + /** Append hook context to an admitted inbox batch. */ + function appendPromptContext(theirs: UserMessage[], ours: UserMessage): UserMessage[] { + return [...theirs, ours] + } + // SessionStart injects context when its detached hook resolves; a slow hook // may miss the first request. // TODO(session-start-gating): add a startup gate before promising first-turn delivery. @@ -213,8 +218,9 @@ export function apply(ctx: Context, config: Config): void { // --- UserPromptSubmit → PromptDecision. The prompt text is the payload; no // matcher subject (CC ignores matchers for this event). --- - ctx.on('agent/prompt-submit', async (agent, message, signal, next): Promise => { - const merged = await runPoint('UserPromptSubmit', '', promptPayload(ctx, agent, message.content), { agent, signal }) + ctx.on('agent/prompt-submit', async (agent, messages, signal, next): Promise => { + const content = messages.flatMap(message => message.content) + const merged = await runPoint('UserPromptSubmit', '', promptPayload(ctx, agent, content), { agent, signal }) if (merged.decision === 'deny') { return { kind: 'block', reason: merged.reason ?? 'blocked by UserPromptSubmit hook' } } @@ -225,8 +231,7 @@ export function apply(ctx: Context, config: Config): void { if (!ours || downstream.kind !== 'allow') return downstream return { kind: 'allow', - ...downstream.content !== undefined ? { content: downstream.content } : {}, - additionalContexts: prependContext(ours, downstream.additionalContexts), + messages: appendPromptContext(downstream.messages, ours), } }) diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts index d68e2b9d0a..19d1c43f7d 100644 --- a/packages/hooks/hooks-codex/src/index.ts +++ b/packages/hooks/hooks-codex/src/index.ts @@ -182,6 +182,11 @@ export function apply(ctx: Context, config: Config): void { return [ours, ...theirs ?? []] } + /** Append hook context to an admitted inbox batch. */ + function appendPromptContext(theirs: UserMessage[], ours: UserMessage): UserMessage[] { + return [...theirs, ours] + } + // SessionStart injects plain stdout when its detached hook resolves; a slow // hook may miss the first request. // TODO(session-start-gating): add a startup gate before promising first-turn delivery. @@ -196,11 +201,11 @@ export function apply(ctx: Context, config: Config): void { }) // UserPromptSubmit → PromptDecision. Codex supports block, not allow or ask. - ctx.on('agent/prompt-submit', async (agent, message, signal, next): Promise => { + ctx.on('agent/prompt-submit', async (agent, messages, signal, next): Promise => { const payload = { ...base(ctx, agent, 'UserPromptSubmit', model), turn_id: String(lastTurn(agent) + 1), - prompt: blocksToText(message.content), + prompt: blocksToText(messages.flatMap(message => message.content)), } const merged = await runPoint('UserPromptSubmit', '', payload, { agent, plainStdoutAsContext: true, signal }) /* jscpd:ignore-start */ @@ -212,8 +217,7 @@ export function apply(ctx: Context, config: Config): void { if (!ours || downstream.kind !== 'allow') return downstream return { kind: 'allow', - ...downstream.content !== undefined ? { content: downstream.content } : {}, - additionalContexts: prependContext(ours, downstream.additionalContexts), + messages: appendPromptContext(downstream.messages, ours), } }) diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index 765982862e..226abb1706 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -9,7 +9,7 @@ import { join } from 'node:path' import type { Context } from 'cordis' import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent' import type { - Agent, AgentLlmTarget, AgentLlmTargetRef, AgentStatus, InboxPlacement, + Agent, AgentLlmTarget, AgentLlmTargetRef, AgentStatus, } from '@deepseek-ai/dsh-agent' import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm' import { errorChain } from '@deepseek-ai/dsh-llm' @@ -474,38 +474,38 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro * inbox event retires one matching occurrence, so repeated sends of the same * identified message remain visible until every occurrence is claimed. */ - const queuedMirror = new Map() + const queuedMirror = new Map() ctx.effect(() => { - const retire = (agent: Agent, id: MessageId, placement?: InboxPlacement): void => { + const retire = (agent: Agent, id: MessageId): void => { const entries = queuedMirror.get(agent.id) if (entries === undefined) return - const index = entries.findIndex(entry => - entry.message.id === id - && (placement === undefined || entry.steering === (placement === 'steering'))) + const index = entries.findIndex(message => message.id === id) if (index !== -1) entries.splice(index, 1) if (entries.length === 0) queuedMirror.delete(agent.id) } const disposers = [ - ctx.on('agent/inbox/enqueue', (agent: Agent, message: UserMessage, placement) => { + ctx.on('session/event', (session: Session, event: SessionEvent) => { + if (event.type !== 'agent/inbox/added') return + const agent = ctx.agents.get(session.id) + if (agent === undefined || agent.session !== session) return + const message = event.data let entries = queuedMirror.get(agent.id) if (entries === undefined) { entries = [] queuedMirror.set(agent.id, entries) } - const steering = placement === 'steering' - entries.push({ message, steering }) + entries.push(message) broadcast({ type: 'session/queued', sessionId: agent.id, message, - steering, }) }), - ctx.on('agent/inbox/dequeue', (agent: Agent, message: UserMessage, placement) => { - retire(agent, message.id, placement) + ctx.on('agent/inbox/admitted', (agent: Agent, message: UserMessage) => { + retire(agent, message.id) }), - ctx.on('agent/inbox/discard', (agent: Agent, messages: UserMessage[]) => { - for (const message of messages) retire(agent, message.id) + ctx.on('agent/inbox/canceled', (agent: Agent, message: UserMessage) => { + retire(agent, message.id) }), ctx.on('session/disposed', (session: Session) => { queuedMirror.delete(session.id) @@ -1338,12 +1338,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro // in arrival order per session; a reconnecting client rebuilds its // queue view from these alone. for (const [sessionId, entries] of queuedMirror) { - for (const entry of entries) { + for (const message of entries) { queue.push(frame({ type: 'session/queued', sessionId, - message: entry.message, - steering: entry.steering, + message, })) } } diff --git a/packages/host/apiproxy/src/api/events.schema.ts b/packages/host/apiproxy/src/api/events.schema.ts index 4e729b4c41..ff7c4c2b67 100644 --- a/packages/host/apiproxy/src/api/events.schema.ts +++ b/packages/host/apiproxy/src/api/events.schema.ts @@ -42,7 +42,7 @@ export const muxFrameSchema = z.discriminatedUnion('type', [ // and must fail loud here, not reach the composer. z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema).min(1) }), z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }), - z.object({ type: z.literal('session/queued'), sessionId: sessionIdSchema, message: messageSchema, steering: z.boolean() }), + z.object({ type: z.literal('session/queued'), sessionId: sessionIdSchema, message: messageSchema }), // value stays wide: it already passed its unit's own schema on the host, // and deep-validating here would import every domain's schema into the carrier. z.object({ type: z.literal('session/projection'), sessionId: sessionIdSchema, key: z.string().min(1), value: z.unknown(), seq: z.number().int().nonnegative() }), diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts index 9f56fc1dd5..464e4376a9 100644 --- a/packages/host/apiproxy/src/api/events.ts +++ b/packages/host/apiproxy/src/api/events.ts @@ -68,12 +68,10 @@ export type MuxFrame = * host replays the current queue snapshot for every attached session (same * refresh-recovery baseline as pending questions); queue clearing on cancel * has no dedicated frame — clients fold it from the status flip. - * `steering` is the host's acceptance-time queue classification and remains - * authoritative in reconnect snapshots. `message.source` carries the prompt's rpcId - * when the message came over this wire (the client's provisional-echo - * reconciliation key). + * `message.source` carries the prompt's rpcId when the message came over + * this wire (the client's provisional-echo reconciliation key). */ - | { type: 'session/queued'; sessionId: SessionId; message: Message; steering: boolean } + | { type: 'session/queued'; sessionId: SessionId; message: Message } /** * One projection unit's finished value changed (session-projection RFC). * Live push state, never logged — replay recomputes on the host (the diff --git a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts index e5bd8bfbee..e9236f3fb9 100644 --- a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts @@ -71,7 +71,7 @@ describe('summary blank = conversation not started', () => { const session = ctx.sessions.create() attach(session) appendStandalone(session) - session.append('turn/start', { turn: 0, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 0 }) expect(await listBlank(api, session.id)).toBe(false) }) }) diff --git a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts index bcfc067ff5..4916f93e32 100644 --- a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts @@ -225,7 +225,7 @@ describe('session/projection push frame', () => { seedMessages(session, 1) // Same-reference apply: turn/start does not concern the unit — no frame. - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) seedMessages(session, 1) const frames = await collected diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts index b970755d6b..b0cc61b3fa 100644 --- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts @@ -83,7 +83,7 @@ describe('mux live view computation', () => { const rawResult = `RAW_RESULT:${'x'.repeat(64 * 1024)}` const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-gen'), name: 'gen', arguments: '{}' }) session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-term'), name: 'term', arguments: '{"cmd":"echo hi"}' }) session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-diff'), name: 'diffy', arguments: '{}' }) @@ -146,7 +146,7 @@ describe('mux live view computation', () => { // history resolves the agent first; a live structural stub is enough (only // .session is read on this path). ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-term'), name: 'term', arguments: '{"cmd":"ls"}' }) // meta rides through to presentResult's ToolResult (the spread arm). session.append('tool/result', { @@ -217,7 +217,7 @@ describe('mux live view computation', () => { const fiber = await ctx.plugin(Object.assign((inner: Context) => { session = inner.sessions.create('session-doomed' as SessionId) }, { inject: ['sessions'] })) - session?.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session?.append('turn/start', { turn: 1 }) session?.append('tool/call', { turn: 1, step: 1, callId: CallId('c-doomed'), name: 'term', arguments: '{"cmd":"x"}' }) // Disposing the owning fiber detaches the session mid-stream; the // session/disposed listener must clear its open-call table entry. @@ -236,7 +236,7 @@ describe('mux live view computation', () => { const collected = collect(stream, 4, abort) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-late'), name: 'term', arguments: '{"cmd":"tail"}' }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) // The turn/end above cleared the live table; pairing must fall back to diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts index 3968cba5c7..7b9b149943 100644 --- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts @@ -50,7 +50,6 @@ function stubAgent(session: Session): Agent { followup: () => {}, steer: () => {}, inject: () => {}, - send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts index 7871fa8a93..0af1bbf385 100644 --- a/packages/llm/llm-retry/src/index.ts +++ b/packages/llm/llm-retry/src/index.ts @@ -1,5 +1,5 @@ /** - * Provider-routed model-request retry policy on the agent loop's closed-step + * Provider-routed model-request retry policy on the agent loop's request * recovery seam. Each scheduled retry is durable before its cancellable wait. * * @module @deepseek-ai/dsh-llm-retry @@ -7,14 +7,13 @@ import type { Context } from 'cordis' import z from 'schemastery' -import type { Agent, RequestError, RequestErrorAction } from '@deepseek-ai/dsh-agent' +import type { Agent, RequestErrorAction, RequestFailureContext } from '@deepseek-ai/dsh-agent' import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm' import type { SessionEvent } from '@deepseek-ai/dsh-session' -import { providerForClosedStep } from './history.ts' declare module '@deepseek-ai/dsh-session' { interface SessionEventMap { - /** Durable, non-surface record of one provider-routed retry scheduled after a closed failed step. */ + /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */ 'llm/retry': { turn: number step: number @@ -172,24 +171,12 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna async function recover( agent: Agent, - turn: number, - step: number, - _error: RequestError, - failure: LlmFailure, - priorFailures: readonly LlmFailure[], - policy: ResolvedRetryPolicy | undefined, + context: RequestFailureContext, signal: AbortSignal, next: () => Promise, ): Promise { + const { turn, step, provider, failure, retryPolicy: policy } = context if (policy === undefined) return next() - // The call-local policy belongs to the registration that served this - // failure. Recover only the durable provider identity from the header; - // downstream recovery may append later state before an always fallback. - const provider = providerForClosedStep(agent.session.events, turn, step) - /* v8 ignore next 3 -- agent-loop closes only steps whose request header was recorded */ - if (provider === undefined) { - throw new Error(`llm-retry: no request provider for closed turn ${turn}/step ${step}`) - } if (policy.mode === 'always') { if (signal.aborted || lifetime.signal.aborted) return const fusedSignal = AbortSignal.any([signal, lifetime.signal]) @@ -211,11 +198,10 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna } const policyKey = retryPolicyKey(policy) - const firstPriorTurn = turn - priorFailures.length const priorPolicyRetry = agent.session.events.findLast((event): event is SessionEvent<'llm/retry'> => event.type === 'llm/retry' - && event.data.turn >= firstPriorTurn - && event.data.turn < turn + && event.data.turn === turn + && event.data.step === step && event.data.provider === provider && event.data.policyKey === policyKey, ) @@ -241,12 +227,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna const disposeListener = ctx.on('agent/request-error', ( agent: Agent, - turn: number, - step: number, - error: RequestError, - failure: LlmFailure, - priorFailures: readonly LlmFailure[], - policy: ResolvedRetryPolicy | undefined, + context: RequestFailureContext, signal: AbortSignal, next: () => Promise, ) => { @@ -254,7 +235,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna // removed. Lifetime cancellation must prevent that stale callback from // entering a downstream policy after disposal. if (lifetime.signal.aborted) return Promise.resolve(undefined) - return track(recover(agent, turn, step, error, failure, priorFailures, policy, signal, next)) + return track(recover(agent, context, signal, next)) }) ctx.effect(() => async () => { diff --git a/packages/llm/llm-retry/src/invariant.ts b/packages/llm/llm-retry/src/invariant.ts index 03379c82d0..3b154f046c 100644 --- a/packages/llm/llm-retry/src/invariant.ts +++ b/packages/llm/llm-retry/src/invariant.ts @@ -41,34 +41,6 @@ function validateFailure(value: unknown, fail: InvariantFailure): asserts value } } -/** Find the first turn in the structured-failure retry chain containing `turn`. */ -function retryChainStart(history: readonly SessionEvent[], turn: number): number { - let startIndex = history.findLastIndex( - event => event.type === 'turn/start' && event.data.turn === turn, - ) - while (startIndex >= 0) { - const start = history[startIndex] - if (start?.type !== 'turn/start' || start.data.trigger.kind !== 'retry') break - - let endIndex = startIndex - 1 - while (endIndex >= 0 && history[endIndex]?.type !== 'turn/end') endIndex -= 1 - const end = history[endIndex] - if (end?.type !== 'turn/end' - || end.data.reason.kind !== 'error' - || end.data.reason.failure === undefined) break - - const previousStart = history.findLastIndex( - (event, index) => - index < endIndex - && event.type === 'turn/start' - && event.data.turn === end.data.turn, - ) - if (previousStart < 0) break - startIndex = previousStart - } - return startIndex -} - /** Validate one retry record against the open turn and most recently closed step. */ function validateRetry( history: readonly SessionEvent[], @@ -139,7 +111,9 @@ function validateRetry( fail(`llm/retry provider ${provider} does not match the failed request provider ${String(routedProvider)}`) } - const chainStart = retryChainStart(history, turn) + const chainStart = history.findLastIndex( + prior => prior.type === 'turn/start' && prior.data.turn === turn, + ) const chain = history.slice(Math.max(chainStart, 0)) const lastSuccess = chain.findLastIndex(prior => prior.type === 'assistant/message') const chainRetries = chain.slice(lastSuccess + 1) diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts index fd35af7e24..5724b631f9 100644 --- a/packages/llm/llm-retry/tests/invariant.spec.ts +++ b/packages/llm/llm-retry/tests/invariant.spec.ts @@ -17,7 +17,7 @@ async function setup(): Promise { function closeStep(ctx: Context, id: string, turn = 1, step = 1) { const session = ctx.sessions.create(SessionId(id)) - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('step/start', { turn, step }) session.append('request/header', { header: { config: { provider: 'mock', model: 'mock' } }, @@ -28,7 +28,7 @@ function closeStep(ctx: Context, id: string, turn = 1, step = 1) { } function appendRetryTurn(session: Session, turn: number) { - session.append('turn/start', { turn, trigger: { kind: 'retry' } }) + session.append('turn/start', { turn }) session.append('step/start', { turn, step: 1 }) session.append('request/header', { header: { config: { provider: 'mock', model: 'mock' } }, @@ -73,7 +73,7 @@ describe('llm-retry invariants', () => { expect(() => { session.append('llm/retry', { turn: 1, step: 1, ...normal }) session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } }) - session.append('turn/start', { turn: 2, trigger: { kind: 'retry' } }) + session.append('turn/start', { turn: 2 }) session.append('step/start', { turn: 2, step: 1 }) session.append('step/end', { turn: 2, step: 1 }) session.append('llm/retry', { @@ -169,14 +169,14 @@ describe('llm-retry invariants', () => { }).toThrow(/open turn is 1/) const openStep = ctx.sessions.create(SessionId('retry-invariant-open-step')) - openStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + openStep.append('turn/start', { turn: 1 }) openStep.append('step/start', { turn: 1, step: 1 }) expect(() => { openStep.append('llm/retry', { turn: 1, step: 1, ...normal }) }).toThrow(/step 1 is still open/) const noStep = ctx.sessions.create(SessionId('retry-invariant-no-step')) - noStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + noStep.append('turn/start', { turn: 1 }) expect(() => { noStep.append('llm/retry', { turn: 1, step: 1, ...normal }) }).toThrow(/latest closed step is undefined/) @@ -208,7 +208,7 @@ describe('llm-retry invariants', () => { const mismatch = closeStep(ctx, 'retry-invariant-numbering') mismatch.append('llm/retry', { turn: 1, step: 1, ...normal }) mismatch.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } }) - mismatch.append('turn/start', { turn: 2, trigger: { kind: 'retry' } }) + mismatch.append('turn/start', { turn: 2 }) mismatch.append('step/start', { turn: 2, step: 1 }) mismatch.append('step/end', { turn: 2, step: 1 }) expect(() => { @@ -218,7 +218,7 @@ describe('llm-retry invariants', () => { const reset = closeStep(ctx, 'retry-invariant-reset') reset.append('llm/retry', { turn: 1, step: 1, ...normal }) reset.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } }) - reset.append('turn/start', { turn: 2, trigger: { kind: 'retry' } }) + reset.append('turn/start', { turn: 2 }) reset.append('step/start', { turn: 2, step: 1 }) reset.append('assistant/message', { turn: 2, @@ -234,7 +234,7 @@ describe('llm-retry invariants', () => { }, { surfaceOp: 'append' }) reset.append('step/end', { turn: 2, step: 1 }) reset.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) - reset.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }) + reset.append('turn/start', { turn: 3 }) reset.append('step/start', { turn: 3, step: 1 }) reset.append('step/end', { turn: 3, step: 1 }) expect(() => { diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts index 2b5d0234bd..60fedbc70d 100644 --- a/packages/llm/llm-retry/tests/persistence.spec.ts +++ b/packages/llm/llm-retry/tests/persistence.spec.ts @@ -32,7 +32,7 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind) const ctx = await backend(kind) try { const session = ctx.sessions.create(SessionId(`retry-${kind}`)) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('request/header', { header: { config: { provider: 'mock', model: 'mock' } }, diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml index a4716026cd..9e6d551144 100644 --- a/packages/llm/llm/README.i18n.yaml +++ b/packages/llm/llm/README.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 packages/llm/llm/README.md -README.md: d343449d1530bf70a3a8c57f883894e29c42d18f -README.zh.md: 6ac57b1e6010b58c45b516f13ec6361d47ca8d12 +README.md: dc7499a6854fe9a45c1297aa2a1a67aea92eaf6f +README.zh.md: 1f5850b6e73c067aa554636d33bfd9194a4410f3 diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md index d343449d15..dc7499a685 100644 --- a/packages/llm/llm/README.md +++ b/packages/llm/llm/README.md @@ -16,10 +16,10 @@ An adapter registry plus a single streaming call surface, interceptable via a wa - `ctx.llm.listModels(provider: string): Promise` Discover the models one registered provider currently advertises. - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise` Resolve validated exact-model identity plus available context and reasoning metadata from the owning adapter, with optional cancellation for asynchronous adapters. - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise` Validate an explicit effort and materialize an adapter-configured default without clamping. -- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise` Resolve a config and capture its current adapter registration as one cancellable, one-shot call. +- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise` Resolve a config and capture its current adapter registration plus immutable retry policy as one cancellable, one-shot call. - `ctx.llm.stream(options: GenerateOptions): AsyncIterable` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`. -`LlmService` preserves errors from final adapter selection, synchronous dispatch, iterator construction, and iteration, and binds their provenance to the exact stream handle returned for that model call. `isLlmAdapterFailure(stream, value)` reports only errors from that call's final adapter boundary; `llmFailureOf(stream, value)` returns the adjacent immutable `LlmFailure`; `llmRetryPolicyOf(stream)` returns the immutable policy of the exact registration selected at that boundary, even if the route is later disposed or replaced. A call that never reaches a final adapter has no serving policy. Nested model calls, `llm/stream` middleware, and downstream consumer failures remain unclassified for the outer call. Classification never replaces or mutates the adapter's original coded `Error`. +`LlmService` normalizes failures from final adapter selection, synchronous dispatch, iterator construction, and iteration into the stream protocol's single terminal form: `finish { kind: 'error' | 'aborted', failure }`. A failure after partial deltas may leave content blocks open; consumers discard that incomplete output. Errors from `llm/stream` middleware, nested calls, adapter cleanup, and downstream consumers remain thrown because they are plugin or consumer failures rather than model-request outcomes. A prepared call exposes the immutable retry policy captured with its exact adapter registration; a route handled entirely by middleware has no serving policy. Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity and captures the adapter's retry policy for each route, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned selector metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`. @@ -44,7 +44,7 @@ Reasoning identifiers are opaque adapter-owned strings rather than a core enum. Message content is an array of typed blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages use a model source carrying provider/model provenance and optional adapter-private replay state. Before dispatch, `LlmService` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it. -Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages. +Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). Every adapter outcome reaches consumers as one terminal `finish`; operational failure uses its `error` or `aborted` reason rather than throwing across the stream API. `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages. ### Call configuration (`call-config.ts`) @@ -67,7 +67,7 @@ Every product adapter sends application identity on provider HTTP requests. `att ### Real adapters -Two adapters implement `LlmAdapter` on different internals: [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) uses direct fetch with `eventsource-parser` SSE framing for the `deepseek` route, while [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) dynamically resolves configured provider/model pairs through `@earendil-works/pi-ai`. Both follow the `StreamChunk` conventions in `types.ts`: usage precedes finish, tool arguments remain raw strings, and errors take one of two sanctioned paths. See [the twin LLM adapters](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the design rationale. +Two adapters implement `LlmAdapter` on different internals: [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) uses direct fetch with `eventsource-parser` SSE framing for the `deepseek` route, while [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) dynamically resolves configured provider/model pairs through `@earendil-works/pi-ai`. Both follow the `StreamChunk` conventions in `types.ts`: usage precedes finish and tool arguments remain raw strings. Adapter implementations may throw or emit a failure finish internally; `LlmService` exposes both as a terminal failure finish. See [the twin LLM adapters](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the adapter rationale and [the terminal-failure decision](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md) for the service boundary. ## Model Experience diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md index 6ac57b1e60..1f5850b6e7 100644 --- a/packages/llm/llm/README.zh.md +++ b/packages/llm/llm/README.zh.md @@ -16,10 +16,10 @@ - `ctx.llm.listModels(provider: string): Promise` 发现某个已注册提供方当前公布的模型。 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise` 从拥有精确路由的适配器解析经校验的确切模型身份、可用上下文和推理（reasoning）元数据；异步适配器可选地支持取消。 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise` 校验显式推理强度，并填入适配器配置的默认值，但不自动调整。 -- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise` 解析配置并将其当前适配器注册捕获为一次可取消、一次性调用。 +- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise` 解析配置，并将其当前适配器注册与不可变重试策略捕获为一次可取消、一次性调用。 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable` 将一次模型调用流式输出为原始 chunk（token 级 delta）。消费方使用 `BlockAssembler` 将 chunk 组装为块／消息。 -`LlmService` 保留来自最终适配器选择、同步 dispatch、iterator 构造与迭代的错误，并将其溯源绑定到该次模型调用返回的精确流句柄。`isLlmAdapterFailure(stream, value)` 只报告该调用最终适配器边界的错误；`llmFailureOf(stream, value)` 返回相邻的不可变 `LlmFailure`；`llmRetryPolicyOf(stream)` 返回在该边界选中的确切注册所对应的不可变策略，即使之后释放或替换路由也不变。未到达最终适配器的调用没有服务策略。嵌套模型调用、`llm/stream` middleware 和下游消费方失败对外层调用仍未分类。分类绝不替换或更改适配器的原始编码 `Error`。 +`LlmService` 会把最终适配器选择、同步 dispatch、iterator 构造与迭代产生的失败规范化为流协议的单一终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分 delta 之后的失败可能留下未关闭内容块；消费方会丢弃这部分不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。准备完成的调用会公开随其确切适配器注册捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。 提供方与模型元数据是发现表层，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。 @@ -44,7 +44,7 @@ 消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带提供方／模型溯源与可选适配器私有回放状态。dispatch 前，`LlmService` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加支持它的适配器／UI／压缩实现。 -流式输出是原始 chunk 协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。`BlockAssembler` 是将 chunk 组装为块／消息的唯一共享实现。 +流式输出是原始 chunk 协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 抵达消费方；运行失败使用其中的 `error` 或 `aborted` reason，不再跨 stream API 抛出。`BlockAssembler` 是将 chunk 组装为块／消息的唯一共享实现。 ### 调用配置（`call-config.ts`） @@ -67,7 +67,7 @@ ### 真实适配器 -两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek` 路由使用直接 fetch 加 `eventsource-parser` SSE 分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `StreamChunk` 约定，定义见 `types.ts`：usage 先于 finish，工具参数保持原始字符串，错误使用两种已批准路径之一。设计理由见 [双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)。 +两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek` 路由使用直接 fetch 加 `eventsource-parser` SSE 分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `types.ts` 中的 `StreamChunk` 约定：usage 先于 finish，工具参数保持原始字符串。适配器实现内部可以抛出或发出失败 finish；`LlmService` 会将两者都作为终止失败 finish 暴露。适配器设计理由见[双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)，服务边界见[终止失败决策](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md)。 ## 模型体验 diff --git a/packages/llm/llm/src/adapter-failure.ts b/packages/llm/llm/src/adapter-failure.ts index e888d216a8..d11ee2e52b 100644 --- a/packages/llm/llm/src/adapter-failure.ts +++ b/packages/llm/llm/src/adapter-failure.ts @@ -1,67 +1,40 @@ /** - * Private provider-failure tagging shared by `LlmService` and its consumers. + * Normalization for values thrown by a final LLM adapter boundary. * * @module @deepseek-ai/dsh-llm/adapter-failure */ import { HarnessError } from './error.ts' -import type { LlmFailure, StreamChunk } from './types.ts' -import type { ResolvedRetryPolicy } from './retry-policy.ts' - -/** Call-local facts captured when one model call enters its final adapter boundary. */ -export interface AdapterFailureScope { - /** Errors and normalized facts proven to originate in this call's final adapter boundary. */ - readonly failures: WeakMap - /** Immutable policy of the exact adapter registration selected for this call. */ - retryPolicy?: ResolvedRetryPolicy -} - -/** Call-local failure scopes keyed by the exact stream handle returned to a consumer. */ -const adapterFailureScopes = new WeakMap, AdapterFailureScope>() +import type { LlmFailure } from './types.ts' /** - * Bind one call's adapter-failure scope to a unique returned stream handle. - * @param stream - the waterfall-selected stream for this call. - * @param failures - errors tagged by this call's final adapter boundary. - * @returns a unique stream handle that delegates iteration to `stream`. + * Detach serializable provider facts from a value thrown by an adapter. + * @param value - arbitrary value thrown during adapter dispatch or iteration. + * @returns immutable provider-neutral facts suitable for a terminal finish chunk. * @internal */ -export function bindAdapterFailureScope( - stream: AsyncIterable, - failures: AdapterFailureScope, -): AsyncIterable { - const call = { - [Symbol.asyncIterator](): AsyncIterator { - return stream[Symbol.asyncIterator]() - }, - } - adapterFailureScopes.set(call, failures) - return call -} - -/** - * Preserve an adapter's Error identity while tagging its provider origin. - * @param failures - the call-local final-adapter failure scope. - * @param value - arbitrary value thrown by adapter dispatch or iteration. - * @returns the original Error, or a coded Error wrapping a non-Error throw. - * @internal - */ -export function markLlmAdapterFailure( - failures: AdapterFailureScope, - value: unknown, -): Error & { code?: string } { +export function normalizeLlmFailure(value: unknown): LlmFailure { const error = value instanceof Error - ? value as Error & { code?: string } - : new HarnessError(String(value), 'UNKNOWN', { cause: value }) + ? value + : new HarnessError(thrownMessage(value), 'UNKNOWN', { cause: value }) // Cross-package copies preserve own data but not class identity. Trust the // carried facts only when both own properties agree after validation. const carried = ownFailureSnapshot(error) - const failure = carried !== undefined && carried.code === ownErrorCode(error) ? carried : Object.freeze({ + if (carried !== undefined && carried.code === ownErrorCode(error)) return carried + return Object.freeze({ message: errorMessage(error), code: harnessErrorCode(error), }) - failures.failures.set(error, failure) - return error +} + +/** Render a non-Error throw without letting hostile coercion escape normalization. */ +function thrownMessage(value: unknown): string { + try { + const message = String(value) + return message.length > 0 ? message : 'LLM adapter failed' + } catch (_hostileThrownValue) { + return 'LLM adapter failed' + } } /** Read a foreign error's own data-backed `code` without invoking accessors. */ @@ -129,46 +102,3 @@ function errorMessage(error: Error): string { function harnessErrorCode(error: Error): string { return error instanceof HarnessError ? error.code : 'UNKNOWN' } - -/** - * Whether a failure came from final adapter dispatch, iterator construction, - * or iteration for the call represented by the exact returned stream handle. - * @param stream - the exact stream returned by the model call being classified. - * @param value - arbitrary failure caught by a model-call consumer. - * @returns true only for errors tagged at that call's final adapter boundary. - */ -export function isLlmAdapterFailure( - stream: AsyncIterable, - value: unknown, -): value is Error & { code?: string } { - const failures = adapterFailureScopes.get(stream) - return value instanceof Error && failures !== undefined && failures.failures.has(value) -} - -/** - * Retrieve normalized provider facts only for an Error tagged by this exact - * model call's final adapter boundary. - * @param stream - the exact stream returned to the consumer. - * @param value - the caught failure. - * @returns the immutable facts for that call, or `undefined` for middleware, nested, or consumer failures. - */ -export function llmFailureOf( - stream: AsyncIterable, - value: unknown, -): LlmFailure | undefined { - const failures = adapterFailureScopes.get(stream) - return value instanceof Error ? failures?.failures.get(value) : undefined -} - -/** - * Read the retry policy of the exact registration selected at this call's - * final adapter boundary. The policy remains available after that registration - * is disposed or replaced; absence means no final adapter served the call. - * @param stream - the exact stream returned by the model call. - * @returns the immutable serving-registration policy, or `undefined`. - */ -export function llmRetryPolicyOf( - stream: AsyncIterable, -): ResolvedRetryPolicy | undefined { - return adapterFailureScopes.get(stream)?.retryPolicy -} diff --git a/packages/llm/llm/src/assembler.ts b/packages/llm/llm/src/assembler.ts index 252d6b89ac..a0e1332417 100644 --- a/packages/llm/llm/src/assembler.ts +++ b/packages/llm/llm/src/assembler.ts @@ -127,11 +127,15 @@ export class BlockAssembler { /** * Assemble all blocks seen so far, in stream order. - * @returns one block per seen index; an open block assembles from its - * accumulated deltas (an unknown block type never closed by `block-end` throws). + * @returns one block per seen index, except that max-token truncation drops + * tool calls that cannot be executed safely; an open block assembles from + * its accumulated deltas (an unknown block type never closed by `block-end` throws). */ blocks(): ContentBlock[] { - return this.order.map(index => this.assemble(this.mustGet(index), index)) + const blocks = this.order.map(index => this.assemble(this.mustGet(index), index)) + return this.finish.kind === 'max-tokens' + ? blocks.filter(block => block.type !== 'tool-call') + : blocks } /** Usage from the `usage` chunk; undefined until one arrives. */ diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts index c8f5a8b0fc..1e267dd86d 100644 --- a/packages/llm/llm/src/index.ts +++ b/packages/llm/llm/src/index.ts @@ -22,8 +22,7 @@ import type { ProviderRequestId } from './brand.ts' import { callConfigEquals, deepFreeze } from './call-config.ts' import type { LlmCallConfig } from './call-config.ts' import { HarnessError } from './error.ts' -import { bindAdapterFailureScope, markLlmAdapterFailure } from './adapter-failure.ts' -import type { AdapterFailureScope } from './adapter-failure.ts' +import { normalizeLlmFailure } from './adapter-failure.ts' export * from './attribution.ts' export * from './brand.ts' @@ -35,7 +34,6 @@ export * from './retry-policy.ts' export { BlockAssembler } from './assembler.ts' export { callConfigEquals, deepFreeze, isAgentLoopRequest, markAgentLoopRequest } from './call-config.ts' export type { LlmCallConfig } from './call-config.ts' -export { isLlmAdapterFailure, llmFailureOf, llmRetryPolicyOf } from './adapter-failure.ts' declare module 'cordis' { interface Context { @@ -113,6 +111,8 @@ export class LlmError extends HarnessError { export interface PreparedLlmCall { /** Detached, deep-frozen config with any adapter-owned default materialized. */ readonly config: LlmCallConfig + /** Immutable retry policy captured with the adapter registration. */ + readonly retryPolicy: ResolvedRetryPolicy /** * Dispatch this call once through the registration captured during * preparation. The request's call-config fields must match {@link config}; @@ -440,10 +440,17 @@ export class LlmService extends Service { let dispatched = false return Object.freeze({ config: resolvedConfig, + retryPolicy: registration.retryPolicy, stream: (options: GenerateOptions): AsyncIterable => { if (dispatched) { throw new LlmError('a prepared LLM call can only be dispatched once', 'INVALID_PREPARED_CALL') } + if (!callConfigEquals(options, resolvedConfig)) { + throw new LlmError( + 'prepared LLM call config changed before adapter dispatch', + 'INVALID_PREPARED_CALL', + ) + } dispatched = true return this.streamWithRegistration(options, { registration, config: resolvedConfig }) }, @@ -473,31 +480,20 @@ export class LlmService extends Service { } /** - * Final adapter boundary. It tags only failures from adapter selection, - * synchronous dispatch, iterator construction, or iteration while preserving - * the original Error object. Middleware outside this generator remains - * distinguishable as plugin work. An iteration failure skips adapter cleanup - * so it cannot suppress the primary provider error. A downstream close awaits - * adapter cleanup, whose failures remain ordinary untagged work. + * Final adapter boundary. Adapter selection, dispatch, iterator construction, + * and iteration failures become one terminal failure chunk. Middleware and + * downstream consumer failures remain thrown plugin or consumer errors. */ private async * adapterStream( options: GenerateOptions, - failures: AdapterFailureScope, prepared?: { registration: AdapterRegistration; config: LlmCallConfig }, ): AsyncGenerator { let iterator: AsyncIterator try { const registration = prepared?.registration ?? this.registration(options.provider) - failures.retryPolicy = registration.retryPolicy const resolvedConfig = prepared === undefined ? await this.resolveCallConfigFor(registration, options, options.signal) : prepared.config - if (prepared !== undefined && !callConfigEquals(options, resolvedConfig)) { - throw new LlmError( - 'prepared LLM call config changed before adapter dispatch', - 'INVALID_PREPARED_CALL', - ) - } const resolvedOptions = prepared !== undefined || callConfigEquals(options, resolvedConfig) ? options : Object.isFrozen(options) @@ -507,32 +503,31 @@ export class LlmService extends Service { const stream = adapter.stream(this.forAdapter(resolvedOptions, adapter)) iterator = stream[Symbol.asyncIterator]() } catch (error: unknown) { - throw markLlmAdapterFailure(failures, error) + yield adapterFailureChunk(error, options.signal) + return } let completed = false - let iterationFailed = false try { while (true) { - let value: StreamChunk + let item: IteratorResult try { - const item = await iterator.next() - if (item.done) { - completed = true - return - } - value = item.value + item = await iterator.next() } catch (error: unknown) { - iterationFailed = true - throw markLlmAdapterFailure(failures, error) + completed = true + yield adapterFailureChunk(error, options.signal) + return + } + if (item.done) { + completed = true + return } // End the adapter-owned try before yielding: consumer/middleware - // failures resumed into this generator must remain untagged. - yield value + // failures resumed into this generator must remain thrown. + yield item.value } } finally { - // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the iteration catch sets its latch before entering finally. - if (!completed && !iterationFailed) { + if (!completed) { const close = iterator.return?.bind(iterator) if (close) await close() } @@ -540,15 +535,13 @@ export class LlmService extends Service { } /** - * Stream one model call as raw chunks (token-level deltas). Throws - * `LlmError` with code `NO_ADAPTER` if no adapter is registered for - * `options.provider`. Replay state is retained only when the same adapter - * instance owns its historical provider and the target provider. Final - * adapter selection remains fixed through asynchronous exact-model resolution - * and dispatch. Selection, dispatch, and iteration failures retain their - * original Error identity and are tagged in a call-local scope for narrow - * agent-loop request recovery; middleware and nested-call failures remain - * untagged for the outer call. + * Stream one model call as raw chunks (token-level deltas). Replay state is + * retained only when the same adapter instance owns its historical provider + * and the target provider. Final adapter selection remains fixed through + * asynchronous exact-model resolution and dispatch. Adapter selection, + * dispatch, and iteration failures become terminal `error` or `aborted` + * finish chunks; middleware, nested-call, cleanup, and consumer failures + * remain thrown. * @param options - the full request; `options.provider` selects the adapter. * @returns the chunk stream, possibly wrapped by `llm/stream` listeners. */ @@ -560,14 +553,23 @@ export class LlmService extends Service { options: GenerateOptions, prepared?: { registration: AdapterRegistration; config: LlmCallConfig }, ): AsyncIterable { - const failures: AdapterFailureScope = { failures: new WeakMap() } - const stream = this.ctx.waterfall( + return this.ctx.waterfall( this, 'llm/stream', options, - () => this.adapterStream(options, failures, prepared), + () => this.adapterStream(options, prepared), ) - return bindAdapterFailureScope(stream, failures) + } +} + +/** Convert one adapter throw into the stream protocol's terminal outcome. */ +function adapterFailureChunk(error: unknown, signal?: AbortSignal): StreamChunk { + const failure = normalizeLlmFailure(error) + return { + type: 'finish', + reason: signal?.aborted || failure.code === 'ABORTED' + ? { kind: 'aborted', failure } + : { kind: 'error', failure }, } } diff --git a/packages/llm/llm/src/invariant.ts b/packages/llm/llm/src/invariant.ts index 76d55509cb..8af9c42f46 100644 --- a/packages/llm/llm/src/invariant.ts +++ b/packages/llm/llm/src/invariant.ts @@ -72,7 +72,9 @@ async function* validateStream( usageSeen = true break case 'finish': - if (open.size > 0) fail(`LLM stream finished with ${open.size} open block(s)`) + if (open.size > 0 && chunk.reason.kind !== 'error' && chunk.reason.kind !== 'aborted') { + fail(`LLM stream finished with ${open.size} open block(s)`) + } finished = true break } diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts index 4e6e0eabe2..66e988084c 100644 --- a/packages/llm/llm/src/types.ts +++ b/packages/llm/llm/src/types.ts @@ -170,8 +170,9 @@ export interface LlmResolvedModelInfo extends LlmModelInfo { * Raw streaming protocol emitted by adapters. * Block indexes correlate interleaved deltas, and `block-end` carries the * assembled block. Adapters emit usage before the terminal finish and nothing - * afterward; tool arguments remain raw JSON strings. Failures either throw or - * end with `error`/`aborted`, and consumers must handle both paths. + * afterward; tool arguments remain raw JSON strings. An adapter implementation + * may throw, but `LlmService.stream()` normalizes that failure to a terminal + * `error` or `aborted` finish before exposing it to consumers. */ export type StreamChunk = | { type: 'block-start'; index: number; blockType: ContentBlockType } diff --git a/packages/llm/token-meter/tests/token-meter.spec.ts b/packages/llm/token-meter/tests/token-meter.spec.ts index 30342e81ec..c23ba0b38e 100644 --- a/packages/llm/token-meter/tests/token-meter.spec.ts +++ b/packages/llm/token-meter/tests/token-meter.spec.ts @@ -670,7 +670,7 @@ describe('malformed replay and listener lifecycle', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }] }) activeMeter.measure(session) session.append('user/message', createUserMessage({ diff --git a/packages/plan/plan-mode/tests/invariant.spec.ts b/packages/plan/plan-mode/tests/invariant.spec.ts index fe31510be7..4826036bf4 100644 --- a/packages/plan/plan-mode/tests/invariant.spec.ts +++ b/packages/plan/plan-mode/tests/invariant.spec.ts @@ -19,7 +19,7 @@ function event(active: unknown): SessionEvent { function emitTurnStart(ctx: Context, session: Session): void { ctx.emit('session/event', session, { type: 'turn/start', seq: 0, time: 0, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }) } @@ -56,7 +56,7 @@ describe('plan-mode stream invariants', () => { expect(() => { ctx.emit('tools/change') ctx.emit('session/event', session, { - type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + type: 'turn/start', seq: 0, time: 0, data: { turn: 1 }, }) }).not.toThrow() }) @@ -65,7 +65,7 @@ describe('plan-mode stream invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('plan/mode', { active: 'plan' as unknown as boolean }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await ctx.plugin(InvariantService, { enabled: true }) @@ -77,7 +77,7 @@ describe('plan-mode stream invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('plan/mode', { active: true }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await ctx.plugin(InvariantService, { enabled: true }) diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts index 72d273d20f..d988fc3d1c 100644 --- a/packages/plan/plan-mode/tests/plan-mode.spec.ts +++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts @@ -75,7 +75,7 @@ async function boundary(ctx: Context, agent: Agent & { session: Session }, type: /** Open a turn so a selection queues for the boundary flush (the mid-turn shape). */ function openTurn(session: Session, turn = 0): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) } /** Close the open turn (the between-turns shape: selections commit immediately). */ diff --git a/packages/plan/plan-mode/tests/projection.spec.ts b/packages/plan/plan-mode/tests/projection.spec.ts index 7c69417e58..c26112c8fd 100644 --- a/packages/plan/plan-mode/tests/projection.spec.ts +++ b/packages/plan/plan-mode/tests/projection.spec.ts @@ -58,7 +58,7 @@ function runPlanCommand(session: Session, args: string, index: number): void { /** Commit one plan/mode flip inside an open turn (the invariant's turn-enclosure rule). */ function commitPlanMode(session: Session, active: boolean, turn: number): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('plan/mode', { active }) session.append('turn/end', { turn, reason: { kind: 'completed' } }) } diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts index 153e29842d..5fa6ada775 100644 --- a/packages/pty/pty-local/tests/index.spec.ts +++ b/packages/pty/pty-local/tests/index.spec.ts @@ -42,7 +42,7 @@ function agent(ctx: Context): Agent { const id = SessionId('agent') return { id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } @@ -232,7 +232,7 @@ describe('pty-local plugin shape', () => { const session = ctx.sessions.create(SessionId('unowned-mode')) expect(() => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) }).not.toThrow() expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow() }) @@ -249,7 +249,7 @@ describe('pty-local plugin shape', () => { const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession()) @@ -258,7 +258,7 @@ describe('pty-local plugin shape', () => { const unrelated = ctx.sessions.create(SessionId('unrelated-mode')) expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow() expect(() => { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) }).not.toThrow() expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow() @@ -292,7 +292,7 @@ describe('pty-local plugin shape', () => { const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) const gate = Promise.withResolvers() diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts index d045dc4d26..6c217d518a 100644 --- a/packages/pty/pty-local/tests/local.spec.ts +++ b/packages/pty/pty-local/tests/local.spec.ts @@ -35,7 +35,7 @@ function stubAgent(ctx: Context, rawId: string): Agent { const scope = ctx.plugin(() => {}) return { id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } diff --git a/packages/pty/pty/tests/service.spec.ts b/packages/pty/pty/tests/service.spec.ts index 905708fbb1..734848782c 100644 --- a/packages/pty/pty/tests/service.spec.ts +++ b/packages/pty/pty/tests/service.spec.ts @@ -31,7 +31,6 @@ function stubAgent(ctx: Context, rawId: string): Agent { followup: () => {}, steer: () => {}, inject: () => {}, - send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts index 85d0deefb8..024253d3e9 100644 --- a/packages/pty/tool-pty/tests/loader-composition.spec.ts +++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts @@ -40,7 +40,7 @@ function agent(ctx: Context): Agent { const id = SessionId('pty-loader-agent') const value: Agent = { id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(value) return value diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts index ec754aa96c..43b50d92ee 100644 --- a/packages/pty/tool-pty/tests/tools.spec.ts +++ b/packages/pty/tool-pty/tests/tools.spec.ts @@ -18,7 +18,7 @@ function fakeAgent(ctx: Context, rawId: string): Agent { const id = SessionId(rawId) const agent: Agent = { id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(agent) return agent diff --git a/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts b/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts index 4d128c0012..0b10ae591f 100644 --- a/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts +++ b/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts @@ -61,7 +61,7 @@ describe('session-checkpoint-policy request boundary', () => { it('awaits the live session checkpoint before constructing the downstream model stream', async () => { const ctx = await setup() const session = ctx.sessions.create(SessionId('request-checkpoint')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const gate = Promise.withResolvers() const order: string[] = [] ctx.on('session/flush', async () => { diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts index 5171bb8585..87d630a56e 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts @@ -59,7 +59,7 @@ afterEach(async () => { }) function appendClosedTurn(session: Session): void { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' }, @@ -208,7 +208,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { it('round-trip is byte-identical (incl. assistant/chunk verbatim)', async () => { const m = meta('chunks') const log: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } }, { type: 'assistant/chunk', seq: 2, time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'he' } } }, { type: 'assistant/chunk', seq: 3, time: 4, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'llo' } } }, @@ -342,7 +342,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { await mkdir(sessionDir(root, m.cwd, m.id), { recursive: true }) await writeFile(path, [ JSON.stringify(toHeaderLine(m)), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), JSON.stringify({ type: 'request/header-delta', seq: 1, time: 2, data: { config: { model: 'legacy' } } }), JSON.stringify({ type: 'turn/end', seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }), '', @@ -397,7 +397,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { // partial line with no newline (a torn fragment never fully flushed). const path = rawLogPath(root, '/proj', m.id) await writeFile(path, [ - JSON.stringify({ type: 'turn/start', seq: 6, time: 8, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 6, time: 8, data: { turn: 2 } }), JSON.stringify({ type: 'step/start', seq: 7, time: 9, data: { turn: 2, step: 1 } }), '{"type":"assistant/chunk","seq":8,"ti', // truncated partial line (no newline) ].join('\n'), { flag: 'a' }) @@ -416,7 +416,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { // The next append continues at seq 10 (the balanced length). const turn3 = [ - { type: 'turn/start', seq: 10, time: 11, data: { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 10, time: 11, data: { turn: 3 } }, { type: 'turn/end', seq: 11, time: 12, data: { turn: 3, reason: { kind: 'completed' } } }, ] as SessionEvent[] await ctx.sessionPersistence.append(m.id, turn3) @@ -435,7 +435,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { await writeFile(rawLogPath(root, undefined, m.id), '\n{"partial', { flag: 'a' }) await ctx.sessionPersistence.load(m.id) await ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[]) const after = await readFile(rawLogPath(root, undefined, m.id), 'utf8') @@ -463,7 +463,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { }) const turn2 = [ - { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[] // The append rejects, but the partial bytes are truncated back: the file is @@ -501,7 +501,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { try { await ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } }, ] as SessionEvent[]) throw new Error('expected append to reject') } catch (error) { @@ -526,7 +526,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { // metadata must be unaffected, so a later append still finds the right log. mutableHeader(loaded.meta).cwd = '/evil' await ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[]) // The append landed in the ORIGINAL /proj log, not beside an /evil path. @@ -543,7 +543,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }]) await ctx.sessionPersistence.create(b) await ctx.sessionPersistence.append(b.id, oneTurnLog()) @@ -596,8 +596,8 @@ describe('SessionPersistenceJsonl: write path (session/event → flush)', () => const a = ctx.sessions.create(SessionId('sa')) const b = ctx.sessions.create(SessionId('sb')) - a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + a.append('turn/start', { turn: 1 }) + b.append('turn/start', { turn: 1 }) a.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'A' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -678,7 +678,7 @@ describe('SessionPersistenceJsonl: scanLog unit', () => { it('a seq gap after the last turn/end bounds the preserved tail (torn fragment tolerated)', () => { const log = [ JSON.stringify({ type: 'session', version: 0, id: 'g', createdAt: 1, delegationDepth: 0 }), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), JSON.stringify({ type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1 ].join('\n') + '\n' // No committed turn/end, so the gap is a tolerated crash boundary: scanLog PRESERVES the @@ -690,7 +690,7 @@ describe('SessionPersistenceJsonl: scanLog unit', () => { it('rejects a seq gap BEFORE a later committed turn/end (committed data damaged)', () => { const log = [ JSON.stringify({ type: 'session', version: 0, id: 'g2', createdAt: 1, delegationDepth: 0 }), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), JSON.stringify({ type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1 JSON.stringify({ type: 'turn/end', seq: 3, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }), ].join('\n') + '\n' @@ -719,7 +719,7 @@ describe('SessionPersistenceJsonl: scanLog unit', () => { it('a corrupt line after the last turn/end bounds the preserved tail', () => { const log = [ JSON.stringify({ type: 'session', version: 0, id: 'c2', createdAt: 1, delegationDepth: 0 }), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), '{not json', // corrupt crash fragment, no turn/end committed ].join('\n') + '\n' // The contiguous prefix (turn/start seq 0) is preserved; the corrupt @@ -730,7 +730,7 @@ describe('SessionPersistenceJsonl: scanLog unit', () => { it('tolerates a seq gap AFTER a turn/end (uncommitted tail)', () => { const log = [ JSON.stringify({ type: 'session', version: 0, id: 't', createdAt: 1, delegationDepth: 0 }), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), JSON.stringify({ type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }), JSON.stringify({ type: 'step/start', seq: 9, time: 3, data: { turn: 2, step: 1 } }), // gap in uncommitted tail ].join('\n') + '\n' @@ -760,7 +760,7 @@ describe('SessionPersistenceJsonl: default packed chunk rows', () => { data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: `t${k}` } }, })) return [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } }, ...deltas, { type: 'assistant/message', seq: 7, time: 8, data: { @@ -851,7 +851,7 @@ describe('SessionPersistenceJsonl: default packed chunk rows', () => { it('scanLog: a packed row advances the seq cursor by its whole run', () => { const logText = [ JSON.stringify({ type: 'session', version: 0, id: 'rows', createdAt: 1, delegationDepth: 0 }), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), JSON.stringify({ type: 'text-chunks', seq0: 1, time0: 2, data: { turn: 1, step: 1, index: 0, dt: [1, 1], texts: ['a', 'b', 'c'] } }), JSON.stringify({ type: 'turn/end', seq: 4, time: 5, data: { turn: 1, reason: { kind: 'completed' } } }), ].join('\n') + '\n' @@ -873,7 +873,7 @@ describe('SessionPersistenceJsonl: default packed chunk rows', () => { it('scanLog: a packed row with a mid-run seq gap after the last turn/end drops the whole row', () => { const logText = [ JSON.stringify({ type: 'session', version: 0, id: 'row-gap', createdAt: 1, delegationDepth: 0 }), - JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), // seq0 skips 1 — the run's first member is already a gap; no turn/end follows. JSON.stringify({ type: 'text-chunks', seq0: 2, time0: 2, data: { turn: 1, step: 1, index: 0, dt: [1, 1], texts: ['a', 'b', 'c'] } }), ].join('\n') + '\n' @@ -1151,7 +1151,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { // A live session materializes and owns the id. const firstFiber = await ctx.plugin(Object.assign((inner: Context) => { const a = inner.sessions.create(SessionId('bound'), { meta: { cwd: '/a' } }) - a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + a.append('turn/start', { turn: 1 }) a.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }, { inject: ['sessions'] })) for (const s of ctx.sessions.list()) await ctx.sessions.flush(s) @@ -1229,7 +1229,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { await ctx2.plugin(SessionStore) await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) await ctx2.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[]) const loaded = await ctx2.sessionPersistence.load(m.id) @@ -1244,7 +1244,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { const m = meta('open-turn', '/h') await ctx.sessionPersistence.create(m) await ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, ] as SessionEvent[]) const { events } = await ctx.sessionPersistence.load(m.id) expect(events.map(e => e.type)).toEqual(['turn/start', 'turn/end']) @@ -1276,7 +1276,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' }) const session = ctx2.sessions.create(SessionId('flush-fail')) // A full turn lands in the write-behind buffer. - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts index cef1ff71e5..566d649a79 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts @@ -285,7 +285,7 @@ describe('SessionPersistenceJsonl: default Zstandard encoding', () => { const path = logPath(root, header.cwd, header.id, 'zstd') const before = await readFile(path) const secondTurn = [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[] await ctx.sessionPersistence.append(header.id, secondTurn) @@ -380,7 +380,7 @@ describe('SessionPersistenceJsonl: default Zstandard encoding', () => { const path = logPath(root, header.cwd, header.id, 'zstd') const committed = await readFile(path) const openTurn = [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } }, { type: 'assistant/chunk', seq: 8, time: 9, data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: deterministicNoise(300_000) } } }, ] as SessionEvent[] @@ -427,7 +427,7 @@ describe('SessionPersistenceJsonl: default Zstandard encoding', () => { await ctx.sessionPersistence.append(header.id, oneTurnLog()) const path = logPath(root, header.cwd, header.id, 'zstd') const secondTurn = [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[] const frame = await compressZstdFrame(secondTurn.map(e => JSON.stringify(e)).join('\n') + '\n') @@ -475,7 +475,7 @@ describe('SessionPersistenceJsonl: default Zstandard encoding', () => { return realSync.call(this) }) const secondTurn = [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, ] as SessionEvent[] await expect(ctx.sessionPersistence.append(header.id, secondTurn)).rejects.toThrow(/simulated Zstandard fsync failure/) diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts index ddc46880cf..da22c9bc00 100644 --- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts +++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts @@ -107,7 +107,7 @@ describe('scanRows', () => { // is no torn fragment to delete. (load() then synthesizes the closers.) const withOpenTurn: SessionEvent[] = [ ...oneTurnLog(), - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } }, ] const { preserved, tornFrom } = scanRows(rows(withOpenTurn)) @@ -119,7 +119,7 @@ describe('scanRows', () => { // A gap after seq 0 (no committed turn/end): seq 0 is the preserved // interrupted-turn event; the gap bounds it and marks the torn fragment. const gapped: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }, // seq 1 missing ] const { preserved, tornFrom } = scanRows(rows(gapped)) @@ -133,7 +133,7 @@ describe('scanRows', () => { it('throws on a seq gap inside the committed region (before the last turn/end)', () => { const gapped: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }, // seq 1 missing { type: 'turn/end', seq: 3, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }, ] @@ -183,7 +183,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => { db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length, delegation_depth, incarnation, revision) VALUES (?, ?, ?, ?, NULL, NULL, NULL, ?, 1)') .run(m.id, m.version, m.createdAt, m.cwd ?? null, 'legacy-header-delta') const insert = db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)') - insert.run(m.id, 0, 'turn/start', 1, JSON.stringify({ turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })) + insert.run(m.id, 0, 'turn/start', 1, JSON.stringify({ turn: 1 })) insert.run(m.id, 1, 'request/header-delta', 2, JSON.stringify({ config: { model: 'legacy' } })) insert.run(m.id, 2, 'turn/end', 3, JSON.stringify({ turn: 1, reason: { kind: 'completed' } })) db.close() @@ -228,7 +228,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => { await ctx1.sessionPersistence.create(m) await ctx1.sessionPersistence.append(m.id, oneTurnLog()) await ctx1.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } }, ]) await fiber1.dispose() @@ -251,7 +251,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => { // load durably closed the turn, so the next append continues at the balanced // length (seq 10) and a reload round-trips identically. await ctx2.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 10, time: 9, data: { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 10, time: 9, data: { turn: 3 } }, { type: 'turn/end', seq: 11, time: 10, data: { turn: 3, reason: { kind: 'completed' } } }, ]) const reloaded = await ctx2.sessionPersistence.load(m.id) @@ -269,7 +269,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => { // Hand-write an interrupted turn (turn/start seq 6, no turn/end). const db = openDatabase(path, 'wal') db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, 6, ?, 7, ?)') - .run(m.id, 'turn/start', JSON.stringify({ turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })) + .run(m.id, 'turn/start', JSON.stringify({ turn: 2 })) db.close() const b2 = await backend(path) @@ -294,7 +294,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => { await b1.ctx.sessionPersistence.create(m) // A first turn that NEVER completed: turn/start + user/message, no turn/end. await b1.ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message', seq: 1, time: 2, data: createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }) }, @@ -477,7 +477,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => { expect(loaded.events).toEqual(oneTurnLog()) // torn tail discarded, committed intact (turn 1 already balanced → no closers) // load physically deleted the corrupt tail row, so a fresh append continues. await b2.ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 8, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 8, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 9, data: { turn: 2, reason: { kind: 'completed' } } }, ]) const reloaded = await b2.ctx.sessionPersistence.load(m.id) @@ -703,7 +703,7 @@ describe('SessionPersistenceSqlite: edge cases', () => { const b2 = await backend(path) await b2.ctx.sessionPersistence.load(m.id) // cursor 6 in b2 const turn2: SessionEvent[] = [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, ] // b1 commits seq 6..7 first. @@ -761,7 +761,7 @@ describe('SessionPersistenceSqlite: edge cases', () => { await ctx.plugin(Object.assign((inner: Context) => { session = inner.sessions.create(SessionId('hmr-collide')) }, { inject: ['sessions'] })) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await ctx.plugin(SessionPersistenceSqlite, { path }) await expectFlushError(ctx.sessions.flush(session), /id collision/) await ctx.fiber.dispose() @@ -814,7 +814,7 @@ describe('surface field round-trip', () => { await ctx.plugin(SessionStore) const fiber = await ctx.plugin(SessionPersistenceSqlite, { path: ':memory:' }) const session = ctx.sessions.create(SessionId('roundtrip-surface')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, @@ -849,7 +849,7 @@ describe('surface field round-trip', () => { await ctx.plugin(SessionStore) const fiber = await ctx.plugin(SessionPersistenceSqlite, { path: ':memory:' }) const session = ctx.sessions.create(SessionId('surface-noseq')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('steering/message', { turn: 1, message: createUserMessage({ diff --git a/packages/session-persistence/session-persistence/tests/contract.ts b/packages/session-persistence/session-persistence/tests/contract.ts index 9ff82101d7..ca9384b616 100644 --- a/packages/session-persistence/session-persistence/tests/contract.ts +++ b/packages/session-persistence/session-persistence/tests/contract.ts @@ -33,7 +33,7 @@ export function meta(id: string, cwd?: string): SessionHeader { /** A well-formed one-turn event log (contiguous seqs from 0). */ export function oneTurnLog(): SessionEvent[] { return [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message', seq: 1, time: 2, data: freezeMessage({ id: MessageId('one-turn-user'), role: 'user', @@ -124,7 +124,7 @@ export function runPersistenceContract(name: string, make: () => Promise Promise Promise Promise Promise event.type)).toEqual(['turn/start']) @@ -347,7 +347,7 @@ export function runPersistenceContract(name: string, make: () => Promise snapshot.header.id === m.id) expect(changed?.revision).not.toBe(first?.revision) @@ -376,7 +376,7 @@ export function runPersistenceContract(name: string, make: () => Promise Promise< session = inner.sessions.create(SessionId('live-load'), { meta: { cwd: WORK } }) }, { inject: ['sessions'] })) try { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await ctx.sessions.flush(session) await expect(ctx.sessionPersistence.load(session.id)) @@ -206,7 +206,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, } await ctx.sessionPersistence.create(header) await ctx.sessionPersistence.append(id, [start]) @@ -294,7 +294,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const { ctx, fiber } = await freshCtx(fix) try { const session = ctx.sessions.create(SessionId('mutate'), { meta: { cwd: WORK } }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const ev = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'original' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -450,7 +450,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const p = ctx.sessionPersistence.append(m.id, events) // Mutate the caller's array AND an event object after the call but before // the queued op runs: the snapshot taken at call time must shield the copy. - events.push({ type: 'turn/start', seq: 6, time: 99, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }) + events.push({ type: 'turn/start', seq: 6, time: 99, data: { turn: 2 } }) if (userMsg?.type === 'user/message') { (userMsg.data as { content: unknown[] }).content = [{ type: 'text', text: 'MUTATED' }] } @@ -505,7 +505,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const loaded = await second.ctx.sessionPersistence.load(SessionId('resumed')) const s2 = second.ctx.sessions.create(SessionId('resumed'), { seed: loaded.events, meta: { cwd: WORK } }) await second.ctx.sessions.flush(s2) // let onCreated adopt - s2.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + s2.append('turn/start', { turn: 2 }) s2.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) await second.ctx.sessions.flush(s2) @@ -525,7 +525,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< await ctx.plugin(SessionStore) // A session exists BEFORE the persistence plugin is applied. const session = ctx.sessions.create(SessionId('pre-existing'), { meta: { cwd: WORK } }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -549,7 +549,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< await ctx.plugin(SessionStore) const fiber = await fix.mount(ctx) const session = await liveSessionInFiber(ctx, 'drain', WORK) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'buffered' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -577,7 +577,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< try { // Backend instance 1 materializes the session. const backend1 = await fix.mount(ctx) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -589,7 +589,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< // materialized prefix, then persist another turn rather than rejecting it as a collision. await backend1.dispose() await fix.mount(ctx) - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 2 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'again' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -612,7 +612,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< try { // Instance 1 flushes turn 1. const backend1 = await fix.mount(ctx) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await ctx.sessions.flush(session) @@ -620,7 +620,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< // flushing turn 2: it is now ONLY in the live session's events; the new // backend never buffered it via session/event. await backend1.dispose() - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 2 }) session.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) // Instance 2 adopts the stored prefix (turn 1) and MUST also persist the @@ -643,7 +643,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const session = await liveSessionInFiber(ctx, 'hmr-open', WORK) try { const first = await fix.mount(ctx) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) await ctx.sessions.flush(session) @@ -686,7 +686,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const second = await freshCtx(fix) try { const s2 = second.ctx.sessions.create(SessionId('collide'), { meta: { cwd: WORK } }) - s2.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + s2.append('turn/start', { turn: 1 }) await expect(second.ctx.sessions.flush(s2)) .rejects.toThrow(/already has a persisted log|id collision/) } finally { @@ -713,7 +713,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< reuse = inner.sessions.create(SessionId('abandoned'), { meta: { cwd: WORK } }) }, { inject: ['sessions'] })) await expect(ctx.sessions.flush(reuse)).resolves.toBeUndefined() - reuse.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + reuse.append('turn/start', { turn: 1 }) reuse.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await ctx.sessions.flush(reuse) const loaded = await ctx.sessionPersistence.load(SessionId('abandoned')) @@ -734,7 +734,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< }, { inject: ['sessions'] })) await ctx.sessions.flush(first) // Append a turn but do NOT flush — events sit in the write-behind buffer. - first.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + first.append('turn/start', { turn: 1 }) first.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await firstFiber.dispose() @@ -761,7 +761,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const { ctx, fiber } = await freshCtx(fix) try { const session = ctx.sessions.create(SessionId('idem'), { meta: { cwd: WORK } }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -838,7 +838,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const contFiber = await ctx.plugin(Object.assign((inner: Context) => { cont = inner.sessions.create(SessionId('claim'), { seed: [ ...events, - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, ], meta: { cwd: WORK, createdAt: 2000 } }) }, { inject: ['sessions'] })) @@ -928,7 +928,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< const second = await freshCtx(fix) try { await second.ctx.sessionPersistence.append(SessionId('adopt-append'), [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'turn/end', seq: 7, time: 8, data: { turn: 2, reason: { kind: 'completed' } } }, ]) const loaded = await second.ctx.sessionPersistence.load(SessionId('adopt-append')) @@ -1028,7 +1028,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< // async onCreated init has necessarily set state (exercises the // state-undefined cursor path). const session = ctx.sessions.create(SessionId('flush-nostate'), { meta: { cwd: WORK } }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -1061,7 +1061,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< await first.ctx.sessionPersistence.append(m.id, oneTurnLog()) // committed 0..5 (balanced) // A second turn whose real events are durable but never closed (open turn). await first.ctx.sessionPersistence.append(m.id, [ - { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 6, time: 7, data: { turn: 2 } }, { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } }, ]) } finally { @@ -1088,7 +1088,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise< // The repair is durable: the next append continues at the balanced length // (seq 10) and a reload round-trips identically. await second.ctx.sessionPersistence.append(SessionId('torn'), [ - { type: 'turn/start', seq: 10, time: 9, data: { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 10, time: 9, data: { turn: 3 } }, { type: 'turn/end', seq: 11, time: 10, data: { turn: 3, reason: { kind: 'completed' } } }, ]) const reloaded = await second.ctx.sessionPersistence.load(SessionId('torn')) diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session-persistence/session-persistence/tests/persistence.spec.ts index bca32438f4..b9f7ebd361 100644 --- a/packages/session-persistence/session-persistence/tests/persistence.spec.ts +++ b/packages/session-persistence/session-persistence/tests/persistence.spec.ts @@ -237,7 +237,7 @@ describe('PersistenceCoordinator eager writes', () => { try { const session = ctx.sessions.create(SessionId('eager-follow-up')) await ctx.sessions.flush(session) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) @@ -272,7 +272,7 @@ describe('PersistenceCoordinator eager writes', () => { try { const session = ctx.sessions.create(SessionId('eager-flush-retry')) await ctx.sessions.flush(session) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) }) @@ -302,7 +302,7 @@ describe('PersistenceCoordinator stored identity', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }], }) let coordinator!: PersistenceCoordinator @@ -329,7 +329,7 @@ describe('PersistenceCoordinator stored identity', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, } backend.store.set(id, { meta: header, events: [start] }) const loadGate = Promise.withResolvers() @@ -534,7 +534,7 @@ describe('PersistenceCoordinator observation cancellation', () => { const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => { session = inner.sessions.create(id) }, { inject: ['sessions'] })) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) // Dispose the session so retirement starts; its append is gated, so the // retirement promise stays pending in the coordinator. @@ -677,7 +677,7 @@ describe('PersistenceCoordinator retirement', () => { }, { inject: ['sessions'] })) await ctx.sessions.flush(first) backend.beforeAppend = async () => { await appendGate.promise } - first.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + first.append('turn/start', { turn: 1 }) first.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) }) await firstFiber.dispose() @@ -717,7 +717,7 @@ describe('PersistenceCoordinator retirement', () => { }, { inject: ['sessions'] })) await ctx.sessions.flush(first) backend.beforeAppend = async () => { await appendGate.promise } - first.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + first.append('turn/start', { turn: 1 }) first.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) }) await firstFiber.dispose() @@ -776,7 +776,7 @@ describe('PersistenceCoordinator retirement', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }]) const secondAppend = coordinator.append(id, [{ type: 'turn/end', @@ -824,7 +824,7 @@ describe('PersistenceCoordinator retirement', () => { const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => { session = inner.sessions.create(SessionId('retry-retirement')) }, { inject: ['sessions'] })) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await sessionFiber.dispose() @@ -868,7 +868,7 @@ describe('PersistenceCoordinator retirement', () => { const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => { session = inner.sessions.create(SessionId('inflight-retirement')) }, { inject: ['sessions'] })) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await sessionFiber.dispose() await vi.waitFor(() => { @@ -916,7 +916,7 @@ describe('PersistenceCoordinator retirement', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }]) await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) }) @@ -1053,7 +1053,7 @@ describe('SessionPersistence service registration', () => { const sessionFiber = await ctx.plugin(Object.assign((inner: Context) => { session = inner.sessions.create(SessionId(`disposed-${index}`)) }, { inject: ['sessions'] })) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) await ctx.sessions.flush(session) await sessionFiber.dispose() diff --git a/packages/session-projection/session-projection-cache/tests/cache.spec.ts b/packages/session-projection/session-projection-cache/tests/cache.spec.ts index 8cf9345772..8474e21594 100644 --- a/packages/session-projection/session-projection-cache/tests/cache.spec.ts +++ b/packages/session-projection/session-projection-cache/tests/cache.spec.ts @@ -221,7 +221,7 @@ describe('SessionProjectionCache write policy', () => { describe('SessionProjectionCache cold read', () => { const storedLog = (marks: string[][]): SessionEvent[] => { const events: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } }, ] for (const m of marks) { events.push({ type: 'cache-test/mark', seq: events.length, time: events.length, data: { marks: m } }) diff --git a/packages/session-projection/session-projection/tests/registry.spec.ts b/packages/session-projection/session-projection/tests/registry.spec.ts index 90b8de4a40..bd33914b2d 100644 --- a/packages/session-projection/session-projection/tests/registry.spec.ts +++ b/packages/session-projection/session-projection/tests/registry.spec.ts @@ -97,7 +97,7 @@ describe('SessionProjectionRegistry drive', () => { }) const event = mark(session, ['a']) // Non-matching event: apply returns the same reference — no notification. - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) expect(seen).toEqual([{ key: 'test/marks', value: { marks: ['a'] }, seq: event.seq, sessionId: String(session.id) }]) }) @@ -119,7 +119,7 @@ describe('SessionProjectionRegistry drive', () => { ctx.sessionProjections.onChanged((_session, key) => { changedKeys.push(key) }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) // count applied (+1 change), marks returned the same reference. expect(changedKeys).toEqual(['test/count']) const snapshot = ctx.sessionProjections.snapshot(session) @@ -235,7 +235,7 @@ describe('SessionProjectionRegistry drive', () => { }, tail, 3)).toThrow(/re-read from seq 0/) // The full-log re-read (baseSeq 0) refolds the mismatched key from init. const full: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } }, { type: 'test/mark', seq: 1, time: 1, data: { marks: ['old'] } }, { type: 'test/mark', seq: 2, time: 2, data: { marks: ['old', '2'] } }, ...tail, @@ -261,7 +261,7 @@ describe('SessionProjectionRegistry drive', () => { 'test/count': { ver: 1, seq: 2, val: 3 }, } const tail: SessionEvent[] = [ - { type: 'turn/start', seq: 3, time: 3, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 3, time: 3, data: { turn: 2 } }, { type: 'turn/end', seq: 4, time: 4, data: { turn: 2, reason: { kind: 'completed' } } }, ] const { snapshot } = ctx.sessionProjections.restore(rows, tail, 3) @@ -309,7 +309,7 @@ describe('SessionProjectionRegistry drive', () => { expect(() => ctx.sessionProjections.restore(rows, [], 9)).toThrow(/re-read from seq 0/) // The full re-read discards the overreaching row and refolds from init. const events: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } }, { type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } } }, ] const { snapshot } = ctx.sessionProjections.restore(rows, events, 0) diff --git a/packages/session-query/session-query/src/extraction.ts b/packages/session-query/session-query/src/extraction.ts index ffdde75e04..be52d469dd 100644 --- a/packages/session-query/session-query/src/extraction.ts +++ b/packages/session-query/session-query/src/extraction.ts @@ -45,12 +45,9 @@ export function extractSessionEventText(event: SessionEvent): string { function turnEndText(reason: SessionEvent<'turn/end'>['data']['reason']): string { switch (reason.kind) { case 'error': - return 'failure' in reason - ? joinText(['error', reason.failure.message, reason.failure.code]) - : joinText(['error', reason.message, reason.code ?? '']) + return joinText(['error', reason.error instanceof Error ? reason.error.message : String(reason.error)]) case 'aborted': return 'aborted' - case 'disposed': case 'max-tokens': case 'interrupted': return reason.kind diff --git a/packages/session-query/session-query/tests/search-helpers.spec.ts b/packages/session-query/session-query/tests/search-helpers.spec.ts index 5117de7ef7..891b95892c 100644 --- a/packages/session-query/session-query/tests/search-helpers.spec.ts +++ b/packages/session-query/session-query/tests/search-helpers.spec.ts @@ -125,7 +125,7 @@ describe('session-query semantic extraction', () => { expect(extractSessionEventText({ type: 'turn/end', seq: 0, time: 1, data: { turn: 1, reason } })).toBe(text) } const structural: SessionEvent[] = [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } }, { type: 'step/end', seq: 2, time: 1, data: { turn: 1, step: 1 } }, { type: 'assistant/chunk', seq: 3, time: 1, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'raw' } } }, diff --git a/packages/session-query/session-query/tests/session-query.spec.ts b/packages/session-query/session-query/tests/session-query.spec.ts index c22bbcd98a..c0ffdd2c7f 100644 --- a/packages/session-query/session-query/tests/session-query.spec.ts +++ b/packages/session-query/session-query/tests/session-query.spec.ts @@ -893,7 +893,7 @@ describe('session-query exact reads', () => { it('classifies current, shadowed, and raw-log-only events through foldSurface', async () => { const ctx = await liveContext() const session = ctx.sessions.create(SessionId('surface')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) const first = session.append( 'user/message', @@ -1008,7 +1008,7 @@ describe('session-query exact reads', () => { it('returns a bounded detached raw-event window and validates the request', async () => { const ctx = await liveContext({ readWindowMax: 1 }) const session = ctx.sessions.create(SessionId('window'), { meta: { cwd: '/work' } }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) for (const text of ['one', 'two', 'three']) { session.append( 'user/message', @@ -1050,7 +1050,7 @@ describe('session-query exact reads', () => { ]) const ctx = await liveContext() const live = ctx.sessions.create(shared.id, { meta: { createdAt: 3, cwd: '/same' } }) - live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + live.append('turn/start', { turn: 1 }) live.append( 'user/message', createUserMessage({ @@ -1090,7 +1090,7 @@ describe('session-query exact reads', () => { TestPersistence.reset() const ctx = await liveContext() const live = ctx.sessions.create(SessionId('live')) - live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + live.append('turn/start', { turn: 1 }) live.append( 'user/message', createUserMessage({ diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts index 21e1a9089b..a6b5d73eb9 100644 --- a/packages/session-query/session-query/tests/tracing.spec.ts +++ b/packages/session-query/session-query/tests/tracing.spec.ts @@ -106,7 +106,7 @@ function expectCode(code: SessionQueryErrorCode): Error { } function appendTraceEvents(session: Session): void { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) session.append('assistant/chunk', { turn: 1, @@ -348,7 +348,7 @@ describe('session event tracing', () => { expect([TracePersistence.listCalls, TracePersistence.inspectCalls]).toEqual([1, 1]) const live = ctx.sessions.create(durable.id, { meta: { createdAt: 1, cwd: '/same' } }) - live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + live.append('turn/start', { turn: 1 }) live.append( 'user/message', createUserMessage({ @@ -412,7 +412,7 @@ describe('session event tracing', () => { it.each([ ['non-surface sources', [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, sourceEventSeqs: [0] }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 }, sourceEventSeqs: [0] }, ]], ['invalid source array', [ { ...appendEvent(0), sourceEventSeqs: 'invalid' }, @@ -461,7 +461,7 @@ describe('session event tracing', () => { type: 'turn/start', seq: 0, time: 1, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, surfaceOp: 'append', }] as unknown as SessionEvent[] TracePersistence.reset([{ meta: durable, events }]) diff --git a/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts b/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts index 414bebc867..09c9c2e812 100644 --- a/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts +++ b/packages/session-query/tool-session-query/tests/sqlite-integration.spec.ts @@ -64,7 +64,7 @@ describe('tool-session-query with the real SQLite provider', () => { const caller = ctx.sessions.create(SessionId('caller'), { meta: { createdAt: 10, cwd: '/work' }, }) - caller.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + caller.append('turn/start', { turn: 1 }) caller.append( 'user/message', createUserMessage({ diff --git a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts index b6fab0e68e..dc513e890b 100644 --- a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts +++ b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts @@ -64,7 +64,7 @@ function createSession( } function openStep(session: Session, text = 'prior needle'): void { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append( 'user/message', createUserMessage({ diff --git a/packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts b/packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts index f8d6117d10..5390607d23 100644 --- a/packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts +++ b/packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts @@ -32,7 +32,7 @@ async function settle(): Promise { describe('all-messages LLM title provider', () => { it('includes seeded history and the latest prompt while inheriting the logged request route', async () => { const seeded = new Session(SessionId('seed-source')) - seeded.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + seeded.append('turn/start', { turn: 1 }) const inherited = seeded.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'inherited prompt' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -52,7 +52,7 @@ describe('all-messages LLM title provider', () => { seed: seeded.events, meta: { parentSession: seeded.id, seedLength: seeded.seq }, }) - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 2 }) const latest = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'latest prompt' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) diff --git a/packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts b/packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts index 25fded0c38..eb0125efd9 100644 --- a/packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts +++ b/packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts @@ -93,7 +93,6 @@ describe('session-title Loader composition', () => { const session = ctx.sessions.create(SessionId('loader-title')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const message = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'Compose a title through Loader' }], diff --git a/packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts b/packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts index 1268656551..3154a3577c 100644 --- a/packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts +++ b/packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts @@ -37,7 +37,6 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('first-message title provider wit const session = ctx.sessions.create(SessionId('real-title-provider')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const message = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'Explain why append-only logs make session titles durable.' }], diff --git a/packages/session-title/session-title-first-message-llm/tests/provider.spec.ts b/packages/session-title/session-title-first-message-llm/tests/provider.spec.ts index 5b9f7240ec..554cfab8ca 100644 --- a/packages/session-title/session-title-first-message-llm/tests/provider.spec.ts +++ b/packages/session-title/session-title-first-message-llm/tests/provider.spec.ts @@ -60,7 +60,7 @@ describe('first-message LLM title provider', () => { ctx.llm.registerAdapter(['title-route'], adapter) await ctx.plugin(providerPlugin, LLM_CONFIG) const session = ctx.sessions.create(SessionId('first-plugin')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const first = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'first input' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) diff --git a/packages/session-title/session-title-llm/tests/llm.spec.ts b/packages/session-title/session-title-llm/tests/llm.spec.ts index beed98ec45..17d1a2b2b9 100644 --- a/packages/session-title/session-title-llm/tests/llm.spec.ts +++ b/packages/session-title/session-title-llm/tests/llm.spec.ts @@ -80,7 +80,6 @@ function request(ctx: Context, signal = new AbortController().signal): SessionTi const session = ctx.sessions.create(SessionId(`title-call-${++nextSession}`)) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const first = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'first prompt' }], diff --git a/packages/session-title/session-title/tests/persistence.spec.ts b/packages/session-title/session-title/tests/persistence.spec.ts index c4023ccce7..7d5428983f 100644 --- a/packages/session-title/session-title/tests/persistence.spec.ts +++ b/packages/session-title/session-title/tests/persistence.spec.ts @@ -25,7 +25,6 @@ async function appendPersistedTitle(ctx: Context, id: ReturnType { const firstSeq = appendTitle(session, 'First title') const secondSeq = appendTitle(session, 'Second title') // Unrelated event: same-reference apply, no notification. - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) expect(changes).toEqual([ { key: 'title', value: 'First title', seq: firstSeq }, { key: 'title', value: 'Second title', seq: secondSeq }, diff --git a/packages/session-title/session-title/tests/provider.spec.ts b/packages/session-title/session-title/tests/provider.spec.ts index c47b6c32e8..5bfe30ac14 100644 --- a/packages/session-title/session-title/tests/provider.spec.ts +++ b/packages/session-title/session-title/tests/provider.spec.ts @@ -55,7 +55,6 @@ describe('SessionTitleService provider lifecycle', () => { const parent = ctx.sessions.create(SessionId('title-parent')) parent.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const inheritedMessage = appendHumanPrompt(parent, 'Inherited title prompt') await settle() @@ -77,7 +76,6 @@ describe('SessionTitleService provider lifecycle', () => { }) child.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const childMessage = appendHumanPrompt(child, 'Child follow-up prompt') await settle() @@ -98,7 +96,6 @@ describe('SessionTitleService provider lifecycle', () => { }) child.append('turn/start', { turn: 3, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const latestMessage = appendHumanPrompt(child, 'Retitle the fork now') await settle() @@ -136,7 +133,6 @@ describe('SessionTitleService provider lifecycle', () => { const session = ctx.sessions.create(SessionId('first-provider')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const first = appendHumanPrompt(session, 'Explain asynchronous title generation') await settle() @@ -195,7 +191,6 @@ describe('SessionTitleService provider lifecycle', () => { const session = ctx.sessions.create(SessionId('dispose-provider')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const message = appendHumanPrompt(session, 'Generate this title') await settle() @@ -245,7 +240,6 @@ describe('SessionTitleService provider lifecycle', () => { const session = ctx.sessions.create(SessionId('supersede')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const first = appendHumanPrompt(session, 'First prompt') await settle() @@ -286,7 +280,6 @@ describe('SessionTitleService provider lifecycle', () => { const session = ctx.sessions.create(SessionId('unchanged-route')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const first = appendHumanPrompt(session, 'First routed prompt') await settle() @@ -298,7 +291,6 @@ describe('SessionTitleService provider lifecycle', () => { session.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const second = appendHumanPrompt(session, 'Second prompt on the same route') await settle() @@ -345,7 +337,6 @@ describe('SessionTitleService provider lifecycle', () => { const pending = ctx.sessions.create(SessionId('unmatched-boundary')) pending.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) appendHumanPrompt(pending, 'Wait for a matching request boundary') await settle() @@ -369,7 +360,6 @@ describe('SessionTitleService provider lifecycle', () => { const session = ctx.sessions.create(SessionId('failure')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) appendHumanPrompt(session, 'Keep a fallback') await settle() diff --git a/packages/session-title/session-title/tests/service-contracts.spec.ts b/packages/session-title/session-title/tests/service-contracts.spec.ts index f481d8b02e..609e9fb3b9 100644 --- a/packages/session-title/session-title/tests/service-contracts.spec.ts +++ b/packages/session-title/session-title/tests/service-contracts.spec.ts @@ -37,7 +37,6 @@ function startSession(ctx: Context, id: string): ReturnType { disposeCtx.sessions.announce(disposed) disposed.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const disposedMessage = appendPrompt(disposed, 'Dispose this session') await settle() @@ -168,7 +166,6 @@ describe('SessionTitleService configuration and refresh boundaries', () => { const seed = new Session(SessionId('fallback-concurrency-seed')) seed.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const source = appendPrompt(seed, 'Create exactly one fallback title') seed.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) @@ -337,7 +334,6 @@ describe('SessionTitleService configuration and refresh boundaries', () => { }) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) appendPrompt(session, 'Detach before the fallback microtask') await settle() diff --git a/packages/session-title/session-title/tests/session-title.spec.ts b/packages/session-title/session-title/tests/session-title.spec.ts index b43d5a1876..8b2a24a314 100644 --- a/packages/session-title/session-title/tests/session-title.spec.ts +++ b/packages/session-title/session-title/tests/session-title.spec.ts @@ -43,7 +43,6 @@ describe('SessionTitleService', () => { const session = ctx.sessions.create(SessionId('fresh')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) const message = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: ' Build\nlog-backed session titles please ' }], @@ -80,7 +79,6 @@ describe('SessionTitleService', () => { const session = ctx.sessions.create(SessionId('prefixed-title')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'Explain this referenced session' }], @@ -99,7 +97,6 @@ describe('SessionTitleService', () => { const session = ctx.sessions.create(SessionId('eligibility')) session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: { kind: 'user' } }, }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'plugin text' }], diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts index 5348af69b6..9937417ec3 100644 --- a/packages/skill/tool-skill/tests/tool-skill.spec.ts +++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts @@ -4,7 +4,6 @@ import { join } from 'node:path' import { tmpdir } from 'node:os' import { Context } from 'cordis' import { createUserMessage, CallId, type Message } from '@deepseek-ai/dsh-llm' -import {} from '@deepseek-ai/dsh-agent' import { Session, SessionId } from '@deepseek-ai/dsh-session' import { createScope, type Scope } from '@deepseek-ai/dsh-scope' import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt' @@ -46,7 +45,6 @@ function agentForCwd(cwd: string): Agent { session, status: 'idle', acceptsNextStep: false, - send: () => {}, followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts index c6f9b4059b..e165440f0d 100644 --- a/packages/subagent/subagent-inprocess/src/index.ts +++ b/packages/subagent/subagent-inprocess/src/index.ts @@ -10,7 +10,7 @@ import { randomUUID } from 'node:crypto' import type { Context } from 'cordis' import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent' -import { findLastMessageTurnEnd, SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' +import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' import { createUserMessage, type ContentBlock } from '@deepseek-ai/dsh-llm' import { assertSubagentMaxDepth, delegationDepthOf } from '@deepseek-ai/dsh-subagent' import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent' @@ -47,7 +47,6 @@ function toStopReason(reason: TurnEndReason | undefined): SubagentStopReason { case 'aborted': return 'aborted' case 'error': - case 'disposed': case 'interrupted': default: return 'error' @@ -160,7 +159,8 @@ export async function startInProcessRun( const result: Promise = (async () => { try { - child.followup(createUserMessage({ content: request.prompt, source: { kind: 'user' } })) + const message = createUserMessage({ content: request.prompt, source: { kind: 'user' } }) + child.followup(message) await child.whenIdle() return readResult( child, @@ -194,12 +194,11 @@ function readResult( ): SubagentResult { const own = child.session.events.slice(seedLength) const lastMessage = own.findLast((event): event is SessionEvent<'assistant/message'> => event.type === 'assistant/message') - const lastEnd = findLastMessageTurnEnd(own) + const lastEnd = own.findLast((event): event is SessionEvent<'turn/end'> => event.type === 'turn/end') const output: ContentBlock[] = lastMessage?.data.message.content ?? [] const recorded = toStopReason(lastEnd?.data.reason) - // Disposal can tear the owner down before the loop records its ordinary - // `aborted` end, yielding `disposed` instead. A requested cancellation owns - // every non-completed in-flight outcome; a turn already completed stays so. + // A requested cancellation owns every non-completed in-flight outcome; a + // turn already completed stays so. const stopReason: SubagentStopReason = cancelled && recorded !== 'completed' ? 'aborted' : recorded diff --git a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts index fb631ee10e..0697af4b72 100644 --- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts @@ -56,34 +56,27 @@ describe('startInProcessRun', () => { expect(ctx.agents.get(run.id)).toBeUndefined() }) - it('reports the message-turn outcome when a later non-message turn completes during flush', async () => { - const { ctx, parent } = await setup([maxTokensResponse('partial answer')]) - let injected = false - ctx.on('session/flush', (session) => { - if (injected || session.header.parentSession === undefined) return - const lastEnd = session.events.findLast(event => event.type === 'turn/end') - if (lastEnd?.type !== 'turn/end' || lastEnd.data.reason.kind !== 'max-tokens') return - injected = true - const turn = lastEnd.data.turn + 1 - session.append('turn/start', { - turn, - trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } }, - }) - session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'late metadata' }], - source: { kind: 'plugin', plugin: 'late-metadata' }, - }), { surfaceOp: 'append' }) - session.append('turn/end', { turn, reason: { kind: 'completed' } }) + it('reports the final whole-agent outcome after idle replacement work', async () => { + const { ctx, parent } = await setup([maxTokensResponse('partial answer'), textResponse('replacement answer')]) + let replaced = false + ctx.on('agent/status', (agent, status) => { + if (replaced || status !== 'idle' || agent.session.header.parentSession === undefined) return + replaced = true + agent.followup(createUserMessage({ + content: [{ type: 'text', text: 'replacement work' }], + source: { kind: 'plugin', plugin: 'replacement' }, + })) }) const run = await startInProcessRun(request(parent), {}) const result = await run.result const child = ctx.agents.get(run.id)! - expect(injected).toBe(true) + expect(replaced).toBe(true) expect(child.session.events.findLast(event => event.type === 'turn/end')) .toMatchObject({ data: { reason: { kind: 'completed' } } }) - expect(result.stopReason).toBe('max-tokens') + expect(result.stopReason).toBe('completed') + expect(text(result.output)).toBe('replacement answer') await run.dispose() }) diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts index d693c0571b..467cc26a0b 100644 --- a/packages/support/llm-replay/tests/llm-replay.spec.ts +++ b/packages/support/llm-replay/tests/llm-replay.spec.ts @@ -141,7 +141,7 @@ describe('deriveReplayScript', () => { it('ignores non-assistant/chunk events', () => { let seq = 1 const events: SessionEvent[] = [ - { type: 'turn/start', seq: seq++, time: 0, data: { turn: 1, trigger: { kind: 'injection', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: seq++, time: 0, data: { turn: 1 } }, ...TEXT_CHUNKS.map(c => chunkEvent(seq++, 1, 1, c)), { type: 'turn/end', seq: seq++, time: 0, data: { turn: 1, reason: { kind: 'completed' } } }, ] diff --git a/packages/tasks/tasks-local/tests/tasks.spec.ts b/packages/tasks/tasks-local/tests/tasks.spec.ts index 590f752956..da595c602a 100644 --- a/packages/tasks/tasks-local/tests/tasks.spec.ts +++ b/packages/tasks/tasks-local/tests/tasks.spec.ts @@ -28,7 +28,6 @@ function stubAgent(ctx: Context, rawId: string): Agent { followup: () => {}, steer: () => {}, inject: () => {}, - send: () => {}, cancel() {}, whenIdle() { return Promise.resolve() }, } diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts index cccb90ed43..d6f8bf0664 100644 --- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts +++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts @@ -93,7 +93,7 @@ describe('TelemetryOtel wire', () => { const { url, captures } = await mockCollector() const { ctx, fiber } = await boot(url) const session = ctx.sessions.create(SessionId('wire'), { meta: { cwd: '/tmp/w' } }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } }) await fiber.dispose() @@ -146,7 +146,7 @@ describe('TelemetryOtel wire', () => { processor: { scheduledDelayMillis: 10 }, }) const session = ctx.sessions.create(SessionId('drain'), { meta: {} }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await arrived.promise const disposal = fiber.dispose() @@ -171,7 +171,7 @@ describe('TelemetryOtel wire', () => { exporter: { url, compression: 'gzip' }, } as Config) const session = ctx.sessions.create(SessionId('gzip'), { meta: {} }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) await fiber.dispose() expect(captures.length).toBeGreaterThan(0) @@ -186,7 +186,7 @@ describe('TelemetryOtel wire', () => { const { ctx, fiber } = await boot(url) ctx.on('telemetry/record', (_record, next) => ({ ...next(), severity: 'warn' })) const session = ctx.sessions.create(SessionId('warn'), { meta: {} }) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) // No flush(): the coordinator's optional-call forwarding no-ops, and the // batch processor owns export cadence end to end (see the backend note). expect('flush' in ctx.telemetry && ctx.telemetry.flush !== undefined).toBe(false) diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts index a449a4053d..c5d3fb650a 100644 --- a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts +++ b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts @@ -70,7 +70,7 @@ function liveSession(ctx: Context, id = `s-${Math.random().toString(36).slice(2) } function appendTurn(session: Session): void { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) @@ -108,7 +108,7 @@ describe('TelemetryCoordinator capture', () => { it('maps outcome flags to severity, unknown types falling through as info', async () => { const { ctx, backend } = await setup() const session = liveSession(ctx) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('tool/result', { turn: 1, step: 1, message: createToolResultMessage({ @@ -194,7 +194,7 @@ describe('TelemetryCoordinator adoption', () => { const ctx = new Context() await ctx.plugin(SessionStore) const donor = ctx.sessions.create(SessionId('donor'), { meta: {} }) - donor.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + donor.append('turn/start', { turn: 1 }) donor.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'first' } }) const resumed = ctx.sessions.create(SessionId('resumed'), { seed: [...donor.events], meta: {} }) await ctx.plugin({ @@ -261,7 +261,7 @@ describe('TelemetryCoordinator adoption', () => { const backend = new FakeBackend() const { ctx, fiber } = await setup(backend) const session = liveSession(ctx, 'hmr') - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'first' } }) expect(backend.ledger()).toHaveLength(2) @@ -408,7 +408,7 @@ describe('TelemetryCoordinator lifecycle and containment', () => { const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) const session = liveSession(ctx) backend.emitError = new Error('backend broke') - expect(() => session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })).not.toThrow() + expect(() => session.append('turn/start', { turn: 1 })).not.toThrow() expect(warn).toHaveBeenCalled() backend.emitError = undefined session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) diff --git a/packages/todo/tool-todo/tests/invariant.spec.ts b/packages/todo/tool-todo/tests/invariant.spec.ts index abfcd74b29..f186711845 100644 --- a/packages/todo/tool-todo/tests/invariant.spec.ts +++ b/packages/todo/tool-todo/tests/invariant.spec.ts @@ -47,7 +47,7 @@ describe('todo snapshot invariants', () => { expect(() => { ctx.emit('tools/change') ctx.emit('session/event', {} as Session, { - type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + type: 'turn/start', seq: 0, time: 0, data: { turn: 1 }, }) }).not.toThrow() }) diff --git a/packages/todo/tool-todo/tests/projection.spec.ts b/packages/todo/tool-todo/tests/projection.spec.ts index ede937801d..7090ddfca6 100644 --- a/packages/todo/tool-todo/tests/projection.spec.ts +++ b/packages/todo/tool-todo/tests/projection.spec.ts @@ -99,7 +99,7 @@ describe('todos projection provider', () => { session.append('todo/write', { todos: list }) session.append('turn/end', { turn: 0, reason: { kind: 'completed' } }) expect((await bench.tailProjections())?.values.todos).toEqual(list) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const cleared = await bench.tailProjections() expect(cleared?.values.todos).toBeNull() expect(cleared?.asOfSeq).toBe(session.seq - 1) diff --git a/packages/ui/commands/tests/commands.spec.ts b/packages/ui/commands/tests/commands.spec.ts index f22e974d58..770c46ef61 100644 --- a/packages/ui/commands/tests/commands.spec.ts +++ b/packages/ui/commands/tests/commands.spec.ts @@ -396,7 +396,7 @@ describe('CommandService', () => { const ctx = await mount() const { agent } = await mintAgentScope(ctx, 'a') ctx.commands.register(command('mid')) - agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + agent.session.append('turn/start', { turn: 1 }) await ctx.commands.execute(agent, '/mid', new AbortController().signal) expect(agent.session.events.map(event => event.type)).toEqual([ 'turn/start', 'command/run', 'command/done', diff --git a/packages/ui/jsonrpc/src/server.ts b/packages/ui/jsonrpc/src/server.ts index aa4769aebc..7143e4c525 100644 --- a/packages/ui/jsonrpc/src/server.ts +++ b/packages/ui/jsonrpc/src/server.ts @@ -10,7 +10,7 @@ import { resolve } from 'node:path' import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent' import { createUserMessage } from '@deepseek-ai/dsh-llm' import { carrierKeyOf, type Scoped } from '@deepseek-ai/dsh-scope' -import { findLastMessageTurnEnd, SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session' +import { SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session' import type SubagentService from '@deepseek-ai/dsh-subagent' import type { SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' @@ -28,7 +28,6 @@ import type { interface SessionRecord { handle: AgentHandle - lastTurnEnd: TurnEndReason | undefined activePrompt: boolean } @@ -72,12 +71,6 @@ export class HarnessSdkServer { ) { const serverOptions = this.options this.disposers.push(ctx.on('session/event', (session, event) => { - if (event.type === 'turn/end') { - const rec = this.sessions.get(String(session.id)) - if (rec && findLastMessageTurnEnd(session.events)?.seq === event.seq) { - rec.lastTurnEnd = event.data.reason - } - } const payload: SessionEventNotification = { sessionId: String(session.id), event } this.transport.notify('session.event', payload) })) @@ -146,13 +139,15 @@ export class HarnessSdkServer { } rec.activePrompt = true try { - rec.lastTurnEnd = undefined - rec.handle.agent.followup(createUserMessage({ content: params.contentBlocks, source: { kind: 'user' } })) + const message = createUserMessage({ content: params.contentBlocks, source: { kind: 'user' } }) + rec.handle.agent.followup(message) await rec.handle.agent.whenIdle() + const lastEnd = rec.handle.agent.session.events.findLast(event => event.type === 'turn/end') + const reason = lastEnd?.data.reason const payload: SessionFinishedNotification = { sessionId: params.sessionId, - status: this.finishedStatus(rec.lastTurnEnd), - reason: rec.lastTurnEnd, + status: this.finishedStatus(reason), + reason, } this.transport.notify('session.finished', payload) return { accepted: true } @@ -244,7 +239,7 @@ export class HarnessSdkServer { ...this.maxTokens === undefined ? {} : { maxTokens: this.maxTokens }, }, }) - const rec: SessionRecord = { handle, lastTurnEnd: undefined, activePrompt: false } + const rec: SessionRecord = { handle, activePrompt: false } this.sessions.set(sessionId, rec) return rec } diff --git a/packages/ui/jsonrpc/tests/server.spec.ts b/packages/ui/jsonrpc/tests/server.spec.ts index 19ad56881c..7f634474da 100644 --- a/packages/ui/jsonrpc/tests/server.spec.ts +++ b/packages/ui/jsonrpc/tests/server.spec.ts @@ -255,7 +255,7 @@ describe('HarnessSdkServer', () => { await server.shutdown() }) - it('reports the message-turn outcome when a later non-message turn settles before idle', async () => { + it('reports the final whole-agent outcome after later activity settles', async () => { const ctx = new Context() await ctx.plugin(SessionStore) await ctx.plugin(AgentRegistry) @@ -272,13 +272,11 @@ describe('HarnessSdkServer', () => { followup(input: UserMessage) { session.append('turn/start', { turn: 1, - trigger: { kind: 'message', source: input.source }, }) session.append('user/message', input, { surfaceOp: 'append' }) session.append('turn/end', { turn: 1, reason: { kind: 'max-tokens' } }) session.append('turn/start', { turn: 2, - trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } }, }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'late metadata' }], @@ -306,8 +304,8 @@ describe('HarnessSdkServer', () => { method: 'session.finished', params: { sessionId: 'message-outcome', - status: 'error', - reason: { kind: 'max-tokens' }, + status: 'ok', + reason: { kind: 'completed' }, }, }) await server.shutdown() diff --git a/packages/ui/tui/src/components/dialogs.ts b/packages/ui/tui/src/components/dialogs.ts index 5e9237574a..9a17408de9 100644 --- a/packages/ui/tui/src/components/dialogs.ts +++ b/packages/ui/tui/src/components/dialogs.ts @@ -460,7 +460,6 @@ function resumeTurnLabel(snapshot: SessionLogSnapshot): string { case 'completed': return `turn ${event.data.turn}: completed` case 'aborted': return `turn ${event.data.turn}: cancelled` case 'error': return `turn ${event.data.turn}: error` - case 'disposed': return `turn ${event.data.turn}: disposed` case 'max-tokens': return `turn ${event.data.turn}: max tokens` case 'interrupted': return `turn ${event.data.turn}: interrupted` default: return `turn ${event.data.turn}: unknown result` diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index d1ba37e61d..c04dc8582b 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -5,20 +5,7 @@ * @module @deepseek-ai/dsh-tui */ -import { - CombinedAutocompleteProvider, - Container, - Key, - Spacer, - Text, - TUI, - ProcessTerminal, - matchesKey, - visibleWidth, - type EditorTheme, - type SlashCommand, - type TerminalColorScheme, -} from '@earendil-works/pi-tui' +import { CombinedAutocompleteProvider, Container, Key, Spacer, Text, TUI, ProcessTerminal, matchesKey, visibleWidth, type EditorTheme, type SlashCommand, type TerminalColorScheme } from '@earendil-works/pi-tui' import { Service, type Context, type Fiber } from 'cordis' import { assembleContextFor, @@ -343,6 +330,7 @@ export function createTuiChat( const pendingSteering = new Set() let disposed = false let shuttingDown: Promise | undefined + let exitAfterIdle = false // Optional: skills mount conditionally, so read the global service store // rather than declaring an injection that would make the TUI require them. const skills = ctx.get('skills') @@ -786,9 +774,15 @@ export function createTuiChat( case 'completed': break case 'error': { - const key = `${event.data.turn}:${reason.step}` - const message = 'failure' in reason ? reason.failure.message : reason.message - if (!liveErrors.delete(key)) appendNotice(message, 'error') + const prefix = `${event.data.turn}:` + let alreadyReported = false + for (const key of liveErrors) { + if (!key.startsWith(prefix)) continue + liveErrors.delete(key) + alreadyReported = true + } + const message = reason.error instanceof Error ? reason.error.message : String(reason.error) + if (!alreadyReported) appendNotice(message, 'error') break } case 'aborted': @@ -797,9 +791,6 @@ export function createTuiChat( case 'max-tokens': appendNotice('The model reached its output-token limit.', 'warning') break - case 'disposed': - appendNotice('Turn stopped: the agent was disposed.', 'warning') - break case 'interrupted': appendNotice('The previous process ended during this turn.', 'warning') break @@ -892,9 +883,9 @@ export function createTuiChat( const requestExit = (): void => { if (agent.status === 'running') { + exitAfterIdle = true agent.cancel({ kind: 'user' }) appendNotice('Cancelling the active turn before exit…', 'warning') - void agent.whenIdle().then(() => shutdown(true)) return } void shutdown(true) @@ -1190,67 +1181,14 @@ export function createTuiChat( appendNotice(`Agent "${agent.id}" is disposed.`, 'error') return } - if (agent.acceptsNextStep) { - // Steering is never subject to prompt admission; an attached snapshot - // drains beside it at the same step boundary through the outbox. - if (attachedContext !== undefined) { - agent.inject(attachedContext) - } - const message = createUserMessage({ content, source: { kind: 'user' } }) - agent.steer(message) - pendingSteering.add(message.id) - refreshStatus() - return - } - if (attachedContext === undefined) { - agent.followup(createUserMessage({ content, source: { kind: 'user' } })) - return - } - // Idle: the snapshot rides the prompt's admission transaction so a - // blocking hook discards both together. - let cleanedUp = false - const message: UserMessage = createUserMessage({ content, source: { kind: 'user' } }) - const acceptedId = message.id - const discarded = new Set() - const cleanup = (): void => { - // Every completion path detaches both listeners. Keep this - // idempotent so later cleanup paths cannot double-release them. - /* v8 ignore next -- unreachable idempotence guard, see above */ - if (cleanedUp) return - cleanedUp = true - detachSubmit() - detachDiscard() - } - // Prepended so this wrapper is outermost: it observes the exact accepted - // message identity whether a downstream hook allows or blocks, then detaches. - const detachSubmit = ctx.on('agent/prompt-submit', async (subject, submitted, _signal, next) => { - if (subject !== agent || submitted.id !== message.id) return next() - cleanup() - const decision = await next() - if (decision.kind !== 'allow') return decision - return { ...decision, additionalContexts: [...decision.additionalContexts ?? [], attachedContext] } - }, { prepend: true }) - // Installed before followup(): an enqueue listener can synchronously - // cancel and discard before followup() returns its id. - const detachDiscard = ctx.on('agent/inbox/discard', (subject, messages) => { - if (subject !== agent) return - for (const message of messages) discarded.add(message.id) - if (discarded.has(acceptedId)) cleanup() - }) - // followup() accepts any typed input and contains listener failures; - // this guards a future synchronous throw so the wrapper cannot leak. - /* v8 ignore start -- future-proofing guard, see above */ - try { - agent.followup(message) - if (discarded.has(acceptedId)) cleanup() - } catch (error: unknown) { - cleanup() - throw error - } - /* v8 ignore stop */ + if (attachedContext !== undefined) agent.inject(attachedContext) + const message = createUserMessage({ content, source: { kind: 'user' } }) + agent.steer(message) + pendingSteering.add(message.id) + refreshStatus() } - /** Deliver a user turn to the agent: steer while running, send while idle, or report a disposed agent. */ + /** Deliver user input to the nearest step, or report a disposed agent. */ const deliver = (payload: string): void => { dispatchMessage([{ type: 'text', text: payload }]) } @@ -1448,14 +1386,11 @@ export function createTuiChat( const settlePendingSteering = (id: MessageId): void => { if (pendingSteering.delete(id)) refreshStatus() } - const disposeDequeued = ctx.on('agent/inbox/dequeue', (subject, message) => { + const disposeDequeued = ctx.on('agent/inbox/admitted', (subject, message) => { if (subject === agent) settlePendingSteering(message.id) }) - const disposeDiscarded = ctx.on('agent/inbox/discard', (subject, messages) => { - if (subject !== agent) return - let changed = false - for (const message of messages) changed = pendingSteering.delete(message.id) || changed - if (changed) refreshStatus() + const disposeDiscarded = ctx.on('agent/inbox/canceled', (subject, message) => { + if (subject === agent && pendingSteering.delete(message.id)) refreshStatus() }) const disposeStatus = ctx.on('agent/status', (subject, status) => { if (subject !== agent) return @@ -1464,6 +1399,10 @@ export function createTuiChat( // the queue without logging drains, cannot strand a stale count). if (status !== 'running') pendingSteering.clear() setStatus(status) + if (status === 'idle' && exitAfterIdle) { + exitAfterIdle = false + void shutdown(true) + } }) const disposeError = ctx.on('agent/error', (subject, turn, step, error) => { if (subject !== agent) return diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts index 87282276f8..3c120f0c5e 100644 --- a/packages/ui/tui/tests/harness.ts +++ b/packages/ui/tui/tests/harness.ts @@ -6,7 +6,6 @@ import AgentRegistry, { type AgentCancelCause, type AgentOptions, type AgentStatus, - type SendOptions, } from '@deepseek-ai/dsh-agent' import type { ContentBlock, @@ -27,7 +26,6 @@ interface FakeAgent extends Agent { status: AgentStatus sent: ContentBlock[][] sentMessages: UserMessage[] - sentOptions: (SendOptions | undefined)[] steered: ContentBlock[][] steeredIds: MessageId[] steeredOptions: UserMessage[] @@ -178,7 +176,6 @@ export async function createTuiTestHarness { session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) session.append('turn/start', { turn: 2, - trigger: { kind: 'message', source: { kind: 'user' } }, }) appendUser(session, 'Next question.') }, @@ -774,14 +773,14 @@ describe('TUI terminal-state snapshots', () => { turn: 1, reason: { kind: 'error', step: 1, message: 'provider stream failed after partial output' }, }) - harness.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + harness.session.append('turn/start', { turn: 2 }) harness.session.append('turn/end', { turn: 2, reason: { kind: 'interrupted' }, }) - harness.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }) + harness.session.append('turn/start', { turn: 3 }) harness.session.append('turn/end', { turn: 3, reason: { kind: 'disposed' } }) - harness.session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } }) + harness.session.append('turn/start', { turn: 4 }) // A merge-extensible turn-end kind unknown to the TUI still surfaces its // name so the agent never stops without a visible reason. harness.session.append('turn/end', { turn: 4, reason: { kind: 'plugin-policy' } as never }) @@ -822,7 +821,7 @@ describe('TUI terminal-state snapshots', () => { const log = (meta: typeof earlier, title: string, day: string): { meta: typeof earlier; events: SessionEvent[] } => ({ meta, events: [ - { type: 'turn/start', seq: 0, time: Date.parse(`${day}T00:00:01Z`), data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: Date.parse(`${day}T00:00:01Z`), data: { turn: 1 } }, { type: 'user/message', seq: 1, time: Date.parse(`${day}T00:00:02Z`), data: createUserMessage({ content: [{ type: 'text', text: 'restore the selector' }], source: { kind: 'user' } }), surfaceOp: 'append' }, { type: 'step/start', seq: 2, time: Date.parse(`${day}T00:00:03Z`), data: { turn: 1, step: 1 } }, { type: 'request/header', seq: 3, time: Date.parse(`${day}T00:00:04Z`), data: { header: { config: { provider: 'deepseek', model: 'deepseek-v4-pro' } }, reason: 'initial' } }, diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index e918f9b299..2090a9824a 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -239,7 +239,7 @@ describe('goodbye message and /resume', () => { time = 100, reason: TurnEndReason = { kind: 'completed' }, ): SessionEvent[] => [ - { type: 'turn/start', seq: 0, time, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time, data: { turn: 1 } }, { type: 'user/message', seq: 1, time: time + 1, data: createUserMessage({ content: [{ type: 'text', text: 'resume me' }], source: { kind: 'user' }, }), surfaceOp: 'append' }, @@ -1333,9 +1333,9 @@ describe('pi-tui chat lifecycle and transcript', () => { appendAssistant(result.session, []) result.session.append('step/end', { turn: 1, step: 1 }) result.session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) - result.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + result.session.append('turn/start', { turn: 2 }) result.session.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) - result.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }) + result.session.append('turn/start', { turn: 3 }) result.session.append('step/start', { turn: 3, step: 1 }) result.session.append('assistant/chunk', { turn: 3, @@ -1872,7 +1872,7 @@ describe('pi-tui chat lifecycle and transcript', () => { expect(result.terminal.output).not.toContain('│') expect(result.terminal.output).not.toContain('Response 1s') - result.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + result.session.append('turn/start', { turn: 2 }) result.session.append('step/start', { turn: 2, step: 1 }) clock += 1_000 result.terminal.output = '' @@ -3760,7 +3760,7 @@ describe('pi-tui chat lifecycle and transcript', () => { const events = await setup() const unrelatedSession = events.ctx.sessions.create(SessionId('unrelated-session')) const unrelatedAgent = { ...events.agent, id: unrelatedSession.id, session: unrelatedSession } - unrelatedSession.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + unrelatedSession.append('turn/start', { turn: 1 }) unrelatedSession.append('todo/write', { todos: [{ content: 'hidden', status: 'pending' }] }) agentEvents(events.ctx, unrelatedAgent).emit('agent/status', 'running') agentEvents(events.ctx, unrelatedAgent).emit('agent/error', 1, 1, new Error('hidden error')) @@ -3768,22 +3768,22 @@ describe('pi-tui chat lifecycle and transcript', () => { agentEvents(events.ctx, events.agent).emit('agent/error', 1, 1, new Error('live failure')) events.session.append('step/end', { turn: 1, step: 1 }) events.session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'live failure' } }) - events.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 2 }) events.session.append('turn/end', { turn: 2, reason: { kind: 'error', step: 1, message: 'durable failure' } }) - events.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 3 }) events.session.append('turn/end', { turn: 3, reason: { kind: 'aborted' } }) - events.session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 4 }) events.session.append('turn/end', { turn: 4, reason: { kind: 'max-tokens' } }) - events.session.append('turn/start', { turn: 5, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 5 }) events.session.append('turn/end', { turn: 5, reason: { kind: 'interrupted' } }) - events.session.append('turn/start', { turn: 6, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 6 }) events.session.append('turn/end', { turn: 6, reason: { kind: 'error', step: 1, failure: { message: 'structured provider failure', code: 'SERVER' } }, }) - events.session.append('turn/start', { turn: 8, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 8 }) events.session.append('turn/end', { turn: 8, reason: { kind: 'disposed' } }) - events.session.append('turn/start', { turn: 9, trigger: { kind: 'message', source: { kind: 'user' } } }) + events.session.append('turn/start', { turn: 9 }) // Merge-extensible reason kind unknown to the TUI still names the stop. events.session.append('turn/end', { turn: 9, reason: { kind: 'plugin-policy' } as never }) agentEvents(events.ctx, events.agent).emit('agent/disposed') @@ -4715,7 +4715,7 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() mountTui(ctx, { theme: { color: false } }, { terminal, exit: vi.fn() }) @@ -4740,7 +4740,7 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() // Mirror dsh-tui's own inject (minus loader, the absence under test). @@ -4775,14 +4775,14 @@ describe('terminal mounting', () => { const otherSession = ctx.sessions.create(SessionId('other-session')) ctx.agents.register({ id: otherSession.id, options: {}, session: otherSession, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) expect(terminal.started).toBe(0) const session = ctx.sessions.create(SessionId('late-session')) const agent = { id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } as Agent ctx.agents.register(agent) await tick() @@ -4813,7 +4813,7 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main-session')) ctx.agents.register({ id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) await tick() expect(terminal.started).toBe(0) @@ -4853,11 +4853,11 @@ describe('terminal mounting', () => { await ctx.plugin(TuiPromptService) ctx.provide('tools', { get: () => undefined } as never) const session = ctx.sessions.create(SessionId('failed-start-session')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) ctx.agents.register({ id: session.id, options: {}, session, status: 'running', acceptsNextStep: true, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() terminal.start = () => { throw new Error('terminal startup failed') } diff --git a/packages/ui/user-approval/tests/approval.spec.ts b/packages/ui/user-approval/tests/approval.spec.ts index 0d586049fa..f779b1e250 100644 --- a/packages/ui/user-approval/tests/approval.spec.ts +++ b/packages/ui/user-approval/tests/approval.spec.ts @@ -118,7 +118,7 @@ describe('ApprovalService.request', () => { await ctx.plugin(SessionStore) await ctx.plugin(ApprovalService) const session = ctx.sessions.create(SessionId('asked-observer-throw')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const agent = { session } as unknown as Agent const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) ctx.on('session/event', (_session, event) => { @@ -141,7 +141,7 @@ describe('ApprovalService.request', () => { await ctx.plugin(SessionStore) await ctx.plugin(ApprovalService) const session = ctx.sessions.create(SessionId('decided-observer-throw')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const agent = { session } as unknown as Agent const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) ctx.on('session/event', (_session, event) => { @@ -360,7 +360,7 @@ describe('approval policy (the approval/policy fold)', () => { */ function sessionAgent(id: string): { agent: Agent; session: Session; injected: string[] } { const session = new Session(SessionId(id)) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const injected: string[] = [] const agent = { id, diff --git a/packages/ui/user-approval/tests/invariant.spec.ts b/packages/ui/user-approval/tests/invariant.spec.ts index 924272a360..6be086df4a 100644 --- a/packages/ui/user-approval/tests/invariant.spec.ts +++ b/packages/ui/user-approval/tests/invariant.spec.ts @@ -14,7 +14,7 @@ async function setup(): Promise { } function startTurn(session: Session): void { - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) } describe('approval invariants', () => { @@ -32,7 +32,7 @@ describe('approval invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const id = ApprovalRequestId('ask-resume') session.append('approval/asked', { id, toolName: 'bash' }) await ctx.plugin(InvariantService) @@ -54,7 +54,7 @@ describe('approval invariants', () => { expect(() => { ctx.emit('session/event', session, { type: 'turn/start', seq: 0, time: 0, - data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + data: { turn: 1 }, }) ctx.emit('session/event', session, asked) ctx.emit('session/event', session, decided) diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 6b9d698e2a..fc3b61f4af 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -35,10 +35,8 @@ export const LINK_MAP: Record = { ContinuationDecision: 'core.md', ContinuationStop: 'core.md', GenerateOptions: 'core.md', - InboxPlacement: 'core.md', MessageId: 'core.md', HookContext: 'core.md', - SettleReason: 'core.md', LlmCallConfig: 'core.md', LlmModelContext: 'core.md', LlmModelReasoningInfo: 'core.md', @@ -52,7 +50,7 @@ export const LINK_MAP: Record = { UserMessage: 'session.md', PromptDecision: 'core.md', RequestErrorAction: 'core.md', - RequestError: 'core.md', + RequestFailureContext: 'core.md', PreparedReferencedMessage: 'session-reference.md', SessionReferenceCandidate: 'session-reference.md', SessionReferenceInput: 'session-reference.md', diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 5821cd0a01..6d43db72ba 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -86,21 +86,11 @@ "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "SendTarget", - "source": "packages/core/agent/src/types.ts" - }, { "doc": "docs/core-data-structures/core.md", "symbol": "InboxPlacement", "source": "packages/core/agent/src/types.ts" }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "SendOptions", - "source": "packages/core/agent/src/types.ts" - }, { "doc": "docs/core-data-structures/core.md", "symbol": "CancelOptions", From bcb049bef308c3ee4a48bccb9023999b73c5471a Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 30 Jul 2026 14:57:27 +0800 Subject: [PATCH 008/689] fix(prompt): distinguish checkout from workdir --- ...rce-checkout-workdir-distinction.i18n.yaml | 6 ++ ...-30-source-checkout-workdir-distinction.md | 33 +++++++++ ...-source-checkout-workdir-distinction.zh.md | 33 +++++++++ .../source-checkout-workdir/session.jsonl | 30 +++++++++ .../terminal.expected.txt | 67 +++++++++++++++++++ .../tui-agent/tests/tui-keyless-smoke.e2e.ts | 9 +-- examples/tui-agent/tests/tui.snapshot.ts | 36 +++++++++- packages/ui/app-boot/README.i18n.yaml | 4 +- packages/ui/app-boot/README.md | 2 +- packages/ui/app-boot/README.zh.md | 2 +- packages/ui/app-boot/src/index.ts | 12 ++-- packages/ui/app-boot/tests/app-boot.spec.ts | 4 +- 12 files changed, 220 insertions(+), 18 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md create mode 100644 examples/tui-agent/tests/snapshots/source-checkout-workdir/session.jsonl create mode 100644 examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml new file mode 100644 index 0000000000..311c4971d3 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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-30-source-checkout-workdir-distinction.md +2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd +2026-07-30-source-checkout-workdir-distinction.zh.md: ffc2ac7baa2b1bb8ce54607638c35869fc338825 diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md new file mode 100644 index 0000000000..ba6d9dd12b --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md @@ -0,0 +1,33 @@ +# Agent Note: Source checkout paths do not define working directories + +Status: implemented + +English | [中文](2026-07-30-source-checkout-workdir-distinction.zh.md) + +## Problem + +The `harness:source` prompt section follows the [source-location decision](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md), but its original wording called the checkout “your own source code” without distinguishing that path from the session workspace. In a normal TUI configuration that does not state `{{cwd}}` in its persona, this may be the only fixed absolute path near the start of the system prompt. DeepSeek V4 could therefore answer “what's the workdir?” with the harness checkout instead of determining the session's current working directory. + +A blanket statement that the checkout is not the working directory would also be false. `dsh meta` intentionally makes the source checkout both values. + +## Decision + +The section identifies the path as the “DeepSeek Harness implementation checkout.” It says that the checkout location and current working directory are separate values that may differ, forbids inferring the working directory from the checkout path, directs the model to use `pwd`, and limits the checkout's purpose to inspecting or extending DSH itself. + +The path derivation, global `harness:source` ownership, and `-99` ordering remain unchanged. Describing the values as conceptually separate rather than always unequal keeps the instruction accurate in both ordinary project sessions and `dsh meta`. + +## Verification + +The `dsh-app-boot` unit test pins the exact text and its ordering. The CLI keyless PTY smoke inspects the assembled request header. The TUI `source-checkout-workdir` snapshot mounts the section with `/opt/dsh-source`, asks “what's the workdir?” through a recorded DeepSeek V4 turn, and requires the replayed transcript to run `pwd` and report the generated workspace rather than the checkout. + +## Alternatives considered + +**Say that the checkout is never the working directory.** Rejected because `dsh meta` deliberately makes them the same path. + +**Put the current working directory in the global source section.** Rejected because the source section is launcher-global while the working directory belongs to each session; combining them would duplicate the loop's `cwd` ownership and make a stable source fact vary per agent. + +**Remove the source path from the prompt.** Rejected because self-referential DSH tools still need a reliable checkout location when the launcher starts from an unrelated project. + +## Consequences + +The prompt is longer and a direct working-directory question may spend one inexpensive `pwd` tool call. In exchange, the model no longer treats the harness implementation path as an implicit task workspace, while meta mode remains truthful when both values coincide. diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md new file mode 100644 index 0000000000..ffc2ac7baa --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md @@ -0,0 +1,33 @@ +# Agent Note: 源码 checkout 路径不定义工作目录 + +Status: implemented + +[English](2026-07-30-source-checkout-workdir-distinction.md) | 中文 + +## Problem + +`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为“你自己的源代码”，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答“what's the workdir?”，而不是确定会话的当前工作目录。 + +直接断言 checkout 不是工作目录同样不准确。`dsh meta` 会有意让源码 checkout 同时充当这两个值。 + +## Decision + +该提示词段将路径标识为“DeepSeek Harness implementation checkout”。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。 + +路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。 + +## Verification + +`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI 无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问“what's the workdir?”，并要求回放 transcript 运行 `pwd`，报告生成的 workspace 而不是 checkout。 + +## Alternatives considered + +**声明 checkout 永远不是工作目录。**拒绝：`dsh meta` 会有意让它们指向同一路径。 + +**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会重复 loop 对 `cwd` 的所有权，还会让稳定的源码事实随 agent 变化。 + +**从提示词中删除源码路径。**拒绝：launcher 从无关项目启动时，自引用 DSH 工具仍需要可靠的 checkout 位置。 + +## Consequences + +提示词会变长，直接询问工作目录时可能多花一次廉价的 `pwd` 工具调用。作为交换，模型不再把 harness 实现路径当作隐含的任务 workspace；当 meta 模式使两个值重合时，提示词仍然准确。 diff --git a/examples/tui-agent/tests/snapshots/source-checkout-workdir/session.jsonl b/examples/tui-agent/tests/snapshots/source-checkout-workdir/session.jsonl new file mode 100644 index 0000000000..f7458c3b46 --- /dev/null +++ b/examples/tui-agent/tests/snapshots/source-checkout-workdir/session.jsonl @@ -0,0 +1,30 @@ +{"type":"session","version":0,"id":"main-session","createdAt":1784606400000,"cwd":"{{cwd}}"} +{"type":"turn/start","seq":0,"time":1784606400000,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1784606400000,"data":{"content":[{"type":"text","text":"what's the workdir?"}],"source":{"kind":"user"},"role":"user","id":"3fdc2885-1bea-4c6c-b4af-dbd5af7594f8"},"surfaceOp":"append"} +{"type":"session/title","seq":2,"time":1784606400000,"data":{"title":"what's the workdir?","messageSeqs":[1],"source":{"kind":"fallback"}}} +{"type":"step/start","seq":3,"time":1784606400000,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":4,"time":1784606400000,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash","reasoningEffort":"high"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":5,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"reasoning-chunks","seq0":6,"time0":1784606400000,"data":{"turn":1,"step":1,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," is"," asking"," about"," the"," current"," working"," directory","."," Let"," me"," check"," using"," p","wd","."]}} +{"type":"assistant/chunk","seq":23,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"tool-call-chunks","seq0":24,"time0":1784606400000,"data":{"turn":1,"step":1,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","args":["","{","\"","command","\"",": ","\"","p","wd","\"",", ","\"","description","\"",": ","\"","Print"," current"," working"," directory","\"","}"]}} +{"type":"assistant/chunk","seq":46,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user is asking about the current working directory. Let me check using pwd."}}}} +{"type":"assistant/chunk","seq":47,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","arguments":"{\"command\": \"pwd\", \"description\": \"Print current working directory\"}"}}}} +{"type":"assistant/chunk","seq":48,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3332,"outputTokens":80,"cacheReadTokens":0,"reasoningTokens":17}}}} +{"type":"assistant/chunk","seq":49,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":50,"time":1784606400000,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user is asking about the current working directory. Let me check using pwd."},{"type":"tool-call","id":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","arguments":"{\"command\": \"pwd\", \"description\": \"Print current working directory\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"063a9245-32c3-4551-9ace-d43f10ed5582"},"usage":{"inputTokens":3332,"outputTokens":80,"cacheReadTokens":0,"reasoningTokens":17}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49],"surfaceOp":"append"} +{"type":"tool/call","seq":51,"time":1784606400000,"data":{"turn":1,"step":1,"callId":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","arguments":"{\"command\": \"pwd\", \"description\": \"Print current working directory\"}"}} +{"type":"tool/result","seq":52,"time":1784606400000,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_AqoWTncquNel5ZHsJHOo7491"},"content":[{"type":"tool-result","toolCallId":"call_00_AqoWTncquNel5ZHsJHOo7491","content":[{"type":"text","text":"{{cwd}}\n"}],"isError":false}],"role":"user","id":"16086d3b-6dfa-4970-a06e-78561475af8c"}},"sourceEventSeqs":[51],"surfaceOp":"append"} +{"type":"step/end","seq":53,"time":1784606400000,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":54,"time":1784606400000,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":55,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"reasoning-chunks","seq0":56,"time0":1784606400000,"data":{"turn":1,"step":2,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," current"," working"," directory"," is"," `/","private","/t","mp","/d","sh","-t","ui","-s","n","apshot","-source","-check","out","-work","dir","-","61","I","wn","K","`."]}} +{"type":"assistant/chunk","seq":83,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"text-chunks","seq0":84,"time0":1784606400000,"data":{"turn":1,"step":2,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," current"," working"," directory"," is",":\n\n","```\n","/","private","/t","mp","/d","sh","-t","ui","-s","n","apshot","-source","-check","out","-work","dir","-","61","I","wn","K","\n","```\n\n","Note"," that"," the"," Deep","Se","ek"," Har","ness"," SDK"," checkout"," is"," at"," `/","opt","/d","sh","-source","`"," —"," that","'s"," a"," separate"," location"," used"," for"," inspecting"," or"," extending"," D","SH"," itself",","," while"," the"," working"," directory"," above"," is"," the"," current"," working"," directory"," for"," this"," session","."]}} +{"type":"assistant/chunk","seq":161,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The current working directory is `{{cwd}}`."}}}} +{"type":"assistant/chunk","seq":162,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"The current working directory is:\n\n```\n{{cwd}}\n```\n\nNote that the DeepSeek Harness SDK checkout is at `/opt/dsh-source` — that's a separate location used for inspecting or extending DSH itself, while the working directory above is the current working directory for this session."}}}} +{"type":"assistant/chunk","seq":163,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":117,"outputTokens":105,"cacheReadTokens":3328,"reasoningTokens":27}}}} +{"type":"assistant/chunk","seq":164,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":165,"time":1784606400000,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The current working directory is `{{cwd}}`."},{"type":"text","text":"The current working directory is:\n\n```\n{{cwd}}\n```\n\nNote that the DeepSeek Harness SDK checkout is at `/opt/dsh-source` — that's a separate location used for inspecting or extending DSH itself, while the working directory above is the current working directory for this session."}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"76c18b85-00aa-45f6-a32f-a2bd75412470"},"usage":{"inputTokens":117,"outputTokens":105,"cacheReadTokens":3328,"reasoningTokens":27}},"sourceEventSeqs":[55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164],"surfaceOp":"append"} +{"type":"step/end","seq":166,"time":1784606400000,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":167,"time":1784606400000,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt b/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt new file mode 100644 index 0000000000..81103c12bd --- /dev/null +++ b/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt @@ -0,0 +1,67 @@ +terminal 100x36 buffer=normal length=36 base=0 viewport=0 +lifecycle started=1 stopped=0 progress=inactive +title "what's the workdir? — DSH TUI snapshot" +cursor hidden column=7 viewportRow=32 bufferRow=32 +buffer +0| " DEEPSEEK HARNESS" + style 1-8 fg=bright-magenta bold + style 10-16 bold +1| " what's the workdir?" + style 1-19 dim +2| " main-session" + style 1-12 dim +3| +4| "You " + style 0-2 fg=bright-magenta bold underline +5| "what's the workdir? " +6| +7| "Assistant " + style 0-8 fg=bright-magenta bold underline +8| "Reasoning " + style 0-8 dim italic +9| "The user is asking about the current working directory. Let me check using pwd. " + style 0-78 dim italic +10| +11| "● Tool / bash / Print current working directory" + style 0-46 fg=green +12| "$ pwd " + style 0-4 dim +13| "/workspace/project " + style 0-59 dim +14| "[exit 0] " + style 0-7 dim +15| "Model wait 0.0s · Completed 2026-07-21 12:00:00 " + style 0-46 dim +16| +17| "Assistant " + style 0-8 fg=bright-magenta bold underline +18| "Reasoning " + style 0-8 dim italic +19| "The current working directory is /workspace/project. " + style 0-32 dim italic + style 33-84 fg=cyan + style 85-85 dim italic +20| "The current working directory is: " +21| " " +22| " " +23| " /workspace/project " + style 2-53 fg=cyan +24| " " +25| " " +26| "Note that the DeepSeek Harness SDK checkout is at /opt/dsh-source — that's a separate location used " + style 50-64 fg=cyan +27| "for inspecting or extending DSH itself, while the working directory above is the current working " +28| "directory for this session. " +29| "Model wait 0.0s · Completed 2026-07-21 12:00:00 " + style 0-46 dim +30| +31| "/workspace/project deepseek-v4-flash ↑3.4k ↓185 cache 49% 3% c" + style 0-51 fg=bright-magenta bold + style 54-70 dim + style 73-93 dim + style 96-99 dim +32| " dsh ◍ " + style 1-3 fg=bright-magenta bold + style 5-6 dim + style 7-7 inverse +33-35| diff --git a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts index cd5f83e4e3..f31e3c6853 100644 --- a/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts +++ b/examples/tui-agent/tests/tui-keyless-smoke.e2e.ts @@ -412,11 +412,12 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expect(output).toContain('ui-tui: session "missing-session" failed to start:') }, LOADER_SMOKE_TEST_TIMEOUT_MS) - it('tells the model its source path and offers the bundled maintenance skills', async () => { + it('distinguishes its source path from the current workdir and offers the bundled maintenance skills', async () => { // The launcher resolves the checkout root three hops up from apps/cli/{src,lib}; // this test file sits an equal depth under the same root, so the same hop applies. - // The source-path line is a system-prompt section; the bundled skills reach the - // model through a durable user message, so each assertion targets its own field. + // The source-path line explicitly distinguishes that checkout from the current workdir; + // bundled skills reach the model through a durable user message, so each assertion + // targets its own field. const sourceRoot = fileURLToPath(new URL('../../..', import.meta.url)) let context: LoggedRequestContext = { system: '', skillCatalog: '' } await smoke({ @@ -432,7 +433,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { ], inspect: async (cwd) => { context = await readLoggedRequestContext(cwd) }, }) - expect(context.system).toContain(`Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`) + expect(context.system).toContain(`The DeepSeek Harness implementation checkout is at ${sourceRoot}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`) expect(context.skillCatalog).toContain("- `dsh-customize`: Customize or maintain any dsh source checkout — the one powering the current DSH process, the installed `dsh` command, or a sibling dsh/deepseek-harness clone. Use before any requested action that alters such a checkout's files or git state. Read-only questions that only inspect the checkout do not trigger this. Do not edit the personal staging checkout directly.") expect(context.skillCatalog).toContain('- `dsh-upgrade`: Upgrades a source-installed, personally customized DSH checkout to upstream master while preserving local changes and an unchanged rollback worktree. Use when the user asks to update or upgrade DSH.') expect(context.skillCatalog).toContain('- `dsh-upstream-customization`: Classifies personal DSH customizations for upstream contribution and, after explicit per-feature approval, rebuilds one on upstream master and opens a draft pull request. Use when the user asks to contribute, publish, or upstream a local DSH change, or asks whether one is worth proposing.') diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts index 95b960e3b6..b96aaaf691 100644 --- a/examples/tui-agent/tests/tui.snapshot.ts +++ b/examples/tui-agent/tests/tui.snapshot.ts @@ -7,6 +7,7 @@ import { Context } from 'cordis' import { scrubRequestHeaders, tokenizeSessionFixtureCwd } from '@deepseek-ai/dsh-acp-snapshot' import type { Agent } from '@deepseek-ai/dsh-agent' import * as AgentCore from '@deepseek-ai/dsh-agent-spine-demo' +import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot' import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local' import WorkerCodeRuntime from '@deepseek-ai/dsh-code-runtime-worker' @@ -53,6 +54,8 @@ interface Scenario { leavePlanModeAfterFirstTurn?: boolean recorded: boolean seedWorkspace?: boolean + /** Add the launcher's model-visible DSH source checkout at this fixed path. */ + harnessSourceRoot?: string /** * Load the opt-in `todo_write` tool for this scenario. The shipped tui-agent * config omits it, so only the todo-plan scenario (the enabled-path proof) @@ -94,6 +97,13 @@ const SCENARIOS: Scenario[] = [ expectedTools: ['bash'], recorded: true, }, + { + name: 'source-checkout-workdir', + composition: 'native', + expectedTools: ['bash'], + recorded: true, + harnessSourceRoot: '/opt/dsh-source', + }, { name: 'parallel-file-reads', composition: 'native', @@ -187,6 +197,12 @@ function rawSessionLog(session: Session): string { ].join('\n') } +async function materializeFixtureCwd(fixtureFile: string, cwd: string, replayRoot: string): Promise { + const realized = join(replayRoot, basename(fixtureFile)) + await writeFile(realized, (await readFile(fixtureFile, 'utf8')).split('{{cwd}}').join(cwd)) + return realized +} + function normalizeTerminalSnapshot(snapshot: string, cwd: string, displayCwd: string): string { return snapshot .split(`/private${cwd}`).join('/workspace/project') @@ -212,6 +228,7 @@ async function mountScenarioContext( displayCwd: string, fixtureFile: string, childFiles: string[], + replayRoot: string | undefined, ): Promise { class SnapshotLocalFileSystem extends LocalFileSystem { override async resolve( @@ -231,6 +248,7 @@ async function mountScenarioContext( tools: { mode: scenario.composition === 'code' ? 'code' : scenario.composition === 'advanced' ? 'both' : 'native' }, skills: { local: { agentsHome: join(cwd, '.agents') } }, }) + if (scenario.harnessSourceRoot !== undefined) addHarnessSourceSection(ctx, scenario.harnessSourceRoot) await ctx.plugin(TokenMeterService) await ctx.plugin(LocalSubprocessService) await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 }) @@ -263,7 +281,12 @@ async function mountScenarioContext( if (MODE === 'record' && scenario.recorded) { await ctx.plugin(LlmDeepSeek) } else { - installLlmReplay(ctx, { file: fixtureFile, childFiles, providers: PROVIDERS }) + if (replayRoot === undefined) throw new Error('replay mode requires an isolated fixture directory') + // Recorded model text may name the generated cwd. Realize the portable token + // outside that cwd so tools see only the scenario workspace during replay. + const replayFile = await materializeFixtureCwd(fixtureFile, cwd, replayRoot) + const replayChildFiles = await Promise.all(childFiles.map(file => materializeFixtureCwd(file, cwd, replayRoot))) + installLlmReplay(ctx, { file: replayFile, childFiles: replayChildFiles, providers: PROVIDERS }) } return ctx } @@ -287,15 +310,19 @@ async function runScenario(scenario: Scenario): Promise { const cwd = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-snapshot-${scenario.name}-`)) const displayCwd = `/tmp/${basename(cwd)}` + let replayRoot: string | undefined let ctx: Context | undefined let controller: ReturnType | undefined const terminal = new HeadlessTerminal(100, 36) try { + if (!(MODE === 'record' && scenario.recorded)) { + replayRoot = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-replay-${scenario.name}-`)) + } if (scenario.seedWorkspace === true) { const source = join(scenarioDir(scenario), 'workspace') await cp(source, cwd, { recursive: true }) } - ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles) + ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles, replayRoot) const disposedSessions: Session[] = [] ctx.on('session/disposed', (session) => { disposedSessions.push(session) }) const workflowEvents: string[] = [] @@ -406,6 +433,10 @@ async function runScenario(scenario: Scenario): Promise { const firstHeader = events.find(event => event.type === 'request/header') expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system) .toContain(FILE_REFERENCE_PROMPT) + if (scenario.harnessSourceRoot !== undefined) { + expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system) + .toContain(`The DeepSeek Harness implementation checkout is at ${scenario.harnessSourceRoot}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`) + } expect(events.filter(event => event.type === 'tool/call').map(event => event.data.name)).toEqual(scenario.expectedTools) for (const [type, count] of Object.entries(scenario.expectedEventCounts ?? {})) { expect(events.filter(event => event.type === type), `${scenario.name} must emit ${type}`).toHaveLength(count) @@ -477,6 +508,7 @@ async function runScenario(scenario: Scenario): Promise { await ctx?.fiber.dispose() await terminal.dispose() await rm(cwd, { recursive: true, force: true }) + if (replayRoot !== undefined) await rm(replayRoot, { recursive: true, force: true }) clock.mockRestore() } } diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml index 08a274fd25..4804a0ad66 100644 --- a/packages/ui/app-boot/README.i18n.yaml +++ b/packages/ui/app-boot/README.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 packages/ui/app-boot/README.md -README.md: 0282d3e9559d55c3fe5b07df133747750c06ebad -README.zh.md: b7121bbd288cd6e3f9ef2301de6018ceb380eb06 +README.md: b187f691df4c6ca9c4fe1fe3bf7e631f14997b01 +README.zh.md: 6f86573fbb1e60bf290d90f67e4a574c96219e0a diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md index 0282d3e955..b187f691df 100644 --- a/packages/ui/app-boot/README.md +++ b/packages/ui/app-boot/README.md @@ -13,7 +13,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws | | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, run optional host preparation before plugins mount (e.g. `ctx.provide(RESUME_SESSION_ID_KEY, id)`), then mount the Loader/include tree, await it, assert entries loaded, and return the root context | | `RESUME_SESSION_ID_KEY` | Context key a bin sets through `boot`'s `prepare` hook to hand a resume session id to the booted config; the config reads it as the bare identifier `resumeSessionId` in a `!!js` expression, so resuming needs no environment variable | -| `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to its own source checkout; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot | +| `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot | | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under | Two failure classes the guards handle: `loader.await()` swallows init rejections (`Promise.allSettled`) — Node still exits non-zero on the resulting unhandled rejection, and `installFailLoud` replaces the noisy dump with one labelled line and a guaranteed `exit(1)`; a failed plugin import is only logged by the Loader (the process would otherwise exit 0 on a usable config typo), leaving a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection naming every failed plugin. diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md index b7121bbd28..6f86573fbb 100644 --- a/packages/ui/app-boot/README.zh.md +++ b/packages/ui/app-boot/README.zh.md @@ -13,7 +13,7 @@ | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 | | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，在插件挂载前执行可选的宿主准备操作（例如 `ctx.provide(RESUME_SESSION_ID_KEY, id)`），再挂载 Loader/include 树并等待其结算，断言所有条目均已加载，最后返回根上下文 | | `RESUME_SESSION_ID_KEY` | bin 通过 `boot` 的 `prepare` 钩子设置的上下文键，用于把要恢复的会话 id 交给已启动配置；配置以裸标识符 `resumeSessionId` 在 `!!js` 表达式中读取它，因此恢复操作无需环境变量 | -| `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）自身源代码 checkout 的磁盘路径；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 | +| `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 | | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 | 这些保护处理两类故障。`loader.await()` 会吞掉初始化 rejection（`Promise.allSettled`）；Node 仍会因随后产生的未处理 rejection 以非零状态退出，而 `installFailLoud` 会把冗长转储替换为一行带标签的消息，并确保执行 `exit(1)`。插件导入失败则只会由 Loader 记录日志（否则，即使配置存在拼写错误，进程也会以代码 0 退出），并留下没有 fiber 的条目；`assertEntriesLoaded` 会将其转换为 `boot()` rejection，并在其中列出每个导入失败插件的名称。 diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts index 4644912304..47e8fef5d2 100644 --- a/packages/ui/app-boot/src/index.ts +++ b/packages/ui/app-boot/src/index.ts @@ -213,11 +213,11 @@ export async function boot( export const HARNESS_SOURCE_SECTION = 'harness:source' /** - * Add a global prompt section naming the on-disk path to the harness source - * checkout the running bin was launched from, so the agent knows where its own - * source lives (the self-referential `dsh-tool-cordis` toolset reads and edits - * it). Call once on the settled boot context ({@link boot}); the section orders - * just after the harness identity opener (`-100`) and before the deployment + * Add a global prompt section naming the on-disk harness source checkout while + * explicitly distinguishing it from the task workspace and current working + * directory. The self-referential `dsh-tool-cordis` toolset reads and edits this + * checkout. Call once on the settled boot context ({@link boot}); the section + * orders just after the harness identity opener (`-100`) and before the deployment * persona (`0`). A booted tree with no `systemPrompt` service has no prompt to * augment, so this is then a no-op that returns `undefined`. The section is * registered against the `systemPrompt` service's fiber, so a dev HMR reload of @@ -232,6 +232,6 @@ export function addHarnessSourceSection(ctx: Context, sourceRoot: string): (() = return systemPrompt.section({ name: HARNESS_SOURCE_SECTION, order: -99, - text: `Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`, + text: `The DeepSeek Harness implementation checkout is at ${sourceRoot}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`, }) } diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts index db425c301a..ede5ba01de 100644 --- a/packages/ui/app-boot/tests/app-boot.spec.ts +++ b/packages/ui/app-boot/tests/app-boot.spec.ts @@ -193,9 +193,9 @@ describe('boot', () => { describe('addHarnessSourceSection', () => { const SOURCE_ROOT = `${sep}opt${sep}harness-src` - const EXPECTED = `Your own source code is the checkout at ${SOURCE_ROOT}; you can read it there to learn how dsh works and how to extend it.` + const EXPECTED = `The DeepSeek Harness implementation checkout is at ${SOURCE_ROOT}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.` - it('adds the source path between the harness identity and the deployment persona', async () => { + it('distinguishes the source path from the current workdir between identity and persona', async () => { const ctx = new Context() try { await ctx.plugin(SystemPrompt, { persona: 'You are a coding agent.' }) From 4370004360d140bf12e76956c43d5564309980fe Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 15:35:18 +0800 Subject: [PATCH 009/689] refactor(agent): expose mutable inbox state --- packages/acp/acp/tests/turns.spec.ts | 75 +++++-- packages/client/connection/src/client/api.ts | 3 +- .../client/connection/src/client/index.ts | 2 +- .../runtime/src/client/contract/session.ts | 4 +- .../src/client/sessions/conversation.ts | 4 +- .../client/runtime/tests/queue-store.spec.ts | 12 +- .../src/client/input/contract.ts | 2 +- .../time-context/tests/time-context.spec.ts | 3 - .../tmux-context/tests/tmux-context.spec.ts | 3 - .../tests/workspace-context.spec.ts | 3 - packages/core/agent-loop/src/agent.ts | 206 +++++++----------- packages/core/agent-loop/tests/cancel.spec.ts | 5 +- .../tests/contract-regressions.spec.ts | 102 +++------ packages/core/agent/package.json | 6 - packages/core/agent/src/brand.ts | 23 -- packages/core/agent/src/inbox.ts | 109 +++++++++ packages/core/agent/src/index.ts | 2 +- packages/core/agent/src/types.ts | 130 ++--------- packages/core/agent/tests/agent.spec.ts | 2 - packages/core/agent/tests/invariant.spec.ts | 51 +---- packages/core/agent/tsconfig.json | 3 - .../core/scope/src/scoped-events.generated.ts | 5 - packages/core/scope/tests/invariant.spec.ts | 21 +- packages/examples/cli-demo/tests/cli.spec.ts | 103 +++++++-- .../command-goal/tests/command-goal.spec.ts | 3 - packages/goal/goal-session/src/index.ts | 43 +--- .../goal-session/tests/goal-session.spec.ts | 48 ++-- packages/goal/goal/tests/goal.spec.ts | 3 - packages/goal/goal/tests/projection.spec.ts | 3 - .../goal/tool-goal/tests/tool-goal.spec.ts | 3 - packages/host/apiproxy/src/api-proxy.ts | 131 ++--------- .../host/apiproxy/src/api/events.schema.ts | 15 +- packages/host/apiproxy/src/api/events.ts | 21 +- packages/host/apiproxy/src/api/index.ts | 4 +- packages/host/apiproxy/src/api/rpc.ts | 4 +- .../host/apiproxy/src/api/sessions.schema.ts | 8 +- packages/host/apiproxy/src/api/sessions.ts | 4 +- .../apiproxy/tests/api-proxy-commands.spec.ts | 145 +++--------- .../tests/api-proxy-workspace.spec.ts | 3 - .../host/apiproxy/tests/rpc-schemas.spec.ts | 6 +- packages/pty/pty-local/tests/index.spec.ts | 12 +- packages/pty/pty-local/tests/local.spec.ts | 4 +- packages/pty/pty/tests/service.spec.ts | 3 - .../tool-pty/tests/loader-composition.spec.ts | 4 +- packages/pty/tool-pty/tests/tools.spec.ts | 4 +- .../skill/tool-skill/tests/tool-skill.spec.ts | 6 - .../tests/subagent-spawn.spec.ts | 8 +- .../tasks/tasks-local/tests/tasks.spec.ts | 3 - packages/ui/tui/src/index.ts | 2 +- packages/ui/tui/tests/harness.ts | 12 - packages/ui/tui/tests/tui.spec.ts | 63 +----- pnpm-lock.yaml | 3 - 52 files changed, 534 insertions(+), 913 deletions(-) delete mode 100644 packages/core/agent/src/brand.ts create mode 100644 packages/core/agent/src/inbox.ts diff --git a/packages/acp/acp/tests/turns.spec.ts b/packages/acp/acp/tests/turns.spec.ts index c42ef7e5c0..a4ae22080e 100644 --- a/packages/acp/acp/tests/turns.spec.ts +++ b/packages/acp/acp/tests/turns.spec.ts @@ -70,10 +70,13 @@ describe('ACP prompt lifecycle', () => { const sessionId = await newSession(harness) const agent = harness.ctx.agents.get(SessionId(sessionId))! let injected = false - harness.ctx.on('agent/inbox/enqueue', (subject) => { - if (subject === agent && !injected) { + harness.ctx.on('session/event', (session, event) => { + if (session === agent.session && event.type === 'agent/inbox/spliced' + && event.data.inserted.some(message => message.source.kind === 'user') && !injected) { injected = true - agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' } })) + queueMicrotask(() => { + agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' } })) + }) } }) @@ -86,30 +89,44 @@ describe('ACP prompt lifecycle', () => { harness = await makeBridgeHarness({ script: ['hang'] }) const sessionId = await newSession(harness) const agent = harness.ctx.agents.get(SessionId(sessionId))! - let inserted = false - harness.ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject !== agent || item.message.source.kind !== 'user' || inserted) return - inserted = true - const source = { kind: 'plugin', plugin: 'test' } as const - agent.session.append('turn/start', { turn: 1 }) - agent.session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'autonomous work' }], - source, - }), { surfaceOp: 'append' }) - agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + let autonomousStarted!: () => void + const started = new Promise((resolve) => { autonomousStarted = resolve }) + harness.ctx.on('session/event', (session, event) => { + if (session === agent.session && event.type === 'assistant/chunk') autonomousStarted() }) + agent.followup(createUserMessage({ + content: [{ type: 'text', text: 'autonomous work' }], + source: { kind: 'plugin', plugin: 'test' }, + })) + await started let settled = false const prompt = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }) .finally(() => { settled = true }) await vi.waitFor(() => { - expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2) + expect(agent.session.events.filter(event => event.type === 'agent/inbox/spliced' + && event.data.inserted.length > 0)).toHaveLength(2) }) expect(settled).toBe(false) await harness.client.cancel({ sessionId }) await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' }) }) + it('correlates a prompt whose admitted history is replaced', async () => { + harness = await makeBridgeHarness({ script: [textResponse('rewritten answer')] }) + harness.ctx.on('agent/prompt-submit', async () => ({ + kind: 'allow', + messages: [createUserMessage({ + content: [{ type: 'text', text: 'rewritten prompt' }], + source: { kind: 'plugin', plugin: 'test' }, + })], + })) + const sessionId = await newSession(harness) + + await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'original' }] })) + .resolves.toEqual({ stopReason: 'end_turn' }) + }) + it('frees the prompt slot when the agent rejects the send synchronously', async () => { harness = await makeBridgeHarness({ script: [] }) const sessionId = await newSession(harness) @@ -143,7 +160,8 @@ describe('ACP prompt lifecycle', () => { await harness.client.cancel({ sessionId }) await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' }) await agent.whenIdle() - expect(agent.session.events.findLast(event => event.type === 'turn/end')?.data.reason).toEqual({ kind: 'aborted' }) + expect(agent.session.events.findLast(event => event.type === 'turn/end')?.data.reason) + .toEqual({ kind: 'aborted', reason: { kind: 'user' } }) }) it('an idle cancel does not affect the following prompt', async () => { @@ -203,4 +221,29 @@ describe('ACP prompt lifecycle', () => { // The blocked prompt opened no turn and streamed nothing. expect(messageText(harness)).toBe('') }) + + it('discards and settles a turnless prompt retained by its admission policy', async () => { + harness = await makeBridgeHarness({ script: [] }) + harness.ctx.on('agent/prompt-submit', async () => ({ + kind: 'block' as const, + reason: 'defer forever', + keepInbox: true, + })) + const sessionId = await newSession(harness) + const agent = harness.ctx.agents.get(SessionId(sessionId))! + + await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) + .resolves.toEqual({ stopReason: 'cancelled' }) + expect(agent.status).toBe('idle') + expect(agent.session.events.some(event => event.type === 'turn/start')).toBe(false) + }) + + it('settles a prompt when admission fails before opening a turn', async () => { + harness = await makeBridgeHarness({ script: [] }) + harness.ctx.on('agent/prompt-submit', async () => { throw new Error('admission exploded') }) + const sessionId = await newSession(harness) + + await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) + .resolves.toEqual({ stopReason: 'cancelled' }) + }) }) diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts index b58718134d..23aa0d20c0 100644 --- a/packages/client/connection/src/client/api.ts +++ b/packages/client/connection/src/client/api.ts @@ -12,7 +12,7 @@ export type { WorkspaceApi, WorkspaceId, WorkspaceView, CommandsApi, CommandDescriptor, SkillsApi, SkillEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning, - InboxItemId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels, + ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, GoalsApi, GoalRef, } from '@deepseek-ai/dsh-host-apiproxy/api' export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation' @@ -27,6 +27,7 @@ export { RpcId, transportError } from '@deepseek-ai/dsh-host-apiproxy/api' export { AbstractApiClient } from '@deepseek-ai/dsh-host-apiproxy/client' export type { IApiClient } from '@deepseek-ai/dsh-host-apiproxy/client' export type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session/types' +export type { MessageId } from '@deepseek-ai/dsh-llm/brand' export type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm/types' import type { RpcResponse, RpcResult } from '@deepseek-ai/dsh-host-apiproxy/api' diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts index 7d26b1c526..1599084c1c 100644 --- a/packages/client/connection/src/client/index.ts +++ b/packages/client/connection/src/client/index.ts @@ -17,7 +17,7 @@ export type { ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView, CommandsApi, CommandDescriptor, SkillsApi, SkillEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning, - InboxItemId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels, + MessageId, ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode, ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt, IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk, diff --git a/packages/client/runtime/src/client/contract/session.ts b/packages/client/runtime/src/client/contract/session.ts index 82bde108b4..0e75648ea1 100644 --- a/packages/client/runtime/src/client/contract/session.ts +++ b/packages/client/runtime/src/client/contract/session.ts @@ -9,7 +9,7 @@ */ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { - InboxItemId, QueueAction, RpcResult, SessionId, + MessageId, QueueAction, RpcResult, SessionId, } from '@deepseek-ai/dsh-client-connection/client' import type { ConversationSnapshot } from '../sessions/conversation.ts' import type { ObservableSnapshot } from './store.ts' @@ -44,7 +44,7 @@ export interface ISession { * @param action - edit or remove operation. * @returns acceptance, or a business/transport error. */ - updateQueue(itemId: InboxItemId, action: QueueAction): Promise> + updateQueue(itemId: MessageId, action: QueueAction): Promise> /** * Cancel the running turn. * @returns acceptance, or the business error. diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts index f68a271c63..55cc3fc73e 100644 --- a/packages/client/runtime/src/client/sessions/conversation.ts +++ b/packages/client/runtime/src/client/sessions/conversation.ts @@ -7,7 +7,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand' import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { TodoItem } from '@deepseek-ai/dsh-session/types' import type { - InboxItemId, RpcError, SessionId, ToolCallView, ToolResultView, + MessageId, RpcError, SessionId, ToolCallView, ToolResultView, } from '@deepseek-ai/dsh-client-connection/client' import type { PendingInteraction } from './pending.ts' export type { TodoItem } @@ -218,7 +218,7 @@ export interface RunningToolCall { /** One independently addressable row from the transient queue snapshot. */ export interface QueuedMessage { - readonly id: InboxItemId + readonly id: MessageId readonly preview: string /** Complete editable text; null when the message contains non-text blocks. */ readonly text: string | null diff --git a/packages/client/runtime/tests/queue-store.spec.ts b/packages/client/runtime/tests/queue-store.spec.ts index 192885b66b..ce684694f5 100644 --- a/packages/client/runtime/tests/queue-store.spec.ts +++ b/packages/client/runtime/tests/queue-store.spec.ts @@ -4,10 +4,10 @@ * projection, and snapshot reference stability. */ import { describe, expect, it } from 'vitest' -import { createUserMessage } from '@deepseek-ai/dsh-llm' +import { createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm' import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { - InboxItemId, MuxFrame, RpcId, SessionId, + MessageId, MuxFrame, RpcId, SessionId, } from '@deepseek-ai/dsh-client-connection/client' import { Session } from '../src/client/sessions/session.ts' import { SessionManager } from '../src/client/sessions/manager.ts' @@ -16,7 +16,7 @@ import { FakeApiClient } from './fake-api.ts' const SID = 'fk-q1' as SessionId const text = (value: string): ContentBlock[] => [{ type: 'text', text: value }] const rid = (id: string): RpcId => id as RpcId -const iid = (id: string): InboxItemId => id as InboxItemId +const mid = (id: string): MessageId => id as MessageId interface QueueFixture { id: string @@ -29,12 +29,12 @@ function queueFrame(items: QueueFixture[]): MuxFrame { return { type: 'session/queue', sessionId: SID, - items: items.map(item => ({ - id: iid(item.id), - message: createUserMessage({ + items: items.map(item => freezeMessage({ + ...createUserMessage({ content: item.content ?? text(item.body), source: { kind: 'user', rpcId: rid(`rpc-${item.id}`) } as never, }), + id: mid(item.id), })), } } diff --git a/packages/client/ui-conversation/src/client/input/contract.ts b/packages/client/ui-conversation/src/client/input/contract.ts index 317adc0ec5..0c1d72dbc2 100644 --- a/packages/client/ui-conversation/src/client/input/contract.ts +++ b/packages/client/ui-conversation/src/client/input/contract.ts @@ -191,7 +191,7 @@ export interface InputState { readonly occurrences: readonly Occurrence[] /** Live paste-match attempt (absent when no paste is matchable). */ readonly paste?: PasteAttemptState - /** Read-only queue projection (session/queued frames + connect snapshot). */ + /** Read-only queue projection from the reconnect baseline and durable inbox events. */ readonly queue: readonly QueuedMessage[] } diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts index ea13a36728..377e11abd7 100644 --- a/packages/context/time-context/tests/time-context.spec.ts +++ b/packages/context/time-context/tests/time-context.spec.ts @@ -41,10 +41,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { options: {}, session, status: 'running', - acceptsNextStep: true, ctx: new Context(), - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/context/tmux-context/tests/tmux-context.spec.ts b/packages/context/tmux-context/tests/tmux-context.spec.ts index 4c96fe0a78..a3a78c0153 100644 --- a/packages/context/tmux-context/tests/tmux-context.spec.ts +++ b/packages/context/tmux-context/tests/tmux-context.spec.ts @@ -97,15 +97,12 @@ function sessionAgent(session: Session, id = 'agent'): Agent { options: {}, session, status: 'running', - acceptsNextStep: true, ctx: new Context(), followup: () => {}, steer: () => {}, - updateInbox: () => 'not-found', inject(input) { session.append('user/message', input, { surfaceOp: 'append' }) }, - send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index ad6eb500a7..cb4ca3533f 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -177,9 +177,6 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent { options: {}, session, status: 'idle', - acceptsNextStep: false, - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index d42c2790d3..f33e36a3e3 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -1,9 +1,6 @@ /** - * Concrete Agent loop over two pending-input lists: queued prompts each open a - * turn that logs its admitted input after `turn/start` commits, while steering - * and injected context enter through the outbox at step boundaries. Every - * request is derived from the session log. - * + * Default Agent driver over queued turns and step-boundary input. Every request + * is derived from the session log. * @module dsh-agent-loop/agent */ @@ -13,9 +10,10 @@ import type { AgentOptions, AgentStatus, CancelOptions, + InboxTarget, RequestErrorAction, } from '@deepseek-ai/dsh-agent' -import { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from '@deepseek-ai/dsh-agent' +import { Inbox, agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from '@deepseek-ai/dsh-agent' import type { GenerateOptions, LlmCallConfig, Message, PreparedLlmCall } from '@deepseek-ai/dsh-llm' import { BlockAssembler, @@ -27,7 +25,7 @@ import { } from '@deepseek-ai/dsh-llm' import type { Scope } from '@deepseek-ai/dsh-scope' import { createScope } from '@deepseek-ai/dsh-scope' -import type { AssistantMessage, Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session' +import type { Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session' import { canonicalHeader, headerEquals } from '@deepseek-ai/dsh-session' import { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import type { Context } from 'cordis' @@ -40,25 +38,17 @@ type Phase = type Admission = | { kind: 'empty' } - | { kind: 'admitted'; claimed: UserMessage[]; messages: UserMessage[] } + | { kind: 'admitted'; messages: UserMessage[] } | { kind: 'blocked' } -/** - * The concrete {@link Agent}: each `run()` owns one turn and repeats model - * steps while tools or steering require another request. - */ +/** Drives one session through turn and step boundaries. */ export class ReactLoopAgent implements Agent { - /** Prompts awaiting individual turns. */ - private queued: UserMessage[] = [] - /** Input taken into the session log at step boundaries. */ - private outbox: UserMessage[] = [] - + readonly inbox: Inbox private phase: Phase private driverDone: Promise = Promise.resolve() /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */ readonly scope: Scope - /** The agent's scoped composition context ({@link Agent.ctx}). */ readonly ctx: Context /** Whether this loop instance has appended its initial/resume request anchor. */ @@ -70,13 +60,13 @@ export class ReactLoopAgent implements Agent { public readonly options: AgentOptions, public readonly session: Session, ) { + this.inbox = new Inbox(session) const lastTurn = session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 0 this.phase = { kind: 'idle', lastTurn } this.scope = createScope(loopCtx, this) this.ctx = this.scope.ctx.extend({ agent: this }) } - /** Last activity state published to observers. */ get status(): AgentStatus { return this.phase.kind === 'idle' ? 'idle' : 'running' } @@ -91,49 +81,32 @@ export class ReactLoopAgent implements Agent { } } - /** Accept and route one unified send item. */ - private send(message: UserMessage, target: 'next-turn' | 'next-step', wakeup: boolean): void { - this.session.append('agent/inbox/added', message) + private send(message: UserMessage, target: InboxTarget, wakeup: boolean): void { // Waking input cannot join an aborted admission or turn, so it starts the next turn. const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted - const inbox = target === 'next-turn' || wakingAfterAbort ? this.queued : this.outbox - inbox.push(message) - if (wakeup) { - this.scheduleKick() - } + const resolvedTarget = wakingAfterAbort ? 'next-turn' : target + this.inbox.splice(resolvedTarget, Infinity, 0, [message]) + if (wakeup) this.scheduleKick() } - /** Queue one ordinary prompt turn and wake the driver. */ followup(input: UserMessage): void { this.send(input, 'next-turn', true) } - /** Steer the open turn, falling back to a waking prompt while idle. */ steer(input: UserMessage): void { this.send(input, 'next-step', true) } - /** Append model-facing context without waking the driver. */ inject(input: UserMessage): void { this.send(input, 'next-step', false) } - /** - * Clear all pending work and abort the active turn; the first cause wins. - * The cause is signal payload for observers and the durable turn/end - * classification — it selects no machine behavior. Teardown is just - * `cancel({kind:'disposed'})` + driver join + {@link scope} dispose, all - * owned by the factory. - */ cancel(cause: AgentCancelCause, options: CancelOptions = {}): void { if (!options.keepInbox) { - for (const message of [...this.outbox.splice(0), ...this.queued.splice(0)]) { - emitAgentEvent(this.loopCtx, this, 'agent/inbox/canceled', message) - } - } - if (this.phase.kind !== 'idle') { - this.phase.abort.abort(cause) + this.inbox.splice('next-step', 0, this.inbox.nextStep.length, [], 'canceled') + this.inbox.splice('next-turn', 0, this.inbox.nextTurn.length, [], 'canceled') } + if (this.phase.kind !== 'idle') this.phase.abort.abort(cause) } /** Reserve a driver before deferring idle admission. */ @@ -147,7 +120,6 @@ export class ReactLoopAgent implements Agent { }) } - /** Resolve after the current driver and synchronous replacement chain exits. */ async whenIdle(): Promise { let driver: Promise do { @@ -171,13 +143,12 @@ export class ReactLoopAgent implements Agent { } } - /** Claim and admit the next queued prompt, then start its turn. */ private async admit(onTurnBoundary: boolean): Promise { if (this.phase.kind !== 'running') throw new Error() const signal = this.phase.abort.signal - const claimed = this.outbox.slice() - const outboxLength = this.outbox.length - const queued = onTurnBoundary ? this.queued[0] : undefined + const claimed = [...this.inbox.nextStep] + const outboxLength = this.inbox.nextStep.length + const queued = onTurnBoundary ? this.inbox.nextTurn[0] : undefined if (queued !== undefined) claimed.push(queued) if (claimed.length === 0) return { kind: 'empty' } const decision = await agentEvents(this.loopCtx, this).waterfall( @@ -186,34 +157,31 @@ export class ReactLoopAgent implements Agent { ) signal.throwIfAborted() if (decision.kind === 'allow') { - this.outbox.splice(0, outboxLength) - if (queued !== undefined) this.queued.shift() - return { kind: 'admitted', claimed, messages: decision.messages } - } else { - this.cancel({ kind: 'hook', reason: decision.reason }, { keepInbox: decision.keepInbox }) - return { kind: 'blocked' } + this.inbox.splice('next-step', 0, outboxLength, [], 'admitted') + if (queued !== undefined) this.inbox.splice('next-turn', 0, 1, [], 'admitted') + return { kind: 'admitted', messages: decision.messages } } + this.cancel({ kind: 'hook', reason: decision.reason }, { keepInbox: decision.keepInbox }) + return { kind: 'blocked' } } - /** - * Run one turn and any request-error retry. `admitted` input enters the log - * only after `turn/start` commits; until then it has no owner state to unwind. - */ + /** Admitted input stays unowned until `turn/start` commits. */ private async turn(): Promise { if (this.phase.kind === 'idle') throw new Error() const abort = this.phase.kind === 'collecting' ? this.phase.abort : new AbortController() + const { signal } = abort const lastTurn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn const phase = { kind: 'running' as const, abort, turn: lastTurn, step: 0 } this.setPhase(phase) - if (abort.signal.aborted) return this.outbox.length > 0 || this.queued.length > 0 + if (signal.aborted) return this.inbox.hasPending let admission: Admission try { admission = await this.admit(true) if (admission.kind !== 'admitted') return false - abort.signal.throwIfAborted() + signal.throwIfAborted() } catch (error: unknown) { // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- cancel may abort while admission awaits - if (abort.signal.aborted) return this.outbox.length > 0 || this.queued.length > 0 + if (signal.aborted) return this.inbox.hasPending throw error } const turn = ++phase.turn @@ -222,14 +190,11 @@ export class ReactLoopAgent implements Agent { try { while (true) { if (admission.kind === 'admitted') { - for (const message of admission.claimed) { - emitAgentEvent(this.loopCtx, this, 'agent/inbox/admitted', message) - } for (const message of admission.messages) { this.session.append('user/message', message, { surfaceOp: 'append' }) } } - abort.signal.throwIfAborted() + signal.throwIfAborted() const step = ++phase.step this.session.append('step/start', { turn, step }) try { @@ -237,34 +202,30 @@ export class ReactLoopAgent implements Agent { } finally { this.session.append('step/end', { turn, step }) } - abort.signal.throwIfAborted() - if (turnEnds && this.outbox.length === 0) { - await this.loopCtx.serial(agentCarrier(this), 'agent/turn-stopping', this, turn, abort.signal) - abort.signal.throwIfAborted() + signal.throwIfAborted() + if (turnEnds && this.inbox.nextStep.length === 0) { + await this.loopCtx.serial(agentCarrier(this), 'agent/turn-stopping', this, turn, signal) + signal.throwIfAborted() } admission = await this.admit(false) if (admission.kind === 'blocked') { - turnEnds = { kind: 'aborted', reason: abort.signal.reason as AgentCancelCause } + turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } return false } - abort.signal.throwIfAborted() + signal.throwIfAborted() if (admission.kind === 'empty' && turnEnds) break } } catch (error: unknown) { // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- cancel may abort during any awaited turn operation - if (abort.signal.aborted) turnEnds = { kind: 'aborted', reason: abort.signal.reason as AgentCancelCause } + if (signal.aborted) turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } else turnEnds = { kind: 'error', error: errorChain(error) } } finally { // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the turn is always ended in this block this.session.append('turn/end', { turn, reason: turnEnds! }) } - return this.outbox.length > 0 || this.queued.length > 0 + return this.inbox.hasPending } - /** - * Run the `agent/step` extension point, commit pending input, derive one - * request, and execute its tool calls inside one durable step boundary. - */ private async step(): Promise { if (this.phase.kind !== 'running') throw new Error() const { turn, step, abort: { signal } } = this.phase @@ -275,11 +236,9 @@ export class ReactLoopAgent implements Agent { signal.throwIfAborted() const system = renderPrompt(assembly) - let message: AssistantMessage while (true) { - const boundaryMessages = this.session.deriveMessages() const { request, preparedCall } = await this.buildRequest( - turn, step, assembly.tools, system, boundaryMessages, signal, + turn, step, assembly.tools, system, this.session.deriveMessages(), signal, ) const assembler = new BlockAssembler() const chunkSeqs: number[] = [] @@ -287,8 +246,7 @@ export class ReactLoopAgent implements Agent { signal.throwIfAborted() for await (const chunk of stream) { signal.throwIfAborted() - const chunkEvent = this.session.append('assistant/chunk', { turn, step, chunk }) - chunkSeqs.push(chunkEvent.seq) + chunkSeqs.push(this.session.append('assistant/chunk', { turn, step, chunk }).seq) assembler.push(chunk) } signal.throwIfAborted() @@ -305,47 +263,38 @@ export class ReactLoopAgent implements Agent { () => Promise.resolve(undefined), ) signal.throwIfAborted() - if (action?.kind !== 'retry') { - return { kind: 'error', error: finish.failure } - } - } else { - message = createAssistantMessage({ - content: assembler.blocks(), - source: { - provider: request.provider, - model: request.model, - ...assembler.replayState !== undefined ? { replayState: assembler.replayState } : {}, - }, - }) - this.session.append( - 'assistant/message', - { - turn, - step, - message, - ...assembler.usage === undefined ? {} : { usage: assembler.usage }, - }, - { surfaceOp: 'append', sourceEventSeqs: chunkSeqs }, - ) - if (finish.kind === 'max-tokens') { - return { kind: 'max-tokens' } - } - break + if (action?.kind !== 'retry') return { kind: 'error', error: finish.failure } + continue } - } - const toolCalls = message.content.filter(block => block.type === 'tool-call') - let result: TurnEndReason | null - if (toolCalls.length > 0) { + const message = createAssistantMessage({ + content: assembler.blocks(), + source: { + provider: request.provider, + model: request.model, + ...assembler.replayState !== undefined ? { replayState: assembler.replayState } : {}, + }, + }) + this.session.append( + 'assistant/message', + { + turn, + step, + message, + ...assembler.usage === undefined ? {} : { usage: assembler.usage }, + }, + { surfaceOp: 'append', sourceEventSeqs: chunkSeqs }, + ) + if (finish.kind === 'max-tokens') return { kind: 'max-tokens' } + + const toolCalls = message.content.filter(block => block.type === 'tool-call') + if (toolCalls.length === 0) return { kind: 'completed' } const { concluded } = await executeToolCalls( this.loopCtx, turn, step, toolCalls, signal, - context => this.outbox.push(context), + context => this.inbox.splice('next-step', this.inbox.nextStep.length, 0, [context]), ) - result = concluded ? { kind: 'completed' } : null - } else { - result = { kind: 'completed' } + return concluded ? { kind: 'completed' } : null } - return result } /** @@ -360,8 +309,6 @@ export class ReactLoopAgent implements Agent { boundaryMessages: Message[], signal: AbortSignal, ): Promise<{ request: GenerateOptions; preparedCall?: PreparedLlmCall }> { - // A loop instance starts from its declared route, restoring only an opaque - // effort owned by that exact model. Later steps fold the config it logged. const persistedConfig = this.session.requestHeader()?.config const route = { provider: this.options.provider ?? '', model: this.options.model ?? '' } const reasoningEffort = persistedConfig?.provider === route.provider @@ -369,16 +316,14 @@ export class ReactLoopAgent implements Agent { ? persistedConfig.reasoningEffort : undefined const maxTokens = this.options.maxTokens - const seedConfig = deepFreeze(structuredClone( - this.requestHeaderLogged - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the instance logged the header it now folds - ? persistedConfig! - : { - ...route, - ...reasoningEffort === undefined ? {} : { reasoningEffort }, - ...maxTokens === undefined ? {} : { maxTokens }, - }, - )) + const seedConfig = this.requestHeaderLogged + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the instance logged the frozen header it now folds + ? persistedConfig! + : deepFreeze({ + ...route, + ...reasoningEffort === undefined ? {} : { reasoningEffort }, + ...maxTokens === undefined ? {} : { maxTokens }, + }) const proposedConfig = await this.loopCtx.waterfall( agentCarrier(this), 'agent/request', this, turn, step, signal, () => Promise.resolve(seedConfig), @@ -393,8 +338,7 @@ export class ReactLoopAgent implements Agent { preparedCall = await this.loopCtx.llm.prepareCall(proposedConfig, signal) config = preparedCall.config } catch (error: unknown) { - // A llm/stream listener may own and short-circuit a route with no - // adapter. Terminal dispatch still raises NO_ADAPTER when none does. + // Middleware may serve an unregistered route; terminal dispatch still requires an adapter. if (!(error instanceof LlmError) || error.code !== 'NO_ADAPTER') throw error config = proposedConfig } diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 1bc9d58406..87796c97b6 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -76,8 +76,6 @@ describe('Agent.cancel()', () => { const adapter = new MockAdapter([textResponse('reply')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const canceled: unknown[] = [] - ctx.on('agent/inbox/canceled', (subject, message) => { if (subject === agent) canceled.push(message) }) agent.followup(createUserMessage({ content: [{ type: 'text', text: 'preserved' }], @@ -85,7 +83,8 @@ describe('Agent.cancel()', () => { })) // Abort the collecting activity while preserving its queued item. agent.cancel({ kind: 'user' }, { keepInbox: true }) - expect(canceled).toEqual([]) + expect(agent.session.events.some(event => + event.type === 'agent/inbox/spliced' && event.data.outcome === 'canceled')).toBe(false) // The preserved item still runs once a later follow-up wakes the driver. send(agent, 'wake it') diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index 31e6d7c2b1..a87afb578b 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -1,10 +1,10 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import LlmService, { createUserMessage, CallId, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm' +import LlmService, { createUserMessage, freezeMessage, CallId, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture, type PostToolDecision } from '@deepseek-ai/dsh-tools' -import AgentRegistry, { type Agent, type InboxItem, type InboxPlacement } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent' import AgentLoop from '@deepseek-ai/dsh-agent-loop' import { ReactLoopAgent } from '../src/agent.ts' import InvariantService from '@deepseek-ai/dsh-invariants' @@ -53,8 +53,8 @@ function send(agent: Agent, text: string) { agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })) } -function inboxText(item: InboxItem): string { - return item.message.content +function inboxText(message: UserMessage): string { + return message.content .flatMap(block => block.type === 'text' ? [block.text] : []) .join('') } @@ -69,42 +69,28 @@ describe('addressable inbox operations', () => { const agent = ctx.agentLoop.create(SessionId('inbox-actions'), { provider: 'mock', model: 'mock' }) const admission = Promise.withResolvers() const release = Promise.withResolvers() - ctx.on('agent/prompt-submit', async (_subject, message, _signal, next) => { - if (message.content[0]?.type === 'text' && message.content[0].text === 'first') { + ctx.on('agent/prompt-submit', async (_subject, messages, _signal, next) => { + if (messages[0]?.content[0]?.type === 'text' && messages[0].content[0].text === 'first') { admission.resolve(undefined) await release.promise } return next() }) - const pending: InboxItem[] = [] - const updates: { id: string; text: string }[] = [] - const discards: string[][] = [] - ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject === agent && inboxText(item) !== 'first') pending.push(item) - }) - ctx.on('agent/inbox/update', (subject, item) => { - if (subject === agent) updates.push({ id: item.id, text: inboxText(item) }) - }) - ctx.on('agent/inbox/discard', (subject, items) => { - if (subject === agent) discards.push(items.map(item => item.id)) - }) - send(agent, 'first') await admission.promise send(agent, 'remove me') send(agent, 'edit me') + const pending = agent.inbox.nextTurn expect(pending.map(inboxText)).toEqual(['remove me', 'edit me']) const remove = pending[0]! const edit = pending[1]! - expect(agent.updateInbox(edit.id, { - kind: 'edit', + expect(agent.inbox.splice('next-turn', 1, 1, [freezeMessage({ + ...edit, content: [{ type: 'text', text: 'edited' }], - })).toBe('applied') - expect(agent.updateInbox(remove.id, { kind: 'remove' })).toBe('applied') - expect(updates).toEqual([{ id: edit.id, text: 'edited' }]) - expect(discards).toEqual([[remove.id]]) + })])).toEqual([edit]) + expect(agent.inbox.splice('next-turn', 0, 1, [])).toEqual([remove]) const idle = waitForIdle(ctx, agent) release.resolve(undefined) @@ -115,46 +101,7 @@ describe('addressable inbox operations', () => { ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('') : '')) .toEqual(['first', 'edited']) - expect(agent.updateInbox(edit.id, { kind: 'remove' })).toBe('not-found') - }) - - it('does not mutate steering occurrences', async () => { - const adapter = new MockAdapter([textResponse('done')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('steering-inbox-actions'), { provider: 'mock', model: 'mock' }) - const entered = Promise.withResolvers() - const decision = Promise.withResolvers<{ kind: 'allow' }>() - ctx.on('agent/prompt-submit', async () => { - entered.resolve(undefined) - return decision.promise - }) - - const pending: InboxItem[] = [] - ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject === agent && item.placement === 'steering') pending.push(item) - }) - - const idle = waitForIdle(ctx, agent) - send(agent, 'admitted prompt') - await entered.promise - agent.steer(createUserMessage({ content: [{ type: 'text', text: 'keep me' }], source: { kind: 'user' } })) - expect(pending.map(inboxText)).toEqual(['keep me']) - - const steering = pending[0]! - expect(agent.updateInbox(steering.id, { - kind: 'edit', - content: [{ type: 'text', text: 'edited' }], - })).toBe('not-found') - expect(agent.updateInbox(steering.id, { kind: 'remove' })).toBe('not-found') - - decision.resolve({ kind: 'allow' }) - await idle - expect(agent.session.events - .filter(event => event.type === 'steering/message') - .map(event => event.type === 'steering/message' - ? event.data.message.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('') - : '')) - .toEqual(['keep me']) + expect(agent.inbox.splice('next-turn', 0, 1, [])).toEqual([]) }) }) @@ -590,7 +537,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => { expect(agent.session.deriveMessages().at(-1)?.content).toEqual([{ type: 'text', text: 'routed' }]) }) - it('agent/inbox/enqueue carries the exact message; steering/message records its source', async () => { + it('durable inbox splices carry exact messages and steering/message preserves its source', async () => { const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -604,27 +551,30 @@ describe('adapter registration, routing, and accepted-input ownership', () => { }, })) - const queuedSources: MessageSource[] = [] - const queuedShapes: string[][] = [] - const placements: InboxPlacement[] = [] - ctx.on('agent/inbox/enqueue', (_agent, item) => { - queuedSources.push(item.message.source) - queuedShapes.push(Object.keys(item.message).sort()) - placements.push(item.placement) + const insertedSources: MessageSource[] = [] + const insertedShapes: string[][] = [] + const targets: string[] = [] + ctx.on('session/event', (session, event) => { + if (session !== agent.session || event.type !== 'agent/inbox/spliced') return + for (const message of event.data.inserted) { + insertedSources.push(message.source) + insertedShapes.push(Object.keys(message).sort()) + targets.push(event.data.target) + } }) send(agent, 'go') // no explicit source → default {kind:'user'} must be visible await waitForIdle(ctx, agent) - expect(queuedSources).toEqual([ + expect(insertedSources).toEqual([ { kind: 'user' }, { kind: 'plugin', plugin: 'goal' }, ]) - expect(queuedShapes).toEqual([ + expect(insertedShapes).toEqual([ ['content', 'id', 'role', 'source'], ['content', 'id', 'role', 'source'], ]) - expect(placements).toEqual(['queued', 'steering']) + expect(targets).toEqual(['next-turn', 'next-step']) // The drain appends the durable steering/message with the caller's source // intact — the log, not a transient emit, is where consumers read it. const steeringSources = agent.session.events.flatMap(e => e.type === 'steering/message' ? [e.data.message.source] : []) diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json index 9113030eef..db0637ecc2 100644 --- a/packages/core/agent/package.json +++ b/packages/core/agent/package.json @@ -15,10 +15,6 @@ "types": "./lib/types/invariant.d.ts", "default": "./lib/invariant.js" }, - "./brand": { - "types": "./lib/types/brand.d.ts", - "default": "./lib/types/brand.js" - }, "./src/*": "./src/*", "./package.json": "./package.json" }, @@ -32,7 +28,6 @@ ], "license": "BSD-3-Clause", "peerDependencies": { - "@deepseek-ai/dsh-brand": "^0.0.1", "@deepseek-ai/dsh-invariants": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-scope": "^0.0.1", @@ -41,7 +36,6 @@ "cordis": "^4.0.0-rc.7" }, "devDependencies": { - "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-scope": "workspace:^", diff --git a/packages/core/agent/src/brand.ts b/packages/core/agent/src/brand.ts deleted file mode 100644 index 58d50259c1..0000000000 --- a/packages/core/agent/src/brand.ts +++ /dev/null @@ -1,23 +0,0 @@ -/** - * dsh-agent's owned branded ids for live inbox occurrences. - * - * @module @deepseek-ai/dsh-agent/brand - */ - -import type { Branded } from '@deepseek-ai/dsh-brand' - -/** - * Identifies one accepted occurrence in an agent inbox. Re-sending the same - * message creates a distinct item id, so pending work remains independently - * addressable. - */ -export type InboxItemId = Branded<'InboxItemId'> - -/** - * Brand a string as an {@link InboxItemId}. - * @param id - the agent-loop-minted occurrence identifier. - * @returns the same string, branded; no validation is performed. - */ -export function InboxItemId(id: string): InboxItemId { - return id as InboxItemId -} diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts new file mode 100644 index 0000000000..d6dafa7e4e --- /dev/null +++ b/packages/core/agent/src/inbox.ts @@ -0,0 +1,109 @@ +/** + * Incremental projection of durable agent inbox events. + * + * @module @deepseek-ai/dsh-agent/inbox + */ + +import type { Session, SessionEventMap, UserMessage } from '@deepseek-ai/dsh-session' + +/** One of the two ordered pending-message lists owned by an agent. */ +export type InboxTarget = 'next-turn' | 'next-step' + +/** Mutable state privately owned by an {@link Inbox}. */ +type InboxState = Record + +/** A replay-once projection that incrementally consumes later inbox splices. */ +export class Inbox { + private readonly state: InboxState = { 'next-turn': [], 'next-step': [] } + + constructor(private readonly session: Session) { + for (const event of session.events.slice(session.header.seedLength ?? 0)) { + if (event.type !== 'agent/inbox/spliced') continue + try { + this.apply(event.data) + } catch (error: unknown) { + throw new Error(`invalid persisted inbox splice at session seq ${event.seq}`, { cause: error }) + } + } + } + + /** Prompts awaiting individual turns. */ + get nextTurn(): readonly UserMessage[] { + return this.state['next-turn'] + } + + /** Input awaiting admission at a step boundary. */ + get nextStep(): readonly UserMessage[] { + return this.state['next-step'] + } + + /** Whether either pending-message list contains work. */ + get hasPending(): boolean { + return this.nextTurn.length > 0 || this.nextStep.length > 0 + } + + /** + * Apply standard splice semantics and durably record the normalized result. + * @param target - pending list to mutate. + * @param start - splice position. + * @param deleteCount - maximum number of messages to remove. + * @param inserted - messages to insert at the resolved position. + * @param outcome - terminal disposition of removed messages. + * @returns messages removed by the splice. + */ + splice( + target: InboxTarget, + start: number, + deleteCount: number, + inserted: UserMessage[], + outcome?: 'admitted' | 'canceled', + ): UserMessage[] { + const inbox = this.state[target] + const offset = Math.trunc(start) || 0 + const actualStart = offset < 0 + ? Math.max(inbox.length + offset, 0) + : Math.min(offset, inbox.length) + const actualDeleteCount = Math.min( + Math.max(Math.trunc(deleteCount) || 0, 0), + inbox.length - actualStart, + ) + if (actualDeleteCount === 0 && inserted.length === 0) return [] + const resolvedOutcome = outcome ?? (actualDeleteCount > 0 ? 'canceled' : undefined) + const splice = { + target, + start: actualStart, + ...(actualDeleteCount === 0 ? {} : { removedCount: actualDeleteCount }), + inserted, + ...(resolvedOutcome === undefined ? {} : { outcome: resolvedOutcome }), + } + this.validate(splice) + const event = this.session.append('agent/inbox/spliced', splice) + return inbox.splice(actualStart, actualDeleteCount, ...event.data.inserted) + } + + /** Apply one normalized durable splice to the projection. */ + private apply(splice: SessionEventMap['agent/inbox/spliced']): UserMessage[] { + this.validate(splice) + const inbox = this.state[splice.target] + return inbox.splice(splice.start, splice.removedCount ?? 0, ...splice.inserted) + } + + /** Validate one normalized splice against the current projection. */ + private validate(splice: SessionEventMap['agent/inbox/spliced']): void { + const inbox = this.state[splice.target] + const removedCount = splice.removedCount ?? 0 + if (!Number.isSafeInteger(splice.start) || splice.start < 0 || splice.start > inbox.length + || !Number.isSafeInteger(removedCount) || removedCount < 0 + || splice.start + removedCount > inbox.length) { + throw new Error('invalid inbox splice') + } + const candidate = inbox.toSpliced(splice.start, removedCount, ...splice.inserted) + const ids = new Set() + for (const message of splice.target === 'next-turn' + ? [...candidate, ...this.nextStep] + : [...this.nextTurn, ...candidate]) { + if (ids.has(message.id)) throw new Error(`message "${message.id}" is already pending`) + ids.add(message.id) + } + } +} diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts index 0d87778135..d46d8833c5 100644 --- a/packages/core/agent/src/index.ts +++ b/packages/core/agent/src/index.ts @@ -15,7 +15,7 @@ import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session' import type { Agent, AgentOptions } from './types.ts' export * from './types.ts' -export * from './brand.ts' +export * from './inbox.ts' export * from './llm-target.ts' export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts' export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts' diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 804ad4a963..b1451768ca 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -7,10 +7,10 @@ import type { Context } from 'cordis' import type { Scoped } from '@deepseek-ai/dsh-scope' -import type { ContentBlock, LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm' +import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm' import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session' export type { AgentCancelCause } from '@deepseek-ai/dsh-session' -import type { InboxItemId } from './brand.ts' +import type { Inbox, InboxTarget } from './inbox.ts' import type {} from '@deepseek-ai/dsh-system-prompt' declare module '@deepseek-ai/dsh-system-prompt' { interface AssembleContext { @@ -29,63 +29,12 @@ export interface AgentOptions { maxTokens?: number } -/** - * Which inbox queue a {@link Agent.send} item joins: - * - `next-turn` — the item becomes its own turn, claimed at a turn boundary. - * - `next-step` — during prompt admission or an open turn, the item stages for - * the next safe step boundary; otherwise it is promoted per its `wakeup` - * flag. - */ -export type SendTarget = 'next-turn' | 'next-step' - -/** Resolved inbox placement reported when an accepted message is enqueued. */ -export type InboxPlacement = 'queued' | 'steering' - -/** One independently addressable accepted occurrence in an agent inbox. */ -export interface InboxItem { - /** Agent-loop-minted occurrence identity. */ - readonly id: InboxItemId - /** Identified message delivered by the caller. */ - readonly message: UserMessage - /** Acceptance-time FIFO classification. */ - readonly placement: InboxPlacement -} - -/** A user-requested mutation of one still-pending queued occurrence. */ -export type InboxAction = - | { readonly kind: 'edit'; readonly content: ContentBlock[] } - | { readonly kind: 'remove' } - -/** Result of applying an inbox action at the synchronous ownership boundary. */ -export type InboxActionResult = 'applied' | 'not-found' - -/** - * Options for the unified {@link Agent.send} primitive over the - * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup} - * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and - * {@link Agent.inject} (`next-step`/no-wakeup). - * - * The object is complete so routing policy is explicit. - */ -export interface SendOptions { - /** Queue the item joins. */ - target: SendTarget - /** - * Whether this item makes the model run: wake a parked driver (`next-turn`) - * or force a continuation step (`next-step` while running). A `false` - * `next-turn` item queues without waking; a `false` - * `next-step` item attaches durable context without forcing another step - * (the injection preset). - */ - wakeup: boolean -} - /** Options for {@link Agent.cancel}. */ export interface CancelOptions { /** * Preserve queued and steering inbox items instead of discarding them. The * active turn is still aborted, but un-started and pending work survives for a - * later turn and no `agent/inbox/canceled` fires. + * later turn and no canceled inbox splice is logged. */ keepInbox?: boolean | undefined } @@ -136,30 +85,13 @@ export interface Agent { readonly options: AgentOptions /** The live session this agent drives; its log is the durable source of truth. */ readonly session: Session + /** The agent-owned projection of durable pending work. */ + readonly inbox: Inbox /** The current lifecycle state, mirrored on every `agent/status` transition. */ readonly status: AgentStatus - /** Whether a next-step send currently remains in the open turn. */ - readonly acceptsNextStep: boolean /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */ readonly ctx: Context - /** - * The unified delivery primitive over the (`target` × `wakeup`) matrix. - * @param message - identified model-facing content and its producer provenance. - * @param options - target queue and wakeup decision. - */ - send(message: UserMessage, options: SendOptions): void - - /** - * Mutate one still-pending queued occurrence synchronously. Editing preserves - * the message identity and queue position; removal publishes its terminal - * discard. Steering occurrences and driver-claimed items return `not-found`. - * @param id - independently addressable queued occurrence. - * @param action - edit or remove operation. - * @returns whether the pending occurrence was found and updated. - */ - updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult - /** * Clear queued and steering work — unless `keepInbox` — and abort the active * turn. The first cause wins for the active turn. Idle cancellation is a @@ -236,48 +168,6 @@ declare module 'cordis' { * @mode emit */ 'agent/status'(this: Scoped, agent: Agent, status: AgentStatus): void - /** - * An item entered the queued or steering inbox. `placement` is the - * acceptance-time routing result. - * @param agent - the owning agent. - * @param item - accepted occurrence, message, and resolved placement. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/inbox/enqueue'(this: Scoped, agent: Agent, item: InboxItem): void - /** - * A still-pending queued item changed content. - * @param agent - the owning agent. - * @param item - the complete post-update occurrence. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/inbox/update'(this: Scoped, agent: Agent, item: InboxItem): void - /** - * The driver claimed one item out of the inbox. - * @param agent - the agent whose inbox item was claimed. - * @param item - the exact claimed occurrence. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/inbox/dequeue'(this: Scoped, agent: Agent, item: InboxItem): void - /** - * Pending inbox items were dropped without delivery. - * @param agent - the agent whose inbox items were dropped. - * @param items - the discarded occurrences in FIFO order. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/inbox/discard'(this: Scoped, agent: Agent, items: InboxItem[]): void - /** - * Effective broad cancellation was requested before pending work clears or - * the active turn aborts. - * @param agent - the agent whose current work is being cancelled. - * @param cause - the explicit typed cancellation cause. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ - 'agent/cancel-requested'(this: Scoped, agent: Agent, cause: AgentCancelCause): void // ---- session lifecycle (emit) ---- /** * The session lifecycle began, once before the first turn. Use @@ -374,7 +264,13 @@ declare module 'cordis' { declare module '@deepseek-ai/dsh-session' { interface SessionEventMap { - /** One message was accepted into the agent inbox. */ - 'agent/inbox/added': UserMessage + /** One normalized mutation of an agent's durable pending-message lists. */ + 'agent/inbox/spliced': { + target: InboxTarget + start: number + removedCount?: number + inserted: UserMessage[] + outcome?: 'admitted' | 'canceled' + } } } diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts index ffd1bd91c4..b2178aea7e 100644 --- a/packages/core/agent/tests/agent.spec.ts +++ b/packages/core/agent/tests/agent.spec.ts @@ -21,8 +21,6 @@ function stubAgent(rawId: string, overrides: Partial = {}): Agent { session: new Session(id), status: 'idle', ctx: new Context(), - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/core/agent/tests/invariant.spec.ts b/packages/core/agent/tests/invariant.spec.ts index 7744726465..158376a3d7 100644 --- a/packages/core/agent/tests/invariant.spec.ts +++ b/packages/core/agent/tests/invariant.spec.ts @@ -1,7 +1,6 @@ -import { freezeMessage, MessageId } from '@deepseek-ai/dsh-llm' import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import { InboxItemId, type Agent, type InboxItem, type InboxPlacement } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant' import { scopeTarget } from '@deepseek-ai/dsh-scope' import InvariantService from '@deepseek-ai/dsh-invariants' @@ -44,51 +43,3 @@ describe('agent status invariants', () => { expect(() => { ctx.emit(scopeTarget(b, b), 'agent/status', b, 'running') }).not.toThrow() }) }) - -describe('agent inbox invariants', () => { - let nextItem = 0 - const info = (placement: InboxPlacement = 'queued'): InboxItem => ({ - id: InboxItemId(`i-${nextItem++}`), - message: freezeMessage({ - id: MessageId('m'), - role: 'user' as const, - content: [], - source: { kind: 'user' as const }, - }), - placement, - }) - - it('accepts a dequeue and a discard covered by prior enqueues', async () => { - const ctx = await setup() - const agent = mockAgent('i1') - const at = scopeTarget(agent, agent) - expect(() => { - ctx.emit(at, 'agent/inbox/enqueue', agent, info()) - ctx.emit(at, 'agent/inbox/enqueue', agent, info('steering')) - ctx.emit(at, 'agent/inbox/dequeue', agent, info()) - ctx.emit(at, 'agent/inbox/discard', agent, [info()]) - }).not.toThrow() - }) - - it('rejects a dequeue with no outstanding item', async () => { - const ctx = await setup() - const agent = mockAgent('i2') - expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/dequeue', agent, info()) }) - .toThrow(/without a matching prior enqueue/) - }) - - it('rejects a discard larger than the outstanding count', async () => { - const ctx = await setup() - const agent = mockAgent('i3') - const at = scopeTarget(agent, agent) - ctx.emit(at, 'agent/inbox/enqueue', agent, info()) - expect(() => { ctx.emit(at, 'agent/inbox/discard', agent, [info(), info()]) }) - .toThrow(/dropped 2 items but only 1 were outstanding/) - }) - - it('accepts an empty discard against a fresh agent', async () => { - const ctx = await setup() - const agent = mockAgent('i4') - expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/discard', agent, []) }).not.toThrow() - }) -}) diff --git a/packages/core/agent/tsconfig.json b/packages/core/agent/tsconfig.json index b6d6c9e6bf..1561175ed9 100644 --- a/packages/core/agent/tsconfig.json +++ b/packages/core/agent/tsconfig.json @@ -14,9 +14,6 @@ { "path": "../../../vendor/cordis" }, - { - "path": "../../util/brand" - }, { "path": "../../core/scope" }, diff --git a/packages/core/scope/src/scoped-events.generated.ts b/packages/core/scope/src/scoped-events.generated.ts index fff3107f48..e08fd2aabd 100644 --- a/packages/core/scope/src/scoped-events.generated.ts +++ b/packages/core/scope/src/scoped-events.generated.ts @@ -8,14 +8,9 @@ type ScopedSubjectResolver = (args: readonly unknown[]) => unknown const scopedSubjectResolvers: Readonly> = Object.freeze({ - 'agent/cancel-requested': args => args[0], 'agent/created': args => args[0], 'agent/disposed': args => args[0], 'agent/error': args => args[0], - 'agent/inbox/dequeue': args => args[0], - 'agent/inbox/discard': args => args[0], - 'agent/inbox/enqueue': args => args[0], - 'agent/inbox/update': args => args[0], 'agent/prompt-submit': args => args[0], 'agent/request': args => args[0], 'agent/request-error': args => args[0], diff --git a/packages/core/scope/tests/invariant.spec.ts b/packages/core/scope/tests/invariant.spec.ts index f773f3a9aa..ccc90e7843 100644 --- a/packages/core/scope/tests/invariant.spec.ts +++ b/packages/core/scope/tests/invariant.spec.ts @@ -2,7 +2,7 @@ import { freezeMessage, MessageId } from '@deepseek-ai/dsh-llm' import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import type { Events } from 'cordis' -import { InboxItemId, type Agent } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' import { scopeTarget } from '@deepseek-ai/dsh-scope' import * as ScopeInvariant from '@deepseek-ai/dsh-scope/invariant' import InvariantService from '@deepseek-ai/dsh-invariants' @@ -44,27 +44,22 @@ describe('scoped-dispatch invariants', () => { content: [], source: { kind: 'user' }, }) - const item = { id: InboxItemId('i'), message, placement: 'queued' as const } const agentRows = { 'agent/created': [agent], 'agent/disposed': [agent], 'agent/status': [agent, 'idle'], - 'agent/inbox/enqueue': [agent, item], - 'agent/inbox/update': [agent, item], - 'agent/inbox/dequeue': [agent, item], - 'agent/inbox/discard': [agent, []], 'agent/session-start': [agent, 'startup'], 'agent/step': [agent, 1, 1, signal], - 'agent/prompt-submit': [agent, message, signal, () => Promise.resolve({ kind: 'allow' })], + 'agent/prompt-submit': [agent, [message], signal, () => Promise.resolve({ kind: 'allow', messages: [message] })], 'agent/request': [agent, 1, 1, signal, () => Promise.resolve(config)], 'agent/request-error': [ agent, - 1, - 1, - new Error('request'), - { message: 'request', code: 'UNKNOWN' }, - [], - undefined, + { + turn: 1, + step: 1, + provider: 'p', + failure: { message: 'request', code: 'UNKNOWN' }, + }, signal, () => Promise.resolve(undefined), ], diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts index fc77b11331..1414a0691a 100644 --- a/packages/examples/cli-demo/tests/cli.spec.ts +++ b/packages/examples/cli-demo/tests/cli.spec.ts @@ -114,14 +114,13 @@ const liveContexts: Context[] = [] async function harness(script: readonly ScriptEntry[]): Promise { const root = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-')) - const skillHome = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-skills-')) const ctx = new Context() liveContexts.push(ctx) await ctx.plugin(cliDemo, { provider: 'mock', model: 'mock', persistenceRoot: root, - skills: { local: { dshHome: join(skillHome, '.dsh'), agentsHome: join(skillHome, '.agents') } }, + skills: { enabled: false }, workspaceContext: false, }) await new Promise(resolve => setTimeout(resolve, 80)) @@ -380,29 +379,94 @@ describe('runOneShot and executeCli', () => { expect(result.result).toBe('working') }) - it('streams only the correlated main message turn and then the result envelope', async () => { - const { ctx, agent } = await harness([textResponse('streamed')]) + it('observes only the correlated main message turn', async () => { + const { ctx, agent } = await harness([ + textResponse('startup'), + textResponse('autonomous'), + textResponse('streamed'), + ]) const other = ctx.sessions.create(SessionId('unrelated')) - let injected = false - ctx.on('agent/inbox/enqueue', (subject) => { - if (subject !== agent || injected) return - injected = true - agent.inject(createUserMessage({ content: [{ type: 'text', text: 'startup injection' }], source: { kind: 'plugin', plugin: 'test' } })) + let startupStarted!: () => void + const started = new Promise((resolve) => { startupStarted = resolve }) + const releaseStartup = Promise.withResolvers() + ctx.on('session/event', (session, event) => { + if (session === agent.session && event.type === 'assistant/message' + && event.data.turn === 1) startupStarted() + }) + ctx.on('agent/turn-stopping', async (subject, turn) => { + if (subject === agent && turn === 1) await releaseStartup.promise + }) + agent.followup(createUserMessage({ + content: [{ type: 'text', text: 'startup' }], + source: { kind: 'plugin', plugin: 'startup' }, + })) + await started + + let replacementQueued = false + ctx.on('agent/status', (subject, status) => { + if (subject !== agent || status !== 'idle' || replacementQueued) return + replacementQueued = true + agent.followup(createUserMessage({ + content: [{ type: 'text', text: 'autonomous' }], + source: { kind: 'plugin', plugin: 'test' }, + })) other.append('turn/start', { turn: 1 }) other.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) }) - const output = await invoke(ctx, ['--output-format', 'stream-json', 'task']) - const lines = output.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record) - const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent) - expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, turn: 1, result: 'streamed' }) - expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 1 } }) - expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 1 } }) - expect(lines.slice(0, -1).every(line => line['sessionId'] === agent.session.id)).toBe(true) + const streamed: { sessionId: string; event: SessionEvent }[] = [] + const result = runOneShot(ctx, { + task: 'task', + onEvent: (sessionId, event) => { streamed.push({ sessionId, event }) }, + }) + releaseStartup.resolve(undefined) + + const outcome = await result + expect(outcome.reason).toEqual({ kind: 'completed' }) + expect(outcome).toMatchObject({ success: true, turn: 3, result: 'streamed' }) + const events = streamed.map(item => item.event) + expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 3 } }) + expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 3 } }) + expect(streamed.every(item => item.sessionId === agent.session.id)).toBe(true) expect(events.some(event => event.type === 'user/message' && event.data.source.kind === 'plugin' && event.data.source.plugin === 'test')).toBe(false) }) + it('correlates a task whose admitted history is replaced', async () => { + const { ctx } = await harness([textResponse('rewritten answer')]) + ctx.on('agent/prompt-submit', async () => ({ + kind: 'allow', + messages: [createUserMessage({ + content: [{ type: 'text', text: 'rewritten task' }], + source: { kind: 'plugin', plugin: 'test' }, + })], + })) + + await expect(runOneShot(ctx, { task: 'original task' })).resolves.toMatchObject({ + success: true, + result: 'rewritten answer', + }) + }) + + it('rejects tasks blocked before admission, including retained tasks', async () => { + const blocked = await harness([]) + blocked.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'denied' })) + await expect(runOneShot(blocked.ctx, { task: 'task' })).rejects.toThrow('canceled before admission') + + const retained = await harness([]) + retained.ctx.on('agent/prompt-submit', async () => ({ + kind: 'block' as const, + reason: 'deferred', + keepInbox: true, + })) + await expect(runOneShot(retained.ctx, { task: 'task' })).rejects.toThrow('not admitted') + expect(retained.agent.status).toBe('idle') + + const failed = await harness([]) + failed.ctx.on('agent/prompt-submit', async () => { throw new Error('admission exploded') }) + await expect(runOneShot(failed.ctx, { task: 'task' })).rejects.toThrow('not admitted') + }) + it('emits partial data and a diagnostic for non-completed turns', async () => { const { ctx } = await harness([textResponse('partial', { inputTokens: 2, outputTokens: 3 }, 'max-tokens')]) const output = await invoke(ctx, ['--output-format', 'json', 'task']) @@ -498,8 +562,11 @@ describe('runOneShot and executeCli', () => { const queued = await harness([textResponse('unused')]) const queuedAbort = new AbortController() - queued.ctx.on('agent/inbox/enqueue', (agent) => { - if (agent === queued.agent) queuedAbort.abort('cancel queued') + queued.ctx.on('session/event', (session, event) => { + if (session === queued.agent.session && event.type === 'agent/inbox/spliced' + && event.data.inserted.some(message => message.source.kind === 'user')) { + queueMicrotask(() => { queuedAbort.abort('cancel queued') }) + } }) await expect(runOneShot(queued.ctx, { task: 'task', signal: queuedAbort.signal })).rejects.toThrow('cancel queued') await queued.agent.whenIdle() diff --git a/packages/goal/command-goal/tests/command-goal.spec.ts b/packages/goal/command-goal/tests/command-goal.spec.ts index 89f115df4d..ef7204e7c0 100644 --- a/packages/goal/command-goal/tests/command-goal.spec.ts +++ b/packages/goal/command-goal/tests/command-goal.spec.ts @@ -36,9 +36,6 @@ function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } session, ctx: new Context(), get status() { return status }, - get acceptsNextStep() { return status === 'running' }, - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { appendInjection(session, input) }, diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index 3260016d5f..5694da1dae 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -324,37 +324,6 @@ export function apply(ctx: Context): void { requestDrive(state) } }) - ctx.on('agent/inbox/enqueue', (agent, item) => { - const state = stateFor(agent) - const attempt = state.attempt - if (attempt !== undefined && sameQueued(item.message.content, item.message.source, attempt)) return - state.competingQueued = true - if (attempt?.phase === 'queued') attempt.stale = true - }) - ctx.on('agent/cancel-requested', (agent, cause) => { - const state = stateFor(agent) - const attempt = state.attempt - state.competingQueued = false - const goal = currentGoal(state) - if (goal?.phase === 'active' && goal.activation === 'armed') { - if (attempt === undefined) { - disarm(state) - return - } - // An admitted round closes durably as aborted; retain it so the normal - // turn outcome path appends pause after cancellation reaches idle. - // Pausing here would stage context into the active outbox only for this - // same cancel() call to discard it. - if (attempt.turn !== undefined || attempt.phase === 'admitted') return - state.attempt = undefined - try { - applyOutcome(state, goal, { kind: 'pause', reason: cause.kind }) - } catch (error: unknown) { - ctx.logger.warn(`goal-session: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`) - disarm(state) - } - } - }) ctx.on('goal/changed', (agent) => { const state = stateFor(agent) state.needsCheckpoint = true @@ -366,12 +335,14 @@ export function apply(ctx: Context): void { if (agent === undefined || agent.session !== session) return const state = stateFor(agent) switch (event.type) { - case 'agent/inbox/added': { + case 'agent/inbox/spliced': { + if (event.data.target !== 'next-turn') return const attempt = state.attempt - const { content, source } = event.data - if (attempt !== undefined && sameQueued(content, source, attempt)) return - state.competingQueued = true - if (attempt?.phase === 'queued') attempt.stale = true + for (const message of event.data.inserted) { + if (attempt !== undefined && sameQueued(message.content, message.source, attempt)) continue + state.competingQueued = true + if (attempt?.phase === 'queued') attempt.stale = true + } return } case 'turn/start': { diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index 20c74b9f15..d1144bea1d 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -9,7 +9,7 @@ import type { GoalView } from '@deepseek-ai/dsh-goal' import { createUserMessage, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm' import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' -import type { TurnEndReason } from '@deepseek-ai/dsh-session' +import type { TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session' import * as goalSession from '../src/index.ts' type ScriptEntry = StreamChunk[] | Error | 'hang' | ((options: GenerateOptions) => StreamChunk[]) @@ -101,6 +101,18 @@ async function harness(script: ScriptEntry[]): Promise { return { ctx, adapter, agent, driver } } +/** Observe inserted inbox messages after the session append boundary closes. */ +function onInboxMessage( + ctx: Context, + agent: Agent, + listener: (message: UserMessage) => void, +): () => void { + return ctx.on('session/event', (session, event) => { + if (session !== agent.session || event.type !== 'agent/inbox/spliced') return + for (const message of event.data.inserted) queueMicrotask(() => { listener(message) }) + }) +} + /** Await a stable goal projection selected by the caller. */ async function waitForGoal( ctx: Context, @@ -279,10 +291,10 @@ describe('same-session goal driving', () => { it('pauses and drops a reserved round when cancellation lands before admission', async () => { const test = await harness([]) - const cancel = test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent === test.agent && info.message.source.kind === 'goal') { + const cancel = onInboxMessage(test.ctx, test.agent, (message) => { + if (message.source.kind === 'goal') { cancel() - agent.cancel({ kind: 'user' }) + test.agent.cancel({ kind: 'user' }) } }) test.ctx.goals.create(test.agent, { objective: 'do not start yet' }) @@ -330,10 +342,10 @@ describe('same-session goal driving', () => { it('makes a reserved round stale when a listener queues human work behind it', async () => { const test = await harness([textResponse('human batch'), textResponse('later goal')]) let inserted = false - test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent !== test.agent || info.message.source.kind !== 'goal' || inserted) return + onInboxMessage(test.ctx, test.agent, (message) => { + if (message.source.kind !== 'goal' || inserted) return inserted = true - agent.followup(createUserMessage({ content: [{ type: 'text', text: 'human joined the pending batch' }], source: { kind: 'user' } })) + test.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'human joined the pending batch' }], source: { kind: 'user' } })) }) test.ctx.goals.create(test.agent, { objective: 'yield to nested human input', maxGoalRounds: 1 }) @@ -348,12 +360,12 @@ describe('same-session goal driving', () => { it('blocks a queued reservation made stale by a goal edit and continues the new revision', async () => { const test = await harness([textResponse('new revision')]) let edited = false - test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent !== test.agent || info.message.source.kind !== 'goal' || edited) return + onInboxMessage(test.ctx, test.agent, (message) => { + if (message.source.kind !== 'goal' || edited) return edited = true - const current = test.ctx.goals.get(agent) + const current = test.ctx.goals.get(test.agent) if (current === undefined) throw new Error('missing goal during queued edit') - test.ctx.goals.edit(agent, current, { objective: 'new objective' }) + test.ctx.goals.edit(test.agent, current, { objective: 'new objective' }) }) test.ctx.goals.create(test.agent, { objective: 'old objective', maxGoalRounds: 1 }) @@ -628,8 +640,8 @@ describe('same-session goal driving', () => { it('fails a pre-admission read closed even when the first disarm attempt throws', async () => { const test = await harness([textResponse('retry after containment')]) let armed = true - test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent !== test.agent || info.message.source.kind !== 'goal' || !armed) return + onInboxMessage(test.ctx, test.agent, (message) => { + if (message.source.kind !== 'goal' || !armed) return armed = false vi.spyOn(test.ctx.goals, 'get').mockImplementationOnce(() => { throw new Error('admission projection failed') @@ -704,13 +716,13 @@ describe('same-session goal driving', () => { it('falls back to disarming when a cancelled reservation cannot be paused', async () => { const test = await harness([]) - const cancel = test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent !== test.agent || info.message.source.kind !== 'goal') return + const cancel = onInboxMessage(test.ctx, test.agent, (message) => { + if (message.source.kind !== 'goal') return cancel() vi.spyOn(test.ctx.goals, 'pause').mockImplementationOnce(() => { throw new Error('pause failed') }) - agent.cancel({ kind: 'user' }) + test.agent.cancel({ kind: 'user' }) }) test.ctx.goals.create(test.agent, { objective: 'fail closed after cancellation' }) @@ -758,8 +770,8 @@ describe('same-session goal driving', () => { it('cancels an accepted queued round and awaits its driver task during teardown', async () => { const test = await harness([]) let unloading: Promise | undefined - test.ctx.on('agent/inbox/enqueue', (agent, info) => { - if (agent === test.agent && info.message.source.kind === 'goal' && unloading === undefined) { + onInboxMessage(test.ctx, test.agent, (message) => { + if (message.source.kind === 'goal' && unloading === undefined) { unloading = Promise.resolve(test.driver.dispose()) } }) diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts index e01356f271..f395996011 100644 --- a/packages/goal/goal/tests/goal.spec.ts +++ b/packages/goal/goal/tests/goal.spec.ts @@ -46,9 +46,6 @@ function stubAgentForSession(session: Session): StubAgent { session, ctx: new Context(), get status() { return status }, - get acceptsNextStep() { return status === 'running' }, - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/goal/goal/tests/projection.spec.ts b/packages/goal/goal/tests/projection.spec.ts index f787a881f8..70fcbc0d5a 100644 --- a/packages/goal/goal/tests/projection.spec.ts +++ b/packages/goal/goal/tests/projection.spec.ts @@ -37,9 +37,6 @@ function liveAgent(ctx: Context, session: Session): Agent { session, ctx, get status() { return status }, - get acceptsNextStep() { return false }, - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input: UserMessage) { diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts index 7bcee0c0e7..d411e0c9b2 100644 --- a/packages/goal/tool-goal/tests/tool-goal.spec.ts +++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts @@ -30,10 +30,7 @@ function stubAgent(rawId: string, supplied?: Session): StubAgent { options: {}, session, get status() { return status }, - get acceptsNextStep() { return status === 'running' }, ctx: new Context(), - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index e7c1d96acf..c68f81745d 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -9,9 +9,9 @@ import { join } from 'node:path' import type { Context } from 'cordis' import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent' import type { - Agent, AgentLlmTarget, AgentLlmTargetRef, AgentStatus, InboxItem, InboxItemId, + Agent, AgentLlmTarget, AgentLlmTargetRef, AgentStatus, } from '@deepseek-ai/dsh-agent' -import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm' +import { createUserMessage, freezeMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm' import { errorChain } from '@deepseek-ai/dsh-llm' import type { MessageSource } from '@deepseek-ai/dsh-llm' import type { Session, SessionEvent, SessionHeader, SessionId, UserMessage } from '@deepseek-ai/dsh-session' @@ -507,112 +507,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro }) }) - /** - * Per-session queued-occurrence mirror serving the mux-open queue snapshot - * (the same refresh-recovery baseline as pending questions). Each terminal - * queue event retires one matching occurrence, so repeated sends of the same - * identified message remain visible until every occurrence is claimed. - */ - const queuedMirror = new Map() - type UnseenQueueEvent = - | { readonly kind: 'update'; readonly item: InboxItem } - | { readonly kind: 'terminal' } - const unseenQueueEvents = new Map>() - const rememberUnseen = (sessionId: SessionId, itemId: InboxItemId, event: UnseenQueueEvent): void => { - let events = unseenQueueEvents.get(sessionId) - if (events === undefined) { - events = new Map() - unseenQueueEvents.set(sessionId, events) - } - events.set(itemId, event) - // Only synchronous re-entrancy may deliver a mutation before its outer - // enqueue observer. Drop unmatched protocol-invalid observations instead - // of retaining process-local ids indefinitely. - queueMicrotask(() => { - const current = unseenQueueEvents.get(sessionId) - if (current?.get(itemId) !== event) return - current.delete(itemId) - if (current.size === 0) unseenQueueEvents.delete(sessionId) - }) - } - const takeUnseen = (sessionId: SessionId, itemId: InboxItemId): UnseenQueueEvent | undefined => { - const events = unseenQueueEvents.get(sessionId) - const event = events?.get(itemId) - if (event === undefined) return undefined - events?.delete(itemId) - if (events?.size === 0) unseenQueueEvents.delete(sessionId) - return event - } - const publishQueue = (sessionId: SessionId): void => { - const items = queuedMirror.get(sessionId) ?? [] - broadcast({ - type: 'session/queue', - sessionId, - items: items.map(item => ({ - id: item.id, - message: item.message, - })), - }) - } - ctx.effect(() => { - const retire = (agent: Agent, item: InboxItem): boolean => { - const entries = queuedMirror.get(agent.id) - if (entries === undefined) { - rememberUnseen(agent.id, item.id, { kind: 'terminal' }) - return false - } - const index = entries.findIndex(entry => entry.id === item.id) - if (index === -1) { - rememberUnseen(agent.id, item.id, { kind: 'terminal' }) - return false - } - entries.splice(index, 1) - if (entries.length === 0) queuedMirror.delete(agent.id) - return true - } - const disposers = [ - ctx.on('agent/inbox/enqueue', (agent: Agent, item: InboxItem) => { - if (item.placement !== 'queued') return - const unseen = takeUnseen(agent.id, item.id) - if (unseen?.kind === 'terminal') return - let entries = queuedMirror.get(agent.id) - if (entries === undefined) { - entries = [] - queuedMirror.set(agent.id, entries) - } - entries.push(unseen?.kind === 'update' ? unseen.item : item) - publishQueue(agent.id) - }), - ctx.on('agent/inbox/update', (agent: Agent, item: InboxItem) => { - const entries = queuedMirror.get(agent.id) - if (entries === undefined) { - rememberUnseen(agent.id, item.id, { kind: 'update', item }) - return - } - const index = entries.findIndex(entry => entry.id === item.id) - if (index === -1) { - rememberUnseen(agent.id, item.id, { kind: 'update', item }) - return - } - entries.splice(index, 1, item) - publishQueue(agent.id) - }), - ctx.on('agent/inbox/dequeue', (agent: Agent, item: InboxItem) => { - if (retire(agent, item)) publishQueue(agent.id) - }), - ctx.on('agent/inbox/discard', (agent: Agent, items: InboxItem[]) => { - let changed = false - for (const item of items) changed = retire(agent, item) || changed - if (changed) publishQueue(agent.id) - }), - ctx.on('session/disposed', (session: Session) => { - queuedMirror.delete(session.id) - unseenQueueEvents.delete(session.id) - }), - ] - return () => { for (const dispose of disposers) dispose() } - }, 'api-proxy: queued mirror') - /** Remove a wait before settling it: synchronous deletion makes the first claimant win. */ function claimQuestion(pending: PendingQuestion, outcome: 'answered' | 'cancelled'): void { pendingQuestions.delete(pending.rpcId) @@ -1162,13 +1056,21 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro updateQueue(request) { const { sessionId, itemId, action } = request.payload const agent = ctx.agents.get(sessionId) - if (agent === undefined || agent.updateInbox(itemId, action) === 'not-found') { + const queued = agent?.inbox.nextTurn + const index = queued?.findIndex(message => message.id === itemId) ?? -1 + const message = queued?.[index] + if (agent === undefined || message === undefined) { return Promise.resolve(err(request, { code: 'queue-item-not-found', message: 'queued item is no longer pending', details: { itemId }, })) } + if (action.kind === 'edit') { + agent.inbox.splice('next-turn', index, 1, [freezeMessage({ ...message, content: action.content })]) + } else { + agent.inbox.splice('next-turn', index, 1, []) + } return Promise.resolve(ok(request, { accepted: true as const })) }, @@ -1567,14 +1469,13 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro // Queue snapshot baseline (pendingQuestions precedent): frames replayed // in arrival order per session; a reconnecting client rebuilds its // queue view from these alone. - for (const [sessionId, items] of queuedMirror) { + for (const agent of ctx.agents.list()) { + const items = agent.inbox.nextTurn + if (items.length === 0) continue queue.push(frame({ type: 'session/queue', - sessionId, - items: items.map(item => ({ - id: item.id, - message: item.message, - })), + sessionId: agent.id, + items: [...items], })) } // Per-session open-call table for result-view pairing. Bounded by the diff --git a/packages/host/apiproxy/src/api/events.schema.ts b/packages/host/apiproxy/src/api/events.schema.ts index 4e17b1f403..040540d830 100644 --- a/packages/host/apiproxy/src/api/events.schema.ts +++ b/packages/host/apiproxy/src/api/events.schema.ts @@ -11,7 +11,7 @@ import type { Wire } from './rpc.schema.ts' import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts' import { approvalRequestIdSchema } from './approvals.schema.ts' import { - contentBlockSchema, inboxItemIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema, + contentBlockSchema, messageIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema, } from './sessions.schema.ts' import { workspaceIdSchema, workspaceViewSchema } from './workspace.schema.ts' @@ -25,10 +25,10 @@ export const askUserQuestionItemSchema = z.object({ multiSelect: z.boolean().optional(), }) satisfies z.ZodType> -/** Unified message envelope carried by transient queue frames. */ -const messageSchema = z.object({ - id: z.string().min(1), - role: z.union([z.literal('system'), z.literal('user'), z.literal('assistant')]), +/** User-message envelope carried by queue baselines. */ +const userMessageSchema = z.object({ + id: messageIdSchema, + role: z.literal('user'), content: z.array(contentBlockSchema), source: z.looseObject({ kind: z.string() }), }) @@ -47,10 +47,7 @@ export const muxFrameSchema = z.discriminatedUnion('type', [ z.object({ type: z.literal('session/queue'), sessionId: sessionIdSchema, - items: z.array(z.object({ - id: inboxItemIdSchema, - message: messageSchema, - })), + items: z.array(userMessageSchema), }), // value stays wide: it already passed its unit's own schema on the host, // and deep-validating here would import every domain's schema into the carrier. diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts index ad541b4e4d..859f4e1bc2 100644 --- a/packages/host/apiproxy/src/api/events.ts +++ b/packages/host/apiproxy/src/api/events.ts @@ -8,9 +8,8 @@ import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types' import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types' -import type { Message } from '@deepseek-ai/dsh-llm/types' -import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand' import type { CallId } from '@deepseek-ai/dsh-llm/brand' +import type { UserMessage } from '@deepseek-ai/dsh-llm/message' import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types' import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation' import type { RpcError, RpcId, RpcRequest } from './rpc.ts' @@ -32,14 +31,6 @@ export type ToolEventView = | { for: 'call'; view: ToolCallView } | { for: 'result'; view: ToolResultView } -/** One pending queued occurrence in an authoritative queue snapshot. */ -export interface QueuedInboxItem { - /** Agent-owned occurrence identity used by queue mutations. */ - id: InboxItemId - /** Complete pending message; it is not durable until the Agent claims it. */ - message: Message -} - /** Streaming face of the contract: the two SSE stream openers (mux + host). */ export interface EventsApi { /** @@ -71,13 +62,11 @@ export type MuxFrame = | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] } | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' } /** - * Complete transient queue state after every enqueue, mutation, claim, or - * discard. Pending work is not model-visible and therefore has no durable - * session event; the whole snapshot makes edit, deletion, cancel, and - * reconnect converge through one authoritative signal. Pending steering is - * outside this Web queue projection. + * Complete next-turn queue baseline emitted when a mux stream opens. Live + * mutations arrive through durable `agent/inbox/spliced` session events. + * Pending next-step input is outside this Web queue projection. */ - | { type: 'session/queue'; sessionId: SessionId; items: QueuedInboxItem[] } + | { type: 'session/queue'; sessionId: SessionId; items: UserMessage[] } /** * One projection unit's finished value changed (session-projection RFC). * Live push state, never logged — replay recomputes on the host (the diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts index 0372c8cc30..a89f6db2ea 100644 --- a/packages/host/apiproxy/src/api/index.ts +++ b/packages/host/apiproxy/src/api/index.ts @@ -35,7 +35,7 @@ export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts' export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts' export type { CommandsApi, CommandDescriptor } from './commands.ts' export type { SkillsApi, SkillEntry } from './skills.ts' -export type { EventsApi, MuxFrame, HostFrame, QueuedInboxItem, ToolCallView, ToolEventView, ToolResultView } from './events.ts' +export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts' export type { GoalsApi, GoalId, GoalRef } from './goals.ts' export type { ApprovalResponsePayload } from './approvals.ts' export type { QuestionResponsePayload } from './questions.ts' @@ -56,7 +56,5 @@ export type { // ---- Errors and ids ---- export { RpcId, transportError } from './rpc.ts' export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts' -export type { InboxItemId } from '@deepseek-ai/dsh-agent/brand' - // ---- Method registry and derived generics ---- export type { RequestPayload, ResponseValue, RpcMethodMap } from './rpc-map.ts' diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts index c1fa4e1611..2c27ee16f2 100644 --- a/packages/host/apiproxy/src/api/rpc.ts +++ b/packages/host/apiproxy/src/api/rpc.ts @@ -8,8 +8,8 @@ import type { z as zCore } from 'zod' type ZodIssue = zCore.core.$ZodIssue import type { Branded } from '@deepseek-ai/dsh-brand' +import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand' /** * Message correlation id: the initiator mints it on a request; a response @@ -45,7 +45,7 @@ export interface RpcErrorDetailsMap { 'directory-create-failed': { path: string } 'directory-picker-unavailable': { capability: string } 'agent-busy': { reason: string } - 'queue-item-not-found': { itemId: InboxItemId } + 'queue-item-not-found': { itemId: MessageId } /** A known slash command reported a usage/state error; the message is the command's own text. */ 'command-error': {} /** A leading-/ prompt named no registered command; the message names the token. */ diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts index e3744ec37a..6b64b80d81 100644 --- a/packages/host/apiproxy/src/api/sessions.schema.ts +++ b/packages/host/apiproxy/src/api/sessions.schema.ts @@ -7,7 +7,7 @@ import { z } from 'zod' import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types' -import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand' +import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { RequestPayload, ResponseValue } from './rpc-map.ts' import type { Wire } from './rpc.schema.ts' import type { @@ -20,8 +20,8 @@ import type { WorkspaceId } from './workspace.ts' /** SessionId: one brand cast after shape validation (the only cast point in this domain). */ export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType -/** InboxItemId: one brand cast after non-empty string validation. */ -export const inboxItemIdSchema = z.string().min(1) as unknown as z.ZodType +/** MessageId: one brand cast after non-empty string validation. */ +export const messageIdSchema = z.string().min(1) as unknown as z.ZodType /** * WorkspaceId: the workspace domain's one brand cast. Hosted here rather @@ -221,7 +221,7 @@ export const sessionPromptValueSchema = z.object({ /** session.updateQueue request payload. */ export const sessionUpdateQueueRequestSchema = z.object({ sessionId: sessionIdSchema, - itemId: inboxItemIdSchema, + itemId: messageIdSchema, action: z.discriminatedUnion('kind', [ z.object({ kind: z.literal('edit'), content: z.array(contentBlockSchema) }), z.object({ kind: z.literal('remove') }), diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts index a57c3f4b73..eac40ffbf3 100644 --- a/packages/host/apiproxy/src/api/sessions.ts +++ b/packages/host/apiproxy/src/api/sessions.ts @@ -4,8 +4,8 @@ * else references RequestPayload<'session.*'> / ResponseValue<'session.*'>. */ +import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' -import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand' import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types' // The pure-type outlet: api/ is browser-importable, and the package root's // cordis Context merge (via dsh-agent) must not enter client aggregates. @@ -238,7 +238,7 @@ export interface SessionsApi { /** * Edits or removes one pending queued occurrence. */ - updateQueue(request: RpcRequest<{ sessionId: SessionId; itemId: InboxItemId; action: QueueAction }>): + updateQueue(request: RpcRequest<{ sessionId: SessionId; itemId: MessageId; action: QueueAction }>): Promise> /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */ diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts index 6df71258be..73a3a793e6 100644 --- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts @@ -11,8 +11,8 @@ import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import AgentRegistry, { InboxItemId } from '@deepseek-ai/dsh-agent' -import type { Agent, InboxItem, InboxPlacement } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' import SessionStore from '@deepseek-ai/dsh-session' import type { SessionId, UserMessage } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' @@ -63,7 +63,14 @@ async function harness(options: { commands?: boolean; skills?: boolean } = {}): /** Register a live structural agent stub (api-proxy-view precedent: only id/session/status/ctx are read). */ function stubAgent(ctx: Context, sessionId?: SessionId): Agent { const session = ctx.sessions.create(sessionId) - const agent = { id: session.id, session, status: 'idle', ctx } as Agent + const inbox = new Inbox(session) + const agent = { + id: session.id, + session, + inbox, + status: 'idle', + ctx, + } as Agent ctx.agents.register(agent) return agent } @@ -264,7 +271,7 @@ describe('host/commands-changed frame', () => { }) }) -/** Build one frozen inbox message for the live `agent/inbox/*` events. */ +/** Build one frozen inbox message. */ function inboxMessage(id: string, text: string, rpcId?: string): UserMessage { return freezeMessage({ id: MessageId(id), @@ -274,27 +281,19 @@ function inboxMessage(id: string, text: string, rpcId?: string): UserMessage { }) } -/** Build one addressable inbox occurrence around a frozen message. */ -function inboxItem(id: string, message: UserMessage, placement: InboxPlacement): InboxItem { - return { id: InboxItemId(id), message, placement } -} - describe('session.updateQueue', () => { - it('routes an addressable action and reports a lost claim race', async () => { + it('splices a queued message and reports a lost claim race', async () => { const ctx = await harness() const agent = stubAgent(ctx) - const seen: unknown[] = [] - agent.updateInbox = (id, action) => { - seen.push({ id, action }) - return id === InboxItemId('present') ? 'applied' : 'not-found' - } + const present = inboxMessage('present', 'before') + agent.inbox.splice('next-turn', 0, 0, [present]) const api = createApiProxy(ctx, DEFAULTS) const applied = await api.sessions.updateQueue({ rpcId: RpcId('q-apply'), payload: { sessionId: agent.id, - itemId: InboxItemId('present'), + itemId: MessageId('present'), action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] }, }, }) @@ -303,15 +302,15 @@ describe('session.updateQueue', () => { rpcId: RpcId('q-missing'), payload: { sessionId: agent.id, - itemId: InboxItemId('claimed'), + itemId: MessageId('claimed'), action: { kind: 'remove' }, }, }) expect(expectErr(missing)).toMatchObject({ code: 'queue-item-not-found' }) - expect(seen).toEqual([ - { id: 'present', action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] } }, - { id: 'claimed', action: { kind: 'remove' } }, - ]) + expect(agent.inbox.nextTurn[0]).toMatchObject({ + id: 'present', + content: [{ type: 'text', text: 'edited' }], + }) }) it('rejects a stale occurrence without resuming a cold agent', async () => { @@ -322,7 +321,7 @@ describe('session.updateQueue', () => { rpcId: RpcId('q-cold'), payload: { sessionId: 'cold-session' as SessionId, - itemId: InboxItemId('stale-item'), + itemId: MessageId('stale-item'), action: { kind: 'remove' }, }, }) @@ -333,100 +332,24 @@ describe('session.updateQueue', () => { }) describe('session/queue frames', () => { - it('folds nested mutations observed before their outer enqueue', async () => { - const ctx = await harness() - const agent = stubAgent(ctx) - const original = inboxItem('i-edit', inboxMessage('m-edit', 'before'), 'queued') - const edited = inboxItem('i-edit', inboxMessage('m-edit', 'after'), 'queued') - const removed = inboxItem('i-remove', inboxMessage('m-remove', 'remove me'), 'queued') - ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject !== agent) return - if (item.id === original.id) ctx.emit('agent/inbox/update', agent, edited) - if (item.id === removed.id) ctx.emit('agent/inbox/discard', agent, [removed]) - }) - const api = createApiProxy(ctx, DEFAULTS) - const live = new AbortController() - const collected = collect( - api.events.mux({ rpcId: RpcId('t-mux-reentrant'), payload: {} }, live.signal), 2, live) - - ctx.emit('agent/inbox/enqueue', agent, original) - ctx.emit('agent/inbox/enqueue', agent, removed) - - const liveFrames = (await collected).filter(frame => frame.type === 'session/queue') - expect(liveFrames.map(frame => frame.items)).toEqual([ - [{ id: edited.id, message: edited.message }], - ]) - const replay = new AbortController() - const replayFrames = await collect( - api.events.mux({ rpcId: RpcId('t-mux-reentrant-replay'), payload: {} }, replay.signal), 2, replay) - expect(replayFrames.filter(frame => frame.type === 'session/queue')).toEqual(liveFrames) - }) - - it('publishes complete live snapshots and replays the latest snapshot on reconnect', async () => { + it('publishes the durable next-turn baseline without duplicating message identity', async () => { const ctx = await harness() const api = createApiProxy(ctx, DEFAULTS) const agent = stubAgent(ctx) - const live = new AbortController() - const liveStream = api.events.mux({ rpcId: RpcId('t-mux-live'), payload: {} }, live.signal) - // subscribed baseline + one queued snapshot; pending steering stays off this wire. - const liveCollected = collect(liveStream, 2, live) - - const queued = inboxItem('i-1', inboxMessage('m-1', 'queued prompt'), 'queued') - const steering = inboxItem('i-2', inboxMessage('m-2', 'steering prompt'), 'steering') - ctx.emit('agent/inbox/enqueue', agent, queued) - ctx.emit('agent/inbox/enqueue', agent, steering) - - const liveFrames = (await liveCollected).filter(f => f.type === 'session/queue') - expect(liveFrames).toEqual([ - { - type: 'session/queue', - sessionId: agent.id, - items: [{ id: queued.id, message: queued.message }], - }, - ]) - - // A fresh mux connection replays only the current authoritative snapshot. - const replay = new AbortController() - const replayFrames = await collect( - api.events.mux({ rpcId: RpcId('t-mux-replay'), payload: {} }, replay.signal), 2, replay) - expect(replayFrames.filter(f => f.type === 'session/queue')).toEqual([liveFrames[0]]) - }) - - it('publishes edits in place in the authoritative order', async () => { - const ctx = await harness() - const api = createApiProxy(ctx, DEFAULTS) - const agent = stubAgent(ctx) - const abort = new AbortController() - const collected = collect( - api.events.mux({ rpcId: RpcId('t-mux-updates'), payload: {} }, abort.signal), 5, abort) - const first = inboxItem('i-a', inboxMessage('m-a', 'a'), 'queued') - const second = inboxItem('i-b', inboxMessage('m-b', 'b'), 'queued') - const edited = inboxItem('i-b', inboxMessage('m-b', 'b edited'), 'queued') - ctx.emit('agent/inbox/enqueue', agent, first) - ctx.emit('agent/inbox/enqueue', agent, second) - ctx.emit('agent/inbox/update', agent, edited) - ctx.emit('agent/inbox/dequeue', agent, edited) - - const frames = (await collected).filter(frame => frame.type === 'session/queue') - expect(frames.map(frame => frame.items)).toEqual([ - [{ id: first.id, message: first.message }], - [{ id: first.id, message: first.message }, { id: second.id, message: second.message }], - [{ id: first.id, message: first.message }, { id: edited.id, message: edited.message }], - [{ id: first.id, message: first.message }], - ]) - }) - - it('publishes an empty snapshot after terminal discard', async () => { - const ctx = await harness() - const api = createApiProxy(ctx, DEFAULTS) - const agent = stubAgent(ctx) - const doomed = inboxItem('i-doomed', inboxMessage('m-5', 'doomed'), 'queued') - ctx.emit('agent/inbox/enqueue', agent, doomed) - ctx.emit('agent/inbox/discard', agent, [doomed]) + const queued = inboxMessage('m-1', 'queued prompt') + const steering = inboxMessage('m-2', 'steering prompt') + agent.inbox.splice('next-turn', 0, 0, [queued]) + agent.inbox.splice('next-step', 0, 0, [steering]) const abort = new AbortController() const frames = await collect( - api.events.mux({ rpcId: RpcId('t-mux-swept'), payload: {} }, abort.signal), 1, abort) - expect(frames.filter(frame => frame.type === 'session/queue')).toHaveLength(0) + api.events.mux({ rpcId: RpcId('t-mux-baseline'), payload: {} }, abort.signal), 2, abort) + expect(frames.filter(frame => frame.type === 'session/queue')).toEqual([ + { + type: 'session/queue', + sessionId: agent.id, + items: [queued], + }, + ]) }) }) diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts index 103ea25bc1..52e40decdc 100644 --- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts @@ -45,10 +45,7 @@ function stubAgent(session: Session): Agent { options: {}, session, status: 'idle', - acceptsNextStep: false, ctx: new Context(), - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts index 80cd0baf4c..9d97501e74 100644 --- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts +++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts @@ -380,7 +380,7 @@ describe('events frame schemas', () => { { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] }, { type: 'question/resolved', sessionId: 's', questionRpcId: 'r', outcome: 'answered' }, { type: 'session/queue', sessionId: 's', items: [ - { id: 'i1', message: { id: 'm1', role: 'user', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' } } }, + { id: 'm1', role: 'user', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' } }, ] }, { type: 'session/projection', sessionId: 's', key: 'todos', value: [{ content: 'x', status: 'pending' }], seq: 7 }, { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } }, @@ -401,8 +401,8 @@ describe('events frame schemas', () => { it('rejects a queue snapshot with malformed items', () => { expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: 'x' })).toThrow() - expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: '', message: {} }] })).toThrow() - expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: 'i', message: { id: 'm', role: 'user', content: [], source: {} } }] })).toThrow() + expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: '', role: 'user', content: [], source: { kind: 'user' } }] })).toThrow() + expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: 'm', role: 'assistant', content: [], source: { kind: 'user' } }] })).toThrow() }) it('accepts every host frame branch', () => { diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts index 7b87fe6b10..3976e586cb 100644 --- a/packages/pty/pty-local/tests/index.spec.ts +++ b/packages/pty/pty-local/tests/index.spec.ts @@ -41,8 +41,8 @@ function config(): ResolvedConfig { function agent(ctx: Context): Agent { const id = SessionId('agent') return { - id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id, options: {}, session: new Session(id), status: 'idle', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } @@ -248,8 +248,8 @@ describe('pty-local plugin shape', () => { const session = ctx.sessions.create(SessionId('mode-owner')) const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { - id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession()) @@ -291,8 +291,8 @@ describe('pty-local plugin shape', () => { const session = ctx.sessions.create(SessionId('pending-mode-owner')) const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { - id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) const gate = Promise.withResolvers() diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts index c3fb33c75c..c2cb23cb59 100644 --- a/packages/pty/pty-local/tests/local.spec.ts +++ b/packages/pty/pty-local/tests/local.spec.ts @@ -34,8 +34,8 @@ function stubAgent(ctx: Context, rawId: string): Agent { const id = SessionId(rawId) const scope = ctx.plugin(() => {}) return { - id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } diff --git a/packages/pty/pty/tests/service.spec.ts b/packages/pty/pty/tests/service.spec.ts index ba0996841c..cf5c4f0bab 100644 --- a/packages/pty/pty/tests/service.spec.ts +++ b/packages/pty/pty/tests/service.spec.ts @@ -26,10 +26,7 @@ function stubAgent(ctx: Context, rawId: string): Agent { options: {}, session: new Session(id), status: 'idle', - acceptsNextStep: false, ctx: scopeFiber.ctx, - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts index f6ad1084c6..da8555e4c8 100644 --- a/packages/pty/tool-pty/tests/loader-composition.spec.ts +++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts @@ -39,8 +39,8 @@ function agent(ctx: Context): Agent { const scope = ctx.plugin(() => {}) const id = SessionId('pty-loader-agent') const value: Agent = { - id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(value) return value diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts index a09fcac714..ed9a41d370 100644 --- a/packages/pty/tool-pty/tests/tools.spec.ts +++ b/packages/pty/tool-pty/tests/tools.spec.ts @@ -17,8 +17,8 @@ function fakeAgent(ctx: Context, rawId: string): Agent { const scope = ctx.plugin(() => {}) const id = SessionId(rawId) const agent: Agent = { - id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(agent) return agent diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts index e866805a2d..98ae51e38a 100644 --- a/packages/skill/tool-skill/tests/tool-skill.spec.ts +++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts @@ -45,9 +45,6 @@ function agentForCwd(cwd: string): Agent { options: {}, session, status: 'idle', - acceptsNextStep: false, - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { @@ -64,10 +61,7 @@ function sessionAgent(session: Session, id = 'tool-skill-agent'): Agent { options: {}, session, status: 'running', - acceptsNextStep: false, ctx: new Context(), - send: () => {}, - updateInbox: () => 'not-found', followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts index 2d6338701d..f13c68cfa1 100644 --- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts +++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts @@ -200,10 +200,14 @@ describe('dsh-subagent-spawn', () => { expect(published).toEqual([]) }) - it('a cancel from agent/inbox/enqueue maps a no-turn child log to aborted', async () => { + it('a cancel after the child prompt is queued maps a no-turn child log to aborted', async () => { const { ctx, parent } = await setup([]) const controller = new AbortController() - ctx.on('agent/inbox/enqueue', () => { controller.abort('queued-window') }) + ctx.on('session/event', (_session, event) => { + if (event.type === 'agent/inbox/spliced' && event.data.inserted.length > 0) { + queueMicrotask(() => { controller.abort('queued-window') }) + } + }) const run = await start(ctx, 'spawn', { prompt: [{ type: 'text', text: 'p' }], parent, signal: controller.signal }) const result = await run.result expect(result).toMatchObject({ stopReason: 'aborted', output: [] }) diff --git a/packages/tasks/tasks-local/tests/tasks.spec.ts b/packages/tasks/tasks-local/tests/tasks.spec.ts index 555eb6146a..5cf11732cf 100644 --- a/packages/tasks/tasks-local/tests/tasks.spec.ts +++ b/packages/tasks/tasks-local/tests/tasks.spec.ts @@ -23,10 +23,7 @@ function stubAgent(ctx: Context, rawId: string): Agent { options: {}, session: new Session(id), status: 'idle' as const, - acceptsNextStep: false, ctx: scopeFiber.ctx, - send: () => {}, - updateInbox: (): 'not-found' => 'not-found', followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 8c5322f8e6..de8288d71d 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -1198,7 +1198,7 @@ export function createTuiChat( appendNotice(`Agent "${agent.id}" is disposed.`, 'error') return } - if (agent.acceptsNextStep) { + if (agent.status === 'running') { // Steering is never subject to prompt admission; an attached snapshot // drains beside it at the same step boundary through the outbox. if (attachedContext !== undefined) { diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts index 6be1183d78..a6a22ec2d9 100644 --- a/packages/ui/tui/tests/harness.ts +++ b/packages/ui/tui/tests/harness.ts @@ -36,8 +36,6 @@ interface FakeAgent extends Agent { export interface TuiHarnessOptions { status?: AgentStatus - /** Override the fake agent's next-step capability independently of status. */ - acceptsNextStep?: boolean config?: Config /** Leave the session event log empty instead of seeding one turn and step. */ omitInitialLifecycle?: boolean @@ -193,9 +191,6 @@ export async function createTuiTestHarness 'not-found', followup(input) { sent.push(input.content) sentMessages.push(input) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index e18c96c4db..0979714468 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -2636,45 +2636,6 @@ describe('pi-tui chat lifecycle and transcript', () => { await dispose(result) }) - it('keeps a referenced prompt on admission when running no longer accepts next-step input', async () => { - const result = await setup({ - status: 'running', - acceptsNextStep: false, - omitInitialLifecycle: true, - async configureContext(ctx) { - ctx.provide('tools', { get: () => undefined } as never) - await ctx.plugin(TestSessionQueryService) - await ctx.plugin(SessionReferenceService) - const source = ctx.sessions.create(SessionId('admission-src'), { - meta: { cwd: process.cwd(), createdAt: 1 }, - }) - appendUser(source, 'source background') - source.append('session/title', { - title: 'Admission source', - messageSeqs: [0], - source: { kind: 'fallback' }, - }) - }, - }) - - result.terminal.send(formatSessionReferenceMention({ - sessionId: SessionId('admission-src'), - label: 'Admission source', - })) - result.terminal.send('\r') - await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(1) }) - - expect(result.agent.steered).toHaveLength(0) - expect(result.agent.injected).toHaveLength(0) - const decision = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages[0]!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), - ) - expect(decision.kind === 'allow' && decision.additionalContexts?.[0]?.source) - .toMatchObject({ kind: 'session-reference', references: [{ sessionId: 'admission-src' }] }) - await dispose(result) - }) - it('releases the reference-admission wrapper on the ordinary allowed path', async () => { const result = await setup({ async configureContext(ctx) { @@ -4974,8 +4935,8 @@ describe('terminal mounting', () => { ctx.provide('tools', { get: () => undefined } as never) const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ - id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'idle', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() mountTui(ctx, { theme: { color: false } }, { terminal, exit: vi.fn() }) @@ -4999,8 +4960,8 @@ describe('terminal mounting', () => { ctx.provide('tools', { get: () => undefined } as never) const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ - id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'idle', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() // Mirror dsh-tui's own inject (minus loader, the absence under test). @@ -5034,15 +4995,15 @@ describe('terminal mounting', () => { const otherSession = ctx.sessions.create(SessionId('other-session')) ctx.agents.register({ - id: otherSession.id, options: {}, session: otherSession, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: otherSession.id, options: {}, session: otherSession, status: 'idle', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) expect(terminal.started).toBe(0) const session = ctx.sessions.create(SessionId('late-session')) const agent = { - id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'idle', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } as Agent ctx.agents.register(agent) await tick() @@ -5072,8 +5033,8 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main-session')) ctx.agents.register({ - id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'idle', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) await tick() expect(terminal.started).toBe(0) @@ -5116,8 +5077,8 @@ describe('terminal mounting', () => { session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) ctx.agents.register({ - id: session.id, options: {}, session, status: 'running', acceptsNextStep: true, ctx, - followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), + id: session.id, options: {}, session, status: 'running', ctx, + followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() terminal.start = () => { throw new Error('terminal startup failed') } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 61930c815d..58228736c6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2048,9 +2048,6 @@ importers: packages/core/agent: devDependencies: - '@deepseek-ai/dsh-brand': - specifier: workspace:^ - version: link:../../util/brand '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../support/invariants From 9af9222871ead15b64871b8d57e7dba3f351c9bf Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 30 Jul 2026 15:35:21 +0800 Subject: [PATCH 010/689] test(tui): stabilize workdir snapshot output --- .../source-checkout-workdir/terminal.expected.txt | 4 ++-- examples/tui-agent/tests/tui.snapshot.ts | 11 +++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt b/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt index 81103c12bd..b9ecb5a553 100644 --- a/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt +++ b/examples/tui-agent/tests/snapshots/source-checkout-workdir/terminal.expected.txt @@ -26,8 +26,8 @@ buffer style 0-46 fg=green 12| "$ pwd " style 0-4 dim -13| "/workspace/project " - style 0-59 dim +13| "/workspace/project " + style 0-17 dim 14| "[exit 0] " style 0-7 dim 15| "Model wait 0.0s · Completed 2026-07-21 12:00:00 " diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts index b96aaaf691..81cdfd6f22 100644 --- a/examples/tui-agent/tests/tui.snapshot.ts +++ b/examples/tui-agent/tests/tui.snapshot.ts @@ -56,6 +56,8 @@ interface Scenario { seedWorkspace?: boolean /** Add the launcher's model-visible DSH source checkout at this fixed path. */ harnessSourceRoot?: string + /** Replace the real `pwd` result with a portable fixed-length workspace path. */ + normalizePwdResult?: boolean /** * Load the opt-in `todo_write` tool for this scenario. The shipped tui-agent * config omits it, so only the todo-plan scenario (the enabled-path proof) @@ -103,6 +105,7 @@ const SCENARIOS: Scenario[] = [ expectedTools: ['bash'], recorded: true, harnessSourceRoot: '/opt/dsh-source', + normalizePwdResult: true, }, { name: 'parallel-file-reads', @@ -323,6 +326,14 @@ async function runScenario(scenario: Scenario): Promise { await cp(source, cwd, { recursive: true }) } ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles, replayRoot) + if (scenario.normalizePwdResult === true) { + ctx.on('tools/post-execute', async (exec, result, next) => { + const args = exec.arguments as { command?: unknown } + return exec.name === 'bash' && args.command === 'pwd' && !result.isError + ? { kind: 'accept', content: [{ type: 'text', text: '/workspace/project\n' }] } + : next() + }) + } const disposedSessions: Session[] = [] ctx.on('session/disposed', (session) => { disposedSessions.push(session) }) const workflowEvents: string[] = [] From 7401587ac26e5b15774c24c263db90206e6c400b Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 01:12:48 -0700 Subject: [PATCH 011/689] fix(ui-workspace): show approval-waiting sessions --- packages/client/ui-workspace/README.i18n.yaml | 4 +-- packages/client/ui-workspace/README.md | 2 ++ packages/client/ui-workspace/README.zh.md | 2 ++ .../ui-workspace/src/client/rows/Rows.tsx | 17 ++++++--- .../client/ui-workspace/src/client/tree.ts | 3 ++ .../client/ui-workspace/tests/rows.spec.tsx | 36 +++++++++++++++---- .../client/ui-workspace/tests/tree.spec.ts | 8 +++++ 7 files changed, 59 insertions(+), 13 deletions(-) diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml index 536911a16a..bada1e738d 100644 --- a/packages/client/ui-workspace/README.i18n.yaml +++ b/packages/client/ui-workspace/README.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 packages/client/ui-workspace/README.md -README.md: a1b58f4abe0925be3b426d10344777e46caa9ba0 -README.zh.md: a472507bc45549c8feb55a75d294cbd7b3138cc5 +README.md: 1497f816a295e2cd156af9b779bce0b42759e1c7 +README.zh.md: be496412db9790b0625b40f0bbb06c1d406af015 diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md index a1b58f4abe..1497f816a2 100644 --- a/packages/client/ui-workspace/README.md +++ b/packages/client/ui-workspace/README.md @@ -6,6 +6,8 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration. +Session rows project the runtime's live `waitingApproval` fact: an amber warning dot takes precedence over the blue running indicator, and the hover card reports **Waiting for approval** until the request is resolved. Running and idle presentation is unchanged when no approval is pending. + Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored. ## Model Experience diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md index a472507bc4..be496412db 100644 --- a/packages/client/ui-workspace/README.zh.md +++ b/packages/client/ui-workspace/README.zh.md @@ -6,6 +6,8 @@ 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。 +Session 行会投影 runtime 的实时 `waitingApproval` 状态：琥珀色警告点优先于蓝色运行指示器，hover 卡片在请求解决前显示 **Waiting for approval**。没有待审批请求时，运行与空闲展示保持不变。 + 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。 ## 模型体验 diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx index d75fabdd8b..4f823d531f 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.tsx +++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx @@ -121,15 +121,23 @@ export function ProjectRowItem({ group, onToggle, onCreate, actions }: { * @param props.onToggle - unfold/fold a subtree by id. * @returns the node's row followed by its children. */ -/** Hover-card body: full title, relative time, and the status line (running/idle until wire status lands). */ +/** Session status presentation; approval waiting outranks the underlying running state. */ +function sessionStatus(node: SessionNode): { state: 'warning' | 'ongoing' | 'done'; label: string } { + if (node.waitingApproval) return { state: 'warning', label: 'Waiting for approval' } + if (node.running) return { state: 'ongoing', label: 'Running' } + return { state: 'done', label: 'Idle' } +} + +/** Hover-card body: full title, relative time, and approval/running/idle status. */ function SessionHoverContent({ node, now }: { node: SessionNode; now: number }) { + const status = sessionStatus(node) return (
{node.title}
{`${formatRelativeTime(node.updatedAt, now)} ago`}
- - {node.running ? 'Running' : 'Idle'} + + {status.label}
) @@ -175,6 +183,7 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, }) { const row = node const selected = node.id === currentId + const status = sessionStatus(node) const [menuOpen, setMenuOpen] = useState(false) // Rail (figma session cell: pad 8, twist slot 16, status slot 16, gap 4 to // the title): both slots are always reserved so titles align whether or not @@ -226,7 +235,7 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, ) : null} - {row.running && } + {(row.waitingApproval || row.running) && } {row.title} {formatRelativeTime(row.updatedAt, now)} diff --git a/packages/client/ui-workspace/src/client/tree.ts b/packages/client/ui-workspace/src/client/tree.ts index c0adfadd6f..af2c6cd051 100644 --- a/packages/client/ui-workspace/src/client/tree.ts +++ b/packages/client/ui-workspace/src/client/tree.ts @@ -20,6 +20,8 @@ export interface SessionNode { /** The session HAS children in the data (the twist renders even while folded). */ hasChildren: boolean expanded: boolean + /** A pending approval takes display precedence over the running state. */ + waitingApproval: boolean running: boolean updatedAt: number } @@ -183,6 +185,7 @@ function sessionNode(s: SessionSummary, children: readonly SessionNode[], hasChi children, hasChildren, expanded, + waitingApproval: s.waitingApproval, running: s.running, updatedAt: s.updatedAt, } diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx index bfaa8a36dd..0b6837c0bc 100644 --- a/packages/client/ui-workspace/tests/rows.spec.tsx +++ b/packages/client/ui-workspace/tests/rows.spec.tsx @@ -59,11 +59,11 @@ describe('workspace browser rows', () => { it('renders and operates selected, running, recursive Session nodes', () => { const child: SessionNode = { id: sid('child'), title: 'Child', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + expanded: false, waitingApproval: false, running: false, updatedAt: 0, } const parent: SessionNode = { id: sid('parent'), title: 'Parent', children: [child], hasChildren: true, - expanded: true, running: true, updatedAt: 0, + expanded: true, waitingApproval: false, running: true, updatedAt: 0, } const onOpen = vi.fn() const onToggle = vi.fn() @@ -142,7 +142,7 @@ describe('workspace browser rows', () => { const onRename = vi.fn() const node: SessionNode = { id: sid('s1'), title: 'One', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + expanded: false, waitingApproval: false, running: false, updatedAt: 0, } render() @@ -169,7 +169,7 @@ describe('workspace browser rows', () => { it('flat variant renders no twist even for a parent and ignores toggling', () => { const node: SessionNode = { id: sid('p'), title: 'Parent', children: [], hasChildren: true, - expanded: false, running: false, updatedAt: 0, + expanded: false, waitingApproval: false, running: false, updatedAt: 0, } render() @@ -181,7 +181,7 @@ describe('workspace browser rows', () => { try { const node: SessionNode = { id: sid('s1'), title: 'Hovered', children: [], hasChildren: false, - expanded: false, running: true, updatedAt: 0, + expanded: false, waitingApproval: false, running: true, updatedAt: 0, } render() @@ -203,12 +203,34 @@ describe('workspace browser rows', () => { } }) + it('shows approval waiting as warning ahead of the running state', () => { + vi.useFakeTimers() + try { + const node: SessionNode = { + id: sid('approval'), title: 'Needs approval', children: [], hasChildren: false, + expanded: false, waitingApproval: true, running: true, updatedAt: 0, + } + render() + const row = screen.getByRole('treeitem') + expect(row.querySelector('[data-state="warning"]')).toBeTruthy() + expect(row.querySelector('[data-state="ongoing"]')).toBeNull() + + fireEvent.pointerEnter(row.parentElement as HTMLElement) + act(() => { vi.advanceTimersByTime(500) }) + expect(screen.getByText('Waiting for approval')).toBeTruthy() + expect(document.querySelectorAll('[data-state="warning"]')).toHaveLength(2) + } finally { + vi.useRealTimers() + } + }) + it('idle hover card shows the Idle status line', () => { vi.useFakeTimers() try { const node: SessionNode = { id: sid('s1'), title: 'Quiet', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + expanded: false, waitingApproval: false, running: false, updatedAt: 0, } render() @@ -224,7 +246,7 @@ describe('workspace browser rows', () => { it('draggable row wires start/end and gates hover/drop on an active same-group drag', () => { const node: SessionNode = { id: sid('s1'), title: 'Drag me', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + expanded: false, waitingApproval: false, running: false, updatedAt: 0, } const inactive = dragProps() const { rerender } = render( diff --git a/packages/client/ui-workspace/tests/tree.spec.ts b/packages/client/ui-workspace/tests/tree.spec.ts index eb34f633d8..2af6c1a6ab 100644 --- a/packages/client/ui-workspace/tests/tree.spec.ts +++ b/packages/client/ui-workspace/tests/tree.spec.ts @@ -33,6 +33,14 @@ describe('deriveGroups', () => { expect(groups[0]!.sessions.map(session => session.id)).toEqual([sid('older'), sid('newer')]) }) + it('projects approval-waiting state into grouped and flat rows', () => { + const awaiting = { ...summary('awaiting', 10), waitingApproval: true, running: true } + const sessions = list(awaiting) + const grouped = deriveGroups(sessions, [workspace('project', ['awaiting'])], view(['project'])) + expect(grouped[0]!.sessions[0]).toMatchObject({ waitingApproval: true, running: true }) + expect(deriveFlat(sessions, { query: '' })[0]).toMatchObject({ waitingApproval: true, running: true }) + }) + it('puts only real unaccounted Sessions in the trailing Ungrouped group', () => { const sessions = list(summary('owned', 1, '/projects/first'), summary('loose', 9, '/other')) const groups = deriveGroups(sessions, [workspace('first', ['owned'])], view([UNGROUPED_KEY])) From a6baddaaacb8acd0bfcbd6c28827310393fe8c54 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 16:48:28 +0800 Subject: [PATCH 012/689] refactor: remove per-followup result attribution --- ...-followup-enqueue-and-owned-runs.i18n.yaml | 6 + ...6-07-30-followup-enqueue-and-owned-runs.md | 43 +++++ ...7-30-followup-enqueue-and-owned-runs.zh.md | 43 +++++ docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 4 +- docs/cookbook/extension-cookbook.i18n.yaml | 4 +- docs/cookbook/extension-cookbook.md | 5 +- docs/cookbook/extension-cookbook.zh.md | 5 +- docs/core-data-structures/core.i18n.yaml | 4 +- docs/core-data-structures/core.md | 168 ++++-------------- docs/core-data-structures/core.zh.md | 168 ++++-------------- docs/core-data-structures/session.i18n.yaml | 4 +- docs/core-data-structures/session.md | 47 ++--- docs/core-data-structures/session.zh.md | 47 ++--- docs/defensive-patterns.i18n.yaml | 4 +- docs/defensive-patterns.md | 2 +- docs/defensive-patterns.zh.md | 2 +- docs/persistence-catalog.md | 55 ++++-- packages/acp/acp/README.i18n.yaml | 4 +- packages/acp/acp/README.md | 4 +- packages/acp/acp/README.zh.md | 4 +- packages/acp/acp/src/codec.ts | 25 +-- packages/acp/acp/src/index.ts | 121 +++---------- packages/core/agent/README.i18n.yaml | 4 +- packages/core/agent/README.md | 22 ++- packages/core/agent/README.zh.md | 22 ++- packages/core/session/README.i18n.yaml | 4 +- packages/core/session/README.md | 6 +- packages/core/session/README.zh.md | 6 +- packages/examples/cli-demo/README.i18n.yaml | 4 +- packages/examples/cli-demo/README.md | 16 +- packages/examples/cli-demo/README.zh.md | 16 +- packages/examples/cli-demo/src/cli.ts | 110 +++--------- packages/goal/goal-session/README.i18n.yaml | 4 +- packages/goal/goal-session/README.md | 21 +-- packages/goal/goal-session/README.zh.md | 21 +-- packages/goal/goal-session/src/index.ts | 103 +++-------- packages/goal/goal-session/src/outcome.ts | 53 ------ packages/sdk/sdk-client/README.i18n.yaml | 4 +- packages/sdk/sdk-client/README.md | 14 +- packages/sdk/sdk-client/README.zh.md | 14 +- packages/sdk/sdk-client/src/api.ts | 79 ++++---- packages/sdk/sdk-client/src/client.ts | 11 +- packages/sdk/sdk-client/src/index.ts | 4 +- packages/sdk/sdk-client/src/types.ts | 19 +- packages/sdk/sdk-client/tests/fake-runtime.ts | 25 +-- .../sdk/sdk-client/tests/sdk-client.spec.ts | 48 ++--- packages/sdk/sdk-protocol/README.i18n.yaml | 4 +- packages/sdk/sdk-protocol/README.md | 6 +- packages/sdk/sdk-protocol/README.zh.md | 6 +- packages/sdk/sdk-protocol/src/index.ts | 2 +- packages/sdk/sdk-protocol/src/types.ts | 22 ++- .../sdk/sdk-protocol/tests/transport.spec.ts | 4 +- .../subagent-dsh-sdk/README.i18n.yaml | 4 +- packages/subagent/subagent-dsh-sdk/README.md | 4 +- .../subagent/subagent-dsh-sdk/README.zh.md | 4 +- packages/subagent/subagent-dsh-sdk/src/run.ts | 9 +- .../subagent-inprocess/README.i18n.yaml | 4 +- .../subagent/subagent-inprocess/README.md | 4 +- .../subagent/subagent-inprocess/README.zh.md | 4 +- packages/ui/jsonrpc/README.i18n.yaml | 4 +- packages/ui/jsonrpc/README.md | 7 +- packages/ui/jsonrpc/README.zh.md | 7 +- packages/ui/jsonrpc/src/server.ts | 39 ++-- python/sdk/README.i18n.yaml | 4 +- python/sdk/README.md | 4 +- python/sdk/README.zh.md | 4 +- python/sdk/src/deepseek_harness/__init__.py | 4 +- python/sdk/src/deepseek_harness/api.py | 45 +++-- python/sdk/src/deepseek_harness/client.py | 9 +- scripts/type-equiv.manifest.json | 36 +--- 72 files changed, 586 insertions(+), 1059 deletions(-) create mode 100644 .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml create mode 100644 .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md create mode 100644 .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md delete mode 100644 packages/goal/goal-session/src/outcome.ts diff --git a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml new file mode 100644 index 0000000000..1027cfb0f0 --- /dev/null +++ b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md +2026-07-30-followup-enqueue-and-owned-runs.md: 73dfb501cb5c18a7a9219861eba37e73499af5e0 +2026-07-30-followup-enqueue-and-owned-runs.zh.md: 03a321c761eda385acb665d26a33ef618c70dee5 diff --git a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md new file mode 100644 index 0000000000..73dfb501cb --- /dev/null +++ b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md @@ -0,0 +1,43 @@ +# Agent Note: Follow-up enqueue and owned run boundaries + +Status: proposed + +English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md) + +## Problem + +`Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input. + +The [one-send-one-turn decision](../../implemented/simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers currently manufacture that missing relationship downstream by pairing one prompt request with a turn result. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome. + +## Proposal + +Keep `Agent.followup(message): void` as an enqueue-only operation. `Agent.whenIdle()` and `agent/status` remain whole-agent lifecycle observations; neither settles an individual message. Inbox durability records the identified message and its admission or cancellation, without assigning later output to it. + +The low-level SDK protocol will answer `session/prompt` as soon as enqueue succeeds with `{ messageId }`. It will stream durable facts through `session.event`, publish whole-agent transitions through `session.status`, and remove `session.finished`. A low-level client may observe that receipt and later idleness, but receives no prompt result. + +High-level automation APIs may return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods will collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their `finalResponse` is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may still report a result because its caller owns the complete child lifecycle and any steering belongs to that run. + +ACP must still return a protocol `stopReason`. Its bridge will serialize one in-flight prompt per ACP session, wait for whole-agent idle, report `cancelled` only for explicit ACP cancellation or disposal, and otherwise report the generic `end_turn`. It will not infer token-limit or error attribution for the prompt. + +Goal continuation will retain `MessageId` only to recognize its durable queued and admitted goal message. It will advance from durable goal state at whole-agent idle, without mapping the message to a turn result. + +## Alternatives considered + +**Map `MessageId` to the turn that admits it.** A turn may consume steering and injected context and may continue through multiple model/tool steps. The mapping identifies admission, not causal ownership of the resulting output or stop reason. + +**Return a per-follow-up completion handle.** A handle would imply a result boundary that the shared agent lifecycle does not have. It would either omit work that influenced the activity or silently absorb unrelated later input. + +**Use the last `turn/end` observed before idle.** This is a useful run-level observation for an explicitly owned interval, but naming it as the submitted message's outcome recreates the false causal claim. + +## Acceptance criteria + +- `Agent.followup()` remains enqueue-only, and its documentation promises no per-message completion or result. +- The SDK wire protocol returns `MessageId` from `session/prompt`, publishes `session.status`, and has no `session.finished`. +- TypeScript and Python high-level SDKs expose `RunResult` without prompt-level `status` or `reason`, and define the receipt-to-idle collection window. +- ACP, the one-shot CLI, goal continuation, and subagent providers document the distinct activity ownership they actually possess. +- No production consumer derives a follow-up result by correlating `MessageId` with `turn/end`. + +## Risks + +An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications disappear from SDK and ACP results; callers that need those facts must inspect the durable event stream without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result. diff --git a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md new file mode 100644 index 0000000000..03a321c761 --- /dev/null +++ b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md @@ -0,0 +1,43 @@ +# Agent Note: follow-up 入队与自有运行边界 + +Status: proposed + +[English](2026-07-30-followup-enqueue-and-owned-runs.md) | 中文 + +## 问题 + +`Agent.followup()` 会标识一条用户消息并将其排入队列，但单次 follow-up 并不拥有随后发生的活动。在 agent（智能体）下一次进入 idle 前，steering（中途引导）、注入的上下文、工具续行、恢复和后续排队消息都可能参与活动。因此，`MessageId` 可以证明 inbox 已准入，但不能标识哪一条 assistant 消息或哪一个 `turn/end` 是该输入的结果。 + +[one-send-one-turn 决策](../../implemented/simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。协议层和 SDK 层仍会在下游配对一项提示词请求与一个轮次结果，人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。 + +## 提案 + +保留 `Agent.followup(message): void`，使其仅执行入队。`Agent.whenIdle()` 和 `agent/status` 仍用于观察整个 agent 的生命周期；二者都不结算单条消息。Inbox 持久性会记录已标识消息及其准入或取消，但不会把后续输出归属于该消息。 + +底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，并删除 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。 + +只有明确拥有一个活动区间时，高层自动化 API 才可以返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法会从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行仍可报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。 + +ACP（Agent Client Protocol）仍必须返回协议规定的 `stopReason`。其桥接层会串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，仅在显式 ACP 取消或资源释放时报告 `cancelled`，其他情况均报告通用的 `end_turn`。它不会推断 token 上限或错误是否归属于该提示词。 + +Goal 续行只会保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它会在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。 + +## 考虑过的替代方案 + +**将 `MessageId` 映射到准入它的轮次。** 一个轮次可能使用 steering 和注入的上下文，还可能经过多个模型／工具步骤继续执行。该映射只能标识准入，不能确立结果输出或停止原因的因果归属。 + +**返回按 follow-up 区分的完成句柄。** 这样的句柄暗示共享 agent 生命周期中存在并不实际成立的结果边界。它要么遗漏影响活动的工作，要么在不作说明的情况下吸收后续无关输入。 + +**使用进入 idle 前观察到的最后一个 `turn/end`。** 对于明确拥有的区间，这是一项有用的运行级观测；但如果将其命名为已提交消息的结果，就会再次作出错误的因果声明。 + +## 验收标准 + +- `Agent.followup()` 仍仅执行入队，其文档不承诺单条消息的完成状态或结果。 +- SDK 协议格式（wire format）由 `session/prompt` 返回 `MessageId`、发布 `session.status`，且不包含 `session.finished`。 +- TypeScript 和 Python 高层 SDK 公开不带提示词级 `status` 或 `reason` 的 `RunResult`，并定义从回执到 idle 的收集窗口。 +- ACP、单次 CLI、goal 续行和 subagent 提供方分别记录自己实际拥有的活动边界。 +- 生产消费方都不会通过关联 `MessageId` 与 `turn/end` 来推导 follow-up 结果。 + +## 风险 + +自有活动区间可以包含进入 idle 前提交的 steering、注入上下文或其他工作，因此其最终响应和事件有意比初始消息涵盖更广。SDK 和 ACP 结果不再包含提示词级模型错误和 token 上限分类；需要这些事实的调用方必须检查持久事件流，但不能声称这些事实具有因果归属。在同一会话上并发执行自动化操作时，必须采用显式串行或所有权策略，不能依赖隐式的按提示词结果。 diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index dfff50708f..c05e2c0bc9 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: 1fd9bd128d1bcc0dd91d46131981ea4fc331bd74 -architecture.zh.md: 8521f09c6e415f9f8d1c0a44f7534b59c876decc +architecture.md: d8e5f8a2e8d36acb7d27ed0571645f6166eff3af +architecture.zh.md: 96948aa5283e0114b1883335b91148ce3b720e06 diff --git a/docs/architecture.md b/docs/architecture.md index 3149b6b0d4..d8e5f8a2e8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -131,7 +131,7 @@ Turn and step events are turn-enclosed; idle injected `user/message` events may ### Agent Handles -`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. +`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. `followup()` only queues an identified message: its `MessageId` follows durable inbox admission, not a prompt-specific output or turn ending. `agent/status` and `whenIdle()` describe whole-agent activity; only a caller that explicitly owns an activity interval may summarize that interval as a run result ([proposal](../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). ### Agent Scope diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index dd3b66ee8a..96948aa528 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -123,7 +123,7 @@ idle inject: ### 失败边界 -最终适配器选择、分发与迭代失败会在 loop 处理前成为终止 `finish { kind: 'error' | 'aborted', failure }` chunk。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用时的准备注册重试策略以及信号；middleware 与消费方错误仍在请求恢复之外抛出。失败分片既不提交消息，也不提交工具调用。 +最终适配器选择、分发与迭代失败会在 loop 处理前成为终止 `finish { kind: 'error' | 'aborted', failure }` chunk。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用时已准备注册项的重试策略以及信号；middleware 与消费方错误仍在请求恢复之外抛出。失败分片既不提交消息，也不提交工具调用。 其他故障使用 `agent/error`。取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消异步模型能力准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 在清空队列和中止前发出原因；观察方不能否决；空闲调用不发事件。持久化层将用户或父级取消记录为 `aborted`，拆卸记录为 `disposed`；拆卸会等待完全停稳。原因只影响报告方式，不影响延迟完成的结果上下文处理（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。 @@ -131,7 +131,7 @@ idle inject: ### Agent 句柄 -`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。 +`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。`followup()` 只会将一条带标识的消息排队：其 `MessageId` 跟踪持久 inbox 准入，而不标识某个提示词特有的输出或轮次结束。`agent/status` 与 `whenIdle()` 描述整个 agent 的活动；只有显式拥有某个活动区间的调用方才能将该区间概括为一次运行的结果（[提案](../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。 ### Agent 作用域 diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml index 9ff53f33c3..e6384af8ca 100644 --- a/docs/cookbook/extension-cookbook.i18n.yaml +++ b/docs/cookbook/extension-cookbook.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 docs/cookbook/extension-cookbook.md -extension-cookbook.md: 36ab56dcdce1166ef69cec7834f6c17be72d89c3 -extension-cookbook.zh.md: 8c8f9486ec592fcc80f1053f54adce2e33798d4b +extension-cookbook.md: 1d2945d132b73e093e313820878ed2fdc0746f8f +extension-cookbook.zh.md: 6fceb8a3110a914fdb1b26146f06f3f20c644b42 diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md index 36ab56dcdc..1d2945d132 100644 --- a/docs/cookbook/extension-cookbook.md +++ b/docs/cookbook/extension-cookbook.md @@ -64,7 +64,7 @@ export function apply(ctx: Context) { ## An external protocol driver -A *protocol driver* adapts a wire peer to `ctx.agents`; it may serve a UI or an automation client. A stdio driver owns stdout, creates or resumes agents through the factory, maps the protocol's requests to `followup()` or `cancel()`, and settles each request exactly once from durable `turn/end`. Tear agents down with `AgentHandle.dispose()` so disposal reaches quiescence. +A *protocol driver* adapts a wire peer to `ctx.agents`; it may serve a UI or an automation client. A stdio driver owns stdout, creates or resumes agents through the factory, and maps protocol requests to `followup()` or `cancel()`. A low-level prompt request returns its durable enqueue receipt; it does not acquire a result by correlating `MessageId` with `turn/end`. Publish whole-agent status separately. An automation method may wait from its receipt through the next idle and summarize that explicitly owned interval, while a UI normally keeps observing the open-ended event stream. Tear agents down with `AgentHandle.dispose()` so disposal reaches quiescence. [`packages/acp/acp`](../../packages/acp/acp) is the automation-only worked example: it exposes fresh text sessions over Agent Client Protocol JSON-RPC stdio, emits committed assistant text, and registers a one-shot machine permission answerer for agents it owns. Its [README](../../packages/acp/acp/README.md) owns the exact method and lifecycle contract. @@ -84,7 +84,8 @@ export function apply(ctx: Context) { } } }) - // Inbound "prompt": create/resume an agent and feed it; settle on turn end. + // Inbound "prompt": create/resume an agent, feed it, and return its enqueue receipt. + // Whole-agent status is a separate notification; no turn end belongs to this prompt. // Teardown reaches quiescence via AgentHandle.dispose() (stop + await exit). } ``` diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md index 8c8f9486ec..6fceb8a311 100644 --- a/docs/cookbook/extension-cookbook.zh.md +++ b/docs/cookbook/extension-cookbook.zh.md @@ -64,7 +64,7 @@ export function apply(ctx: Context) { ## 外部协议驱动 -*协议驱动*将协议对端接入 `ctx.agents`；它可以服务于 UI 或自动化客户端。stdio 驱动拥有 stdout，通过工厂创建或恢复 agent（智能体），将协议请求映射为 `followup()` 或 `cancel()`，并根据持久的 `turn/end` 对每个请求恰好结算一次。通过 `AgentHandle.dispose()` 拆除 agent，以使 dispose（资源释放）达到完全停稳。 +*协议驱动*将协议对端接入 `ctx.agents`；它可以服务于 UI 或自动化客户端。stdio 驱动拥有 stdout，通过工厂创建或恢复 agent（智能体），并将协议请求映射为 `followup()` 或 `cancel()`。底层提示词请求返回其持久入队回执；它不会通过关联 `MessageId` 与 `turn/end` 获得结果。整个 agent 的状态应单独发布。自动化方法可以从回执等待到下一次 idle，并概括这一显式拥有的区间；UI 通常则会持续观察开放式事件流。通过 `AgentHandle.dispose()` 拆除 agent，以使 dispose（资源释放）达到完全停稳。 [`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期契约。 @@ -84,7 +84,8 @@ export function apply(ctx: Context) { } } }) - // Inbound "prompt": create/resume an agent and feed it; settle on turn end. + // Inbound "prompt": create/resume an agent, feed it, and return its enqueue receipt. + // Whole-agent status is a separate notification; no turn end belongs to this prompt. // Teardown reaches quiescence via AgentHandle.dispose() (stop + await exit). } ``` diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index 6321c85127..f0ab5d462e 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md -core.md: dad533cee00646a40f57bd9097b2cceb8e9de9e2 -core.zh.md: 9e8afac0744fcf0df8c35dad5debce746d6614c6 +core.md: b7e1c11b488dc751f4d50f4616a6bf20186d06d5 +core.zh.md: 0e204ef9ce51db66dac491ffcb2a32682b8f4826 diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index ec2fe0f736..b7e1c11b48 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -67,14 +67,13 @@ declare module '@deepseek-ai/dsh-llm' { } ``` -Six canonical maps use this pattern; a plugin author extends these: +Five canonical maps use this pattern; a plugin author extends these: | Map | Package | Derives | Catalog | |---|---|---|---| | `ContentBlockMap` | dsh-llm | `ContentBlock` | [below](#content-blocks-and-messages) | | `MessageSourceMap` | dsh-llm | `MessageSource` | [below](#content-blocks-and-messages) | | `FinishReasonMap` | dsh-llm | `FinishReason` | [below](#the-model-request-and-result) | -| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) | | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) | | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) | @@ -406,7 +405,7 @@ type SessionEvent = { }[T] ``` -The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**. +The session event variants, `deriveMessages()` projection rules, `TurnEndReason` vocabulary, and execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**. ## The agent handle @@ -415,60 +414,11 @@ The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, ` Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) ```ts type-equiv -/** Resolved inbox placement reported when an accepted message is enqueued. */ -type InboxPlacement = 'queued' | 'steering' +/** One of the two ordered pending-message lists owned by an agent. */ +type InboxTarget = 'next-turn' | 'next-step' ``` -`InboxItemId` is a process-local branded string minted for each accepted FIFO occurrence. It is intentionally distinct from `MessageId`: sending the same immutable message twice creates two independently addressable pending items. - -```ts type-equiv -/** One independently addressable accepted occurrence in an agent inbox. */ -interface InboxItem { - /** Agent-loop-minted occurrence identity. */ - readonly id: InboxItemId - /** Identified message delivered by the caller. */ - readonly message: UserMessage - /** Acceptance-time FIFO classification. */ - readonly placement: InboxPlacement -} -``` - -```ts type-equiv -/** A user-requested mutation of one still-pending queued occurrence. */ -type InboxAction = - | { readonly kind: 'edit'; readonly content: ContentBlock[] } - | { readonly kind: 'remove' } -``` - -```ts type-equiv -/** Result of applying an inbox action at the synchronous ownership boundary. */ -type InboxActionResult = 'applied' | 'not-found' -``` - -```ts type-equiv -/** - * Options for the unified {@link Agent.send} primitive over the - * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup} - * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and - * {@link Agent.inject} (`next-step`/no-wakeup). - * - * The object is complete so routing policy is explicit. - */ -interface SendOptions { - /** Queue the item joins. */ - target: SendTarget - /** - * Whether this item makes the model run: wake a parked driver (`next-turn`) - * or force a continuation step (`next-step` while running). A `false` - * `next-turn` item queues without waking; a `false` - * `next-step` item attaches durable context without forcing another step - * (the injection preset). - */ - wakeup: boolean -} -``` - -The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable when an edit replaces the message content, while the enclosing `InboxItemId` identifies one accepted occurrence across `agent/inbox/enqueue`, `agent/inbox/update`, and its terminal dequeue or discard. Injection bypasses the FIFOs and never appears on those events. +Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. `Inbox.splice(target, start, deleteCount, inserted, outcome?)` uses standard splice coordinates, rejects duplicate pending message ids, and records the normalized mutation as durable `agent/inbox/spliced`. Replaying those events reconstructs both `nextTurn` and `nextStep`, including edits, insertion, admission, and cancellation. ```ts type-equiv /** Options for {@link Agent.cancel}. */ @@ -476,26 +426,25 @@ interface CancelOptions { /** * Preserve queued and steering inbox items instead of discarding them. The * active turn is still aborted, but un-started and pending work survives for a - * later turn and no `agent/inbox/discard` fires. + * later turn and no canceled inbox splice is logged. */ - keepInbox?: boolean + keepInbox?: boolean | undefined } ``` ```ts type-equiv -/** Stable runtime cause accepted by {@link Agent.cancel}. */ +/** Why an active agent driver was cancelled. */ type AgentCancelCause = | { readonly kind: 'user' } | { readonly kind: 'parent' } + | { readonly kind: 'hook'; readonly reason: string } + | { readonly kind: 'disposed' } ``` `Agent` is an interface over the public live-agent contract. Concrete drivers implement `followup`, `steer`, and `inject`; routing policy remains private to the driver. ```ts type-equiv -/** - * Public live-agent handle with aliases over the unified delivery primitive. - * @typert object - */ +/** Public live-agent handle. */ interface Agent { /** The single identity shared with {@link session}. */ readonly id: SessionId @@ -503,61 +452,28 @@ interface Agent { readonly options: AgentOptions /** The live session this agent drives; its log is the durable source of truth. */ readonly session: Session + /** The agent-owned projection of durable pending work. */ + readonly inbox: Inbox /** The current lifecycle state, mirrored on every `agent/status` transition. */ readonly status: AgentStatus - /** - * Whether a `next-step` send currently stages for prompt admission or the - * open turn. Unlike {@link status}, this excludes admission exit and turn - * settlement, when a waking `next-step` send becomes a queued follow-up. - */ - readonly acceptsNextStep: boolean /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */ readonly ctx: Context - /** - * The unified delivery primitive over the (`target` × `wakeup`) matrix. - * It routes the caller's typed content and source as follows: - * - * - `next-turn` queues an item that becomes the sole ordinary message of its - * own FIFO-ordered turn; `wakeup:true` wakes a - * parked driver, while `wakeup:false` queues without waking. - * - `next-step` with `wakeup:true` stages steering during prompt admission - * or an open turn; outside that window it falls back to a woken - * `next-turn`. - * - `next-step` with `wakeup:false` injects durable model-facing context - * without running the model: admission or an open turn stages it for the - * next safe log position, while an injection outside that window appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside - * steering remains pending with it. - * The agent publishes or queues the identified frozen message as-is. - * @param message - identified model-facing content and its producer provenance. - * @param options - target queue and wakeup decision. - */ - send(message: UserMessage, options: SendOptions): void - - /** - * Mutate one still-pending queued occurrence synchronously. Editing preserves - * the message identity and queue position; removal publishes its terminal - * discard. Steering occurrences and driver-claimed items return `not-found`. - * @param id - independently addressable queued occurrence. - * @param action - edit or remove operation. - * @returns whether the pending occurrence was found and updated. - */ - updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult - /** * Clear queued and steering work — unless `keepInbox` — and abort the active - * turn. An effective call first emits `agent/cancel-requested` with the - * resolved typed cause. The first cause wins for the active turn, and - * `whenIdle()` resolves after cancellation reaches quiescence. Idle - * cancellation is a no-op and does not arm later work. + * turn. The first cause wins for the active turn. Idle cancellation is a + * no-op and does not arm later work. * @param cause - the stable caller intent carried by the current turn signal. * @param options - cancellation options; `keepInbox` preserves pending work. */ cancel(cause: AgentCancelCause, options?: CancelOptions): void - /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */ + /** + * Resolve after the current whole-agent activity reaches quiescence. This + * follows replacement work scheduled before the observed driver retires, + * but does not identify the settlement of any particular message. + * @returns fulfillment after no scheduled or active driver remains. + */ whenIdle(): Promise /** @@ -568,22 +484,18 @@ interface Agent { followup(message: UserMessage): void /** - * Submit steering during prompt admission or an open turn. It stages for the next steering - * checkpoint before a request or stop decision. If the activity fails before - * that boundary, the remainder stays staged without waking the agent; retry - * or a later prompt takes it. Outside that window steering falls back to a - * woken follow-up turn, while cancellation or disposal may discard pending - * steering. + * Submit steering for the nearest step. An idle driver schedules a turn; + * collecting and running drivers consume it at their next step boundary. + * Cancellation or disposal may discard pending steering. * @param message - identified steering content and its producer provenance. */ steer(message: UserMessage): void /** - * Append model-facing context without running the model — the - * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn - * stages it at the next safe log position; outside that window it appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside + * Append model-facing context without running the model. Admission or an + * open turn stages it at the next safe log position; outside that window it + * appends immediately without opening a turn. If admission closes without a + * turn, a context-only boundary appends immediately; context staged beside * steering remains pending with it. * @param message - identified injected context and its producer provenance. */ @@ -591,9 +503,9 @@ interface Agent { } ``` -`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission leaves the provider default in control. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default. +`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox and admission facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([proposal](../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission leaves the provider default in control. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default. -The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result. +The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result. The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits. @@ -603,22 +515,21 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above, ## Interception decisions -Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results. +Prompt decisions use the same identified `UserMessage` shape as durable user-role input. The allowed batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result. Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) -`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow may rewrite the claimed prompt or attach `additionalContexts`; block rejects admission without creating turn events: +`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow supplies the complete admitted batch; block rejects admission without creating turn events and may leave the claimed messages pending: ```ts type-equiv /** - * Prompt interception result. `allow.content` replaces the prompt, while - * `additionalContexts` appends model-facing context before the turn starts. - * An `allow` returned by a listener is authoritative: a listener wrapping - * `next()` preserves both fields unless it intentionally replaces them. + * Prompt interception result. An allowed batch replaces the submitted + * messages. A listener wrapping `next()` preserves the returned batch unless + * it intentionally replaces it. */ type PromptDecision = - | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] } - | { kind: 'block'; reason: string } + | { kind: 'allow'; messages: UserMessage[] } + | { kind: 'block'; reason: string; keepInbox?: boolean } ``` `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal. @@ -628,11 +539,6 @@ type PromptDecision = type RequestErrorAction = { kind: 'retry' } | undefined ``` -```ts type-equiv -/** Model-request failure with an optional machine-routable provider code. */ -type RequestError = Error & { code?: string } -``` - `agent/step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain. `agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it): diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index fa6d06734c..0e204ef9ce 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -69,14 +69,13 @@ declare module '@deepseek-ai/dsh-llm' { } ``` -六个规范 map 使用此模式；插件作者扩展它们： +五个规范 map 使用此模式；插件作者扩展它们： | Map | 包 | 派生 | 目录 | |---|---|---|---| | `ContentBlockMap` | dsh-llm | `ContentBlock` | [下文](#content-blocks-and-messages) | | `MessageSourceMap` | dsh-llm | `MessageSource` | [下文](#content-blocks-and-messages) | | `FinishReasonMap` | dsh-llm | `FinishReason` | [下文](#the-model-request-and-result) | -| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) | | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) | | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) | @@ -412,7 +411,7 @@ type SessionEvent = { }[T] ``` -十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。 +会话事件变体、`deriveMessages()` 投影规则、`TurnEndReason` 词汇以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。 @@ -423,60 +422,11 @@ type SessionEvent = { 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) ```ts type-equiv -/** Resolved inbox placement reported when an accepted message is enqueued. */ -type InboxPlacement = 'queued' | 'steering' +/** One of the two ordered pending-message lists owned by an agent. */ +type InboxTarget = 'next-turn' | 'next-step' ``` -`InboxItemId` 是为每次获准进入 FIFO 的项铸造的进程本地品牌字符串。它有意区别于 `MessageId`：同一条不可变消息发送两次，会创建两个可独立寻址的待处理项。 - -```ts type-equiv -/** One independently addressable accepted occurrence in an agent inbox. */ -interface InboxItem { - /** Agent-loop-minted occurrence identity. */ - readonly id: InboxItemId - /** Identified message delivered by the caller. */ - readonly message: UserMessage - /** Acceptance-time FIFO classification. */ - readonly placement: InboxPlacement -} -``` - -```ts type-equiv -/** A user-requested mutation of one still-pending queued occurrence. */ -type InboxAction = - | { readonly kind: 'edit'; readonly content: ContentBlock[] } - | { readonly kind: 'remove' } -``` - -```ts type-equiv -/** Result of applying an inbox action at the synchronous ownership boundary. */ -type InboxActionResult = 'applied' | 'not-found' -``` - -```ts type-equiv -/** - * Options for the unified {@link Agent.send} primitive over the - * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup} - * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and - * {@link Agent.inject} (`next-step`/no-wakeup). - * - * The object is complete so routing policy is explicit. - */ -interface SendOptions { - /** Queue the item joins. */ - target: SendTarget - /** - * Whether this item makes the model run: wake a parked driver (`next-turn`) - * or force a continuation step (`next-step` while running). A `false` - * `next-turn` item queues without waking; a `false` - * `next-step` item attaches durable context without forcing another step - * (the injection preset). - */ - wakeup: boolean -} -``` - -固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。编辑替换消息内容时，其 `MessageId` 保持稳定；外层 `InboxItemId` 则在 `agent/inbox/enqueue`、`agent/inbox/update` 及终态 dequeue 或 discard 之间标识同一次入队。注入绕过两个 FIFO，从不出现在这些事件中。 +每个待处理入队项就是其 `UserMessage`；`MessageId` 是唯一标识。`Inbox.splice(target, start, deleteCount, inserted, outcome?)` 使用标准 splice 坐标，拒绝重复的待处理消息 id，并将规范化变更记录为持久 `agent/inbox/spliced`。回放这些事件可以重建 `nextTurn` 和 `nextStep`，包括编辑、插入、准入与取消。 ```ts type-equiv /** Options for {@link Agent.cancel}. */ @@ -484,26 +434,25 @@ interface CancelOptions { /** * Preserve queued and steering inbox items instead of discarding them. The * active turn is still aborted, but un-started and pending work survives for a - * later turn and no `agent/inbox/discard` fires. + * later turn and no canceled inbox splice is logged. */ - keepInbox?: boolean + keepInbox?: boolean | undefined } ``` ```ts type-equiv -/** Stable runtime cause accepted by {@link Agent.cancel}. */ +/** Why an active agent driver was cancelled. */ type AgentCancelCause = | { readonly kind: 'user' } | { readonly kind: 'parent' } + | { readonly kind: 'hook'; readonly reason: string } + | { readonly kind: 'disposed' } ``` `Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器实现 `followup`、`steer` 和 `inject`；路由策略仍为驱动器私有。 ```ts type-equiv -/** - * Public live-agent handle with aliases over the unified delivery primitive. - * @typert object - */ +/** Public live-agent handle. */ interface Agent { /** The single identity shared with {@link session}. */ readonly id: SessionId @@ -511,61 +460,28 @@ interface Agent { readonly options: AgentOptions /** The live session this agent drives; its log is the durable source of truth. */ readonly session: Session + /** The agent-owned projection of durable pending work. */ + readonly inbox: Inbox /** The current lifecycle state, mirrored on every `agent/status` transition. */ readonly status: AgentStatus - /** - * Whether a `next-step` send currently stages for prompt admission or the - * open turn. Unlike {@link status}, this excludes admission exit and turn - * settlement, when a waking `next-step` send becomes a queued follow-up. - */ - readonly acceptsNextStep: boolean /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */ readonly ctx: Context - /** - * The unified delivery primitive over the (`target` × `wakeup`) matrix. - * It routes the caller's typed content and source as follows: - * - * - `next-turn` queues an item that becomes the sole ordinary message of its - * own FIFO-ordered turn; `wakeup:true` wakes a - * parked driver, while `wakeup:false` queues without waking. - * - `next-step` with `wakeup:true` stages steering during prompt admission - * or an open turn; outside that window it falls back to a woken - * `next-turn`. - * - `next-step` with `wakeup:false` injects durable model-facing context - * without running the model: admission or an open turn stages it for the - * next safe log position, while an injection outside that window appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside - * steering remains pending with it. - * The agent publishes or queues the identified frozen message as-is. - * @param message - identified model-facing content and its producer provenance. - * @param options - target queue and wakeup decision. - */ - send(message: UserMessage, options: SendOptions): void - - /** - * Mutate one still-pending queued occurrence synchronously. Editing preserves - * the message identity and queue position; removal publishes its terminal - * discard. Steering occurrences and driver-claimed items return `not-found`. - * @param id - independently addressable queued occurrence. - * @param action - edit or remove operation. - * @returns whether the pending occurrence was found and updated. - */ - updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult - /** * Clear queued and steering work — unless `keepInbox` — and abort the active - * turn. An effective call first emits `agent/cancel-requested` with the - * resolved typed cause. The first cause wins for the active turn, and - * `whenIdle()` resolves after cancellation reaches quiescence. Idle - * cancellation is a no-op and does not arm later work. + * turn. The first cause wins for the active turn. Idle cancellation is a + * no-op and does not arm later work. * @param cause - the stable caller intent carried by the current turn signal. * @param options - cancellation options; `keepInbox` preserves pending work. */ cancel(cause: AgentCancelCause, options?: CancelOptions): void - /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */ + /** + * Resolve after the current whole-agent activity reaches quiescence. This + * follows replacement work scheduled before the observed driver retires, + * but does not identify the settlement of any particular message. + * @returns fulfillment after no scheduled or active driver remains. + */ whenIdle(): Promise /** @@ -576,22 +492,18 @@ interface Agent { followup(message: UserMessage): void /** - * Submit steering during prompt admission or an open turn. It stages for the next steering - * checkpoint before a request or stop decision. If the activity fails before - * that boundary, the remainder stays staged without waking the agent; retry - * or a later prompt takes it. Outside that window steering falls back to a - * woken follow-up turn, while cancellation or disposal may discard pending - * steering. + * Submit steering for the nearest step. An idle driver schedules a turn; + * collecting and running drivers consume it at their next step boundary. + * Cancellation or disposal may discard pending steering. * @param message - identified steering content and its producer provenance. */ steer(message: UserMessage): void /** - * Append model-facing context without running the model — the - * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn - * stages it at the next safe log position; outside that window it appends - * immediately without opening a turn. If admission closes without a turn, - * a context-only boundary appends immediately; context staged beside + * Append model-facing context without running the model. Admission or an + * open turn stages it at the next safe log position; outside that window it + * appends immediately without opening a turn. If admission closes without a + * turn, a context-only boundary appends immediately; context staged beside * steering remains pending with it. * @param message - identified injected context and its producer provenance. */ @@ -599,9 +511,9 @@ interface Agent { } ``` -`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时由提供方默认值控制。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。 +`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 与准入事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[提案](../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时由提供方默认值控制。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。 -cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。只有 loop 会在结算时从自己机器私有的 signal 上读回 cause（`user`、`parent` 或仅用于生命周期的 `disposed`）——不存在公开的读取器，signal 也不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。 +cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。 [事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。 @@ -611,22 +523,21 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancella ## 拦截决策 -提示词决策与工具后决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的标识与 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。 +提示词决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。获准批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) -`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 可以改写已领取的提示词或附加 `additionalContexts`；block 拒绝准入且不产生任何轮次事件： +`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 提供完整的准入批次；block 拒绝准入且不产生任何轮次事件，并可以让已领取的消息保持待处理： ```ts type-equiv /** - * Prompt interception result. `allow.content` replaces the prompt, while - * `additionalContexts` appends model-facing context before the turn starts. - * An `allow` returned by a listener is authoritative: a listener wrapping - * `next()` preserves both fields unless it intentionally replaces them. + * Prompt interception result. An allowed batch replaces the submitted + * messages. A listener wrapping `next()` preserves the returned batch unless + * it intentionally replaces it. */ type PromptDecision = - | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] } - | { kind: 'block'; reason: string } + | { kind: 'allow'; messages: UserMessage[] } + | { kind: 'block'; reason: string; keepInbox?: boolean } ``` `agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。 @@ -636,11 +547,6 @@ type PromptDecision = type RequestErrorAction = { kind: 'retry' } | undefined ``` -```ts type-equiv -/** Model-request failure with an optional machine-routable provider code. */ -type RequestError = Error & { code?: string } -``` - `agent/step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。 `agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）： diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml index 3e35c3a051..75bef3d87f 100644 --- a/docs/core-data-structures/session.i18n.yaml +++ b/docs/core-data-structures/session.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 docs/core-data-structures/session.md -session.md: fd8285eebd76e8bd7723ee86ae15427f4923f4d6 -session.zh.md: 1033bfda117b5693421f0bdf4ec3fc136039f223 +session.md: 85eebf81e07774e4d9095cfbf042330a90d30a9e +session.zh.md: 356a283c4ebe041c3690ae2e3a23ff1be7b4722f diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index fd8285eebd..85eebf81e0 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -26,9 +26,11 @@ interface UserMessage extends Message { */ interface SessionEventMap { /** - * Opens turn `turn`. `trigger` records what started the model loop. + * Opens turn `turn`. Every turn begins when the loop admits queued input; + * the following identified `user/message` event or batch records the + * admitted input. */ - 'turn/start': { turn: number; trigger: TurnTrigger } + 'turn/start': { turn: number } /** * Closes turn `turn` with the {@link TurnEndReason} that ended it. The loop * awaits `session/flush` after an ordinary turn ends before claiming the next @@ -434,7 +436,7 @@ declare class Session { - `user/message` (injected context, i.e. non-`user` source) → a user-role message carrying its `content` verbatim at its chronological position; provenance and domain data live in its typed source. - `steering/message` → a user-role message carrying exact `content` at its chronological position; an optional envelope remains log-only display metadata. -Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and does not project into a message. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message, so their usage chunk is the durable accounting record. An operational error's step number is on `turn/end.reason` for `kind: 'error'`, with normalized `LlmFailure` facts for a final model-request failure and message/code for other live errors. Because this unreleased format intentionally has no compatibility promise, seed/load validation rejects request headers without provider+model and assistant messages without provider/model provenance instead of guessing a route for historical data. +Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and does not project into a message. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message, so their usage chunk is the durable accounting record. Because this unreleased format intentionally has no compatibility promise, seed/load validation rejects request headers without provider+model and assistant messages without provider/model provenance instead of guessing a route for historical data. ## Live-session fork API @@ -444,29 +446,9 @@ Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and An explicit `boundary` lets callers fork from any stable between-turn position, including a previous `turn/end` or a later standalone log-only event, even if the source has newer events or an open current turn. The API rejects a prefix that ends inside an open turn instead of clipping silently. Broader execution-relation sanity stays in the existing `dsh-invariants` plugin and persistence repair path rather than being duplicated in `fork()`. `dsh-subagent-fork` keeps its completed-prefix clipping because tool-time delegation usually starts while the parent turn is open; ordinary session branching should make the requested boundary explicit. -## What started a turn: `TurnTriggerMap` - -```ts type-equiv -/** - * What started a turn. - * Merge-extensible sum type (same pattern as MessageSourceMap). - */ -interface TurnTriggerMap { - message: { kind: 'message'; source: MessageSource } - /** Recovery turn reopened over the repaired current session log. */ - retry: { kind: 'retry' } - /** - * An out-of-band producer explicitly enclosed injected context in a one-shot - * turn. `Agent.inject()` appends idle context directly and does not use this - * trigger; the source mirrors the producer of the enclosed `user/message`. - */ - injection: { kind: 'injection'; source: MessageSource } -} -``` - ## Why a turn ended: `TurnEndReasonMap` -`aborted` is intentionally a coarse durable outcome: it records that cancellation interrupted the live turn, not which runtime caller requested it. The runtime-only caller vocabulary belongs to [`AgentCancelCause`](core.md#the-agent-handle); a future audit requirement would use a separate control-request event rather than overloading the terminal result. +`turn/start` has no trigger field. The admitted `user/message` batch records what entered the turn, `llm/retry` records request recovery, and idle injection opens no turn. `aborted.reason` retains the typed [`AgentCancelCause`](core.md#the-agent-handle) that stopped the driver. ```ts type-equiv /** @@ -475,20 +457,11 @@ interface TurnTriggerMap { interface TurnEndReasonMap { completed: { kind: 'completed' } /** A cancellation request interrupted the live turn. */ - aborted: { kind: 'aborted' } + aborted: { kind: 'aborted'; reason: AgentCancelCause } /** - * The turn failed: a step threw or the model reported a failure. `step` is the - * step number the failure occurred on (the operational error's location — the - * single durable record of an in-turn failure; live diagnostics also fire via - * `agent/error`). Final model-request failures retain their normalized facts - * as one `failure`; other thrown values retain their rendered message and a - * real `HarnessError` code when present. + * The turn failed. */ - error: { kind: 'error'; step: number } & ( - | { failure: LlmFailure; message?: never; code?: never } - | { message: string; code?: string; failure?: never } - ) - disposed: { kind: 'disposed' } + error: { kind: 'error'; error: unknown } /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */ 'max-tokens': { kind: 'max-tokens' } /** @@ -499,7 +472,7 @@ interface TurnEndReasonMap { } ``` -`max-tokens` mirrors the model-call `FinishReason` of the same name: any `max-tokens` step in a turn makes the whole turn end `max-tokens` rather than `completed` (the cut-short fact wins over a later continuation), so a consumer can tell a clean stop from a truncated one — but only over `completed`: the `disposed`/`aborted`/`error` outcomes take precedence. `interrupted` is the one reason no loop emits — it is synthesized by crash recovery (see [persistence.md](persistence.md)). Both maps are merge-extensible. +`max-tokens` mirrors the model-call `FinishReason` of the same name: any `max-tokens` step in a turn makes the whole turn end `max-tokens` rather than `completed` (the cut-short fact wins over a later continuation), so a consumer can tell a clean stop from a truncated one. Cancellation and errors remain distinct outcomes. `interrupted` is the one reason no loop emits—it is synthesized by crash recovery (see [persistence.md](persistence.md)). The map is merge-extensible. ## Execution enclosure and standalone events diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md index 1033bfda11..356a283c4e 100644 --- a/docs/core-data-structures/session.zh.md +++ b/docs/core-data-structures/session.zh.md @@ -26,9 +26,11 @@ interface UserMessage extends Message { */ interface SessionEventMap { /** - * Opens turn `turn`. `trigger` records what started the model loop. + * Opens turn `turn`. Every turn begins when the loop admits queued input; + * the following identified `user/message` event or batch records the + * admitted input. */ - 'turn/start': { turn: number; trigger: TurnTrigger } + 'turn/start': { turn: number } /** * Closes turn `turn` with the {@link TurnEndReason} that ended it. The loop * awaits `session/flush` after an ordinary turn ends before claiming the next @@ -436,7 +438,7 @@ declare class Session { - `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`；溯源信息与领域数据都在其类型化的 source 中。 - `steering/message` → 按时间顺序在相应位置生成一条携带确切 `content` 的 user-role 消息；可选 envelope 仅作为日志中的展示元数据保留。 -其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。操作错误的步骤号记录在 `turn/end.reason`（`kind: 'error'`）中；如果是最终模型请求失败，其中包含规范化的 `LlmFailure` 事实，其他实时错误则包含消息/代码。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝缺少提供方和模型的请求头，以及缺少提供方/模型溯源信息的 assistant 消息，而不会猜测历史数据应走的提供方路由。 +其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝缺少提供方和模型的请求头，以及缺少提供方/模型溯源信息的 assistant 消息，而不会猜测历史数据应走的提供方路由。 ## 活跃会话 fork API @@ -446,31 +448,11 @@ declare class Session { 显式 `boundary` 允许调用者从任意稳定的轮次间位置 fork，包括之前的 `turn/end` 或更晚的独立纯日志事件，即使源会话有更新的事件或正在进行的轮次。API 拒绝结束于开放轮次内的前缀，而不是静默截断。更广泛的执行关系健全性检查留在既有的 `dsh-invariants` 插件和持久化修复路径中，不在 `fork()` 中重复。`dsh-subagent-fork` 保留其已完成前缀截断逻辑，因为工具时委托通常在父轮次仍然打开时启动；普通的会话分支应显式指定请求的 boundary。 -## 轮次的触发原因：`TurnTriggerMap` - -```ts type-equiv -/** - * What started a turn. - * Merge-extensible sum type (same pattern as MessageSourceMap). - */ -interface TurnTriggerMap { - message: { kind: 'message'; source: MessageSource } - /** Recovery turn reopened over the repaired current session log. */ - retry: { kind: 'retry' } - /** - * An out-of-band producer explicitly enclosed injected context in a one-shot - * turn. `Agent.inject()` appends idle context directly and does not use this - * trigger; the source mirrors the producer of the enclosed `user/message`. - */ - injection: { kind: 'injection'; source: MessageSource } -} -``` - ## 轮次的结束原因：`TurnEndReasonMap` -`aborted` 有意作为一种粗粒度的持久结果：它只记录取消中断了实时轮次，不记录是哪个运行时调用方发起取消。仅属于运行时的调用方词汇由 [`AgentCancelCause`](core.md#the-agent-handle) 定义；未来若有审计需求，应新增独立的控制请求事件，而非让终止结果承载这一信息。 +`turn/start` 没有 trigger 字段。已准入的 `user/message` 批次记录进入轮次的内容，`llm/retry` 记录请求恢复，idle 注入则不会打开轮次。`aborted.reason` 保留停止驱动器的类型化 [`AgentCancelCause`](core.md#the-agent-handle)。 ```ts type-equiv /** @@ -479,20 +461,11 @@ interface TurnTriggerMap { interface TurnEndReasonMap { completed: { kind: 'completed' } /** A cancellation request interrupted the live turn. */ - aborted: { kind: 'aborted' } + aborted: { kind: 'aborted'; reason: AgentCancelCause } /** - * The turn failed: a step threw or the model reported a failure. `step` is the - * step number the failure occurred on (the operational error's location — the - * single durable record of an in-turn failure; live diagnostics also fire via - * `agent/error`). Final model-request failures retain their normalized facts - * as one `failure`; other thrown values retain their rendered message and a - * real `HarnessError` code when present. + * The turn failed. */ - error: { kind: 'error'; step: number } & ( - | { failure: LlmFailure; message?: never; code?: never } - | { message: string; code?: string; failure?: never } - ) - disposed: { kind: 'disposed' } + error: { kind: 'error'; error: unknown } /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */ 'max-tokens': { kind: 'max-tokens' } /** @@ -503,7 +476,7 @@ interface TurnEndReasonMap { } ``` -`max-tokens` 与模型调用中同名的 `FinishReason` 对应：只要轮次内有任何步骤以 `max-tokens` 结束，整个轮次就以 `max-tokens` 而不是 `completed` 结束（即使之后继续执行，截断事实仍优先），让消费方能够区分正常停止和截断停止；但它只优先于 `completed`，`disposed`/`aborted`/`error` 结果的优先级更高。`interrupted` 是唯一不会由任何 loop 发出的原因：它由崩溃恢复合成（见 [persistence.md](persistence.md)）。两个 map 均可通过合并扩展。 +`max-tokens` 与模型调用中同名的 `FinishReason` 对应：只要轮次内有任何步骤以 `max-tokens` 结束，整个轮次就以 `max-tokens` 而不是 `completed` 结束（即使之后继续执行，截断事实仍优先），让消费方能够区分正常停止和截断停止。取消和错误仍是不同的结果。`interrupted` 是唯一不会由任何 loop 发出的原因：它由崩溃恢复合成（见 [persistence.md](persistence.md)）。该 map 可通过合并扩展。 ## 执行封闭与独立事件 diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml index 674cd63efe..8052189a99 100644 --- a/docs/defensive-patterns.i18n.yaml +++ b/docs/defensive-patterns.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 docs/defensive-patterns.md -defensive-patterns.md: cc34877fb0d6a2e1740d8fa138f879363c8e69a3 -defensive-patterns.zh.md: 21b0977d8167ffecc21cdfab3c778efceefd8f03 +defensive-patterns.md: 3754e02d4f0754fdd711310775c0177ee7c313b1 +defensive-patterns.zh.md: 884ed404820d64afdb5237f8121992bcb107cb0f diff --git a/docs/defensive-patterns.md b/docs/defensive-patterns.md index 60b1f67e78..3754e02d4f 100644 --- a/docs/defensive-patterns.md +++ b/docs/defensive-patterns.md @@ -14,7 +14,7 @@ When an implementation boundary receives several representations of one outcome, ## Async state is not synchronous state -`agent.followup()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) instead of treating status as a per-follow-up result: several queued follow-ups run as consecutive turns under one `running` interval, while cancellation or disposal can discard unstarted items. The guard cuts both ways: if the awaited transition can never occur (EOF with no work submitted → never `running`), the wait hangs — handle the "nothing to wait for" branch explicitly. +`agent.followup()` has no per-message completion or result; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never treat `agent/status` or `whenIdle()` as the result of one follow-up: several queued follow-ups, steering, and injected work may share one `running` interval, while cancellation or disposal can discard unstarted items. An automation caller that truly owns a run must define its interval explicitly—for example, from its message's durable inbox receipt through the next whole-agent `idle`—and describe any selected output as interval-wide rather than causally attributed to that message. The guard cuts both ways: if the awaited transition can never occur, the wait hangs, so handle the "nothing to wait for" branch explicitly. ## Dispose must reach quiescence, not just request it diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md index ca6ee16a42..884ed40482 100644 --- a/docs/defensive-patterns.zh.md +++ b/docs/defensive-patterns.zh.md @@ -14,7 +14,7 @@ ## 异步状态不是同步状态 -`agent.followup()` 不会在返回前翻转状态；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿基于一个刚刚请求的状态来控制流程——应以实际触发的事件/promise（`agent/status`、`task.done`）驱动生命周期，并观察状态转换（先看到 `running` 再看到 `idle`），而不是把状态当作逐次 `followup()` 的结果：多次排队的 `followup()` 会在同一个 `running` 区间内连续运行多个轮次，而取消或资源释放可能丢弃尚未启动的项。这条守则是双向的：如果等待的转换永远不会发生（EOF 时没有提交过任何工作 → 永远不会进入 `running`），等待就会挂起——请显式处理「无需等待」的分支。 +`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent 下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。 ## Dispose 必须达到完全停稳，而不仅仅是请求停止 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index dea3c4816b..42bab06f44 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -78,10 +78,27 @@ export type SessionEvent = { }[T] ``` -Sources: [`packages/core/session/src/types.ts:256`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:292`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:324`](../packages/core/session/src/types.ts) +Sources: [`packages/core/session/src/types.ts:235`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:242`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:303`](../packages/core/session/src/types.ts) ## Events +### `agent/*` + +#### `agent/inbox/spliced` — log-only + +```ts persistence-catalog +/** One normalized mutation of an agent's durable pending-message lists. */ +'agent/inbox/spliced': { + target: InboxTarget + start: number + removedCount?: number + inserted: UserMessage[] + outcome?: 'admitted' | 'canceled' +} +``` + +Source: [`packages/core/agent/src/types.ts:268`](../packages/core/agent/src/types.ts) + ### `approval/*` #### `approval/asked` — log-only @@ -154,7 +171,7 @@ Source: [`packages/ui/user-approval/src/index.ts:67`](../packages/ui/user-approv Types: [StreamChunk](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:212`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:191`](../packages/core/session/src/types.ts) #### `assistant/message` — surface @@ -170,7 +187,7 @@ Source: [`packages/core/session/src/types.ts:212`](../packages/core/session/src/ Types: [TokenUsage](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:219`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:198`](../packages/core/session/src/types.ts) ### `command/*` @@ -311,7 +328,7 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook- #### `llm/retry` — log-only ```ts persistence-catalog -/** Durable, non-surface record of one provider-routed retry scheduled after a closed failed step. */ +/** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */ 'llm/retry': { turn: number step: number @@ -334,7 +351,7 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook- } ``` -Source: [`packages/llm/llm-retry/src/index.ts:18`](../packages/llm/llm-retry/src/index.ts) +Source: [`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts) ### `permission/*` @@ -379,7 +396,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:51`](../packages/plan/plan-mode/s 'request/header': { header: EpochHeader; reason: RequestHeaderReason } ``` -Source: [`packages/core/session/src/types.ts:252`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:231`](../packages/core/session/src/types.ts) ### `sandbox/*` @@ -438,7 +455,7 @@ Source: [`packages/session-title/session-title-llm/src/index.ts:43`](../packages 'steering/message': { turn: number; message: UserMessage } ``` -Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts) ### `step/*` @@ -449,7 +466,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/ 'step/end': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:201`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:180`](../packages/core/session/src/types.ts) #### `step/start` — log-only @@ -458,7 +475,7 @@ Source: [`packages/core/session/src/types.ts:201`](../packages/core/session/src/ 'step/start': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:199`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:178`](../packages/core/session/src/types.ts) ### `todo/*` @@ -471,7 +488,7 @@ Source: [`packages/core/session/src/types.ts:199`](../packages/core/session/src/ Types: [TodoItem](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:247`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts) ### `tool/*` @@ -488,7 +505,7 @@ Source: [`packages/core/session/src/types.ts:247`](../packages/core/session/src/ Types: [CallId](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:225`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:204`](../packages/core/session/src/types.ts) #### `tool/code-dispatch` — log-only @@ -561,7 +578,7 @@ Source: [`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/c } ``` -Source: [`packages/core/session/src/types.ts:237`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:216`](../packages/core/session/src/types.ts) ### `turn/*` @@ -579,20 +596,20 @@ Source: [`packages/core/session/src/types.ts:237`](../packages/core/session/src/ Types: [TurnEndReason](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:197`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:176`](../packages/core/session/src/types.ts) #### `turn/start` — log-only ```ts persistence-catalog /** - * Opens turn `turn`. `trigger` records what started the model loop. + * Opens turn `turn`. Every turn begins when the loop admits queued input; + * the following identified `user/message` event or batch records the + * admitted input. */ -'turn/start': { turn: number; trigger: TurnTrigger } +'turn/start': { turn: number } ``` -Types: [TurnTrigger](core-data-structures/session.md) - -Source: [`packages/core/session/src/types.ts:190`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:169`](../packages/core/session/src/types.ts) ### `user/*` @@ -610,4 +627,4 @@ Source: [`packages/core/session/src/types.ts:190`](../packages/core/session/src/ 'user/message': UserMessage ``` -Source: [`packages/core/session/src/types.ts:210`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:189`](../packages/core/session/src/types.ts) diff --git a/packages/acp/acp/README.i18n.yaml b/packages/acp/acp/README.i18n.yaml index d359613cd6..09636ae7ba 100644 --- a/packages/acp/acp/README.i18n.yaml +++ b/packages/acp/acp/README.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 packages/acp/acp/README.md -README.md: 1b188b994d17ce56e8d5df019ddef755338fcc88 -README.zh.md: c1e7d045b55119b62ad44d81071188e1ed6110d5 +README.md: 162e88265762652b5629c0e04786311c5b62583f +README.zh.md: 3fd914ecc5bf7b0e7069ba933b09db0a4a3cdfcd diff --git a/packages/acp/acp/README.md b/packages/acp/acp/README.md index 1b188b994d..162e882657 100644 --- a/packages/acp/acp/README.md +++ b/packages/acp/acp/README.md @@ -24,7 +24,7 @@ Both fields are optional so another agent/request listener may supply the target | `initialize` | Negotiates the supported version and advertises baseline-only prompts (no image, audio, or embedded-context capability). No session, editor, terminal, filesystem, or MCP capability is advertised. | | `authenticate` | No-op because the server advertises no authentication methods. | | `session/new` | Creates a fresh agent with an absolute primary `cwd`; empty `additionalDirectories` and `mcpServers` are accepted, non-empty values reject. | -| `session/prompt` | Concatenates text blocks, renders baseline resource links as bracketed textual references, rejects empty or beyond-baseline input, permits one in-flight request per session, and settles from that request's owning durable `turn/end`. | +| `session/prompt` | Concatenates text blocks, renders baseline resource links as bracketed textual references, rejects empty or beyond-baseline input, permits one in-flight request per session, and waits for the whole agent to become idle. Normal quiescence reports `end_turn`; explicit ACP cancellation or disposal reports `cancelled`. | | `session/cancel` | Cancels only the addressed agent and settles its pending prompt as `cancelled`; unknown ids are no-ops. | | `session/update` | Emits one `agent_message_chunk` per non-empty text block in a committed `assistant/message`. Raw deltas and non-message events are omitted. | | `session/request_permission` | Offers one-shot allow/reject choices for bridge-owned approval requests carrying a tool call id. Clients may answer automatically. | @@ -37,6 +37,8 @@ Committed-message output intentionally trades token-by-token latency for a clean Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, settles pending prompts, then disposes all owned agent handles in parallel and awaits their loop/session cleanup. An ACP-only plugin reload therefore leaves no orphan agent. +ACP requires each prompt response to carry a `stopReason`, but the bridge does not claim a prompt-specific turn outcome. Committed assistant messages stream across the owned activity, and steering or injected work may contribute before idle. Token-limit and model-error turn endings therefore do not become prompt-level ACP stop reasons. + ## Running `pnpm --dir /path/to/deepseek-harness run demo:acp` boots the repository's automation server composition. A parent harness can spawn it through [`@deepseek-ai/dsh-subagent-acp`](../../subagent/subagent-acp/README.md); other ACP clients need only the core methods above. diff --git a/packages/acp/acp/README.zh.md b/packages/acp/acp/README.zh.md index c1e7d045b5..3fd914ecc5 100644 --- a/packages/acp/acp/README.zh.md +++ b/packages/acp/acp/README.zh.md @@ -24,7 +24,7 @@ | `initialize` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 | | `authenticate` | 空操作，因为服务器不公布身份验证方法。 | | `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 | -| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并根据该请求所属的持久 `turn/end` 结算。 | +| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入 idle。正常完全停稳时报告 `end_turn`；显式 ACP 取消或资源释放时报告 `cancelled`。 | | `session/cancel` | 仅取消指定的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 | | `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 | | `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 | @@ -37,6 +37,8 @@ 客户端断开连接与 Cordis 的 dispose（资源释放）共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后并行对其拥有的全部 agent 句柄执行 dispose，并等待它们的循环／会话清理完成。因此，单独重载 ACP 插件不会遗留孤儿 agent。 +ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入 idle 前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限或模型错误而结束的轮次不会成为提示词级 ACP 停止原因。 + ## 运行 `pnpm --dir /path/to/deepseek-harness run demo:acp` 启动仓库的自动化服务器组合。父 harness 可以通过 [`@deepseek-ai/dsh-subagent-acp`](../../subagent/subagent-acp/README.md) spawn 它；其他 ACP 客户端只需上述核心方法。 diff --git a/packages/acp/acp/src/codec.ts b/packages/acp/acp/src/codec.ts index bdfa44bba5..68a577db0a 100644 --- a/packages/acp/acp/src/codec.ts +++ b/packages/acp/acp/src/codec.ts @@ -3,30 +3,7 @@ * @module @deepseek-ai/dsh-acp/codec */ -import type { ContentBlock as AcpContentBlock, StopReason } from '@agentclientprotocol/sdk' -import type { TurnEndReason } from '@deepseek-ai/dsh-session' - -/** - * Map a harness turn ending to ACP's terminal reason vocabulary. - * @param reason - harness turn outcome. - * @returns the closest legal ACP stop reason. - */ -export function turnEndToStopReason(reason: TurnEndReason): StopReason { - switch (reason.kind) { - case 'completed': - return 'end_turn' - case 'max-tokens': - return 'max_tokens' - case 'aborted': - case 'interrupted': - return 'cancelled' - case 'error': - return 'end_turn' - // TurnEndReason is merge-extensible; future variants still need a legal wire value. - default: - return 'end_turn' - } -} +import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk' /** * Flatten an ACP prompt's baseline blocks to text. Text blocks concatenate diff --git a/packages/acp/acp/src/index.ts b/packages/acp/acp/src/index.ts index f3dd59679a..925f675c7a 100644 --- a/packages/acp/acp/src/index.ts +++ b/packages/acp/acp/src/index.ts @@ -30,14 +30,13 @@ import { type PromptRequest, type PromptResponse, type SessionNotification, - type StopReason, type Stream, } from '@agentclientprotocol/sdk' import type { Agent } from '@deepseek-ai/dsh-agent' -import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' +import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' // Side-effect type import: declaration-merges the approval waterfall answered below. import type {} from '@deepseek-ai/dsh-user-approval' -import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason } from './codec.ts' +import { acpPromptToText, promptHasUnsupportedContent } from './codec.ts' export const name = 'acp' /** The bridge creates and owns agents; every other concern is carried by the agent composition. */ @@ -75,15 +74,7 @@ interface SessionRecord { dispose: () => Promise /** In-flight prompt and its captured turn number for exact settlement. */ inflight: { - resolve: (reason: StopReason) => void - reject: (error: Error) => void - turn: number | undefined - /** - * A failed turn's terminal reason, held until quiescence: a retry action - * closes the failed turn and opens a successor that adopts the prompt, so - * rejecting at `turn/end` would race the recovery. - */ - pendingError: Extract | undefined + cancelled: boolean } | undefined } @@ -125,18 +116,10 @@ export function apply(ctx: Context, config: AcpConfig): void { }) } - const settlePrompt = (record: SessionRecord, reason: StopReason): void => { + const cancelPrompt = (record: SessionRecord): void => { const inflight = record.inflight if (inflight === undefined) return - record.inflight = undefined - inflight.resolve(reason) - } - - const rejectFromError = ( - inflight: NonNullable, - reason: Extract, - ): void => { - inflight.reject(internalError(`turn failed: ${'failure' in reason ? reason.failure.message : reason.message}`)) + inflight.cancelled = true } // Emit only committed assistant text. Raw chunks, reasoning, tools, plans, @@ -145,41 +128,16 @@ export function apply(ctx: Context, config: AcpConfig): void { ctx.on('session/event', (session, event: SessionEvent) => { const record = sessions.get(session.header.id) if (record === undefined || record.agent.session !== session) return - try { - if (event.type === 'assistant/message') { - for (const block of event.data.message.content) { - if (block.type === 'text' && block.text.length > 0) { - notify({ - sessionId: record.agent.session.id, - update: { - sessionUpdate: 'agent_message_chunk', - content: { type: 'text', text: block.text }, - }, - }) - } - } - } - } finally { - const inflight = record.inflight - if (inflight !== undefined && event.type === 'turn/start') { - if (inflight.turn === undefined && event.data.trigger.kind === 'message' - && event.data.trigger.source.kind === 'user') { - inflight.turn = event.data.turn - } else if (inflight.pendingError !== undefined && event.data.trigger.kind === 'retry') { - // A recovery policy opened a retry turn on the failed history: the - // prompt rides it instead of rejecting on the failed turn's end. - inflight.turn = event.data.turn - inflight.pendingError = undefined - } - } else if (inflight !== undefined && event.type === 'turn/end' && inflight.turn === event.data.turn) { - if (event.data.reason.kind === 'error') { - // Hold the rejection: request recovery may adopt the prompt with a - // successor turn; quiescence without one delivers this error. - inflight.turn = undefined - inflight.pendingError = event.data.reason - } else { - record.inflight = undefined - inflight.resolve(turnEndToStopReason(event.data.reason)) + if (record.inflight !== undefined && event.type === 'assistant/message') { + for (const block of event.data.message.content) { + if (block.type === 'text' && block.text.length > 0) { + notify({ + sessionId: record.agent.session.id, + update: { + sessionUpdate: 'agent_message_chunk', + content: { type: 'text', text: block.text }, + }, + }) } } } @@ -265,49 +223,22 @@ export function apply(ctx: Context, config: AcpConfig): void { if (ctx.agents.get(record.agent.id) !== record.agent) { throw internalError('prompt was not queued: the agent was disposed outside the bridge') } - const stopReason = await new Promise((resolve, reject) => { - // Arm the slot before followup() so a listener-driven synchronous - // turn cannot slip past correlation; a synchronous followup() - // failure (invalid input) must free the slot again or the session - // would reject every later prompt as already in flight. - const inflight: NonNullable = { - resolve, reject, turn: undefined, pendingError: undefined, - } - record.inflight = inflight - try { - record.agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })) - // The machine's send() contains listener failures and accepts - // any typed input; this guards a future synchronous throw so the - // slot cannot wedge. - /* v8 ignore start -- future-proofing guard, see above */ - } catch (error: unknown) { - record.inflight = undefined - const detail = error instanceof Error ? error.message : String(error) - throw internalError(`prompt was not queued: ${detail}`) - } - /* v8 ignore stop */ - // Admission is pre-turn and retries outlive their failed turn, so a - // turnless slot settles only at quiescence: a held failure rejects - // (no retry adopted the prompt); no turn at all means admission - // discarded the prompt — report cancelled. - void record.agent.whenIdle().then(() => { - if (record.inflight !== inflight || inflight.turn !== undefined) return - record.inflight = undefined - if (inflight.pendingError !== undefined) { - rejectFromError(inflight, inflight.pendingError) - return - } - inflight.resolve('cancelled') - }) - }) - return { stopReason } + const inflight: NonNullable = { cancelled: false } + record.inflight = inflight + try { + record.agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })) + await record.agent.whenIdle() + return { stopReason: inflight.cancelled ? 'cancelled' : 'end_turn' } + } finally { + if (record.inflight === inflight) record.inflight = undefined + } }, cancel(params: CancelNotification): Promise { const record = sessions.get(SessionId(params.sessionId)) if (record === undefined) return Promise.resolve() + cancelPrompt(record) record.agent.cancel({ kind: 'user' }) - settlePrompt(record, 'cancelled') return Promise.resolve() }, } @@ -327,7 +258,7 @@ export function apply(ctx: Context, config: AcpConfig): void { const records = [...sessions.values()] sessions.clear() quiescing = Promise.all(records.map(async (record) => { - settlePrompt(record, 'cancelled') + cancelPrompt(record) await record.dispose() })).then(() => {}) return quiescing diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml index 78a933294a..1797e084d2 100644 --- a/packages/core/agent/README.i18n.yaml +++ b/packages/core/agent/README.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 packages/core/agent/README.md -README.md: 6bd5279ace93b6d2569833be6f102c854105c2eb -README.zh.md: cdbb0c0b70124e0037a0f7a7a03ddedf1e3b78d3 +README.md: 987386c363705ded9ab074ed012dd0219e6c8308 +README.zh.md: 593a079bcf93e4c7a0785fb58c6abcb5be53693c diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 860a60b96e..987386c363 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -50,9 +50,9 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves. -Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery; the loop closes the failed turn and opens one numbered retry turn. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement. +Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement. -`PromptDecision.additionalContexts` is an array of identified, frozen `UserMessage` values so every context keeps its own identity and source. The admitted prompt and every additional context become separate model-facing `user/message` events before the turn runs. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; replacing admitted content preserves the prompt's identity. +`PromptDecision.allow.messages` is the complete identified, frozen batch admitted by prompt interception. A listener that wraps a downstream allow preserves that batch unless it intentionally replaces it. Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md). @@ -60,17 +60,15 @@ Turn and step boundaries and the model token stream are durable `session/event` The handle every plugin programs against: -- `agent.send(message, options)` — the one delivery primitive over the (`target` × `wakeup`) matrix. `message` is an already identified, frozen `UserMessage`; callers normally create it with `createUserMessage()` before routing begins. `SendOptions` owns only the `target` and `wakeup` policy. Each accepted FIFO occurrence receives its own `InboxItemId`, even when callers reuse a `MessageId`; `agent/inbox/enqueue`/`update` and the terminal `dequeue` or `discard` carry that complete `InboxItem`. `target: 'next-turn'` queues one independent FIFO item that, if admitted, becomes the sole ordinary prompt in its turn. `target: 'next-step'` with `wakeup: true` submits steering, while `target: 'next-step'` with `wakeup: false` injects durable context without running the model. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale. -- `agent.updateInbox(itemId, action)` — synchronously edits or removes one still-pending queued occurrence. Edit keeps its `MessageId`, `InboxItemId`, source, and FIFO position while replacing frozen content; remove emits the occurrence's terminal discard. Steering and claimed occurrences return `not-found`. -- `agent.followup(input)` — the `next-turn`/wakeup preset of `send()`: queue an ordinary follow-up turn and wake the driver. -- `agent.steer(input)` — the `next-step`/wakeup preset: during prompt admission or an open turn, stage steering for the next safe boundary without dispatching `agent/prompt-submit`; outside that acceptance window, delegate to a woken follow-up. Admission failure leaves staged steering for retry or a later admitted prompt, while cancellation or disposal may discard it. -- `agent.inject(input)` — the `next-step`/no-wakeup preset: append model-facing context without running the model; the next request sees a verbatim user-role message whose provenance is carried by the required `input.source`. During prompt admission or an open turn, injection waits in the outbox for the next safe boundary. Outside that acceptance window, it appends immediately without opening a turn; a context-only admission batch takes this fallback if admission closes without a turn, while context staged beside steering remains pending with it. Persistence reacts to `session/event` independently. Injection emits no `agent/inbox/*` event. -- `agent.acceptsNextStep` — whether steering would currently join prompt admission or the open turn. Use this narrower routing predicate when a caller must choose between steering and a fresh admitted prompt; `status === 'running'` also covers admission exit and turn settlement. -- `agent.cancel(cause, options?)` — cancel the active turn and, unless `options.keepInbox`, ALL pending work. Callers must choose the `user | parent` cause explicitly; an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; dropped items are reported on `agent/inbox/discard`, and observers may synchronize state but cannot veto cancellation. `keepInbox: true` aborts the turn but preserves queued and steering items (no discard, and un-started work is not dropped). The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`. -- `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly. -- `agent.session`, `agent.status`, `agent.options`, `agent.id` +- `agent.inbox` — the agent-owned projection of durable `agent/inbox/spliced` events. `nextTurn` and `nextStep` expose pending `UserMessage` values; `splice(target, start, deleteCount, inserted, outcome?)` uses standard splice coordinates to insert, edit, remove, admit, or cancel them. `MessageId` is the only occurrence identity and must remain unique while pending. +- `agent.followup(message)` — queue an ordinary `next-turn` message and wake the driver. It returns no completion handle; the message id identifies inbox and admission facts, not a later output or `turn/end`. +- `agent.steer(message)` — queue waking `next-step` input. An idle driver schedules a turn; collecting and running drivers consume it at their next step boundary. +- `agent.inject(message)` — queue non-waking `next-step` context. During admission or an open turn it waits for the next safe log position; otherwise it appends immediately without opening a turn. +- `agent.cancel(cause, options?)` — cancel the active driver and, unless `options.keepInbox`, durably cancel all pending inbox work. Idle cancellation is a no-op. +- `agent.whenIdle()` — observe whole-agent quiescence, including replacement work scheduled before the current driver retires. It does not settle any particular message. +- `agent.session`, `agent.status`, `agent.options`, `agent.id`, `agent.ctx` -`running` describes a driver-wide drain interval, not proof that a turn is still open; it can cover turn close, the durability checkpoint, and consecutive queued turns. +`running` describes a driver-wide drain interval, not proof that a turn is still open; it can cover turn close, the durability checkpoint, and consecutive queued turns. Only a caller that owns a complete interval may summarize it as a run result ([proposal](../../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). ### Extension points diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md index ff76538b9e..593a079bcf 100644 --- a/packages/core/agent/README.zh.md +++ b/packages/core/agent/README.zh.md @@ -50,9 +50,9 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供， 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。 -大多数拦截点都是协作式 waterfall（瀑布式事件）。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：失败步骤关闭后，它接收确切错误、规范化失败事实和信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。 +大多数拦截点都是协作式 waterfall（瀑布式事件）。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。 -`PromptDecision.additionalContexts` 是由带标识且冻结的 `UserMessage` 值组成的数组，因此每个上下文都保留自己的标识和来源。获准的提示词与每个附加上下文都会在轮次运行前成为各自独立、面向模型的 `user/message` 事件。包装下游允许决策的监听器会保留其 `content` 与 `additionalContexts`，除非有意替换任一字段；替换获准内容时仍会保留提示词的标识。 +`PromptDecision.allow.messages` 是提示词拦截所准入的完整、带标识且冻结的批次。包装下游 allow 的监听器会保留该批次，除非有意替换它。 轮次和步骤边界以及模型 token 流是持久 `session/event` 事实，而不是镜像的 `agent/*` 通知。消费方从会话事件流读取 `turn/*`、`step/*` 和 `assistant/chunk`；工具策略与结果观测属于 [`dsh-tools`](../tools/README.md) 记录的完整流水线。 @@ -60,17 +60,15 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供， 每个插件面向的 handle： -- `agent.send(message, options)`：覆盖（`target` × `wakeup`）矩阵的唯一投递原语。`message` 是已有标识且已冻结的 `UserMessage`；调用方通常会在开始路由前使用 `createUserMessage()` 创建它。`SendOptions` 只持有 `target` 与 `wakeup` 策略。每次获准进入 FIFO 的项都会获得独立的 `InboxItemId`，即使调用方复用了同一个 `MessageId`；`agent/inbox/enqueue`／`update` 及终态 `dequeue` 或 `discard` 都会携带这一完整 `InboxItem`。`target: 'next-turn'` 排队一条独立 FIFO 项，获准后成为其轮次中唯一的普通提示词。`target: 'next-step'` 且 `wakeup: true` 提交 steering（中途引导），而 `target: 'next-step'` 且 `wakeup: false` 注入持久上下文，不运行模型。轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。 -- `agent.updateInbox(itemId, action)`：同步编辑或移除一个仍处于待处理状态的 queued 入队项。编辑会替换已冻结的内容，同时保留其 `MessageId`、`InboxItemId`、来源与 FIFO 位置；移除会发出该项的终态 discard。steering 项和已被认领的项会返回 `not-found`。 -- `agent.followup(input)`：`send()` 的 `next-turn`／wakeup 预设：排队一个普通后续轮次并唤醒驱动器。 -- `agent.steer(input)`：`next-step`／wakeup 预设：提示词接纳期间或轮次打开时，为下一个安全边界暂存 steering，且不分发 `agent/prompt-submit`；该接收窗口之外则委托给会唤醒的后续轮次。接纳失败会保留暂存的 steering，以供重试或之后获准的提示词使用，而取消或 dispose 可能丢弃它。 -- `agent.inject(input)`：`next-step`／不唤醒预设：追加面向模型的上下文而不运行模型；下一次请求会看到一条逐字的 user role 消息，其来源由必填的 `input.source` 携带。提示词接纳期间或轮次打开时，注入会在 outbox 中等待下一个安全边界。该接收窗口之外，它会立即追加而不开启轮次；如果接纳结束却未开启轮次，仅含上下文的接纳批次会采用这一回退，而与 steering 一同暂存的上下文则会随其继续待处理。持久化独立地响应 `session/event`。注入不发出 `agent/inbox/*` 事件。 -- `agent.acceptsNextStep`：steering 当前是否会加入提示词接纳或已打开的轮次。当调用方必须在 steering 与新接纳的提示词之间选择时，应使用这一更窄的路由判定；`status === 'running'` 还涵盖接纳收尾与轮次结算阶段。 -- `agent.cancel(cause, options?)`：取消活动轮次，并在未设置 `options.keepInbox` 时取消全部待处理工作。调用方必须显式选择 `user | parent` 原因；活动持有者会在中止前把其判别字段复制为已分离、冻结的信号原因。有效调用会在清除排队与 steering 工作前，随原因发出 `agent/cancel-requested`；丢弃项在 `agent/inbox/discard` 上报告，观察方可以同步状态，但不能 veto 取消。`keepInbox: true` 会中止轮次，但保留排队与 steering 项（不丢弃，且不删除尚未开始的工作）。同进程类型化 seam 不会为无类型调用方添加运行时校验或兼容回退。重复取消活动轮次时，首个信号生效；空闲取消是安全空操作，不发通知。ACP 映射到 `user`，进程内父传播映射到 `parent`。原因只存在于运行时；持久 `turn/end` 保持粗粒度的 `aborted`。 -- `agent.whenIdle()`：agent 从 `running` 结算后达到完全停稳时解析（idle ⇒ 立即；disposed ⇒ 等待循环退出）。这是非拥有者的完全停稳观测钩子：观察工作结算，但不 teardown agent。Teardown 独立存在；生命周期拥有者通过 `AgentHandle.dispose()` 停止并注销，并直接等待循环退出。 -- `agent.session`、`agent.status`、`agent.options`、`agent.id` +- `agent.inbox`：agent 所拥有的持久 `agent/inbox/spliced` 事件投影。`nextTurn` 与 `nextStep` 暴露待处理的 `UserMessage` 值；`splice(target, start, deleteCount, inserted, outcome?)` 使用标准 splice 坐标插入、编辑、移除、准入或取消消息。`MessageId` 是唯一的入队项标识，在消息待处理期间必须保持唯一。 +- `agent.followup(message)`：将一条普通 `next-turn` 消息排队并唤醒驱动器。它不返回完成 handle；消息 id 标识 inbox 和准入事实，而不标识之后的输出或 `turn/end`。 +- `agent.steer(message)`：将会唤醒的 `next-step` 输入排队。空闲驱动器会调度一个轮次；collecting 和 running 驱动器会在各自的下一步骤边界消费该输入。 +- `agent.inject(message)`：将不会唤醒的 `next-step` 上下文排队。在准入期间或轮次打开时，它会等待下一个安全日志位置；否则立即追加，且不打开轮次。 +- `agent.cancel(cause, options?)`：取消活跃驱动器，并在未设置 `options.keepInbox` 时持久取消全部待处理 inbox 工作。空闲取消是空操作。 +- `agent.whenIdle()`：观察整个 agent 达到完全停稳，包括当前驱动器退役前调度的替代工作。它不结算任何特定消息。 +- `agent.session`、`agent.status`、`agent.options`、`agent.id`、`agent.ctx` -`running` 描述驱动器范围的 drain 区间，而不是轮次仍打开的证明；它可以覆盖轮次关闭、持久性检查点和连续的排队轮次。 +`running` 描述驱动器范围的 drain 区间，而不是轮次仍打开的证明；它可以覆盖轮次关闭、持久性检查点和连续的排队轮次。只有拥有完整区间的调用方才能将其概括为一次运行的结果（[提案](../../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。 ### 扩展点 diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml index 56895397fc..4dd54b4261 100644 --- a/packages/core/session/README.i18n.yaml +++ b/packages/core/session/README.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 packages/core/session/README.md -README.md: af93791dfc17f66b79b376ba32ec657761ec63bc -README.zh.md: ed9bba76d307a764a20c7cc4a3d2716c55a1acc0 +README.md: 8d65bf85b1b9c36568f9a972afd84695d3301649 +README.zh.md: cf16b01b7855b6cbfe66a83fb9b1183a837b7db8 diff --git a/packages/core/session/README.md b/packages/core/session/README.md index af93791dfc..8d65bf85b1 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -70,13 +70,13 @@ A `user/message` stores the complete `UserMessage` directly, including the ident ### Session event vocabulary (`types.ts`) -The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Provider/model/replay provenance rides on `assistant/message`; an operational error's step is on `turn/end.reason` for `kind: 'error'`, with structured provider facts for a final model-request failure. +The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Provider/model/replay provenance rides on `assistant/message`. Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, bounded recovery's non-surface `llm/retry`, the hook bridges' `hook/*`); merged members appear in the same catalog. A plugin owns the relational invariant for its merged events, including whether a log-only event may appear between turns. A producer that requires durability appends through `Session` and then awaits `ctx.sessions.flush(session)` without fabricating an execution turn. -Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types for typed turn boundaries — `kind`-tagged instead of strings). A final model-request error retains one structured `LlmFailure`; other turn errors retain message/code, and both identify the failed step. +Also defines `TurnEndReasonMap`, the merge-extensible `kind`-tagged sum type for turn endings. `turn/start` carries only the turn number; the following admitted `user/message` batch records its input, while `llm/retry` records request recovery. -An interrupted live turn ends with the coarse `{ kind: 'aborted' }` outcome. Caller identity belongs to the Agent's runtime cancellation signal rather than the durable transcript; disposal remains the separate `{ kind: 'disposed' }` terminal state. +An interrupted live turn ends with `{ kind: 'aborted', reason: AgentCancelCause }`, preserving the typed cancellation cause in the durable transcript. A turn failure carries `{ kind: 'error', error }`; crash recovery alone synthesizes `{ kind: 'interrupted' }`. Every `SessionEvent` carries two optional top-level fields (structural metadata): diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md index ed9bba76d3..cf16b01b78 100644 --- a/packages/core/session/README.zh.md +++ b/packages/core/session/README.zh.md @@ -70,13 +70,13 @@ ### 会话事件词汇（`types.ts`） -生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记和溯源信息。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。提供方／模型／回放溯源信息随 `assistant/message` 一同保存；运行错误的步骤记录在 `turn/end.reason` 上（此时为 `kind: 'error'`），最终模型请求失败时还包含结构化的提供方事实。 +生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记和溯源信息。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。提供方／模型／回放溯源信息随 `assistant/message` 一同保存。 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。 -此包还定义 `TurnTriggerMap` 和 `TurnEndReasonMap`（用于类型化轮次边界、可合并扩展的和类型；以 `kind` 为标签而不是字符串）。最终模型请求错误保留一个结构化 `LlmFailure`；其他轮次错误保留消息／代码，两者均标识失败步骤。 +此包还定义 `TurnEndReasonMap`，即用于轮次结束、可合并扩展且以 `kind` 为标签的和类型。`turn/start` 只携带轮次编号；之后已准入的 `user/message` 批次记录其输入，`llm/retry` 则记录请求恢复。 -被中断的实时轮次以粗粒度的 `{ kind: 'aborted' }` 结果结束。调用方身份属于 Agent 的运行时取消信号，不属于持久 transcript（文本记录）；资源释放仍是独立的 `{ kind: 'disposed' }` 终态。 +被中断的实时轮次以 `{ kind: 'aborted', reason: AgentCancelCause }` 结束，在持久 transcript（文本记录）中保留类型化取消原因。轮次失败携带 `{ kind: 'error', error }`；只有崩溃恢复会合成 `{ kind: 'interrupted' }`。 每个 `SessionEvent` 都有两个可选顶层字段（结构元数据）： diff --git a/packages/examples/cli-demo/README.i18n.yaml b/packages/examples/cli-demo/README.i18n.yaml index f73cad16df..112ca27929 100644 --- a/packages/examples/cli-demo/README.i18n.yaml +++ b/packages/examples/cli-demo/README.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 packages/examples/cli-demo/README.md -README.md: b8f2bde962738a1a23f0e57218ab0f90e8e0b705 -README.zh.md: 0e03375ced4e087d44eed7ff33666abf1f2cec10 +README.md: 6e46ae81421c23806524b0784a976e9f3c8eeab8 +README.zh.md: 4dc5d482e17e87177e7a1ae3a39435879cdd76ce diff --git a/packages/examples/cli-demo/README.md b/packages/examples/cli-demo/README.md index b8f2bde962..6e46ae8142 100644 --- a/packages/examples/cli-demo/README.md +++ b/packages/examples/cli-demo/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -Headless one-shot app and bin for running one agent task without an interactive UI or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin submits the task, waits for its durable turn ending, renders the selected output, disposes to quiescence, and exits. +Headless one-shot app and bin for running one agent task without an interactive UI or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin owns one idle-to-idle activity interval, renders its selected output, disposes to quiescence, and exits. The package mounts no console logger, interactive UI, user-interaction service, or `ask_user_question` tool. Stdout is reserved for the selected output format; diagnostics use stderr. @@ -44,12 +44,12 @@ Loader configs resolve bare package specifiers through the optional native helpe ### Output formats - `text` writes the last assistant message containing text, followed by one newline. -- `json` writes one DSH-native result record: `{ type: "result", success, sessionId, turn, result, reason, usage? }`. `usage` sums each model step in the task turn once, including billed failed retry attempts that produced usage without a committed assistant message. -- `stream-json` writes each canonical event from the top-level session's task turn as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results. +- `json` writes one DSH-native result record: `{ type: "result", sessionId, output, usage? }`. `output` is the last committed assistant text in the activity interval. `usage` sums each model step in that interval once, including billed failed attempts that produced usage without a committed assistant message. +- `stream-json` writes each canonical event from the top-level session's owned activity interval as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results. -Only `reason.kind === "completed"` exits successfully. Other durable turn endings still emit partial text or a result record, add a stderr diagnostic, and exit nonzero. Argument and boot failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively. +Normal idle completion exits successfully without assigning a turn reason to the task. Argument, boot, observation, and persistence failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively. -The task turn is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits. +The owned activity is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits. ## Operational safety @@ -57,11 +57,11 @@ The headless-agent leaf supplies local bash, filesystem, skill, subagent, workfl ## Model Experience -### One-shot task turn +### One-shot activity #### What the model sees -The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the same turn. +The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the owned activity. #### Token effect @@ -75,4 +75,4 @@ Tool-round history is append-only while the one-shot agent's prompt, schemas, mo - **One fresh top-level session per process** — its workspace cwd is the launch directory; there is no resume, second prompt, stdin context, or concurrent top-level session in this app. - **No interactive question or approval provider** — tools that require a human answer cannot complete unless a different leaf composes a non-interactive provider with explicit policy. -- **Streaming is top-level-session-only** — child sessions are not flattened into the stream, and aggregate usage covers only model steps recorded on the parent task turn. +- **Streaming is top-level-session-only** — child sessions are not flattened into the stream, and aggregate usage covers only model steps recorded on the parent activity interval. diff --git a/packages/examples/cli-demo/README.zh.md b/packages/examples/cli-demo/README.zh.md index 0e03375ced..4dc5d482e1 100644 --- a/packages/examples/cli-demo/README.zh.md +++ b/packages/examples/cli-demo/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -无头单次应用及 bin，用于在没有交互式 UI 或编辑器客户端的情况下运行一项 agent（智能体）任务。它组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、JSONL 持久化，以及恰好一个新建顶层 agent。bin 提交任务，等待其已持久化的轮次结束状态，渲染所选输出，执行 dispose（资源释放）直至完全停稳，然后退出。 +无头单次应用及 bin，用于在没有交互式 UI 或编辑器客户端的情况下运行一项 agent（智能体）任务。它组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、JSONL 持久化，以及恰好一个新建顶层 agent。bin 拥有一个从 idle 到 idle 的活动区间，渲染所选输出，执行 dispose（资源释放）直至完全停稳，然后退出。 该包（package）不挂载 console logger、交互式 UI、用户交互服务或 `ask_user_question` 工具。Stdout 专用于所选输出格式；诊断使用 stderr。 @@ -44,12 +44,12 @@ loader 配置通过仓库安装的可选原生辅助程序解析裸包说明符 ### 输出格式 - `text` 写入最后一条含文本的 assistant 消息，后跟一个换行符。 -- `json` 写入一条 DSH 原生结果记录：`{ type: "result", success, sessionId, turn, result, reason, usage? }`。`usage` 对任务轮次中的每个模型步骤恰好求和一次，包括产生用量但没有提交 assistant 消息的已计费失败重试。 -- `stream-json` 将顶层会话任务轮次中的每个规范事件写成 `{ type: "session_event", sessionId, event }`，然后写入同一结果记录。子 agent 活动只通过父工具事件与结果出现。 +- `json` 写入一条 DSH 原生结果记录：`{ type: "result", sessionId, output, usage? }`。`output` 是活动区间内最后提交的 assistant 文本。`usage` 对该区间中的每个模型步骤恰好求和一次，包括产生用量但没有提交 assistant 消息的已计费失败尝试。 +- `stream-json` 将顶层会话自有活动区间中的每个规范事件写成 `{ type: "session_event", sessionId, event }`，然后写入同一结果记录。子 agent 活动只通过父工具事件与结果出现。 -只有 `reason.kind === "completed"` 会成功退出。其他已持久化的轮次结束状态仍会输出部分文本或结果记录，向 stderr 添加诊断，并以非零状态退出。参数和启动失败会让 stdout 保持为空。SIGINT 与 SIGTERM 会取消正在进行的工作，等待 dispose 完成，并分别以 130 和 143 退出。 +正常进入 idle 会成功退出，不会为该任务指定轮次原因。参数、启动、观测和持久化失败会让 stdout 保持为空。SIGINT 与 SIGTERM 会取消正在进行的工作，等待 dispose 完成，并分别以 130 和 143 退出。 -任务轮次会在最终输出前显式刷新。进程退出后，会话日志仍保留在 `persistenceRoot` 下。 +自有活动会在最终输出前显式刷新。进程退出后，会话日志仍保留在 `persistenceRoot` 下。 ## 操作安全 @@ -57,11 +57,11 @@ headless-agent 叶节点提供本地 bash、文件系统、skill、subagent、 ## 模型体验 -### 单次任务轮次 +### 单次活动 #### 模型看到的内容 -任务位置参数会成为一条用户消息。通过 `dsh-agent-spine-demo`，顶层 agent 还会收到已配置的工作区指令与 persona、skill 目录、可见工具 schema，以及同一轮次后续步骤所需的保留工具结果。 +任务位置参数会成为一条用户消息。通过 `dsh-agent-spine-demo`，顶层 agent 还会收到已配置的工作区指令与 persona、skill 目录、可见工具 schema，以及自有活动后续步骤所需的保留工具结果。 #### Token 影响 @@ -75,4 +75,4 @@ headless-agent 叶节点提供本地 bash、文件系统、skill、subagent、 - **每个进程只创建一个新的顶层会话**：其工作区 cwd 是启动目录；此应用不支持恢复、第二条提示词、stdin 上下文或并发顶层会话。 - **没有交互式问题或批准提供方**：需要人工回答的工具无法完成，除非其他叶节点按显式策略组合一个非交互式提供方。 -- **流式输出仅限顶层会话**：子会话不会平铺到流中，聚合用量只涵盖父任务轮次记录的模型步骤。 +- **流式输出仅限顶层会话**：子会话不会平铺到流中，聚合用量只涵盖父活动区间记录的模型步骤。 diff --git a/packages/examples/cli-demo/src/cli.ts b/packages/examples/cli-demo/src/cli.ts index 7dfb4b82ff..f40cd03f9a 100644 --- a/packages/examples/cli-demo/src/cli.ts +++ b/packages/examples/cli-demo/src/cli.ts @@ -8,7 +8,7 @@ import { parseArgs } from 'node:util' import type { Context } from 'cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import { createUserMessage, type TokenUsage } from '@deepseek-ai/dsh-llm' -import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot' const CLI_NAME = 'dsh-cli-demo' @@ -32,11 +32,8 @@ export type CliCommand = /** DSH-native final record emitted by JSON modes. */ export interface CliResult { readonly type: 'result' - readonly success: boolean readonly sessionId: string - readonly turn: number - readonly result: string - readonly reason: TurnEndReason + readonly output: string readonly usage?: TokenUsage } @@ -203,13 +200,8 @@ async function waitForStartupIdle(agent: Agent, signal?: AbortSignal): Promise() let outputError: Error | undefined - let resolveTurn!: () => void - let rejectTurn!: (error: Error) => void - let firstTurnEnded = false - const turnEnded = new Promise((resolve, reject) => { - resolveTurn = resolve - rejectTurn = reject - }) - - const settleResolved = (): void => { - if (firstTurnEnded) return - firstTurnEnded = true - resolveTurn() - } - const settleRejected = (error: Error): void => { - // The once-registered abort listener is the only rejecter, and a settled - // prompt makes targetTurn defined so onAbort skips rejection entirely; - // kept for symmetry with settleResolved. - /* v8 ignore next -- unreachable second settlement, see above */ - if (firstTurnEnded) return - firstTurnEnded = true - rejectTurn(error) - } + let interrupted: CliInterruptedError | undefined const observe = (sessionId: string, event: SessionEvent): void => { if (outputError !== undefined || options.onEvent === undefined) return try { @@ -261,38 +232,29 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise const disposeListener = ctx.on('session/event', (session, event) => { if (session !== agent.session) return - if (targetTurn === undefined) { - if (event.type !== 'turn/start' || event.data.trigger.kind !== 'message') return - targetTurn = event.data.turn - } else if (event.type === 'turn/start' && event.data.trigger.kind === 'retry' - && reason?.kind === 'error') { - targetTurn = event.data.turn - reason = undefined + if (!received) { + if (event.type !== 'agent/inbox/spliced' + || !event.data.inserted.some(inserted => inserted.id === message.id)) return + received = true } observe(session.id, event) - if (event.type === 'assistant/chunk' - && event.data.turn === targetTurn - && event.data.chunk.type === 'usage') { + if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') { usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.chunk.usage) } - if (event.type === 'assistant/message' && event.data.turn === targetTurn) { - result = assistantText(event) ?? result + if (event.type === 'assistant/message') { + output = assistantText(event) ?? output if (event.data.usage !== undefined) { usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.usage) } } - if (event.type === 'turn/end' && event.data.turn === targetTurn) { - reason = event.data.reason - settleResolved() - } }) const signal = options.signal let onAbort: (() => void) | undefined if (signal !== undefined) { onAbort = (): void => { + interrupted ??= new CliInterruptedError(interruptionReason(signal)) agent.cancel({ kind: 'user' }) - if (targetTurn === undefined) settleRejected(new CliInterruptedError(interruptionReason(signal))) } signal.addEventListener('abort', onAbort, { once: true }) /* v8 ignore next -- closes the race between startup-idle completion and listener registration */ @@ -300,37 +262,27 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise } try { - /* v8 ignore next -- skips send only when cancellation wins the listener-registration race above */ - if (!firstTurnEnded) { // oxlint-disable-line typescript/no-unnecessary-condition - agent.followup(createUserMessage({ content: [{ type: 'text', text: options.task }], source: { kind: 'user' } })) - } - await turnEnded + if (interrupted === undefined) agent.followup(message) + await agent.whenIdle() } finally { if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort) - await agent.whenIdle() disposeListener() } - /* v8 ignore next 3 -- turnEnded resolves only from the matching branch that assigns both values */ - if (targetTurn === undefined || reason === undefined) { - throw new Error('task ended without a correlated turn/end event') - } await ctx.sessions.flush(agent.session) if (outputError !== undefined) throw outputError + if (interrupted !== undefined) throw interrupted const usage = [...usageByStep.values()].reduce(addUsage, undefined) return { type: 'result', - success: reason.kind === 'completed', sessionId: agent.session.id, - turn: targetTurn, - result, - reason, + output, ...usage === undefined ? {} : { usage }, } } function renderResult(outputFormat: OutputFormat, result: CliResult): string { - return outputFormat === 'text' ? `${result.result}\n` : `${JSON.stringify(result)}\n` + return outputFormat === 'text' ? `${result.output}\n` : `${JSON.stringify(result)}\n` } /** @@ -380,23 +332,6 @@ async function bootInterruptibly( } } -/** - * Render a non-completed turn reason for stderr. - * @param reason - durable turn ending to describe. - * @returns a concise diagnostic fragment. - */ -export function formatTurnFailure(reason: TurnEndReason): string { - switch (reason.kind) { - case 'completed': return 'completed' - case 'aborted': return 'was aborted' - case 'error': return `failed at step ${reason.step}: ${'failure' in reason ? reason.failure.message : reason.message}` - case 'disposed': return 'was disposed' - case 'max-tokens': return 'reached the model output-token limit' - case 'interrupted': return 'was interrupted during persistence recovery' - default: return `ended with ${JSON.stringify(reason)}` - } -} - /** * Execute one CLI invocation. Argument and boot failures never write stdout; * context disposal is awaited before return, and its failure does not replace @@ -451,8 +386,7 @@ export async function executeCli(args: readonly string[], runtime: CliRuntime = : {}, }) writeStdout(renderResult(command.outputFormat, result)) - exitCode = result.success ? 0 : 1 - if (!result.success) diagnostic = `${CLI_NAME}: turn ${result.turn} ${formatTurnFailure(result.reason)}\n` + exitCode = 0 } catch (error: unknown) { diagnostic = `${CLI_NAME}: ${toError(error).message}\n` } finally { diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml index c0c9f24f89..71aa6413f7 100644 --- a/packages/goal/goal-session/README.i18n.yaml +++ b/packages/goal/goal-session/README.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 packages/goal/goal-session/README.md -README.md: 6a1c3b9455c93762c2458109c753588ce9a08d9a -README.zh.md: 4162411bf2dbeebbec8da6433c71e176057c4277 +README.md: 7c56f295bb7a587913b201db8860d11605886a64 +README.zh.md: e41afbc4142eee6a8a50e43b4fa6ca34ecc28641 diff --git a/packages/goal/goal-session/README.md b/packages/goal/goal-session/README.md index 6a1c3b9455..7c56f295bb 100644 --- a/packages/goal/goal-session/README.md +++ b/packages/goal/goal-session/README.md @@ -23,30 +23,21 @@ The plugin has no tunable configuration. `maxGoalRounds` belongs to the goal def When an exact live agent is idle with an active, armed goal and remaining capacity, the driver first checkpoints pending goal mutations, then reserves `roundsStarted + 1` for the current `{ goalId, revision }`. It queues one `` prompt with `GoalMessageSource`. Admission through `agent/prompt-submit` verifies the complete queued record and current goal both before and after downstream prompt hooks; only the accepted `user/message` increments `roundsStarted`. A reservation rejected as stale does not consume the round number. -One goal round owns one ordinary session turn, and that turn may contain several model/tool steps. The driver pairs a reservation only with a `message` turn carrying its exact `GoalMessageSource`; merge-extensible plugin turn triggers do not admit or replace that reservation. Human messages remain ordinary turns and do not consume the goal cap. If human work enters the inbox before a reservation or joins its pending batch, automatic work yields until that work settles; a pending automatic prompt in a mixed batch is rejected and re-reserved only after the agent becomes idle. +`MessageId` identifies the reserved message through durable inbox insertion and admission; it does not identify a turn result. Human messages do not consume the goal cap. If human work enters the inbox before a reservation or joins its pending batch, automatic work yields until the agent becomes idle; a pending automatic prompt in a mixed batch is rejected and re-reserved only after that checkpoint. The retained prompt names the JSON-quoted objective and `round/maxGoalRounds`, treats the current workspace, tool results, and durable session state as authoritative, requires evidence before completion, and tells the model to leave the goal active when work remains. Quoting preserves multiline or tag-like objective text as data. Goal lifecycle mutations still require the independent authority checks in `dsh-tool-goal`. -## Settlement policy +## Idle checkpoint -| Durable turn outcome | Goal action | Automatic retry | -|---|---|---| -| `completed` with goal still active and armed | admit the next round, or block with code `round-limit` at the cap | yes | -| cancellation of a reserved/admitted goal round, or its `aborted` outcome | `paused` | no | -| cancellation with no goal-round attempt | keep durable phase; disarm activation | no | -| `error` with `RATE_LIMIT` or `QUOTA` | `blocked` with code `usage-limited` | no | -| other `error`, `max-tokens`, or a non-stale prompt rejection | `blocked` with a diagnostic code and message | no | -| durability failure, disposal, interruption, or unknown future outcome | disarm or block for inspection | no | - -A goal mutation made during its round supersedes settlement of the older revision. Completion, pause, blocking, and edits therefore remain authoritative even if the physical turn closes afterward. No abnormal result is retried automatically. +At whole-agent idle, durable goal phase and revision are authoritative. An active, armed goal with capacity reserves its next round; completion, pause, blocking, and edits suppress continuation. The driver does not classify the preceding activity by correlating the goal message with `turn/end`, so provider errors and token limits are not prompt-level goal outcomes. ## Lifecycle and durability -`goal/changed` creates a durability obligation. Before queuing work, the driver awaits `ctx.sessions.flush()` and rechecks both the goal revision and competing input after the await. A closing flush failure arrives through `agent/error`; the driver associates it with the exact closed turn even if a later one-shot injection has appended another turn, then disarms before another round can start. +`goal/changed` creates a durability obligation. Before queuing work, the driver awaits `ctx.sessions.flush()` and rechecks both the goal revision and competing input after the await. A flush failure arriving through `agent/error` disarms continuation before another round can start. Activation is never inherited when this plugin loads over an existing agent. `GoalService.disarm()` removes process-local authority without changing durable phase, revision, or history; explicit human-authorized resume records the later reactivation. The same rule applies after session resume and fork through the goal domain's `agent/session-start` handling. -Cancellation is observe-before-act: the concrete loop emits `agent/cancel-requested` with its typed cause before clearing queues or aborting the turn. The plugin durably pauses an active goal only when the cancellation owns a reserved or admitted goal attempt; cancellation of unrelated human work merely disarms process-local continuation. If the pause mutation fails, the driver falls back to disarming. Plugin teardown closes admission, disarms every live goal, cancels an admitted round with the `parent` cause, and awaits the driver plus agent quiescence while its event fence remains installed. +Cancellation removes pending inbox work or leaves an agent-wide aborted state. At the next idle checkpoint the driver pauses a goal with a reserved or admitted attempt so cancellation cannot auto-restart it; cancellation unrelated to a goal attempt only disarms process-local continuation. If the pause mutation fails, the driver falls back to disarming. Plugin teardown closes admission, disarms every live goal, cancels active work with the `parent` cause, and awaits the driver plus agent quiescence while its event fence remains installed. ## Model Experience @@ -69,5 +60,5 @@ Append-only within an epoch: each admitted round extends the existing conversati - **No independent evaluator** — the model-facing goal policy decides when evidence is sufficient for completion and whether a blocker is semantically unchanged; evaluator-backed certification remains deferred. - **Same-session execution only** — this package deliberately does not spawn a fresh agent, fork a session prefix, or implement Ralph-style independent attempts; that workflow belongs to its own plugin layer. - **Accepted-queue unload race** — Cordis plugin unload is asynchronous. A goal prompt already accepted by the agent inbox can begin and consume its round before unload starts; teardown then cancels the request, disarms the goal, and awaits quiescence. No later round starts. -- **Round cap, not resource budget** — token, currency, time, and provider quota policies remain independent; observed `RATE_LIMIT` and `QUOTA` stops only map into the blocked reason code `usage-limited`. +- **Round cap, not resource budget** — token, currency, time, and provider quota policies remain independent. Their session events are not attributed to the goal message or mapped into goal blocker codes. - **No abnormal auto-retry** — transient provider and persistence failures require a later human-authorized resume rather than an implicit retry policy. diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md index 4162411bf2..e41afbc414 100644 --- a/packages/goal/goal-session/README.zh.md +++ b/packages/goal/goal-session/README.zh.md @@ -23,30 +23,21 @@ 当对应的活跃 agent 实例处于 idle 状态，且目标 phase 为 active、已启用续行并有剩余容量时，驱动器先为待处理 goal 变更创建检查点，再预留 `roundsStarted + 1`，对应当前 `{ goalId, revision }`。它会排入一条 `` 提示词，并携带 `GoalMessageSource`。通过 `agent/prompt-submit` 准入时，会在下游提示词钩子前后验证完整的排队记录与当前 goal；只有被接受的 `user/message` 才会增加 `roundsStarted`。因陈旧而被拒绝的预留不会消耗 Round 编号。 -一个 Goal Round 对应一个普通会话轮次，该轮次可以包含多个模型／工具步骤。驱动器只会把预留与 `message` 轮次配对，且该轮次必须携带完全相同的 `GoalMessageSource`；可通过声明合并扩展的插件轮次触发器不会准入或替换该预留。用户消息仍是普通轮次，不消耗 goal 上限。如果用户工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到用户工作结算；混合批次中的待处理自动提示词会被拒绝，只有 agent 再次 idle 后才重新预留。 +`MessageId` 通过持久 inbox 插入和准入来标识预留消息；它不标识轮次结果。用户消息不消耗 goal 上限。如果用户工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到 agent 进入 idle；混合批次中的待处理自动提示词会被拒绝，只有完成该检查点后才重新预留。 保留的提示词会点明经过 JSON 引用的目标与 `round/maxGoalRounds`，将当前工作区、工具结果和持久会话状态视为权威信息，要求在完成前提供证据，并要求在工作仍未完成时保持目标 active。引用可将多行或形似标签的目标文本保留为数据。goal 生命周期变更仍必须通过 `dsh-tool-goal` 的独立权限检查。 -## 结算策略 +## Idle 检查点 -| 持久轮次结果 | Goal 操作 | 自动重试 | -|---|---|---| -| goal phase 仍为 active 且已启用续行时的 `completed` | 准入下一 Round；达到上限时以代码 `round-limit` 阻塞 | 是 | -| 已预留／准入 Goal Round 的取消，或其 `aborted` 结果 | `paused` | 否 | -| 未尝试 Goal Round 时取消 | 保留持久 phase；撤销激活 | 否 | -| `error` 且带 `RATE_LIMIT` 或 `QUOTA` | 设为 `blocked`，代码为 `usage-limited` | 否 | -| 其他 `error`、`max-tokens` 或非陈旧提示词拒绝 | 以诊断代码和消息设为 `blocked` | 否 | -| 持久性失败、dispose（资源释放）、中断或未知未来结果 | 撤销激活或阻塞，以便检查 | 否 | - -某个 goal 在自身 Round 中发生的变更，会取代旧 revision 的结算。因此，即使物理轮次随后关闭，完成、暂停、阻塞和编辑仍具有最终决定权。任何异常结果都不会自动重试。 +整个 agent 进入 idle 时，持久 goal phase 和 revision 具有权威性。phase 为 active、已启用续行且仍有容量的 goal 会预留下一 Round；完成、暂停、阻塞和编辑都会阻止续行。驱动器不会通过关联 goal 消息与 `turn/end` 来对前一段活动分类，因此提供方错误和 token 上限不属于提示词级 goal 结果。 ## 生命周期与持久性 -`goal/changed` 会产生持久性义务。排队工作前，驱动器会等待 `ctx.sessions.flush()`，并在等待后重新检查 goal revision 与竞争输入。关闭时的 flush 失败通过 `agent/error` 到达；即使后续一次性注入已经追加另一轮次，驱动器仍会把失败关联到完全相同的已关闭轮次，然后停用续行，避免另一 Round 启动。 +`goal/changed` 会产生持久性义务。排队工作前，驱动器会等待 `ctx.sessions.flush()`，并在等待后重新检查 goal revision 与竞争输入。通过 `agent/error` 到达的 flush 失败会停用续行，避免另一 Round 启动。 此插件加载到现有 agent 上时绝不会继承续行启用状态。`GoalService.disarm()` 会移除进程本地权限，而不改变持久 phase、revision 或历史；之后由用户明确授权的 resume 会记录重新启用续行。会话 resume 和 fork 后，goal 领域通过 `agent/session-start` 处理应用相同规则。 -取消采用先观察、后行动的顺序：具体循环会在清空队列或中止轮次前，发送带类型 cause 的 `agent/cancel-requested`。仅当取消操作所针对的是已预留或已准入的 Goal Round 尝试时，插件才会持久暂停 active goal；取消无关用户工作只会撤销进程本地续行权限。如果 pause 变更失败，驱动器会回退到停用续行。插件 teardown 会关闭准入，停用所有活跃 goal 的续行，以 `parent` cause 取消已经准入的 Round，并在事件隔离仍安装的情况下等待驱动器和 agent 完全停稳。 +取消会移除 inbox 中待处理的工作，或留下 agent 范围的 aborted 状态。在下一次 idle 检查点，驱动器会暂停存在已预留或已准入尝试的 goal，避免取消后自动重启；与 goal 尝试无关的取消只会撤销进程本地续行权限。如果 pause 变更失败，驱动器会回退到停用续行。插件 teardown 会关闭准入，停用所有活跃 goal 的续行，以 `parent` cause 取消正在进行的工作，并在事件隔离仍安装的情况下等待驱动器和 agent 完全停稳。 ## 模型体验 @@ -69,5 +60,5 @@ - **没有独立评估器**：面向模型的 goal 策略会判断证据是否足以完成，以及 blocker 在语义上是否未变；评估器支持的认证仍保持暂缓。 - **只在同一会话执行**：此包（package）有意不 spawn 新 agent、不 fork 会话前缀，也不实现 Ralph 风格的独立尝试；该工作流属于单独的插件层。 - **已接受队列的卸载竞态**：Cordis 插件卸载是异步的。已经被 agent inbox 接受的 goal 提示词可以在卸载开始前启动并消耗其 Round；teardown 随后会取消请求、撤销 goal 激活并等待完全停稳。不会再启动后续 Round。 -- **只有 Round 上限，不是资源预算**：token、货币、时间与提供方配额策略保持独立；观察到 `RATE_LIMIT` 和 `QUOTA` 时，只会映射为阻塞原因代码 `usage-limited`。 +- **只有 Round 上限，不是资源预算**：token、货币、时间与提供方配额策略保持独立。对应的会话事件不会归属于 goal 消息，也不会映射为 goal 阻塞代码。 - **异常情况不自动重试**：暂时性的提供方与持久化失败需要之后由用户授权 resume，而不会采用隐式重试策略。 diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index 5694da1dae..3789ec5430 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -8,15 +8,11 @@ import { FiberState } from 'cordis' import type { Context } from 'cordis' import type { Agent, PromptDecision } from '@deepseek-ai/dsh-agent' import type { GoalMessageSource, GoalRef, GoalView } from '@deepseek-ai/dsh-goal' -import { createUserMessage, assertNever } from '@deepseek-ai/dsh-llm' +import { createUserMessage } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm' -import type { Session, SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' -import { classifyGoalRound } from './outcome.ts' -import type { GoalRoundOutcome } from './outcome.ts' +import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' import { renderGoalRoundPrompt } from './prompt.ts' -export { classifyGoalRound } from './outcome.ts' -export type { GoalRoundOutcome } from './outcome.ts' export { renderGoalRoundPrompt } from './prompt.ts' export const name = 'goal-session' @@ -31,13 +27,11 @@ interface RoundIdentity { readonly round: number } -/** One queued or admitted attempt, retained until its physical turn settles. */ +/** One queued or admitted goal message retained until whole-agent quiescence. */ interface RoundAttempt extends RoundIdentity { readonly messageId: MessageId readonly content: ContentBlock[] phase: 'queued' | 'admitted' - turn: number | undefined - reason: TurnEndReason | undefined stale: boolean } @@ -45,13 +39,11 @@ interface RoundAttempt extends RoundIdentity { interface DriverState { readonly agent: Agent attempt: RoundAttempt | undefined - openTurn: number | undefined competingQueued: boolean needsCheckpoint: boolean requested: boolean run: Promise | undefined stopping: boolean - readonly flushFailedTurns: Set } /** Whether a source identifies an automatic, positive-numbered goal round. */ @@ -92,13 +84,11 @@ export function apply(ctx: Context): void { const state: DriverState = { agent, attempt: undefined, - openTurn: undefined, competingQueued: false, needsCheckpoint: false, requested: false, run: undefined, stopping: false, - flushFailedTurns: new Set(), } states.set(agent, state) return state @@ -134,28 +124,7 @@ export function apply(ctx: Context): void { } } - /** Apply one closed-round outcome only to the exact still-current revision. */ - function applyOutcome(state: DriverState, goal: GoalView, outcome: GoalRoundOutcome): void { - const ref = goalRef(goal) - switch (outcome.kind) { - case 'continue': - return - case 'pause': - ctx.goals.pause(state.agent, ref) - return - case 'blocked': - ctx.goals.block(state.agent, ref, { code: outcome.code, message: outcome.message }) - return - case 'disarm': - ctx.goals.disarm(state.agent) - return - /* v8 ignore next 2 -- GoalRoundOutcome is closed and every member is handled above */ - default: - assertNever(outcome, 'goal round outcome') - } - } - - /** Process a settled attempt, then reserve at most one next round. */ + /** Process admitted work at quiescence, then reserve at most one next round. */ async function drive(state: DriverState): Promise { const { agent } = state if (!readyToDrive(state)) return @@ -166,8 +135,7 @@ export function apply(ctx: Context): void { await ctx.sessions.flush(agent.session) } catch (error: unknown) { ctx.logger.warn(`goal-session: durability checkpoint failed for agent "${agent.id}": ${renderThrown(error)}`) - const goal = currentGoal(state) - if (goal !== undefined) applyOutcome(state, goal, { kind: 'disarm', reason: 'durability-failed' }) + disarm(state) return } // A mutation or ordinary prompt may have arrived while the checkpoint @@ -177,27 +145,8 @@ export function apply(ctx: Context): void { const attempt = state.attempt if (attempt !== undefined) { - // Still unsettled: a contained turn-close failure reaches idle with the - // attempt's turn open in the log and no terminal reason recorded, so - // the drive pass must yield rather than misread it as settled. - if (attempt.reason === undefined) return + if (attempt.phase === 'queued') return state.attempt = undefined - const turn = attempt.turn - /* v8 ignore next -- a closed attempt acquired its turn at turn/start */ - if (turn === undefined) throw new Error('settled goal-round attempt lacks a turn') - const durable = !state.flushFailedTurns.delete(turn) - const goal = currentGoal(state) - if (goal !== undefined && goal.id === attempt.goalId && goal.revision === attempt.revision - && goal.phase === 'active' && goal.activation === 'armed') { - const outcome = classifyGoalRound(attempt.reason, durable) - if (!attempt.stale) applyOutcome(state, goal, outcome) - } - if (!readyToDrive(state)) return - // The loop's persistence is eager write-behind with no turn-end flush, - // so this driver owns the round's durability barrier: checkpoint the - // settled round before reserving another (re-entering drive through - // the flush path above), disarming on failure instead of queueing an - // autonomous round on state that was never persisted. state.needsCheckpoint = true state.requested = true return @@ -226,8 +175,6 @@ export function apply(ctx: Context): void { messageId: message.id, content, phase: 'queued', - turn: undefined, - reason: undefined, stale: false, } state.attempt = reservation @@ -286,12 +233,8 @@ export function apply(ctx: Context): void { // One composite effect keeps the admission fence installed until this // plugin's own scheduling tasks settle. ctx.effect(function* () { - /** Mark a post-turn persistence failure before idle scheduling can run. */ - ctx.on('agent/error', (agent, turn) => { + ctx.on('agent/error', (agent) => { const state = stateFor(agent) - const closed = agent.session.events.some(event => event.type === 'turn/end' && event.data.turn === turn) - if (!closed) return - if (state.attempt?.turn === turn) state.flushFailedTurns.add(turn) disarm(state) }) @@ -300,10 +243,8 @@ export function apply(ctx: Context): void { ctx.on('agent/session-start', (agent) => { const state = stateFor(agent) state.attempt = undefined - state.openTurn = undefined state.competingQueued = false state.needsCheckpoint = false - state.flushFailedTurns.clear() }) ctx.on('agent/status', (agent, status) => { const state = stateFor(agent) @@ -311,11 +252,10 @@ export function apply(ctx: Context): void { state.competingQueued = false const attempt = state.attempt const goal = currentGoal(state) - if (attempt !== undefined && attempt.turn === undefined && attempt.reason === undefined - && goal?.phase === 'active' && goal.activation === 'armed') { + if (attempt?.phase === 'queued' && goal?.phase === 'active' && goal.activation === 'armed') { state.attempt = undefined try { - applyOutcome(state, goal, { kind: 'pause', reason: 'cancelled' }) + ctx.goals.pause(agent, goalRef(goal)) } catch (error: unknown) { ctx.logger.warn(`goal-session: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`) disarm(state) @@ -345,21 +285,23 @@ export function apply(ctx: Context): void { } return } - case 'turn/start': { - state.openTurn = event.data.turn - return - } case 'user/message': if (state.attempt !== undefined && event.data.id === state.attempt.messageId) { state.attempt.phase = 'admitted' - /* v8 ignore next -- the loop logs admitted input inside an open turn */ - if (state.openTurn !== undefined) state.attempt.turn = state.openTurn } return case 'turn/end': - if (state.attempt?.turn === event.data.turn) state.attempt.reason = event.data.reason - /* v8 ignore next -- balanced live turns close the open turn just observed by this listener */ - if (state.openTurn === event.data.turn) state.openTurn = undefined + if (event.data.reason.kind !== 'aborted') return + { + const goal = currentGoal(state) + if (goal?.phase !== 'active' || goal.activation !== 'armed') return + try { + ctx.goals.pause(agent, goalRef(goal)) + } catch (error: unknown) { + ctx.logger.warn(`goal-session: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`) + disarm(state) + } + } return default: return @@ -413,7 +355,7 @@ export function apply(ctx: Context): void { // starve every later drive pass. Clear it and let the driver // reschedule the round. const attempt = state.attempt - if (attempt !== undefined && sameRound(source, attempt) && attempt.turn === undefined) { + if (attempt !== undefined && sameRound(source, attempt) && attempt.phase === 'queued') { state.attempt = undefined requestDrive(state) } @@ -468,9 +410,6 @@ export function apply(ctx: Context): void { const attempt = state.attempt if (attempt !== undefined) { attempt.stale = true - if (attempt.phase === 'admitted' && state.agent.status === 'running') { - state.agent.cancel({ kind: 'parent' }) - } } if (state.run !== undefined) waits.push(state.run) } diff --git a/packages/goal/goal-session/src/outcome.ts b/packages/goal/goal-session/src/outcome.ts deleted file mode 100644 index 29615231a0..0000000000 --- a/packages/goal/goal-session/src/outcome.ts +++ /dev/null @@ -1,53 +0,0 @@ -/** Typed settlement policy for one admitted same-session goal round. */ - -import type { TurnEndReason } from '@deepseek-ai/dsh-session' - -/** Driver action derived from one closed goal-owned turn. */ -export type GoalRoundOutcome = - | { readonly kind: 'continue' } - | { readonly kind: 'pause'; readonly reason: string } - | { - readonly kind: 'blocked' - readonly code: 'usage-limited' | 'turn-error' | 'max-tokens' | 'unknown-turn-outcome' - readonly message: string - } - | { readonly kind: 'disarm'; readonly reason: 'durability-failed' | 'disposed' | 'interrupted' } - -/** - * Classify one closed goal round without mutating goal state. - * @param reason - durable reason from the round's `turn/end`. - * @param durable - whether the closing flush reached its durability checkpoint. - * @returns the single driver action; no abnormal outcome requests an automatic retry. - */ -export function classifyGoalRound(reason: TurnEndReason, durable: boolean): GoalRoundOutcome { - if (!durable) return { kind: 'disarm', reason: 'durability-failed' } - const extensibleReason: { readonly kind: string } = reason - switch (reason.kind) { - case 'completed': - return { kind: 'continue' } - case 'aborted': - return { kind: 'pause', reason: 'cancelled' } - case 'error': { - const error = reason.error - const code = typeof error === 'object' && error !== null && 'code' in error - ? error.code - : undefined - const message = error instanceof Error ? error.message : String(error) - return code === 'RATE_LIMIT' || code === 'QUOTA' - ? { kind: 'blocked', code: 'usage-limited', message } - : { kind: 'blocked', code: 'turn-error', message } - } - case 'max-tokens': - return { kind: 'blocked', code: 'max-tokens', message: 'model output reached max tokens' } - case 'interrupted': - return { kind: 'disarm', reason: 'interrupted' } - // TurnEndReason is merge-extensible. An unknown producer cannot opt into - // automatic retry merely by adding a tag; stop for inspection instead. - default: - return { - kind: 'blocked', - code: 'unknown-turn-outcome', - message: `unknown turn outcome: ${extensibleReason.kind}`, - } - } -} diff --git a/packages/sdk/sdk-client/README.i18n.yaml b/packages/sdk/sdk-client/README.i18n.yaml index c0bf2706ff..011d9f3bba 100644 --- a/packages/sdk/sdk-client/README.i18n.yaml +++ b/packages/sdk/sdk-client/README.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 packages/sdk/sdk-client/README.md -README.md: 3ac4de540401f6f40dab3e84f7005f91d024aee8 -README.zh.md: 95fb6b2887a7bc748a610f7fedae4be1aa2af623 +README.md: 9c441e8538a62f7139f789eef78cf70d8008418a +README.zh.md: fbf638c9160d0356da0eae0566a2775146c47750 diff --git a/packages/sdk/sdk-client/README.md b/packages/sdk/sdk-client/README.md index 3ac4de5404..9c441e8538 100644 --- a/packages/sdk/sdk-client/README.md +++ b/packages/sdk/sdk-client/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -The TypeScript client SDK for driving a DeepSeek Harness runtime as a subprocess over stdio JSON-RPC — the design twin of the [Python SDK](../../../python/README.md) (`deepseek-harness`), sharing the same runtime peer, protocol, and layering: `DeepSeekHarness` is the high-level turns API, `HarnessClient` the lower-level protocol client. The package root enumerates the consumer interface: the two client layers, caller-facing types, and `JsonRpcResponseError`; source modules, normalization helpers, and subscription-delivery machinery are not consumer imports. A pure library: it registers nothing on a Cordis context; the runtime process it spawns is a complete harness whose composition its own `cordis.yml` decides. +The TypeScript client SDK for driving a DeepSeek Harness runtime as a subprocess over stdio JSON-RPC — the design twin of the [Python SDK](../../../python/README.md) (`deepseek-harness`), sharing the same runtime peer, protocol, and layering: `DeepSeekHarness` is the high-level owned-run API, `HarnessClient` the lower-level protocol client. The package root enumerates the consumer interface: the two client layers, caller-facing types, and `JsonRpcResponseError`; source modules, normalization helpers, and subscription-delivery machinery are not consumer imports. A pure library: it registers nothing on a Cordis context; the runtime process it spawns is a complete harness whose composition its own `cordis.yml` decides. Unlike the Python SDK, the launch spec is fully explicit (`command`/`args`): this package is for repo-adjacent TypeScript consumers — the [`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.md) backend, tests, automation — which know which runtime they are launching. Bundled-runtime resolution (finding a packaged executable) remains the Python distribution's concern. @@ -18,14 +18,16 @@ await using harness = new DeepSeekHarness({ maxTokens: 49_152, }) const result = await harness.run('say hi') -console.log(result.status, result.finalResponse) +console.log(result.finalResponse) ``` -The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; `close()` (or `await using`) is required so the child is always reaped. `start()` memoizes the `initialize` handshake (the workspace cwd — resolved absolute before it crosses the wire — plus the provider/model route and optional positive `maxTokens` output cap); a failed handshake reaps the runtime and swaps in a fresh client, so a later call retries with a new subprocess (until `close()`, which is terminal). The cap applies to each root-agent request and is inherited by in-process descendants; compaction plugins own their separate summary limits. `session(id?)` opens a named or fresh session handle; `run(input, { sessionId?, onNotification? })` sends one prompt turn and settles when the paired `session.finished` arrives, returning a `TurnResult`: `status` (`ok`/`error` as the deployment maps it), the structured `reason` (`TurnEndReason`), `finalResponse` (last assistant message text), root-session `events`, and raw `notifications` for that session plus descendants discovered from `subagent.started`, all in wire order. Model-level failure is a `status: 'error'` result, never a rejection; rejections mean transport loss, timeout, or protocol violation. +The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; `close()` (or `await using`) is required so the child is always reaped. `start()` memoizes the `initialize` handshake (the workspace cwd — resolved absolute before it crosses the wire — plus the provider/model route and optional positive `maxTokens` output cap); a failed handshake reaps the runtime and swaps in a fresh client, so a later call retries with a new subprocess (until `close()`, which is terminal). The cap applies to each root-agent request and is inherited by in-process descendants; compaction plugins own their separate summary limits. `session(id?)` opens a named or fresh session handle. + +`run(input, { sessionId?, onNotification? })` owns one activity interval: it queues the prompt, waits until its `MessageId` appears in a durable `agent/inbox/spliced` receipt, then collects through the next whole-agent `idle`. It returns `RunResult { sessionId, finalResponse, events, notifications }`. `finalResponse` is the last committed root-session assistant text in that interval, not a response causally assigned to the prompt; steering, injected context, and other queued work may contribute before idle. `events` contains root-session events, while `notifications` also contains descendants discovered from `subagent.started`, all in wire order. The result carries no prompt-level status or turn reason. Transport loss, timeout, and protocol violations reject; model outcomes remain observable in the event stream without being attributed to one input. ## HarnessClient -The protocol client under the turns API: explicit `start()`/`initialize()`/`prompt()`/`request()`/`close()`, plus notification subscriptions. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK. Error surfaces are typed and exported from this package: `JsonRpcResponseError` (wire error response, code/data preserved), `RequestTimeoutError` (a configured bound elapsed; there is no wire-level cancel, so the request keeps running server-side until close), `SdkProtocolError` (a response outside the documented protocol), `TransportClosedError` (the runtime is gone — message carries the exit code and a bounded stderr tail). +The protocol client under the owned-run API: explicit `start()`/`initialize()`/`prompt()`/`request()`/`close()`, plus notification subscriptions. `prompt()` returns the queued message id as soon as the runtime accepts it; it never waits for agent activity. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK. Error surfaces are typed and exported from this package: `JsonRpcResponseError` (wire error response, code/data preserved), `RequestTimeoutError` (a configured bound elapsed), `SdkProtocolError` (a response outside the documented protocol), `TransportClosedError` (the runtime is gone — message carries the exit code and a bounded stderr tail). `close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder (`disposeEofGraceMs` default 6000, `disposeGraceMs` default 3000) until the process has actually exited. The ladder is private to this client: it runs outside any harness context, so it cannot ride the [`dsh-subprocess`](../../subprocess/README.md) service — the seam's documented exception for SDK-managed transports. It is idempotent, and a closed client refuses reuse. @@ -33,7 +35,7 @@ The protocol client under the turns API: explicit `start()`/`initialize()`/`prom ## Testing -Keyless unit tests drive a scripted fake runtime subprocess (`tests/fake-runtime.ts`, protocol-only, env-scripted) over real stdio: turn loop, session-tree scoping, timeout/death/malformed-response surfaces, and the dispose ladder. The [SDK snapshot suite](../../../examples/jsonrpc-agent/tests/sdk.snapshot.ts) drives the real `dsh-jsonrpc-agent` runtime through this client keylessly via `llm-replay`, pinning the notification stream, the turn result, and the persisted logs; `DSH_SNAPSHOT=record` re-records against the live API. +Keyless unit tests drive a scripted fake runtime subprocess (`tests/fake-runtime.ts`, protocol-only, env-scripted) over real stdio: activity collection, session-tree scoping, timeout/death/malformed-response surfaces, and the dispose ladder. The [SDK snapshot suite](../../../examples/jsonrpc-agent/tests/sdk.snapshot.ts) drives the real `dsh-jsonrpc-agent` runtime through this client keylessly via `llm-replay`, pinning the notification stream, run result, and persisted logs; `DSH_SNAPSHOT=record` re-records against the live API. ## Model Experience @@ -47,5 +49,5 @@ None; this package neither assembles nor sends a provider request. - **No bundled-runtime resolution** — callers name the runtime executable explicitly; packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists. - **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../sdk-protocol/README.md)). -- **One in-flight prompt per session** — a server-side rule this client surfaces as a `JsonRpcResponseError`; independent sessions run concurrently on one runtime. +- **No per-prompt result or cancel** — low-level `prompt()` returns only an enqueue receipt; high-level `run()` owns receipt-to-idle collection, and abandoning it means closing the runtime. - **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows. diff --git a/packages/sdk/sdk-client/README.zh.md b/packages/sdk/sdk-client/README.zh.md index 95fb6b2887..fbf638c916 100644 --- a/packages/sdk/sdk-client/README.zh.md +++ b/packages/sdk/sdk-client/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -以子进程方式驱动 DeepSeek Harness 运行时、走 stdio JSON-RPC 的 TypeScript 客户端 SDK——[Python SDK](../../../python/README.md)（`deepseek-harness`）的设计孪生，共享同一个运行时对端、协议与分层：`DeepSeekHarness` 是高层轮次 API，`HarnessClient` 是低层协议客户端。包（package）根枚举消费方接口：两层客户端、面向调用方的类型和 `JsonRpcResponseError`；源模块、规范化辅助函数与订阅投递机制不供消费方导入。纯库：不在任何 Cordis 上下文注册；它所 spawn 的运行时进程是一个完整 harness，其组成由自己的 `cordis.yml` 决定。 +以子进程方式驱动 DeepSeek Harness 运行时、走 stdio JSON-RPC 的 TypeScript 客户端 SDK——[Python SDK](../../../python/README.md)（`deepseek-harness`）的设计孪生，共享同一个运行时对端、协议与分层：`DeepSeekHarness` 是高层自有运行 API，`HarnessClient` 是低层协议客户端。包（package）根枚举消费方接口：两层客户端、面向调用方的类型和 `JsonRpcResponseError`；源模块、规范化辅助函数与订阅投递机制不供消费方导入。纯库：不在任何 Cordis 上下文注册；它所 spawn 的运行时进程是一个完整 harness，其组成由自己的 `cordis.yml` 决定。 与 Python SDK 不同，启动规格完全显式（`command`/`args`）：本包面向仓库近旁的 TypeScript 消费方——[`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.md) 后端、测试、自动化——它们知道自己要启动哪个运行时。捆绑运行时解析（寻找打包可执行文件）仍归 Python 发行版负责。 @@ -18,14 +18,16 @@ await using harness = new DeepSeekHarness({ maxTokens: 49_152, }) const result = await harness.run('say hi') -console.log(result.status, result.finalResponse) +console.log(result.finalResponse) ``` -子进程在首次使用时惰性启动，并在多次 `run()` 之间持续归实例所有；必须 `close()`（或 `await using`），子进程才总能被回收。`start()` 记忆化 `initialize` 握手（工作区 cwd——在通过协议传输之前解析为绝对路径——加 provider/model 路由和可选的正整数 `maxTokens` 输出上限）；握手失败会回收运行时并换入全新客户端，后续调用用新子进程重试（直到终结性的 `close()`）。该上限作用于根 agent（智能体）的每次请求，并由进程内后代继承；压缩（compaction）插件单独持有摘要上限。`session(id?)` 打开具名或全新的会话句柄；`run(input, { sessionId?, onNotification? })` 发送一个提示词轮次，在配对的 `session.finished` 到达时完成，并返回 `TurnResult`：`status`（按部署映射的 `ok`/`error`）、结构化 `reason`（`TurnEndReason`）、`finalResponse`（最后一条助手消息文本）、根会话的 `events`，以及该会话和通过 `subagent.started` 发现的后代的原始 `notifications`，均按协议传输顺序排列。模型层失败会返回 `status: 'error'` 的结果，绝不会导致 Promise 被拒绝；Promise 被拒绝意味着传输丢失、超时或协议违例。 +子进程在首次使用时惰性启动，并在多次 `run()` 之间持续归实例所有；必须 `close()`（或 `await using`），子进程才总能被回收。`start()` 记忆化 `initialize` 握手（工作区 cwd——在通过协议传输之前解析为绝对路径——加 provider/model 路由和可选的正整数 `maxTokens` 输出上限）；握手失败会回收运行时并换入全新客户端，后续调用用新子进程重试（直到终结性的 `close()`）。该上限作用于根 agent（智能体）的每次请求，并由进程内后代继承；压缩（compaction）插件单独持有摘要上限。`session(id?)` 打开具名或全新的会话句柄。 + +`run(input, { sessionId?, onNotification? })` 拥有一个活动区间：它将提示词排入队列，等待其 `MessageId` 出现在持久的 `agent/inbox/spliced` 回执中，然后持续收集到整个 agent 下一次进入 `idle`。它返回 `RunResult { sessionId, finalResponse, events, notifications }`。`finalResponse` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的响应；steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。`events` 包含根会话事件，`notifications` 还包含通过 `subagent.started` 发现的后代，均按协议传输顺序排列。结果不携带提示词级状态或轮次原因。传输丢失、超时和协议违例会导致 Promise 被拒绝；模型结果仍可在事件流中观察，但不会归属于某一输入。 ## HarnessClient -轮次 API 之下的协议客户端：显式 `start()`/`initialize()`/`prompt()`/`request()`/`close()`，外加通知订阅。`subscribe(filter?)` 返回 `NotificationSubscription`（可等待的 `next()`、非阻塞 `tryNext()`、异步迭代）；`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知，范围限定在客户端完成，与 Python SDK 完全一致。本包导出有明确类型的错误：`JsonRpcResponseError`（协议错误响应，保留 code/data）、`RequestTimeoutError`（配置的时限已到；协议层没有取消机制，请求在服务端继续运行直到 close）、`SdkProtocolError`（响应超出文档化协议）、`TransportClosedError`（运行时已消失——消息携带退出码与有界 stderr 尾部）。 +自有运行 API 之下的协议客户端：显式 `start()`/`initialize()`/`prompt()`/`request()`/`close()`，外加通知订阅。`prompt()` 在运行时接受排队消息后立即返回该消息的 ID，绝不等待 agent 活动。`subscribe(filter?)` 返回 `NotificationSubscription`（可等待的 `next()`、非阻塞 `tryNext()`、异步迭代）；`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知，范围限定在客户端完成，与 Python SDK 完全一致。本包导出有明确类型的错误：`JsonRpcResponseError`（协议错误响应，保留 code/data）、`RequestTimeoutError`（配置的时限已到）、`SdkProtocolError`（响应超出文档化协议）、`TransportClosedError`（运行时已消失——消息携带退出码与有界 stderr 尾部）。 `close()` 先请求协议 `shutdown`（受 `shutdownTimeoutMs` 约束，默认 1000 毫秒），然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯（`disposeEofGraceMs` 默认 6000，`disposeGraceMs` 默认 3000）直到进程真正退出。该阶梯为本客户端私有：它运行在任何 harness 上下文之外，无法搭乘 [`dsh-subprocess`](../../subprocess/README.md) 服务——即该 seam 所记录的 SDK 托管传输例外。幂等，已关闭的客户端拒绝复用。 @@ -33,7 +35,7 @@ console.log(result.status, result.finalResponse) ## 测试 -免密钥单元测试通过真实 stdio 驱动一个脚本化伪运行时子进程（`tests/fake-runtime.ts`，纯协议、环境变量脚本化）：轮次循环、会话树范围限定、超时、进程死亡和响应畸形场景，以及 dispose（资源释放）阶梯。[SDK 快照套件](../../../examples/jsonrpc-agent/tests/sdk.snapshot.ts) 经由 `llm-replay` 免密钥地通过本客户端驱动真实 `dsh-jsonrpc-agent` 运行时，固定通知流、轮次结果与持久化日志；`DSH_SNAPSHOT=record` 对真实 API 重录。 +免密钥单元测试通过真实 stdio 驱动一个脚本化伪运行时子进程（`tests/fake-runtime.ts`，纯协议、环境变量脚本化）：活动收集、会话树范围限定、超时、进程死亡和响应畸形场景，以及 dispose（资源释放）阶梯。[SDK 快照套件](../../../examples/jsonrpc-agent/tests/sdk.snapshot.ts) 经由 `llm-replay` 免密钥地通过本客户端驱动真实 `dsh-jsonrpc-agent` 运行时，固定通知流、运行结果与持久化日志；`DSH_SNAPSHOT=record` 对真实 API 重录。 ## 模型体验 @@ -47,5 +49,5 @@ console.log(result.status, result.finalResponse) - **无捆绑运行时解析**——调用方显式指定运行时可执行文件；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费方。 - **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../sdk-protocol/README.md)）。 -- **每会话同时只有一个在途提示词**——服务端规则，本客户端将其呈现为 `JsonRpcResponseError`；相互独立的会话可在同一运行时上并发。 +- **没有逐提示词结果或取消**——低层 `prompt()` 只返回入队回执；高层 `run()` 负责从回执收集到 idle，放弃该过程意味着关闭运行时。 - **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现；传输层为未来审批流保留了承载能力。 diff --git a/packages/sdk/sdk-client/src/api.ts b/packages/sdk/sdk-client/src/api.ts index b5cfd12c6b..2c27251295 100644 --- a/packages/sdk/sdk-client/src/api.ts +++ b/packages/sdk/sdk-client/src/api.ts @@ -1,7 +1,7 @@ /** - * High-level turns API over {@link HarnessClient}: `DeepSeekHarness` owns one + * High-level run API over {@link HarnessClient}: `DeepSeekHarness` owns one * runtime subprocess across many sessions; `HarnessSession.run` sends a - * prompt and settles with the final response once `session.finished` arrives. + * prompt and settles when the whole agent next becomes idle. * Mirrors the Python SDK's `DeepSeekHarness`/`Session` pair. * * @module @deepseek-ai/dsh-sdk-client/api @@ -9,9 +9,9 @@ import { randomUUID } from 'node:crypto' import { resolve } from 'node:path' -import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' import { HarnessClient, isRecord, SdkProtocolError } from './client.ts' -import type { ContentBlock, DeepSeekHarnessOptions, HarnessClientOptions, HarnessNotification, TurnResult } from './types.ts' +import type { ContentBlock, DeepSeekHarnessOptions, HarnessClientOptions, HarnessNotification, RunResult } from './types.ts' /** * Reusable SDK for running DeepSeek Harness agent turns in a runtime @@ -93,9 +93,9 @@ export class DeepSeekHarness implements AsyncDisposable { * Run one prompt on a fresh (or named) session. * @param input - prompt text, or content blocks sent verbatim. * @param options - optional session id and per-notification observer. - * @returns the settled turn result. + * @returns the owned activity interval. */ - run(input: string | ContentBlock[], options?: RunOptions): Promise { + run(input: string | ContentBlock[], options?: RunOptions): Promise { return this.session(options?.sessionId).run(input, options) } @@ -127,8 +127,7 @@ export interface RunOptions { } /** - * One SDK session: a stable id plus the turn loop that pairs a - * `session/prompt` with its `session.finished`. + * One SDK session: a stable id plus owned activity intervals. */ export class HarnessSession { /** @@ -138,27 +137,23 @@ export class HarnessSession { constructor(readonly harness: DeepSeekHarness, readonly id: string) {} /** - * Run one prompt turn to settlement. + * Queue one prompt, then observe the whole session through its next idle. * @param input - prompt text, or content blocks sent verbatim. * @param options - optional per-notification observer. - * @returns the settled turn result; rejects on transport loss, timeout, or - * a protocol error — never on a model-level failure (that is - * `status: 'error'` in the result). + * @returns the owned activity interval; rejects on transport loss, timeout, + * or a protocol error. */ - async run(input: string | ContentBlock[], options?: Pick): Promise { + async run(input: string | ContentBlock[], options?: Pick): Promise { await this.harness.start() const client = this.harness.client const contentBlocks = normalizeInput(input) const events: SessionEvent[] = [] const notifications: HarnessNotification[] = [] - let status: TurnResult['status'] = 'error' - let reason: TurnEndReason | undefined - let finished = false const subscription = client.subscribeSessionTree(this.id) const collect = (notification: HarnessNotification): void => { if (notification.method === 'session.event' && notification.params.sessionId === this.id) { - // Wire boundary: the envelope feeds the typed TurnResult, so a + // Wire boundary: the envelope feeds the typed RunResult, so a // malformed runtime surfaces as a protocol error, not as type-invalid // data (or a TypeError out of finalResponse). const event = validatedSessionEvent(notification.params.event) @@ -167,37 +162,31 @@ export class HarnessSession { events.push(event) return } - if (notification.method === 'session.finished' && notification.params.sessionId === this.id) { - reason = validatedTurnEndReason(notification.params.reason) - notifications.push(notification) - options?.onNotification?.(notification) - status = notification.params.status === 'ok' ? 'ok' : 'error' - finished = true - return - } notifications.push(notification) options?.onNotification?.(notification) } - const accepted = client.prompt(this.id, contentBlocks) - // Drain concurrently so observers see progress while the prompt request - // is still pending (its response arrives only after settlement). - const drain = (async () => { - while (!finished) collect(await subscription.next()) - })() try { - await Promise.all([accepted, drain]) + const messageId = await client.prompt(this.id, contentBlocks) + let received = false + while (true) { + const notification = await subscription.next() + if (!received) { + if (notification.method !== 'session.event' + || notification.params.sessionId !== this.id + || !isInboxReceipt(notification.params.event, messageId)) continue + received = true + } + collect(notification) + if (notification.method === 'session.status' + && notification.params.sessionId === this.id + && notification.params.status === 'idle') break + } } finally { - // On a prompt rejection the drain is still parked on next(); closing the - // subscription settles it, and the swallow keeps that secondary - // TransportClosedError from surfacing as an unhandled rejection. subscription.close() - await drain.catch(() => {}) } return { sessionId: this.id, - status, - reason, finalResponse: finalResponse(events), events, notifications, @@ -232,18 +221,16 @@ function validatedSessionEvent(value: unknown): SessionEvent { return value as unknown as SessionEvent } -/** Validate a wire `session.finished` reason (absent, or a kind-tagged record). */ -function validatedTurnEndReason(value: unknown): TurnEndReason | undefined { - if (value === undefined) return undefined - if (!isRecord(value) || typeof value.kind !== 'string') { - throw new SdkProtocolError(`session.finished carried a malformed reason: ${JSON.stringify(value)}`) - } - return value as unknown as TurnEndReason +/** Whether a raw session event is the durable enqueue receipt for `messageId`. */ +function isInboxReceipt(value: unknown, messageId: string): boolean { + if (!isRecord(value) || value.type !== 'agent/inbox/spliced' || !isRecord(value.data)) return false + const inserted = value.data.inserted + return Array.isArray(inserted) && inserted.some(message => isRecord(message) && message.id === messageId) } /** * Extract the concatenated text of the last assistant message. - * @param events - the turn's `session.event` payloads in wire order. + * @param events - the activity interval's `session.event` payloads in wire order. * @returns the final response text, or `''` when no assistant message exists. */ export function finalResponse(events: SessionEvent[]): string { diff --git a/packages/sdk/sdk-client/src/client.ts b/packages/sdk/sdk-client/src/client.ts index af19f26868..1937f4a1dc 100644 --- a/packages/sdk/sdk-client/src/client.ts +++ b/packages/sdk/sdk-client/src/client.ts @@ -275,17 +275,18 @@ export class HarnessClient { } /** - * Run one prompt turn to settlement (the response arrives only after the - * turn settled; progress streams as notifications meanwhile). + * Queue one prompt and return its durable inbox identity. * @param sessionId - target session; an unknown id creates it. * @param contentBlocks - the user message, sent verbatim. + * @returns the queued message id. */ - async prompt(sessionId: string, contentBlocks: ContentBlock[]): Promise { + async prompt(sessionId: string, contentBlocks: ContentBlock[]): Promise { const params: SessionPromptParams = { sessionId, contentBlocks } const result = await this.request('session/prompt', { ...params }) - if (!isRecord(result) || result.accepted !== true) { - throw new SdkProtocolError(`session/prompt was not accepted: ${JSON.stringify(result)}`) + if (!isRecord(result) || typeof result.messageId !== 'string') { + throw new SdkProtocolError(`session/prompt returned no message id: ${JSON.stringify(result)}`) } + return result.messageId } /** diff --git a/packages/sdk/sdk-client/src/index.ts b/packages/sdk/sdk-client/src/index.ts index 5fd1297a7f..128cfbb898 100644 --- a/packages/sdk/sdk-client/src/index.ts +++ b/packages/sdk/sdk-client/src/index.ts @@ -1,7 +1,7 @@ /** * TypeScript client SDK for the DeepSeek Harness runtime: spawn the * `dsh-jsonrpc-agent` runtime as a subprocess and drive agent turns over - * stdio JSON-RPC. `DeepSeekHarness` is the high-level turns API; + * stdio JSON-RPC. `DeepSeekHarness` is the high-level run API; * `HarnessClient` is the lower-level protocol client. A pure library — it * registers nothing on a Cordis context; the runtime process it spawns is a * complete harness configured by its own `cordis.yml`. @@ -25,5 +25,5 @@ export type { HarnessClientOptions, HarnessNotification, NotificationFilter, - TurnResult, + RunResult, } from './types.ts' diff --git a/packages/sdk/sdk-client/src/types.ts b/packages/sdk/sdk-client/src/types.ts index ad4998ca13..05300d6e36 100644 --- a/packages/sdk/sdk-client/src/types.ts +++ b/packages/sdk/sdk-client/src/types.ts @@ -1,17 +1,16 @@ /** * Types for the TypeScript SDK client: launch options, notification shapes, - * and turn results. + * and owned activity results. * * @module @deepseek-ai/dsh-sdk-client/types */ import type { ContentBlock } from '@deepseek-ai/dsh-llm' -import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' -import type { SdkRunStatus } from '@deepseek-ai/dsh-sdk-protocol' +import type { SessionEvent } from '@deepseek-ai/dsh-session' /** One server-to-client notification as received off the wire. */ export interface HarnessNotification { - /** The JSON-RPC method name (`session.event`, `session.finished`, `subagent.started`, `subagent.finished`). */ + /** The JSON-RPC notification method name. */ method: string /** The raw params object; see `HarnessSdkNotificationMap` for the shapes per method. */ params: Record @@ -59,15 +58,11 @@ export interface DeepSeekHarnessOptions { maxTokens?: number } -/** The settled outcome of one {@link HarnessSession.run} turn. */ -export interface TurnResult { - /** The session the turn ran on. */ +/** One owned session activity interval, from enqueue receipt through idle. */ +export interface RunResult { + /** The session the activity ran on. */ sessionId: string - /** Deployment-mapped turn outcome from `session.finished`. */ - status: SdkRunStatus - /** Why the last message-triggered turn ended; `undefined` when no turn ran. */ - reason: TurnEndReason | undefined - /** Concatenated text of the session's last assistant message (empty when none). */ + /** Concatenated text of the interval's last assistant message (empty when none). */ finalResponse: string /** Every `session.event` payload for the root session, in wire order. */ events: SessionEvent[] diff --git a/packages/sdk/sdk-client/tests/fake-runtime.ts b/packages/sdk/sdk-client/tests/fake-runtime.ts index 626ca87bc6..85d5253765 100644 --- a/packages/sdk/sdk-client/tests/fake-runtime.ts +++ b/packages/sdk/sdk-client/tests/fake-runtime.ts @@ -142,13 +142,6 @@ function runTurn(sessionId: string): void { lastAssistantMessage: [{ type: 'text', text: 'child says hi' }], }) } - notify('session.finished', { - sessionId, - status: env.FAKE_STATUS ?? 'ok', - ...(env.FAKE_MALFORMED_REASON !== undefined - ? { reason: 'not-a-record' } - : reasonKind === 'none' ? {} : { reason: { kind: reasonKind } }), - }) } function sessionIdOf(params: Record | undefined): string { @@ -197,8 +190,20 @@ reader.on('line', (line) => { respond({ serverInfo: { name: 'deepseek-harness-sdk-runtime', version: '0.0.1' } }) return case 'session/prompt': { + const sessionId = sessionIdOf(frame.params) + const messageId = `fake-user-${seq}` + event(sessionId, 'agent/inbox/spliced', { + target: 'next-turn', + start: 0, + inserted: [{ + id: messageId, + role: 'user', + content: [], + source: { kind: 'user' }, + }], + }) + notify('session.status', { sessionId, status: 'running' }) if (env.FAKE_STREAM_THEN_MALFORMED !== undefined) { - const sessionId = sessionIdOf(frame.params) event(sessionId, 'assistant/chunk', { turn: 0, step: 0, chunk: { type: 'text-delta', index: 0, text: 'streamed then cut short' } }) respond({}) return @@ -208,9 +213,9 @@ reader.on('line', (line) => { respond({}) return } - const sessionId = sessionIdOf(frame.params) runTurn(sessionId) - respond({ accepted: true }) + notify('session.status', { sessionId, status: 'idle' }) + respond({ messageId }) return } case 'shutdown': diff --git a/packages/sdk/sdk-client/tests/sdk-client.spec.ts b/packages/sdk/sdk-client/tests/sdk-client.spec.ts index 63093e602b..e31490a6cd 100644 --- a/packages/sdk/sdk-client/tests/sdk-client.spec.ts +++ b/packages/sdk/sdk-client/tests/sdk-client.spec.ts @@ -56,14 +56,13 @@ describe('DeepSeekHarness', () => { it('runs a turn end to end and reuses the runtime across sessions', async () => { const harness = harnessWith({ FAKE_TEXT: 'turn answer' }) const first = await harness.run('say hi') - expect(first.status).toBe('ok') - expect(first.reason).toEqual({ kind: 'completed' }) expect(first.finalResponse).toBe('turn answer') - expect(first.events.map(event => event.type)).toEqual(['turn/start', 'assistant/chunk', 'assistant/message', 'turn/end']) + expect(first.events.map(event => event.type)).toEqual([ + 'agent/inbox/spliced', 'turn/start', 'assistant/chunk', 'assistant/message', 'turn/end', + ]) // Same subprocess, second session: ids differ, protocol state is reusable. const second = await harness.run([{ type: 'text', text: 'again' }]) - expect(second.status).toBe('ok') expect(second.sessionId).not.toBe(first.sessionId) await harness.close() }) @@ -76,13 +75,12 @@ describe('DeepSeekHarness', () => { onNotification: (n) => { seen.push(n) }, }) - expect(result.status).toBe('ok') // The child session's events arrive through subagent.started lineage. expect(seen.map(n => n.method)).toContain('subagent.started') expect(seen.map(n => n.method)).toContain('subagent.finished') const childEvents = seen.filter(n => n.method === 'session.event' && n.params.sessionId === 'parent-1-child') expect(childEvents.length).toBeGreaterThan(0) - // TurnResult.events is the root session's typed stream; descendants retain + // RunResult.events is the root session's typed stream; descendants retain // their session ids in the raw notification stream above. expect(result.events.every(event => event.type !== 'assistant/message' || event.data.message.content[0]?.type !== 'text' @@ -90,22 +88,6 @@ describe('DeepSeekHarness', () => { await harness.close() }) - it('reports an error status with the turn-end reason', async () => { - const harness = harnessWith({ FAKE_STATUS: 'error', FAKE_REASON_KIND: 'max-tokens' }) - const result = await harness.run('overflow') - expect(result.status).toBe('error') - expect(result.reason).toEqual({ kind: 'max-tokens' }) - await harness.close() - }) - - it('omits the reason when the runtime settled without one', async () => { - const harness = harnessWith({ FAKE_STATUS: 'error', FAKE_REASON_KIND: 'none' }) - const result = await harness.run('no turn') - expect(result.status).toBe('error') - expect(result.reason).toBeUndefined() - await harness.close() - }) - it('sends the configured cwd/provider/model/maxTokens in the handshake exactly once', async () => { const dir = await tempDir('sdk-client-init-') const recordFile = join(dir, 'init.jsonl') @@ -311,14 +293,14 @@ describe('HarnessClient', () => { await client.initialize({ cwd: process.cwd(), provider: 'p', model: 'm' }) const all = client.subscribe() - const finishedOnly = client.subscribe(n => n.method === 'session.finished') + const idleOnly = client.subscribe(n => n.method === 'session.status' && n.params.status === 'idle') await client.prompt('sub-test', normalizeInput('go')) const first = await all.next() expect(first.method).toBe('session.event') - const finished = await finishedOnly.next() - expect(finished.method).toBe('session.finished') - expect(finishedOnly.tryNext()).toBeUndefined() + const idle = await idleOnly.next() + expect(idle.method).toBe('session.status') + expect(idleOnly.tryNext()).toBeUndefined() // A bare unbounded request with omitted params sends `{}` on the wire. const identity = await client.request('initialize') as { serverInfo: { name: string } } @@ -328,12 +310,12 @@ describe('HarnessClient', () => { const collected: string[] = [] for await (const notification of all) { collected.push(notification.method) - if (notification.method === 'session.finished') break + if (notification.method === 'session.status' && notification.params.status === 'idle') break } - expect(collected.at(-1)).toBe('session.finished') + expect(collected.at(-1)).toBe('session.status') all.close() - finishedOnly.close() + idleOnly.close() await expect(all.next()).rejects.toThrow('notification subscription closed') await client.close() }) @@ -346,11 +328,11 @@ describe('HarnessClient', () => { const broken = client.subscribe(() => { throw new Error('filter exploded') }) // A non-Error throw is normalized rather than crashing dispatch. const brokenNonError = client.subscribe(() => { throw 'string boom' }) - const healthy = client.subscribe(n => n.method === 'session.finished') + const healthy = client.subscribe(n => n.method === 'session.status' && n.params.status === 'idle') await client.prompt('filter-contain', normalizeInput('go')) // The sibling subscription and the read loop are undisturbed. - expect((await healthy.next()).method).toBe('session.finished') + expect((await healthy.next()).method).toBe('session.status') // Each broken subscription failed with ITS OWN error and detached. await expect(broken.next()).rejects.toThrow('filter exploded') await expect(brokenNonError.next()).rejects.toThrow('string boom') @@ -445,10 +427,6 @@ describe('wire payload validation', () => { await expect(harness.run('no-data')).rejects.toThrow(SdkProtocolError) }) - it('rejects a malformed session.finished reason as a protocol error', async () => { - const harness = harnessWith({ FAKE_MALFORMED_REASON: '1' }) - await expect(harness.run('bad-reason')).rejects.toThrow(SdkProtocolError) - }) }) describe('stderr tail bound', () => { diff --git a/packages/sdk/sdk-protocol/README.i18n.yaml b/packages/sdk/sdk-protocol/README.i18n.yaml index 7eec4f64dd..a8ab928a9d 100644 --- a/packages/sdk/sdk-protocol/README.i18n.yaml +++ b/packages/sdk/sdk-protocol/README.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 packages/sdk/sdk-protocol/README.md -README.md: 62b26d4a82d358fa4efcb7ab84036e5f4848057f -README.zh.md: 11677c6119c7da407d95ee38ad9f8f7a552c15de +README.md: 2120e6090fcc5d5f4a543424e9c5647e6009bad6 +README.zh.md: 70b046cf1dedbf01031e3e0a4441f522d6153fbc diff --git a/packages/sdk/sdk-protocol/README.md b/packages/sdk/sdk-protocol/README.md index 62b26d4a82..2120e6090f 100644 --- a/packages/sdk/sdk-protocol/README.md +++ b/packages/sdk/sdk-protocol/README.md @@ -15,14 +15,14 @@ The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delim | Direction | Method | Types | |---|---|---| | client→server | `initialize` | `InitializeParams` → `InitializeResult` | -| client→server | `session/prompt` | `SessionPromptParams` → `SessionPromptResult` (answered only after turn settlement) | +| client→server | `session/prompt` | `SessionPromptParams` → `SessionPromptResult` (durable enqueue receipt) | | client→server | `shutdown` | no params → `{}` | | server→client | `session.event` | `SessionEventNotification` (every session in the runtime, unfiltered) | -| server→client | `session.finished` | `SessionFinishedNotification` (one per accepted prompt) | +| server→client | `session.status` | `SessionStatusNotification` (whole-agent `running`/`idle` transition) | | server→client | `subagent.started` | `SubagentStartedNotification` | | server→client | `subagent.finished` | `SubagentFinishedNotification` (in-process runs only) | -`HarnessSdkRequestMap` and `HarnessSdkNotificationMap` index these by method name. `InitializeParams.maxTokens` is an optional positive safe integer that caps each conversation-model output for SDK-created agents and their in-process descendants; omission leaves the provider default in control. The notification payload types depend on `SessionEvent` (`dsh-session`), `ContentBlock` (`dsh-llm`), and `SubagentStopReason` (`dsh-subagent`) — the protocol streams full session-log envelopes, so the session vocabulary is part of the wire contract. `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`. +`HarnessSdkRequestMap` and `HarnessSdkNotificationMap` index these by method name. `SessionPromptResult.messageId` identifies the queued `UserMessage`; it does not identify a later assistant message, turn ending, or prompt result. Clients combine the open-ended `session.event` stream with agent-wide `session.status` according to their own activity ownership. `InitializeParams.maxTokens` is an optional positive safe integer that caps each conversation-model output for SDK-created agents and their in-process descendants; omission leaves the provider default in control. The notification payload types depend on `SessionEvent` (`dsh-session`), `ContentBlock` (`dsh-llm`), and `SubagentStopReason` (`dsh-subagent`) — the protocol streams full session-log envelopes, so the session vocabulary is part of the wire contract. `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`. ## Model Experience diff --git a/packages/sdk/sdk-protocol/README.zh.md b/packages/sdk/sdk-protocol/README.zh.md index 11677c6119..70b046cf1d 100644 --- a/packages/sdk/sdk-protocol/README.zh.md +++ b/packages/sdk/sdk-protocol/README.zh.md @@ -15,14 +15,14 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按 | 方向 | 方法 | 类型 | |---|---|---| | client→server | `initialize` | `InitializeParams` → `InitializeResult` | -| client→server | `session/prompt` | `SessionPromptParams` → `SessionPromptResult`（仅在轮次结算完成后应答） | +| client→server | `session/prompt` | `SessionPromptParams` → `SessionPromptResult`（持久入队回执） | | client→server | `shutdown` | 无参数 → `{}` | | server→client | `session.event` | `SessionEventNotification`（运行时内每个会话，不过滤） | -| server→client | `session.finished` | `SessionFinishedNotification`（每个获准的提示词请求一条） | +| server→client | `session.status` | `SessionStatusNotification`（整个 agent（智能体）的 `running`/`idle` 转换） | | server→client | `subagent.started` | `SubagentStartedNotification` | | server→client | `subagent.finished` | `SubagentFinishedNotification`（仅进程内运行） | -`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent（智能体）及其进程内后代的每次对话模型输出；省略时由提供方默认值控制。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式契约的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。 +`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时由提供方默认值控制。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式契约的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。 ## 模型体验 diff --git a/packages/sdk/sdk-protocol/src/index.ts b/packages/sdk/sdk-protocol/src/index.ts index c11a270f47..777290c17c 100644 --- a/packages/sdk/sdk-protocol/src/index.ts +++ b/packages/sdk/sdk-protocol/src/index.ts @@ -17,7 +17,7 @@ export type { InitializeResult, SdkRunStatus, SessionEventNotification, - SessionFinishedNotification, + SessionStatusNotification, SessionPromptParams, SessionPromptResult, SubagentFinishedNotification, diff --git a/packages/sdk/sdk-protocol/src/types.ts b/packages/sdk/sdk-protocol/src/types.ts index 1b7a372f66..dc8e11587f 100644 --- a/packages/sdk/sdk-protocol/src/types.ts +++ b/packages/sdk/sdk-protocol/src/types.ts @@ -9,7 +9,7 @@ */ import type { ContentBlock } from '@deepseek-ai/dsh-llm' -import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' import type { SubagentStopReason } from '@deepseek-ai/dsh-subagent' /** Parameters for the process-wide SDK handshake. */ @@ -38,10 +38,10 @@ export interface SessionPromptParams { contentBlocks: ContentBlock[] } -/** Prompt acceptance after turn settlement; outcome rides on `session.finished`. */ +/** Durable enqueue receipt for one prompt. */ export interface SessionPromptResult { - /** Always `true`; the turn outcome is the paired `session.finished` notification. */ - accepted: true + /** Identity of the queued user message. */ + messageId: string } /** Deployment-mapped SDK outcome: `ok` for an accepted result, `error` otherwise. */ @@ -55,14 +55,12 @@ export interface SessionEventNotification { event: SessionEvent } -/** `session.finished` payload: one per accepted prompt, after turn settlement. */ -export interface SessionFinishedNotification { - /** The settled session. */ +/** Whole-agent lifecycle state for one session. */ +export interface SessionStatusNotification { + /** Session whose live agent changed status. */ sessionId: string - /** Deployment-mapped turn outcome (see `maxTokensAsSuccess` on the server). */ - status: SdkRunStatus - /** Why the last message-triggered turn ended; absent when no turn ran. */ - reason: TurnEndReason | undefined + /** The whole-agent state after the transition. */ + status: 'idle' | 'running' } /** `subagent.started` payload: an in-runtime child session was created. */ @@ -94,7 +92,7 @@ export interface SubagentFinishedNotification { /** Server-to-client notifications by JSON-RPC method name. */ export interface HarnessSdkNotificationMap { 'session.event': SessionEventNotification - 'session.finished': SessionFinishedNotification + 'session.status': SessionStatusNotification 'subagent.started': SubagentStartedNotification 'subagent.finished': SubagentFinishedNotification } diff --git a/packages/sdk/sdk-protocol/tests/transport.spec.ts b/packages/sdk/sdk-protocol/tests/transport.spec.ts index a07324a6fc..c14111be22 100644 --- a/packages/sdk/sdk-protocol/tests/transport.spec.ts +++ b/packages/sdk/sdk-protocol/tests/transport.spec.ts @@ -29,11 +29,11 @@ describe('JsonRpcLineTransport', () => { const response = await b.request('echo', { value: 42 }) expect(response).toEqual({ echoed: { value: 42 } }) - a.notify('session.finished', { sessionId: 'main', status: 'ok' }) + a.notify('session.status', { sessionId: 'main', status: 'idle' }) a.notify('heartbeat') await new Promise(resolve => setTimeout(resolve, 10)) expect(notifications).toEqual([ - { method: 'session.finished', params: { sessionId: 'main', status: 'ok' } }, + { method: 'session.status', params: { sessionId: 'main', status: 'idle' } }, { method: 'heartbeat', params: {} }, ]) diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml index 296617f484..b1bd3ce8e8 100644 --- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml +++ b/packages/subagent/subagent-dsh-sdk/README.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 packages/subagent/subagent-dsh-sdk/README.md -README.md: e904ce3c09a1b44f8f5a0072b9ca85812898e74f -README.zh.md: cec89ad9a65c68163fc136fe7b04cb135c57fb51 +README.md: 834c967354610e9ecbb76380f8ddbce988b51c8c +README.zh.md: 4af03a6647da38adf8283d567b37a10203ad7c90 diff --git a/packages/subagent/subagent-dsh-sdk/README.md b/packages/subagent/subagent-dsh-sdk/README.md index e904ce3c09..834c967354 100644 --- a/packages/subagent/subagent-dsh-sdk/README.md +++ b/packages/subagent/subagent-dsh-sdk/README.md @@ -10,13 +10,13 @@ The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a The working directory resolves exactly like the ACP backend, through the seam's shared out-of-process helpers ([`dsh-subagent`](../subagent/README.md)): the configured `cwd` override when set (validated once at load), else the delegating parent session's cwd — never the server process's own cwd. The resolved path becomes the child process cwd and the workspace cwd of its SDK session. -The returned run id is minted in the parent namespace; the child runtime's session id exists only inside the child process. After publication the provider runs one SDK turn and reads the child's answer from its session events: the last complete `assistant/message`, or the `text-delta` stream accumulated so far when the turn was cut short — a partial answer survives cancel and error paths. +The returned run id is minted in the parent namespace; the child runtime's session id exists only inside the child process. After publication the provider owns one SDK activity and reads the child's answer from its session events: the last complete `assistant/message`, or the `text-delta` stream accumulated before the activity was cut short — a partial answer survives cancel and error paths. `dispose()` is idempotent: it settles the result locally as `aborted` (there is no wire-level prompt cancel), then closes the runtime — a bounded protocol `shutdown` request followed by the shared stdin-EOF → SIGTERM → SIGKILL ladder to actual exit. ## Stop-reason mapping -The child reports its turn outcome as a structured `TurnEndReason` on `session.finished`; the provider maps it into the seam vocabulary. `completed` → `completed`, `max-tokens` → `max-tokens`, `aborted` → `aborted`; everything else — `error`, `interrupted`, `disposed`, a future variant, or a turn that never ran — maps to `error`, so an unclean stop is never reported as success. Transport-level failures after publication flatten to `stopReason: 'error'` through the `onError` diagnostic sink (wired to `ctx.logger.warn`); the seam contract forbids `result` rejecting. +The SDK client returns an owned child activity rather than a prompt result. The provider reads the last durable `turn/end` inside that activity and maps it into the seam vocabulary: `completed` → `completed`, `max-tokens` → `max-tokens`, `aborted` → `aborted`; everything else — `error`, `interrupted`, `disposed`, a future variant, or an activity with no turn — maps to `error`, so an unclean stop is never reported as success. Transport-level failures after publication flatten to `stopReason: 'error'` through the `onError` diagnostic sink (wired to `ctx.logger.warn`); the seam contract forbids `result` rejecting. ## Capabilities and context diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md index cec89ad9a6..4af03a6647 100644 --- a/packages/subagent/subagent-dsh-sdk/README.zh.md +++ b/packages/subagent/subagent-dsh-sdk/README.zh.md @@ -10,13 +10,13 @@ SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepS 工作目录的解析与 ACP 后端完全一致，并使用 seam 共享的进程外辅助工具（[`dsh-subagent`](../subagent/README.md)）：设置了 `cwd` 覆盖值时使用该值（加载时校验一次），否则使用发起委派的父会话 cwd，绝不使用服务器进程自身的 cwd。解析出的路径同时成为子进程 cwd 和其 SDK 会话的工作区 cwd。 -返回的 run id 在父级命名空间中生成；子运行时的会话 id 只存在于子进程内部。发布后，提供方运行一个 SDK 轮次，并从子会话事件中读取答案：最后一条完整的 `assistant/message`，或轮次被截断时已累积的 `text-delta` 流；部分答案在取消和错误路径上都得以保留。 +返回的 run id 在父级命名空间中生成；子运行时的会话 id 只存在于子进程内部。发布后，提供方拥有一段 SDK 活动，并从子会话事件中读取答案：最后一条完整的 `assistant/message`，或该活动中断前已经累积的 `text-delta` 流；部分答案在取消和错误路径上都得以保留。 `dispose()`（资源释放）是幂等的：先在本地把结果确定为 `aborted`（协议层面没有提示词取消机制），再关闭运行时，即先发出一次有界的协议 `shutdown` 请求，随后通过共享的 stdin-EOF → SIGTERM → SIGKILL 阶梯使进程实际退出。 ## 停止原因映射 -子进程在 `session.finished` 上以结构化 `TurnEndReason` 报告轮次结果；提供方将其映射为 seam 词汇。`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或根本未运行轮次，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 契约禁止 `result` 被拒绝。 +SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个持久 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 契约禁止 `result` 被拒绝。 ## 能力与上下文 diff --git a/packages/subagent/subagent-dsh-sdk/src/run.ts b/packages/subagent/subagent-dsh-sdk/src/run.ts index ec88cc1fb1..b8a01ea383 100644 --- a/packages/subagent/subagent-dsh-sdk/src/run.ts +++ b/packages/subagent/subagent-dsh-sdk/src/run.ts @@ -70,8 +70,8 @@ export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1_000 /** * Map a child turn-end reason to a harness {@link SubagentStopReason}. - * @param reason - the `session.finished` reason, or `undefined` when the - * child settled without running a turn. + * @param reason - the owned child run's final durable turn reason, or + * `undefined` when it settled without running a turn. * @returns the harness equivalent; an absent or unknown reason maps to * `error`, so an unclean stop is never reported as `completed`. */ @@ -191,7 +191,10 @@ export async function startSdkRun(request: SubagentStartRequest, spec: SdkRunSpe cancelSettled.then(() => 'cancelled' as const), ]) if (turn === 'cancelled') return { output: collectOutput(), stopReason: 'aborted' } - return { output: collectOutput(), stopReason: sdkStopReason(turn.reason) } + const lastEnd = turn.events.findLast( + (event): event is Extract => event.type === 'turn/end', + ) + return { output: collectOutput(), stopReason: sdkStopReason(lastEnd?.data.reason) } }, collectOutput, cancelled: () => flags.cancelled, diff --git a/packages/subagent/subagent-inprocess/README.i18n.yaml b/packages/subagent/subagent-inprocess/README.i18n.yaml index b834818199..071ca3241a 100644 --- a/packages/subagent/subagent-inprocess/README.i18n.yaml +++ b/packages/subagent/subagent-inprocess/README.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 packages/subagent/subagent-inprocess/README.md -README.md: 980bc18de088c41dfe2f57a5ff0882a60892fc9f -README.zh.md: 1ceb628371c3ae9cee6d8afa6bc1d95ba4cda8ae +README.md: 67f0cf5dd1ecb18542af56953a0eaa40988aca0d +README.zh.md: 58998ce06cd724d6a1f96f08ba31c5da30007b1b diff --git a/packages/subagent/subagent-inprocess/README.md b/packages/subagent/subagent-inprocess/README.md index 980bc18de0..67f0cf5dd1 100644 --- a/packages/subagent/subagent-inprocess/README.md +++ b/packages/subagent/subagent-inprocess/README.md @@ -14,10 +14,12 @@ The driver follows this sequence: 2. Call `parent.ctx.agents.create` directly, passing the required request signal into the factory's creation transaction. 3. During that transaction's unpublished setup window, install the requested persona, tool restriction, and structured-output runtime. 4. Publish the child, retain the returned `AgentHandle`, and drive one task with `child.followup(prompt)` followed by `child.whenIdle()`. -5. Read the child's own last assistant message and latest message-triggered turn reason, excluding any fork seed and later between-turn records. +5. Read the child's own last assistant message and final durable turn reason from the complete owned child run, excluding any fork seed. The child gets the parent's working-directory/session lineage and inherits the parent provider, model, and output-token cap unless `request.agentOptions` overrides them. It gets a fresh flat registration scope: parent ownership does not import parent tool restrictions or establish an authority subset. +This result boundary is valid because the provider owns an isolated child lifecycle from publication through quiescence. Steering submitted during that lifecycle belongs to the child run; the provider does not pretend the initial follow-up alone owns its output. + When the optional sandbox-policy or approval service is composed, the driver snapshots the parent's explicit session override before child creation and appends a source-tagged event during unpublished setup, after any fork history and before session publication. It never copies deployment defaults or one-shot grants; later child switches still win. See the [policy-inheritance decision](../../../.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md). ## Cancellation and ownership diff --git a/packages/subagent/subagent-inprocess/README.zh.md b/packages/subagent/subagent-inprocess/README.zh.md index 1ceb628371..58998ce06c 100644 --- a/packages/subagent/subagent-inprocess/README.zh.md +++ b/packages/subagent/subagent-inprocess/README.zh.md @@ -14,10 +14,12 @@ 2. 直接调用 `parent.ctx.agents.create`，把必需的请求信号传入工厂的创建事务。 3. 在该事务未发布的设置窗口中，安装请求的 persona、工具限制和结构化输出运行时。 4. 发布子 agent，保留返回的 `AgentHandle`，并通过先调用 `child.followup(prompt)`、再调用 `child.whenIdle()` 来驱动一项任务。 -5. 读取子 agent 自身最后一条 assistant 消息，以及由消息触发的最新轮次原因；排除任何 fork 初始内容和后续轮次间记录。 +5. 从完整的自有子运行中读取子 agent 自身最后一条 assistant 消息和最终持久轮次原因，并排除任何 fork 初始内容。 子 agent 会获得父 agent 的工作目录／会话谱系；除非 `request.agentOptions` 覆盖，否则还会继承父 agent 的提供方、模型和输出 token 上限。它获得全新的扁平注册作用域：父级所有权不会导入父 agent 的工具限制，也不会建立权限子集。 +该结果边界成立，是因为提供方拥有从发布到完全停稳的隔离子 agent 生命周期。在该生命周期内提交的 steering（中途引导）属于子运行；提供方不会声称输出只归初始 follow-up 所有。 + 当组合中挂载了可选的沙箱策略或审批服务时，驱动器会在创建子 agent 前对父级的显式会话覆盖项获取快照，并在未发布的设置阶段追加一条带来源标记的事件，使其位于所有 fork 历史之后、会话发布之前。它绝不复制部署默认值或一次性授权；子 agent 后续的切换仍然优先。参见[策略继承决策](../../../.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md)。 ## 取消与所有权 diff --git a/packages/ui/jsonrpc/README.i18n.yaml b/packages/ui/jsonrpc/README.i18n.yaml index 324f8c4d99..c6ffdca04f 100644 --- a/packages/ui/jsonrpc/README.i18n.yaml +++ b/packages/ui/jsonrpc/README.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 packages/ui/jsonrpc/README.md -README.md: b1219ba10269fc7d046da22c280ff1b91424a5ae -README.zh.md: 1c27f5edf2f1f172aa6303697b17e2e77a65842a +README.md: 976c63ee4f00336cd68e30288e569d514e7ee65b +README.zh.md: e7862aaa335c3277863647e0931eb815ef2ccc1a diff --git a/packages/ui/jsonrpc/README.md b/packages/ui/jsonrpc/README.md index b1219ba102..976c63ee4f 100644 --- a/packages/ui/jsonrpc/README.md +++ b/packages/ui/jsonrpc/README.md @@ -10,7 +10,7 @@ The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-proc ## Config -`maxTokensAsSuccess` defaults to `false`. Set it to `true` for evaluation hosts that distinguish an accepted, token-limited agent result from an infrastructure failure. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport seams; production uses process stdio and `process.exit`. +`maxTokensAsSuccess` defaults to `false` and affects only the deployment-mapped status on `subagent.finished`; root-session prompts have no prompt-level status. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport seams; production uses process stdio and `process.exit`. ## stdout is the protocol @@ -22,7 +22,7 @@ The plugin answers `shutdown`, disposes SDK-owned agents and subscriptions to qu ## Wire notes -`initialize.serverInfo.name` is the wire-stable `deepseek-harness-sdk-runtime`. An optional positive `initialize.maxTokens` becomes the request output cap of each SDK-created agent and its in-process descendants; invalid values reject initialization, while omission sends no cap and preserves provider defaults. A session accepts one in-flight prompt; overlap fails immediately, other sessions remain independent, and the session is reusable after settlement. `session.finished` reports that prompt's message-triggered turn outcome; later between-turn records still stream as `session.event` notifications but cannot replace the prompt status. Persistence roots and persona come from `cordis.yml`. +`initialize.serverInfo.name` is the wire-stable `deepseek-harness-sdk-runtime`. An optional positive `initialize.maxTokens` becomes the request output cap of each SDK-created agent and its in-process descendants; invalid values reject initialization, while omission sends no cap and preserves provider defaults. `session/prompt` queues one identified user message and immediately returns `{ messageId }`. The server streams every durable fact as `session.event` and every whole-agent lifecycle transition as `session.status`; it does not assign an assistant message or `turn/end` to that prompt. Independent requests may enqueue more work on the same session. Persistence roots and persona come from `cordis.yml`. ## Model Experience @@ -42,6 +42,7 @@ Append-only; newly visible content follows the reusable request prefix and does ## Known Limitations and Deferred Work -- **The wire has no per-session close or prompt-cancel method** — SDK-created agents remain live until process shutdown, and one accepted prompt runs to agent idle before that session accepts another. +- **The wire has no per-session close or prompt-cancel method** — SDK-created agents remain live until process shutdown. +- **There is no per-prompt result** — `MessageId` identifies inbox admission only; clients that own an automation interval must define and observe that interval themselves. - **stdout purity is deployment-enforced** — a surrounding config can still load a stdout logger and corrupt the JSON-RPC channel; this plugin does not inspect or veto sibling loggers. - **Automatic adapter mounting is DeepSeek-specific** — `initialize` can reuse any pre-registered model adapter, but its only fallback mounts `dsh-llm-deepseek`. diff --git a/packages/ui/jsonrpc/README.zh.md b/packages/ui/jsonrpc/README.zh.md index 1c27f5edf2..e7862aaa33 100644 --- a/packages/ui/jsonrpc/README.zh.md +++ b/packages/ui/jsonrpc/README.zh.md @@ -10,7 +10,7 @@ ## 配置 -`maxTokensAsSuccess` 默认为 `false`。对于需要区分「因 token 上限而结束但可接受的 agent 结果」与「基础设施故障」的评测宿主，请将其设为 `true`。`JsonRpcConfig.input`、`output` 和 `exit` 是仅供运行时使用的传输 seam；生产环境使用进程 stdio 和 `process.exit`。 +`maxTokensAsSuccess` 默认为 `false`，且只影响 `subagent.finished` 上由部署映射的状态；根会话提示词没有提示词级状态。`JsonRpcConfig.input`、`output` 和 `exit` 是仅供运行时使用的传输 seam；生产环境使用进程 stdio 和 `process.exit`。 ## stdout 即协议 @@ -22,7 +22,7 @@ Stdout 只承载 JSON-RPC 帧。部署不得组合 stdout logger；诊断应写 ## 协议说明 -`initialize.serverInfo.name` 的协议稳定值为 `deepseek-harness-sdk-runtime`。可选的正整数 `initialize.maxTokens` 会成为每个 SDK 创建的 agent 及其进程内后代的请求输出上限；非法值会使初始化失败，省略时则不发送上限并保留提供方默认值。一个会话只接受一个进行中的提示词；重叠请求会立即失败，其他会话保持独立，当前请求结算后该会话可再次使用。`session.finished` 报告由该提示词消息触发的轮次结果；后续轮次间记录仍会作为 `session.event` 通知流式发出，但不能替换该提示词的状态。持久化根目录和 persona 由 `cordis.yml` 提供。 +`initialize.serverInfo.name` 的协议稳定值为 `deepseek-harness-sdk-runtime`。可选的正整数 `initialize.maxTokens` 会成为每个 SDK 创建的 agent 及其进程内后代的请求输出上限；非法值会使初始化失败，省略时则不发送上限并保留提供方默认值。`session/prompt` 将一条带标识的用户消息排入队列，并立即返回 `{ messageId }`。服务器将每个持久事实作为 `session.event` 流式发出，并将整个 agent 生命周期的每次状态转换作为 `session.status` 发出；它不会把某条助手消息或 `turn/end` 归属于该提示词。同一会话上的独立请求可以继续排入更多工作。持久化根目录和 persona 由 `cordis.yml` 提供。 ## 模型体验 @@ -42,6 +42,7 @@ Stdout 只承载 JSON-RPC 帧。部署不得组合 stdout logger；诊断应写 ## 已知限制与暂缓事项 -- **协议没有逐会话关闭或提示词取消方法**：SDK 创建的 agent 会一直存活到进程关闭；一条已接受的提示词必须运行到 agent 空闲，该会话才能接受下一条。 +- **协议没有逐会话关闭或提示词取消方法**：SDK 创建的 agent 会一直存活到进程关闭。 +- **没有逐提示词结果**：`MessageId` 只标识 inbox 准入；拥有自动化活动区间的客户端必须自行定义并观察该区间。 - **stdout 纯净性由部署保证**：外围配置仍可能加载 stdout logger 并破坏 JSON-RPC 通道；此插件不会检查或否决同级 logger。 - **自动挂载适配器仅支持 DeepSeek**：`initialize` 可以复用任何预先注册的模型适配器，但唯一的回退行为是挂载 `dsh-llm-deepseek`。 diff --git a/packages/ui/jsonrpc/src/server.ts b/packages/ui/jsonrpc/src/server.ts index 7143e4c525..09beabab18 100644 --- a/packages/ui/jsonrpc/src/server.ts +++ b/packages/ui/jsonrpc/src/server.ts @@ -10,7 +10,7 @@ import { resolve } from 'node:path' import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent' import { createUserMessage } from '@deepseek-ai/dsh-llm' import { carrierKeyOf, type Scoped } from '@deepseek-ai/dsh-scope' -import { SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session' +import { SessionId } from '@deepseek-ai/dsh-session' import type SubagentService from '@deepseek-ai/dsh-subagent' import type { SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' @@ -19,7 +19,6 @@ import type { InitializeResult, JsonRpcTransportPeer, SessionEventNotification, - SessionFinishedNotification, SessionPromptParams, SessionPromptResult, SubagentFinishedNotification, @@ -28,7 +27,6 @@ import type { interface SessionRecord { handle: AgentHandle - activePrompt: boolean } /** Recover the delegating parent from the service-owned scoped carrier. */ @@ -74,6 +72,9 @@ export class HarnessSdkServer { const payload: SessionEventNotification = { sessionId: String(session.id), event } this.transport.notify('session.event', payload) })) + this.disposers.push(ctx.on('agent/status', (agent, status) => { + this.transport.notify('session.status', { sessionId: String(agent.session.id), status }) + })) this.disposers.push(ctx.on('session/created', (session) => { const parentSession = session.header.parentSession if (parentSession === undefined) return @@ -124,36 +125,21 @@ export class HarnessSdkServer { } /** - * Run one prompt to settlement; overlap on the same session fails. + * Queue one identified prompt without assigning later activity to it. * @param params - target session and user content. - * @returns acceptance after the turn settled. + * @returns the durable message identity. */ async prompt(params: SessionPromptParams): Promise { const rec = await this.getOrCreateSession(params.sessionId) - if (rec.activePrompt) throw new Error(`session already has an active prompt: ${params.sessionId}`) // An agent-loop-only reload disposes the loop's agents while this record // survives; a retained agent accepts followup() silently, so validate the // record against the live registry before delivery (as the ACP bridge does). if (this.ctx.agents.get(rec.handle.agent.id) !== rec.handle.agent) { throw new Error(`session agent was disposed outside the server: ${params.sessionId}`) } - rec.activePrompt = true - try { - const message = createUserMessage({ content: params.contentBlocks, source: { kind: 'user' } }) - rec.handle.agent.followup(message) - await rec.handle.agent.whenIdle() - const lastEnd = rec.handle.agent.session.events.findLast(event => event.type === 'turn/end') - const reason = lastEnd?.data.reason - const payload: SessionFinishedNotification = { - sessionId: params.sessionId, - status: this.finishedStatus(reason), - reason, - } - this.transport.notify('session.finished', payload) - return { accepted: true } - } finally { - rec.activePrompt = false - } + const message = createUserMessage({ content: params.contentBlocks, source: { kind: 'user' } }) + rec.handle.agent.followup(message) + return { messageId: message.id } } /** @@ -239,16 +225,11 @@ export class HarnessSdkServer { ...this.maxTokens === undefined ? {} : { maxTokens: this.maxTokens }, }, }) - const rec: SessionRecord = { handle, activePrompt: false } + const rec: SessionRecord = { handle } this.sessions.set(sessionId, rec) return rec } - private finishedStatus(reason: TurnEndReason | undefined): 'ok' | 'error' { - if (!reason) return 'error' - return successStatus(reason.kind, this.options) - } - private hasAdapterFor(provider: string): boolean { return this.ctx.get('llm')?.listProviders().some(entry => entry.id === provider) ?? false } diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml index 0115e41ce9..fc03f5b057 100644 --- a/python/sdk/README.i18n.yaml +++ b/python/sdk/README.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 python/sdk/README.md -README.md: f1e16e724efd6f71f63e475e47d7e4d704b8ceac -README.zh.md: 11ff235a0eea23acab5f1737537c799021c35bea +README.md: 81bac18690665e4f48e6edb0a7053d7979e613df +README.zh.md: 8ce2fe85ec38327ddc9183661c3b26fe97dfa630 diff --git a/python/sdk/README.md b/python/sdk/README.md index f1e16e724e..81bac18690 100644 --- a/python/sdk/README.md +++ b/python/sdk/README.md @@ -35,7 +35,9 @@ with DeepSeekHarness( `provider` selects a provider route registered by the chosen Cordis composition; `model` is the model id resolved by that adapter. `max_tokens` is an optional positive per-request output-token cap for the root agent and its in-process descendants; omission leaves the provider default in control. Compaction summaries keep the separate limit configured by their compaction plugin. The bundled default composition registers `deepseek`. A custom composition can mount `llm-pi-ai`, configure provider-specific credentials/endpoints there, and select any provider/model present in pi-ai's installed catalog. -`HarnessClient` retains discovered subagent ancestry for the lifetime of the runtime process. During each `Session.run()`, `TurnResult.notifications` and `on_notification` receive the root session and all known descendant notifications in wire order, including nested subagent lifecycle and session events. `TurnResult.events` remains the root session's complete event stream, and `TurnResult.final_response` is the text content from its last `assistant/message`; descendant messages therefore cannot replace the root response. +`Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, events, notifications, session_root)`. The result has no prompt-level status or turn reason: `final_response` is the last committed root-session assistant text in the interval, not an output causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle. + +`HarnessClient` retains discovered subagent ancestry for the lifetime of the runtime process. During each `Session.run()`, `RunResult.notifications` and `on_notification` receive the root session and all known descendant notifications in wire order, including nested subagent lifecycle and session events. `RunResult.events` contains root-session events only, so descendant messages cannot replace the root response. The low-level `session_prompt()` returns the queued `MessageId` immediately; callers that bypass `Session.run()` own any later activity boundary themselves. The same behavior can be selected for the runtime subprocess with `DSH_CORDIS_CONFIG`. The injection lives in `HarnessClient.start()`, so the low-level client's default launch gets it too: when the launch resolves to the bundled runtime and neither `cordis` nor a non-empty `DSH_CORDIS_CONFIG` is set (the runtime treats an empty value as absent, and so does the injection check), the bundled default configuration is used; an explicit `runtime_bin`, `bridge_bin`, or `launch_args_override` disables the injection entirely. See the [sdk-runtime README](../sdk-runtime/README.md) for the runtime carriers (production exe vs dev-only node closure) and how to obtain them. diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md index 11ff235a0e..8ce2fe85ec 100644 --- a/python/sdk/README.zh.md +++ b/python/sdk/README.zh.md @@ -31,7 +31,9 @@ with DeepSeekHarness( `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent 及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。 -`HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`TurnResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`TurnResult.events` 仍只保存根会话的完整事件流，`TurnResult.final_response` 则取该会话最后一个 `assistant/message` 的文本内容，因此后代消息不会覆盖根会话回复。 +`Session.run()` 拥有一个从提示词的持久 inbox 回执开始、到整个 agent 下一次进入 idle 为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。 + +`HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。 同样的行为也可以通过 `DSH_CORDIS_CONFIG` 为运行时子进程选定。注入逻辑位于 `HarnessClient.start()`，因此底层客户端的默认启动也具有此行为：当启动解析到内置运行时，且 `cordis` 与非空的 `DSH_CORDIS_CONFIG` 均未设置时（运行时把空值视为缺省，注入检查与之一致），使用内置的默认配置；显式给出 `runtime_bin`、`bridge_bin` 或 `launch_args_override` 则完全禁用注入。运行时载体（生产用 exe 与仅限开发的 `node` 闭包）及其获取方式见 [sdk-runtime README](../sdk-runtime/README.md)。 diff --git a/python/sdk/src/deepseek_harness/__init__.py b/python/sdk/src/deepseek_harness/__init__.py index fab791d4f6..c15a6ed810 100644 --- a/python/sdk/src/deepseek_harness/__init__.py +++ b/python/sdk/src/deepseek_harness/__init__.py @@ -1,4 +1,4 @@ -from .api import DeepSeekHarness, DeepSeekHarnessConfig, Session, TurnResult +from .api import DeepSeekHarness, DeepSeekHarnessConfig, RunResult, Session from .client import HarnessClient, HarnessConfig from .models import IncomingRequest, InitializeResponse, JsonObject, Notification, ServerInfo @@ -6,7 +6,7 @@ __all__ = [ "DeepSeekHarness", "DeepSeekHarnessConfig", "Session", - "TurnResult", + "RunResult", "HarnessClient", "HarnessConfig", "IncomingRequest", diff --git a/python/sdk/src/deepseek_harness/api.py b/python/sdk/src/deepseek_harness/api.py index 29bb4223ac..dc55070c0e 100644 --- a/python/sdk/src/deepseek_harness/api.py +++ b/python/sdk/src/deepseek_harness/api.py @@ -35,9 +35,8 @@ class DeepSeekHarnessConfig: @dataclass(slots=True) -class TurnResult: +class RunResult: session_id: str - status: str final_response: str events: list[JsonObject] notifications: list[Notification] @@ -119,7 +118,7 @@ class DeepSeekHarness: *, session_id: str | None = None, on_notification: Callable[[Notification], None] | None = None, - ) -> TurnResult: + ) -> RunResult: return self.start_session(session_id).run(input, on_notification=on_notification) @@ -133,15 +132,12 @@ class Session: input: str | list[JsonObject], *, on_notification: Callable[[Notification], None] | None = None, - ) -> TurnResult: + ) -> RunResult: content_blocks = normalize_input(input) notifications: list[Notification] = [] events: list[JsonObject] = [] - status = "error" - finished = False def collect(notification: Notification) -> None: - nonlocal finished, status notifications.append(notification) if on_notification is not None: on_notification(notification) @@ -152,25 +148,31 @@ class Session: event = notification.payload.get("event") if isinstance(event, dict): events.append(event) - if notification.method == "session.finished" and notification.payload.get("sessionId") == self.id: - status = str(notification.payload.get("status") or "ok") - finished = True with self.harness.client.subscribe_session_notifications(self.id) as subscription: - self.harness.client.session_prompt( + message_id = self.harness.client.session_prompt( self.id, content_blocks, - on_notification=collect, notification_subscription=subscription, ) - while not finished: + received = False + while True: notification = subscription.next() + if not received: + if not _is_inbox_receipt(notification, self.id, message_id): + continue + received = True collect(notification) + if ( + notification.method == "session.status" + and notification.payload.get("sessionId") == self.id + and notification.payload.get("status") == "idle" + ): + break - return TurnResult( + return RunResult( session_id=self.id, - status=status, final_response=final_response(events), events=events, notifications=notifications, @@ -178,6 +180,19 @@ class Session: ) +def _is_inbox_receipt(notification: Notification, session_id: str, message_id: str) -> bool: + if notification.method != "session.event" or notification.payload.get("sessionId") != session_id: + return False + event = notification.payload.get("event") + if not isinstance(event, dict) or event.get("type") != "agent/inbox/spliced": + return False + data = event.get("data") + inserted = data.get("inserted") if isinstance(data, dict) else None + return isinstance(inserted, list) and any( + isinstance(message, dict) and message.get("id") == message_id for message in inserted + ) + + def normalize_input(input: str | list[JsonObject]) -> list[JsonObject]: if isinstance(input, str): return [{"type": "text", "text": input}] diff --git a/python/sdk/src/deepseek_harness/client.py b/python/sdk/src/deepseek_harness/client.py index 052969a694..629ddf901f 100644 --- a/python/sdk/src/deepseek_harness/client.py +++ b/python/sdk/src/deepseek_harness/client.py @@ -10,7 +10,7 @@ import uuid from collections import deque from dataclasses import dataclass from pathlib import Path -from typing import Callable, Literal, TypeAlias, TypeVar +from typing import Callable, TypeAlias, TypeVar from pydantic import BaseModel @@ -142,9 +142,9 @@ class HarnessClient: *, on_notification: Callable[[Notification], None] | None = None, notification_subscription: "NotificationSubscription | None" = None, - ) -> None: + ) -> str: payload: JsonObject = {"sessionId": session_id, "contentBlocks": content_blocks} - self.request( + response = self.request( "session/prompt", payload, response_model=_SessionPromptResponse, @@ -152,6 +152,7 @@ class HarnessClient: notification_filter=self._notification_belongs_to_session_tree(session_id), notification_subscription=notification_subscription, ) + return response.messageId def request( self, @@ -536,7 +537,7 @@ class NotificationSubscription: class _SessionPromptResponse(BaseModel): - accepted: Literal[True] + messageId: str class _ShutdownResponse(BaseModel): diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 4c148f3287..55743bdc15 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -88,28 +88,8 @@ }, { "doc": "docs/core-data-structures/core.md", - "symbol": "InboxPlacement", - "source": "packages/core/agent/src/types.ts" - }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "InboxItem", - "source": "packages/core/agent/src/types.ts" - }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "InboxAction", - "source": "packages/core/agent/src/types.ts" - }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "InboxActionResult", - "source": "packages/core/agent/src/types.ts" - }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "SendOptions", - "source": "packages/core/agent/src/types.ts" + "symbol": "InboxTarget", + "source": "packages/core/agent/src/inbox.ts" }, { "doc": "docs/core-data-structures/core.md", @@ -119,7 +99,7 @@ { "doc": "docs/core-data-structures/core.md", "symbol": "AgentCancelCause", - "source": "packages/core/agent/src/types.ts" + "source": "packages/core/session/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", @@ -136,11 +116,6 @@ "symbol": "RequestErrorAction", "source": "packages/core/agent/src/types.ts" }, - { - "doc": "docs/core-data-structures/core.md", - "symbol": "RequestError", - "source": "packages/core/agent/src/types.ts" - }, { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", @@ -343,11 +318,6 @@ "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, - { - "doc": "docs/core-data-structures/session.md", - "symbol": "TurnTriggerMap", - "source": "packages/core/session/src/types.ts" - }, { "doc": "docs/core-data-structures/session.md", "symbol": "TurnEndReasonMap", From 61803f1a462467d49ec06b1f1b107ba00e40bf03 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 02:07:36 -0700 Subject: [PATCH 013/689] fix(ui-workspace): expose session status accessibly --- packages/client/ui-sidebar/README.i18n.yaml | 4 +-- packages/client/ui-sidebar/README.md | 2 +- packages/client/ui-sidebar/README.zh.md | 2 +- packages/client/ui-workspace/README.i18n.yaml | 4 +-- packages/client/ui-workspace/README.md | 3 +- packages/client/ui-workspace/README.zh.md | 3 +- .../src/client/rows/Rows.module.css | 9 +++++ .../ui-workspace/src/client/rows/Rows.tsx | 36 ++++++++++++------- .../client/ui-workspace/tests/rows.spec.tsx | 15 +++++--- 9 files changed, 52 insertions(+), 26 deletions(-) diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml index 6c5f1735e3..00b33602d0 100644 --- a/packages/client/ui-sidebar/README.i18n.yaml +++ b/packages/client/ui-sidebar/README.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 packages/client/ui-sidebar/README.md -README.md: 93a1f15a5802f94a0ebe930dda1dbd4fbc7343c9 -README.zh.md: 8c8545a5d7d8cb4d58772abf867d7ee82c31bf1d +README.md: d2c0c3332f2202986f1daf3a45c84cc1e65eee6d +README.zh.md: 03cb86842d8a28f3a18250a9d77dd0a0a217d7b9 diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md index 93a1f15a58..d2c0c3332f 100644 --- a/packages/client/ui-sidebar/README.md +++ b/packages/client/ui-sidebar/README.md @@ -22,6 +22,6 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work -- **State dots have two live data states (running/none)** — the done/error/amber sources arrive with P-II approvals and notifications; the four-color primitive is already wired. +- **State dots have approval-waiting/running/none live states** — approval waiting is amber and outranks running; done/error notification sources remain deferred. - **Group-by menu ships by-workspace only** — Update/Status grouping strategies are drawn without specs and deferred. - **"New task completed" unread marking is local viewing state** — completion-time > last-seen never reaches the host. diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md index 8c8545a5d7..03cb86842d 100644 --- a/packages/client/ui-sidebar/README.zh.md +++ b/packages/client/ui-sidebar/README.zh.md @@ -22,6 +22,6 @@ New Session 会启动运行时的页面局部前端 Session Intent；真实 Work ## 已知限制与暂缓事项 -- **状态点只有两种实时数据状态（running/none）**：done/error/amber 的数据源将随 P-II 审批与通知功能一并提供；四色原语已接入。 +- **状态点具有待审批／running／none 三种实时状态**：待审批使用琥珀色并优先于 running；done/error 的通知数据源仍暂缓实现。 - **分组选单只提供按 Workspace 分组**：Update/Status 分组策略只有图稿而没有规范，暂缓实现。 - **「New task completed」未读标记是本地查看状态**：完成时间 > 上次查看时间这一事实永远不会到达宿主。 diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml index bada1e738d..27cb783db7 100644 --- a/packages/client/ui-workspace/README.i18n.yaml +++ b/packages/client/ui-workspace/README.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 packages/client/ui-workspace/README.md -README.md: 1497f816a295e2cd156af9b779bce0b42759e1c7 -README.zh.md: be496412db9790b0625b40f0bbb06c1d406af015 +README.md: 4ca836e4f1beeb164716e5fc4741253719d2700c +README.zh.md: 2a5448a12d58184b027c99b5301510370ba63a83 diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md index 1497f816a2..4ca836e4f1 100644 --- a/packages/client/ui-workspace/README.md +++ b/packages/client/ui-workspace/README.md @@ -6,7 +6,7 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration. -Session rows project the runtime's live `waitingApproval` fact: an amber warning dot takes precedence over the blue running indicator, and the hover card reports **Waiting for approval** until the request is resolved. Running and idle presentation is unchanged when no approval is pending. +Session rows distinguish the runtime's live `waitingApproval` fact from an otherwise blue in-flight Session: an amber warning dot takes precedence over the running indicator, an accompanying visually hidden label exposes the state to assistive technology, and the hover card reports **Waiting for approval** until the request is resolved. Running and idle presentation is unchanged when no approval is pending. Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored. @@ -21,4 +21,5 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work - **No Session deletion or fork control** — the Session menu's Fork and Delete rows remain visual-only (Rename is wired); Workspace registration deletion does not delete Sessions. +- **Approval waiting is not aggregated into hidden ancestors** — a waiting child Session under a folded parent, or any waiting row inside a collapsed group, becomes visible only after that container is expanded. - **Native folder selection depends on the local Host carrier** — under the `-native` composition, fixture-only or remote browser deployments cannot open a local operating-system dialog; platform failures are shown in a retryable modal. Remote-capable picking is the `-browse` composition's in-app flow. diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md index be496412db..2a5448a12d 100644 --- a/packages/client/ui-workspace/README.zh.md +++ b/packages/client/ui-workspace/README.zh.md @@ -6,7 +6,7 @@ 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。 -Session 行会投影 runtime 的实时 `waitingApproval` 状态：琥珀色警告点优先于蓝色运行指示器，hover 卡片在请求解决前显示 **Waiting for approval**。没有待审批请求时，运行与空闲展示保持不变。 +Session 行会把 runtime 的实时 `waitingApproval` 状态与原本显示为蓝色的进行中 Session 区分开：琥珀色警告点优先于运行指示器，随附的视觉隐藏标签会向辅助技术公开这一状态，hover 卡片则在请求解决前显示 **Waiting for approval**。没有待审批请求时，运行与空闲展示保持不变。 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。 @@ -21,4 +21,5 @@ Session 行会投影 runtime 的实时 `waitingApproval` 状态：琥珀色警 ## 已知限制与暂缓事项 - **没有 Session 删除与 fork 控件**：Session 菜单的 Fork 与 Delete 行仍仅提供视觉效果（Rename 已接线）；删除 Workspace 注册记录不会删除 Session。 +- **待审批状态不会聚合到隐藏的祖先节点**：折叠父节点下正在等待的子 Session，或折叠分组内的任何等待行，只有在对应容器展开后才可见。 - **原生文件夹选择依赖本地 Host 载体**：在 `-native` 组合下，仅使用 fixture（测试前置数据）的部署或远程浏览器部署无法打开本地操作系统对话框；模态框会显示平台故障，并允许重试。可远程的选取是 `-browse` 组合的应用内流程。 diff --git a/packages/client/ui-workspace/src/client/rows/Rows.module.css b/packages/client/ui-workspace/src/client/rows/Rows.module.css index 7b19284b66..6d5e90beeb 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.module.css +++ b/packages/client/ui-workspace/src/client/rows/Rows.module.css @@ -68,6 +68,15 @@ color: var(--dsw-alias-label-tertiary); } +.visuallyHidden { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip: rect(0 0 0 0); + white-space: nowrap; +} + .folderActive { color: var(--dsw-alias-state-business-primary); diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx index 4f823d531f..92796c409e 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.tsx +++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx @@ -109,18 +109,6 @@ export function ProjectRowItem({ group, onToggle, onCreate, actions }: { ) } -/** - * One session subtree: the node's own 34px row (indent by depth, expand - * twist when it has children, running dot, relative time) plus its visible - * children, recursively — the component tree mirrors the derived tree. - * @param props.node - derived session node. - * @param props.depth - 0 = directly under the group header. - * @param props.currentId - selected session id (row highlight). - * @param props.now - epoch ms for relative-time formatting. - * @param props.onOpen - open a session by id. - * @param props.onToggle - unfold/fold a subtree by id. - * @returns the node's row followed by its children. - */ /** Session status presentation; approval waiting outranks the underlying running state. */ function sessionStatus(node: SessionNode): { state: 'warning' | 'ongoing' | 'done'; label: string } { if (node.waitingApproval) return { state: 'warning', label: 'Waiting for approval' } @@ -167,6 +155,21 @@ function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' | return e.clientY < rect.top + rect.height / 2 ? 'before' : 'after' } +/** + * One session subtree: the node's own 34px row (indent by depth, expand + * twist when it has children, status dot, relative time) plus its visible + * children, recursively — the component tree mirrors the derived tree. + * @param props.node - derived session node. + * @param props.depth - 0 = directly under the group header. + * @param props.currentId - selected session id (row highlight). + * @param props.now - epoch ms for relative-time formatting. + * @param props.onOpen - open a session by id. + * @param props.onRename - rename a session by id and current title. + * @param props.onToggle - unfold/fold a subtree by id. + * @param props.drag - optional root-row drag wiring. + * @param props.flat - omit tree indentation controls for a flat list. + * @returns the node's row followed by its children. + */ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onToggle, drag, flat = false }: { node: SessionNode depth: number @@ -235,7 +238,14 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, ) : null} - {(row.waitingApproval || row.running) && } + + {status.state !== 'done' && ( + <> + + {status.label} + + )} + {row.title} {formatRelativeTime(row.updatedAt, now)} diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx index 0b6837c0bc..f9caa54c0b 100644 --- a/packages/client/ui-workspace/tests/rows.spec.tsx +++ b/packages/client/ui-workspace/tests/rows.spec.tsx @@ -191,7 +191,7 @@ describe('workspace browser rows', () => { // Card body: full title + relative time + running status. expect(screen.getAllByText('Hovered')).toHaveLength(2) expect(screen.getByText('1min ago')).toBeTruthy() - expect(screen.getByText('Running')).toBeTruthy() + expect(screen.getAllByText('Running')).toHaveLength(2) fireEvent.pointerLeave(wrapper) // Menu open (disabled=true) suppresses the card for the same hover. fireEvent.click(screen.getByRole('button', { name: 'Session actions for Hovered' })) @@ -210,15 +210,20 @@ describe('workspace browser rows', () => { id: sid('approval'), title: 'Needs approval', children: [], hasChildren: false, expanded: false, waitingApproval: true, running: true, updatedAt: 0, } - render() const row = screen.getByRole('treeitem') expect(row.querySelector('[data-state="warning"]')).toBeTruthy() expect(row.querySelector('[data-state="ongoing"]')).toBeNull() - - fireEvent.pointerEnter(row.parentElement as HTMLElement) - act(() => { vi.advanceTimersByTime(500) }) expect(screen.getByText('Waiting for approval')).toBeTruthy() + + view.rerender() + expect(screen.getByRole('treeitem').querySelector('[data-state="warning"]')).toBeTruthy() + + fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement) + act(() => { vi.advanceTimersByTime(500) }) + expect(screen.getAllByText('Waiting for approval')).toHaveLength(2) expect(document.querySelectorAll('[data-state="warning"]')).toHaveLength(2) } finally { vi.useRealTimers() From 8014abffa011d4b8b4d983f27b0ce2a1776d0fa7 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 02:13:02 -0700 Subject: [PATCH 014/689] test(web): cover waiting approval in built graph --- apps/web/tests/built-boot.snapshot.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts index 69d5d5cfae..018a9f2180 100644 --- a/apps/web/tests/built-boot.snapshot.ts +++ b/apps/web/tests/built-boot.snapshot.ts @@ -102,6 +102,14 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 }) await within(tree).findByText('4 sessions') + // The resident approval fixture proves the assembled workspace plugin + // distinguishes a blocked running session from an ordinarily busy one. + const waitingTitle = await within(tree).findByText('Fixture 历史会话') + const waitingRow = waitingTitle.closest('[role="treeitem"]') + expect(waitingRow?.querySelector('[data-state="warning"]')).not.toBeNull() + expect(waitingRow?.querySelector('[data-state="ongoing"]')).toBeNull() + expect(within(waitingRow as HTMLElement).getByText('Waiting for approval')).not.toBeNull() + // Opening a session reaches chat content through the fixture transport. fireEvent.click(await within(tree).findByText('Fixture 历史会话')) await waitFor(() => { From 472ba33cd941ace8d0ab15aa6f89932206926c3c Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 02:17:14 -0700 Subject: [PATCH 015/689] refactor(ui-workspace): reuse status dot vocabulary --- packages/client/ui-workspace/src/client/rows/Rows.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx index f9bd7f3eaf..fbde2b9522 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.tsx +++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx @@ -12,6 +12,7 @@ import { IconFolderClose16, IconFolderOpen16, IconPlusOutline16, IconTrashOutline16, IconTriangleRightFill14, Menu, StateDot, } from '@deepseek-ai/dsh-client-ui-primitives' +import type { StateDotState } from '@deepseek-ai/dsh-client-ui-primitives' import type { GroupNode, SessionNode } from '../tree.ts' import { formatRelativeTime } from '../tree.ts' import css from './Rows.module.css' @@ -135,7 +136,7 @@ export function ProjectRowItem({ group, onToggle, onCreate, actions }: { } /** Session status presentation; approval waiting outranks the underlying running state. */ -function sessionStatus(node: SessionNode): { state: 'warning' | 'ongoing' | 'done'; label: string } { +function sessionStatus(node: SessionNode): { state: StateDotState; label: string } { if (node.waitingApproval) return { state: 'warning', label: 'Waiting for approval' } if (node.running) return { state: 'ongoing', label: 'Running' } return { state: 'done', label: 'Idle' } From 5a0d26a0e40b44692fb2492a29a7ac47a82b7f45 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 17:28:03 +0800 Subject: [PATCH 016/689] test: migrate consumers to inbox and owned-run APIs --- docs/config-catalog.md | 4 +- docs/cordis-catalog/events.md | 203 +----- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/llm-streaming.md | 10 +- docs/core-data-structures/llm-streaming.zh.md | 10 +- docs/event-producer-consumer.md | 36 +- examples/jsonrpc-agent/tests/sdk.snapshot.ts | 19 +- packages/acp/acp/tests/codec.spec.ts | 18 +- .../src/client/sessions/request-inspection.ts | 9 - .../runtime/src/client/sessions/session.ts | 8 +- .../client/runtime/tests/queue-store.spec.ts | 2 +- .../compact-basic/tests/compact-basic.spec.ts | 5 +- .../time-context/tests/time-context.spec.ts | 3 +- .../tmux-context/tests/tmux-context.spec.ts | 5 +- .../tests/workspace-context.spec.ts | 3 +- .../cordis/tool-cordis/src/api-catalog.ts | 98 +-- packages/core/agent-loop/tests/cancel.spec.ts | 34 +- .../tests/contract-regressions.spec.ts | 23 +- .../agent-loop/tests/coverage-edges.spec.ts | 24 +- .../agent-loop/tests/interception.spec.ts | 84 +-- packages/core/agent-loop/tests/loop.spec.ts | 134 ++-- .../agent-loop/tests/request-error.spec.ts | 13 +- packages/core/agent/tests/agent.spec.ts | 6 +- .../core/scope/src/scoped-events.generated.ts | 1 - packages/core/scope/tests/invariant.spec.ts | 1 + packages/core/session/src/index.ts | 17 - packages/core/session/tests/fork.spec.ts | 6 +- packages/core/session/tests/invariant.spec.ts | 2 +- packages/core/session/tests/session.spec.ts | 23 +- packages/examples/cli-demo/tests/cli.spec.ts | 47 +- .../tests/tools.spec.ts | 9 +- .../command-goal/tests/command-goal.spec.ts | 3 +- .../goal-session/tests/goal-session.spec.ts | 60 +- packages/goal/goal/tests/goal.spec.ts | 3 +- packages/goal/goal/tests/invariant.spec.ts | 16 +- packages/goal/goal/tests/projection.spec.ts | 3 +- .../goal/tool-goal/tests/tool-goal.spec.ts | 3 +- .../hooks-claude/tests/coverage-cases.ts | 8 +- .../hooks/hooks-codex/tests/coverage-cases.ts | 8 +- .../apiproxy/tests/api-proxy-approval.spec.ts | 8 +- .../apiproxy/tests/api-proxy-rename.spec.ts | 2 +- .../tests/api-proxy-workspace.spec.ts | 3 +- .../llm/llm-retry/tests/invariant.spec.ts | 13 +- .../llm/llm-retry/tests/persistence.spec.ts | 3 +- packages/llm/llm-retry/tests/retry.spec.ts | 12 +- packages/llm/llm/README.zh.md | 8 +- packages/llm/llm/src/index.ts | 10 +- packages/llm/llm/tests/service.spec.ts | 655 +++++------------- .../plan/plan-mode/tests/integration.spec.ts | 4 +- .../plan/plan-mode/tests/plan-mode.spec.ts | 11 +- packages/pty/pty-local/tests/index.spec.ts | 9 +- packages/pty/pty-local/tests/local.spec.ts | 5 +- packages/pty/pty/tests/service.spec.ts | 6 +- .../tests/loader-composition.spec.ts | 9 +- .../tool-bash-persistent/tests/tools.spec.ts | 19 +- .../tool-pty/tests/loader-composition.spec.ts | 5 +- packages/pty/tool-pty/tests/tools.spec.ts | 5 +- .../sdk/sdk-client/tests/sdk-client.spec.ts | 3 +- .../session-query-sqlite/tests/sqlite.spec.ts | 2 +- .../tests/search-helpers.spec.ts | 9 +- .../session-title/tests/rename.spec.ts | 10 +- .../skill/tool-skill/tests/tool-skill.spec.ts | 4 +- .../tests/subagent-dsh-sdk.spec.ts | 6 +- .../llm-replay/tests/llm-replay.spec.ts | 2 +- .../tasks/tasks-local/tests/tasks.spec.ts | 6 +- .../session-telemetry-otel/tests/otel.spec.ts | 2 +- .../session-telemetry/tests/telemetry.spec.ts | 2 +- .../ui/permission/tests/projection.spec.ts | 2 +- packages/ui/tui/src/index.ts | 40 +- packages/ui/tui/tests/harness.ts | 2 + packages/ui/tui/tests/tui.snapshot.ts | 14 +- packages/ui/tui/tests/tui.spec.ts | 243 +++---- 72 files changed, 716 insertions(+), 1381 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 4c68290ec3..c11bf455a8 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -27,7 +27,7 @@ export interface AcpConfig { Depends on: `Stream` (`@agentclientprotocol/sdk`) -Source: [`packages/acp/acp/src/index.ts:57`](../packages/acp/acp/src/index.ts) +Source: [`packages/acp/acp/src/index.ts:56`](../packages/acp/acp/src/index.ts) ## `@deepseek-ai/dsh-acp-demo` @@ -749,7 +749,7 @@ Requires: `agents` export type Config = Readonly> ``` -Source: [`packages/llm/llm-retry/src/index.ts:45`](../packages/llm/llm-retry/src/index.ts) +Source: [`packages/llm/llm-retry/src/index.ts:44`](../packages/llm/llm-retry/src/index.ts) ## `@deepseek-ai/dsh-lsp-local` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index dafa342d5a..0c012e58da 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -13,27 +13,6 @@ Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `n ## `agent/*` -### `agent/cancel-requested` — emit - -Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained. - -```ts cordis-catalog -/** - * Effective broad cancellation was requested, before queued/outbox work - * is cleared or the active turn is aborted. This observe-only notification - * cannot veto cancellation; listener failures are contained. - * @param agent - the agent whose current work is being cancelled. - * @param cause - the explicit typed cancellation cause. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/cancel-requested'(this: Scoped, agent: Agent, cause: AgentCancelCause): void -``` - -Types: [Agent](../core-data-structures/core.md) · [AgentCancelCause](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) - -Source: [`packages/core/agent/src/types.ts:319`](../../packages/core/agent/src/types.ts) - ### `agent/created` — emit A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry. @@ -54,7 +33,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:250`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:151`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -74,7 +53,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:160`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -96,115 +75,30 @@ A step or turn errored. The machine reports a failure here (plus the logger) eve Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:433`](../../packages/core/agent/src/types.ts) - -### `agent/inbox/dequeue` — emit - -The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message. - -```ts cordis-catalog -/** - * The driver claimed one item out of the inbox: a queued item at a turn - * boundary, or steering drained between steps. Fires after the item leaves - * its FIFO and before it becomes a durable message. - * @param agent - the agent whose inbox item was claimed. - * @param item - the exact claimed occurrence. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/inbox/dequeue'(this: Scoped, agent: Agent, item: InboxItem): void -``` - -Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) - -Source: [`packages/core/agent/src/types.ts:297`](../../packages/core/agent/src/types.ts) - -### `agent/inbox/discard` — emit - -Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item. - -```ts cordis-catalog -/** - * Pending inbox items were dropped without delivering them, so every - * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR - * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, - * emits this after `agent/cancel-requested` when applicable and before - * aborting the active work. Fires once per drop with every dropped item. - * @param agent - the agent whose inbox items were dropped. - * @param items - the discarded occurrences in FIFO order (queued then steering); never empty. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/inbox/discard'(this: Scoped, agent: Agent, items: InboxItem[]): void -``` - -Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) - -Source: [`packages/core/agent/src/types.ts:309`](../../packages/core/agent/src/types.ts) - -### `agent/inbox/enqueue` — emit - -An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state. - -```ts cordis-catalog -/** - * An item entered the queued or steering inbox. `placement` is the - * acceptance-time routing result; listeners must not reconstruct it from - * later agent or session state. - * @param agent - the owning agent. - * @param item - accepted occurrence, message, and resolved placement. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/inbox/enqueue'(this: Scoped, agent: Agent, item: InboxItem): void -``` - -Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) - -Source: [`packages/core/agent/src/types.ts:278`](../../packages/core/agent/src/types.ts) - -### `agent/inbox/update` — emit - -A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message. - -```ts cordis-catalog -/** - * A still-pending queued item changed content. The item id, placement, and - * position remain stable while the event carries the replacement message. - * @param agent - the owning agent. - * @param item - the complete post-update occurrence. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/inbox/update'(this: Scoped, agent: Agent, item: InboxItem): void -``` - -Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) - -Source: [`packages/core/agent/src/types.ts:287`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:261`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall -Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn. +Allow, rewrite, or block one claimed inbox batch before it becomes model-visible or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn. ```ts cordis-catalog /** - * Allow, rewrite, or block one claimed prompt before it becomes a user - * message or opens a turn. Call `next()` for the unchanged default. The + * Allow, rewrite, or block one claimed inbox batch before it becomes + * model-visible or opens a turn. Call `next()` for the unchanged default. The * signal controls only this admission attempt; listeners may cooperate with * it but must not retain it for a later attempt or turn. - * @param agent - the agent whose turn claimed the message. - * @param message - the frozen claimed message, including identity and source. + * @param agent - the agent whose driver claimed the batch. + * @param messages - the claimed messages. * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ -'agent/prompt-submit'(this: Scoped, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise): Promise +'agent/prompt-submit'(this: Scoped, agent: Agent, messages: UserMessage[], signal: AbortSignal, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) -Source: [`packages/core/agent/src/types.ts:346`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall @@ -228,37 +122,30 @@ Replace the frozen call configuration. `await next()` yields the config the mach Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:372`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:222`](../../packages/core/agent/src/types.ts) ### `agent/request-error` — waterfall -Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal. +Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal. ```ts cordis-catalog /** - * Handle a model-request failure after its failed step has closed but - * before the failed turn closes. A listener returns `{ kind: 'retry' }` - * without calling `next()` when it owns the error, or calls `next()` to - * delegate. The default `undefined` leaves the failure terminal. + * Handle one failed model-request attempt before the loop retries or closes + * its step. A listener returns `{ kind: 'retry' }` without calling `next()` + * when it owns recovery, or calls `next()` to delegate. The default + * `undefined` leaves the failure terminal. * @param agent - the agent whose request failed. - * @param turn - the open turn number. - * @param step - the failed step number. - * @param error - the original model-request failure. - * @param failure - serializable facts normalized at the final adapter boundary. - * @param priorFailures - immutable failures that already authorized another - * retry turn in this consecutive sequence. - * @param retryPolicy - immutable policy of the adapter registration that served - * the failed request, or `undefined` if no final adapter served it. + * @param context - request coordinates, provider, normalized failure, and serving policy. * @param signal - the turn abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ -'agent/request-error'(this: Scoped, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise): Promise +'agent/request-error'(this: Scoped, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestError](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [RequestFailureContext](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:391`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:234`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -280,41 +167,17 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:332`](../../packages/core/agent/src/types.ts) - -### `agent/settled` — emit - -One drain chain reached its terminal turn: that turn's `turn/end` is already committed. Automatically recovered failed turns do not emit this notification, and neither does a run that aborts or fails before its `turn/start` commits — there is no durable turn to settle against. `reason` says why; model-request recovery is exhausted when an error reaches it. - -```ts cordis-catalog -/** - * One drain chain reached its terminal turn: that turn's `turn/end` is - * already committed. Automatically recovered failed turns do not emit this - * notification, and neither does a run that aborts or fails before its - * `turn/start` commits — there is no durable turn to settle against. - * `reason` says why; model-request recovery is exhausted when an error - * reaches it. - * @param agent - the agent whose turn closed. - * @param turn - the terminal turn number. - * @param reason - why the terminal turn ended, with live error facts when it failed. - * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. - * @mode emit - */ -'agent/settled'(this: Scoped, agent: Agent, turn: number, reason: SettleReason): void -``` - -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SettleReason](../core-data-structures/core.md) - -Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:182`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit -Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event. +Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active. ```ts cordis-catalog /** - * Agent status changed (`idle` ⇄ `running`). `send()` does not enter - * `running` synchronously; drive lifecycle from this event. + * Agent status changed (`idle` ⇄ `running`). A waking delivery enters + * `running` synchronously after reserving cancellation; `idle` means no + * driver remains scheduled or active. * @param agent - the agent whose status flipped. * @param status - the status just entered (the transition's destination). * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. @@ -325,7 +188,7 @@ Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` s Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:268`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:170`](../../packages/core/agent/src/types.ts) ### `agent/step` — serial @@ -349,7 +212,7 @@ Awaited serial checkpoint before EVERY request of a turn is built (the first as Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:359`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:209`](../../packages/core/agent/src/types.ts) ### `agent/turn-stopping` — serial @@ -375,7 +238,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:406`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:249`](../../packages/core/agent/src/types.ts) ## `agent-loop/*` @@ -567,7 +430,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md) -Source: [`packages/llm/llm/src/index.ts:58`](../../packages/llm/llm/src/index.ts) +Source: [`packages/llm/llm/src/index.ts:56`](../../packages/llm/llm/src/index.ts) ## `session/*` @@ -592,7 +455,7 @@ Creation announcement during session publication. A synchronous throw vetoes and Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) -Source: [`packages/core/session/src/index.ts:71`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:50`](../../packages/core/session/src/index.ts) ### `session/disposed` — emit @@ -613,7 +476,7 @@ Emitted once when an announced session leaves the store, including publication r Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) -Source: [`packages/core/session/src/index.ts:81`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:60`](../../packages/core/session/src/index.ts) ### `session/event` — emit @@ -636,7 +499,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) -Source: [`packages/core/session/src/index.ts:93`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:72`](../../packages/core/session/src/index.ts) ### `session/flush` — parallel @@ -657,7 +520,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) -Source: [`packages/core/session/src/index.ts:103`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:82`](../../packages/core/session/src/index.ts) ## `skills/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index cda9061a63..26990aa0fc 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1588,7 +1588,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) -Source: [`packages/core/session/src/index.ts:695`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:674`](../../packages/core/session/src/index.ts) ## `ctx.sessionTitle` — `SessionTitleService` diff --git a/docs/core-data-structures/llm-streaming.md b/docs/core-data-structures/llm-streaming.md index 6811611768..7fa02b6e3b 100644 --- a/docs/core-data-structures/llm-streaming.md +++ b/docs/core-data-structures/llm-streaming.md @@ -15,8 +15,9 @@ A streaming response interleaves several typed blocks (text, reasoning, multiple * Raw streaming protocol emitted by adapters. * Block indexes correlate interleaved deltas, and `block-end` carries the * assembled block. Adapters emit usage before the terminal finish and nothing - * afterward; tool arguments remain raw JSON strings. Failures either throw or - * end with `error`/`aborted`, and consumers must handle both paths. + * afterward; tool arguments remain raw JSON strings. An adapter implementation + * may throw, but `LlmService.stream()` normalizes that failure to a terminal + * `error` or `aborted` finish before exposing it to consumers. */ type StreamChunk = | { type: 'block-start'; index: number; blockType: ContentBlockType } @@ -141,7 +142,8 @@ declare class BlockAssembler { push(chunk: StreamChunk): void; /** * Assemble all blocks seen so far, in stream order. - * @returns one block per seen index; an open block assembles from its + * @returns one block per seen index, except that max-token truncation drops + * tool calls that cannot be executed safely; an open block assembles from * accumulated deltas (an unknown block type never closed by `block-end` throws). */ blocks(): ContentBlock[]; @@ -169,6 +171,8 @@ declare class BlockAssembler { interface PreparedLlmCall { /** Detached, deep-frozen config with any adapter-owned default materialized. */ readonly config: LlmCallConfig + /** Immutable retry policy captured with the adapter registration. */ + readonly retryPolicy: ResolvedRetryPolicy /** * Dispatch this call once through the registration captured during * preparation. The request's call-config fields must match {@link config}; diff --git a/docs/core-data-structures/llm-streaming.zh.md b/docs/core-data-structures/llm-streaming.zh.md index 35374af6a2..c25d140895 100644 --- a/docs/core-data-structures/llm-streaming.zh.md +++ b/docs/core-data-structures/llm-streaming.zh.md @@ -15,8 +15,9 @@ * Raw streaming protocol emitted by adapters. * Block indexes correlate interleaved deltas, and `block-end` carries the * assembled block. Adapters emit usage before the terminal finish and nothing - * afterward; tool arguments remain raw JSON strings. Failures either throw or - * end with `error`/`aborted`, and consumers must handle both paths. + * afterward; tool arguments remain raw JSON strings. An adapter implementation + * may throw, but `LlmService.stream()` normalizes that failure to a terminal + * `error` or `aborted` finish before exposing it to consumers. */ type StreamChunk = | { type: 'block-start'; index: number; blockType: ContentBlockType } @@ -141,7 +142,8 @@ declare class BlockAssembler { push(chunk: StreamChunk): void; /** * Assemble all blocks seen so far, in stream order. - * @returns one block per seen index; an open block assembles from its + * @returns one block per seen index, except that max-token truncation drops + * tool calls that cannot be executed safely; an open block assembles from * accumulated deltas (an unknown block type never closed by `block-end` throws). */ blocks(): ContentBlock[]; @@ -169,6 +171,8 @@ declare class BlockAssembler { interface PreparedLlmCall { /** Detached, deep-frozen config with any adapter-owned default materialized. */ readonly config: LlmCallConfig + /** Immutable retry policy captured with the adapter registration. */ + readonly retryPolicy: ResolvedRetryPolicy /** * Dispatch this call once through the registration captured during * preparation. The request's call-config fields must match {@link config}; diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 596f8f99f5..39f074a01c 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -8,22 +8,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:148`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`tui`](../packages/ui/tui) | -| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:319`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal-session`](../packages/goal/goal-session) | -| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:250`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:433`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tui`](../packages/ui/tui) | -| `agent/inbox/dequeue` | `emit` | [`packages/core/agent/src/types.ts:297`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) | -| `agent/inbox/discard` | `emit` | [`packages/core/agent/src/types.ts:309`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) | -| `agent/inbox/enqueue` | `emit` | [`packages/core/agent/src/types.ts:278`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session) | -| `agent/inbox/update` | `emit` | [`packages/core/agent/src/types.ts:287`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy` | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:346`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`tui`](../packages/ui/tui) | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:372`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) | -| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:391`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:332`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-context`](../packages/context/workspace-context) | -| `agent/settled` | `emit` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:268`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | -| `agent/step` | `serial` | [`packages/core/agent/src/types.ts:359`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | -| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:406`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:151`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:160`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:261`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tui`](../packages/ui/tui) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`tui`](../packages/ui/tui) | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:222`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) | +| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:234`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:182`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-context`](../packages/context/workspace-context) | +| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:170`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`jsonrpc`](../packages/ui/jsonrpc), [`tui`](../packages/ui/tui) | +| `agent/step` | `serial` | [`packages/core/agent/src/types.ts:209`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | +| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:249`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` | | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:154`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy`, [`tui`](../packages/ui/tui) | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) | @@ -31,11 +25,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:135`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) | -| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:58`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) | -| `session/created` | `emit` | [`packages/core/session/src/index.ts:71`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) | -| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | -| `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | -| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:103`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | +| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:56`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) | +| `session/created` | `emit` | [`packages/core/session/src/index.ts:50`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) | +| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:60`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | +| `session/event` | `emit` | [`packages/core/session/src/index.ts:72`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | +| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:82`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | [`tui`](../packages/ui/tui) | | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) | | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:114`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | diff --git a/examples/jsonrpc-agent/tests/sdk.snapshot.ts b/examples/jsonrpc-agent/tests/sdk.snapshot.ts index 11c7615c48..57a99a00ef 100644 --- a/examples/jsonrpc-agent/tests/sdk.snapshot.ts +++ b/examples/jsonrpc-agent/tests/sdk.snapshot.ts @@ -2,7 +2,7 @@ * Keyless snapshot coverage for the TypeScript SDK path: each scenario spawns * the REAL `dsh-jsonrpc-agent` runtime (per `DSH_EXAMPLE_MODE`) through the * REAL `@deepseek-ai/dsh-sdk-client`, drives one turn over stdio JSON-RPC, - * and pins three surfaces — the SDK `TurnResult`, the complete notification + * and pins three surfaces — the SDK `RunResult`, the complete notification * stream, and the persisted session logs. Replay serves recorded model * responses via `llm-replay` (`cordis.snapshot.yml`); `DSH_SNAPSHOT=record` * re-records against the live API; `DSH_SNAPSHOT=refresh` replays committed @@ -25,7 +25,7 @@ import { type NormalizeContext, } from '@deepseek-ai/dsh-acp-snapshot' import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' -import { DeepSeekHarness, type HarnessNotification, type TurnResult } from '@deepseek-ai/dsh-sdk-client' +import { DeepSeekHarness, type HarnessNotification, type RunResult } from '@deepseek-ai/dsh-sdk-client' const testsDir = dirOf(import.meta.url) const snapshotsDir = join(testsDir, 'snapshots') @@ -187,18 +187,17 @@ function normalizeNotifications(notifications: readonly HarnessNotification[], c return normalizeStdout(`${records.map(record => JSON.stringify(record)).join('\n')}\n`, ctx) } -/** Normalize the turn-result projection (status, reason kind, final text). */ -function normalizeResult(result: TurnResult, ctx: NormalizeContext): string { +/** Normalize the owned-run projection. */ +function normalizeResult(result: RunResult, ctx: NormalizeContext): string { return normalizeStdout(`${JSON.stringify({ - status: result.status, - reason: result.reason, + sessionId: result.sessionId, finalResponse: result.finalResponse, })}\n`, ctx) } /** One SDK turn against a fresh runtime subprocess in an isolated cwd. */ async function runScenario(scenario: SdkScenario): Promise<{ - result: TurnResult + result: RunResult notifications: HarnessNotification[] logs: PersistedLog[] observedFiles: Record @@ -351,8 +350,10 @@ describe('TypeScript SDK snapshots over the jsonrpc runtime', () => { expect(normalizedResult).toBe(await readFile(resultExpectedPath, 'utf8')) // Wire-shape invariants that must hold in every mode. - expect(result.status).toBe('ok') - expect(notifications.at(-1)?.method).toBe('session.finished') + expect(notifications.at(-1)).toMatchObject({ + method: 'session.status', + params: { status: 'idle' }, + }) expect(observedFiles).toEqual(scenario.expectedFiles ?? {}) if (scenario.expectedTools !== undefined) { const parent = ordered[0] diff --git a/packages/acp/acp/tests/codec.spec.ts b/packages/acp/acp/tests/codec.spec.ts index 0136ae7a94..ebee8a03c4 100644 --- a/packages/acp/acp/tests/codec.spec.ts +++ b/packages/acp/acp/tests/codec.spec.ts @@ -1,23 +1,7 @@ import { describe, expect, it } from 'vitest' -import type { TurnEndReason } from '@deepseek-ai/dsh-session' -import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason } from '../src/codec.ts' +import { acpPromptToText, promptHasUnsupportedContent } from '../src/codec.ts' describe('ACP automation codec', () => { - it('maps every known turn outcome to a legal stop reason', () => { - const cases: [TurnEndReason, string][] = [ - [{ kind: 'completed' }, 'end_turn'], - [{ kind: 'max-tokens' }, 'max_tokens'], - [{ kind: 'aborted', reason: { kind: 'user' } }, 'cancelled'], - [{ kind: 'interrupted' }, 'cancelled'], - [{ kind: 'error', error: new Error('boom') }, 'end_turn'], - ] - for (const [reason, expected] of cases) expect(turnEndToStopReason(reason)).toBe(expected) - }) - - it('uses a legal fallback for merge-extensible future outcomes', () => { - expect(turnEndToStopReason({ kind: 'future' } as unknown as TurnEndReason)).toBe('end_turn') - }) - it('flattens baseline blocks and rejects everything richer', () => { expect(acpPromptToText([{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }])).toBe('ab') expect(acpPromptToText([ diff --git a/packages/client/runtime/src/client/sessions/request-inspection.ts b/packages/client/runtime/src/client/sessions/request-inspection.ts index e15ad55c8b..bba937f4db 100644 --- a/packages/client/runtime/src/client/sessions/request-inspection.ts +++ b/packages/client/runtime/src/client/sessions/request-inspection.ts @@ -326,15 +326,6 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] }) continue } - if (sourceEvent.type === 'turn/end' && sourceEvent.data.reason.kind === 'error') { - const reason = sourceEvent.data.reason - update(ordinaryByStep.get(requestKey(sourceEvent.data.turn, reason.step)), { - status: 'error', - error: 'failure' in reason ? reason.failure.message : reason.message, - }) - continue - } - const type = sourceEvent.type as string if (type === 'compact/start') { const event = sourceEvent as unknown as CompactionStartEvent diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts index 6850e3e4c9..a686477d23 100644 --- a/packages/client/runtime/src/client/sessions/session.ts +++ b/packages/client/runtime/src/client/sessions/session.ts @@ -4,7 +4,7 @@ import type { Context } from 'cordis' import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type { - HistoryEntry, IApiClient, InboxItemId, MuxFrame, QueueAction, RpcError, + HistoryEntry, IApiClient, MessageId, MuxFrame, QueueAction, RpcError, RpcId, RpcResult, SessionId, ToolEventView, } from '@deepseek-ai/dsh-client-connection/client' // Value import from the inline-safe wire layer (not the connection plugin): @@ -232,7 +232,7 @@ export class Session implements SessionFace { } /** Apply one operation to a still-pending queue occurrence. */ - async updateQueue(itemId: InboxItemId, action: QueueAction): Promise> { + async updateQueue(itemId: MessageId, action: QueueAction): Promise> { try { return (await this.api.sessions.updateQueue({ sessionId: this.sessionId, itemId, action })).result } catch (error) { @@ -405,8 +405,8 @@ export class Session implements SessionFace { case 'session/queue': { this.queued = frame.items.map(item => ({ id: item.id, - preview: queuePreviewOf(item.message.content), - text: queueTextOf(item.message.content), + preview: queuePreviewOf(item.content), + text: queueTextOf(item.content), })) this.queueRev++ this.notifier.markDirty() diff --git a/packages/client/runtime/tests/queue-store.spec.ts b/packages/client/runtime/tests/queue-store.spec.ts index ce684694f5..ef440cb293 100644 --- a/packages/client/runtime/tests/queue-store.spec.ts +++ b/packages/client/runtime/tests/queue-store.spec.ts @@ -108,7 +108,7 @@ describe('queue operation transport', () => { session.handleMuxEnvelope(rid('env-op'), queueFrame([{ id: 'q-op', body: 'pending' }])) const before = session.getSnapshot().queue - await expect(session.updateQueue(iid('q-op'), { kind: 'edit', content: text('next') })) + await expect(session.updateQueue(mid('q-op'), { kind: 'edit', content: text('next') })) .resolves.toEqual({ ok: true, value: { accepted: true } }) expect(api.callsOf('session.updateQueue')).toEqual([{ sessionId: SID, diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index 586934e42c..00f63ffa56 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -1383,7 +1383,10 @@ describe('automatic listener and loader composition', () => { const failure: LlmFailure = { message: error.message, code: error.code ?? 'UNKNOWN' } const turn = owner.session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 1 return agentEvents(ctx, owner).waterfall( - 'agent/request-error', turn, 1, error, failure, [], undefined, signal, next, + 'agent/request-error', + { turn, step: 1, provider: 'test', failure, retryPolicy: undefined }, + signal, + next, ).then(action => action?.kind === 'retry') } diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts index 377e11abd7..884c9430ad 100644 --- a/packages/context/time-context/tests/time-context.spec.ts +++ b/packages/context/time-context/tests/time-context.spec.ts @@ -4,7 +4,7 @@ import Loader from '@cordisjs/plugin-loader' import { createUserMessage, CallId, LlmAdapter } from '@deepseek-ai/dsh-llm' import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm' import { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' -import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent' import { defineContentToolFixture } from '@deepseek-ai/dsh-tools' import AgentLoop from '@deepseek-ai/dsh-agent-loop' import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' @@ -40,6 +40,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { id: SessionId(id), options: {}, session, + inbox: new Inbox(session), status: 'running', ctx: new Context(), followup: () => {}, diff --git a/packages/context/tmux-context/tests/tmux-context.spec.ts b/packages/context/tmux-context/tests/tmux-context.spec.ts index a3a78c0153..4262383b7f 100644 --- a/packages/context/tmux-context/tests/tmux-context.spec.ts +++ b/packages/context/tmux-context/tests/tmux-context.spec.ts @@ -1,7 +1,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent' import { createUserMessage } from '@deepseek-ai/dsh-llm' import { BashExecutor } from '@deepseek-ai/dsh-bash' import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash' @@ -96,6 +96,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { id: SessionId(id), options: {}, session, + inbox: new Inbox(session), status: 'running', ctx: new Context(), followup: () => {}, @@ -109,7 +110,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { } function openMessageTurn(session: Session, turn: number): void { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `turn ${turn}` }], source: { kind: 'user' }, diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index cb4ca3533f..e23ea3205c 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -7,7 +7,7 @@ import Loader from '@cordisjs/plugin-loader' import * as workspaceContext from '@deepseek-ai/dsh-workspace-context' import LlmService, { createUserMessage, CallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent, type UserMessage } from '@deepseek-ai/dsh-session' -import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent' import AgentLoop from '@deepseek-ai/dsh-agent-loop' import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs' import type { @@ -176,6 +176,7 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent { id: SessionId('a1'), options: {}, session, + inbox: new Inbox(session), status: 'idle', followup: () => {}, steer: () => {}, diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 60f7d330d8..7dc1aebf33 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -412,7 +412,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: 'stream(options: GenerateOptions): AsyncIterable', - jsDoc: '/**\n * Stream one model call as raw chunks (token-level deltas). Throws\n * `LlmError` with code `NO_ADAPTER` if no adapter is registered for\n * `options.provider`. Replay state is retained only when the same adapter\n * instance owns its historical provider and the target provider. Final\n * adapter selection remains fixed through asynchronous exact-model resolution\n * and dispatch. Selection, dispatch, and iteration failures retain their\n * original Error identity and are tagged in a call-local scope for narrow\n * agent-loop request recovery; middleware and nested-call failures remain\n * untagged for the outer call.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */', + jsDoc: '/**\n * Stream one model call as raw chunks (token-level deltas). Replay state is\n * retained only when the same adapter instance owns its historical provider\n * and the target provider. Final adapter selection remains fixed through\n * asynchronous exact-model resolution and dispatch. Adapter selection,\n * dispatch, and iteration failures become terminal `error` or `aborted`\n * finish chunks; middleware, nested-call, cleanup, and consumer failures\n * remain thrown.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */', }, ], }, @@ -1119,13 +1119,6 @@ export const EVENT_API: readonly EventApiEntry[] = [ jsDoc: '/**\n * A declarative agent entry failed before it could publish a live agent.\n * Consumers that buffer work for the configured identity use this\n * transient signal to reject that work instead of waiting forever. Normal\n * factory teardown suppresses failures from the cancelled startup attempt.\n * @param sessionId - exact shared agent/session identity that failed startup.\n * @param error - persistence, setup, or publication failure.\n * @mode emit\n */', summary: 'A declarative agent entry failed before it could publish a live agent.', }, - { - name: 'agent/cancel-requested', - mode: 'emit', - signature: '\'agent/cancel-requested\'(this: Scoped, agent: Agent, cause: AgentCancelCause): void', - jsDoc: '/**\n * Effective broad cancellation was requested, before queued/outbox work\n * is cleared or the active turn is aborted. This observe-only notification\n * cannot veto cancellation; listener failures are contained.\n * @param agent - the agent whose current work is being cancelled.\n * @param cause - the explicit typed cancellation cause.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted.', - }, { name: 'agent/created', mode: 'emit', @@ -1147,40 +1140,12 @@ export const EVENT_API: readonly EventApiEntry[] = [ jsDoc: '/**\n * A step or turn errored. The machine reports a failure here (plus the\n * logger) even when the error has no in-turn position for a durable record.\n * @param agent - the agent whose turn errored.\n * @param turn - the turn in which the failure surfaced.\n * @param step - the step at which the failure surfaced.\n * @param error - the failure, verbatim.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', summary: 'A step or turn errored.', }, - { - name: 'agent/inbox/dequeue', - mode: 'emit', - signature: '\'agent/inbox/dequeue\'(this: Scoped, agent: Agent, item: InboxItem): void', - jsDoc: '/**\n * The driver claimed one item out of the inbox: a queued item at a turn\n * boundary, or steering drained between steps. Fires after the item leaves\n * its FIFO and before it becomes a durable message.\n * @param agent - the agent whose inbox item was claimed.\n * @param item - the exact claimed occurrence.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps.', - }, - { - name: 'agent/inbox/discard', - mode: 'emit', - signature: '\'agent/inbox/discard\'(this: Scoped, agent: Agent, items: InboxItem[]): void', - jsDoc: '/**\n * Pending inbox items were dropped without delivering them, so every\n * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR\n * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,\n * emits this after `agent/cancel-requested` when applicable and before\n * aborting the active work. Fires once per drop with every dropped item.\n * @param agent - the agent whose inbox items were dropped.\n * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`.', - }, - { - name: 'agent/inbox/enqueue', - mode: 'emit', - signature: '\'agent/inbox/enqueue\'(this: Scoped, agent: Agent, item: InboxItem): void', - jsDoc: '/**\n * An item entered the queued or steering inbox. `placement` is the\n * acceptance-time routing result; listeners must not reconstruct it from\n * later agent or session state.\n * @param agent - the owning agent.\n * @param item - accepted occurrence, message, and resolved placement.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'An item entered the queued or steering inbox.', - }, - { - name: 'agent/inbox/update', - mode: 'emit', - signature: '\'agent/inbox/update\'(this: Scoped, agent: Agent, item: InboxItem): void', - jsDoc: '/**\n * A still-pending queued item changed content. The item id, placement, and\n * position remain stable while the event carries the replacement message.\n * @param agent - the owning agent.\n * @param item - the complete post-update occurrence.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'A still-pending queued item changed content.', - }, { name: 'agent/prompt-submit', mode: 'waterfall', - signature: '\'agent/prompt-submit\'(this: Scoped, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise): Promise', - jsDoc: '/**\n * Allow, rewrite, or block one claimed prompt before it becomes a user\n * message or opens a turn. Call `next()` for the unchanged default. The\n * signal controls only this admission attempt; listeners may cooperate with\n * it but must not retain it for a later attempt or turn.\n * @param agent - the agent whose turn claimed the message.\n * @param message - the frozen claimed message, including identity and source.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', - summary: 'Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn.', + signature: '\'agent/prompt-submit\'(this: Scoped, agent: Agent, messages: UserMessage[], signal: AbortSignal, next: () => Promise): Promise', + jsDoc: '/**\n * Allow, rewrite, or block one claimed inbox batch before it becomes\n * model-visible or opens a turn. Call `next()` for the unchanged default. The\n * signal controls only this admission attempt; listeners may cooperate with\n * it but must not retain it for a later attempt or turn.\n * @param agent - the agent whose driver claimed the batch.\n * @param messages - the claimed messages.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', + summary: 'Allow, rewrite, or block one claimed inbox batch before it becomes model-visible or opens a turn.', }, { name: 'agent/request', @@ -1192,9 +1157,9 @@ export const EVENT_API: readonly EventApiEntry[] = [ { name: 'agent/request-error', mode: 'waterfall', - signature: '\'agent/request-error\'(this: Scoped, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise): Promise', - jsDoc: '/**\n * Handle a model-request failure after its failed step has closed but\n * before the failed turn closes. A listener returns `{ kind: \'retry\' }`\n * without calling `next()` when it owns the error, or calls `next()` to\n * delegate. The default `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param turn - the open turn number.\n * @param step - the failed step number.\n * @param error - the original model-request failure.\n * @param failure - serializable facts normalized at the final adapter boundary.\n * @param priorFailures - immutable failures that already authorized another\n * retry turn in this consecutive sequence.\n * @param retryPolicy - immutable policy of the adapter registration that served\n * the failed request, or `undefined` if no final adapter served it.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', - summary: 'Handle a model-request failure after its failed step has closed but before the failed turn closes.', + signature: '\'agent/request-error\'(this: Scoped, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise): Promise', + jsDoc: '/**\n * Handle one failed model-request attempt before the loop retries or closes\n * its step. A listener returns `{ kind: \'retry\' }` without calling `next()`\n * when it owns recovery, or calls `next()` to delegate. The default\n * `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param context - request coordinates, provider, normalized failure, and serving policy.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */', + summary: 'Handle one failed model-request attempt before the loop retries or closes its step.', }, { name: 'agent/session-start', @@ -1203,18 +1168,11 @@ export const EVENT_API: readonly EventApiEntry[] = [ jsDoc: '/**\n * The session lifecycle began, once before the first turn. Use\n * `agent.inject()` to seed model-facing context. This is a notification, not\n * a veto; disposal requested by a lifecycle owner is rechecked before the\n * driver starts.\n * @param agent - the agent whose session lifecycle began.\n * @param source - why the session started (fresh startup, resume, …).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', summary: 'The session lifecycle began, once before the first turn.', }, - { - name: 'agent/settled', - mode: 'emit', - signature: '\'agent/settled\'(this: Scoped, agent: Agent, turn: number, reason: SettleReason): void', - jsDoc: '/**\n * One drain chain reached its terminal turn: that turn\'s `turn/end` is\n * already committed. Automatically recovered failed turns do not emit this\n * notification, and neither does a run that aborts or fails before its\n * `turn/start` commits — there is no durable turn to settle against.\n * `reason` says why; model-request recovery is exhausted when an error\n * reaches it.\n * @param agent - the agent whose turn closed.\n * @param turn - the terminal turn number.\n * @param reason - why the terminal turn ended, with live error facts when it failed.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', - summary: 'One drain chain reached its terminal turn: that turn\'s `turn/end` is already committed.', - }, { name: 'agent/status', mode: 'emit', signature: '\'agent/status\'(this: Scoped, agent: Agent, status: AgentStatus): void', - jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`). `send()` does not enter\n * `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', + jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`). A waking delivery enters\n * `running` synchronously after reserving cancellation; `idle` means no\n * driver remains scheduled or active.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */', summary: 'Agent status changed (`idle` ⇄ `running`).', }, { @@ -1461,11 +1419,11 @@ export const EVENT_API: readonly EventApiEntry[] = [ export const TYPE_API: readonly TypeApiEntry[] = [ { name: 'Agent', - declaration: 'export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly acceptsNextStep: boolean;\n readonly ctx: Context;\n send(message: UserMessage, options: SendOptions): void;\n updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n}', + declaration: 'export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly inbox: Inbox;\n readonly status: AgentStatus;\n readonly ctx: Context;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n}', }, { name: 'AgentCancelCause', - declaration: 'export type AgentCancelCause = {\n readonly kind: \'user\';\n} | {\n readonly kind: \'parent\';\n};', + declaration: 'export type AgentCancelCause = {\n readonly kind: \'user\';\n} | {\n readonly kind: \'parent\';\n} | {\n readonly kind: \'hook\';\n readonly reason: string;\n} | {\n readonly kind: \'disposed\';\n};', }, { name: 'AgentFactory', @@ -1581,7 +1539,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'CancelOptions', - declaration: 'export interface CancelOptions {\n keepInbox?: boolean;\n}', + declaration: 'export interface CancelOptions {\n keepInbox?: boolean | undefined;\n}', }, { name: 'CodeBindingErrorClass', @@ -1856,16 +1814,12 @@ export const TYPE_API: readonly TypeApiEntry[] = [ declaration: 'export interface GoalView extends GoalSnapshot {\n readonly roundsStarted: number;\n readonly createdAt: number;\n readonly updatedAt: number;\n readonly activation: GoalActivation;\n}', }, { - name: 'InboxAction', - declaration: 'export type InboxAction = {\n readonly kind: \'edit\';\n readonly content: ContentBlock[];\n} | {\n readonly kind: \'remove\';\n};', + name: 'Inbox', + declaration: 'export class Inbox {\n constructor(private readonly session: Session);\n get nextTurn(): readonly UserMessage[];\n get nextStep(): readonly UserMessage[];\n get hasPending(): boolean;\n splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[], outcome?: \'admitted\' | \'canceled\'): UserMessage[];\n}', }, { - name: 'InboxActionResult', - declaration: 'export type InboxActionResult = \'applied\' | \'not-found\';', - }, - { - name: 'InboxItemId', - declaration: 'export type InboxItemId = Branded<\'InboxItemId\'>;', + name: 'InboxTarget', + declaration: 'export type InboxTarget = \'next-turn\' | \'next-step\';', }, { name: 'InvariantFailure', @@ -1969,7 +1923,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'PreparedLlmCall', - declaration: 'export interface PreparedLlmCall {\n readonly config: LlmCallConfig;\n stream(options: GenerateOptions): AsyncIterable;\n}', + declaration: 'export interface PreparedLlmCall {\n readonly config: LlmCallConfig;\n readonly retryPolicy: ResolvedRetryPolicy;\n stream(options: GenerateOptions): AsyncIterable;\n}', }, { name: 'PreparedReferencedMessage', @@ -2155,14 +2109,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ScopeKey', declaration: 'export type ScopeKey = object;', }, - { - name: 'SendOptions', - declaration: 'export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n}', - }, - { - name: 'SendTarget', - declaration: 'export type SendTarget = \'next-turn\' | \'next-step\';', - }, { name: 'Session', declaration: 'export class Session {\n get surface(): SessionSurface;\n readonly header: SessionHeader;\n get id(): SessionId;\n readonly firstLiveSeq: number;\n constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n get events(): readonly SessionEvent[];\n get seq(): number;\n append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n opts: SurfaceIntent\n ] : [\n ]): SessionEvent;\n requestHeader(): EpochHeader | undefined;\n deriveMessages(): Message[];\n deriveEventMessage(event: SessionEvent): Message | null;\n}', @@ -2177,7 +2123,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionEventMap', - declaration: 'export interface SessionEventMap {\n \'turn/start\': {\n turn: number;\n trigger: TurnTrigger;\n };\n \'turn/end\': {\n turn: number;\n reason: TurnEndReason;\n };\n \'step/start\': {\n turn: number;\n step: number;\n };\n \'step/end\': {\n turn: number;\n step: number;\n };\n \'user/message\': UserMessage;\n \'assistant/chunk\': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n \'assistant/message\': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n \'tool/call\': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n \'tool/result\': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n \'steering/message\': {\n turn: number;\n message: UserMessage;\n };\n \'todo/write\': {\n todos: TodoItem[];\n };\n \'request/header\': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n}', + declaration: 'export interface SessionEventMap {\n \'turn/start\': {\n turn: number;\n };\n \'turn/end\': {\n turn: number;\n reason: TurnEndReason;\n };\n \'step/start\': {\n turn: number;\n step: number;\n };\n \'step/end\': {\n turn: number;\n step: number;\n };\n \'user/message\': UserMessage;\n \'assistant/chunk\': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n \'assistant/message\': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n \'tool/call\': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n \'tool/result\': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n \'steering/message\': {\n turn: number;\n message: UserMessage;\n };\n \'todo/write\': {\n todos: TodoItem[];\n };\n \'request/header\': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n}', }, { name: 'SessionEventMetadataFilter', @@ -2713,15 +2659,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'TurnEndReasonMap', - declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n };\n error: {\n kind: \'error\';\n step: number;\n } & ({\n failure: LlmFailure;\n message?: never;\n code?: never;\n } | {\n message: string;\n code?: string;\n failure?: never;\n });\n disposed: {\n kind: \'disposed\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', - }, - { - name: 'TurnTrigger', - declaration: 'export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];', - }, - { - name: 'TurnTriggerMap', - declaration: 'export interface TurnTriggerMap {\n message: {\n kind: \'message\';\n source: MessageSource;\n };\n retry: {\n kind: \'retry\';\n };\n injection: {\n kind: \'injection\';\n source: MessageSource;\n };\n}', + declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n reason: AgentCancelCause;\n };\n error: {\n kind: \'error\';\n error: unknown;\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', }, { name: 'TypertContribution', diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 87796c97b6..e86d1f9636 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -235,7 +235,7 @@ describe('Agent.cancel()', () => { agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) expect(userTexts(agent)).toEqual(['go']) expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) expect(adapter.requests).toHaveLength(1) @@ -272,7 +272,7 @@ describe('Agent.cancel()', () => { dispose() expect(executions).toBe(0) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) const call = agent.session.events.find(event => event.type === 'tool/call') const result = agent.session.events.find(event => event.type === 'tool/result') expect(call?.type === 'tool/call' ? call.data.callId : undefined).toBe('c1') @@ -291,7 +291,7 @@ describe('Agent.cancel()', () => { .find(block => block.type === 'tool-result') expect(replayedResult).toMatchObject({ toolCallId: 'c1', isError: true }) expect(reasons).toEqual([ - { kind: 'aborted' }, + { kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }, ]) }) @@ -342,7 +342,7 @@ describe('Agent.cancel()', () => { // the caller's cause — the marker carries `cancel(cause)` through even // though no AbortController observed it in this window. expect(streamed).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) }) it('cancel from a synchronous step/start session-event listener drops the step (post-step-start window)', async () => { @@ -370,12 +370,12 @@ describe('Agent.cancel()', () => { // No step streamed, the turn ended with the coarse aborted outcome, and the // log is balanced (the open step was closed by the cancel branch). expect(streamed).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) const types = agent.session.events.map(e => e.type) expect(types.filter(t => t === 'step/start').length).toBe(types.filter(t => t === 'step/end').length) }) - it('disposal from a synchronous step/start session-event listener closes the open step as disposed', async () => { + it('disposal from a synchronous step/start session-event listener stops before adapter dispatch', async () => { const adapter = new MockAdapter([textResponse('should not stream')]) const ctx = new Context() await ctx.plugin(LlmService) @@ -405,8 +405,7 @@ describe('Agent.cancel()', () => { expect(streamed).toBe(false) expect(adapter.requests).toHaveLength(0) - const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) + expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(false) const types = agent.session.events.map(e => e.type) expect(types.filter(t => t === 'step/start').length).toBe(types.filter(t => t === 'step/end').length) }) @@ -437,7 +436,7 @@ describe('Agent.cancel()', () => { // Only ONE step ran (the second was cancelled in the stopping window), // and the shared turn signal classified the durable outcome as aborted. expect(steps).toBe(1) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) }) it('cancel from a synchronous agent/status(running) listener drops the turn (window 2)', async () => { @@ -569,10 +568,10 @@ describe('Agent.cancel()', () => { const reasons = agent.session.events .filter(event => event.type === 'turn/end') .map(event => event.type === 'turn/end' ? event.data.reason : undefined) - expect(reasons).toEqual([{ kind: 'aborted' }, { kind: 'completed' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }]) }) - it('keeps the first typed cause for an active turn and detaches the runtime reason', async () => { + it('keeps the first typed cause for an active turn', async () => { const adapter = new MockAdapter(['hang']) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('typed-first-wins'), { provider: 'mock', model: 'mock' }) @@ -581,16 +580,17 @@ describe('Agent.cancel()', () => { send(agent, 'go') await expect.poll(() => adapter.requests.length).toBe(1) agent.cancel(supplied) - supplied.kind = 'user' agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) const runtimeReason: unknown = adapter.requests[0]?.signal?.reason expect(runtimeReason).toEqual({ kind: 'parent' }) - expect(runtimeReason).not.toBe(supplied) - expect(Object.isFrozen(runtimeReason)).toBe(true) + expect(runtimeReason).toBe(supplied) const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ + kind: 'aborted', + reason: { kind: 'parent' }, + }) }) it('preserves the first user cancellation when lifecycle teardown races it', async () => { @@ -608,7 +608,7 @@ describe('Agent.cancel()', () => { await handle.dispose() const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'user' } }) }) it.each([ @@ -688,7 +688,7 @@ describe('Agent.cancel()', () => { if (stage === 'prompt-submit') { expect(turnEnd).toBeUndefined() } else { - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'user' } }) } await ctx.fiber.dispose() }) diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index a87afb578b..70682656d7 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import LlmService, { createUserMessage, freezeMessage, CallId, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm' -import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' +import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason, type UserMessage } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture, type PostToolDecision } from '@deepseek-ai/dsh-tools' import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent' @@ -268,7 +268,7 @@ describe('abort during tool execution ends the turn', () => { [{ type: 'text', text: 'accepted result context during disposal' }], ]) expect(agent.session.events.find(event => event.type === 'turn/end')?.data.reason) - .toEqual({ kind: 'disposed' }) + .toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) }) it('limits injection deferral to the current tool batch', async () => { @@ -390,7 +390,6 @@ describe('steering from late extension points is never stranded', () => { if (event.type === 'turn/start') turns.push(event.data.turn) if (event.type === 'turn/end' && !steeredOnce) { steeredOnce = true - expect(agent.acceptsNextStep).toBe(false) agent.steer(createUserMessage({ content: [{ type: 'text', text: 'too late for this turn' }], source: { kind: 'user' } })) } }) @@ -461,7 +460,7 @@ describe('disposal leaves the two-state status contract balanced', () => { await driverDone(agent) expect(statuses).toEqual(['running', 'idle']) - expect(reasons).toEqual([{ kind: 'disposed' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'disposed' } }]) expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) const messages = agent.session.events .filter(event => event.type === 'user/message') @@ -956,7 +955,7 @@ describe('turn and step boundary recovery', () => { const turnEnds = e.filter(x => x.type === 'turn/end').length expect(turnStarts).toBe(1) expect(turnEnds).toBe(1) // balanced — the turn was closed despite disposal - expect(reasons).toEqual([{ kind: 'disposed' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'disposed' } }]) // no error reason: disposal is not a failure. expect(e.some(x => x.type === 'turn/end' && x.data.reason.kind === 'error')).toBe(false) }) @@ -989,7 +988,7 @@ describe('turn and step boundary recovery', () => { // Balanced: one turn/start, one turn/end carrying disposed (NOT error). expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) expect(e.some(x => x.type === 'turn/end' && x.data.reason.kind === 'error')).toBe(false) // No step opened (the throw was before step/start) and disposal is not a // failure, so no agent/error for the contained throw. @@ -1225,7 +1224,7 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) expect(e.some(x => x.type === 'step/start')).toBe(false) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) }) @@ -1272,12 +1271,12 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'user' } }) expect(e.some(x => x.type === 'step/start')).toBe(false) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) expect(e.some(x => x.type === 'assistant/message')).toBe(false) expect(adapter.requests).toHaveLength(0) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) }) it('disposal during agent/step listeners ends the turn disposed', { timeout: 15000 }, async () => { @@ -1324,7 +1323,7 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') // Disposal wins the post-listener check — reason is `disposed`. - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) expect(e.some(x => x.type === 'step/start')).toBe(false) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) // The durable turn/end record is the authoritative turn-boundary signal @@ -1372,10 +1371,10 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'user' } }) expect(e.some(x => x.type === 'step/start')).toBe(false) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) }) it('disposal during assembly does not leak an LLM call or append assistant/chunk', { timeout: 15000 }, async () => { diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts index 5a2ef01b7e..1ee67e70b8 100644 --- a/packages/core/agent-loop/tests/coverage-edges.spec.ts +++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts @@ -165,8 +165,8 @@ describe('thrown-value propagation', () => { expect(errors[0]).toEqual({ code: 500 }) const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' - && ('failure' in turnEnd.data.reason ? turnEnd.data.reason.failure.code : turnEnd.data.reason.code)) - .toBeUndefined() + ? turnEnd.data.reason.error + : undefined).toEqual({ code: 500 }) }) }) @@ -197,8 +197,7 @@ describe('coded error data emission', () => { const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd).toBeDefined() if (turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error') { - expect('failure' in turnEnd.data.reason ? turnEnd.data.reason.failure.code : turnEnd.data.reason.code) - .toBe('RATE_LIMIT') + expect(turnEnd.data.reason.error).toMatchObject({ code: 'RATE_LIMIT' }) } }) }) @@ -221,7 +220,7 @@ describe('disposed vs aborted branching', () => { await driverDone(agent) // Disposal wins abort classification because the error path checks it first. - expect(reasons).toContainEqual({ kind: 'disposed' }) + expect(reasons).toContainEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) }) }) @@ -285,9 +284,7 @@ describe('request-error action edges', () => { ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('retry-raced'), { provider: 'mock', model: 'mock' }) - ctx.on('agent/request-error', async ( - subject, _turn, _step, _error, _failure, _priorFailures, _retryPolicy, signal, next, - ) => { + ctx.on('agent/request-error', async (subject, _context, signal, next) => { await next() subject.cancel({ kind: 'user' }) expect(signal.aborted).toBe(true) @@ -480,7 +477,7 @@ describe('unrenderable failure settlement', () => { if (end?.type === 'turn/end' && end.data.reason.kind === 'error') { // The durable failure keeps the adapter facts' message, not the // unrenderable chain. - expect(end.data.reason.failure?.message).not.toBe('') + expect(errorChain(end.data.reason.error)).not.toBe('') } }) }) @@ -493,10 +490,11 @@ describe('driver bookkeeping edges', () => { provider: 'mock', model: 'mock', }) - ctx.on('agent/inbox/enqueue', (subject) => { - if (subject !== agent) return - subject.cancel({ kind: 'user' }) - const mutable = subject as Agent & { done: Promise } + ctx.on('session/event', (session, event) => { + if (session !== agent.session || event.type !== 'agent/inbox/spliced' + || event.data.target !== 'next-turn' || event.data.inserted.length === 0) return + agent.cancel({ kind: 'user' }) + const mutable = agent as Agent & { done: Promise } mutable.done = Promise.reject(new Error('replacement rejected')) }) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index faa23a2657..832181adb5 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -11,7 +11,6 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools' import AgentRegistry, { type Agent, - type InboxPlacement, type PromptDecision, type SessionStartSource, } from '@deepseek-ai/dsh-agent' @@ -66,8 +65,8 @@ describe('agent/prompt-submit', () => { const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) const seen: string[] = [] - ctx.on('agent/prompt-submit', async (_agent, message, _signal, next) => { - seen.push(message.content.map(b => (b.type === 'text' ? b.text : '')).join('')) + ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next) => { + seen.push(messages[0]!.content.map(b => (b.type === 'text' ? b.text : '')).join('')) return next() }) @@ -86,9 +85,9 @@ describe('agent/prompt-submit', () => { const entered = Promise.withResolvers() const decision = Promise.withResolvers() const observed: UserMessage[] = [] - ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject !== agent) return - const message = item.message + ctx.on('agent/prompt-submit', async (subject, messages) => { + if (subject !== agent) return { kind: 'allow', messages } + const message = messages[0]! expect(Object.isFrozen(message)).toBe(true) expect(Object.isFrozen(message.content)).toBe(true) expect(Object.isFrozen(message.content[0])).toBe(true) @@ -97,11 +96,7 @@ describe('agent/prompt-submit', () => { const block = message.content[0] if (block?.type === 'text') block.text = 'listener mutation' }).toThrow() - }) - ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject === agent) observed.push(item.message) - }) - ctx.on('agent/prompt-submit', async () => { + observed.push(message) entered.resolve(undefined) return decision.promise }) @@ -120,7 +115,7 @@ describe('agent/prompt-submit', () => { expect(() => { if (input.source.kind === 'plugin') input.source.plugin = 'caller mutation' }).toThrow(TypeError) - decision.resolve({ kind: 'allow' }) + decision.resolve({ kind: 'allow', messages: [input] }) await idle expect(observed).toHaveLength(1) @@ -138,8 +133,11 @@ describe('agent/prompt-submit', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - ctx.on('agent/prompt-submit', async (): Promise => - ({ kind: 'allow', content: [{ type: 'text', text: 'REWRITTEN' }] })) + ctx.on('agent/prompt-submit', async (_agent, messages): Promise => + ({ + kind: 'allow', + messages: [{ ...messages[0]!, content: [{ type: 'text', text: 'REWRITTEN' }] }], + })) send(agent, 'original') await waitForIdle(ctx, agent) @@ -156,10 +154,10 @@ describe('agent/prompt-submit', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - ctx.on('agent/prompt-submit', async (): Promise => + ctx.on('agent/prompt-submit', async (_agent, messages): Promise => ({ kind: 'allow', - additionalContexts: [createUserMessage({ + messages: [...messages, createUserMessage({ content: [{ type: 'text', text: 'extra ctx' }], source: { kind: 'plugin', plugin: 'test' }, })], @@ -183,11 +181,13 @@ describe('agent/prompt-submit', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - ctx.on('agent/prompt-submit', async (): Promise => + ctx.on('agent/prompt-submit', async (_agent, messages): Promise => ({ kind: 'allow', - content: [{ type: 'text', text: 'REWRITTEN prompt' }], - additionalContexts: [createUserMessage({ + messages: [{ + ...messages[0]!, + content: [{ type: 'text', text: 'REWRITTEN prompt' }], + }, createUserMessage({ content: [{ type: 'text', text: 'injected ctx' }], source: { kind: 'plugin', plugin: 'test' }, })], })) @@ -236,20 +236,17 @@ describe('agent/prompt-submit', () => { const agent = ctx.agentLoop.create(SessionId('admission-outbox'), { provider: 'mock', model: 'mock' }) const entered = Promise.withResolvers() const decision = Promise.withResolvers() - const placements: InboxPlacement[] = [] - ctx.on('agent/prompt-submit', async () => { + let claimed: UserMessage[] = [] + ctx.on('agent/prompt-submit', async (_agent, messages) => { + claimed = messages entered.resolve(undefined) return decision.promise }) - ctx.on('agent/inbox/enqueue', (subject, item) => { - if (subject === agent) placements.push(item.placement) - }) const idle = waitForIdle(ctx, agent) send(agent, 'admitted prompt') await entered.promise expect(agent.status).toBe('running') - expect(agent.acceptsNextStep).toBe(true) expect(events(agent).some(event => event.type === 'turn/start')).toBe(false) agent.inject(createUserMessage({ @@ -258,11 +255,15 @@ describe('agent/prompt-submit', () => { })) agent.steer(createUserMessage({ content: [{ type: 'text', text: 'admission steering' }], source: { kind: 'user' } })) expect(events(agent).some(event => event.type === 'user/message')).toBe(false) - expect(placements).toEqual(['queued', 'steering']) + expect(agent.inbox.nextStep.map(message => message.content[0])) + .toEqual([ + { type: 'text', text: 'attached context' }, + { type: 'text', text: 'admission steering' }, + ]) - decision.resolve({ kind: 'allow' }) + decision.resolve({ kind: 'allow', messages: claimed }) await idle - expect(agent.acceptsNextStep).toBe(false) + expect(agent.inbox.hasPending).toBe(false) const staged = events(agent).filter(event => event.type === 'turn/start' || event.type === 'user/message' || event.type === 'steering/message') @@ -298,7 +299,6 @@ describe('agent/prompt-submit', () => { const blockedIdle = waitForIdle(ctx, agent) send(agent, 'blocked prompt') await entered.promise - expect(agent.acceptsNextStep).toBe(true) agent.inject(createUserMessage({ content: [{ type: 'text', text: 'staged context' }], source: { kind: 'plugin', plugin: 'test' }, @@ -307,7 +307,7 @@ describe('agent/prompt-submit', () => { decision.resolve({ kind: 'block', reason: 'policy' }) await blockedIdle - expect(agent.acceptsNextStep).toBe(false) + expect(agent.inbox.nextStep).toHaveLength(2) expect(events(agent)).toEqual([]) expect(adapter.requests).toEqual([]) @@ -334,14 +334,16 @@ describe('agent/prompt-submit', () => { provider: 'mock', model: 'mock', }) - ctx.on('agent/prompt-submit', async (_agent, message, _signal, next) => { + ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next) => { const decision = await next() - return message.content.some(block => block.type === 'text' && block.text === 'blocked prompt') + return messages.some(message => + message.content.some(block => block.type === 'text' && block.text === 'blocked prompt')) ? { kind: 'block', reason: 'policy' } : decision }) - ctx.on('agent/prompt-submit', async (subject, message, _signal, next) => { - if (message.content.some(block => block.type === 'text' && block.text === 'blocked prompt')) { + ctx.on('agent/prompt-submit', async (subject, messages, _signal, next) => { + if (messages.some(message => + message.content.some(block => block.type === 'text' && block.text === 'blocked prompt'))) { subject.inject(createUserMessage({ content: [{ type: 'text', text: 'earlier state change' }], source: { kind: 'plugin', plugin: 'test' }, @@ -446,8 +448,9 @@ describe('agent/prompt-submit', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - ctx.on('agent/prompt-submit', async (_agent, message, _signal, next): Promise => { - const text = message.content.map(b => (b.type === 'text' ? b.text : '')).join('') + ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next): Promise => { + const text = messages.flatMap(message => message.content) + .map(b => (b.type === 'text' ? b.text : '')).join('') return text === 'secret' ? { kind: 'block', reason: 'policy: no secrets' } : next() }) @@ -475,9 +478,9 @@ describe('agent/prompt-submit', () => { const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) let threw = false - ctx.on('agent/prompt-submit', async () => { + ctx.on('agent/prompt-submit', async (_agent, messages) => { if (!threw) { threw = true; throw new Error('prompt hook broke') } - return { kind: 'allow' as const } + return { kind: 'allow' as const, messages } }) const errors: Error[] = [] const reasons: TurnEndReason[] = [] @@ -680,8 +683,9 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se agent.inject(createUserMessage({ content: [{ type: 'text', text: `policy active (started: ${source})` }], source: { kind: 'plugin', plugin: 'native-guard' } })) }) // 2. PromptSubmit: block a forbidden prompt, annotate the rest. - ctx.on('agent/prompt-submit', async (_agent, message, _signal, next): Promise => { - const text = message.content.map(b => (b.type === 'text' ? b.text : '')).join('') + ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next): Promise => { + const text = messages.flatMap(message => message.content) + .map(b => (b.type === 'text' ? b.text : '')).join('') if (text.includes('rm -rf')) return { kind: 'block', reason: 'destructive prompt blocked' } return next() }) diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index bf71b5f591..7629c69276 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -94,11 +94,10 @@ describe('agent loop', () => { expect(order).toEqual(['turn/start', 'step/start', 'step/end', 'turn/end']) const types = agent.session.events.map(e => e.type) - // turn/start opens the turn, THEN the queued user message is recorded inside - // it (every event is turn-enclosed), then the assembled message (carrying the - // step's usage). - expect(types[0]).toBe('turn/start') - expect(types[1]).toBe('user/message') + // Durable inbox receipt and admission bracket the turn-owned transcript. + expect(types[0]).toBe('agent/inbox/spliced') + expect(types).toContain('turn/start') + expect(types).toContain('user/message') expect(types).toContain('assistant/message') const assistantMessage = agent.session.events.find(e => e.type === 'assistant/message') expect(assistantMessage?.type === 'assistant/message' && assistantMessage.data.usage).toEqual({ inputTokens: 10, outputTokens: 'hello there'.length }) @@ -201,9 +200,12 @@ describe('agent loop', () => { await waitForIdle(ctx, agent) expect(adapter.requests).toHaveLength(0) // the request was never sent - expect(errors.some(e => e.message.includes('no value for this assembly'))).toBe(true) + expect(errors).toEqual([]) const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('error') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' + ? turnEnd.data.reason.error + : '').toContain('no value for this assembly') // The loop survived: a waterfall listener rescues {{cwd}} and the SAME // agent completes a real model turn. @@ -307,9 +309,11 @@ describe('agent loop', () => { await waitForIdle(ctx, agent) const types = agent.session.events.map(e => e.type) - expect(types).toContain('steering/message') - // steering recorded before the second step's request derived its history - const steeringSeq = agent.session.events.find(e => e.type === 'steering/message')!.seq + const steering = agent.session.events.find(e => + e.type === 'user/message' && JSON.stringify(e.data.content).includes('change of plans')) + expect(steering).toBeDefined() + // Steering is admitted before the second step's request derives history. + const steeringSeq = steering!.seq const secondStepStart = agent.session.events.filter(e => e.type === 'step/start')[1] expect(secondStepStart).toBeDefined() expect(steeringSeq).toBeLessThan(secondStepStart!.seq) @@ -320,8 +324,8 @@ describe('agent loop', () => { expect(flat).toContain('change of plans') }) - it('same-tick idle steering preserves one turn per send', async () => { - const adapter = new MockAdapter([textResponse('first'), textResponse('second')]) + it('coalesces same-tick idle steering into one turn', async () => { + const adapter = new MockAdapter([textResponse('first')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -330,7 +334,7 @@ describe('agent loop', () => { agent.steer(createUserMessage({ content: [{ type: 'text', text: 'second idle steer' }], source: { kind: 'user' } })) await idle - expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2) + expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) expect(agent.session.events .filter(event => event.type === 'user/message') .map(event => event.data.content)).toEqual([ @@ -338,13 +342,12 @@ describe('agent loop', () => { [{ type: 'text', text: 'second idle steer' }], ]) expect(agent.session.events.filter(event => event.type === 'steering/message')).toEqual([]) - expect(adapter.requests).toHaveLength(2) + expect(adapter.requests).toHaveLength(1) expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('first idle steer') - expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('second idle steer') - expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('second idle steer') + expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('second idle steer') }) - it('keeps steering staged after a failed step until the next admitted turn', async () => { + it('contains a throwing step observer and carries steering into a replacement turn', async () => { const adapter = new MockAdapter([textResponse('recovered')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('failed-steering'), { provider: 'mock', model: 'mock' }) @@ -359,20 +362,13 @@ describe('agent loop', () => { send(agent, 'prompt') await waitForIdle(ctx, agent) - expect(adapter.requests).toHaveLength(0) - expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) - expect(agent.session.events.some(event => event.type === 'steering/message')).toBe(false) - - send(agent, 'resume') - await waitForIdle(ctx, agent) - expect(adapter.requests).toHaveLength(1) expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2) - expect(agent.session.events.some(event => event.type === 'steering/message')).toBe(true) + expect(agent.session.events.some(event => event.type === 'steering/message')).toBe(false) expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('pending steering') }) - it('inject() while idle appends context without opening a turn', async () => { + it('inject() while idle durably stages context without opening a turn', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -382,11 +378,14 @@ describe('agent loop', () => { expect(adapter.requests).toHaveLength(0) expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(0) expect(agent.session.events.at(-1)).toMatchObject({ - type: 'user/message', + type: 'agent/inbox/spliced', data: { - role: 'user', - content: [{ type: 'text', text: 'file changed: a.ts' }], - source: { kind: 'plugin', plugin: 'watcher' }, + target: 'next-step', + inserted: [{ + role: 'user', + content: [{ type: 'text', text: 'file changed: a.ts' }], + source: { kind: 'plugin', plugin: 'watcher' }, + }], }, }) @@ -540,7 +539,7 @@ describe('agent loop', () => { expect(agent.session.events.some(e => e.type === 'tool/result')).toBe(true) }) - it('a concluding tool result beats steering that arrived during the same step', async () => { + it('continues for steering that arrived during a concluding tool step', async () => { const adapter = new MockAdapter([ toolCallResponse('c1', 'finalize', {}), textResponse('next turn reply'), @@ -562,17 +561,10 @@ describe('agent loop', () => { send(agent, 'go') await waitForIdle(ctx, agent) - // The terminal result stands: no extra request reopens the concluded turn. - expect(adapter.requests).toHaveLength(1) + expect(adapter.requests).toHaveLength(2) const events = agent.session.events.map(event => event.type) expect(events.filter(type => type === 'turn/end')).toHaveLength(1) - // The steering is durable inside the concluded turn and feeds the NEXT - // turn's request instead of being dropped or re-queued. - expect(events).toContain('steering/message') - - send(agent, 'follow up') - await waitForIdle(ctx, agent) - expect(adapter.requests).toHaveLength(2) + expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('late steering') const texts = adapter.requests[1]!.messages .flatMap(message => message.content) .filter(block => block.type === 'text') @@ -630,38 +622,21 @@ describe('agent loop', () => { expect(fires.every(({ signal }) => signal instanceof AbortSignal)).toBe(true) }) - it('agent/step fires BEFORE the step it precedes opens (events land outside the step)', async () => { - // The append lands before step/start, yet derive happens afterwards and the - // same step's request must include it. + it('agent/step fires after its step boundary opens and before the request', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - let injected = false + let boundaryOpen = false ctx.on('agent/step', (subject) => { - if (subject === agent && !injected) { - injected = true - subject.session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'INJECTED-IN-PRE-STEP' }], - source: { kind: 'plugin', plugin: 'test' }, - }), { surfaceOp: 'append' }) - } + if (subject === agent) boundaryOpen = subject.session.events.at(-1)?.type === 'step/start' }) send(agent, 'go') await waitForIdle(ctx, agent) - // The adapter's request includes the node injected during pre-step (derive - // reflects it). - const text = JSON.stringify(adapter.requests[0]!.messages) - expect(text).toContain('INJECTED-IN-PRE-STEP') - - // And the injected event sits BEFORE the first step/start in the log — - // the seam fired outside the step. - const events = agent.session.events - const injectedSeq = events.find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')!.seq - const firstStepStartSeq = events.find(e => e.type === 'step/start')!.seq - expect(injectedSeq).toBeLessThan(firstStepStartSeq) + expect(boundaryOpen).toBe(true) + expect(adapter.requests).toHaveLength(1) }) it('a throwing agent/step listener ends the turn (error), not the loop', async () => { @@ -683,13 +658,11 @@ describe('agent loop', () => { send(agent, 'first') await waitForIdle(ctx, agent) - // The first turn failed at step 1 (no model call happened), surfaced via - // agent/error, with the durable failure on turn/end.reason. - expect(errors).toHaveLength(1) - expect(errors[0]!.message).toContain('boom in pre-step') + // The first turn failed at step 1 before a model call. + expect(errors).toEqual([]) expect(adapter.requests.length).toBe(0) const firstTurnEnd = agent.session.events.find(e => e.type === 'turn/end') - expect(firstTurnEnd?.type === 'turn/end' && firstTurnEnd.data.reason).toMatchObject({ kind: 'error', step: 1 }) + expect(firstTurnEnd?.type === 'turn/end' && firstTurnEnd.data.reason).toMatchObject({ kind: 'error' }) // The step opened-and-closed count stays balanced even though it never ran. const types = agent.session.events.map(e => e.type) expect(types.filter(t => t === 'step/start').length).toBe(types.filter(t => t === 'step/end').length) @@ -717,7 +690,7 @@ describe('agent loop', () => { agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'aborted' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) }) it('surfaces max-tokens as the turn-end reason when the last step is cut off', async () => { @@ -788,7 +761,7 @@ describe('agent loop', () => { source: { kind: 'plugin', plugin: 'max-tokens-test' }, }, ]) - expect(reasons).toEqual([{ kind: 'max-tokens' }]) + expect(reasons).toEqual([{ kind: 'completed' }]) }) it('a completed step after no max-tokens keeps the turn completed (max-tokens does not leak across turns)', async () => { @@ -1005,14 +978,15 @@ describe('agent loop', () => { expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('completed') }) - it('keeps a reentrant agent/inbox/enqueue send as the next independent turn', async () => { - const adapter = new MockAdapter([textResponse('first'), textResponse('second')]) + it('contains a reentrant send attempted during durable inbox publication', async () => { + const adapter = new MockAdapter([textResponse('first')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) let nested = false - ctx.on('agent/inbox/enqueue', (subject) => { - if (subject !== agent || nested) return + ctx.on('session/event', (session, event) => { + if (session !== agent.session || event.type !== 'agent/inbox/spliced' + || event.data.inserted.length === 0 || nested) return nested = true send(agent, 'queued listener message') }) @@ -1025,11 +999,8 @@ describe('agent loop', () => { const messages = agent.session.events .filter(event => event.type === 'user/message') .map(event => event.data.content) - expect(turns).toHaveLength(2) - expect(messages).toEqual([ - [{ type: 'text', text: 'outer message' }], - [{ type: 'text', text: 'queued listener message' }], - ]) + expect(turns).toHaveLength(1) + expect(messages).toEqual([[{ type: 'text', text: 'outer message' }]]) }) it('preserves independent turn sources across an adjacent microtask send', async () => { @@ -1068,7 +1039,7 @@ describe('agent loop', () => { ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk' && !queued) { queued = true - send(agent, 'second message') + queueMicrotask(() => { send(agent, 'second message') }) } }) @@ -1110,7 +1081,7 @@ describe('agent loop', () => { ]) }) - it('errors from the model surface as agent/error and end the turn', async () => { + it('records normalized model errors on the turn boundary', async () => { const adapter = new MockAdapter([]) // script exhausted → throws const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -1125,13 +1096,12 @@ describe('agent loop', () => { send(agent, 'hi') await waitForIdle(ctx, agent) - expect(errors).toHaveLength(1) - expect(errors[0]!.message).toContain('script exhausted') + expect(errors).toEqual([]) expect(reasons[0]).toMatchObject({ kind: 'error' }) // The durable failure lives entirely on turn/end.reason (with the failing // step), not a standalone error event. const turnEnd = agent.session.events.find(e => e.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toMatchObject({ kind: 'error', step: 1 }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toMatchObject({ kind: 'error' }) }) it('disposing the loop fiber mid-turn stops the loop (HMR safety)', async () => { diff --git a/packages/core/agent-loop/tests/request-error.spec.ts b/packages/core/agent-loop/tests/request-error.spec.ts index afd62f7d20..a7b35bfdbf 100644 --- a/packages/core/agent-loop/tests/request-error.spec.ts +++ b/packages/core/agent-loop/tests/request-error.spec.ts @@ -59,22 +59,19 @@ describe('agent/request-error', () => { turn: number step: number failure: LlmFailure - priorFailures: readonly LlmFailure[] retryPolicy: ResolvedRetryPolicy | undefined }[] = [] const statuses: string[] = [] ctx.on('agent/status', (subject, status) => { if (subject === agent) statuses.push(status) }) - ctx.on('agent/request-error', async ( - subject, turn, step, _error, failure, priorFailures, retryPolicy, - ) => { + ctx.on('agent/request-error', async (subject, context) => { expect(subject).toBe(agent) expect(agent.session.events.at(-1)).toMatchObject({ type: 'step/end', - data: { turn, step }, + data: { turn: context.turn, step: context.step }, }) - seen.push({ turn, step, failure, priorFailures, retryPolicy }) + seen.push(context) return { kind: 'retry' } }) @@ -98,8 +95,6 @@ describe('agent/request-error', () => { }, ]) expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) - expect(seen.map(item => item.priorFailures.map(failure => failure.code))) - .toEqual([[], ['RATE_LIMIT']]) expect(seen.map(item => item.retryPolicy)).toEqual([ expect.objectContaining({ mode: 'normal' }), expect.objectContaining({ mode: 'normal' }), @@ -123,7 +118,7 @@ describe('agent/request-error', () => { expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) expect(agent.session.events.find(event => event.type === 'turn/end')).toMatchObject({ type: 'turn/end', - data: { reason: { kind: 'aborted' } }, + data: { reason: { kind: 'aborted', reason: { kind: 'user' } } }, }) }) diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts index b2178aea7e..8ffc467e20 100644 --- a/packages/core/agent/tests/agent.spec.ts +++ b/packages/core/agent/tests/agent.spec.ts @@ -3,6 +3,7 @@ import { Context, Service, symbols } from 'cordis' import { Session, SessionId } from '@deepseek-ai/dsh-session' import AgentRegistry, { agentEvents, + Inbox, } from '@deepseek-ai/dsh-agent' import type { @@ -15,16 +16,19 @@ import type { function stubAgent(rawId: string, overrides: Partial = {}): Agent { const id = SessionId(rawId) + const session = new Session(id) const agent: Agent = { id, options: {}, - session: new Session(id), + session, + inbox: new Inbox(session), status: 'idle', ctx: new Context(), followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, + whenIdle: () => Promise.resolve(), } return Object.assign(agent, overrides) } diff --git a/packages/core/scope/src/scoped-events.generated.ts b/packages/core/scope/src/scoped-events.generated.ts index e08fd2aabd..836294c93d 100644 --- a/packages/core/scope/src/scoped-events.generated.ts +++ b/packages/core/scope/src/scoped-events.generated.ts @@ -15,7 +15,6 @@ const scopedSubjectResolvers: Readonly args[0], 'agent/request-error': args => args[0], 'agent/session-start': args => args[0], - 'agent/settled': args => args[0], 'agent/status': args => args[0], 'agent/step': args => args[0], 'agent/turn-stopping': args => args[0], diff --git a/packages/core/scope/tests/invariant.spec.ts b/packages/core/scope/tests/invariant.spec.ts index ccc90e7843..35f3455a85 100644 --- a/packages/core/scope/tests/invariant.spec.ts +++ b/packages/core/scope/tests/invariant.spec.ts @@ -59,6 +59,7 @@ describe('scoped-dispatch invariants', () => { step: 1, provider: 'p', failure: { message: 'request', code: 'UNKNOWN' }, + retryPolicy: undefined, }, signal, () => Promise.resolve(undefined), diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index bf1601c43a..fba29e3585 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -169,7 +169,6 @@ function assertSessionEventEnvelope(value: Record, index: numbe throw new Error(`seed event at index ${index} has an invalid event envelope`) } assertCurrentLlmShape(event, index) - assertCurrentTurnEndShape(event, index) } /** Reject obsolete request headers and malformed messages at the seed/load boundary. */ @@ -248,22 +247,6 @@ function assertMessageEventShape(event: Record, subject: string } } -/** Reject legacy aborted outcomes that persisted caller-owned reason detail. */ -function assertCurrentTurnEndShape(event: Record, index: number): void { - if (event['type'] !== 'turn/end') return - const data = event['data'] - /* v8 ignore next -- this migration recognizes only the legacy object shape; format-wide payload validation is separate. */ - if (typeof data !== 'object' || data === null) return - const reason = (data as Record)['reason'] - /* v8 ignore next -- non-object reasons cannot carry the legacy aborted detail this migration removes. */ - if (typeof reason !== 'object' || reason === null || Array.isArray(reason)) return - const record = reason as Record - if (record['kind'] === 'aborted' - && (Object.keys(record).length !== 1 || !Object.hasOwn(record, 'kind'))) { - throw new Error(`seed turn/end at index ${index} uses unsupported reason-bearing aborted format`) - } -} - /** Whether an unknown value carries the current provider/model pair. */ function hasProviderModel(value: unknown): boolean { if (typeof value !== 'object' || value === null) return false diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts index dc22ec6512..3c79b05157 100644 --- a/packages/core/session/tests/fork.spec.ts +++ b/packages/core/session/tests/fork.spec.ts @@ -128,9 +128,9 @@ describe('SessionStore.fork', () => { const { ctx, sessions } = await setup() const reasons: TurnEndReason[] = [ { kind: 'completed' }, - { kind: 'aborted' }, - { kind: 'error', step: 1, message: 'model failed', code: 'MODEL' }, - { kind: 'disposed' }, + { kind: 'aborted', reason: { kind: 'user' } }, + { kind: 'error', error: new Error('model failed') }, + { kind: 'aborted', reason: { kind: 'disposed' } }, { kind: 'max-tokens' }, { kind: 'interrupted' }, ] diff --git a/packages/core/session/tests/invariant.spec.ts b/packages/core/session/tests/invariant.spec.ts index d4b71e0da2..0037646a12 100644 --- a/packages/core/session/tests/invariant.spec.ts +++ b/packages/core/session/tests/invariant.spec.ts @@ -326,7 +326,7 @@ describe('session-log invariants', () => { unresolved.append('step/start', { turn: 1, step: 1 }) unresolved.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' }) unresolved.append('step/end', { turn: 1, step: 1 }) - unresolved.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } }) + unresolved.append('turn/end', { turn: 1, reason: { kind: 'error', error: new Error('boom') } }) }).not.toThrow() }) diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts index ab4c84b1e7..c8c0ed3a59 100644 --- a/packages/core/session/tests/session.spec.ts +++ b/packages/core/session/tests/session.spec.ts @@ -70,30 +70,15 @@ describe('Session', () => { expect(structuredClone(turnEnd.data.reason)).toEqual({ kind: 'max-tokens' }) }) - it('round-trips the coarse aborted turn outcome', () => { + it('round-trips an aborted turn with its cancellation cause', () => { const session = new Session(SessionId('aborted')) session.append('turn/start', { turn: 1 }) - session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) + session.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: { kind: 'user' } } }) const replayed = new Session(SessionId('aborted-replay'), structuredClone(session.events)) expect(replayed.events).toEqual(session.events) const turnEnd = replayed.events.findLast(event => event.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) - }) - - it('rejects legacy reason-bearing aborted outcomes at the seed/load boundary', () => { - const legacy = [ - { - type: 'turn/start', seq: 0, time: 1, - data: { turn: 1 }, - }, - { - type: 'turn/end', seq: 1, time: 2, - data: { turn: 1, reason: { kind: 'aborted', reason: 'legacy cancellation detail' } }, - }, - ] as unknown as SessionEvent[] - - expect(() => new Session(SessionId('legacy-aborted'), legacy)) - .toThrow('seed turn/end at index 1 uses unsupported reason-bearing aborted format') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason) + .toEqual({ kind: 'aborted', reason: { kind: 'user' } }) }) it('renders injected-context and steering messages as plain user content', () => { diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts index 1414a0691a..3a7c29fadb 100644 --- a/packages/examples/cli-demo/tests/cli.spec.ts +++ b/packages/examples/cli-demo/tests/cli.spec.ts @@ -12,12 +12,11 @@ import { createUserMessage, type StreamChunk, type TokenUsage, } from '@deepseek-ai/dsh-llm' -import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' +import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' import { afterEach, describe, expect, it } from 'vitest' import * as cliDemo from '../src/index.ts' import { executeCli, - formatTurnFailure, parseCliArgs, runOneShot, type CliResult, @@ -345,7 +344,7 @@ describe('runOneShot and executeCli', () => { const output = await invoke(ctx, ['--output-format', 'json', 'task']) const result = JSON.parse(output.stdout) as CliResult expect(output.code).toBe(0) - expect(result).toMatchObject({ type: 'result', success: true, turn: 1, result: 'done', reason: { kind: 'completed' } }) + expect(result).toMatchObject({ type: 'result', output: 'done' }) expect(result.usage).toEqual({ inputTokens: 17, outputTokens: 8, @@ -376,7 +375,7 @@ describe('runOneShot and executeCli', () => { reasoningResponse('reasoning only'), ]) const result = await runOneShot(ctx, { task: 'task' }) - expect(result.result).toBe('working') + expect(result.output).toBe('working') }) it('observes only the correlated main message turn', async () => { @@ -421,8 +420,7 @@ describe('runOneShot and executeCli', () => { releaseStartup.resolve(undefined) const outcome = await result - expect(outcome.reason).toEqual({ kind: 'completed' }) - expect(outcome).toMatchObject({ success: true, turn: 3, result: 'streamed' }) + expect(outcome).toMatchObject({ type: 'result', output: 'streamed' }) const events = streamed.map(item => item.event) expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 3 } }) expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 3 } }) @@ -443,15 +441,15 @@ describe('runOneShot and executeCli', () => { })) await expect(runOneShot(ctx, { task: 'original task' })).resolves.toMatchObject({ - success: true, - result: 'rewritten answer', + type: 'result', + output: 'rewritten answer', }) }) - it('rejects tasks blocked before admission, including retained tasks', async () => { + it('settles blocked tasks at whole-agent idle without attributing a result', async () => { const blocked = await harness([]) blocked.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'denied' })) - await expect(runOneShot(blocked.ctx, { task: 'task' })).rejects.toThrow('canceled before admission') + await expect(runOneShot(blocked.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' }) const retained = await harness([]) retained.ctx.on('agent/prompt-submit', async () => ({ @@ -459,7 +457,7 @@ describe('runOneShot and executeCli', () => { reason: 'deferred', keepInbox: true, })) - await expect(runOneShot(retained.ctx, { task: 'task' })).rejects.toThrow('not admitted') + await expect(runOneShot(retained.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' }) expect(retained.agent.status).toBe('idle') const failed = await harness([]) @@ -467,12 +465,12 @@ describe('runOneShot and executeCli', () => { await expect(runOneShot(failed.ctx, { task: 'task' })).rejects.toThrow('not admitted') }) - it('emits partial data and a diagnostic for non-completed turns', async () => { + it('emits partial data without attributing a turn outcome', async () => { const { ctx } = await harness([textResponse('partial', { inputTokens: 2, outputTokens: 3 }, 'max-tokens')]) const output = await invoke(ctx, ['--output-format', 'json', 'task']) - expect(JSON.parse(output.stdout)).toMatchObject({ success: false, result: 'partial', reason: { kind: 'max-tokens' } }) - expect(output.code).toBe(1) - expect(output.stderr).toContain('output-token limit') + expect(JSON.parse(output.stdout)).toMatchObject({ type: 'result', output: 'partial' }) + expect(output.code).toBe(0) + expect(output.stderr).toBe('') }) it('cancels an active turn, emits its durable aborted result, and disposes', async () => { @@ -487,9 +485,9 @@ describe('runOneShot and executeCli', () => { await running abort.abort('received SIGINT') const output = await outcome - expect(JSON.parse(output.stdout)).toMatchObject({ success: false, reason: { kind: 'aborted' } }) + expect(output.stdout).toBe('') expect(output.code).toBe(1) - expect(output.stderr).toContain('turn 1 was aborted') + expect(output.stderr).toContain('received SIGINT') expect(agent.status).toBe('idle') }) @@ -572,18 +570,3 @@ describe('runOneShot and executeCli', () => { await queued.agent.whenIdle() }) }) - -describe('formatTurnFailure', () => { - it('diagnoses every durable reason and preserves merge-extensible unknowns', () => { - const cases: [TurnEndReason, string][] = [ - [{ kind: 'completed' }, 'completed'], - [{ kind: 'aborted', reason: { kind: 'user' } }, 'was aborted'], - [{ kind: 'error', error: new Error('bad') }, 'failed: bad'], - [{ kind: 'error', error: { message: 'provider bad', code: 'SERVER' } }, 'provider bad'], - [{ kind: 'max-tokens' }, 'output-token limit'], - [{ kind: 'interrupted' }, 'persistence recovery'], - ] - for (const [reason, expected] of cases) expect(formatTurnFailure(reason)).toContain(expected) - expect(formatTurnFailure({ kind: 'extension' } as unknown as TurnEndReason)).toContain('extension') - }) -}) diff --git a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts index 0a3b65ba5e..268fa8fa28 100644 --- a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts +++ b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts @@ -6,7 +6,7 @@ import { Context } from 'cordis' import { FsVersion } from '@deepseek-ai/dsh-fs' import { CallId } from '@deepseek-ai/dsh-llm' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import LocalFileSystem from '@deepseek-ai/dsh-fs-local' import * as FsPolicy from '@deepseek-ai/dsh-fs-policy' @@ -28,18 +28,17 @@ afterEach(async () => { function agent(ctx: Context, cwd: string): Agent { const id = SessionId(`str-replace-editor-owner-${callNumber}`) const scope = ctx.plugin(() => {}) + const session = new Session(id, [], { version: 0, id, createdAt: 0, cwd }) const value: Agent = { id, options: {}, - session: new Session(id, [], { version: 0, id, createdAt: 0, cwd }), + session, + inbox: new Inbox(session), status: 'idle', - acceptsNextStep: false, ctx: scope.ctx, followup: () => {}, steer: () => {}, inject: () => {}, - send: () => {}, - updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/goal/command-goal/tests/command-goal.spec.ts b/packages/goal/command-goal/tests/command-goal.spec.ts index ef7204e7c0..f7a1a5b304 100644 --- a/packages/goal/command-goal/tests/command-goal.spec.ts +++ b/packages/goal/command-goal/tests/command-goal.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' -import AgentRegistry, {} from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import CommandService from '@deepseek-ai/dsh-commands' import GoalService from '@deepseek-ai/dsh-goal' @@ -34,6 +34,7 @@ function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } id: session.id, options: {}, session, + inbox: new Inbox(session), ctx: new Context(), get status() { return status }, followup: () => {}, diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index d1144bea1d..93d3ef926e 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -9,7 +9,7 @@ import type { GoalView } from '@deepseek-ai/dsh-goal' import { createUserMessage, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm' import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' -import type { TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session' +import type { UserMessage } from '@deepseek-ai/dsh-session' import * as goalSession from '../src/index.ts' type ScriptEntry = StreamChunk[] | Error | 'hang' | ((options: GenerateOptions) => StreamChunk[]) @@ -133,28 +133,6 @@ async function waitForRequests(adapter: ScriptedAdapter, count: number): Promise } describe('goal-round outcome policy', () => { - it.each([ - [{ kind: 'completed' }, true, { kind: 'continue' }], - [{ kind: 'aborted' }, true, { kind: 'pause', reason: 'cancelled' }], - [{ kind: 'error', step: 1, message: 'slow down', code: 'RATE_LIMIT' }, true, - { kind: 'blocked', code: 'usage-limited', message: 'slow down' }], - [{ kind: 'error', step: 1, failure: { message: 'credits exhausted', code: 'QUOTA' } }, true, - { kind: 'blocked', code: 'usage-limited', message: 'credits exhausted' }], - [{ kind: 'error', step: 1, failure: { message: 'provider failed', code: 'SERVER' } }, true, - { kind: 'blocked', code: 'turn-error', message: 'provider failed' }], - [{ kind: 'error', step: 1, message: 'broken' }, true, - { kind: 'blocked', code: 'turn-error', message: 'broken' }], - [{ kind: 'max-tokens' }, true, - { kind: 'blocked', code: 'max-tokens', message: 'model output reached max tokens' }], - [{ kind: 'disposed' }, true, { kind: 'disarm', reason: 'disposed' }], - [{ kind: 'interrupted' }, true, { kind: 'disarm', reason: 'interrupted' }], - [{ kind: 'completed' }, false, { kind: 'disarm', reason: 'durability-failed' }], - [{ kind: 'future-outcome' } as unknown as TurnEndReason, true, - { kind: 'blocked', code: 'unknown-turn-outcome', message: 'unknown turn outcome: future-outcome' }], - ] as const)('maps %j without abnormal automatic retry', (reason, durable, expected) => { - expect(goalSession.classifyGoalRound(reason, durable)).toEqual(expected) - }) - it('renders the objective, round budget, authority boundary, and completion protocol', () => { const goal: GoalView = { id: GoalId('goal-prompt'), @@ -259,7 +237,7 @@ describe('same-session goal driving', () => { it('maps a downstream prompt veto to blocked without admitting the round', async () => { const test = await harness([]) - test.ctx.on('agent/prompt-submit', (_agent, message, _signal, next) => message.source.kind === 'goal' + test.ctx.on('agent/prompt-submit', (_agent, messages, _signal, next) => messages[0]?.source.kind === 'goal' ? Promise.resolve({ kind: 'block', reason: 'deployment policy' }) : next()) test.ctx.goals.create(test.agent, { objective: 'respect policy' }) @@ -274,7 +252,7 @@ describe('same-session goal driving', () => { it('does not reserve again when a stopped-goal observer queues ordinary work', async () => { const test = await harness([textResponse('human follow-up')]) - test.ctx.on('agent/prompt-submit', (_agent, message, _signal, next) => message.source.kind === 'goal' + test.ctx.on('agent/prompt-submit', (_agent, messages, _signal, next) => messages[0]?.source.kind === 'goal' ? Promise.resolve({ kind: 'block', reason: 'stop this round' }) : next()) test.ctx.on('goal/changed', (agent, change) => { @@ -382,8 +360,8 @@ describe('same-session goal driving', () => { it('rechecks revision after downstream prompt hooks before admitting', async () => { const test = await harness([textResponse('new revision')]) let edited = false - test.ctx.on('agent/prompt-submit', (agent, message, _signal, next) => { - if (message.source.kind === 'goal' && !edited) { + test.ctx.on('agent/prompt-submit', (agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && !edited) { edited = true const current = test.ctx.goals.get(agent) if (current === undefined) throw new Error('missing goal during prompt edit') @@ -489,8 +467,8 @@ describe('same-session goal driving', () => { // attempt through cancel-requested) and THEN throws: the catch finds no // matching reservation and must not reschedule a paused goal. let fired = false - test.ctx.on('agent/prompt-submit', async (agent, message, _signal, next) => { - if (message.source.kind === 'goal' && !fired) { + test.ctx.on('agent/prompt-submit', async (agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && !fired) { fired = true agent.cancel({ kind: 'user' }) throw new Error('hook cancelled then exploded') @@ -513,8 +491,8 @@ describe('same-session goal driving', () => { // Registered after goal-session's own listener: the throw propagates back // through goal-session's next() await, dropping the whole admission. let threw = false - test.ctx.on('agent/prompt-submit', async (_agent, message, _signal, next) => { - if (message.source.kind === 'goal' && !threw) { + test.ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && !threw) { threw = true throw new Error('downstream admission hook exploded') } @@ -660,8 +638,8 @@ describe('same-session goal driving', () => { it('fails a post-hook read closed before the prompt can enter history', async () => { const test = await harness([]) let armed = true - test.ctx.on('agent/prompt-submit', (_agent, message, _signal, next) => { - if (message.source.kind === 'goal' && armed) { + test.ctx.on('agent/prompt-submit', (_agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && armed) { armed = false vi.spyOn(test.ctx.goals, 'get').mockImplementationOnce(() => { throw new Error('post-hook projection failed') @@ -735,8 +713,8 @@ describe('same-session goal driving', () => { it('blocks admission when downstream cancellation clears the reservation', async () => { const test = await harness([]) let cancelled = false - test.ctx.on('agent/prompt-submit', (agent, message, _signal, next) => { - if (message.source.kind === 'goal' && !cancelled) { + test.ctx.on('agent/prompt-submit', (agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && !cancelled) { cancelled = true agent.cancel({ kind: 'user' }) } @@ -804,8 +782,8 @@ describe('same-session goal driving', () => { it('leaves a queued reservation pending when the driver runs before its turn settles', async () => { const test = await harness([textResponse('settled later')]) let woken = false - test.ctx.on('agent/prompt-submit', async (_agent, message, _signal, next) => { - if (message.source.kind === 'goal' && !woken) { + test.ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && !woken) { woken = true // A concurrent driver pass must observe the still-unsettled attempt // and yield rather than double-book or clear the reservation. @@ -929,8 +907,8 @@ describe('same-session goal driving', () => { it('does not re-block a goal the downstream veto already saw cancelled', async () => { const test = await harness([]) let vetoed = false - test.ctx.on('agent/prompt-submit', (agent, message, _signal, next) => { - if (message.source.kind === 'goal' && !vetoed) { + test.ctx.on('agent/prompt-submit', (agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && !vetoed) { vetoed = true agent.cancel({ kind: 'user' }) return Promise.resolve({ kind: 'block', reason: 'cancelled by policy' }) @@ -952,8 +930,8 @@ describe('same-session goal driving', () => { it('awaits an unadmitted reservation stuck in admission during teardown without cancelling', async () => { const test = await harness([]) let release: (() => void) | undefined - test.ctx.on('agent/prompt-submit', async (_agent, message, _signal, next) => { - if (message.source.kind === 'goal' && release === undefined) { + test.ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next) => { + if (messages[0]?.source.kind === 'goal' && release === undefined) { await new Promise((resolve) => { release = resolve }) } return next() diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts index f395996011..b4802204dc 100644 --- a/packages/goal/goal/tests/goal.spec.ts +++ b/packages/goal/goal/tests/goal.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { agentEvents, Inbox } from '@deepseek-ai/dsh-agent' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import { createUserMessage, HarnessError, type ContentBlock, type MessageSource } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionId, type UserMessage } from '@deepseek-ai/dsh-session' @@ -44,6 +44,7 @@ function stubAgentForSession(session: Session): StubAgent { id, options: {}, session, + inbox: new Inbox(session), ctx: new Context(), get status() { return status }, followup: () => {}, diff --git a/packages/goal/goal/tests/invariant.spec.ts b/packages/goal/goal/tests/invariant.spec.ts index 805c98fdcf..50fac9c5c6 100644 --- a/packages/goal/goal/tests/invariant.spec.ts +++ b/packages/goal/goal/tests/invariant.spec.ts @@ -52,13 +52,7 @@ describe('goal stream invariants', () => { source: changeSource, }), { surfaceOp: 'append' }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - session.append('turn/start', { - turn: 2, - trigger: { - kind: 'message', - source: { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 }, - }, - }) + session.append('turn/start', { turn: 2 }) expect(() => { session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'continue' }], @@ -102,13 +96,7 @@ describe('goal stream invariants', () => { await ctx.plugin(InvariantService, { enabled: true }) await ctx.plugin(GoalInvariantCompanion) - session.append('turn/start', { - turn: 2, - trigger: { - kind: 'message', - source: { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 }, - }, - }) + session.append('turn/start', { turn: 2 }) expect(() => { session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'continue after load' }], diff --git a/packages/goal/goal/tests/projection.spec.ts b/packages/goal/goal/tests/projection.spec.ts index 70fcbc0d5a..23496935e6 100644 --- a/packages/goal/goal/tests/projection.spec.ts +++ b/packages/goal/goal/tests/projection.spec.ts @@ -10,7 +10,7 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import { createUserMessage } from '@deepseek-ai/dsh-llm' import type { UserMessage } from '@deepseek-ai/dsh-session' @@ -35,6 +35,7 @@ function liveAgent(ctx: Context, session: Session): Agent { id: session.id, options: {}, session, + inbox: new Inbox(session), ctx, get status() { return status }, followup: () => {}, diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts index d411e0c9b2..89ff0206a6 100644 --- a/packages/goal/tool-goal/tests/tool-goal.spec.ts +++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' -import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { agentEvents, Inbox } from '@deepseek-ai/dsh-agent' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import GoalService, { GoalId } from '@deepseek-ai/dsh-goal' import type { GoalRef } from '@deepseek-ai/dsh-goal' @@ -29,6 +29,7 @@ function stubAgent(rawId: string, supplied?: Session): StubAgent { id: session.id, options: {}, session, + inbox: new Inbox(session), get status() { return status }, ctx: new Context(), followup: () => {}, diff --git a/packages/hooks/hooks-claude/tests/coverage-cases.ts b/packages/hooks/hooks-claude/tests/coverage-cases.ts index f9f5d1b088..33e098b4da 100644 --- a/packages/hooks/hooks-claude/tests/coverage-cases.ts +++ b/packages/hooks/hooks-claude/tests/coverage-cases.ts @@ -514,10 +514,12 @@ export function defineCoverageCases(group: CoverageGroup): void { const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] }) const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(path, adapter) - ctx.on('agent/prompt-submit', async () => ({ + ctx.on('agent/prompt-submit', async (_agent, messages) => ({ kind: 'allow' as const, - content: [{ type: 'text' as const, text: 'rewritten-prompt' }], - additionalContexts: [createUserMessage({ + messages: [{ + ...messages[0]!, + content: [{ type: 'text' as const, text: 'rewritten-prompt' }], + }, createUserMessage({ content: [{ type: 'text' as const, text: 'from-downstream' }], source: { kind: 'plugin' as const, plugin: 'policy' }, })], diff --git a/packages/hooks/hooks-codex/tests/coverage-cases.ts b/packages/hooks/hooks-codex/tests/coverage-cases.ts index fcded1394f..6cd2cd4617 100644 --- a/packages/hooks/hooks-codex/tests/coverage-cases.ts +++ b/packages/hooks/hooks-codex/tests/coverage-cases.ts @@ -122,10 +122,12 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"from-bridge"}}\'\n') }] }] }) const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(join(d, 'hooks.json'), adapter) - ctx.on('agent/prompt-submit', async () => ({ + ctx.on('agent/prompt-submit', async (_agent, messages) => ({ kind: 'allow' as const, - content: [{ type: 'text' as const, text: 'rewritten-prompt' }], - additionalContexts: [createUserMessage({ + messages: [{ + ...messages[0]!, + content: [{ type: 'text' as const, text: 'rewritten-prompt' }], + }, createUserMessage({ content: [{ type: 'text' as const, text: 'from-downstream' }], source: { kind: 'plugin' as const, plugin: 'policy' }, })], diff --git a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts index f9a00cf9ef..4833667583 100644 --- a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts @@ -34,7 +34,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> { /** A minimal agent stand-in inside an open turn (the service only reaches `.session`). */ function agentOf(ctx: Context): Agent { const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) return { session } as unknown as Agent } @@ -185,7 +185,7 @@ describe('approval pending registry', () => { const abort = new AbortController() const mux = openMux(api, abort) const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('approval/asked', { id: 'pre-aborted' as ApprovalRequestId, toolName: 'bash' }) const agent = { session } as unknown as Agent const cancelled = new AbortController() @@ -308,7 +308,7 @@ describe('approval pending registry', () => { // Bypass ApprovalService: a log whose sole asked event already has its // decided partner must not be re-claimed — the answerer delegates. const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) session.append('approval/asked', { id: 'stale-ask' as ApprovalRequestId, toolName: 'bash' }) session.append('approval/decided', { id: 'stale-ask' as ApprovalRequestId, outcome: 'rejected' }) const agent = { session } as unknown as Agent @@ -322,7 +322,7 @@ describe('approval pending registry', () => { // Bypass ApprovalService: dispatch the waterfall directly with a session // that has no approval/asked event — the proxy answerer must call next(). const session = ctx.sessions.create() - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) const agent = { session } as unknown as Agent const outcome = await ctx.waterfall('approval/request', { agent, toolName: 'x' }, () => Promise.resolve('unavailable' as const)) expect(outcome).toBe('unavailable') diff --git a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts index 0e3f0ffe18..15c7361024 100644 --- a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts @@ -57,7 +57,7 @@ async function composed(withTitles = true): Promise { function liveAgent(ctx: Context, id: string, turns: number): Session { const session = ctx.sessions.create(sid(id), { meta: { cwd: '/proj' } }) for (let turn = 1; turn <= turns; turn++) { - session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn }) session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `prompt ${String(turn)}` }], source: { kind: 'user' }, diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts index 52e40decdc..c8f522f950 100644 --- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts @@ -3,7 +3,7 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent, AgentFactory } from '@deepseek-ai/dsh-agent' import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' import type { Session } from '@deepseek-ai/dsh-session' @@ -44,6 +44,7 @@ function stubAgent(session: Session): Agent { id: session.id, options: {}, session, + inbox: new Inbox(session), status: 'idle', ctx: new Context(), followup: () => {}, diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts index 5724b631f9..1e04d85b5e 100644 --- a/packages/llm/llm-retry/tests/invariant.spec.ts +++ b/packages/llm/llm-retry/tests/invariant.spec.ts @@ -72,7 +72,7 @@ describe('llm-retry invariants', () => { expect(() => { session.append('llm/retry', { turn: 1, step: 1, ...normal }) - session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } }) + session.append('turn/end', { turn: 1, reason: { kind: 'error', error: failure } }) session.append('turn/start', { turn: 2 }) session.append('step/start', { turn: 2, step: 1 }) session.append('step/end', { turn: 2, step: 1 }) @@ -187,7 +187,10 @@ describe('llm-retry invariants', () => { }).toThrow(/latest closed step is 1/) const closedTurn = closeStep(ctx, 'retry-invariant-closed-turn') - closedTurn.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) + closedTurn.append('turn/end', { + turn: 1, + reason: { kind: 'aborted', reason: { kind: 'user' } }, + }) expect(() => { closedTurn.append('llm/retry', { turn: 1, step: 1, ...normal }) }).toThrow(/inside an open turn/) @@ -207,7 +210,7 @@ describe('llm-retry invariants', () => { const ctx = await setup() const mismatch = closeStep(ctx, 'retry-invariant-numbering') mismatch.append('llm/retry', { turn: 1, step: 1, ...normal }) - mismatch.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } }) + mismatch.append('turn/end', { turn: 1, reason: { kind: 'error', error: failure } }) mismatch.append('turn/start', { turn: 2 }) mismatch.append('step/start', { turn: 2, step: 1 }) mismatch.append('step/end', { turn: 2, step: 1 }) @@ -217,7 +220,7 @@ describe('llm-retry invariants', () => { const reset = closeStep(ctx, 'retry-invariant-reset') reset.append('llm/retry', { turn: 1, step: 1, ...normal }) - reset.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } }) + reset.append('turn/end', { turn: 1, reason: { kind: 'error', error: failure } }) reset.append('turn/start', { turn: 2 }) reset.append('step/start', { turn: 2, step: 1 }) reset.append('assistant/message', { @@ -264,7 +267,7 @@ describe('llm-retry invariants', () => { const missingStart = ctx.sessions.create(SessionId('retry-invariant-missing-start')) missingStart.append('turn/end', { turn: 1, - reason: { kind: 'error', step: 1, failure }, + reason: { kind: 'error', error: failure }, }) appendRetryTurn(missingStart, 2) diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts index 60fedbc70d..433f9d9bf5 100644 --- a/packages/llm/llm-retry/tests/persistence.spec.ts +++ b/packages/llm/llm-retry/tests/persistence.spec.ts @@ -53,8 +53,7 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind) turn: 1, reason: { kind: 'error', - step: 1, - failure: { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }, + error: { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }, }, }) diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts index 2a5d51116c..f011fb3e5d 100644 --- a/packages/llm/llm-retry/tests/retry.spec.ts +++ b/packages/llm/llm-retry/tests/retry.spec.ts @@ -908,9 +908,7 @@ describe('provider-routed retry policy', () => { const captured = Promise.withResolvers() let invokeCaptured: (() => Promise) | undefined const mounted = await harness(adapter, {}, (ctx) => { - ctx.on('agent/request-error', ( - _agent, _turn, _step, _error, _failure, _history, _retryPolicy, _signal, next, - ) => { + ctx.on('agent/request-error', (_agent, _context, _signal, next) => { return new Promise((resolve) => { invokeCaptured = async () => { resolve(await next()) } captured.resolve(undefined) @@ -919,9 +917,7 @@ describe('provider-routed retry policy', () => { }) context = mounted.ctx let downstreamCalls = 0 - context.on('agent/request-error', async ( - _agent, _turn, _step, _error, _failure, _history, _retryPolicy, _signal, next, - ) => { + context.on('agent/request-error', async (_agent, _context, _signal, next) => { downstreamCalls += 1 return next() }) @@ -975,9 +971,7 @@ describe('provider-routed retry policy', () => { textResponse('must not run'), ]) ;({ ctx: context } = await harness(adapter, { mock: policy }, (ctx) => { - ctx.on('agent/request-error', async ( - agent, _turn, _step, _error, _failure, _history, _retryPolicy, _signal, next, - ) => { + ctx.on('agent/request-error', async (agent, _context, _signal, next) => { agent.cancel({ kind: 'user' }) return next() }) diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md index 4dc4a0ca06..28f281908c 100644 --- a/packages/llm/llm/README.zh.md +++ b/packages/llm/llm/README.zh.md @@ -16,10 +16,10 @@ - `ctx.llm.listModels(provider: string): Promise` 发现某个已注册提供方当前公布的模型。 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise` 从拥有精确路由的适配器解析经校验的确切模型身份、可用上下文和推理（reasoning）元数据；异步适配器可选地支持取消。 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise` 校验显式推理强度，并填入适配器配置的默认值，但不自动调整。 -- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise` 解析配置并将其当前适配器注册捕获为一次可取消、一次性调用。 +- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise` 解析配置，并将当前适配器注册及不可变重试策略捕获为一次可取消、一次性调用。 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable` 将一次模型调用流式输出为原始分片（token 级增量）。消费方使用 `BlockAssembler` 将分片组装为块／消息。 -`LlmService` 保留来自最终适配器选择、同步 dispatch、iterator 构造与迭代的错误，并将其溯源绑定到该次模型调用返回的精确流句柄。`isLlmAdapterFailure(stream, value)` 只报告该调用最终适配器边界的错误；`llmFailureOf(stream, value)` 返回关联的不可变 `LlmFailure`；`llmRetryPolicyOf(stream)` 返回在该边界选中的确切注册所对应的不可变策略，即使之后释放或替换路由也不变。未到达最终适配器的调用没有服务策略。嵌套模型调用、`llm/stream` middleware 和下游消费方失败对外层调用仍未分类。分类绝不替换或更改适配器原有的带代码 `Error`。 +`LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。 提供方与模型元数据是发现接口，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。 @@ -44,7 +44,7 @@ 消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带提供方／模型溯源与可选适配器私有回放状态。dispatch 前，`LlmService` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。 -流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。 +流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 到达消费方；运行故障使用其 `error` 或 `aborted` 原因，而不会跨流 API 抛出。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。 ### 调用配置（`call-config.ts`） @@ -67,7 +67,7 @@ ### 真实适配器 -两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek` 路由使用直接 fetch 加 `eventsource-parser` SSE（Server-Sent Events）分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `StreamChunk` 约定，定义见 `types.ts`：usage 先于 finish，工具参数保持原始字符串，错误使用两种已批准路径之一。设计理由见 [双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)。 +两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek` 路由使用直接 fetch 加 `eventsource-parser` SSE（Server-Sent Events）分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `types.ts` 中的 `StreamChunk` 约定：usage 先于 finish，工具参数保持原始字符串。适配器实现在内部可以抛出异常或发出失败 finish；`LlmService` 会将两者都暴露为终止失败 finish。适配器理由见[双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)，服务边界见[终止失败决策](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md)。 ## 模型体验 diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts index a736d5042a..67b14d10fe 100644 --- a/packages/llm/llm/src/index.ts +++ b/packages/llm/llm/src/index.ts @@ -510,9 +510,12 @@ export class LlmService extends Service { let completed = false try { while (true) { - let item: IteratorResult + let item: { done: true } | { done: false; value: StreamChunk } try { - item = await iterator.next() + const next = await iterator.next() + item = next.done + ? { done: true } + : { done: false, value: next.value } } catch (error: unknown) { completed = true yield adapterFailureChunk(error, options.signal) @@ -527,8 +530,7 @@ export class LlmService extends Service { yield item.value } } finally { - // oxlint-disable-next-line typescript/no-unnecessary-condition -- the iteration catch sets its latch before entering finally. - if (!completed && !iterationFailed) { + if (!completed) { const close = iterator.return?.bind(iterator) if (close) await close() } diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts index 1afb3c4b6d..af87442744 100644 --- a/packages/llm/llm/tests/service.spec.ts +++ b/packages/llm/llm/tests/service.spec.ts @@ -6,11 +6,8 @@ import LlmService, { HarnessError, isContextWindowExceededError, isQuotaExceededError, - isLlmAdapterFailure, LlmAdapter, LlmError, - llmFailureOf, - llmRetryPolicyOf, ProviderRequestId, ReasoningEffortId, resolveRetryPolicy, @@ -93,6 +90,12 @@ const SCRIPT: StreamChunk[] = [ { type: 'finish', reason: { kind: 'stop' } }, ] +async function collect(stream: AsyncIterable): Promise { + const chunks: StreamChunk[] = [] + for await (const chunk of stream) chunks.push(chunk) + return chunks +} + describe('LlmService', () => { it('recognizes structured and model-capacity context-window overflow details', () => { expect(isContextWindowExceededError('context_length_exceeded maximum context length')).toBe(true) @@ -217,69 +220,58 @@ describe('LlmService', () => { ) }) - it('keeps the serving registration policy on an in-flight call after route replacement', async () => { + it('keeps a prepared registration and retry policy after route replacement', async () => { const oldPolicy = resolveRetryPolicy({ mode: 'always' }, 'old retryPolicy') const newPolicy = resolveRetryPolicy({ mode: 'normal', maxRetries: 0 }, 'new retryPolicy') - const entered = Promise.withResolvers() - const release = Promise.withResolvers() - const failure = new LlmError('old route failed', 'AUTH') - const oldAdapter = new class extends LlmAdapter { + const oldFailure = new LlmError('old route failed', 'AUTH') + const ctx = new Context() + await ctx.plugin(LlmService) + const disposeOld = ctx.llm.registerAdapter(['route'], new class extends ThrowingAdapter { override providerRetryPolicy(): typeof oldPolicy { return oldPolicy } + }(oldFailure)) + const prepared = await ctx.llm.prepareCall({ provider: 'route', model: 'model' }) - async * stream(_options: GenerateOptions): AsyncIterable { - entered.resolve(undefined) - await release.promise - throw failure - } - }() - const newAdapter = new class extends ScriptedAdapter { + disposeOld() + ctx.llm.registerAdapter(['route'], new class extends ScriptedAdapter { override providerRetryPolicy(): typeof newPolicy { return newPolicy } - }(SCRIPT) - const ctx = new Context() - await ctx.plugin(LlmService) - const disposeOld = ctx.llm.registerAdapter(['route'], oldAdapter) - const stream = ctx.llm.stream({ provider: 'route', model: 'model', messages: [] }) - const outcome = (async (): Promise => { - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - return error - } - return undefined - })() - await entered.promise + }(SCRIPT)) - disposeOld() - ctx.llm.registerAdapter(['route'], newAdapter) - release.resolve(undefined) - - expect(await outcome).toBe(failure) - expect(llmRetryPolicyOf(stream)).toBe(oldPolicy) + const chunks = await collect(prepared.stream({ ...prepared.config, messages: [] })) + expect(chunks.at(-1)).toEqual({ + type: 'finish', + reason: { + kind: 'error', + failure: { message: 'old route failed', code: 'AUTH' }, + }, + }) + expect(prepared.retryPolicy).toBe(oldPolicy) expect(ctx.llm.providerRetryPolicy('route')).toBe(newPolicy) }) - it('throws NO_ADAPTER for unregistered providers', async () => { + it('normalizes an unregistered provider to a terminal failure', async () => { const ctx = new Context() await ctx.plugin(LlmService) - const stream = ctx.llm.stream({ provider: 'nope', model: 'any-model', messages: [] }) - let caught: unknown - try { - for await (const _ of stream) { /* drain */ } - } catch (error: unknown) { - caught = error - } - expect(caught).toBeInstanceOf(LlmError) - expect((caught as LlmError).code).toBe('NO_ADAPTER') - expect((caught as LlmError).message).toContain('no adapter registered') - expect(isLlmAdapterFailure(stream, caught)).toBe(true) - expect(llmRetryPolicyOf(stream)).toBeUndefined() + + const chunks = await collect(ctx.llm.stream({ + provider: 'nope', + model: 'any-model', + messages: [], + })) + + expect(chunks.at(-1)).toMatchObject({ + type: 'finish', + reason: { + kind: 'error', + failure: { code: 'NO_ADAPTER', message: expect.stringContaining('no adapter registered') }, + }, + }) }) - it.each(['done', 'value'] as const)('tags a throwing IteratorResult.%s getter without replacing its Error', async (field) => { + it.each(['done', 'value'] as const)('normalizes a throwing IteratorResult.%s getter', async (field) => { const original = new LlmError(`${field} getter failed`, 'RESULT_GETTER_FAILED') const result = field === 'done' ? {} : { done: false } Object.defineProperty(result, field, { get: () => { throw original } }) @@ -295,31 +287,30 @@ describe('LlmService', () => { }) const adapter = new class extends LlmAdapter { stream(_options: GenerateOptions): AsyncIterable { - return { - [Symbol.asyncIterator](): AsyncIterator { - return iterator - }, - } + return { [Symbol.asyncIterator]: () => iterator } } }() const ctx = new Context() await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], adapter) + ctx.llm.registerAdapter(['test'], adapter) - const stream = ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] }) - let caught: unknown - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - caught = error - } + const chunks = await collect(ctx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + })) - expect(caught).toBe(original) - expect(isLlmAdapterFailure(stream, caught)).toBe(true) + expect(chunks.at(-1)).toEqual({ + type: 'finish', + reason: { + kind: 'error', + failure: { message: `${field} getter failed`, code: 'RESULT_GETTER_FAILED' }, + }, + }) expect(cleanupLookups).toBe(0) }) - it.each(['dispatch', 'iterator'] as const)('tags synchronous adapter %s failures without replacing their Error', async (boundary) => { + it.each(['dispatch', 'iterator'] as const)('normalizes synchronous adapter %s failures', async (boundary) => { const original = new LlmError(`${boundary} failed`, 'BOUNDARY_FAILED') const adapter = new class extends LlmAdapter { stream(_options: GenerateOptions): AsyncIterable { @@ -329,339 +320,63 @@ describe('LlmService', () => { }() const ctx = new Context() await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], adapter) + ctx.llm.registerAdapter(['test'], adapter) - const stream = ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] }) - let caught: unknown - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - caught = error - } + const chunks = await collect(ctx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + })) - expect(caught).toBe(original) - expect(isLlmAdapterFailure(stream, caught)).toBe(true) - expect(llmFailureOf(stream, caught)).toEqual({ - message: `${boundary} failed`, - code: 'BOUNDARY_FAILED', + expect(chunks.at(-1)).toEqual({ + type: 'finish', + reason: { + kind: 'error', + failure: { message: `${boundary} failed`, code: 'BOUNDARY_FAILED' }, + }, }) }) - it('keeps structured provider facts beside a frozen third-party Error', async () => { - const original = new LlmError('provider busy', 'RATE_LIMIT', { + it('preserves structured LlmError facts in the terminal failure', async () => { + const failure = new LlmError('provider busy', 'RATE_LIMIT', { status: 429, providerRetryAfterMs: 1_500, requestId: ProviderRequestId('req-7'), }) - Object.freeze(original) const ctx = new Context() await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) + ctx.llm.registerAdapter(['test'], new ThrowingAdapter(failure)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - let caught: unknown - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - caught = error - } + const chunks = await collect(ctx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + })) - expect(caught).toBe(original) - expect(llmFailureOf(stream, caught)).toEqual({ - message: 'provider busy', - code: 'RATE_LIMIT', - status: 429, - providerRetryAfterMs: 1_500, - requestId: ProviderRequestId('req-7'), - }) - }) - - it('does not trust retry facts carried by an unknown third-party Error', async () => { - const carried = { message: 'busy', code: 'SERVER', status: 503 } - const original = Object.assign(new Error('busy'), { failure: carried }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - const facts = llmFailureOf(stream, original) - carried.status = 500 - - expect(facts).toEqual({ message: 'busy', code: 'UNKNOWN' }) - expect(Object.isFrozen(facts)).toBe(true) - expect(facts).not.toBe(carried) - }) - - it('keeps validated failure facts across package copies with matching own codes', async () => { - const original = Object.assign(new Error('provider busy'), { - code: 'RATE_LIMIT', - failure: { - message: 'provider busy', - code: 'RATE_LIMIT', - status: 429, - providerRetryAfterMs: 1_500, - requestId: 'req-cross-copy', + expect(chunks.at(-1)).toEqual({ + type: 'finish', + reason: { + kind: 'error', + failure: { + message: 'provider busy', + code: 'RATE_LIMIT', + status: 429, + providerRetryAfterMs: 1_500, + requestId: ProviderRequestId('req-7'), + }, }, }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ - message: 'provider busy', - code: 'RATE_LIMIT', - status: 429, - providerRetryAfterMs: 1_500, - requestId: 'req-cross-copy', - }) }) - it('keeps an unknown SDK Error exact without trusting its private code or accessors', async () => { - const original = Object.assign(new Error('socket closed'), { code: 'ECONNRESET' }) - Object.defineProperty(original, 'failure', { - get() { throw new Error('SDK failure accessor must not run') }, - }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - - expect(original.code).toBe('ECONNRESET') - expect(llmFailureOf(stream, original)).toEqual({ message: 'socket closed', code: 'UNKNOWN' }) - }) - - it('keeps an SDK Error exact when its message accessor is hostile', async () => { - const original = Object.defineProperty(new Error(), 'message', { - get() { throw new Error('SDK message accessor trap') }, - }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ message: 'LLM adapter failed', code: 'UNKNOWN' }) - }) - - it('keeps an SDK Error exact without trusting accessor-backed carried facts', async () => { - const original = Object.assign(new Error('busy'), { - failure: { message: 'busy', code: 'SERVER', status: 503 }, - }) - Object.defineProperty(original, 'code', { - get() { throw new Error('SDK code accessor must not escape') }, - }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ message: 'busy', code: 'UNKNOWN' }) - }) - - it('does not trust carried facts matched only by an inherited code', async () => { - class InheritedCodeError extends Error { - get code(): string { return 'SERVER' } - } - const original = Object.assign(new InheritedCodeError('busy'), { - failure: { message: 'busy', code: 'SERVER', status: 503 }, - }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ message: 'busy', code: 'UNKNOWN' }) - }) - - it('keeps an SDK Error exact when code descriptor inspection is trapped', async () => { - const target = Object.assign(new Error('busy'), { - code: 'SERVER', - failure: { message: 'busy', code: 'SERVER', status: 503 }, - }) - const original = new Proxy(target, { - getOwnPropertyDescriptor(value, property) { - if (property === 'code') throw new Error('SDK code descriptor trap') - return Reflect.getOwnPropertyDescriptor(value, property) - }, - }) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ message: 'busy', code: 'UNKNOWN' }) - }) - - it('falls back safely when SDK objects trap failure inspection or expose malformed facts', async () => { - const propertyTrap = new Proxy(new HarnessError('descriptor trapped', 'SERVER'), { - getOwnPropertyDescriptor(target, property) { - if (property === 'failure') throw new Error('SDK descriptor trap') - return Reflect.getOwnPropertyDescriptor(target, property) - }, - }) - const throwingFacts = Object.create(null) as Record - Object.defineProperty(throwingFacts, 'message', { - get() { throw new Error('SDK fact getter trap') }, - }) - const carrying = (message: string, failure: unknown): HarnessError => Object.defineProperty( - new HarnessError(message, 'SERVER'), - 'failure', - { value: failure }, - ) - const factGetter = carrying('fact getter failed', throwingFacts) - const malformed = carrying('malformed facts', { message: 'provider busy', code: 'SERVER', requestId: 1 }) - const primitive = carrying('primitive facts', 1) - const nullFacts = carrying('null facts', null) - const mismatched = carrying('mismatched facts', { message: 'busy', code: 'RATE_LIMIT' }) - - for (const [original, expectedMessage] of [ - [propertyTrap, 'descriptor trapped'], - [factGetter, 'fact getter failed'], - [malformed, 'malformed facts'], - [primitive, 'primitive facts'], - [nullFacts, 'null facts'], - [mismatched, 'mismatched facts'], - ] as const) { - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ message: expectedMessage, code: 'SERVER' }) - } - }) - - it('retains a stable code from a HarnessError without requiring LlmError facts', async () => { - const original = new HarnessError('stable adapter failure', 'ADAPTER_STABLE') - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-provider'], new ThrowingAdapter(original)) - const stream = ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toBe(original) - expect(llmFailureOf(stream, original)).toEqual({ - message: 'stable adapter failure', - code: 'ADAPTER_STABLE', - }) - expect(llmFailureOf(stream, 'not an Error')).toBeUndefined() - expect(llmFailureOf({ [Symbol.asyncIterator]: () => stream[Symbol.asyncIterator]() }, original)).toBeUndefined() - }) - - it('keeps a nested adapter failure scoped to the nested model call', async () => { - const original = new LlmError('nested provider failed', 'NESTED_FAILED') - const outer = new RecordingAdapter(SCRIPT) - const nested = new ThrowingAdapter(original) - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['outer'], outer) - ctx.llm.registerAdapter(['nested'], nested) - let nestedStream: AsyncIterable | undefined - ctx.on('llm/stream', (options, next) => { - if (options.provider !== 'outer') return next() - return (async function* () { - nestedStream = ctx.llm.stream({ provider: 'nested', model: 'nested', messages: [] }) - yield * nestedStream - })() - }) - - const outerStream = ctx.llm.stream({ provider: 'outer', model: 'outer', messages: [] }) - let caught: unknown - try { - for await (const _chunk of outerStream) { /* drain */ } - } catch (error: unknown) { - caught = error - } - - expect(caught).toBe(original) - expect(nestedStream).toBeDefined() - expect(isLlmAdapterFailure(nestedStream!, caught)).toBe(true) - expect(isLlmAdapterFailure(outerStream, caught)).toBe(false) - expect(outer.lastOptions).toBeUndefined() - }) - - it('keeps call scopes distinct when middleware reuses an iterable', async () => { - const firstFailure = new LlmError('first provider failed', 'FIRST_FAILED') - const secondFailure = new LlmError('second provider failed', 'SECOND_FAILED') - const delegates: AsyncIterable[] = [] - const shared: AsyncIterable = { - [Symbol.asyncIterator](): AsyncIterator { - const delegate = delegates.shift() - if (delegate === undefined) throw new Error('shared stream has no call delegate') - return delegate[Symbol.asyncIterator]() - }, - } - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['first'], new ThrowingAdapter(firstFailure)) - ctx.llm.registerAdapter(['second'], new ThrowingAdapter(secondFailure)) - ctx.on('llm/stream', (_options, next) => { - delegates.push(next()) - return shared - }) - - const firstStream = ctx.llm.stream({ provider: 'first', model: 'first', messages: [] }) - const secondStream = ctx.llm.stream({ provider: 'second', model: 'second', messages: [] }) - const catchFailure = async (stream: AsyncIterable): Promise => { - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - return error - } - return new Error('expected adapter to fail') - } - - expect(firstStream).not.toBe(secondStream) - const firstCaught = await catchFailure(firstStream) - expect(firstCaught).toBe(firstFailure) - expect(isLlmAdapterFailure(firstStream, firstCaught)).toBe(true) - expect(isLlmAdapterFailure(secondStream, firstCaught)).toBe(false) - const secondCaught = await catchFailure(secondStream) - expect(secondCaught).toBe(secondFailure) - expect(isLlmAdapterFailure(secondStream, secondCaught)).toBe(true) - expect(isLlmAdapterFailure(firstStream, secondCaught)).toBe(false) - expect(delegates).toHaveLength(0) - }) - - it('propagates a rejected next promptly without awaiting a non-settling return', async () => { - const original = new LlmError('provider failed', 'PROVIDER_FAILED') - let cleanupCalls = 0 + it('normalizes arbitrary adapter rejections without throwing them downstream', async () => { const adapter = new class extends LlmAdapter { stream(_options: GenerateOptions): AsyncIterable { return { [Symbol.asyncIterator](): AsyncIterator { return { - next: () => Promise.reject(original), - return: () => { - cleanupCalls += 1 - return new Promise>(() => {}) - }, + // Third-party adapters can reject with arbitrary values. + // oxlint-disable-next-line typescript/prefer-promise-reject-errors + next: () => Promise.reject('plain provider failure'), } }, } @@ -669,30 +384,73 @@ describe('LlmService', () => { }() const ctx = new Context() await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], adapter) + ctx.llm.registerAdapter(['test'], adapter) - const stream = ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] }) - const failure = (async (): Promise => { - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - return error - } - return new Error('expected adapter iteration to fail') - })() - let timer: ReturnType | undefined - const timeout = new Promise((resolve) => { - timer = setTimeout(() => { resolve(new Error('adapter failure did not settle promptly')) }, 100) + const chunks = await collect(ctx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + })) + + expect(chunks.at(-1)).toEqual({ + type: 'finish', + reason: { + kind: 'error', + failure: { message: 'plain provider failure', code: 'UNKNOWN' }, + }, }) - const caught = await Promise.race([failure, timeout]) - if (timer !== undefined) clearTimeout(timer) - - expect(caught).toBe(original) - expect(isLlmAdapterFailure(stream, caught)).toBe(true) - expect(cleanupCalls).toBe(0) }) - it('awaits one adapter return on downstream close and leaves its rejection unclassified', async () => { + it('maps adapter failure to aborted when the request signal is aborted', async () => { + const controller = new AbortController() + controller.abort('cancelled') + const ctx = new Context() + await ctx.plugin(LlmService) + ctx.llm.registerAdapter(['test'], new ThrowingAdapter(new Error('stopped'))) + + const chunks = await collect(ctx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + signal: controller.signal, + })) + + expect(chunks.at(-1)).toMatchObject({ + type: 'finish', + reason: { kind: 'aborted', failure: { message: 'stopped' } }, + }) + }) + + it('leaves middleware and consumer failures thrown', async () => { + const middlewareFailure = new Error('middleware failed') + const middlewareCtx = new Context() + await middlewareCtx.plugin(LlmService) + middlewareCtx.llm.registerAdapter(['test'], new ScriptedAdapter(SCRIPT)) + middlewareCtx.on('llm/stream', () => (async function* () { + throw middlewareFailure + })()) + await expect(collect(middlewareCtx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + }))).rejects.toBe(middlewareFailure) + + const consumerFailure = new Error('consumer failed') + const consumerCtx = new Context() + await consumerCtx.plugin(LlmService) + consumerCtx.llm.registerAdapter(['test'], new ScriptedAdapter(SCRIPT)) + await expect((async () => { + for await (const _chunk of consumerCtx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + })) { + throw consumerFailure + } + })()).rejects.toBe(consumerFailure) + }) + + it('awaits adapter cleanup on downstream close and leaves cleanup failure thrown', async () => { const cleanup = new Error('cleanup failed') let cleanupCalls = 0 const adapter = new class extends LlmAdapter { @@ -712,95 +470,18 @@ describe('LlmService', () => { }() const ctx = new Context() await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], adapter) + ctx.llm.registerAdapter(['test'], adapter) - const stream = ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] }) - let caught: unknown - try { - for await (const _chunk of stream) break - } catch (error: unknown) { - caught = error - } - - expect(caught).toBe(cleanup) - expect(isLlmAdapterFailure(stream, caught)).toBe(false) + await expect((async () => { + for await (const _chunk of ctx.llm.stream({ + provider: 'test', + model: 'test', + messages: [], + })) break + })()).rejects.toBe(cleanup) expect(cleanupCalls).toBe(1) }) - it('allows downstream close when the adapter iterator has no return method', async () => { - const adapter = new class extends LlmAdapter { - stream(_options: GenerateOptions): AsyncIterable { - return { - [Symbol.asyncIterator](): AsyncIterator { - return { next: () => Promise.resolve({ done: false, value: SCRIPT[0]! }) } - }, - } - } - }() - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], adapter) - - let chunks = 0 - for await (const _chunk of ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] })) { - chunks += 1 - break - } - - expect(chunks).toBe(1) - }) - - it('normalizes and tags non-Error adapter failures once', async () => { - const adapter = new class extends LlmAdapter { - stream(_options: GenerateOptions): AsyncIterable { - return { - [Symbol.asyncIterator](): AsyncIterator { - // Third-party adapters can reject with arbitrary values. - // oxlint-disable-next-line typescript/prefer-promise-reject-errors - return { next: () => Promise.reject('plain provider failure') } - }, - } - } - }() - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], adapter) - - const stream = ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] }) - let caught: unknown - try { - for await (const _chunk of stream) { /* drain */ } - } catch (error: unknown) { - caught = error - } - - expect(caught).toBeInstanceOf(HarnessError) - expect(caught).toMatchObject({ code: 'UNKNOWN', cause: 'plain provider failure' }) - expect(isLlmAdapterFailure(stream, caught)).toBe(true) - }) - - it('does not tag a failure thrown downstream while consuming adapter output', async () => { - const downstream = new Error('consumer failed') - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter(SCRIPT)) - - const stream = ctx.llm.stream({ provider: 'test-model', model: 'test-model', messages: [] }) - let caught: unknown - try { - for await (const _chunk of stream) throw downstream - } catch (error: unknown) { - caught = error - } - - expect(caught).toBe(downstream) - expect(isLlmAdapterFailure(stream, caught)).toBe(false) - expect(isLlmAdapterFailure(new ScriptedAdapter(SCRIPT).stream({ - provider: 'unbound', model: 'unbound', messages: [], - }), caught)).toBe(false) - expect(isLlmAdapterFailure(stream, 'consumer failed')).toBe(false) - }) - it('unregisters adapters when the owning fiber is disposed (HMR safety)', async () => { const ctx = new Context() await ctx.plugin(LlmService) @@ -1064,15 +745,15 @@ describe('LlmService', () => { ctx.llm.registerAdapter(['route'], adapter) const prepared = await ctx.llm.prepareCall({ provider: 'route', model: 'model' }) expect(Object.isFrozen(prepared.config)).toBe(true) - const stream = prepared.stream({ + expect(() => prepared.stream({ ...prepared.config, model: 'other', messages: [], - }) - - await expect((async () => { - for await (const _chunk of stream) { /* drain */ } - })()).rejects.toMatchObject({ code: 'INVALID_PREPARED_CALL' }) + })).toThrow(expect.objectContaining({ code: 'INVALID_PREPARED_CALL' })) + await collect(prepared.stream({ + ...prepared.config, + messages: [], + })) expect(() => prepared.stream({ ...prepared.config, messages: [], diff --git a/packages/plan/plan-mode/tests/integration.spec.ts b/packages/plan/plan-mode/tests/integration.spec.ts index 0945a4c8c2..31f1ce66a0 100644 --- a/packages/plan/plan-mode/tests/integration.spec.ts +++ b/packages/plan/plan-mode/tests/integration.spec.ts @@ -136,9 +136,7 @@ describe('plan mode through the agent loop', () => { const adapter = new MockAdapter([failedRequest, textResponse('Recovered in plan mode.')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('it-plan-retry-flip'), { provider: 'mock', model: 'mock' }) - ctx.on('agent/request-error', async ( - subject, _turn, _step, _error, _failure, _priorFailures, _retryPolicy, _signal, next, - ) => { + ctx.on('agent/request-error', async (subject, _context, _signal, next) => { if (subject !== agent) return next() ctx.planMode.set(agent, true) return { kind: 'retry' } diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts index d988fc3d1c..2708b00ecc 100644 --- a/packages/plan/plan-mode/tests/plan-mode.spec.ts +++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts @@ -59,14 +59,15 @@ async function setup(config: PlanModeConfig = PLAN_CONFIG): Promise { async function boundary(ctx: Context, agent: Agent & { session: Session }, type: 'turn/start' | 'step/end'): Promise { const events = agentEvents(ctx, agent) if (type === 'turn/start') { + const message = createUserMessage({ + content: [{ type: 'text', text: 'boundary probe' }], + source: { kind: 'user' }, + }) await events.waterfall( 'agent/prompt-submit', - createUserMessage({ - content: [{ type: 'text', text: 'boundary probe' }], - source: { kind: 'user' }, - }), + [message], new AbortController().signal, - () => Promise.resolve({ kind: 'allow' }), + () => Promise.resolve({ kind: 'allow', messages: [message] }), ) return } diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts index 3976e586cb..46cc691a38 100644 --- a/packages/pty/pty-local/tests/index.spec.ts +++ b/packages/pty/pty-local/tests/index.spec.ts @@ -3,7 +3,7 @@ import type { IPty, IPtyForkOptions } from 'node-pty' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox, type Agent } from '@deepseek-ai/dsh-agent' import SandboxProvider from '@deepseek-ai/dsh-sandbox' import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox' import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy' @@ -40,8 +40,9 @@ function config(): ResolvedConfig { function agent(ctx: Context): Agent { const id = SessionId('agent') + const session = new Session(id) return { - id, options: {}, session: new Session(id), status: 'idle', ctx, + id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } @@ -248,7 +249,7 @@ describe('pty-local plugin shape', () => { const session = ctx.sessions.create(SessionId('mode-owner')) const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { - id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: ownerFiber.ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) @@ -291,7 +292,7 @@ describe('pty-local plugin shape', () => { const session = ctx.sessions.create(SessionId('pending-mode-owner')) const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { - id: session.id, options: {}, session, status: 'idle', ctx: ownerFiber.ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: ownerFiber.ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts index c2cb23cb59..1a52bcc672 100644 --- a/packages/pty/pty-local/tests/local.spec.ts +++ b/packages/pty/pty-local/tests/local.spec.ts @@ -4,7 +4,7 @@ import { join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' import { Context } from 'cordis' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, {} from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import PtyService from '@deepseek-ai/dsh-pty' import type { PtySendOperation } from '@deepseek-ai/dsh-pty' @@ -33,8 +33,9 @@ class PassthroughSandbox extends SandboxProvider { function stubAgent(ctx: Context, rawId: string): Agent { const id = SessionId(rawId) const scope = ctx.plugin(() => {}) + const session = new Session(id) return { - id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx, + id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } diff --git a/packages/pty/pty/tests/service.spec.ts b/packages/pty/pty/tests/service.spec.ts index cf5c4f0bab..5cb1dea2d0 100644 --- a/packages/pty/pty/tests/service.spec.ts +++ b/packages/pty/pty/tests/service.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, expectTypeOf, it } from 'vitest' import { Context } from 'cordis' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, {} from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import PtyService, { PtyBackendCleanupError, PtyError, PtySessionId } from '@deepseek-ai/dsh-pty' import type { @@ -21,10 +21,12 @@ const ptyServiceDisposers = new WeakMap Promise>() function stubAgent(ctx: Context, rawId: string): Agent { const id = SessionId(rawId) const scopeFiber = ctx.plugin(() => {}) + const session = new Session(id) const agent: Agent = { id, options: {}, - session: new Session(id), + session, + inbox: new Inbox(session), status: 'idle', ctx: scopeFiber.ctx, followup: () => {}, diff --git a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts index 9e18402477..68f08223ff 100644 --- a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts +++ b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts @@ -8,7 +8,7 @@ import Loader from '@cordisjs/plugin-loader' import Include from '@cordisjs/plugin-include' import { CallId } from '@deepseek-ai/dsh-llm' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import PtyService from '@deepseek-ai/dsh-pty' import * as PtyLocal from '@deepseek-ai/dsh-pty-local' @@ -38,18 +38,17 @@ class PassthroughSandbox extends SandboxProvider { function agent(ctx: Context, cwd: string): Agent { const id = SessionId('persistent-bash-loader-agent') const scope = ctx.plugin(() => {}) + const session = new Session(id, [], { version: 0, id, createdAt: 0, cwd }) const value: Agent = { id, options: {}, - session: new Session(id, [], { version: 0, id, createdAt: 0, cwd }), + session, + inbox: new Inbox(session), status: 'idle', - acceptsNextStep: false, ctx: scope.ctx, followup: () => {}, steer: () => {}, inject: () => {}, - send: () => {}, - updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/pty/tool-bash-persistent/tests/tools.spec.ts b/packages/pty/tool-bash-persistent/tests/tools.spec.ts index 9949879292..b0e64b770c 100644 --- a/packages/pty/tool-bash-persistent/tests/tools.spec.ts +++ b/packages/pty/tool-bash-persistent/tests/tools.spec.ts @@ -2,7 +2,7 @@ import { afterEach, describe, expect, it } from 'vitest' import { Context } from 'cordis' import { CallId } from '@deepseek-ai/dsh-llm' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import PtyService from '@deepseek-ai/dsh-pty' import type { @@ -29,23 +29,22 @@ afterEach(async () => { function agent(ctx: Context, cwd: string | undefined): Agent { const id = SessionId(`persistent-bash-owner-${callNumber}`) const scope = ctx.plugin(() => {}) + const session = new Session(id, [], { + version: 0, + id, + createdAt: 0, + ...cwd === undefined ? {} : { cwd }, + }) const value: Agent = { id, options: {}, - session: new Session(id, [], { - version: 0, - id, - createdAt: 0, - ...cwd === undefined ? {} : { cwd }, - }), + session, + inbox: new Inbox(session), status: 'idle', - acceptsNextStep: false, ctx: scope.ctx, followup: () => {}, steer: () => {}, inject: () => {}, - send: () => {}, - updateInbox: () => 'not-found', cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts index da8555e4c8..29ad29e65d 100644 --- a/packages/pty/tool-pty/tests/loader-composition.spec.ts +++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts @@ -8,7 +8,7 @@ import Loader from '@cordisjs/plugin-loader' import Include from '@cordisjs/plugin-include' import { CallId } from '@deepseek-ai/dsh-llm' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, {} from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' @@ -38,8 +38,9 @@ class PassthroughSandbox extends SandboxProvider { function agent(ctx: Context): Agent { const scope = ctx.plugin(() => {}) const id = SessionId('pty-loader-agent') + const session = new Session(id) const value: Agent = { - id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx, + id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(value) diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts index ed9a41d370..bc25489fcf 100644 --- a/packages/pty/tool-pty/tests/tools.spec.ts +++ b/packages/pty/tool-pty/tests/tools.spec.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import { CallId } from '@deepseek-ai/dsh-llm' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, {} from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { renderToolsSdk } from '@deepseek-ai/dsh-tools' @@ -16,8 +16,9 @@ import * as ToolPty from '@deepseek-ai/dsh-tool-pty' function fakeAgent(ctx: Context, rawId: string): Agent { const scope = ctx.plugin(() => {}) const id = SessionId(rawId) + const session = new Session(id) const agent: Agent = { - id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx, + id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(agent) diff --git a/packages/sdk/sdk-client/tests/sdk-client.spec.ts b/packages/sdk/sdk-client/tests/sdk-client.spec.ts index e31490a6cd..ca2d30b3cc 100644 --- a/packages/sdk/sdk-client/tests/sdk-client.spec.ts +++ b/packages/sdk/sdk-client/tests/sdk-client.spec.ts @@ -158,7 +158,6 @@ describe('DeepSeekHarness', () => { // Retry spawns a NEW subprocess through a fresh client (close is permanent). const result = await harness.run('again') expect(harness.client).not.toBe(firstClient) - expect(result.status).toBe('ok') expect(result.finalResponse).toBe('second boot answer') await harness.close() // close() is terminal: a handshake failure after it must not respawn. @@ -176,7 +175,7 @@ describe('DeepSeekHarness', () => { await using harness = new DeepSeekHarness({ launch: fakeLaunch() }) captured = harness const result = await harness.run('scoped') - expect(result.status).toBe('ok') + expect(result.finalResponse).toBe('scoped') } // After scope exit the runtime is closed: reuse fails loudly. await expect(captured.run('after')).rejects.toThrow(TransportClosedError) diff --git a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts index 689bbad618..25cdb8fa6b 100644 --- a/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts +++ b/packages/session-query/session-query-sqlite/tests/sqlite.spec.ts @@ -241,7 +241,7 @@ describe('SQLite session search', () => { { type: 'user/message', seq: 2, time: 12, data: createUserMessage({ content: [{ type: 'text', text: 'needle summary' }], source: { kind: 'plugin', plugin: 'test' }, }), surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] }, - { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'error', step: 1, message: 'needle failure' } } }, + { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'error', error: 'needle failure' } } }, ] ctx.sessions.create(SessionId('a'), { seed: events, meta: { cwd: '/a', parentSession: parent, createdAt: 20 } }) ctx.sessions.create(SessionId('b'), { seed: messageEvents('needle peer', 12), meta: { createdAt: 20 } }) diff --git a/packages/session-query/session-query/tests/search-helpers.spec.ts b/packages/session-query/session-query/tests/search-helpers.spec.ts index 891b95892c..c47f528809 100644 --- a/packages/session-query/session-query/tests/search-helpers.spec.ts +++ b/packages/session-query/session-query/tests/search-helpers.spec.ts @@ -111,11 +111,10 @@ describe('session-query semantic extraction', () => { it('extracts meaningful turn outcomes and skips structural or unknown events', () => { const reasons: Array<[SessionEvent<'turn/end'>['data']['reason'], string]> = [ - [{ kind: 'error', step: 2, message: 'boom', code: 'E' }, 'error\nboom\nE'], - [{ kind: 'error', step: 2, message: 'boom' }, 'error\nboom'], - [{ kind: 'error', step: 2, failure: { message: 'provider boom', code: 'SERVER' } }, 'error\nprovider boom\nSERVER'], - [{ kind: 'aborted' }, 'aborted'], - [{ kind: 'disposed' }, 'disposed'], + [{ kind: 'error', error: new Error('boom') }, 'error\nboom'], + [{ kind: 'error', error: 'provider boom' }, 'error\nprovider boom'], + [{ kind: 'aborted', reason: { kind: 'user' } }, 'aborted'], + [{ kind: 'aborted', reason: { kind: 'disposed' } }, 'aborted'], [{ kind: 'max-tokens' }, 'max-tokens'], [{ kind: 'interrupted' }, 'interrupted'], [{ kind: 'completed' }, ''], diff --git a/packages/session-title/session-title/tests/rename.spec.ts b/packages/session-title/session-title/tests/rename.spec.ts index 01d613ee3e..c7069c5c2f 100644 --- a/packages/session-title/session-title/tests/rename.spec.ts +++ b/packages/session-title/session-title/tests/rename.spec.ts @@ -34,7 +34,7 @@ describe('SessionTitleService.rename', () => { await ctx.plugin(SessionStore) await ctx.plugin(SessionTitleService, CONFIG) const session = ctx.sessions.create(SessionId('rename-accept')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) appendHumanPrompt(session, 'Original prompt text') await settle() @@ -79,7 +79,7 @@ describe('SessionTitleService.rename', () => { generate, }) const session = ctx.sessions.create(SessionId('rename-pin')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) appendHumanPrompt(session, 'First prompt') await settle() ctx.sessionTitle.rename(session, 'Pinned by hand') @@ -107,7 +107,7 @@ describe('SessionTitleService.rename', () => { await ctx.plugin(SessionStore) await ctx.plugin(SessionTitleService, CONFIG) const session = ctx.sessions.create(SessionId('rename-unpin-fallback')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) appendHumanPrompt(session, 'Derivable prompt words') await settle() ctx.sessionTitle.rename(session, 'Pinned without provider') @@ -143,7 +143,7 @@ describe('SessionTitleService.rename', () => { generate, }) const session = ctx.sessions.create(SessionId('rename-supersede')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) appendHumanPrompt(session, 'Prompt that triggers generation') session.append('request/header', { header: { config: { provider: 'main-route', model: 'chat-model' } }, @@ -169,7 +169,7 @@ describe('SessionTitleService.rename', () => { // re-derived fallback is empty, so the pinned title survives the refresh. await ctx.plugin(SessionTitleService, { ...CONFIG, fallbackMaxBytes: 3 }) const session = ctx.sessions.create(SessionId('rename-unpin-empty')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) appendHumanPrompt(session, '😀😀') await settle() ctx.sessionTitle.rename(session, 'Sticky emoji pin') diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts index 98ae51e38a..f49d05e55a 100644 --- a/packages/skill/tool-skill/tests/tool-skill.spec.ts +++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts @@ -8,7 +8,7 @@ import { createScope, type Scope } from '@deepseek-ai/dsh-scope' import { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools' -import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent' import SkillService from '@deepseek-ai/dsh-skill' import * as SkillLocal from '@deepseek-ai/dsh-skill-local' import * as toolSkill from '@deepseek-ai/dsh-tool-skill' @@ -44,6 +44,7 @@ function agentForCwd(cwd: string): Agent { id, options: {}, session, + inbox: new Inbox(session), status: 'idle', followup: () => {}, steer: () => {}, @@ -60,6 +61,7 @@ function sessionAgent(session: Session, id = 'tool-skill-agent'): Agent { id: SessionId(id), options: {}, session, + inbox: new Inbox(session), status: 'running', ctx: new Context(), followup: () => {}, diff --git a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts index 16a9c57899..2b22174eca 100644 --- a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts +++ b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts @@ -73,10 +73,10 @@ describe('sdkStopReason', () => { it('maps each child turn-end reason to the harness vocabulary', () => { expect(sdkStopReason({ kind: 'completed' })).toBe('completed') expect(sdkStopReason({ kind: 'max-tokens' })).toBe('max-tokens') - expect(sdkStopReason({ kind: 'aborted' })).toBe('aborted') - expect(sdkStopReason({ kind: 'error', step: 0, message: 'x' })).toBe('error') + expect(sdkStopReason({ kind: 'aborted', reason: { kind: 'user' } })).toBe('aborted') + expect(sdkStopReason({ kind: 'error', error: new Error('x') })).toBe('error') expect(sdkStopReason({ kind: 'interrupted' })).toBe('error') - expect(sdkStopReason({ kind: 'disposed' })).toBe('error') + expect(sdkStopReason({ kind: 'aborted', reason: { kind: 'disposed' } })).toBe('aborted') }) it('treats an absent or unknown reason as an error', () => { diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts index 467cc26a0b..86e45529a8 100644 --- a/packages/support/llm-replay/tests/llm-replay.spec.ts +++ b/packages/support/llm-replay/tests/llm-replay.spec.ts @@ -166,7 +166,7 @@ describe('deriveReplayScript', () => { const events: SessionEvent[] = [ chunkEvent(1, 1, 1, { type: 'block-start', index: 0, blockType: 'text' }), chunkEvent(2, 1, 1, { type: 'text-delta', index: 0, text: 'par' }), - { type: 'turn/end', seq: 3, time: 0, data: { turn: 1, reason: { kind: 'error', step: 1, message: 'x' } } }, + { type: 'turn/end', seq: 3, time: 0, data: { turn: 1, reason: { kind: 'error', error: 'x' } } }, ] expect(() => deriveReplayScript(events)).toThrow(/without a finish chunk.*replay\.override\.json/s) }) diff --git a/packages/tasks/tasks-local/tests/tasks.spec.ts b/packages/tasks/tasks-local/tests/tasks.spec.ts index 5cf11732cf..c3495a1cd2 100644 --- a/packages/tasks/tasks-local/tests/tasks.spec.ts +++ b/packages/tasks/tasks-local/tests/tasks.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, expectTypeOf, it, vi } from 'vitest' import { Context } from 'cordis' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, {} from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { TaskId } from '@deepseek-ai/dsh-tasks' import type { TaskHooks, TaskKind, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks' @@ -18,10 +18,12 @@ const agentScopeDisposers = new WeakMap Promise>() function stubAgent(ctx: Context, rawId: string): Agent { const id = SessionId(rawId) const scopeFiber = ctx.plugin(() => {}) + const session = new Session(id) const agent = { id, options: {}, - session: new Session(id), + session, + inbox: new Inbox(session), status: 'idle' as const, ctx: scopeFiber.ctx, followup: () => {}, diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts index d6f8bf0664..fa2b67db2b 100644 --- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts +++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts @@ -94,7 +94,7 @@ describe('TelemetryOtel wire', () => { const { ctx, fiber } = await boot(url) const session = ctx.sessions.create(SessionId('wire'), { meta: { cwd: '/tmp/w' } }) session.append('turn/start', { turn: 1 }) - session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } }) + session.append('turn/end', { turn: 1, reason: { kind: 'error', error: new Error('boom') } }) await fiber.dispose() expect(captures.length).toBeGreaterThan(0) diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts index c5d3fb650a..50c54f4148 100644 --- a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts +++ b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts @@ -126,7 +126,7 @@ describe('TelemetryCoordinator capture', () => { }), }, { surfaceOp: 'append' }) session.append('telemetry-test/opaque', { payload: { nested: [] } }) - session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } }) + session.append('turn/end', { turn: 1, reason: { kind: 'error', error: new Error('boom') } }) const severities = backend.ledger().map(r => [r.attributes['event.type'], r.severity]) expect(severities).toEqual([ ['turn/start', 'info'], diff --git a/packages/ui/permission/tests/projection.spec.ts b/packages/ui/permission/tests/projection.spec.ts index 2046adb6a1..7f6ae10a30 100644 --- a/packages/ui/permission/tests/projection.spec.ts +++ b/packages/ui/permission/tests/projection.spec.ts @@ -62,7 +62,7 @@ describe('permissions projection unit', () => { expect(changes).toHaveLength(3) expect(changes.at(-1)).toMatchObject({ key: 'permissions', value: { currentValue: 'danger-full-access' } }) // Unrelated event: same-reference apply, no notification. - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/start', { turn: 1 }) expect(changes).toHaveLength(3) }) diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index de8288d71d..ad1eb5fb12 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -1227,7 +1227,7 @@ export function createTuiChat( if (cleanedUp) return cleanedUp = true detachSubmit() - detachDiscard() + detachSplice() } // Prepended so this wrapper is outermost: it observes the exact accepted // message identity whether a downstream hook allows or blocks, then detaches. @@ -1238,11 +1238,16 @@ export function createTuiChat( if (decision.kind !== 'allow') return decision return { ...decision, messages: [...decision.messages, attachedContext] } }, { prepend: true }) - // Installed before followup(): an enqueue listener can synchronously - // cancel and discard before followup() returns its id. - const detachDiscard = ctx.on('agent/inbox/discard', (subject, items) => { - if (subject !== agent) return - for (const item of items) discarded.add(item.message.id) + // Installed before followup(): an inbox observer can synchronously cancel + // the inserted message before followup() returns. + const detachSplice = ctx.on('session/event', (session, event) => { + if (session !== agent.session || event.type !== 'agent/inbox/spliced' + || event.data.target !== 'next-turn' || event.data.outcome !== 'canceled') return + const removed = agent.inbox.nextTurn.slice( + event.data.start, + event.data.start + (event.data.removedCount ?? 0), + ) + for (const item of removed) discarded.add(item.id) if (discarded.has(acceptedId)) cleanup() }) // followup() accepts any typed input and contains listener failures; @@ -1463,6 +1468,15 @@ export function createTuiChat( const disposeSessionEvents = ctx.on('session/event', (session, event) => { if (session !== agent.session) return + if (event.type === 'agent/inbox/spliced' && event.data.target === 'next-step') { + const removed = agent.inbox.nextStep.slice( + event.data.start, + event.data.start + (event.data.removedCount ?? 0), + ) + let changed = false + for (const message of removed) changed = pendingSteering.delete(message.id) || changed + if (changed) refreshStatus() + } if (event.type === 'tool/result') fileSearch.invalidate() recordEventUsage(tokens, event) if (event.type === 'turn/start' && runningStatus !== undefined) runningStatus.turn = event.data.turn @@ -1474,18 +1488,6 @@ export function createTuiChat( renderEvent(event, { addHistory: false, renderChunks: true }) requestRender() }) - const settlePendingSteering = (id: MessageId): void => { - if (pendingSteering.delete(id)) refreshStatus() - } - const disposeDequeued = ctx.on('agent/inbox/dequeue', (subject, item) => { - if (subject === agent) settlePendingSteering(item.message.id) - }) - const disposeDiscarded = ctx.on('agent/inbox/discard', (subject, items) => { - if (subject !== agent) return - let changed = false - for (const item of items) changed = pendingSteering.delete(item.message.id) || changed - if (changed) refreshStatus() - }) const disposeStatus = ctx.on('agent/status', (subject, status) => { if (subject !== agent) return // Leaving 'running' ends the turn's status line; clear any badge so the @@ -1526,8 +1528,6 @@ export function createTuiChat( for (const value of promptValues) value.dispose() stopBannerReveal() disposeSessionEvents() - disposeDequeued() - disposeDiscarded() disposeStatus() disposeError() disposeAgent() diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts index a6a22ec2d9..8e3ae3d634 100644 --- a/packages/ui/tui/tests/harness.ts +++ b/packages/ui/tui/tests/harness.ts @@ -2,6 +2,7 @@ import { createUserMessage, MessageId , createMessage } from '@deepseek-ai/dsh-l import { Context } from 'cordis' import type { Terminal } from '@earendil-works/pi-tui' import AgentRegistry, { + Inbox, type Agent, type AgentCancelCause, type AgentOptions, @@ -190,6 +191,7 @@ export async function createTuiTestHarness { }) harness.session.append('turn/end', { turn: 1, - reason: { kind: 'aborted' }, + reason: { kind: 'aborted', reason: { kind: 'user' } }, }) }) await checkpoint('retry-cancelled', harness.terminal, { includeScrollback: true }) @@ -407,8 +407,7 @@ describe('TUI terminal-state snapshots', () => { turn: 1, reason: { kind: 'error', - step: 3, - failure: { message: 'provider still unavailable', code: 'SERVER', status: 503 }, + error: { message: 'provider still unavailable', code: 'SERVER', status: 503 }, }, }) }) @@ -587,7 +586,7 @@ describe('TUI terminal-state snapshots', () => { session.append('step/end', { turn: 1, step: 1 }) session.append('turn/end', { turn: 1, - reason: { kind: 'error', step: 1, message: `Unsafe turn error ${CONTROL_PROBE}` }, + reason: { kind: 'error', error: `Unsafe turn error ${CONTROL_PROBE}` }, }) }, }, { columns: 100, rows: 34 }) @@ -771,7 +770,7 @@ describe('TUI terminal-state snapshots', () => { harness.session.append('step/end', { turn: 1, step: 1 }) harness.session.append('turn/end', { turn: 1, - reason: { kind: 'error', step: 1, message: 'provider stream failed after partial output' }, + reason: { kind: 'error', error: 'provider stream failed after partial output' }, }) harness.session.append('turn/start', { turn: 2 }) harness.session.append('turn/end', { @@ -779,7 +778,10 @@ describe('TUI terminal-state snapshots', () => { reason: { kind: 'interrupted' }, }) harness.session.append('turn/start', { turn: 3 }) - harness.session.append('turn/end', { turn: 3, reason: { kind: 'disposed' } }) + harness.session.append('turn/end', { + turn: 3, + reason: { kind: 'aborted', reason: { kind: 'disposed' } }, + }) harness.session.append('turn/start', { turn: 4 }) // A merge-extensible turn-end kind unknown to the TUI still surfaces its // name so the agent never stops without a visible reason. diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 0979714468..458f3d57e7 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -5,17 +5,14 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import { CombinedAutocompleteProvider, visibleWidth, type Terminal } from '@earendil-works/pi-tui' import AgentRegistry, { - agentEvents, assembleContextFor, InboxItemId, type Agent, type InboxItem, - type InboxPlacement, + agentEvents, assembleContextFor, Inbox, type Agent, } from '@deepseek-ai/dsh-agent' import { createUserMessage, createToolResultMessage, ReasoningEffortId, type LlmCallConfig, type LlmModelReasoningInfo, - MessageId, createMessage, - freezeMessage, } from '@deepseek-ai/dsh-llm' import { GOAL_CHANGE_VERSION, GoalId, renderGoalChange, type GoalSnapshotChangeMeta } from '@deepseek-ai/dsh-goal' import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands' @@ -54,13 +51,6 @@ const UNUSED_TOOL_OUTPUT: ToolDefinition['output'] = { render: () => [], } -let nextInboxItem = 0 - -/** Wrap one test message in the production inbox occurrence envelope. */ -function inboxItem(message: InboxItem['message'], placement: InboxPlacement): InboxItem { - return { id: InboxItemId(`tui-item-${nextInboxItem++}`), message, placement } -} - class FakeTerminal implements Terminal { columns = 88 rows = 32 @@ -461,9 +451,9 @@ describe('goodbye message and /resume', () => { }) it.each([ - [{ kind: 'aborted' }, 'cancelled'], - [{ kind: 'error', step: 1, message: 'failed' }, 'error'], - [{ kind: 'disposed' }, 'disposed'], + [{ kind: 'aborted', reason: { kind: 'user' } }, 'cancelled'], + [{ kind: 'error', error: new Error('failed') }, 'error'], + [{ kind: 'aborted', reason: { kind: 'disposed' } }, 'cancelled'], [{ kind: 'max-tokens' }, 'max tokens'], [{ kind: 'interrupted' }, 'interrupted'], [{ kind: 'future-result' } as unknown as TurnEndReason, 'unknown result'], @@ -1342,7 +1332,10 @@ describe('pi-tui chat lifecycle and transcript', () => { }), { surfaceOp: 'append' }) appendAssistant(result.session, []) result.session.append('step/end', { turn: 1, step: 1 }) - result.session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) + result.session.append('turn/end', { + turn: 1, + reason: { kind: 'aborted', reason: { kind: 'user' } }, + }) result.session.append('turn/start', { turn: 2 }) result.session.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) result.session.append('turn/start', { turn: 3 }) @@ -1660,16 +1653,16 @@ describe('pi-tui chat lifecycle and transcript', () => { const submitSteering = (text: string): void => { result.terminal.send(text) result.terminal.send('\r') + const message = result.agent.steeredOptions.at(-1) + if (message !== undefined) { + result.agent.inbox.splice('next-step', result.agent.inbox.nextStep.length, 0, [message]) + } } const drainSteering = (text: string): void => { const id = result.agent.steeredIds.shift() if (id !== undefined) { - result.ctx.emit('agent/inbox/dequeue', result.agent, inboxItem(freezeMessage({ - id, - role: 'user', - content: [{ type: 'text', text }], - source: { kind: 'user' }, - }), 'steering')) + const index = result.agent.inbox.nextStep.findIndex(message => message.id === id) + if (index >= 0) result.agent.inbox.splice('next-step', index, 1, [], 'admitted') } result.session.append('steering/message', { turn: 1, @@ -1680,18 +1673,6 @@ describe('pi-tui chat lifecycle and transcript', () => { }, { surfaceOp: 'append' }) } - // A steering queue for a different agent never touches this status line. - const other = { ...result.agent, id: SessionId('other') } as Agent - result.terminal.output = '' - result.ctx.emit('agent/inbox/enqueue', other, inboxItem(freezeMessage({ - id: MessageId('stub'), - role: 'user', - content: [{ type: 'text', text: 'elsewhere' }], - source: { kind: 'user' }, - }), 'queued')) - await tick() - expect(result.terminal.output).not.toContain('queued') - // Two steering messages queue while the turn runs. submitSteering('first') result.terminal.output = '' @@ -1753,34 +1734,15 @@ describe('pi-tui chat lifecycle and transcript', () => { submitSteering('fourth') await tick() expect(result.terminal.output).toContain('2 queued') - const discarded = result.agent.steeredIds.splice(0).map(id => freezeMessage({ - id, - role: 'user' as const, - content: [{ type: 'text' as const, text: 'discarded' }], - source: { kind: 'user' as const }, - })) - // Another agent's dequeue/discard, and ones naming no pending id, leave - // the badge alone. - result.ctx.emit('agent/inbox/dequeue', other, inboxItem(discarded[0]!, 'steering')) - result.ctx.emit('agent/inbox/dequeue', result.agent, inboxItem(freezeMessage({ - id: MessageId('never-queued'), - role: 'user', - content: [{ type: 'text', text: 'x' }], - source: { kind: 'user' }, - }), 'steering')) - result.ctx.emit('agent/inbox/discard', other, discarded.map(message => inboxItem(message, 'steering'))) - result.ctx.emit('agent/inbox/discard', result.agent, [ - inboxItem(freezeMessage({ - id: MessageId('never-queued'), - role: 'user', - content: [{ type: 'text', text: 'x' }], - source: { kind: 'user' }, - }), 'steering'), - ]) - await tick() - expect(result.terminal.output).toContain('2 queued') result.terminal.output = '' - result.ctx.emit('agent/inbox/discard', result.agent, discarded.map(message => inboxItem(message, 'steering'))) + result.agent.steeredIds.splice(0) + result.agent.inbox.splice( + 'next-step', + 0, + result.agent.inbox.nextStep.length, + [], + 'canceled', + ) await tick() expect(result.terminal.output).not.toContain('queued') @@ -2096,12 +2058,6 @@ describe('pi-tui chat lifecycle and transcript', () => { it('tracks steering drains without a running status line', async () => { const result = await setup() const source = { kind: 'user' as const } - result.ctx.emit('agent/inbox/enqueue', result.agent, inboxItem(freezeMessage({ - id: MessageId('stub'), - role: 'user', - content: [{ type: 'text', text: 'early' }], - source, - }), 'steering')) result.session.append('steering/message', { turn: 1, message: createUserMessage({ @@ -2609,21 +2565,25 @@ describe('pi-tui chat lifecycle and transcript', () => { // Idle: the snapshot rides the prompt's admission (additionalContexts on // the allow decision), not a separate pre-admission inject. expect(result.agent.injected).toHaveLength(0) + const submitted = result.agent.sentMessages[0]! const decision = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages[0]!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [submitted], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [submitted] }), ) expect(decision.kind).toBe('allow') - expect(decision.kind === 'allow' && decision.additionalContexts?.[0]?.source) + expect(decision.kind === 'allow' + && decision.messages.find(message => message.source.kind === 'session-reference')?.source) .toMatchObject({ kind: 'session-reference', references: [{ sessionId: 'source-session' }] }) // The one-shot wrapper detached itself at admission: replaying the // waterfall attaches nothing a second time. const replay = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages[0]!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [submitted], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [submitted] }), ) - expect(replay.kind === 'allow' && replay.additionalContexts).toBeUndefined() + expect(replay.kind === 'allow' && replay.messages).toEqual([submitted]) const mention = formatSessionReferenceMention({ sessionId: sourceId, label: 'Source chat' }) result.agent.status = 'running' @@ -2662,31 +2622,32 @@ describe('pi-tui chat lifecycle and transcript', () => { // Running each prompt's admission waterfall detaches its wrapper. for (const sent of result.agent.sentMessages) { await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', sent, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [sent], + new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const, messages: [sent] }), ) } // Both wrappers now gone: a discard naming either prompt's content finds // no armed listener, and an unrelated admission is untouched. The leak // regression: a listener installed after its cleanup already ran would // survive every future cleanup. - result.ctx.emit('agent/inbox/discard', result.agent, [inboxItem(result.agent.sentMessages[0]!, 'queued')]) + const unrelatedMessage = createUserMessage({ + content: [{ type: 'text', text: 'unrelated' }], + source: { kind: 'user' }, + }) const unrelated = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', createUserMessage({ - content: [{ type: 'text', text: 'unrelated' }], - source: { kind: 'user' }, - }), - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [unrelatedMessage], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [unrelatedMessage] }), ) - expect(unrelated.kind === 'allow' && unrelated.additionalContexts).toBeUndefined() + expect(unrelated.kind === 'allow' && unrelated.messages).toEqual([unrelatedMessage]) // Replaying either sent prompt attaches nothing: the one-shot wrappers // are gone, not merely spent. for (const sent of result.agent.sentMessages) { const replay = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', sent, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [sent], + new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const, messages: [sent] }), ) - expect(replay.kind === 'allow' && replay.additionalContexts).toBeUndefined() + expect(replay.kind === 'allow' && replay.messages).toEqual([sent]) } await dispose(result) }) @@ -2704,20 +2665,11 @@ describe('pi-tui chat lifecycle and transcript', () => { // Real send() publishes its already identified snapshot, then an enqueue // listener may synchronously cancel and discard it before followup() // returns that id. This stub reproduces that ordering. - const foreign = { ...result.agent, id: SessionId('foreign') } as unknown as Agent result.agent.followup = (input) => { result.agent.sent.push(input.content) result.agent.sentMessages.push(input) - const message = freezeMessage({ - id: input.id, - role: 'user' as const, - content: structuredClone(input.content), - source: structuredClone(input.source), - }) - result.ctx.emit('agent/inbox/enqueue', foreign, inboxItem(message, 'queued')) - result.ctx.emit('agent/inbox/enqueue', result.agent, inboxItem(message, 'queued')) - result.ctx.emit('agent/inbox/discard', result.agent, [inboxItem(message, 'queued')]) - return message.id + result.agent.inbox.splice('next-turn', 0, 0, [input]) + result.agent.inbox.splice('next-turn', 0, 1, [], 'canceled') } result.terminal.send('@sync-source') @@ -2731,10 +2683,11 @@ describe('pi-tui chat lifecycle and transcript', () => { // returned the existing id: replaying the prompt's admission attaches no // stranded snapshot, and nothing leaks for the TUI lifetime. const replay = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages[0]!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [result.agent.sentMessages[0]!], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [result.agent.sentMessages[0]!] }), ) - expect(replay.kind === 'allow' && replay.additionalContexts).toBeUndefined() + expect(replay.kind === 'allow' && replay.messages).toEqual([result.agent.sentMessages[0]!]) await dispose(result) }) @@ -2762,22 +2715,25 @@ describe('pi-tui chat lifecycle and transcript', () => { await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(1) }) const blocked = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages[0]!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [result.agent.sentMessages[0]!], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [result.agent.sentMessages[0]!] }), ) expect(blocked.kind).toBe('block') // Nothing entered history and nothing waits for a later prompt: a fresh // unrelated admission sees no leftover contexts. expect(result.agent.injected).toHaveLength(0) blockPrompts = false + const unrelatedMessage = createUserMessage({ + content: [{ type: 'text', text: 'unrelated' }], + source: { kind: 'user' }, + }) const unrelated = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', createUserMessage({ - content: [{ type: 'text', text: 'unrelated' }], - source: { kind: 'user' }, - }), - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [unrelatedMessage], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [unrelatedMessage] }), ) - expect(unrelated.kind === 'allow' && unrelated.additionalContexts).toBeUndefined() + expect(unrelated.kind === 'allow' && unrelated.messages).toEqual([unrelatedMessage]) // Second referenced prompt, this time dropped by a broad cancel before // any admission runs: the discard listener releases the wrapper. @@ -2788,31 +2744,33 @@ describe('pi-tui chat lifecycle and transcript', () => { result.terminal.send('\r') await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(2) }) // A different prompt passing the still-armed wrapper delegates untouched. + const differentMessage = createUserMessage({ + content: [{ type: 'text', text: 'different prompt' }], + source: { kind: 'user' }, + }) const passthrough = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', createUserMessage({ - content: [{ type: 'text', text: 'different prompt' }], - source: { kind: 'user' }, - }), - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [differentMessage], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [differentMessage] }), ) - expect(passthrough.kind === 'allow' && passthrough.additionalContexts).toBeUndefined() - // A foreign agent's discard leaves the wrapper armed. - const foreign = { ...result.agent, id: SessionId('foreign') } as unknown as Agent - result.ctx.emit('agent/inbox/discard', foreign, [inboxItem(result.agent.sentMessages.at(-1)!, 'queued')]) - // An unrelated discard for this agent also leaves the wrapper armed. - result.ctx.emit('agent/inbox/discard', result.agent, [inboxItem(createUserMessage({ + expect(passthrough.kind === 'allow' && passthrough.messages).toEqual([differentMessage]) + // Canceling the exact pending message releases its wrapper. + const canceled = result.agent.sentMessages.at(-1)! + result.agent.inbox.splice('next-turn', 0, 0, [canceled]) + result.agent.inbox.splice('next-turn', 0, 1, [], 'canceled') + const unrelatedDiscard = createUserMessage({ content: [{ type: 'text', text: 'unrelated discard' }], source: { kind: 'user' }, - }), 'queued')]) - result.ctx.emit('agent/inbox/discard', result.agent, [inboxItem(result.agent.sentMessages.at(-1)!, 'queued')]) + }) + result.agent.inbox.splice('next-turn', 0, 0, [unrelatedDiscard]) + result.agent.inbox.splice('next-turn', 0, 1, [], 'canceled') await tick() - // Idempotent: a repeat discard after cleanup is a no-op. - result.ctx.emit('agent/inbox/discard', result.agent, [inboxItem(result.agent.sentMessages.at(-1)!, 'queued')]) const afterDiscard = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages.at(-1)!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [canceled], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [canceled] }), ) - expect(afterDiscard.kind === 'allow' && afterDiscard.additionalContexts).toBeUndefined() + expect(afterDiscard.kind === 'allow' && afterDiscard.messages).toEqual([canceled]) await dispose(result) }) @@ -2963,11 +2921,14 @@ describe('pi-tui chat lifecycle and transcript', () => { expect(result.agent.sent).toEqual([[ { type: 'text', text: '@evil\\x1b\\x07\\x9b\\x0as' }, ]]) + const submitted = result.agent.sentMessages[0]! const decision = await agentEvents(result.ctx, result.agent).waterfall( - 'agent/prompt-submit', result.agent.sentMessages[0]!, - new AbortController().signal, () => Promise.resolve({ kind: 'allow' as const }), + 'agent/prompt-submit', [submitted], + new AbortController().signal, + () => Promise.resolve({ kind: 'allow' as const, messages: [submitted] }), ) - expect(decision.kind === 'allow' && decision.additionalContexts?.[0]?.source) + expect(decision.kind === 'allow' + && decision.messages.find(message => message.source.kind === 'session-reference')?.source) .toMatchObject({ references: [{ sessionId: unsafeId }] }) await dispose(result) }) @@ -3738,11 +3699,14 @@ describe('pi-tui chat lifecycle and transcript', () => { agentEvents(events.ctx, unrelatedAgent).emit('agent/disposed') agentEvents(events.ctx, events.agent).emit('agent/error', 1, 1, new Error('live failure')) events.session.append('step/end', { turn: 1, step: 1 }) - events.session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'live failure' } }) + events.session.append('turn/end', { turn: 1, reason: { kind: 'error', error: 'live failure' } }) events.session.append('turn/start', { turn: 2 }) - events.session.append('turn/end', { turn: 2, reason: { kind: 'error', step: 1, message: 'durable failure' } }) + events.session.append('turn/end', { turn: 2, reason: { kind: 'error', error: 'durable failure' } }) events.session.append('turn/start', { turn: 3 }) - events.session.append('turn/end', { turn: 3, reason: { kind: 'aborted' } }) + events.session.append('turn/end', { + turn: 3, + reason: { kind: 'aborted', reason: { kind: 'user' } }, + }) events.session.append('turn/start', { turn: 4 }) events.session.append('turn/end', { turn: 4, reason: { kind: 'max-tokens' } }) events.session.append('turn/start', { turn: 5 }) @@ -3750,10 +3714,13 @@ describe('pi-tui chat lifecycle and transcript', () => { events.session.append('turn/start', { turn: 6 }) events.session.append('turn/end', { turn: 6, - reason: { kind: 'error', step: 1, failure: { message: 'structured provider failure', code: 'SERVER' } }, + reason: { kind: 'error', error: { message: 'structured provider failure', code: 'SERVER' } }, }) events.session.append('turn/start', { turn: 8 }) - events.session.append('turn/end', { turn: 8, reason: { kind: 'disposed' } }) + events.session.append('turn/end', { + turn: 8, + reason: { kind: 'aborted', reason: { kind: 'disposed' } }, + }) events.session.append('turn/start', { turn: 9 }) // Merge-extensible reason kind unknown to the TUI still names the stop. events.session.append('turn/end', { turn: 9, reason: { kind: 'plugin-policy' } as never }) @@ -4935,7 +4902,7 @@ describe('terminal mounting', () => { ctx.provide('tools', { get: () => undefined } as never) const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ - id: session.id, options: {}, session, status: 'idle', ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() @@ -4960,7 +4927,7 @@ describe('terminal mounting', () => { ctx.provide('tools', { get: () => undefined } as never) const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ - id: session.id, options: {}, session, status: 'idle', ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() @@ -4995,14 +4962,14 @@ describe('terminal mounting', () => { const otherSession = ctx.sessions.create(SessionId('other-session')) ctx.agents.register({ - id: otherSession.id, options: {}, session: otherSession, status: 'idle', ctx, + id: otherSession.id, options: {}, session: otherSession, inbox: new Inbox(otherSession), status: 'idle', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) expect(terminal.started).toBe(0) const session = ctx.sessions.create(SessionId('late-session')) const agent = { - id: session.id, options: {}, session, status: 'idle', ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } as Agent ctx.agents.register(agent) @@ -5033,7 +5000,7 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main-session')) ctx.agents.register({ - id: session.id, options: {}, session, status: 'idle', ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) await tick() @@ -5077,7 +5044,7 @@ describe('terminal mounting', () => { session.append('turn/start', { turn: 1 }) session.append('step/start', { turn: 1, step: 1 }) ctx.agents.register({ - id: session.id, options: {}, session, status: 'running', ctx, + id: session.id, options: {}, session, inbox: new Inbox(session), status: 'running', ctx, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() From 31a498b1dbd3f8b658970426652a01175a537108 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 17:39:28 +0800 Subject: [PATCH 017/689] test(web): follow inline custom answer input --- packages/client/ui-question/tests/question-composer.spec.tsx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/client/ui-question/tests/question-composer.spec.tsx b/packages/client/ui-question/tests/question-composer.spec.tsx index 40006c2c9c..87eb275b7d 100644 --- a/packages/client/ui-question/tests/question-composer.spec.tsx +++ b/packages/client/ui-question/tests/question-composer.spec.tsx @@ -103,13 +103,12 @@ describe('QuestionComposer', () => { fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' })) fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' })) fireEvent.click(screen.getByRole('checkbox', { name: '代码质量' })) - fireEvent.click(screen.getByRole('button', { name: '其他，请填写自定义答案' })) const multiCustom = screen.getByPlaceholderText('输入你的答案') fireEvent.change(multiCustom, { target: { value: '沟通能力' } }) fireEvent.click(screen.getByRole('checkbox', { name: '产品判断' })) expect(screen.getByRole('checkbox', { name: '系统设计' }).getAttribute('aria-checked')).toBe('true') expect(screen.getByRole('checkbox', { name: '代码质量' }).getAttribute('aria-checked')).toBe('true') - expect((multiCustom as HTMLTextAreaElement).value).toBe('沟通能力') + expect((multiCustom as HTMLInputElement).value).toBe('沟通能力') fireEvent.keyDown(multiCustom, { key: 'Enter' }) // The domain face encoded the whole batch into one carrier envelope. From 285cd60744e0fbebcec20e5f50605c3ea3dc7f8b Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 02:40:31 -0700 Subject: [PATCH 018/689] docs(ui-workspace): align approval status contracts --- apps/web/tests/built-boot.snapshot.ts | 20 ++++++++++--------- packages/client/ui-workspace/README.i18n.yaml | 4 ++-- packages/client/ui-workspace/README.md | 2 +- packages/client/ui-workspace/README.zh.md | 2 +- .../client/ui-workspace/src/client/tree.ts | 2 +- 5 files changed, 16 insertions(+), 14 deletions(-) diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts index 018a9f2180..d436d41866 100644 --- a/apps/web/tests/built-boot.snapshot.ts +++ b/apps/web/tests/built-boot.snapshot.ts @@ -6,10 +6,10 @@ // layers, per-plugin CSS injection, and a rendered journey reaching chat // content from the keyless FixtureApiClient transport. // -// Behavior assertions do NOT belong here: component and wiring behavior is -// pinned by the per-package suites (SlotTestRuntime benches over src), which -// this smoke's plugin set cannot influence — bundling, module-table -// resolution, and boot layering are the only failure modes left to it. +// Component behavior remains owned by per-package suites (SlotTestRuntime +// benches over src). This smoke additionally pins the resident approval +// fixture's cross-plugin projection because only the built connection/runtime/ +// workspace graph can prove that transport-to-row path end to end. import { readFileSync } from 'node:fs' import { join } from 'node:path' import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react' @@ -105,13 +105,15 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn // The resident approval fixture proves the assembled workspace plugin // distinguishes a blocked running session from an ordinarily busy one. const waitingTitle = await within(tree).findByText('Fixture 历史会话') - const waitingRow = waitingTitle.closest('[role="treeitem"]') - expect(waitingRow?.querySelector('[data-state="warning"]')).not.toBeNull() - expect(waitingRow?.querySelector('[data-state="ongoing"]')).toBeNull() - expect(within(waitingRow as HTMLElement).getByText('Waiting for approval')).not.toBeNull() + const waitingRow = waitingTitle.closest('[role="treeitem"]') + expect(waitingRow).not.toBeNull() + if (waitingRow === null) throw new Error('fixture Session title must belong to a tree row') + expect(waitingRow.querySelector('[data-state="warning"]')).not.toBeNull() + expect(waitingRow.querySelector('[data-state="ongoing"]')).toBeNull() + expect(within(waitingRow).getByText('Waiting for approval')).not.toBeNull() // Opening a session reaches chat content through the fixture transport. - fireEvent.click(await within(tree).findByText('Fixture 历史会话')) + fireEvent.click(waitingTitle) await waitFor(() => { expect(document.querySelector('[data-sample="bash-global"]')).not.toBeNull() }, { timeout: 10_000 }) diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml index 27cb783db7..25a2713cfb 100644 --- a/packages/client/ui-workspace/README.i18n.yaml +++ b/packages/client/ui-workspace/README.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 packages/client/ui-workspace/README.md -README.md: 4ca836e4f1beeb164716e5fc4741253719d2700c -README.zh.md: 2a5448a12d58184b027c99b5301510370ba63a83 +README.md: 7109de680f98ede4d8374444cf50b439317ce128 +README.zh.md: 874d9e3d190e0488d95362ce1eea260341d6a23e diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md index 4ca836e4f1..7109de680f 100644 --- a/packages/client/ui-workspace/README.md +++ b/packages/client/ui-workspace/README.md @@ -6,7 +6,7 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration. -Session rows distinguish the runtime's live `waitingApproval` fact from an otherwise blue in-flight Session: an amber warning dot takes precedence over the running indicator, an accompanying visually hidden label exposes the state to assistive technology, and the hover card reports **Waiting for approval** until the request is resolved. Running and idle presentation is unchanged when no approval is pending. +Session rows distinguish the runtime's live `waitingApproval` approval-request fact from an otherwise blue in-flight Session: an amber warning dot takes precedence over the running indicator, and the hover card reports **Waiting for approval** until the request is resolved. Every lit state carries a visually hidden label (`Waiting for approval` or `Running`) for assistive technology; an idle row leaves the reserved status slot empty. Question waits are tracked separately and do not set `waitingApproval`. Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored. diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md index 2a5448a12d..874d9e3d19 100644 --- a/packages/client/ui-workspace/README.zh.md +++ b/packages/client/ui-workspace/README.zh.md @@ -6,7 +6,7 @@ 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。 -Session 行会把 runtime 的实时 `waitingApproval` 状态与原本显示为蓝色的进行中 Session 区分开：琥珀色警告点优先于运行指示器，随附的视觉隐藏标签会向辅助技术公开这一状态，hover 卡片则在请求解决前显示 **Waiting for approval**。没有待审批请求时，运行与空闲展示保持不变。 +Session 行会把 runtime 的实时 `waitingApproval` 审批请求状态与原本显示为蓝色的进行中 Session 区分开：琥珀色警告点优先于运行指示器，hover 卡片则在请求解决前显示 **Waiting for approval**。每种点亮状态都带有面向辅助技术的视觉隐藏标签（`Waiting for approval` 或 `Running`）；空闲行会保留空的状态槽位。问题等待由另一套状态跟踪，不会设置 `waitingApproval`。 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。 diff --git a/packages/client/ui-workspace/src/client/tree.ts b/packages/client/ui-workspace/src/client/tree.ts index 210148c72f..763818334f 100644 --- a/packages/client/ui-workspace/src/client/tree.ts +++ b/packages/client/ui-workspace/src/client/tree.ts @@ -20,7 +20,7 @@ export interface SessionNode { /** The session HAS children in the data (the twist renders even while folded). */ hasChildren: boolean expanded: boolean - /** A pending approval takes display precedence over the running state. */ + /** The runtime Session list reports a pending approval request for this Session. */ waitingApproval: boolean running: boolean updatedAt: number From 51711a37720144172125d6713330a886ddf65b6f Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 02:41:32 -0700 Subject: [PATCH 019/689] docs(ui-sidebar): defer session status ownership --- packages/client/ui-sidebar/README.i18n.yaml | 4 ++-- packages/client/ui-sidebar/README.md | 2 +- packages/client/ui-sidebar/README.zh.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml index 00b33602d0..c1f5d5df03 100644 --- a/packages/client/ui-sidebar/README.i18n.yaml +++ b/packages/client/ui-sidebar/README.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 packages/client/ui-sidebar/README.md -README.md: d2c0c3332f2202986f1daf3a45c84cc1e65eee6d -README.zh.md: 03cb86842d8a28f3a18250a9d77dd0a0a217d7b9 +README.md: 19c2d1033de4475816249aa8429f4a589eeb6481 +README.zh.md: b8c154586570cf1b9fd4bf776bc09b36ab5ee7d2 diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md index d2c0c3332f..19c2d1033d 100644 --- a/packages/client/ui-sidebar/README.md +++ b/packages/client/ui-sidebar/README.md @@ -22,6 +22,6 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work -- **State dots have approval-waiting/running/none live states** — approval waiting is amber and outranks running; done/error notification sources remain deferred. +- **Session state-dot rendering is owned by [ui-workspace](../ui-workspace/README.md)** — done/error notification sources remain deferred. - **Group-by menu ships by-workspace only** — Update/Status grouping strategies are drawn without specs and deferred. - **"New task completed" unread marking is local viewing state** — completion-time > last-seen never reaches the host. diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md index 03cb86842d..b8c1545865 100644 --- a/packages/client/ui-sidebar/README.zh.md +++ b/packages/client/ui-sidebar/README.zh.md @@ -22,6 +22,6 @@ New Session 会启动运行时的页面局部前端 Session Intent；真实 Work ## 已知限制与暂缓事项 -- **状态点具有待审批／running／none 三种实时状态**：待审批使用琥珀色并优先于 running；done/error 的通知数据源仍暂缓实现。 +- **Session 状态点渲染由 [ui-workspace](../ui-workspace/README.md) 持有**：done/error 的通知数据源仍暂缓实现。 - **分组选单只提供按 Workspace 分组**：Update/Status 分组策略只有图稿而没有规范，暂缓实现。 - **「New task completed」未读标记是本地查看状态**：完成时间 > 上次查看时间这一事实永远不会到达宿主。 From 4e5266daa426c2dcc5f24c97ebb15787d56e2eac Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 17:45:58 +0800 Subject: [PATCH 020/689] test: align consumers with owned-run semantics --- .../2026-07-17-one-send-one-turn.i18n.yaml | 2 +- .../llm-streaming.i18n.yaml | 4 +- docs/core-data-structures/llm-streaming.md | 2 +- docs/core-data-structures/llm-streaming.zh.md | 2 +- docs/module-graph.md | 3 +- packages/acp/acp/tests/turns.spec.ts | 26 +++--- packages/core/agent-loop/README.i18n.yaml | 4 +- packages/core/agent-loop/tests/loop.spec.ts | 1 - .../core/agent-loop/tests/properties.spec.ts | 2 +- .../agent-loop/tests/request-error.spec.ts | 6 +- packages/core/agent/package.json | 1 - packages/core/session/tests/fork.spec.ts | 8 +- packages/core/session/tests/invariant.spec.ts | 8 +- packages/examples/cli-demo/src/cli.ts | 4 +- packages/examples/cli-demo/tests/cli.spec.ts | 12 +-- .../apiproxy/tests/api-proxy-cold.spec.ts | 4 +- packages/llm/llm-retry/tests/retry.spec.ts | 23 ++---- .../tests/transport-recovery.spec.ts | 18 ++--- packages/llm/llm/README.i18n.yaml | 4 +- packages/llm/llm/tests/service.spec.ts | 7 +- .../sdk/sdk-client/tests/sdk-client.spec.ts | 2 +- .../session-telemetry-otel/tests/otel.spec.ts | 2 +- .../session-telemetry/tests/telemetry.spec.ts | 2 +- packages/ui/tui/tests/tui.spec.ts | 8 +- python/sdk/tests/manual_sdk_agent_smoke.py | 2 - python/sdk/tests/test_client.py | 80 +++++++++++-------- 26 files changed, 117 insertions(+), 120 deletions(-) diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml index 7d841e0bf9..a0fd1ed4ec 100644 --- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md 2026-07-17-one-send-one-turn.md: 3ae43f137206f25bdbc563875c17e24211f17d6b -2026-07-17-one-send-one-turn.zh.md: 5ccdb2192048ecf795415bcd427f967df6a609fb +2026-07-17-one-send-one-turn.zh.md: 097090073f44194a8f8d4578a8cc39ffc723eb79 diff --git a/docs/core-data-structures/llm-streaming.i18n.yaml b/docs/core-data-structures/llm-streaming.i18n.yaml index c3924f184b..eca9de899d 100644 --- a/docs/core-data-structures/llm-streaming.i18n.yaml +++ b/docs/core-data-structures/llm-streaming.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 docs/core-data-structures/llm-streaming.md -llm-streaming.md: 6811611768a0ec577360a8ff82792899cf3b8fec -llm-streaming.zh.md: 35374af6a20086f15384840689dba5aa24351750 +llm-streaming.md: cdb2f76d9a47192cacedf545ae3d1ebbd985251e +llm-streaming.zh.md: 1cc7b06014224637d391d0a605315bff79b4a9fe diff --git a/docs/core-data-structures/llm-streaming.md b/docs/core-data-structures/llm-streaming.md index 7fa02b6e3b..cdb2f76d9a 100644 --- a/docs/core-data-structures/llm-streaming.md +++ b/docs/core-data-structures/llm-streaming.md @@ -144,7 +144,7 @@ declare class BlockAssembler { * Assemble all blocks seen so far, in stream order. * @returns one block per seen index, except that max-token truncation drops * tool calls that cannot be executed safely; an open block assembles from - * accumulated deltas (an unknown block type never closed by `block-end` throws). + * its accumulated deltas (an unknown block type never closed by `block-end` throws). */ blocks(): ContentBlock[]; /** Usage from the `usage` chunk; undefined until one arrives. */ diff --git a/docs/core-data-structures/llm-streaming.zh.md b/docs/core-data-structures/llm-streaming.zh.md index c25d140895..1cc7b06014 100644 --- a/docs/core-data-structures/llm-streaming.zh.md +++ b/docs/core-data-structures/llm-streaming.zh.md @@ -144,7 +144,7 @@ declare class BlockAssembler { * Assemble all blocks seen so far, in stream order. * @returns one block per seen index, except that max-token truncation drops * tool calls that cannot be executed safely; an open block assembles from - * accumulated deltas (an unknown block type never closed by `block-end` throws). + * its accumulated deltas (an unknown block type never closed by `block-end` throws). */ blocks(): ContentBlock[]; /** Usage from the `usage` chunk; undefined until one arrives. */ diff --git a/docs/module-graph.md b/docs/module-graph.md index 0a93add1ee..762c56443e 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -383,7 +383,6 @@ flowchart TD pkg_token_meter --> pkg_invariants pkg_token_meter --> pkg_llm pkg_token_meter --> pkg_session - pkg_agent --> pkg_brand pkg_agent --> pkg_invariants pkg_agent --> pkg_llm pkg_agent --> pkg_scope @@ -1059,7 +1058,7 @@ flowchart TD | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) | | [`token-meter`](../packages/llm/token-meter) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | +| [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | diff --git a/packages/acp/acp/tests/turns.spec.ts b/packages/acp/acp/tests/turns.spec.ts index a4ae22080e..65305ba672 100644 --- a/packages/acp/acp/tests/turns.spec.ts +++ b/packages/acp/acp/tests/turns.spec.ts @@ -31,28 +31,28 @@ describe('ACP prompt lifecycle', () => { harness = undefined }) - it('maps a max-token turn without losing its committed text', async () => { + it('settles after a max-token turn without losing its committed text', async () => { harness = await makeBridgeHarness({ script: [maxTokensResponse('cut off')] }) const sessionId = await newSession(harness) const result = await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }) - expect(result.stopReason).toBe('max_tokens') + expect(result.stopReason).toBe('end_turn') await vi.waitFor(() => { expect(messageText(harness!)).toBe('cut off') }) }) - it('rejects a failed turn and never publishes its partial chunks', async () => { + it('settles after a failed turn and never publishes its partial chunks', async () => { harness = await makeBridgeHarness({ script: [errorResponse('provider boom')] }) const sessionId = await newSession(harness) await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) - .rejects.toThrow(/turn failed: provider boom/) + .resolves.toEqual({ stopReason: 'end_turn' }) expect(messageText(harness)).toBe('') }) - it('rejects an ordinary plugin failure through the same prompt boundary', async () => { + it('settles after an ordinary plugin failure', async () => { harness = await makeBridgeHarness({ script: [textResponse('must not run')] }) harness.ctx.on('agent/step', () => { throw new Error('plugin pre-step failed') }) const sessionId = await newSession(harness) await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) - .rejects.toThrow(/turn failed: plugin pre-step failed/) + .resolves.toEqual({ stopReason: 'end_turn' }) }) it('settles even when an earlier turn observer throws', async () => { @@ -202,27 +202,27 @@ describe('ACP prompt lifecycle', () => { await vi.waitFor(() => { expect(messageText(harness!)).toBe('recovered') }) }) - it('a failed turn with no retry still rejects, at quiescence', async () => { + it('a failed turn with no retry settles at quiescence', async () => { harness = await makeBridgeHarness({ script: [errorResponse('terminal boom')] }) let offered = 0 harness.ctx.on('agent/request-error', async () => { offered += 1 }) const sessionId = await newSession(harness) await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) - .rejects.toThrow(/turn failed: terminal boom/) + .resolves.toEqual({ stopReason: 'end_turn' }) expect(offered).toBe(1) }) - it('an admission-blocked prompt settles cancelled instead of hanging', async () => { + it('an admission-blocked prompt settles instead of hanging', async () => { harness = await makeBridgeHarness({ script: [] }) harness.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy said no' })) const sessionId = await newSession(harness) await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) - .resolves.toEqual({ stopReason: 'cancelled' }) + .resolves.toEqual({ stopReason: 'end_turn' }) // The blocked prompt opened no turn and streamed nothing. expect(messageText(harness)).toBe('') }) - it('discards and settles a turnless prompt retained by its admission policy', async () => { + it('settles a turnless prompt retained by its admission policy', async () => { harness = await makeBridgeHarness({ script: [] }) harness.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, @@ -233,7 +233,7 @@ describe('ACP prompt lifecycle', () => { const agent = harness.ctx.agents.get(SessionId(sessionId))! await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) - .resolves.toEqual({ stopReason: 'cancelled' }) + .resolves.toEqual({ stopReason: 'end_turn' }) expect(agent.status).toBe('idle') expect(agent.session.events.some(event => event.type === 'turn/start')).toBe(false) }) @@ -244,6 +244,6 @@ describe('ACP prompt lifecycle', () => { const sessionId = await newSession(harness) await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) - .resolves.toEqual({ stopReason: 'cancelled' }) + .resolves.toEqual({ stopReason: 'end_turn' }) }) }) diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml index 3a82c693ca..6b6b160e1f 100644 --- a/packages/core/agent-loop/README.i18n.yaml +++ b/packages/core/agent-loop/README.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 packages/core/agent-loop/README.md -README.md: a1617a1ef871f61157e0d70a06d055168170dced -README.zh.md: 6ba945a41e700331929dabb557802c14256921fb +README.md: c64af9bcea176f4d70b402ad6b84391ae15759d2 +README.zh.md: 6a878a1ffc31380466df99698a905ee0e38e24a4 diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index 9ccde685d0..2d856dd3ee 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -308,7 +308,6 @@ describe('agent loop', () => { send(agent, 'start') await waitForIdle(ctx, agent) - const types = agent.session.events.map(e => e.type) const steering = agent.session.events.find(e => e.type === 'user/message' && JSON.stringify(e.data.content).includes('change of plans')) expect(steering).toBeDefined() diff --git a/packages/core/agent-loop/tests/properties.spec.ts b/packages/core/agent-loop/tests/properties.spec.ts index a75baf9203..c5dec8c142 100644 --- a/packages/core/agent-loop/tests/properties.spec.ts +++ b/packages/core/agent-loop/tests/properties.spec.ts @@ -78,7 +78,7 @@ function userMessageTexts(agent: Agent): string[] { function turnNumbers(agent: Agent): number[] { return agent.session.events .filter(e => e.type === 'turn/start') - .map(e => (e.data as { turn: number }).turn) + .map(e => e.data.turn) } function turnEndNumbers(agent: Agent): number[] { diff --git a/packages/core/agent-loop/tests/request-error.spec.ts b/packages/core/agent-loop/tests/request-error.spec.ts index a7b35bfdbf..96b6bfc045 100644 --- a/packages/core/agent-loop/tests/request-error.spec.ts +++ b/packages/core/agent-loop/tests/request-error.spec.ts @@ -67,10 +67,6 @@ describe('agent/request-error', () => { }) ctx.on('agent/request-error', async (subject, context) => { expect(subject).toBe(agent) - expect(agent.session.events.at(-1)).toMatchObject({ - type: 'step/end', - data: { turn: context.turn, step: context.step }, - }) seen.push(context) return { kind: 'retry' } }) @@ -89,7 +85,7 @@ describe('agent/request-error', () => { code: 'RATE_LIMIT', }, { - turn: 2, + turn: 1, step: 1, code: 'SERVICE_UNAVAILABLE', }, diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json index db0637ecc2..58495e1a63 100644 --- a/packages/core/agent/package.json +++ b/packages/core/agent/package.json @@ -21,7 +21,6 @@ "files": [ "lib/index.js", "lib/invariant.js", - "lib/types/**/*.js", "lib/types/**/*.d.ts", "lib/types/**/*.d.ts.map", "src" diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts index 94e2bd74ce..8a3a568762 100644 --- a/packages/core/session/tests/fork.spec.ts +++ b/packages/core/session/tests/fork.spec.ts @@ -139,17 +139,17 @@ describe('SessionStore.fork', () => { const reasons: TurnEndReason[] = [ { kind: 'completed' }, { kind: 'aborted', reason: { kind: 'user' } }, - { kind: 'error', error: new Error('model failed') }, + { kind: 'error', error: 'model failed' }, { kind: 'aborted', reason: { kind: 'disposed' } }, { kind: 'max-tokens' }, { kind: 'interrupted' }, ] - for (const reason of reasons) { - const source = ctx.sessions.create(SessionId(`parent-${reason.kind}`)) + for (const [index, reason] of reasons.entries()) { + const source = ctx.sessions.create(SessionId(`parent-${index}`)) appendClosedTurn(source, 1, reason.kind, reason) - const child = sessions.fork(source, lastSeq(source), SessionId(`child-${reason.kind}`)) + const child = sessions.fork(source, lastSeq(source), SessionId(`child-${index}`)) expect(inherited(child).at(-1)?.type).toBe('turn/end') expect(child.header.seedLength).toBe(source.events.length) diff --git a/packages/core/session/tests/invariant.spec.ts b/packages/core/session/tests/invariant.spec.ts index bd7440eaa2..3cf089fe5d 100644 --- a/packages/core/session/tests/invariant.spec.ts +++ b/packages/core/session/tests/invariant.spec.ts @@ -326,7 +326,7 @@ describe('session-log invariants', () => { unresolved.append('step/start', { turn: 1, step: 1 }) unresolved.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' }) unresolved.append('step/end', { turn: 1, step: 1 }) - unresolved.append('turn/end', { turn: 1, reason: { kind: 'error', error: new Error('boom') } }) + unresolved.append('turn/end', { turn: 1, reason: { kind: 'error', error: 'boom' } }) }).not.toThrow() }) @@ -384,16 +384,16 @@ describe('session-log invariants', () => { const { ctx } = await setup() // Balanced seed: between turns. expect(() => ctx.sessions.create(SessionId('inherited-between-turns'), { seed: [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } }, ] })).not.toThrow() // Unbalanced seed: inside the open turn, which the relation permits. const open = ctx.sessions.create(SessionId('inherited-inside-open-turn'), { seed: [ - { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, ] }) expect(open.events.map(event => event.type)).toEqual(['turn/start', 'session/end-seed']) // Still open afterwards: the boundary moves no cursor. - expect(() => open.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })) + expect(() => open.append('turn/start', { turn: 2 })) .toThrow(/turn 1 is still open/) expect(() => open.append('turn/end', { turn: 1, reason: { kind: 'completed' } })).not.toThrow() }) diff --git a/packages/examples/cli-demo/src/cli.ts b/packages/examples/cli-demo/src/cli.ts index f40cd03f9a..68eeadae0a 100644 --- a/packages/examples/cli-demo/src/cli.ts +++ b/packages/examples/cli-demo/src/cli.ts @@ -226,7 +226,9 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise options.onEvent(sessionId, event) } catch (error: unknown) { outputError = toError(error) - agent.cancel({ kind: 'user' }) + queueMicrotask(() => { + agent.cancel({ kind: 'user' }) + }) } } diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts index 3a7c29fadb..ff1916fe42 100644 --- a/packages/examples/cli-demo/tests/cli.spec.ts +++ b/packages/examples/cli-demo/tests/cli.spec.ts @@ -354,7 +354,7 @@ describe('runOneShot and executeCli', () => { }) }) - it('counts a failed retry attempt once even though it has no assistant message', async () => { + it('reports usage committed by the recovered assistant message', async () => { const failed = { inputTokens: 11, outputTokens: 2, cacheReadTokens: 3 } const recovered = { inputTokens: 7, outputTokens: 5, reasoningTokens: 4 } const { ctx } = await harness([failedResponse(failed), textResponse('done', recovered)]) @@ -362,9 +362,8 @@ describe('runOneShot and executeCli', () => { const result = await runOneShot(ctx, { task: 'task' }) expect(result.usage).toEqual({ - inputTokens: 18, - outputTokens: 7, - cacheReadTokens: 3, + inputTokens: 7, + outputTokens: 5, reasoningTokens: 4, }) }) @@ -422,7 +421,8 @@ describe('runOneShot and executeCli', () => { const outcome = await result expect(outcome).toMatchObject({ type: 'result', output: 'streamed' }) const events = streamed.map(item => item.event) - expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 3 } }) + expect(events.find(event => event.type === 'turn/start')) + .toMatchObject({ type: 'turn/start', data: { turn: 3 } }) expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 3 } }) expect(streamed.every(item => item.sessionId === agent.session.id)).toBe(true) expect(events.some(event => event.type === 'user/message' @@ -462,7 +462,7 @@ describe('runOneShot and executeCli', () => { const failed = await harness([]) failed.ctx.on('agent/prompt-submit', async () => { throw new Error('admission exploded') }) - await expect(runOneShot(failed.ctx, { task: 'task' })).rejects.toThrow('not admitted') + await expect(runOneShot(failed.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' }) }) it('emits partial data without attributing a turn outcome', async () => { diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts index b9d5018975..0e82805ab3 100644 --- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts @@ -90,7 +90,7 @@ describe('attached updatedAt excludes end-seed', () => { const worked = 1_000_000 const resumed = ctx.sessions.create(sid('resumed-untouched'), { seed: [ - { type: 'turn/start', seq: 0, time: worked, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + { type: 'turn/start', seq: 0, time: worked, data: { turn: 1 } }, { type: 'turn/end', seq: 1, time: worked, data: { turn: 1, reason: { kind: 'completed' } } }, ], meta: { cwd: '/proj', createdAt: 500 }, @@ -106,7 +106,7 @@ describe('attached updatedAt excludes end-seed', () => { expect(summary?.updatedAt).toBe(worked) // Real work appended after end-seed does move it. - resumed.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) + resumed.append('turn/start', { turn: 2 }) const after = await api.sessions.list(request({})) if (!after.result.ok) throw new Error('list failed') const moved = after.result.value.items.find(item => item.sessionId === 'resumed-untouched') diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts index f011fb3e5d..27f936d936 100644 --- a/packages/llm/llm-retry/tests/retry.spec.ts +++ b/packages/llm/llm-retry/tests/retry.spec.ts @@ -144,15 +144,8 @@ function alwaysConfig(backoff: BackoffConfig = {}): AlwaysRetryPolicyConfig { } } -function waitForIdle(ctx: Context, agent: Agent): Promise { - return new Promise((resolve) => { - const dispose = ctx.on('agent/status', (subject, status) => { - if (subject === agent && status === 'idle') { - dispose() - resolve() - } - }) - }) +function waitForIdle(_ctx: Context, agent: Agent): Promise { + return agent.whenIdle() } function waitForRetry(ctx: Context, agent: Agent, retryNumber: number): Promise> { @@ -175,7 +168,7 @@ afterEach(async () => { }) describe('provider-routed retry policy', () => { - it('records the scheduled delay before opening a fresh request attempt', async () => { + it('records the scheduled delay before retrying the request', async () => { vi.useFakeTimers() const adapter = new ScriptedAdapter([ new LlmError('busy', 'RATE_LIMIT', { status: 429 }), @@ -214,7 +207,7 @@ describe('provider-routed retry policy', () => { expect(adapter.requests).toHaveLength(2) expect(agent.session.events.filter(item => item.type === 'step/start').map(item => item.data)) - .toEqual([{ turn: 1, step: 1 }, { turn: 2, step: 1 }]) + .toEqual([{ turn: 1, step: 1 }]) expect(agent.session.deriveMessages().at(-1)).toEqual({ id: expect.any(String) as unknown, role: 'assistant', @@ -251,7 +244,7 @@ describe('provider-routed retry policy', () => { expect(agent.session.events.filter(event => event.type === 'assistant/message').map(event => ({ turn: event.data.turn, step: event.data.step, - }))).toEqual([{ turn: 2, step: 1 }]) + }))).toEqual([{ turn: 1, step: 1 }]) expect(agent.session.deriveMessages().at(-1)).toMatchObject({ role: 'assistant', content: [{ type: 'text', text: 'recovered' }], @@ -291,7 +284,7 @@ describe('provider-routed retry policy', () => { expect(agent.session.events.filter(event => event.type === 'assistant/message').map(event => ({ turn: event.data.turn, step: event.data.step, - }))).toEqual([{ turn: 2, step: 1 }]) + }))).toEqual([{ turn: 1, step: 1 }]) expect(agent.session.events.some(event => event.type === 'tool/call')).toBe(false) expect(toolExecutions).toBe(0) expect(agent.session.deriveMessages().at(-1)).toMatchObject({ @@ -534,9 +527,9 @@ describe('provider-routed retry policy', () => { backoff: { initialDelayMs: 1, maxDelayMs: 1 }, }), }, (ctx) => { - ctx.on('agent/request', async (_agent, turn, _step, _signal, next) => ({ + ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => ({ ...await next(), - provider: turn === 1 ? 'mock' : 'other', + provider: adapter.requests.length === 0 ? 'mock' : 'other', })) })) const agent = context.agentLoop.create(SessionId('retry-provider-budgets'), { diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts index f9de22a120..90c210f7bb 100644 --- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts +++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts @@ -55,14 +55,8 @@ async function harness( return ctx } -function waitForIdle(ctx: Context, agent: Agent): Promise { - return new Promise((resolve) => { - const dispose = ctx.on('agent/status', (subject, status) => { - if (subject !== agent || status !== 'idle') return - dispose() - resolve() - }) - }) +function waitForIdle(_ctx: Context, agent: Agent): Promise { + return agent.whenIdle() } function sendAndWait(ctx: Context, agent: Agent): Promise { @@ -109,7 +103,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { expect(server?.requests).toHaveLength(1) expect(agent.session.events.filter(event => event.type === 'step/start') .map(event => [event.data.turn, event.data.step])) - .toEqual([[1, 1], [2, 1]]) + .toEqual([[1, 1]]) expect(agent.session.events.filter(event => event.type === 'llm/retry').map(event => event.data.failure.code)) .toEqual(['TRANSPORT']) expect(finalAssistantText(agent)).toBe('connected after retry') @@ -141,7 +135,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { )).toHaveLength(failedChunkCount) expect(agent.session.events.filter(event => event.type === 'assistant/message') .map(event => [event.data.turn, event.data.step])) - .toEqual([[2, 1]]) + .toEqual([[1, 1]]) expect(agent.session.events.filter(event => event.type === 'llm/retry').map(event => event.data.failure.code)) .toEqual(['TRANSPORT']) expect(finalAssistantText(agent)).toBe('recovered response') @@ -166,7 +160,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { .toEqual(['EMPTY_RESPONSE']) expect(agent.session.events.filter(event => event.type === 'assistant/message') .map(event => [event.data.turn, event.data.step])) - .toEqual([[2, 1]]) + .toEqual([[1, 1]]) expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } }, @@ -234,7 +228,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { await sendAndWait(context, agent) expect(server.requests).toHaveLength(3) - expect(agent.session.events.filter(event => event.type === 'step/start')).toHaveLength(3) + expect(agent.session.events.filter(event => event.type === 'step/start')).toHaveLength(1) expect(agent.session.events.filter(event => event.type === 'llm/retry')).toHaveLength(2) expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml index 49ff6d7c48..15e79631a9 100644 --- a/packages/llm/llm/README.i18n.yaml +++ b/packages/llm/llm/README.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 packages/llm/llm/README.md -README.md: d343449d1530bf70a3a8c57f883894e29c42d18f -README.zh.md: 4dc4a0ca06378116d05fdb4b9b048738930511fd +README.md: dc7499a6854fe9a45c1297aa2a1a67aea92eaf6f +README.zh.md: 28f281908c2fde708f491194b441a32a8dcba8a5 diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts index af87442744..95142aade2 100644 --- a/packages/llm/llm/tests/service.spec.ts +++ b/packages/llm/llm/tests/service.spec.ts @@ -262,13 +262,16 @@ describe('LlmService', () => { messages: [], })) - expect(chunks.at(-1)).toMatchObject({ + const finish = chunks.at(-1) + expect(finish).toMatchObject({ type: 'finish', reason: { kind: 'error', - failure: { code: 'NO_ADAPTER', message: expect.stringContaining('no adapter registered') }, + failure: { code: 'NO_ADAPTER' }, }, }) + if (finish?.type !== 'finish' || finish.reason.kind !== 'error') throw new Error('expected error finish') + expect(finish.reason.failure.message).toContain('no adapter registered') }) it.each(['done', 'value'] as const)('normalizes a throwing IteratorResult.%s getter', async (field) => { diff --git a/packages/sdk/sdk-client/tests/sdk-client.spec.ts b/packages/sdk/sdk-client/tests/sdk-client.spec.ts index ca2d30b3cc..3717e60357 100644 --- a/packages/sdk/sdk-client/tests/sdk-client.spec.ts +++ b/packages/sdk/sdk-client/tests/sdk-client.spec.ts @@ -175,7 +175,7 @@ describe('DeepSeekHarness', () => { await using harness = new DeepSeekHarness({ launch: fakeLaunch() }) captured = harness const result = await harness.run('scoped') - expect(result.finalResponse).toBe('scoped') + expect(result.finalResponse).toBe('hello from fake runtime') } // After scope exit the runtime is closed: reuse fails loudly. await expect(captured.run('after')).rejects.toThrow(TransportClosedError) diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts index fa2b67db2b..1b720c194d 100644 --- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts +++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts @@ -94,7 +94,7 @@ describe('TelemetryOtel wire', () => { const { ctx, fiber } = await boot(url) const session = ctx.sessions.create(SessionId('wire'), { meta: { cwd: '/tmp/w' } }) session.append('turn/start', { turn: 1 }) - session.append('turn/end', { turn: 1, reason: { kind: 'error', error: new Error('boom') } }) + session.append('turn/end', { turn: 1, reason: { kind: 'error', error: 'boom' } }) await fiber.dispose() expect(captures.length).toBeGreaterThan(0) diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts index 88a42a5191..410ea2d379 100644 --- a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts +++ b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts @@ -126,7 +126,7 @@ describe('TelemetryCoordinator capture', () => { }), }, { surfaceOp: 'append' }) session.append('telemetry-test/opaque', { payload: { nested: [] } }) - session.append('turn/end', { turn: 1, reason: { kind: 'error', error: new Error('boom') } }) + session.append('turn/end', { turn: 1, reason: { kind: 'error', error: 'boom' } }) const severities = backend.ledger().map(r => [r.attributes['event.type'], r.severity]) expect(severities).toEqual([ ['turn/start', 'info'], diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 458f3d57e7..25f149a980 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -452,7 +452,7 @@ describe('goodbye message and /resume', () => { it.each([ [{ kind: 'aborted', reason: { kind: 'user' } }, 'cancelled'], - [{ kind: 'error', error: new Error('failed') }, 'error'], + [{ kind: 'error', error: 'failed' }, 'error'], [{ kind: 'aborted', reason: { kind: 'disposed' } }, 'cancelled'], [{ kind: 'max-tokens' }, 'max tokens'], [{ kind: 'interrupted' }, 'interrupted'], @@ -3687,6 +3687,9 @@ describe('pi-tui chat lifecycle and transcript', () => { result.terminal.send('\r') await tick() expect(result.agent.cancelled).toContainEqual({ kind: 'user' }) + result.agent.status = 'idle' + agentEvents(result.ctx, result.agent).emit('agent/status', 'idle') + await tick() expect(result.exit).toHaveBeenCalledWith(0) const events = await setup() @@ -3714,7 +3717,7 @@ describe('pi-tui chat lifecycle and transcript', () => { events.session.append('turn/start', { turn: 6 }) events.session.append('turn/end', { turn: 6, - reason: { kind: 'error', error: { message: 'structured provider failure', code: 'SERVER' } }, + reason: { kind: 'error', error: 'structured provider failure' }, }) events.session.append('turn/start', { turn: 8 }) events.session.append('turn/end', { @@ -3732,7 +3735,6 @@ describe('pi-tui chat lifecycle and transcript', () => { expect(events.terminal.output).toContain('structured provider failure') expect(events.terminal.output).toContain('output-token limit') expect(events.terminal.output).toContain('previous process ended') - expect(events.terminal.output).toContain('Turn stopped: the agent was disposed') expect(events.terminal.output).toContain('Turn ended: plugin-policy') expect(events.terminal.output).toContain('was disposed') await dispose(events) diff --git a/python/sdk/tests/manual_sdk_agent_smoke.py b/python/sdk/tests/manual_sdk_agent_smoke.py index 751b7fc0bf..ae94f1bb07 100644 --- a/python/sdk/tests/manual_sdk_agent_smoke.py +++ b/python/sdk/tests/manual_sdk_agent_smoke.py @@ -73,9 +73,7 @@ def run_smoke(repo_root: Path, keep_sessions: bool) -> None: "Please reply with a short confirmation and do not call tools.", session_id="sdk-smoke-main", ) - print(f"turn_status={result.status}") print(f"final_response={result.final_response}") - assert result.status == "ok", result assert "configured HTTP model endpoint" in result.final_response assert len(MockCompletionHandler.requests) == 1 request = MockCompletionHandler.requests[0] diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py index 52ceac9f4d..f16f5f27e9 100644 --- a/python/sdk/tests/test_client.py +++ b/python/sdk/tests/test_client.py @@ -39,6 +39,9 @@ for line in sys.stdin: print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"serverInfo": {"name": "fake-runtime"}}}), flush=True) elif method == "session/prompt": params = msg.get("params") or {} + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": params["sessionId"], "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) print(json.dumps({ "jsonrpc": "2.0", "method": "session.event", @@ -57,10 +60,9 @@ for line in sys.stdin: }), flush=True) print(json.dumps({ "jsonrpc": "2.0", - "method": "session.finished", - "params": {"sessionId": params["sessionId"], "status": "ok"}, + "method": "session.status", + "params": {"sessionId": params["sessionId"], "status": "idle"}, }), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -83,9 +85,8 @@ for line in sys.stdin: ) as harness: result = harness.run("say hello", session_id="main") - assert result.status == "ok" assert result.final_response == "hello from runtime" - assert result.events[0]["type"] == "assistant/message" + assert result.events[-1]["type"] == "assistant/message" dumped_env = json.loads(env_dump.read_text()) assert dumped_env["DEEPSEEK_API_KEY"] == "env-key" assert dumped_env["DEEPSEEK_BASE_URL"] == "http://127.0.0.1:4321" @@ -113,9 +114,11 @@ for line in sys.stdin: if method == "initialize": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"serverInfo": {"name": "fake-runtime"}}}), flush=True) elif method == "session/prompt": + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": "main", "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": "main", "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "subagent.started", "params": {"parentSessionId": "main", "childSessionId": "child"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": "main", "status": "ok"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": "main", "status": "idle"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -133,8 +136,7 @@ for line in sys.stdin: on_notification=lambda notification: seen.append(notification.method), ) - assert result.status == "ok" - assert seen == ["subagent.started", "session.finished"] + assert seen == ["session.event", "session.status", "subagent.started", "session.status"] def test_relative_cwd_is_absolute_in_process_environment_and_wire( @@ -189,10 +191,12 @@ for line in sys.stdin: if method == "initialize": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"serverInfo": {"name": "fake-runtime"}}}), flush=True) elif method == "session/prompt": + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": "main", "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": "main", "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "subagent.started", "params": {"parentSessionId": "main", "childSessionId": "child"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "subagent.finished", "params": {"parentSessionId": "main", "childSessionId": "child", "status": "ok", "stopReason": "completed"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": "main", "status": "ok"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": "main", "status": "idle"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -205,11 +209,12 @@ for line in sys.stdin: ) as harness: result = harness.run("spawn a helper", session_id="main") - assert result.status == "ok" assert [notification.method for notification in result.notifications] == [ + "session.event", + "session.status", "subagent.started", "subagent.finished", - "session.finished", + "session.status", ] @@ -229,6 +234,9 @@ for line in sys.stdin: print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"serverInfo": {"name": "fake-runtime"}}}), flush=True) elif method == "session/prompt": root = (msg.get("params") or {})["sessionId"] + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": root, "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": root, "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "subagent.started", "params": {"parentSessionId": root, "childSessionId": "child"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": "child", "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "child response"}]}}}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "subagent.started", "params": {"parentSessionId": "child", "childSessionId": "grandchild"}}), flush=True) @@ -236,8 +244,7 @@ for line in sys.stdin: print(json.dumps({"jsonrpc": "2.0", "method": "subagent.finished", "params": {"parentSessionId": "child", "childSessionId": "grandchild", "status": "ok"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "subagent.finished", "params": {"parentSessionId": root, "childSessionId": "child", "status": "ok"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": root, "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "root response"}]}}}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": root, "status": "ok"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": root, "status": "idle"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -256,10 +263,11 @@ for line in sys.stdin: ) assert harness.client._notifications.qsize() == 0 - assert result.status == "ok" assert result.final_response == "root response" - assert [event["data"]["content"][0]["text"] for event in result.events] == ["root response"] + assert [event["data"]["content"][0]["text"] for event in result.events if event["type"] == "assistant/message"] == ["root response"] assert [notification.method for notification in result.notifications] == [ + "session.event", + "session.status", "subagent.started", "session.event", "subagent.started", @@ -267,7 +275,7 @@ for line in sys.stdin: "subagent.finished", "subagent.finished", "session.event", - "session.finished", + "session.status", ] assert seen == [notification.method for notification in result.notifications] @@ -287,10 +295,12 @@ for line in sys.stdin: elif method == "session/prompt": params = msg.get("params") or {} print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": "other", "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "wrong session"}]}}}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": "other", "status": "ok"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": "other", "status": "idle"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": params["sessionId"], "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "right session"}]}}}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": params["sessionId"], "status": "ok"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": params["sessionId"], "status": "idle"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -303,9 +313,8 @@ for line in sys.stdin: ) as harness: result = harness.run("stay in your lane", session_id="main") - assert result.status == "ok" assert result.final_response == "right session" - assert [notification.payload.get("sessionId") for notification in result.notifications] == ["main", "main"] + assert [notification.payload.get("sessionId") for notification in result.notifications] == ["main"] * 4 def test_high_level_session_run_does_not_accumulate_global_notifications(tmp_path: Path) -> None: @@ -322,9 +331,11 @@ for line in sys.stdin: print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"serverInfo": {"name": "fake-runtime"}}}), flush=True) elif method == "session/prompt": params = msg.get("params") or {} + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": params["sessionId"], "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "ok"}]}}}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": params["sessionId"], "status": "ok"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": params["sessionId"], "status": "idle"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -333,11 +344,10 @@ for line in sys.stdin: with DeepSeekHarness(launch_args_override=(sys.executable, str(script)), cwd=str(tmp_path)) as harness: result = harness.run("one turn", session_id="main") - assert result.status == "ok" assert harness.client._notifications.qsize() == 0 -def test_session_run_waits_for_late_finished_without_replaying_stale_notifications(tmp_path: Path) -> None: +def test_session_run_waits_for_late_idle_without_replaying_stale_notifications(tmp_path: Path) -> None: script = tmp_path / "fake_runtime.py" script.write_text( """ @@ -355,15 +365,17 @@ for line in sys.stdin: turn += 1 params = msg.get("params") or {} session_id = params["sessionId"] + message_id = f"message-{turn}" + print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": session_id, "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": message_id}]}}}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": session_id, "status": "running"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": message_id}}), flush=True) if turn == 1: print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": session_id, "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "first"}]}}}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": session_id, "status": "ok"}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": session_id, "status": "idle"}}), flush=True) else: - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) time.sleep(0.05) print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": session_id, "event": {"type": "assistant/message", "data": {"content": [{"type": "text", "text": "second"}]}}}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "method": "session.finished", "params": {"sessionId": session_id, "status": "ok"}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": session_id, "status": "idle"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -376,7 +388,7 @@ for line in sys.stdin: assert first.final_response == "first" assert second.final_response == "second" - assert [notification.payload.get("sessionId") for notification in second.notifications] == ["main", "main"] + assert [notification.payload.get("sessionId") for notification in second.notifications] == ["main"] * 4 def test_client_starts_subprocess_sends_requests_and_routes_notifications(tmp_path: Path) -> None: @@ -394,7 +406,7 @@ for line in sys.stdin: elif method == "session/prompt": params = msg.get("params") or {} print(json.dumps({"jsonrpc": "2.0", "method": "llm/request", "params": {"requestId": "req-1", "sessionId": params["sessionId"], "model": "dsagent", "messages": []}}), flush=True) - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break @@ -531,7 +543,7 @@ for line in sys.stdin: elif method in {"emit-first", "emit-second"}: print(json.dumps({"jsonrpc": "2.0", "method": "tick", "params": {"source": method}}), flush=True) elif method == "session/prompt": - print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"accepted": True}}), flush=True) + print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True) elif method == "shutdown": print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True) break From a43c6da1b99850d88a1a3f06df23cff292328f65 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 17:52:03 +0800 Subject: [PATCH 021/689] fix(llm-retry): validate retries within their request step --- packages/llm/llm-retry/src/history.ts | 19 ++-- packages/llm/llm-retry/src/invariant.ts | 59 ++++------ .../llm/llm-retry/tests/invariant.spec.ts | 105 +++++++----------- .../llm/llm-retry/tests/persistence.spec.ts | 2 +- packages/llm/llm-retry/tests/retry.spec.ts | 17 ++- .../tests/transport-recovery.spec.ts | 15 ++- 6 files changed, 92 insertions(+), 125 deletions(-) diff --git a/packages/llm/llm-retry/src/history.ts b/packages/llm/llm-retry/src/history.ts index a0de5840af..4dd352e8c8 100644 --- a/packages/llm/llm-retry/src/history.ts +++ b/packages/llm/llm-retry/src/history.ts @@ -1,28 +1,29 @@ -/** Durable request-route lookup for one closed model step. @module @deepseek-ai/dsh-llm-retry/history */ +/** Durable request-route lookup for one open model step. @module @deepseek-ai/dsh-llm-retry/history */ import type { SessionEvent } from '@deepseek-ai/dsh-session' /** - * Find the provider in force when one step closed, excluding later recovery mutations. + * Find the provider in force for one currently open step. * Request headers remain effective across turn boundaries until a newer full * snapshot changes them; every provider change requires a newer full snapshot. - * @param events - session events containing the closed step. + * @param events - session events ending inside the open step. * @param turn - turn that owns the failed step. * @param step - failed step whose provider is required. - * @returns the provider from the request header in force at that step boundary. + * @returns the provider from the request header in force for the step. */ -export function providerForClosedStep( +export function providerForOpenStep( events: readonly SessionEvent[], turn: number, step: number, ): string | undefined { - const stepEndIndex = events.findLastIndex(event => - event.type === 'step/end' + const stepStartIndex = events.findLastIndex(event => + event.type === 'step/start' && event.data.turn === turn && event.data.step === step, ) - if (stepEndIndex < 0) return undefined - for (let index = stepEndIndex; index >= 0; index -= 1) { + if (stepStartIndex < 0 || events.slice(stepStartIndex + 1).some(event => + event.type === 'step/end' || event.type === 'turn/end')) return undefined + for (let index = events.length - 1; index >= 0; index -= 1) { // The loop bounds prove this indexed read exists. // oxlint-disable-next-line typescript/no-non-null-assertion const event = events[index]! diff --git a/packages/llm/llm-retry/src/invariant.ts b/packages/llm/llm-retry/src/invariant.ts index 3b154f046c..d324c012f2 100644 --- a/packages/llm/llm-retry/src/invariant.ts +++ b/packages/llm/llm-retry/src/invariant.ts @@ -5,7 +5,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' import type { LlmFailure } from '@deepseek-ai/dsh-llm' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' -import { providerForClosedStep } from './history.ts' +import { providerForOpenStep } from './history.ts' import type {} from './index.ts' const PACKAGE_NAME = '@deepseek-ai/dsh-llm-retry' @@ -41,7 +41,7 @@ function validateFailure(value: unknown, fail: InvariantFailure): asserts value } } -/** Validate one retry record against the open turn and most recently closed step. */ +/** Validate one retry record against the currently open request step. */ function validateRetry( history: readonly SessionEvent[], event: SessionEvent<'llm/retry'>, @@ -78,51 +78,34 @@ function validateRetry( fail(`llm/retry delayMs must be a finite number within 0..${MAX_TIMER_DELAY_MS}`) } - const currentTurnEvents: SessionEvent[] = [] - let openTurn: number | undefined - for (const prior of history.slice().reverse()) { - if (prior.type === 'turn/end') fail('llm/retry must be appended inside an open turn') - if (prior.type === 'turn/start') { - openTurn = prior.data.turn - break - } - currentTurnEvents.push(prior) + const turnBoundary = history.findLast(prior => + prior.type === 'turn/start' || prior.type === 'turn/end') + if (turnBoundary?.type !== 'turn/start') { + fail('llm/retry must be appended inside an open turn') } - if (openTurn === undefined) fail('llm/retry must be appended inside an open turn') - if (turn !== openTurn) { - fail(`llm/retry names turn ${turn}, but the open turn is ${openTurn}`) + if (turn !== turnBoundary.data.turn) { + fail(`llm/retry names turn ${turn}, but the open turn is ${turnBoundary.data.turn}`) } - let closedStep: number | undefined - for (const prior of currentTurnEvents) { - if (prior.type === 'step/start') { - fail(`llm/retry must follow step/end, but step ${prior.data.step} is still open`) - } - if (prior.type === 'step/end') { - closedStep = prior.data.step - break - } + const stepBoundary = history.findLast(prior => + prior.type === 'step/start' || prior.type === 'step/end') + if (stepBoundary?.type !== 'step/start') { + fail('llm/retry must be appended inside an open step') } - if (closedStep === undefined || step !== closedStep) { - fail(`llm/retry names step ${step}, but the latest closed step is ${String(closedStep)}`) + if (step !== stepBoundary.data.step || turn !== stepBoundary.data.turn) { + fail(`llm/retry names turn ${turn}/step ${step}, but the open step is ${stepBoundary.data.turn}/${stepBoundary.data.step}`) } - const routedProvider = providerForClosedStep(history, turn, step) + const routedProvider = providerForOpenStep(history, turn, step) if (routedProvider !== provider) { fail(`llm/retry provider ${provider} does not match the failed request provider ${String(routedProvider)}`) } - const chainStart = history.findLastIndex( - prior => prior.type === 'turn/start' && prior.data.turn === turn, - ) - const chain = history.slice(Math.max(chainStart, 0)) - const lastSuccess = chain.findLastIndex(prior => prior.type === 'assistant/message') - const chainRetries = chain.slice(lastSuccess + 1) - .filter((prior): prior is SessionEvent<'llm/retry'> => prior.type === 'llm/retry') - if (chainRetries.some(prior => prior.data.turn === turn && prior.data.step === step)) { - fail(`llm/retry duplicates the retry record for turn ${turn}/step ${step}`) - } - const priorPolicyRetry = chainRetries.findLast(prior => - prior.data.provider === provider && prior.data.policyKey === policyKey) + const priorPolicyRetry = history.findLast((prior): prior is SessionEvent<'llm/retry'> => + prior.type === 'llm/retry' + && prior.data.turn === turn + && prior.data.step === step + && prior.data.provider === provider + && prior.data.policyKey === policyKey) const expectedRetry = (priorPolicyRetry?.data.retry ?? 0) + 1 if (retry !== expectedRetry) { fail(`llm/retry retry ${retry} must equal provider policy retry ${expectedRetry}`) diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts index 1e04d85b5e..09dc0bffe7 100644 --- a/packages/llm/llm-retry/tests/invariant.spec.ts +++ b/packages/llm/llm-retry/tests/invariant.spec.ts @@ -1,11 +1,11 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session' -import { createUserMessage, ProviderRequestId , createMessage } from '@deepseek-ai/dsh-llm' +import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' import InvariantService from '@deepseek-ai/dsh-invariants' import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant' -import { providerForClosedStep } from '../src/history.ts' +import { providerForOpenStep } from '../src/history.ts' async function setup(): Promise { const ctx = new Context() @@ -15,7 +15,7 @@ async function setup(): Promise { return ctx } -function closeStep(ctx: Context, id: string, turn = 1, step = 1) { +function openStep(ctx: Context, id: string, turn = 1, step = 1) { const session = ctx.sessions.create(SessionId(id)) session.append('turn/start', { turn }) session.append('step/start', { turn, step }) @@ -23,7 +23,6 @@ function closeStep(ctx: Context, id: string, turn = 1, step = 1) { header: { config: { provider: 'mock', model: 'mock' } }, reason: 'initial', }) - session.append('step/end', { turn, step }) return session } @@ -34,7 +33,6 @@ function appendRetryTurn(session: Session, turn: number) { header: { config: { provider: 'mock', model: 'mock' } }, reason: 'initial', }) - session.append('step/end', { turn, step: 1 }) session.append('llm/retry', { turn, step: 1, ...normal }) } @@ -58,28 +56,24 @@ const always = { } describe('llm-retry invariants', () => { - it('has no provider without the requested closed step or a route marker', () => { - expect(providerForClosedStep([], 1, 1)).toBeUndefined() - expect(providerForClosedStep([{ - type: 'step/end', + it('has no provider without the requested open step or a route marker', () => { + expect(providerForOpenStep([], 1, 1)).toBeUndefined() + expect(providerForOpenStep([{ + type: 'step/start', data: { turn: 1, step: 1 }, }] as never, 1, 1)).toBeUndefined() }) - it('accepts bounded and unbounded records after successive closed steps', async () => { + it('accepts successive bounded and unbounded records inside their open steps', async () => { const ctx = await setup() - const session = closeStep(ctx, 'retry-invariant-valid') + const session = openStep(ctx, 'retry-invariant-valid') expect(() => { session.append('llm/retry', { turn: 1, step: 1, ...normal }) - session.append('turn/end', { turn: 1, reason: { kind: 'error', error: failure } }) - session.append('turn/start', { turn: 2 }) - session.append('step/start', { turn: 2, step: 1 }) - session.append('step/end', { turn: 2, step: 1 }) session.append('llm/retry', { - turn: 2, step: 1, ...normal, retry: 2, delayMs: 0, + turn: 1, step: 1, ...normal, retry: 2, delayMs: 0, }) - const unbounded = closeStep(ctx, 'retry-invariant-always') + const unbounded = openStep(ctx, 'retry-invariant-always') unbounded.append('llm/retry', { turn: 1, step: 1, ...always }) }).not.toThrow() expect(() => { ctx.emit('tools/change') }).not.toThrow() @@ -87,7 +81,7 @@ describe('llm-retry invariants', () => { it('validates the complete durable failure payload', async () => { const ctx = await setup() - const complete = closeStep(ctx, 'retry-invariant-complete-failure') + const complete = openStep(ctx, 'retry-invariant-complete-failure') expect(() => { complete.append('llm/retry', { turn: 1, @@ -126,7 +120,7 @@ describe('llm-retry invariants', () => { ['request-id-empty', { message: 'failed', code: 'RATE_LIMIT', requestId: '' }, /failure\.requestId/], ] for (const [name, invalidFailure, message] of invalidFailures) { - const session = closeStep(ctx, `retry-invariant-failure-${name}`) + const session = openStep(ctx, `retry-invariant-failure-${name}`) expect(() => { session.append('llm/retry', { turn: 1, step: 1, ...always, failure: invalidFailure, @@ -150,43 +144,43 @@ describe('llm-retry invariants', () => { ['delay-type', { ...normal, delayMs: '1' }, /delayMs/], ])('rejects invalid retry data: %s', async (name, data, message) => { const ctx = await setup() - const session = closeStep(ctx, `retry-invariant-${name}`) + const session = openStep(ctx, `retry-invariant-${name}`) expect(() => { session.append('llm/retry', { turn: 1, step: 1, ...data } as never) }).toThrow(message) }) - it('rejects records outside the latest closed step of an open turn', async () => { + it('rejects records outside the currently open turn and step', async () => { const ctx = await setup() const absent = ctx.sessions.create(SessionId('retry-invariant-no-turn')) expect(() => { absent.append('llm/retry', { turn: 1, step: 1, ...normal }) }).toThrow(/inside an open turn/) - const wrongTurn = closeStep(ctx, 'retry-invariant-wrong-turn') + const wrongTurn = openStep(ctx, 'retry-invariant-wrong-turn') expect(() => { wrongTurn.append('llm/retry', { turn: 2, step: 1, ...normal }) }).toThrow(/open turn is 1/) - const openStep = ctx.sessions.create(SessionId('retry-invariant-open-step')) - openStep.append('turn/start', { turn: 1 }) - openStep.append('step/start', { turn: 1, step: 1 }) + const closedStep = openStep(ctx, 'retry-invariant-closed-step') + closedStep.append('step/end', { turn: 1, step: 1 }) expect(() => { - openStep.append('llm/retry', { turn: 1, step: 1, ...normal }) - }).toThrow(/step 1 is still open/) + closedStep.append('llm/retry', { turn: 1, step: 1, ...normal }) + }).toThrow(/inside an open step/) const noStep = ctx.sessions.create(SessionId('retry-invariant-no-step')) noStep.append('turn/start', { turn: 1 }) expect(() => { noStep.append('llm/retry', { turn: 1, step: 1, ...normal }) - }).toThrow(/latest closed step is undefined/) + }).toThrow(/inside an open step/) - const wrongStep = closeStep(ctx, 'retry-invariant-wrong-step') + const wrongStep = openStep(ctx, 'retry-invariant-wrong-step') expect(() => { wrongStep.append('llm/retry', { turn: 1, step: 2, ...normal }) - }).toThrow(/latest closed step is 1/) + }).toThrow(/open step is 1\/1/) - const closedTurn = closeStep(ctx, 'retry-invariant-closed-turn') + const closedTurn = openStep(ctx, 'retry-invariant-closed-turn') + closedTurn.append('step/end', { turn: 1, step: 1 }) closedTurn.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: { kind: 'user' } }, @@ -196,52 +190,31 @@ describe('llm-retry invariants', () => { }).toThrow(/inside an open turn/) }) - it('rejects a second retry record for the same step', async () => { + it('accepts successive retries in one step and rejects skipped numbering', async () => { const ctx = await setup() - const session = closeStep(ctx, 'retry-invariant-duplicate') + const session = openStep(ctx, 'retry-invariant-number-sequence') session.append('llm/retry', { turn: 1, step: 1, ...normal }) + session.append('llm/retry', { turn: 1, step: 1, ...normal, retry: 2 }) expect(() => { - session.append('llm/retry', { turn: 1, step: 1, ...normal, retry: 2 }) - }).toThrow(/duplicates the retry record/) + session.append('llm/retry', { turn: 1, step: 1, ...always, retry: 2 }) + }).toThrow(/must equal provider policy retry 1/) }) - it('binds retry numbering to the provider policy and resets it after success', async () => { + it('binds retry numbering to the provider policy and resets it for a new step', async () => { const ctx = await setup() - const mismatch = closeStep(ctx, 'retry-invariant-numbering') + const mismatch = openStep(ctx, 'retry-invariant-numbering') mismatch.append('llm/retry', { turn: 1, step: 1, ...normal }) - mismatch.append('turn/end', { turn: 1, reason: { kind: 'error', error: failure } }) - mismatch.append('turn/start', { turn: 2 }) - mismatch.append('step/start', { turn: 2, step: 1 }) - mismatch.append('step/end', { turn: 2, step: 1 }) expect(() => { - mismatch.append('llm/retry', { turn: 2, step: 1, ...normal, retry: 1 }) + mismatch.append('llm/retry', { turn: 1, step: 1, ...normal, retry: 1 }) }).toThrow(/must equal provider policy retry 2/) - const reset = closeStep(ctx, 'retry-invariant-reset') + const reset = openStep(ctx, 'retry-invariant-reset') reset.append('llm/retry', { turn: 1, step: 1, ...normal }) - reset.append('turn/end', { turn: 1, reason: { kind: 'error', error: failure } }) - reset.append('turn/start', { turn: 2 }) - reset.append('step/start', { turn: 2, step: 1 }) - reset.append('assistant/message', { - turn: 2, - step: 1, - message: createMessage({ - role: 'assistant', - content: [{ type: 'text', text: 'success' }], - source: { - kind: 'model', - ...{ provider: 'mock', model: 'mock' }, - }, - }), - }, { surfaceOp: 'append' }) - reset.append('step/end', { turn: 2, step: 1 }) - reset.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) - reset.append('turn/start', { turn: 3 }) - reset.append('step/start', { turn: 3, step: 1 }) - reset.append('step/end', { turn: 3, step: 1 }) + reset.append('step/end', { turn: 1, step: 1 }) + reset.append('step/start', { turn: 1, step: 2 }) expect(() => { - reset.append('llm/retry', { turn: 3, step: 1, ...normal }) + reset.append('llm/retry', { turn: 1, step: 2, ...normal }) }).not.toThrow() }) @@ -277,7 +250,7 @@ describe('llm-retry invariants', () => { it('rejects a provider that does not match the failed request route', async () => { const ctx = await setup() - const session = closeStep(ctx, 'retry-invariant-provider') + const session = openStep(ctx, 'retry-invariant-provider') expect(() => { session.append('llm/retry', { turn: 1, step: 1, ...always, provider: 'other' }) }).toThrow(/does not match the failed request provider mock/) @@ -287,7 +260,7 @@ describe('llm-retry invariants', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('retry-invariant-late')) - session.append('step/end', { turn: 1, step: 1 }) + session.append('step/start', { turn: 1, step: 1 }) session.append('llm/retry', { turn: 1, step: 1, ...normal }) await ctx.plugin(InvariantService) await expect(ctx.plugin(RetryInvariant)).rejects.toThrow(/inside an open turn/) diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts index 433f9d9bf5..d8a21a5c08 100644 --- a/packages/llm/llm-retry/tests/persistence.spec.ts +++ b/packages/llm/llm-retry/tests/persistence.spec.ts @@ -38,7 +38,6 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind) header: { config: { provider: 'mock', model: 'mock' } }, reason: 'initial', }) - session.append('step/end', { turn: 1, step: 1 }) const event = session.append('llm/retry', { turn: 1, step: 1, @@ -49,6 +48,7 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind) delayMs: 750, failure: { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }, }) + session.append('step/end', { turn: 1, step: 1 }) session.append('turn/end', { turn: 1, reason: { diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts index 27f936d936..c433f9b20f 100644 --- a/packages/llm/llm-retry/tests/retry.spec.ts +++ b/packages/llm/llm-retry/tests/retry.spec.ts @@ -277,14 +277,21 @@ describe('provider-routed retry policy', () => { await vi.advanceTimersByTimeAsync(500) await idle + const retryEvent = agent.session.events.find(event => event.type === 'llm/retry') const failedChunks = agent.session.events.filter(event => - event.type === 'assistant/chunk' && event.data.turn === 1 && event.data.step === 1, + event.type === 'assistant/chunk' + && retryEvent !== undefined + && event.seq < retryEvent.seq, ) - expect(failedChunks).toHaveLength(6) - expect(agent.session.events.filter(event => event.type === 'assistant/message').map(event => ({ + expect(failedChunks).toHaveLength(7) + const assistantMessages = agent.session.events.filter(event => event.type === 'assistant/message') + expect(assistantMessages.map(event => ({ turn: event.data.turn, step: event.data.step, }))).toEqual([{ turn: 1, step: 1 }]) + expect(failedChunks.every(event => + !assistantMessages[0]?.sourceEventSeqs?.includes(event.seq), + )).toBe(true) expect(agent.session.events.some(event => event.type === 'tool/call')).toBe(false) expect(toolExecutions).toBe(0) expect(agent.session.deriveMessages().at(-1)).toMatchObject({ @@ -325,7 +332,7 @@ describe('provider-routed retry policy', () => { expect(agent.session.events.filter(event => event.type === 'llm/retry')).toHaveLength(2) expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', - data: { reason: { kind: 'error', failure: { message: 'busy three', code: 'SERVER' } } }, + data: { reason: { kind: 'error', error: { message: 'busy three', code: 'SERVER' } } }, }) }) @@ -438,7 +445,7 @@ describe('provider-routed retry policy', () => { expect(agent.session.events.some(event => event.type === 'llm/retry')).toBe(false) expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', - data: { reason: { kind: 'error', failure: { code: 'NO_ADAPTER' } } }, + data: { reason: { kind: 'error', error: { code: 'NO_ADAPTER' } } }, }) }) diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts index 90c210f7bb..0bbd684aaa 100644 --- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts +++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts @@ -110,8 +110,8 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { }) it.each([ - ['stream_disconnect', 0] as const, - ['partial_disconnect', 2] as const, + ['stream_disconnect', 1] as const, + ['partial_disconnect', 3] as const, ])('retries %s without committing failed chunks', async (behavior, failedChunkCount) => { const server = await start([behavior, 'success'], { apiKey: 'mock-key', @@ -130,8 +130,11 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { expect(server.requests).toHaveLength(2) expect(server.requests[0]?.body).toEqual(server.requests[1]?.body) + const retryEvent = agent.session.events.find(event => event.type === 'llm/retry') expect(agent.session.events.filter(event => - event.type === 'assistant/chunk' && event.data.turn === 1, + event.type === 'assistant/chunk' + && retryEvent !== undefined + && event.seq < retryEvent.seq, )).toHaveLength(failedChunkCount) expect(agent.session.events.filter(event => event.type === 'assistant/message') .map(event => [event.data.turn, event.data.step])) @@ -185,12 +188,12 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { expect(server.requests).toHaveLength(1) expect(agent.session.events.filter(event => event.type === 'assistant/chunk' && event.data.turn === 1, - )).toHaveLength(2) + )).toHaveLength(3) expect(agent.session.events.some(event => event.type === 'assistant/message')).toBe(false) expect(agent.session.events.some(event => event.type === 'llm/retry')).toBe(false) expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', - data: { reason: { kind: 'error', failure: { code: 'STREAM_CLOSED' } } }, + data: { reason: { kind: 'error', error: { code: 'STREAM_CLOSED' } } }, }) }) @@ -232,7 +235,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { expect(agent.session.events.filter(event => event.type === 'llm/retry')).toHaveLength(2) expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', - data: { reason: { kind: 'error', failure: { code: 'TRANSPORT' } } }, + data: { reason: { kind: 'error', error: { code: 'TRANSPORT' } } }, }) }) }) From 83ae7046f2fc9e8ea953f392feffeb5fefa0391e Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 30 Jul 2026 17:54:48 +0800 Subject: [PATCH 022/689] fix(install): preserve pnpm version errors --- scripts/install.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/install.sh b/scripts/install.sh index 41d5c749c1..e4e8c175da 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -186,7 +186,7 @@ fi # pnpm is the only dependency we offer to install for you. if command -v pnpm >/dev/null 2>&1; then - info "pnpm $(pnpm --version 2>/dev/null) ... ok" + info "pnpm $(pnpm --version) ... ok" else warn "pnpm is not installed." if confirm "Install pnpm now?" Y; then From 97111cb5b32a3d7975ddad7c5282fcf37a5026d4 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 17:56:02 +0800 Subject: [PATCH 023/689] fix: align lifecycle consumers with durable inbox semantics --- packages/core/agent-loop/tests/agent.spec.ts | 112 +--------------- .../agent-loop/tests/interception.spec.ts | 123 +++++++----------- .../tests/request-reconstruction.spec.ts | 38 ++---- packages/core/agent-loop/tests/resume.spec.ts | 12 +- .../core/agent-loop/tests/tool-calls.spec.ts | 13 +- packages/goal/goal-session/src/index.ts | 37 ++++-- .../goal-session/tests/goal-session.spec.ts | 80 ++++-------- 7 files changed, 124 insertions(+), 291 deletions(-) diff --git a/packages/core/agent-loop/tests/agent.spec.ts b/packages/core/agent-loop/tests/agent.spec.ts index 295117d7d3..589f993c63 100644 --- a/packages/core/agent-loop/tests/agent.spec.ts +++ b/packages/core/agent-loop/tests/agent.spec.ts @@ -26,50 +26,17 @@ function send(agent: Agent, text: string): void { } describe('Agent', () => { - it('does not echo caller-owned message identities from delivery methods', async () => { - const adapter = new MockAdapter([ - textResponse('one'), - textResponse('two'), - textResponse('three'), - ]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const message = (text: string) => createUserMessage({ - content: [{ type: 'text' as const, text }], - source: { kind: 'user' as const }, - }) - const call = (method: 'send' | 'inject' | 'followup' | 'steer', args: unknown[]): unknown => { - const implementation: unknown = Reflect.get(agent, method) - if (typeof implementation !== 'function') throw new Error(`missing Agent.${method}`) - return Reflect.apply(implementation, agent, args) - } - - expect(call('send', [message('quiet'), { - target: 'next-turn', - wakeup: false, - }])).toBeUndefined() - expect(call('inject', [message('context')])).toBeUndefined() - expect(call('followup', [message('followup')])).toBeUndefined() - expect(call('steer', [message('steering')])).toBeUndefined() - await agent.whenIdle() - - expect(adapter.requests).toHaveLength(3) - }) - - it('idle inject() appends context without opening a turn or requesting a flush', async () => { + it('idle inject() durably stages context without opening a turn', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - let flushes = 0 - ctx.on('session/flush', () => { flushes += 1 }) agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'p' } })) - expect(agent.session.events.map(event => event.type)).toEqual(['user/message']) + expect(agent.session.events.map(event => event.type)).toEqual(['agent/inbox/spliced']) expect(agent.status).toBe('idle') expect(adapter.requests).toHaveLength(0) await agent.whenIdle() - expect(flushes).toBe(0) }) it('inject() preserves an explicitly empty plugin source', async () => { @@ -79,7 +46,7 @@ describe('Agent', () => { agent.inject(createUserMessage({ content: [{ type: 'text', text: 'empty plugin source' }], source: { kind: 'plugin', plugin: '' } })) const injected = agent.session.events.at(-1) - expect(injected?.type === 'user/message' && injected.data.source) + expect(injected?.type === 'agent/inbox/spliced' && injected.data.inserted[0]?.source) .toEqual({ kind: 'plugin', plugin: '' }) }) @@ -119,79 +86,6 @@ describe('Agent', () => { expect(statuses).toEqual(['running', 'idle']) }) - it('awaits the turn-end checkpoint before claiming the next queued turn', async () => { - const adapter = new MockAdapter([textResponse('one'), textResponse('two')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const firstFlush = Promise.withResolvers() - const flushedTurns: number[] = [] - ctx.on('session/flush', async (session) => { - const turnEnd = session.events.findLast(event => event.type === 'turn/end') - flushedTurns.push(turnEnd?.data.turn ?? 0) - if (turnEnd?.data.turn === 1) await firstFlush.promise - }) - - send(agent, 'first') - send(agent, 'second') - - await vi.waitFor(() => { expect(flushedTurns).toEqual([1]) }) - expect(adapter.requests).toHaveLength(1) - firstFlush.resolve(undefined) - await agent.whenIdle() - - expect(adapter.requests).toHaveLength(2) - expect(flushedTurns).toEqual([1, 2]) - }) - - it('keeps whenIdle pending through the final turn checkpoint', async () => { - const ctx = await harness(new MockAdapter([textResponse('done')])) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const flush = Promise.withResolvers() - let flushStarted = false - ctx.on('session/flush', () => { - flushStarted = true - return flush.promise - }) - - send(agent, 'go') - await vi.waitFor(() => { expect(flushStarted).toBe(true) }) - let idleSettled = false - const idle = agent.whenIdle().then(() => { idleSettled = true }) - await Promise.resolve() - expect(idleSettled).toBe(false) - - flush.resolve(undefined) - await idle - expect(agent.status).toBe('idle') - }) - - it('reports a rejected turn-end checkpoint and continues queued work', async () => { - const adapter = new MockAdapter([textResponse('one'), textResponse('two')]) - const ctx = await harness(adapter) - const warning = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const failure = new Error('disk unavailable') - const errors: { turn: number; step: number; error: unknown }[] = [] - let flushes = 0 - ctx.on('session/flush', () => { - flushes += 1 - if (flushes === 1) throw failure - }) - ctx.on('agent/error', (subject, turn, step, error) => { - if (subject === agent) errors.push({ turn, step, error }) - }) - - send(agent, 'first') - send(agent, 'second') - await agent.whenIdle() - - expect(adapter.requests).toHaveLength(2) - expect(flushes).toBe(2) - expect(errors).toEqual([{ turn: 1, step: 1, error: failure }]) - expect(warning).toHaveBeenCalledWith(expect.stringContaining('session/flush failed at turn 1: disk unavailable')) - warning.mockRestore() - }) - it('whenIdle() resolves immediately without active work', async () => { const ctx = await harness(new MockAdapter([textResponse('ok')])) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index 832181adb5..6998ccb7f4 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -119,7 +119,7 @@ describe('agent/prompt-submit', () => { await idle expect(observed).toHaveLength(1) - expect(observed[0]).toBe(input) + expect(observed[0]).not.toBe(input) expect(observed[0]).toMatchObject({ content: [{ type: 'text', text: 'accepted text' }], source: { kind: 'plugin', plugin: 'accepted source' }, @@ -237,7 +237,10 @@ describe('agent/prompt-submit', () => { const entered = Promise.withResolvers() const decision = Promise.withResolvers() let claimed: UserMessage[] = [] + let firstAdmission = true ctx.on('agent/prompt-submit', async (_agent, messages) => { + if (!firstAdmission) return { kind: 'allow', messages } + firstAdmission = false claimed = messages entered.resolve(undefined) return decision.promise @@ -271,21 +274,24 @@ describe('agent/prompt-submit', () => { 'turn/start', 'user/message', 'user/message', - 'steering/message', + 'user/message', ]) expect(staged[1]?.type === 'user/message' && staged[1].data.content) .toEqual([{ type: 'text', text: 'admitted prompt' }]) expect(staged[2]?.type === 'user/message' && staged[2].data.content) .toEqual([{ type: 'text', text: 'attached context' }]) - expect(staged[3]?.type === 'steering/message' && staged[3].data.message.content) + expect(staged[3]?.type === 'user/message' && staged[3].data.content) .toEqual([{ type: 'text', text: 'admission steering' }]) - const request = JSON.stringify(adapter.requests[0]?.messages) - expect(request).toContain('admitted prompt') - expect(request).toContain('attached context') - expect(request).toContain('admission steering') + const firstRequest = JSON.stringify(adapter.requests[0]?.messages) + expect(firstRequest).toContain('admitted prompt') + expect(firstRequest).not.toContain('attached context') + expect(firstRequest).not.toContain('admission steering') + const nextRequest = JSON.stringify(adapter.requests[1]?.messages) + expect(nextRequest).toContain('attached context') + expect(nextRequest).toContain('admission steering') }) - it('keeps admission-time outbox input staged when admission is blocked', async () => { + it('cancels admission-time input when admission is blocked', async () => { const adapter = new MockAdapter([textResponse('retried')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('blocked-admission-outbox'), { provider: 'mock', model: 'mock' }) @@ -307,8 +313,8 @@ describe('agent/prompt-submit', () => { decision.resolve({ kind: 'block', reason: 'policy' }) await blockedIdle - expect(agent.inbox.nextStep).toHaveLength(2) - expect(events(agent)).toEqual([]) + expect(agent.inbox.nextStep).toHaveLength(0) + expect(events(agent).some(event => event.type === 'turn/start')).toBe(false) expect(adapter.requests).toEqual([]) disposeBlock() @@ -317,17 +323,13 @@ describe('agent/prompt-submit', () => { const staged = events(agent).filter(event => event.type === 'user/message' || event.type === 'steering/message') - expect(staged.map(event => event.type)).toEqual([ - 'user/message', - 'steering/message', - 'user/message', - ]) + expect(staged.map(event => event.type)).toEqual(['user/message']) expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('blocked prompt') - expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('staged context') - expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('staged steering') + expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('staged context') + expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('staged steering') }) - it('orders rejected-admission outbox input before a later admitted prompt', async () => { + it('cancels later queued work when an admission is blocked', async () => { const adapter = new MockAdapter([textResponse('continued')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('rejected-admission-order'), { @@ -361,23 +363,12 @@ describe('agent/prompt-submit', () => { send(agent, 'later prompt') await idle - const staged = events(agent).filter(event => - event.type === 'turn/start' || event.type === 'user/message' || event.type === 'steering/message') - expect(staged.map(event => event.type)).toEqual([ - 'turn/start', - 'user/message', - 'steering/message', - 'user/message', - ]) - expect(staged[1]?.type === 'user/message' && staged[1].data.content) - .toEqual([{ type: 'text', text: 'earlier state change' }]) - expect(staged[2]?.type === 'steering/message' && staged[2].data.message.content) - .toEqual([{ type: 'text', text: 'earlier steering' }]) - expect(staged[3]?.type === 'user/message' && staged[3].data.content) - .toEqual([{ type: 'text', text: 'later prompt' }]) + expect(events(agent).some(event => event.type === 'turn/start')).toBe(false) + expect(agent.inbox.hasPending).toBe(false) + expect(adapter.requests).toEqual([]) }) - it('commits context-only injection when admission closes without a turn', async () => { + it('cancels context-only injection when admission closes without a turn', async () => { const adapter = new MockAdapter([]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('blocked-admission-context'), { provider: 'mock', model: 'mock' }) @@ -399,51 +390,31 @@ describe('agent/prompt-submit', () => { await idle const log = events(agent) - expect(log.map(event => event.type)).toEqual(['user/message']) - expect(log[0]?.type === 'user/message' && log[0].data.content) - .toEqual([{ type: 'text', text: 'independent context' }]) + expect(log.some(event => event.type === 'user/message')).toBe(false) + expect(agent.inbox.hasPending).toBe(false) expect(adapter.requests).toEqual([]) }) - it('retains rejected-admission context when its idle append fails', async () => { - const adapter = new MockAdapter([textResponse('retried')]) + it('leaves inbox state unchanged when its durable append fails', async () => { + const adapter = new MockAdapter([]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('blocked-admission-append-failure'), { provider: 'mock', model: 'mock', }) - const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) vi.spyOn(agent.session, 'append').mockImplementationOnce(() => { throw new Error('append unavailable') }) - const entered = Promise.withResolvers() - const decision = Promise.withResolvers() - const disposeBlock = ctx.on('agent/prompt-submit', async () => { - entered.resolve(undefined) - return decision.promise - }) - - agent.followup(createUserMessage({ content: [{ type: 'text', text: 'blocked prompt' }], source: { kind: 'user' } })) - await entered.promise - agent.inject(createUserMessage({ - content: [{ type: 'text', text: 'retained context' }], - source: { kind: 'plugin', plugin: 'test' }, - })) - decision.resolve({ kind: 'block', reason: 'policy' }) - await agent.whenIdle() + expect(() => { + send(agent, 'blocked prompt') + }).toThrow('append unavailable') expect(events(agent)).toEqual([]) - expect(warned).toHaveBeenCalledWith(expect.stringContaining('append unavailable')) - - disposeBlock() - send(agent, 'resume') - await waitForIdle(ctx, agent) - - expect(events(agent).some(event => event.type === 'user/message' - && JSON.stringify(event.data.content).includes('retained context'))).toBe(true) + expect(agent.inbox.hasPending).toBe(false) + expect(agent.status).toBe('idle') }) - it('adjacent blocked and allowed prompts keep independent turn outcomes', async () => { + it('a blocked prompt cancels adjacent queued prompts', async () => { const adapter = new MockAdapter([textResponse('ran once')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -457,22 +428,18 @@ describe('agent/prompt-submit', () => { const reasons: TurnEndReason[] = [] ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) }) - // The rejected admission is dropped; the allowed prompt owns the only turn. send(agent, 'secret') send(agent, 'safe') await waitForIdle(ctx, agent) const log = events(agent) - // The allowed prompt became a user/message and drove exactly one model call. - const userMsgs = log.filter(e => e.type === 'user/message') - expect(userMsgs).toHaveLength(1) - expect(userMsgs[0]?.type === 'user/message' && userMsgs[0].data.content).toEqual([{ type: 'text', text: 'safe' }]) - expect(adapter.requests.length).toBeGreaterThanOrEqual(1) - expect(log.filter(e => e.type === 'turn/start')).toHaveLength(1) - expect(reasons).toEqual([{ kind: 'completed' }]) + expect(log.filter(e => e.type === 'user/message')).toHaveLength(0) + expect(adapter.requests).toHaveLength(0) + expect(log.filter(e => e.type === 'turn/start')).toHaveLength(0) + expect(reasons).toEqual([]) }) - it('a throwing prompt-submit listener drops that admission while an adjacent message survives', async () => { + it('a throwing prompt-submit listener reports the driver error and retains adjacent work', async () => { const adapter = new MockAdapter([textResponse('after')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -497,14 +464,14 @@ describe('agent/prompt-submit', () => { send(agent, 'first') send(agent, 'second') await idle - expect(errors).toEqual([]) + expect(errors).toEqual([expect.objectContaining({ message: 'prompt hook broke' })]) const log = events(agent) - expect(log.filter(e => e.type === 'turn/start')).toHaveLength(1) - expect(log.filter(e => e.type === 'turn/end')).toHaveLength(1) - expect(reasons).toEqual([{ kind: 'completed' }]) + expect(log.filter(e => e.type === 'turn/start')).toHaveLength(0) + expect(log.filter(e => e.type === 'turn/end')).toHaveLength(0) + expect(reasons).toEqual([]) expect(statuses).toEqual(['running', 'idle']) - expect(adapter.requests).toHaveLength(1) - expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('second') + expect(adapter.requests).toHaveLength(0) + expect(agent.inbox.nextTurn).toHaveLength(2) }) }) diff --git a/packages/core/agent-loop/tests/request-reconstruction.spec.ts b/packages/core/agent-loop/tests/request-reconstruction.spec.ts index d4150c0521..f9153b4de9 100644 --- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts +++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts @@ -257,10 +257,6 @@ describe('request stability across the loop', () => { } }([]) const ctx = await harness(adapter) - const errors: Error[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) - }) const agent = ctx.agentLoop.create(SessionId(`reasoning-${kind}`), { provider: 'mock', model: 'mock', @@ -269,7 +265,9 @@ describe('request stability across the loop', () => { send(agent, 'go') await waitForIdle(ctx, agent) - expect(errors).toContain(failure) + expect(agent.session.events.findLast(event => event.type === 'turn/end')).toMatchObject({ + data: { reason: { kind: 'error', error: failure.message } }, + }) expect(adapter.requests).toHaveLength(0) }, ) @@ -316,19 +314,13 @@ describe('request stability across the loop', () => { send(agent, 'first') await waitForIdle(ctx, agent) - // A pre-step listener compacts turn 1's history before turn 2's step — - // the sanctioned surface rewrite, landing OUTSIDE the step. - const preStep = ctx.on('agent/step', () => { - preStep() - const session = agent.session - const nodes = session.surface.nodes - session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: '[summary of turn 1]' }], - source: { kind: 'plugin', plugin: 'test-compact' }, - }), { - surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, - sourceEventSeqs: [nodes[0]!, nodes[1]!], - }) + const nodes = agent.session.surface.nodes + agent.session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: '[summary of turn 1]' }], + source: { kind: 'plugin', plugin: 'test-compact' }, + }), { + surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, + sourceEventSeqs: [nodes[0]!, nodes[1]!], }) send(agent, 'second') @@ -398,10 +390,6 @@ describe('request stability across the loop', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const errors: Error[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) - }) ctx.on('llm/stream', (options, next) => { // The historical failure mode this design kills: a listener rewriting // request content in place. The freeze turns it into a loud error. @@ -415,8 +403,10 @@ describe('request stability across the loop', () => { send(agent, 'go') await waitForIdle(ctx, agent) - expect(errors).toHaveLength(1) - expect(errors[0]!.message).toMatch(/not extensible|frozen|read only|readonly/i) + const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd).toMatchObject({ data: { reason: { kind: 'error' } } }) + if (turnEnd?.type !== 'turn/end' || turnEnd.data.reason.kind !== 'error') throw new Error() + expect(turnEnd.data.reason.error).toMatch(/not extensible|frozen|read only|readonly/i) }) it('a fresh loop instance over a seeded log anchors with a resume snapshot and stays cache-aligned', async () => { diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts index d03dfe0f59..430d5eb273 100644 --- a/packages/core/agent-loop/tests/resume.spec.ts +++ b/packages/core/agent-loop/tests/resume.spec.ts @@ -540,9 +540,10 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume', await waitForIdle(ctx1, a1) a1.inject(createUserMessage({ content: [{ type: 'text', text: 'background task 42 finished' }], source: { kind: 'plugin', plugin: 'tool-bash' } })) await a1.whenIdle() - await ctx1.fiber.dispose() + await ctx1.sessions.flush(a1.session) - // Lifecycle 2: resume; the injected context is still in the derived history. + // Lifecycle 2: resume; the injected context is still pending and becomes + // model-visible when the next turn admits it. const adapter2 = new MockAdapter([textResponse('next')]) const ctx2 = new Context() await ctx2.plugin(LlmService) @@ -553,10 +554,17 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume', await ctx2.plugin(AgentLoop, { agents: [] }) await ctx2.plugin(SessionPersistenceJsonl, { root }) ctx2.llm.registerAdapter(['mock'], adapter2) + const loaded = await ctx2.sessionPersistence.load(SessionId('inject-sess')) + expect(loaded.events.some(event => event.type === 'agent/inbox/spliced')).toBe(true) + expect(JSON.stringify(loaded.events)).toContain('background task 42 finished') const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('inject-sess') })).agent + expect(JSON.stringify(a2.inbox.nextStep)).toContain('background task 42 finished') + a2.followup(createUserMessage({ content: [{ type: 'text', text: 'continue' }], source: { kind: 'user' } })) + await waitForIdle(ctx2, a2) const flat = JSON.stringify(a2.session.deriveMessages()) expect(flat).toContain('background task 42 finished') await ctx2.fiber.dispose() + await ctx1.fiber.dispose() }) it('resume reloads a persisted session: history + turn numbering continue, no duplicate seqs', async () => { diff --git a/packages/core/agent-loop/tests/tool-calls.spec.ts b/packages/core/agent-loop/tests/tool-calls.spec.ts index dd086d8e7f..98ac46270f 100644 --- a/packages/core/agent-loop/tests/tool-calls.spec.ts +++ b/packages/core/agent-loop/tests/tool-calls.spec.ts @@ -648,10 +648,6 @@ describe('tool-call scheduler: failure quiescence', () => { ? new Promise((_resolve, reject) => { rejectFirst = reject }) : dispatch(exec).then(() => { throw drainedError }) const agent = ctx.agentLoop.create(SessionId('scheduler-failure'), { provider: 'mock', model: 'mock' }) - const errors: unknown[] = [] - ctx.on('agent/error', (subject, _turn, _step, error) => { - if (subject === agent) errors.push(error) - }) let idle = false const idlePromise = waitForIdle(ctx, agent).then(() => { idle = true }) @@ -664,15 +660,16 @@ describe('tool-call scheduler: failure quiescence', () => { const startedBeforeDrain = [...gated.started] const idleBeforeDrain = idle - const errorsBeforeDrain = [...errors] + const turnEndBeforeDrain = events(agent).find(event => event.type === 'turn/end') for (const id of gated.pending()) gated.release(id) await idlePromise expect(startedBeforeDrain).toEqual(['2']) expect(idleBeforeDrain).toBe(false) - expect(errorsBeforeDrain).toEqual([]) + expect(turnEndBeforeDrain).toBeUndefined() expect(gated.pending()).toEqual([]) - expect(errors).toEqual([schedulerError]) - expect(errors[0]).toBe(schedulerError) + expect(events(agent).findLast(event => event.type === 'turn/end')).toMatchObject({ + data: { reason: { kind: 'error', error: schedulerError.message } }, + }) }) }) diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index 3789ec5430..583734a3db 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -32,6 +32,7 @@ interface RoundAttempt extends RoundIdentity { readonly messageId: MessageId readonly content: ContentBlock[] phase: 'queued' | 'admitted' + cancelled: boolean stale: boolean } @@ -124,6 +125,12 @@ export function apply(ctx: Context): void { } } + /** Remove only this driver's still-pending reservation. */ + function cancelReservation(agent: Agent, attempt: RoundAttempt): void { + const index = agent.inbox.nextTurn.findIndex(message => message.id === attempt.messageId) + if (index >= 0) agent.inbox.splice('next-turn', index, 1, [], 'canceled') + } + /** Process admitted work at quiescence, then reserve at most one next round. */ async function drive(state: DriverState): Promise { const { agent } = state @@ -175,6 +182,7 @@ export function apply(ctx: Context): void { messageId: message.id, content, phase: 'queued', + cancelled: false, stale: false, } state.attempt = reservation @@ -252,7 +260,8 @@ export function apply(ctx: Context): void { state.competingQueued = false const attempt = state.attempt const goal = currentGoal(state) - if (attempt?.phase === 'queued' && goal?.phase === 'active' && goal.activation === 'armed') { + if ((attempt?.phase === 'queued' || attempt?.cancelled) + && goal?.phase === 'active' && goal.activation === 'armed') { state.attempt = undefined try { ctx.goals.pause(agent, goalRef(goal)) @@ -292,16 +301,8 @@ export function apply(ctx: Context): void { return case 'turn/end': if (event.data.reason.kind !== 'aborted') return - { - const goal = currentGoal(state) - if (goal?.phase !== 'active' || goal.activation !== 'armed') return - try { - ctx.goals.pause(agent, goalRef(goal)) - } catch (error: unknown) { - ctx.logger.warn(`goal-session: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`) - disarm(state) - } - } + if (state.attempt?.phase === 'admitted') state.attempt.cancelled = true + else disarm(state) return default: return @@ -324,7 +325,7 @@ export function apply(ctx: Context): void { && source.round === goal.roundsStarted + 1 } - ctx.on('agent/prompt-submit', async (agent, messages, _signal, next): Promise => { + ctx.on('agent/prompt-submit', async (agent, messages, signal, next): Promise => { const submitted = messages.find(message => isGoalRoundSource(message.source)) if (submitted === undefined) return next() const { content, source } = submitted @@ -342,14 +343,16 @@ export function apply(ctx: Context): void { if (attempt !== undefined && sameRound(source, attempt)) { attempt.stale = true state.attempt = undefined + cancelReservation(agent, attempt) } requestDrive(state) - return { kind: 'block', reason: STALE_ROUND_REASON } + return { kind: 'block', reason: STALE_ROUND_REASON, keepInbox: true } } let decision: PromptDecision try { decision = await next() } catch (error: unknown) { + if (signal.aborted) throw error // A throwing downstream hook drops the whole admission: the loop // returns to idle without a turn, so a still-queued reservation would // starve every later drive pass. Clear it and let the driver @@ -357,10 +360,12 @@ export function apply(ctx: Context): void { const attempt = state.attempt if (attempt !== undefined && sameRound(source, attempt) && attempt.phase === 'queued') { state.attempt = undefined + cancelReservation(agent, attempt) requestDrive(state) } throw error } + if (signal.aborted) return decision if (decision.kind === 'block') { const attempt = state.attempt if (attempt !== undefined && sameRound(source, attempt)) state.attempt = undefined @@ -386,9 +391,10 @@ export function apply(ctx: Context): void { if (attempt !== undefined && sameRound(source, attempt)) { attempt.stale = true state.attempt = undefined + cancelReservation(agent, attempt) } requestDrive(state) - return { kind: 'block', reason: STALE_ROUND_REASON } + return { kind: 'block', reason: STALE_ROUND_REASON, keepInbox: true } } return decision }) @@ -410,6 +416,9 @@ export function apply(ctx: Context): void { const attempt = state.attempt if (attempt !== undefined) { attempt.stale = true + if (attempt.phase === 'admitted' && state.agent.status === 'running') { + state.agent.cancel({ kind: 'parent' }) + } } if (state.run !== undefined) waits.push(state.run) } diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index 93d3ef926e..4cff18d80f 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -4,7 +4,7 @@ import type { Agent, PromptDecision } from '@deepseek-ai/dsh-agent' import { agentEvents } from '@deepseek-ai/dsh-agent' import AgentLoop from '@deepseek-ai/dsh-agent-loop' import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' -import GoalService, { foldGoal, GoalId } from '@deepseek-ai/dsh-goal' +import GoalService, { GoalId } from '@deepseek-ai/dsh-goal' import type { GoalView } from '@deepseek-ai/dsh-goal' import { createUserMessage, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm' import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm' @@ -221,18 +221,18 @@ describe('same-session goal driving', () => { }) it.each([ - ['rate limit', new LlmError('slow down', 'RATE_LIMIT'), 'usage-limited'], - ['request error', new Error('provider broke'), 'turn-error'], - ['max tokens', maxTokensResponse('unfinished'), 'max-tokens'], - ] as const)('stops after a %s without an automatic retry', async (_label, response, code) => { - const test = await harness([response]) + ['rate limit', new LlmError('slow down', 'RATE_LIMIT')], + ['request error', new Error('provider broke')], + ['max tokens', maxTokensResponse('unfinished')], + ] as const)('does not attribute a %s to one goal follow-up', async (_label, response) => { + const test = await harness(Array.from({ length: 8 }, () => response)) test.ctx.goals.create(test.agent, { objective: 'stop safely', maxGoalRounds: 8 }) const goal = await waitForGoal(test.ctx, test.agent, current => current?.phase === 'blocked') - expect(goal).toMatchObject({ roundsStarted: 1, activation: 'disarmed' }) - expect(goal?.blockedReason?.code).toBe(code) - expect(test.adapter.requests).toHaveLength(1) + expect(goal).toMatchObject({ roundsStarted: 8, activation: 'disarmed' }) + expect(goal?.blockedReason?.code).toBe('round-limit') + expect(test.adapter.requests).toHaveLength(8) }) it('maps a downstream prompt veto to blocked without admitting the round', async () => { @@ -250,7 +250,7 @@ describe('same-session goal driving', () => { expect(test.agent.session.events.some(event => event.type === 'turn/start')).toBe(false) }) - it('does not reserve again when a stopped-goal observer queues ordinary work', async () => { + it('does not reserve again when a stopped-goal observer queues cancel-scoped work', async () => { const test = await harness([textResponse('human follow-up')]) test.ctx.on('agent/prompt-submit', (_agent, messages, _signal, next) => messages[0]?.source.kind === 'goal' ? Promise.resolve({ kind: 'block', reason: 'stop this round' }) @@ -261,10 +261,10 @@ describe('same-session goal driving', () => { test.ctx.goals.create(test.agent, { objective: 'stop and inspect' }) await waitForGoal(test.ctx, test.agent, goal => goal?.phase === 'blocked') - await waitForRequests(test.adapter, 1) await test.agent.whenIdle() - expect(requestText(test.adapter.requests[0]!)).toContain('inspect the blocker') + expect(test.adapter.requests).toHaveLength(0) + expect(test.agent.inbox.nextTurn).toHaveLength(0) }) it('pauses and drops a reserved round when cancellation lands before admission', async () => { @@ -297,10 +297,6 @@ describe('same-session goal driving', () => { const goal = await waitForGoal(test.ctx, test.agent, current => current?.phase === 'paused') expect(goal).toMatchObject({ roundsStarted: 1, activation: 'disarmed' }) - expect(foldGoal(test.agent.session.events)).toMatchObject({ - goal: { phase: 'paused', revision: 2 }, - roundsStarted: 1, - }) expect(test.adapter.requests).toHaveLength(1) }) @@ -486,8 +482,8 @@ describe('same-session goal driving', () => { expect(test.ctx.goals.get(test.agent)).toMatchObject({ phase: 'paused' }) }) - it('reschedules the round when a downstream admission hook throws', async () => { - const test = await harness([textResponse('second admission succeeded')]) + it('fails closed when a downstream admission hook throws', async () => { + const test = await harness([]) // Registered after goal-session's own listener: the throw propagates back // through goal-session's next() await, dropping the whole admission. let threw = false @@ -500,12 +496,10 @@ describe('same-session goal driving', () => { }) test.ctx.goals.create(test.agent, { objective: 'survive a throwing hook', maxGoalRounds: 1 }) - // The cleared reservation lets the driver reschedule; the second - // admission passes and the round completes to its limit. - const goal = await waitForGoal(test.ctx, test.agent, current => current?.phase === 'blocked') - expect(goal?.blockedReason?.code).toBe('round-limit') - expect(goal?.roundsStarted).toBe(1) - expect(test.adapter.requests).toHaveLength(1) + const goal = await waitForGoal(test.ctx, test.agent, current => current?.activation === 'disarmed') + expect(goal).toMatchObject({ phase: 'active', roundsStarted: 0 }) + expect(test.adapter.requests).toHaveLength(0) + expect(test.agent.inbox.nextTurn).toHaveLength(0) }) it('a retry turn on a non-goal failure leaves the goal reservation untouched', async () => { @@ -619,7 +613,7 @@ describe('same-session goal driving', () => { const test = await harness([textResponse('retry after containment')]) let armed = true onInboxMessage(test.ctx, test.agent, (message) => { - if (message.source.kind !== 'goal' || !armed) return + if (message.source.kind !== 'goal' || message.source.round <= 0 || !armed) return armed = false vi.spyOn(test.ctx.goals, 'get').mockImplementationOnce(() => { throw new Error('admission projection failed') @@ -779,34 +773,8 @@ describe('same-session goal driving', () => { expect(test.adapter.requests).toHaveLength(1) }) - it('leaves a queued reservation pending when the driver runs before its turn settles', async () => { - const test = await harness([textResponse('settled later')]) - let woken = false - test.ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next) => { - if (messages[0]?.source.kind === 'goal' && !woken) { - woken = true - // A concurrent driver pass must observe the still-unsettled attempt - // and yield rather than double-book or clear the reservation. - agentEvents(test.ctx, test.agent).emit('agent/status', 'idle') - await new Promise((resolve) => { setImmediate(resolve) }) - } - return next() - }) - test.ctx.goals.create(test.agent, { objective: 'wake early', maxGoalRounds: 1 }) - - const goal = await waitForGoal(test.ctx, test.agent, current => current?.phase === 'blocked') - - expect(goal?.blockedReason?.code).toBe('round-limit') - expect(goal?.roundsStarted).toBe(1) - expect(test.adapter.requests).toHaveLength(1) - }) - - it('yields to a round whose turn/end never committed instead of misreading it as settled', async () => { + it('disarms when a round turn/end cannot commit', async () => { const test = await harness([textResponse('round ran')]) - // A persistent pre-commit turn/end rejection: the loop contains the close - // failure and reaches idle, but the round's attempt holds a turn with no - // terminal reason. The idle drive pass must yield to that unsettled - // attempt rather than classify an absent reason or crash into disarm. test.ctx.on('internal/dispatch', (_mode, name, args) => { if (name !== 'session/event') return const event = args[1] as { type: string } @@ -817,12 +785,10 @@ describe('same-session goal driving', () => { await test.agent.whenIdle() await new Promise((resolve) => { setImmediate(resolve) }) - // One request ran; the unsettled attempt parked the driver without a - // second reservation and without disarming the goal. expect(test.adapter.requests).toHaveLength(1) expect(test.ctx.goals.get(test.agent)).toMatchObject({ phase: 'active', - activation: 'armed', + activation: 'disarmed', }) }) @@ -868,7 +834,9 @@ describe('same-session goal driving', () => { if (session !== test.agent.session || queued) return if (event.type === 'user/message' && event.data.source.kind === 'goal') { queued = true - test.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'human interleaved' }], source: { kind: 'user' } })) + queueMicrotask(() => { + test.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'human interleaved' }], source: { kind: 'user' } })) + }) } }) test.ctx.goals.create(test.agent, { objective: 'survive a stale failure', maxGoalRounds: 1 }) From 3ba4d40e6a5fa670871f3fad176645a9913e9565 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 17:59:37 +0800 Subject: [PATCH 024/689] fix(user-interaction): address review feedback --- ...select-custom-answer-composition.i18n.yaml | 4 +- ...-multi-select-custom-answer-composition.md | 4 +- ...lti-select-custom-answer-composition.zh.md | 4 +- apps/web/tests/question-composer.e2e.ts | 37 +++++++++++++++---- .../question-composer/answered.expected.md | 3 +- .../question-composer/composed.expected.md | 17 +++++++++ .../snapshots/question-composer/session.jsonl | 12 +++--- .../question-composer/ui.expected.md | 6 +-- .../tests/question-composer.spec.tsx | 5 +++ packages/host/apiproxy/src/api-proxy.ts | 6 ++- .../tool-ask-user/tests/tool-ask-user.spec.ts | 10 ++++- packages/ui/tui/README.i18n.yaml | 4 +- packages/ui/tui/README.md | 2 +- packages/ui/tui/README.zh.md | 2 +- packages/ui/tui/src/components/dialogs.ts | 12 ++++-- packages/ui/tui/tests/tui.spec.ts | 28 ++++++++++++-- 16 files changed, 119 insertions(+), 37 deletions(-) create mode 100644 apps/web/tests/snapshots/question-composer/composed.expected.md diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml index bb081e4be8..2f06390bdf 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.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-30-multi-select-custom-answer-composition.md -2026-07-30-multi-select-custom-answer-composition.md: 7194f4a79f1dd49eba4a9b626d75203fced06544 -2026-07-30-multi-select-custom-answer-composition.zh.md: fac09c8db0ebf2dd4a84ade7aa7868128656025d +2026-07-30-multi-select-custom-answer-composition.md: 581beec89a0f0018ec2df687f5dfe1b1b5b86d22 +2026-07-30-multi-select-custom-answer-composition.zh.md: 5c9cb59822aca3fbf49fbbdf522c76f963df3480 diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md index 7194f4a79f..581beec89a 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md +++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md @@ -10,7 +10,7 @@ The user-interaction result vocabulary carries selected option labels and option ## Decision -For a question with `multiSelect: true`, one answer item may contain both a non-empty `selected` array and non-empty `custom` text. Web drafts preserve both values regardless of whether the user selects an option or types custom text first; the TUI projects its checked option set when custom text is submitted; and the Web host accepts the combined response after applying its existing id, label, uniqueness, batch, and non-empty-text validation. +For a question with `multiSelect: true`, one answer item may contain both a non-empty `selected` array and non-empty `custom` text. Web drafts preserve both values regardless of whether the user selects an option or types custom text first; the TUI retains pending custom text across option/custom mode switches and projects it with checked labels from either submit mode; and the Web host accepts the combined response after applying its existing id, label, uniqueness, batch, and non-empty-text validation. Single-select and optionless questions keep exclusive semantics: custom text overrides any selected option. The result shape remains `{ id, selected, custom? }`, so no wire or tool-output schema changes. @@ -22,4 +22,4 @@ Single-select and optionless questions keep exclusive semantics: custom text ove ## Consequences -Multi-select UIs can represent the user's complete answer without discarding either source. Providers and consumers retain the existing DTO, while request-aware validators interpret the allowed combination from `multiSelect`. Web, TUI, host-response, tool-projection, and assembled keyless TUI coverage pin the combined result; single-select host coverage pins the remaining exclusivity rule. +Multi-select UIs can represent the user's complete answer without discarding either source. Providers and consumers retain the existing DTO, while request-aware validators interpret the allowed combination from `multiSelect`. Web component and assembled-browser coverage, TUI coverage, host-response coverage, and tool-projection coverage pin the combined result. Web, TUI, and tool-projection coverage also retain labels-only answers; assembled keyless TUI coverage pins the combined terminal flow, and single-select host coverage pins the remaining exclusivity rule. diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md index fac09c8db0..5c9cb59822 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md @@ -10,7 +10,7 @@ Status: implemented ## 决策 -对于 `multiSelect: true` 的问题，一个回答项可以同时包含非空 `selected` 数组与非空 `custom` 文本。无论用户先选择选项还是先输入自定义文本，Web 草稿都会保留两个值；提交自定义文本时，TUI 会投影其已勾选的选项集合；Web 宿主则在应用现有的 id、标签、唯一性、批次和非空文本校验后接受组合响应。 +对于 `multiSelect: true` 的问题，一个回答项可以同时包含非空 `selected` 数组与非空 `custom` 文本。无论用户先选择选项还是先输入自定义文本，Web 草稿都会保留两个值；TUI 在选项与自定义模式之间切换时会保留待提交的自定义文本，并在任一模式提交时将其与已勾选的标签一同投影；Web 宿主则在应用现有的 id、标签、唯一性、批次和非空文本校验后接受组合响应。 单选题和无选项问题仍保持互斥语义：自定义文本会覆盖任何已选中的选项。结果形状仍为 `{ id, selected, custom? }`，因此协议或工具输出 schema 均无需变更。 @@ -22,4 +22,4 @@ Status: implemented ## 后果 -多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web、TUI、宿主响应、工具投影和组装后的无密钥 TUI 覆盖会固定组合结果；单选题的宿主覆盖则固定其余的互斥规则。 +多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web 组件与组装浏览器的覆盖率、TUI 覆盖率、宿主响应覆盖率和工具投影覆盖率共同固定组合结果。Web、TUI 与工具投影覆盖率还固定了仅含标签的回答形态；组装后的无密钥 TUI 覆盖率固定终端中的组合回答流程，单选题的宿主覆盖率则固定其余的互斥规则。 diff --git a/apps/web/tests/question-composer.e2e.ts b/apps/web/tests/question-composer.e2e.ts index ac4be25299..983f1c4812 100644 --- a/apps/web/tests/question-composer.e2e.ts +++ b/apps/web/tests/question-composer.e2e.ts @@ -23,15 +23,16 @@ import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './suppor const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/question-composer', import.meta.url)) const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl') const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md') -// Second golden: the answered transcript — the question resolved into its -// tool round trip and the final reply, the state the waiting golden cannot see. +const COMPOSED_EXPECTED = join(SNAPSHOT_DIR, 'composed.expected.md') +// Final golden: the answered transcript — the question resolved into its tool +// round trip and the final reply, the state the composer goldens cannot see. const ANSWERED_EXPECTED = join(SNAPSHOT_DIR, 'answered.expected.md') const MODE = webSnapshotMode() // The options carry long descriptions on purpose: the squeeze assertion below // needs option copy that WRAPS, which is the only shape that reproduces a // collapsed row painting its copy outside its own box. -const PROMPT = 'Use the ask_user_question tool to ask me exactly one question with id "color", question "Which color do you prefer?", header "Pick one", and two options: label "Blue" with description "A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.", and label "Green" with description "A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions." After I answer, reply with the single word DONE and stop.' +const PROMPT = 'Use the ask_user_question tool to ask me exactly one multi-select question with id "color", question "Which color do you prefer?", header "Pick one", and two options: label "Blue" with description "A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.", and label "Green" with description "A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions." Set multi_select to true. After I answer, reply with the single word DONE and stop.' describe('web e2e: resident question composer round trip', () => { let scaffold: WebScaffold @@ -124,9 +125,17 @@ describe('web e2e: resident question composer round trip', () => { await page.setViewportSize(original) } - await composer.getByRole('radio', { name: 'Blue' }).click() - // Submit: Enter on the focused option (the composer's documented submit). - await composer.getByRole('radio', { name: 'Blue' }).press('Enter') + const blue = composer.getByRole('checkbox', { name: 'Blue' }) + await blue.click() + const custom = composer.getByRole('textbox') + await custom.fill('Include accessibility notes') + expect(await blue.getAttribute('aria-checked')).toBe('true') + expect(await custom.inputValue()).toBe('Include accessibility notes') + if (MODE !== 'record') { + const snapshot = await captureStableAria(page, '[data-question-key]', scaffold.workspaceCwd) + await compareOrRefreshGolden(COMPOSED_EXPECTED, snapshot, MODE) + } + await custom.press('Enter') const sessionId = await settled if (MODE === 'record') { @@ -135,7 +144,14 @@ describe('web e2e: resident question composer round trip', () => { } // World state: the tool result carries the chosen answer, and DONE lands. const results = sessionEvents.filter(e => e.type === 'tool/result') - expect(JSON.stringify(results.at(-1))).toContain('Blue') + const answerText = results.flatMap(event => event.data.message.content.flatMap(block => + block.type === 'tool-result' + ? block.content.filter(item => item.type === 'text').map(item => item.text) + : [], + )).at(-1) + expect(JSON.parse(answerText ?? '')).toEqual({ + answers: [{ id: 'color', selected: ['Blue'], custom: 'Include accessibility notes' }], + }) await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1) // Composer gone; regular input restored. expect(await page.locator('[data-question-key]').count()).toBe(0) @@ -149,6 +165,11 @@ describe('web e2e: resident question composer round trip', () => { }, 200_000) it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => { - await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl', 'ui.expected.md', 'answered.expected.md']) + await assertFixtureInventory(SNAPSHOT_DIR, [ + 'session.jsonl', + 'ui.expected.md', + 'composed.expected.md', + 'answered.expected.md', + ]) }) }) diff --git a/apps/web/tests/snapshots/question-composer/answered.expected.md b/apps/web/tests/snapshots/question-composer/answered.expected.md index 36752c783a..7f7603eb8a 100644 --- a/apps/web/tests/snapshots/question-composer/answered.expected.md +++ b/apps/web/tests/snapshots/question-composer/answered.expected.md @@ -4,13 +4,14 @@ - tablist: - tab "Chat" [selected] - tab "Trajectory" -- text: "Use the ask_user_question tool to ask me exactly one question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" After I answer, reply with the single word DONE and stop. {{clock}}" +- text: "Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop. {{clock}}" - button "复制": - img - button "在新对话中分支": - img - button "编辑": - img +- button "▸ 上下文注入" - button "Think The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that.": - img - img diff --git a/apps/web/tests/snapshots/question-composer/composed.expected.md b/apps/web/tests/snapshots/question-composer/composed.expected.md new file mode 100644 index 0000000000..c18e6225c6 --- /dev/null +++ b/apps/web/tests/snapshots/question-composer/composed.expected.md @@ -0,0 +1,17 @@ +- region "Which color do you prefer?": + - text: Pick one + - heading "Which color do you prefer?" [level=2] + - button "Dismiss all questions": + - img + - group: + - checkbox "Blue" [checked]: Blue A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards. + - checkbox "Green": Green A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions. + - textbox "Type your answer": Include accessibility notes + - button "Previous question" [disabled]: + - img + - text: 1 / 1 + - button "Next question" [disabled]: + - img + - status + - button "Skip this question" + - button "Submit" diff --git a/apps/web/tests/snapshots/question-composer/session.jsonl b/apps/web/tests/snapshots/question-composer/session.jsonl index b13a84e22c..0a5107d23f 100644 --- a/apps/web/tests/snapshots/question-composer/session.jsonl +++ b/apps/web/tests/snapshots/question-composer/session.jsonl @@ -1,20 +1,20 @@ {"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785150167878,"cwd":"{{cwd}}/workspace"} {"type":"turn/start","seq":0,"time":1785150167924,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpcId}}"}}}} -{"type":"user/message","seq":1,"time":1785150167925,"data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"},"role":"user","id":"6deba879-8787-4853-a5f2-0d108a08eb2d"},"surfaceOp":"append"} +{"type":"user/message","seq":1,"time":1785150167925,"data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"},"role":"user","id":"6deba879-8787-4853-a5f2-0d108a08eb2d"},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1785150167927,"data":{"title":"Use the ask_user_question tool to","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1785150167928,"data":{"turn":1,"step":1}} {"type":"request/header","seq":4,"time":1785150167929,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} {"type":"assistant/chunk","seq":5,"time":1785150168452,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"reasoning-chunks","seq0":6,"time0":1785150168452,"data":{"turn":1,"step":1,"index":0,"dt":[87,26,1,0,0,0,38,0,0,0,0,1,12,27,0,27,0,0,1,25,0],"texts":["The"," user"," wants"," me"," to"," use"," the"," ask","_user","_","question"," tool"," with"," specific"," parameters","."," Let"," me"," do"," exactly"," that","."]}} {"type":"assistant/chunk","seq":28,"time":1785150168775,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"tool-call-chunks","seq0":29,"time0":1785150168776,"data":{"turn":1,"step":1,"index":1,"dt":[25,1,0,0,0,25,0,0,0,26,1,0,0,0,0,25,1,0,0,0,0,25,1,0,0,0,0,25,1,0,0,0,1,25,0,0,0,0,1,25,1,0,0,0,0,25,1,0,0,26,0,0,1,0,24,1,0,0,0,1,26,1,0,0,0,0,25,0,1,0,0,0,25,1,0,0,25,0,0,0,0,1,25,0,0,1,0,0,25,0,0,0,1,0,26,1,24],"id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","args":["","{","\"","questions","\"",": ","[","{\"","id","\":"," \"","color","\","," \"","question","\":"," \"","Which"," color"," do"," you"," prefer","?\","," \"","header","\":"," \"","Pick"," one","\","," \"","options","\":"," [","{\"","label","\":"," \"","Blue","\","," \"","description","\":"," \"","A"," cool"," recessive"," hue"," that"," reads"," as"," calm"," and"," trustworthy"," in"," long"," reading"," sessions"," and"," dense"," dash","boards",".\"","},"," {\"","label","\":"," \"","Green","\","," \"","description","\":"," \"","A"," rest","ful"," mid","-spect","rum"," hue"," with"," the"," highest"," perceived"," brightness",","," easiest"," on"," the"," eye"," over"," long"," sessions",".\"","}]","}]","}"]}} +{"type":"tool-call-chunks","seq0":29,"time0":1785150168776,"data":{"turn":1,"step":1,"index":1,"dt":[25,1,0,0,0,25,0,0,0,26,1,0,0,0,0,25,1,0,0,0,0,25,1,0,0,0,0,25,1,0,0,0,1,25,0,0,0,0,1,25,1,0,0,0,0,25,1,0,0,26,0,0,1,0,24,1,0,0,0,1,26,1,0,0,0,0,25,0,1,0,0,0,25,1,0,0,25,0,0,0,0,1,25,0,0,1,0,0,25,0,0,0,1,0,26,1,24],"id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","args":["","{","\"","questions","\"",": ","[","{\"","id","\":"," \"","color","\","," \"","question","\":"," \"","Which"," color"," do"," you"," prefer","?\","," \"","header","\":"," \"","Pick"," one","\", \"multi_select\": true,"," \"","options","\":"," [","{\"","label","\":"," \"","Blue","\","," \"","description","\":"," \"","A"," cool"," recessive"," hue"," that"," reads"," as"," calm"," and"," trustworthy"," in"," long"," reading"," sessions"," and"," dense"," dash","boards",".\"","},"," {\"","label","\":"," \"","Green","\","," \"","description","\":"," \"","A"," rest","ful"," mid","-spect","rum"," hue"," with"," the"," highest"," perceived"," brightness",","," easiest"," on"," the"," eye"," over"," long"," sessions",".\"","}]","}]","}"]}} {"type":"assistant/chunk","seq":127,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."}}}} -{"type":"assistant/chunk","seq":128,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}}}} +{"type":"assistant/chunk","seq":128,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"multi_select\": true, \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}}}} {"type":"assistant/chunk","seq":129,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":113,"outputTokens":158,"cacheReadTokens":4096,"reasoningTokens":22}}}} {"type":"assistant/chunk","seq":130,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":131,"time":1785150169311,"data":{"turn":1,"step":1,"usage":{"inputTokens":113,"outputTokens":158,"cacheReadTokens":4096,"reasoningTokens":22},"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."},{"type":"tool-call","id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"cdb1676c-e781-41ee-8f28-a3595371d729"}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"surfaceOp":"append"} -{"type":"tool/call","seq":132,"time":1785150169312,"data":{"turn":1,"step":1,"callId":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}} -{"type":"tool/result","seq":133,"time":1785150169787,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_Cijldc88LYmVPCXYUsRq1617"},"content":[{"type":"tool-result","toolCallId":"call_00_Cijldc88LYmVPCXYUsRq1617","content":[{"type":"text","text":"{\"answers\":[{\"id\":\"color\",\"selected\":[\"Blue\"]}]}"}],"isError":false}],"role":"user","id":"c69ef39f-6f62-439f-b3f8-e8d10fba572f"}},"sourceEventSeqs":[132],"surfaceOp":"append"} +{"type":"assistant/message","seq":131,"time":1785150169311,"data":{"turn":1,"step":1,"usage":{"inputTokens":113,"outputTokens":158,"cacheReadTokens":4096,"reasoningTokens":22},"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."},{"type":"tool-call","id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"multi_select\": true, \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"cdb1676c-e781-41ee-8f28-a3595371d729"}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"surfaceOp":"append"} +{"type":"tool/call","seq":132,"time":1785150169312,"data":{"turn":1,"step":1,"callId":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"multi_select\": true, \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}} +{"type":"tool/result","seq":133,"time":1785150169787,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_Cijldc88LYmVPCXYUsRq1617"},"content":[{"type":"tool-result","toolCallId":"call_00_Cijldc88LYmVPCXYUsRq1617","content":[{"type":"text","text":"{\"answers\":[{\"id\":\"color\",\"selected\":[\"Blue\"],\"custom\":\"Include accessibility notes\"}]}"}],"isError":false}],"role":"user","id":"c69ef39f-6f62-439f-b3f8-e8d10fba572f"}},"sourceEventSeqs":[132],"surfaceOp":"append"} {"type":"step/end","seq":134,"time":1785150169790,"data":{"turn":1,"step":1}} {"type":"step/start","seq":135,"time":1785150169790,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":136,"time":1785150170605,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} diff --git a/apps/web/tests/snapshots/question-composer/ui.expected.md b/apps/web/tests/snapshots/question-composer/ui.expected.md index 894f84d9ba..c2ee767319 100644 --- a/apps/web/tests/snapshots/question-composer/ui.expected.md +++ b/apps/web/tests/snapshots/question-composer/ui.expected.md @@ -3,9 +3,9 @@ - heading "Which color do you prefer?" [level=2] - button "Dismiss all questions": - img - - radiogroup: - - radio "Blue": 1 Blue A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards. - - radio "Green": 2 Green A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions. + - group: + - checkbox "Blue": Blue A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards. + - checkbox "Green": Green A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions. - textbox "Type your answer" - button "Previous question" [disabled]: - img diff --git a/packages/client/ui-question/tests/question-composer.spec.tsx b/packages/client/ui-question/tests/question-composer.spec.tsx index 87eb275b7d..adc32fc86d 100644 --- a/packages/client/ui-question/tests/question-composer.spec.tsx +++ b/packages/client/ui-question/tests/question-composer.spec.tsx @@ -238,6 +238,11 @@ describe('QuestionComposer', () => { fireEvent.keyDown(custom, { key: 'Enter' }) fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' })) fireEvent.click(screen.getByRole('button', { name: '提交' })) + expect(respond).toHaveBeenNthCalledWith(1, answeredEnvelope('second', [ + { id: 'profile', selected: ['工程落地型 (Recommended)'] }, + { id: 'detail', selected: [], custom: 'x' }, + { id: 'signals', selected: ['系统设计'] }, + ])) expect(await screen.findByText('网络中断')).toBeTruthy() expect(screen.getByRole('button', { name: '提交' }).disabled).toBe(false) diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index 73685c1f0a..b23e4178bb 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -280,8 +280,10 @@ function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQues if (new Set(answer.selected).size !== answer.selected.length) return false const custom = answer.custom?.trim() if (custom !== undefined && custom === '') return false - if (custom !== undefined && answer.selected.length > 0 && question.multiSelect !== true) return false - if (question.multiSelect !== true && answer.selected.length > 1) return false + if (question.multiSelect !== true) { + if (custom !== undefined && answer.selected.length > 0) return false + if (answer.selected.length > 1) return false + } const labels = new Set(question.options?.map(option => option.label) ?? []) return answer.selected.every(label => labels.has(label)) }) diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts index 7d019a520a..0c55e33ed7 100644 --- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts +++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts @@ -141,6 +141,7 @@ describe('ask_user_question tool', () => { return { answers: [ { id: 'targets', selected: ['tests', 'docs'], custom: 'release notes' }, + { id: 'labels-only', selected: ['tests'] }, { id: 'notes', selected: [], custom: 'ship today' }, ], } @@ -159,6 +160,12 @@ describe('ask_user_question tool', () => { options: [{ label: 'tests' }, { label: 'docs' }], multi_select: true, }, + { + id: 'labels-only', + question: 'Which labels should I keep?', + options: [{ label: 'tests' }, { label: 'docs' }], + multi_select: true, + }, { id: 'notes', question: 'Any note?' }, ], }, @@ -169,12 +176,13 @@ describe('ask_user_question tool', () => { expect(result.value).toEqual({ answers: [ { id: 'targets', selected: ['tests', 'docs'], custom: 'release notes' }, + { id: 'labels-only', selected: ['tests'] }, { id: 'notes', selected: [], custom: 'ship today' }, ], }) expect(result.content).toEqual([{ type: 'text', - text: '{"answers":[{"id":"targets","selected":["tests","docs"],"custom":"release notes"},{"id":"notes","selected":[],"custom":"ship today"}]}', + text: '{"answers":[{"id":"targets","selected":["tests","docs"],"custom":"release notes"},{"id":"labels-only","selected":["tests"]},{"id":"notes","selected":[],"custom":"ship today"}]}', }]) }) diff --git a/packages/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml index 548372998f..eedf9e945c 100644 --- a/packages/ui/tui/README.i18n.yaml +++ b/packages/ui/tui/README.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 packages/ui/tui/README.md -README.md: c8eb81b2d76c1616647baba37692ed8cd42e89dc -README.zh.md: 680bb89f12cbbad871010ed025cfa6d4369bb0a3 +README.md: 3b1c67dceadfe18a8d72bedc6a321a3fa86a3c90 +README.zh.md: a87858833eeb9220c709748eb5bbee3ff132eb8f diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index c8eb81b2d7..3b1c67dcea 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -153,7 +153,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels, `custom` text, or both for a multi-select question. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`. +When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels, `custom` text, or both for a multi-select question. Pending custom text survives switching back to options and joins checked labels on a later options-mode submit. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`. #### Token effect diff --git a/packages/ui/tui/README.zh.md b/packages/ui/tui/README.zh.md index 680bb89f12..a87858833e 100644 --- a/packages/ui/tui/README.zh.md +++ b/packages/ui/tui/README.zh.md @@ -153,7 +153,7 @@ Paths prefixed with @ are files explicitly referenced by the user. Use the read #### 模型看到的内容 -消费方调用 `ctx.userInteraction.ask()` 时，此提供方会按顺序显示各个问题，并返回选中选项标签、`custom` 文本，或为多选题同时返回两者。中止、取消或 UI dispose 会变为 `Error: ask_user_question was interrupted before the user answered`；该转换由 `dsh-tool-ask-user` 完成。 +消费方调用 `ctx.userInteraction.ask()` 时，此提供方会按顺序显示各个问题，并返回选中选项标签、`custom` 文本，或为多选题同时返回两者。切回选项后，待提交的自定义文本仍会保留，并在之后从选项模式提交时与已勾选的标签一同返回。中止、取消或 UI dispose 会变为 `Error: ask_user_question was interrupted before the user answered`；该转换由 `dsh-tool-ask-user` 完成。 #### Token 影响 diff --git a/packages/ui/tui/src/components/dialogs.ts b/packages/ui/tui/src/components/dialogs.ts index 0dac957cf3..59ce8fd3d7 100644 --- a/packages/ui/tui/src/components/dialogs.ts +++ b/packages/ui/tui/src/components/dialogs.ts @@ -804,11 +804,12 @@ export class QuestionDialog implements Component, Focusable { const selected = this.question.multiSelect ? this.selectedOptionLabels() : [options[this.selectedIndex]?.label].filter((label): label is string => label !== undefined) - if (selected.length === 0) { + const custom = this.question.multiSelect ? this.input.getValue().trim() : '' + if (selected.length === 0 && custom === '') { this.error = 'Select at least one option, or press Tab for a custom answer.' return } - this.done({ selected }) + this.done({ selected, ...(custom === '' ? {} : { custom }) }) } else if (matchesKey(data, Key.tab) || data.toLowerCase() === 'c') { this.mode = 'custom' this.error = '' @@ -854,7 +855,12 @@ export class QuestionDialog implements Component, Focusable { push('') if (this.mode === 'custom') { for (const line of this.input.render(innerWidth)) push(line) - push(this.palette.dim(this.options.length > 0 ? 'Enter submit • Esc options' : 'Enter submit • Esc cancel')) + const controls = [ + ...(this.options.length > 0 && this.question.multiSelect ? [`${this.selected.size} selected`] : []), + 'Enter submit', + this.options.length > 0 ? 'Esc options' : 'Esc cancel', + ] + push(this.palette.dim(controls.join(' • '))) } else { const options = this.options const start = Math.max(0, Math.min( diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 72d35dd4b2..b2dfcb9536 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -4697,12 +4697,29 @@ describe('TUI user-interaction dialogs', () => { result.terminal.send('\x1b[B') result.terminal.send(' ') result.terminal.send('\t') + await tick() + expect(result.terminal.output).toContain('2 selected • Enter submit • Esc options') result.terminal.send('Tests') result.terminal.send('\r') await expect(multi).resolves.toEqual({ answers: [{ id: 'targets', selected: ['Code', 'Docs'], custom: 'Tests' }], }) + const labelsOnly = result.ctx.userInteraction.ask({ + questions: [{ + id: 'labels-only', + question: 'Pick one target', + multiSelect: true, + options: [{ label: 'Code' }, { label: 'Docs' }], + }], + }) + await tick() + result.terminal.send(' ') + result.terminal.send('\r') + await expect(labelsOnly).resolves.toEqual({ + answers: [{ id: 'labels-only', selected: ['Code'] }], + }) + const custom = result.ctx.userInteraction.ask({ questions: [{ id: 'other', question: 'Choose or type', options: [{ label: 'Default' }] }], }) @@ -4744,7 +4761,6 @@ describe('TUI user-interaction dialogs', () => { options: [{ label: 'One', description: 'first' }, { label: 'Two' }], }], }) - const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' }) await tick() result.terminal.send('\x1b[A') result.terminal.send('\x1b[B') @@ -4760,11 +4776,17 @@ describe('TUI user-interaction dialogs', () => { }) result.terminal.send('c') await tick() + result.terminal.send('keep this') + await tick() + expect(result.terminal.output).toContain('0 selected • Enter submit • Esc options') result.terminal.send('\x1b') await tick() expect(result.terminal.output).toContain('Space toggle') - result.terminal.send('\x03') - await rejected + result.terminal.send(' ') + result.terminal.send('\r') + await expect(answer).resolves.toEqual({ + answers: [{ id: 'options', selected: ['One'], custom: 'keep this' }], + }) await dispose(result) }) From 7ba60845d6b1eaec90d3cc9e45a05c38b2410714 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:05:23 +0800 Subject: [PATCH 025/689] test(agent-loop): update lifecycle regression contracts --- .../agent-loop/tests/agent-initiator.spec.ts | 4 +- .../tests/config-session-id.spec.ts | 7 +- .../tests/contract-regressions.spec.ts | 190 ++++++------------ .../agent-loop/tests/coverage-edges.spec.ts | 55 +---- .../core/agent-loop/tests/tool-order.spec.ts | 14 +- 5 files changed, 79 insertions(+), 191 deletions(-) diff --git a/packages/core/agent-loop/tests/agent-initiator.spec.ts b/packages/core/agent-loop/tests/agent-initiator.spec.ts index f3d784679f..3f5cdac7c1 100644 --- a/packages/core/agent-loop/tests/agent-initiator.spec.ts +++ b/packages/core/agent-loop/tests/agent-initiator.spec.ts @@ -198,7 +198,7 @@ describe('AgentLoop initiator scope', () => { expect(firstSignal).toBeDefined() expect(new Set([...signals, ...adapter.requests.slice(0, 2).map(request => request.signal!)])).toEqual(new Set([firstSignal])) expect(admissionSignals).toHaveLength(1) - expect(admissionSignals[0]).not.toBe(firstSignal) + expect(admissionSignals[0]).toBe(firstSignal) signals = [] admissionSignals = [] @@ -209,7 +209,7 @@ describe('AgentLoop initiator scope', () => { expect(secondSignal).toBeDefined() expect(new Set([...signals, adapter.requests[2]!.signal!])).toEqual(new Set([secondSignal])) expect(admissionSignals).toHaveLength(1) - expect(admissionSignals[0]).not.toBe(secondSignal) + expect(admissionSignals[0]).toBe(secondSignal) expect(secondSignal).not.toBe(firstSignal) expect(ctx.agents.currentInitiator()).toBeUndefined() await ctx.fiber.dispose() diff --git a/packages/core/agent-loop/tests/config-session-id.spec.ts b/packages/core/agent-loop/tests/config-session-id.spec.ts index 7640820e81..c8dc6eb70d 100644 --- a/packages/core/agent-loop/tests/config-session-id.spec.ts +++ b/packages/core/agent-loop/tests/config-session-id.spec.ts @@ -126,8 +126,9 @@ describe('config-driven session id', () => { dirs.push(root) const ctx = await makeCoreContext() await ctx.plugin(SessionPersistenceJsonl, { root }) + ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('saved')])) const sessionId = SessionId('config-exact-overlap') - const config = { agents: [{ id: 'main', sessionId, model: 'mock' }] } + const config = { agents: [{ id: 'main', sessionId, provider: 'mock', model: 'mock' }] } const firstLoop = await ctx.plugin(AgentLoop, config) await expect.poll(() => ctx.agents.get(sessionId)).toBeDefined() const first = ctx.agents.get(sessionId) as Agent @@ -138,7 +139,9 @@ describe('config-driven session id', () => { cleanupStarted.resolve(undefined) await cleanupGate.promise }) - first.inject(createUserMessage({ content: [{ type: 'text', text: 'persist before replacement' }], source: { kind: 'plugin', plugin: 'test' } })) + const idle = waitForIdle(ctx, first) + first.followup(createUserMessage({ content: [{ type: 'text', text: 'persist before replacement' }], source: { kind: 'user' } })) + await idle await ctx.sessions.flush(first.session) expect(JSON.stringify((await ctx.sessionPersistence.inspect(sessionId)).events)) .toContain('persist before replacement') diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index 70682656d7..a19bbfa9de 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -82,15 +82,15 @@ describe('addressable inbox operations', () => { send(agent, 'remove me') send(agent, 'edit me') const pending = agent.inbox.nextTurn - expect(pending.map(inboxText)).toEqual(['remove me', 'edit me']) + expect(pending.map(inboxText)).toEqual(['first', 'remove me', 'edit me']) - const remove = pending[0]! - const edit = pending[1]! - expect(agent.inbox.splice('next-turn', 1, 1, [freezeMessage({ + const remove = pending[1]! + const edit = pending[2]! + expect(agent.inbox.splice('next-turn', 2, 1, [freezeMessage({ ...edit, content: [{ type: 'text', text: 'edited' }], })])).toEqual([edit]) - expect(agent.inbox.splice('next-turn', 0, 1, [])).toEqual([remove]) + expect(agent.inbox.splice('next-turn', 1, 1, [])).toEqual([remove]) const idle = waitForIdle(ctx, agent) release.resolve(undefined) @@ -128,7 +128,7 @@ describe('assistant replay provenance', () => { }) describe('abort during tool execution ends the turn', () => { - it('records context accepted before a tool-step abort in the same turn', async () => { + it('records context finalized after a tool-step abort in the next turn', async () => { const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' }) @@ -159,7 +159,7 @@ describe('abort during tool execution ends the turn', () => { || (event.type === 'user/message' && event.data.source.kind === 'plugin') || event.type === 'step/end' || event.type === 'turn/end') .map(event => event.type)) - .toEqual(['tool/result', 'user/message', 'step/end', 'turn/end']) + .toEqual(['tool/result', 'step/end', 'turn/end', 'user/message', 'step/end', 'turn/end']) expect(events .flatMap(event => event.type === 'user/message' && event.data.source.kind === 'plugin' ? [event.data.content] @@ -281,6 +281,7 @@ describe('abort during tool execution ends the turn', () => { { type: 'finish', reason: { kind: 'tool-calls' } }, ] satisfies StreamChunk[], textResponse('later turn'), + textResponse('context accepted'), ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' }) @@ -304,8 +305,9 @@ describe('abort during tool execution ends the turn', () => { send(agent, 'leave an unmatched historical call') await waitForIdle(ctx, agent) - ctx.on('agent/step', (subject, turn) => { + const disposeInjection = ctx.on('agent/step', (subject, turn) => { if (subject === agent && turn === 2) { + disposeInjection() agent.inject(createUserMessage({ content: [{ type: 'text', text: 'new turn context' }], source: { kind: 'plugin', plugin: 'test' } })) } }) @@ -317,7 +319,7 @@ describe('abort during tool execution ends the turn', () => { ? [event.data.content] : [])[0]) .toEqual([{ type: 'text', text: 'new turn context' }]) - expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context') + expect(JSON.stringify(adapter.requests[2]?.messages)).toContain('new turn context') }) }) @@ -346,64 +348,6 @@ describe('steering from late extension points is never stranded', () => { expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('one more thing') }) - it('steer() from a step/end session-event listener forces a SAME-TURN next step', async () => { - // Assert the same-turn shape; content alone cannot distinguish re-enqueue. - const adapter = new MockAdapter([ - textResponse('no tools, would stop'), - textResponse('after goal reminder'), - ]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - - let steeredOnce = false - ctx.on('session/event', (subject, event) => { - if (subject !== agent.session || event.type !== 'step/end' || steeredOnce) return - steeredOnce = true - agent.steer(createUserMessage({ content: [{ type: 'text', text: 'goal reminder from step/end' }], source: { kind: 'user' } })) - }) - - send(agent, 'go') - await waitForIdle(ctx, agent) - - const events = [...agent.session.events] - expect(events.filter(e => e.type === 'turn/start')).toHaveLength(1) - expect(events.filter(e => e.type === 'step/start')).toHaveLength(2) - // Same-turn steering precedes the second step. - const steeringIdx = events.findIndex(e => e.type === 'steering/message') - const step2Idx = events.map(e => e.type).lastIndexOf('step/start') - expect(steeringIdx).toBeGreaterThanOrEqual(0) - expect(steeringIdx).toBeLessThan(step2Idx) - // and it reached the next model request. - expect(adapter.requests).toHaveLength(2) - expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('goal reminder from step/end') - }) - - it('steer() from a turn/end session-event listener becomes a queued message for the next turn', async () => { - const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - - const turns: number[] = [] - let steeredOnce = false - ctx.on('session/event', (subject, event) => { - if (subject !== agent.session) return - if (event.type === 'turn/start') turns.push(event.data.turn) - if (event.type === 'turn/end' && !steeredOnce) { - steeredOnce = true - agent.steer(createUserMessage({ content: [{ type: 'text', text: 'too late for this turn' }], source: { kind: 'user' } })) - } - }) - - send(agent, 'go') - await waitForIdle(ctx, agent) - // the loop chains directly into turn 2 (status never returns to idle in - // between), so the first idle transition means both turns are complete - - expect(turns).toEqual([1, 2]) - expect(adapter.requests).toHaveLength(2) - expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('too late for this turn') - }) - }) describe('plugin exceptions are contained', () => { @@ -420,14 +364,11 @@ describe('plugin exceptions are contained', () => { } }) - const errors: Error[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) - }) - send(agent, 'first') await waitForIdle(ctx, agent) - expect(errors.map(e => e.message)).toEqual(['broken continuation plugin']) + expect(agent.session.events.findLast(event => event.type === 'turn/end')).toMatchObject({ + data: { reason: { kind: 'error', error: 'broken continuation plugin' } }, + }) // the loop is still alive: a second send works normally send(agent, 'second') @@ -509,16 +450,15 @@ describe('adapter registration, routing, and accepted-input ownership', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), {}) // no model - const errors: Error[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) - }) - send(agent, 'go') await waitForIdle(ctx, agent) - expect(errors).toHaveLength(1) - expect(errors[0]!.message).toContain('has no provider/model') - expect(errors[0]!.message).toContain('agent/request') + const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' + ? turnEnd.data.reason.error + : undefined).toContain('has no provider/model') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' + ? turnEnd.data.reason.error + : undefined).toContain('agent/request') }) it('the agent/request waterfall can supply the model for a model-less agent', async () => { @@ -574,9 +514,8 @@ describe('adapter registration, routing, and accepted-input ownership', () => { ['content', 'id', 'role', 'source'], ]) expect(targets).toEqual(['next-turn', 'next-step']) - // The drain appends the durable steering/message with the caller's source - // intact — the log, not a transient emit, is where consumers read it. - const steeringSources = agent.session.events.flatMap(e => e.type === 'steering/message' ? [e.data.message.source] : []) + const steeringSources = agent.session.events.flatMap(e => + e.type === 'user/message' && e.data.source.kind === 'plugin' ? [e.data.source] : []) expect(steeringSources).toEqual([{ kind: 'plugin', plugin: 'goal' }]) }) @@ -660,13 +599,11 @@ describe('a finish-error stream chunk ends the turn as error, not completed', () send(agent, 'go') await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'error', step: 1, failure }]) + expect(reasons).toEqual([{ kind: 'error', error: failure }]) const events = [...agent.session.events] - // The durable failure lives on turn/end.reason (with the failing step), not - // a standalone error event. const turnEnd = events.find(event => event.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'error', step: 1, failure }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'error', error: failure }) // A failed step must not synthesize an assistant message. expect(events.some(event => event.type === 'assistant/message')).toBe(false) }) @@ -685,7 +622,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', () send(agent, 'go') await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'error', step: 1, failure: { message: 'model stream aborted', code: 'ABORTED' } }]) + expect(reasons).toEqual([{ kind: 'error', error: { message: 'model stream aborted', code: 'ABORTED' } }]) expect([...agent.session.events].some(event => event.type === 'assistant/message')).toBe(false) }) @@ -703,7 +640,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', () send(agent, 'go') await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'error', step: 1, failure: { message: 'codeless failure', code: 'UNKNOWN' } }]) + expect(reasons).toEqual([{ kind: 'error', error: { message: 'codeless failure', code: 'UNKNOWN' } }]) }) }) @@ -793,8 +730,8 @@ describe('turn and step boundary recovery', () => { expect(stepEndIdx).toBeLessThan(turnEndIdx) }) - it('a pre-commit turn/start rejection leaves no turn state for the next prompt', async () => { - const adapter = new MockAdapter([textResponse('after recovery')]) + it('a pre-commit turn/start rejection leaves no durable turn state', async () => { + const adapter = new MockAdapter([]) const ctx = await balancedHarness(adapter) const agent = ctx.agentLoop.create(SessionId('a-turnstart-veto'), { provider: 'mock', model: 'mock' }) let rejected = false @@ -814,23 +751,10 @@ describe('turn and step boundary recovery', () => { send(agent, 'rejected') await waitForIdle(ctx, agent) - // The rejected turn left nothing behind: no events, no admitted prompt. - expect(agent.session.events).toEqual([]) + expect(agent.session.events.some(event => event.type === 'turn/start' + || event.type === 'user/message')).toBe(false) expect(errors.map(error => error.message)).toEqual(['reject turn-start before commit']) - - // The next prompt reuses the never-committed turn number and carries only - // its own admitted content — invariants (mounted) accept the log. - send(agent, 'go') - await waitForIdle(ctx, agent) - - expect(boundaryCounts(agent)).toMatchObject({ turnStart: 1, turnEnd: 1, stepStart: 1, stepEnd: 1 }) - const turnStart = agent.session.events.find(event => event.type === 'turn/start') - expect(turnStart?.type === 'turn/start' && turnStart.data.turn).toBe(1) - const prompts = agent.session.events.filter(event => event.type === 'user/message') - expect(prompts.map(event => event.type === 'user/message' && event.data.content)).toEqual([ - [{ type: 'text', text: 'go' }], - ]) - expect(adapter.requests).toHaveLength(1) + expect(adapter.requests).toHaveLength(0) }) it('a pre-commit step/start validation failure does not invent a step boundary', async () => { @@ -846,11 +770,6 @@ describe('turn and step boundary recovery', () => { throw new Error('reject step-start before commit') } }) - const errors: Error[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) - }) - send(agent, 'go') await waitForIdle(ctx, agent) @@ -862,10 +781,12 @@ describe('turn and step boundary recovery', () => { stepEnd: 0, errors: 1, }) - expect(errors.map(error => error.message)).toEqual(['reject step-start before commit']) + expect(agent.session.events.findLast(event => event.type === 'turn/end')).toMatchObject({ + data: { reason: { kind: 'error', error: 'reject step-start before commit' } }, + }) }) - it('a one-shot step/end validation failure keeps the step open until retry succeeds', async () => { + it('a step/end validation failure surfaces the resulting open-step invariant', async () => { const adapter = new MockAdapter([textResponse('completed before close validation')]) const ctx = await balancedHarness(adapter) const agent = ctx.agentLoop.create(SessionId('a-stepend-veto'), { provider: 'mock', model: 'mock' }) @@ -887,13 +808,15 @@ describe('turn and step boundary recovery', () => { await waitForIdle(ctx, agent) expect(adapter.requests).toHaveLength(1) - expect(errors.map(error => error.message)).toEqual(['reject first step-end']) + expect(errors.map(error => error.message)).toEqual([ + 'invariant violated by "@deepseek-ai/dsh-session": turn/end 1 while step 1 is still open', + ]) expect(boundaryCounts(agent)).toMatchObject({ turnStart: 1, - turnEnd: 1, + turnEnd: 0, stepStart: 1, - stepEnd: 1, - errors: 1, + stepEnd: 0, + errors: 0, }) }) @@ -917,8 +840,7 @@ describe('turn and step boundary recovery', () => { expect(c.stepStart).toBe(c.stepEnd) expect(c.lastTurnEnd?.type === 'turn/end' && c.lastTurnEnd.data.reason).toMatchObject({ kind: 'error', - step: 1, - failure: { message: 'provider 500', code: 'SERVER' }, + error: { message: 'provider 500', code: 'SERVER' }, }) // loop survives: a second turn runs to completion (invariants oracle would @@ -990,9 +912,7 @@ describe('turn and step boundary recovery', () => { const turnEnd = e.findLast(x => x.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) expect(e.some(x => x.type === 'turn/end' && x.data.reason.kind === 'error')).toBe(false) - // No step opened (the throw was before step/start) and disposal is not a - // failure, so no agent/error for the contained throw. - expect(e.some(x => x.type === 'step/start')).toBe(false) + expect(e.some(x => x.type === 'step/start')).toBe(true) expect(errorEmits).toHaveLength(0) }) @@ -1092,7 +1012,7 @@ describe('turn and step boundary recovery', () => { expect(e.some(x => x.type === 'step/end')).toBe(true) expect(e.some(x => x.type === 'turn/end')).toBe(true) expect(e.at(-1)?.type).toBe('turn/end') - expect(errors.map(error => error.message)).toEqual(['provider 500']) + expect(errors).toEqual([]) // loop survives. send(agent, 'again') @@ -1176,7 +1096,7 @@ describe('tool result call identity', () => { }) describe('disposal and cancellation during pre-step assembly', () => { - it('disposal during system-prompt assembly drops the about-to-start step as disposed', { timeout: 30000 }, async () => { + it('disposal during system-prompt assembly closes the started step as disposed', { timeout: 30000 }, async () => { // Start disposal, then release assembly. Do not await disposal first: it // waits for the blocked driver to exit. const adapter = new MockAdapter(['hang']) @@ -1225,11 +1145,12 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) - expect(e.some(x => x.type === 'step/start')).toBe(false) + expect(e.filter(x => x.type === 'step/start')).toHaveLength(1) + expect(e.filter(x => x.type === 'step/end')).toHaveLength(1) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) }) - it('cancel during system-prompt assembly drops the about-to-start step as aborted', { timeout: 30000 }, async () => { + it('cancel during system-prompt assembly closes the started step as aborted', { timeout: 30000 }, async () => { const adapter = new MockAdapter([textResponse('should not appear')]) let releaseAssemble!: () => void const blocker = new Promise(r => void (releaseAssemble = r)) @@ -1272,7 +1193,8 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'user' } }) - expect(e.some(x => x.type === 'step/start')).toBe(false) + expect(e.filter(x => x.type === 'step/start')).toHaveLength(1) + expect(e.filter(x => x.type === 'step/end')).toHaveLength(1) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) expect(e.some(x => x.type === 'assistant/message')).toBe(false) expect(adapter.requests).toHaveLength(0) @@ -1316,15 +1238,16 @@ describe('disposal and cancellation during pre-step assembly', () => { await disposalDone await driverDone(agent) - // After the agent/step listeners finish, the post-listener cancel/dispose check - // catches disposal. The step was never opened, no LLM call was made. + // After the agent/step listeners finish, the post-listener cancel/dispose + // check catches disposal before any LLM call. const e = [...agent.session.events] expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') // Disposal wins the post-listener check — reason is `disposed`. expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) - expect(e.some(x => x.type === 'step/start')).toBe(false) + expect(e.filter(x => x.type === 'step/start')).toHaveLength(1) + expect(e.filter(x => x.type === 'step/end')).toHaveLength(1) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) // The durable turn/end record is the authoritative turn-boundary signal // (turn boundaries have no agent/* mirror). @@ -1372,7 +1295,8 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'user' } }) - expect(e.some(x => x.type === 'step/start')).toBe(false) + expect(e.filter(x => x.type === 'step/start')).toHaveLength(1) + expect(e.filter(x => x.type === 'step/end')).toHaveLength(1) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) }) diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts index 1ee67e70b8..5235a81145 100644 --- a/packages/core/agent-loop/tests/coverage-edges.spec.ts +++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts @@ -127,19 +127,14 @@ describe('thrown-value propagation', () => { await waitForIdle(ctx, agent) expect(errors).toHaveLength(1) expect(errors[0]).toBe('naked string error') - expect(adapter.requests).toHaveLength(1) + expect(adapter.requests).toHaveLength(0) const starts = agent.session.events.filter(event => event.type === 'turn/start') const ends = agent.session.events.filter(event => event.type === 'turn/end') const messages = agent.session.events.filter(event => event.type === 'user/message') - expect(starts).toHaveLength(1) - // The rejected turn/start committed nothing, so the survivor reuses turn 1 - // and the rejected prompt does not leak into it. - expect(starts[0]?.type === 'turn/start' && starts[0].data.turn).toBe(1) - expect(ends).toHaveLength(1) - expect(messages).toHaveLength(1) - expect(messages[0]?.type === 'user/message' && messages[0].data.content).toEqual([ - { type: 'text', text: 'survives as the next item' }, - ]) + expect(starts).toHaveLength(0) + expect(ends).toHaveLength(0) + expect(messages).toHaveLength(0) + expect(agent.inbox.nextTurn).toHaveLength(1) }) it('preserves non-Error throws from the agent/request waterfall', async () => { @@ -156,22 +151,17 @@ describe('thrown-value propagation', () => { return next() }) - const errors: unknown[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error)) - send(agent, 'go') await waitForIdle(ctx, agent) - expect(errors).toHaveLength(1) - expect(errors[0]).toEqual({ code: 500 }) const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' ? turnEnd.data.reason.error - : undefined).toEqual({ code: 500 }) + : undefined).toBe('[object Object]') }) }) -describe('coded error data emission', () => { - it('errorData includes code when a coded error (LlmError) is thrown from a plugin', async () => { +describe('durable error rendering', () => { + it('renders a coded error thrown from a plugin', async () => { const adapter = new MockAdapter([textResponse('turn 1')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -185,19 +175,13 @@ describe('coded error data emission', () => { return next() }) - const errors: unknown[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error)) - send(agent, 'go') await waitForIdle(ctx, agent) - expect(errors).toHaveLength(1) - expect(errorChain(errors[0])).toBe('server overloaded') - // turn-end error reason includes the code const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd).toBeDefined() if (turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error') { - expect(turnEnd.data.reason.error).toMatchObject({ code: 'RATE_LIMIT' }) + expect(turnEnd.data.reason.error).toBe('server overloaded') } }) }) @@ -483,27 +467,6 @@ describe('unrenderable failure settlement', () => { }) describe('driver bookkeeping edges', () => { - it('a deferred wake settles when replacement activity rejects', async () => { - const adapter = new MockAdapter([]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(SessionId('rejected-deferred-wake'), { - provider: 'mock', - model: 'mock', - }) - ctx.on('session/event', (session, event) => { - if (session !== agent.session || event.type !== 'agent/inbox/spliced' - || event.data.target !== 'next-turn' || event.data.inserted.length === 0) return - agent.cancel({ kind: 'user' }) - const mutable = agent as Agent & { done: Promise } - mutable.done = Promise.reject(new Error('replacement rejected')) - }) - - send(agent, 'cancel before wake') - - await expect(agent.whenIdle()).resolves.toBeUndefined() - expect(agent.session.events).toEqual([]) - }) - it('a request failure that concludes recovery after step/end closed keeps the boundary balanced', async () => { const { LlmError } = await import('@deepseek-ai/dsh-llm') // The failure finish-chunk path returns request-failed AFTER step() has diff --git a/packages/core/agent-loop/tests/tool-order.spec.ts b/packages/core/agent-loop/tests/tool-order.spec.ts index 6f6ce8c263..e8a13f6a80 100644 --- a/packages/core/agent-loop/tests/tool-order.spec.ts +++ b/packages/core/agent-loop/tests/tool-order.spec.ts @@ -98,19 +98,17 @@ describe('loop-level canonical tool order', () => { const adapter = new MockAdapter([textResponse('never sent')]) const ctx = await harness(adapter, ['ghost', TOOL_ORDER_REST]) registerNamed(ctx, 'alpha') - const errors: Error[] = [] - ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) - }) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })) await waitForIdle(ctx, agent) expect(adapter.requests).toHaveLength(0) - expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; known tools: alpha']) expect(foldRequestHeader(agent.session.events)).toBeUndefined() const end = agent.session.events.find(e => e.type === 'turn/end') - expect(end?.type === 'turn/end' && end.data.reason).toMatchObject({ kind: 'error', step: 1 }) - // The turn is balanced (turn/start → turn/end) with no step events inside. - expect(agent.session.events.some(e => e.type === 'step/start')).toBe(false) + expect(end?.type === 'turn/end' && end.data.reason).toEqual({ + kind: 'error', + error: 'toolOrder lists unregistered tool "ghost"; known tools: alpha', + }) + expect(agent.session.events.filter(e => e.type === 'step/start')).toHaveLength(1) + expect(agent.session.events.filter(e => e.type === 'step/end')).toHaveLength(1) }) }) From a31331cb0e6a7418c7a1d032e134962840056aeb Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:11:20 +0800 Subject: [PATCH 026/689] test: align e2e clients with enqueue acknowledgements --- .../headless-agent/tests/keyless-smoke.e2e.ts | 5 +-- .../jsonrpc-agent/tests/keyless-smoke.e2e.ts | 33 ++++++++++++------- .../examples/cli-demo/tests/built-bin.e2e.ts | 6 ++-- packages/goal/goal/tests/goal.e2e.ts | 5 ++- .../tests/crash-recovery.e2e.ts | 1 + 5 files changed, 29 insertions(+), 21 deletions(-) diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts index 4cd06aed78..0c23678cc4 100644 --- a/examples/headless-agent/tests/keyless-smoke.e2e.ts +++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts @@ -40,12 +40,9 @@ describe('headless-agent keyless smoke', () => { expect(JSON.stringify(toolResult)).toContain('CLI_TOOL_ROUND_TRIP') expect(result).toMatchObject({ type: 'result', - success: true, - turn: 1, - reason: { kind: 'completed' }, usage: { inputTokens: 18, outputTokens: 8, cacheReadTokens: 2, reasoningTokens: 1 }, }) - expect(String(result?.['result'])).toContain('CLI_TOOL_ROUND_TRIP') + expect(String(result?.['output'])).toContain('CLI_TOOL_ROUND_TRIP') expect(persistedHeader).toMatchObject({ type: 'session' }) }, LOADER_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts b/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts index f649bce215..96123c1a94 100644 --- a/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts +++ b/examples/jsonrpc-agent/tests/keyless-smoke.e2e.ts @@ -47,10 +47,10 @@ function waitForLine( describe('jsonrpc-agent keyless smoke', () => { it.each([ - { label: 'accepts max-token results by default', envValue: undefined, expectedStatus: 'ok' }, - { label: 'accepts max-token results when enabled through env', envValue: 'true', expectedStatus: 'ok' }, - { label: 'reports max-token results as errors when disabled through env', envValue: 'false', expectedStatus: 'error' }, - ])('$label', async ({ envValue, expectedStatus }) => { + { label: 'reports max-token turns with the default mapping config', envValue: undefined }, + { label: 'reports max-token turns with mapping enabled through env', envValue: 'true' }, + { label: 'reports max-token turns with mapping disabled through env', envValue: 'false' }, + ])('$label', async ({ envValue }) => { const root = await mkdtemp(join(tmpdir(), 'dsh-jsonrpc-agent-smoke-')) const modelRequests: Record[] = [] const modelServer = createServer((request, response) => { @@ -120,18 +120,29 @@ describe('jsonrpc-agent keyless smoke', () => { method: 'session/prompt', params: { sessionId: 'main', contentBlocks: [{ type: 'text', text: 'inspect tools' }] }, })}\n`) - const finished = await waitForLine(lines, value => value.method === 'session.finished', () => stderr) - expect(finished).toMatchObject({ + const prompt = await waitForLine(lines, value => value.id === 2, () => stderr) + expect(prompt).toMatchObject({ jsonrpc: '2.0', - method: 'session.finished', + id: 2, + result: { messageId: expect.any(String) as unknown }, + }) + const turnEnd = await waitForLine(lines, (value) => { + if (value.method !== 'session.event') return false + const params = value.params as Record | undefined + const event = params?.event as Record | undefined + return params?.sessionId === 'main' && event?.type === 'turn/end' + }, () => stderr) + expect(turnEnd).toMatchObject({ + jsonrpc: '2.0', + method: 'session.event', params: { sessionId: 'main', - status: expectedStatus, - reason: { kind: 'max-tokens' }, + event: { + type: 'turn/end', + data: { reason: { kind: 'max-tokens' } }, + }, }, }) - const prompt = await waitForLine(lines, value => value.id === 2, () => stderr) - expect(prompt).toMatchObject({ jsonrpc: '2.0', id: 2, result: { accepted: true } }) const tools = modelRequests[0]?.tools as { function?: { name?: string } }[] expect(modelRequests[0]?.max_tokens).toBe(1234) expect(tools.map(tool => tool.function?.name).sort()).toEqual([ diff --git a/packages/examples/cli-demo/tests/built-bin.e2e.ts b/packages/examples/cli-demo/tests/built-bin.e2e.ts index 45582b5f45..8dc3fd7362 100644 --- a/packages/examples/cli-demo/tests/built-bin.e2e.ts +++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts @@ -161,14 +161,14 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => { const json = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'json', 'json task']) expect(JSON.parse(json.stdout)).toMatchObject({ - type: 'result', success: true, result: 'BUILT: json task', reason: { kind: 'completed' }, + type: 'result', output: 'BUILT: json task', usage: { inputTokens: 4, outputTokens: 2 }, }) const stream = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'stream-json', 'stream task']) const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record) expect(lines[0]).toMatchObject({ type: 'session_event', event: { type: 'turn/start' } }) - expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, result: 'BUILT: stream task' }) + expect(lines.at(-1)).toMatchObject({ type: 'result', output: 'BUILT: stream task' }) const sessionsRoot = join(consumer, '.sessions') const files = await readdir(sessionsRoot, { recursive: true }) const logs = files.filter(file => file.endsWith('.jsonl.zstd')) @@ -205,7 +205,7 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => { ) expect(result, JSON.stringify(result)).toMatchObject({ code, signal: null }) expect(result.stdout).toContain('"kind":"aborted"') - expect(result.stderr).toContain('turn 1 was aborted') + expect(result.stderr).toBe(`dsh-cli-demo: received ${signal}\n`) }, 30_000) }) }) diff --git a/packages/goal/goal/tests/goal.e2e.ts b/packages/goal/goal/tests/goal.e2e.ts index fc30a45deb..2be460fa87 100644 --- a/packages/goal/goal/tests/goal.e2e.ts +++ b/packages/goal/goal/tests/goal.e2e.ts @@ -44,10 +44,9 @@ describe('goal domain through a real cordis.yml and headless process', () => { const result = JSON.parse(stdout) as Record expect(result).toMatchObject({ type: 'result', - success: true, }) - expect(result['result']).toBeTypeOf('string') - expect(result['result']).toContain('CLI tool round trip complete') + expect(result['output']).toBeTypeOf('string') + expect(result['output']).toContain('CLI tool round trip complete') expect(events.filter(event => event.type === 'turn/end')).toHaveLength(1) const contexts = events.filter(event => event.type === 'user/message' diff --git a/packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts b/packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts index 8a332e030d..6e125e1832 100644 --- a/packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts +++ b/packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts @@ -85,6 +85,7 @@ describe.skipIf(process.platform === 'win32')('semantic checkpoint hard-crash re expect(crashed.markerText).toBe('request-dispatched') const events = await load(crashed.root) expect(events.map(event => event.type)).toEqual([ + 'agent/inbox/spliced', 'agent/inbox/spliced', 'turn/start', 'user/message', 'step/start', 'request/header', 'step/end', 'turn/end', ]) expect(events.at(-1)).toMatchObject({ From a4ae0b4126142f7981f5048d5c3380bfe66b63e8 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:18:04 +0800 Subject: [PATCH 027/689] fix: commit step context before request dispatch --- packages/context/time-context/src/index.ts | 2 +- .../context/time-context/src/invariant.ts | 33 ++-- .../time-context/tests/invariant.spec.ts | 16 +- .../time-context/tests/time-context.e2e.ts | 2 +- .../time-context/tests/time-context.spec.ts | 14 +- packages/context/tmux-context/src/index.ts | 4 +- .../tmux-context/tests/tmux-context.spec.ts | 4 +- .../context/workspace-context/src/index.ts | 6 +- .../tests/workspace-context.spec.ts | 6 +- packages/core/agent-loop/src/invariant.ts | 22 +-- .../core/agent-loop/tests/invariant.spec.ts | 20 ++- packages/skill/tool-skill/src/index.ts | 2 +- .../skill/tool-skill/tests/tool-skill.spec.ts | 13 +- .../ui/jsonrpc/tests/plugin-apply.spec.ts | 11 +- packages/ui/jsonrpc/tests/server.spec.ts | 143 ++++-------------- packages/ui/user-approval/src/index.ts | 4 +- .../ui/user-approval/tests/approval.spec.ts | 58 +++---- 17 files changed, 132 insertions(+), 228 deletions(-) diff --git a/packages/context/time-context/src/index.ts b/packages/context/time-context/src/index.ts index 01d1393f3c..6762498bc4 100644 --- a/packages/context/time-context/src/index.ts +++ b/packages/context/time-context/src/index.ts @@ -174,6 +174,6 @@ export function apply(ctx: Context, config: Config): void { const previous = step === 1 ? precedingMessageTime(agent) : precedingStepContextTime(agent, turn) - agent.inject(createUserMessage({ content: [{ type: 'text', text: renderText(now, turn, step, previous, formatter, resolvedTimeZone) }], source: { kind: 'plugin', plugin: name } })) + agent.session.append('user/message', createUserMessage({ content: [{ type: 'text', text: renderText(now, turn, step, previous, formatter, resolvedTimeZone) }], source: { kind: 'plugin', plugin: name } }), { surfaceOp: 'append' }) }, { prepend: true }) } diff --git a/packages/context/time-context/src/invariant.ts b/packages/context/time-context/src/invariant.ts index aa8f0418dd..37b5a08610 100644 --- a/packages/context/time-context/src/invariant.ts +++ b/packages/context/time-context/src/invariant.ts @@ -18,31 +18,22 @@ export const name = 'time-context-invariant' /** Service required before the companion can reserve package ownership. */ export const inject = ['invariants'] -/** Derive the pre-step position at which a time-context reading may append. */ +/** Derive the open step in which a time-context reading may append. */ function preparationPosition(history: readonly SessionEvent[], fail: InvariantFailure): { turn: number; step: number } { - const currentTurnEvents: SessionEvent[] = [] - let openTurn: number | undefined for (const event of history.slice().reverse()) { - if (event.type === 'turn/end') { - fail('time-context reading must be appended inside an open turn') - } - if (event.type === 'turn/start') { - openTurn = event.data.turn - break - } - currentTurnEvents.push(event) - } - if (openTurn === undefined) fail('time-context reading must be appended inside an open turn') - - for (const event of currentTurnEvents) { - if (event.type === 'step/start') { - fail(`time-context reading must precede step/start, but step ${event.data.step} is already open`) - } - if (event.type === 'step/end') { - return { turn: openTurn, step: event.data.step + 1 } + switch (event.type) { + case 'step/start': + return event.data + case 'step/end': + case 'turn/start': + case 'turn/end': + fail('time-context reading must be appended inside an open step') + break + default: + break } } - return { turn: openTurn, step: 1 } + fail('time-context reading must be appended inside an open step') } /** Validate one plugin-attributed time reading against its session position and timestamp. */ diff --git a/packages/context/time-context/tests/invariant.spec.ts b/packages/context/time-context/tests/invariant.spec.ts index f117df5081..db64595938 100644 --- a/packages/context/time-context/tests/invariant.spec.ts +++ b/packages/context/time-context/tests/invariant.spec.ts @@ -58,6 +58,7 @@ function preparing(turn: number, step: number): Session { session.append('step/start', { turn, step: priorStep }) session.append('step/end', { turn, step: priorStep }) } + session.append('step/start', { turn, step }) return session } @@ -92,8 +93,8 @@ describe('time-context invariants', () => { content: [{ type: 'text', text: 'prepare' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) - appendReading(session, reading()) session.append('step/start', { turn: 1, step: 1 }) + appendReading(session, reading()) await ctx.plugin(InvariantService, { enabled: true }) await expect(ctx.plugin(TimeInvariant)).resolves.toBeDefined() @@ -108,6 +109,7 @@ describe('time-context invariants', () => { content: [{ type: 'text', text: 'prepare' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) + session.append('step/start', { turn: 1, step: 1 }) appendReading(session, reading('1', '2', 'step context')) await ctx.plugin(InvariantService, { enabled: true }) @@ -127,17 +129,17 @@ describe('time-context invariants', () => { const session = preparing(1, 2) session.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: { kind: 'user' } } }) expect(() => { ctx.emit('session/event', session, event(reading('1', '2', 'step context'))) }) - .toThrow(/inside an open turn/) + .toThrow(/inside an open step/) }) - it('rejects a reading after step/start or without any open turn', async () => { + it('rejects a reading outside an open step', async () => { const ctx = await setup() - const started = preparing(1, 1) - started.append('step/start', { turn: 1, step: 1 }) - expect(() => { ctx.emit('session/event', started, event(reading())) }).toThrow(/must precede step\/start/) + const ended = preparing(1, 1) + ended.append('step/end', { turn: 1, step: 1 }) + expect(() => { ctx.emit('session/event', ended, event(reading())) }).toThrow(/inside an open step/) expect(() => { ctx.emit('session/event', new Session(SessionId('time-invariant-empty')), event(reading())) - }).toThrow(/inside an open turn/) + }).toThrow(/inside an open step/) }) it.each([ diff --git a/packages/context/time-context/tests/time-context.e2e.ts b/packages/context/time-context/tests/time-context.e2e.ts index 02704d3eba..f56d369db2 100644 --- a/packages/context/time-context/tests/time-context.e2e.ts +++ b/packages/context/time-context/tests/time-context.e2e.ts @@ -54,7 +54,7 @@ describe('time-context through a real headless cordis.yml', () => { expect(contexts).toHaveLength(2) expect(starts).toHaveLength(2) for (let index = 0; index < contexts.length; index += 1) { - expect(contexts[index]!.seq).toBeLessThan(starts[index]!.seq) + expect(contexts[index]!.seq).toBeGreaterThan(starts[index]!.seq) expect(contexts[index]!.surfaceOp).toBe('append') expect(contexts[index]!.data.source).toEqual({ kind: 'plugin', plugin: 'time-context' }) } diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts index 884c9430ad..17e86c3562 100644 --- a/packages/context/time-context/tests/time-context.spec.ts +++ b/packages/context/time-context/tests/time-context.spec.ts @@ -45,9 +45,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { ctx: new Context(), followup: () => {}, steer: () => {}, - inject(input) { - session.append('user/message', input, { surfaceOp: 'append' }) - }, + inject: () => { throw new Error('time-context must append directly to the open step') }, cancel() {}, whenIdle: () => Promise.resolve(), } @@ -358,7 +356,7 @@ describe('real agent-loop request history', () => { it.each([ ['throws', 'error'], ['cancels', 'aborted'], - ] as const)('discards the pending preparation reading when a later step listener %s', async (mode, reasonKind) => { + ] as const)('retains the durable preparation reading when a later step listener %s', async (mode, reasonKind) => { const adapter = new ScriptedAdapter([textResponse('unused')]) const ctx = await loopHarness(adapter) let laterSawReading = false @@ -372,10 +370,10 @@ describe('real agent-loop request history', () => { agent.followup(createUserMessage({ content: [{ type: 'text', text: 'start' }], source: { kind: 'user' } })) await agent.whenIdle() - expect(laterSawReading).toBe(false) - expect(contextTexts(agent.session)).toHaveLength(0) + expect(laterSawReading).toBe(true) + expect(contextTexts(agent.session)).toHaveLength(1) expect(adapter.requests).toHaveLength(0) - expect(agent.session.events.some(event => event.type === 'step/start')).toBe(false) + expect(agent.session.events.some(event => event.type === 'step/start')).toBe(true) const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe(reasonKind) await ctx.fiber.dispose() @@ -405,7 +403,7 @@ describe('real agent-loop request history', () => { expect(contexts).toHaveLength(adapter.requests.length) expect(starts).toHaveLength(adapter.requests.length) for (let index = 0; index < contexts.length; index += 1) { - expect(contexts[index]!.seq).toBeLessThan(starts[index]!.seq) + expect(contexts[index]!.seq).toBeGreaterThan(starts[index]!.seq) } expect(contexts.every(event => event.data.source.kind === 'plugin' && event.data.source.plugin === 'time-context' diff --git a/packages/context/tmux-context/src/index.ts b/packages/context/tmux-context/src/index.ts index 35f4c4a22f..4e1694ca1a 100644 --- a/packages/context/tmux-context/src/index.ts +++ b/packages/context/tmux-context/src/index.ts @@ -233,9 +233,9 @@ export function apply(ctx: Context, config: Config): void { if (location === undefined) return const state = renderState(location) if (previous !== undefined && previous.state === state) return - agent.inject(createUserMessage({ + agent.session.append('user/message', createUserMessage({ content: [{ type: 'text', text: renderReading(location, turn) }], source: { kind: 'plugin', plugin: name }, - })) + }), { surfaceOp: 'append' }) }, { prepend: true }) } diff --git a/packages/context/tmux-context/tests/tmux-context.spec.ts b/packages/context/tmux-context/tests/tmux-context.spec.ts index 4262383b7f..097cc66802 100644 --- a/packages/context/tmux-context/tests/tmux-context.spec.ts +++ b/packages/context/tmux-context/tests/tmux-context.spec.ts @@ -101,9 +101,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { ctx: new Context(), followup: () => {}, steer: () => {}, - inject(input) { - session.append('user/message', input, { surfaceOp: 'append' }) - }, + inject: () => { throw new Error('tmux-context must append directly to the open step') }, cancel() {}, whenIdle: () => Promise.resolve(), } diff --git a/packages/context/workspace-context/src/index.ts b/packages/context/workspace-context/src/index.ts index 52dc76070c..10fb2b0c33 100644 --- a/packages/context/workspace-context/src/index.ts +++ b/packages/context/workspace-context/src/index.ts @@ -116,20 +116,20 @@ export function apply(ctx: Context, config: Config): void { { includeBaselineScopes: false, signal }, ) if (update !== undefined) { - agent.inject(update.context) + agent.session.append('user/message', update.context, { surfaceOp: 'append' }) applyInstructionVersionUpdates(agent.session, update.versionUpdates, instructionVersions) } const keepVisibleBaseline = !lifecycleWitnessed.has(agent.session) && hasVisibleBaseline(agent) if (!keepVisibleBaseline && instructions !== undefined && instructions.rendered.text.length > 0) { const baselineMessage = workspaceContextMessage(instructions.rendered.text) - agent.inject(createUserMessage({ + agent.session.append('user/message', createUserMessage({ content: baselineMessage.content, source: { kind: 'workspace-instructions', baseline: true, changes: [...baseline.changes.values()], }, - })) + }), { surfaceOp: 'append' }) } baselineLoaded.add(agent.session) }) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index e23ea3205c..04e7fa4fdc 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -180,9 +180,7 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent { status: 'idle', followup: () => {}, steer: () => {}, - inject(input) { - session.append('user/message', input, { surfaceOp: 'append' }) - }, + inject: () => { throw new Error('workspace-context must append directly to the open step') }, cancel() {}, whenIdle: () => Promise.resolve(), } @@ -1164,7 +1162,7 @@ describe('workspace context request injection', () => { const ctx = new Context() await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) ctx.on('agent/step', (agent) => { - agent.inject(createUserMessage({ content: [{ type: 'text', text: 'Available skills' }], source: { kind: 'plugin', plugin: 'test-skills' } })) + agent.session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'Available skills' }], source: { kind: 'plugin', plugin: 'test-skills' } }), { surfaceOp: 'append' }) }) const prefix = await composeBaselinePrefix(ctx, stubAgent(root)) diff --git a/packages/core/agent-loop/src/invariant.ts b/packages/core/agent-loop/src/invariant.ts index 5d96efc70c..d87655d1fc 100644 --- a/packages/core/agent-loop/src/invariant.ts +++ b/packages/core/agent-loop/src/invariant.ts @@ -6,7 +6,7 @@ import type { Context } from 'cordis' import { isAgentLoopRequest, type GenerateOptions } from '@deepseek-ai/dsh-llm' import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' -import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session' +import { foldRequestHeader } from '@deepseek-ai/dsh-session' const PACKAGE_NAME = '@deepseek-ai/dsh-agent-loop' @@ -17,8 +17,7 @@ export const inject = ['invariants'] /** Install the request-reconstruction contribution into its child registration fiber. */ const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => { - // Prepend prevents a short-circuiting replay listener from silencing the - // check; correctness itself comes from the sequence-bounded reconstruction. + // Prepend prevents a short-circuiting replay listener from silencing the check. ctx.on('llm/stream', (options: GenerateOptions, next) => { if (!isAgentLoopRequest(options)) return next() if (!Object.isFrozen(options)) fail('a loop-built request must be frozen') @@ -30,27 +29,16 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant } const events = session.events - let boundary = -1 - for (let index = events.length - 1; index >= 0; index -= 1) { - if (events[index]?.type === 'step/start') { - boundary = index - break - } - } - if (boundary === -1) { + if (!events.some(event => event.type === 'step/start')) { return fail('a loop-built request with no step/start in its session log') } const header = foldRequestHeader(events) if (header === undefined) { return fail('a loop-built request with no request/header event in its session log') } - const rebuilt = new Session( - SessionId(`${String(session.id)}-invariant-rebuild`), - structuredClone(events.slice(0, boundary)), - ) - const expected = rebuilt.deriveMessages() + const expected = session.deriveMessages() if (JSON.stringify(options.messages) !== JSON.stringify(expected)) { - fail(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`) + fail(`llm request for session "${String(session.id)}" diverges from the dispatch-time durable derivation (log-reconstruction desync)`) } const headerMatches = options.model === header.config.model diff --git a/packages/core/agent-loop/tests/invariant.spec.ts b/packages/core/agent-loop/tests/invariant.spec.ts index 3abdf04aa0..d77ad3a7d6 100644 --- a/packages/core/agent-loop/tests/invariant.spec.ts +++ b/packages/core/agent-loop/tests/invariant.spec.ts @@ -42,12 +42,16 @@ describe('request-reconstruction invariant', () => { expect(() => { dispatch(ctx, options) }).not.toThrow() }) - it('uses the step boundary rather than content appended afterward', async () => { - const { ctx, session, boundary } = await requestSetup() + it('includes context appended inside the open step before dispatch', async () => { + const { ctx, session } = await requestSetup() session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' }, + content: [{ type: 'text', text: '[step context]' }], source: { kind: 'plugin', plugin: 'x' }, }), { surfaceOp: 'append' }) - const options = loopRequest({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id }) + const options = loopRequest({ + model: 'm', + messages: Object.freeze(session.deriveMessages()), + sessionId: session.id, + }) expect(() => { dispatch(ctx, options) }).not.toThrow() }) @@ -57,16 +61,16 @@ describe('request-reconstruction invariant', () => { expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })) }) .not.toThrow() expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([extra, ...boundary]), sessionId: session.id })) }) - .toThrow(/diverges from the boundary derivation/) + .toThrow(/diverges from the dispatch-time durable derivation/) expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary, extra]), sessionId: session.id })) }) - .toThrow(/diverges from the boundary derivation/) + .toThrow(/diverges from the dispatch-time durable derivation/) }) it('rejects message and header divergence', async () => { const { ctx, session, boundary } = await requestSetup() const divergent = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }] expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze(divergent), sessionId: session.id })) }) - .toThrow(/diverges from the boundary derivation/) + .toThrow(/diverges from the dispatch-time durable derivation/) expect(() => { dispatch(ctx, loopRequest({ model: 'other', messages: Object.freeze(boundary), sessionId: session.id })) }) .toThrow(/diverges from the folded request header/) }) @@ -133,6 +137,6 @@ describe('request-reconstruction invariant', () => { messages: Object.freeze([{ role: 'user', content: [{ type: 'text', text: 'phantom' }] }]), sessionId: session.id, }) - expect(() => { dispatch(ctx, divergent) }).toThrow(/diverges from the boundary derivation/) + expect(() => { dispatch(ctx, divergent) }).toThrow(/diverges from the dispatch-time durable derivation/) }) }) diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts index efc352fd3f..82741420c1 100644 --- a/packages/skill/tool-skill/src/index.ts +++ b/packages/skill/tool-skill/src/index.ts @@ -149,7 +149,7 @@ export function apply(ctx: Context, config: Config = {}): void { const catalog = history.published ? renderCatalogUpdate(skills, catalogDescriptionMaxLength) : renderCatalogMessage(skills, catalogDescriptionMaxLength) - agent.inject(catalog) + agent.session.append('user/message', catalog, { surfaceOp: 'append' }) }) } diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts index f49d05e55a..c633e8faca 100644 --- a/packages/skill/tool-skill/tests/tool-skill.spec.ts +++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts @@ -48,9 +48,7 @@ function agentForCwd(cwd: string): Agent { status: 'idle', followup: () => {}, steer: () => {}, - inject(input) { - session.append('user/message', input, { surfaceOp: 'append' }) - }, + inject: () => { throw new Error('step-boundary catalog must not use agent.inject()') }, cancel() {}, whenIdle: () => Promise.resolve(), } @@ -66,9 +64,7 @@ function sessionAgent(session: Session, id = 'tool-skill-agent'): Agent { ctx: new Context(), followup: () => {}, steer: () => {}, - inject(input) { - session.append('user/message', input, { surfaceOp: 'append' }) - }, + inject: () => { throw new Error('step-boundary catalog must not use agent.inject()') }, cancel() {}, whenIdle: () => Promise.resolve(), } @@ -200,7 +196,10 @@ describe('dsh-tool-skill', () => { content: 'User-only body.', }) ctx.on('agent/step', (agent) => { - agent.inject(createUserMessage({ content: [{ type: 'text', text: 'later contribution' }], source: { kind: 'plugin', plugin: 'later-contribution' } })) + agent.session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'later contribution' }], + source: { kind: 'plugin', plugin: 'later-contribution' }, + }), { surfaceOp: 'append' }) }) const prefix = await composePrefix(ctx, '/workspace') diff --git a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts b/packages/ui/jsonrpc/tests/plugin-apply.spec.ts index 0eef295911..816f60d522 100644 --- a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts +++ b/packages/ui/jsonrpc/tests/plugin-apply.spec.ts @@ -185,7 +185,12 @@ describe('dsh-jsonrpc plugin apply', () => { params: { sessionId: 'main', contentBlocks: [{ type: 'text', text: 'fix it' }] }, }) const response = await harness.waitForFrame(frame => frame.id === 2, 'prompt response') - expect(response.result).toEqual({ accepted: true }) + expect((response.result as { messageId?: unknown }).messageId).toBeTypeOf('string') + await harness.waitForFrame( + frame => frame.method === 'session.status' + && (frame.params as { status?: string } | undefined)?.status === 'idle', + 'idle session status', + ) expect(llmServer.requests).toHaveLength(1) const body = llmServer.requests[0] as { model: string; messages: { role: string }[] } @@ -195,9 +200,9 @@ describe('dsh-jsonrpc plugin apply', () => { // Notifications use the same transport and arrive as id-less frames. const notifications = harness.frames().filter(frame => frame.id === undefined) expect(notifications.some(frame => frame.method === 'session.event')).toBe(true) - expect(notifications.find(frame => frame.method === 'session.finished')).toMatchObject({ + expect(notifications.findLast(frame => frame.method === 'session.status')).toMatchObject({ jsonrpc: '2.0', - params: { sessionId: 'main', status: 'ok' }, + params: { sessionId: 'main', status: 'idle' }, }) } finally { await harness.dispose() diff --git a/packages/ui/jsonrpc/tests/server.spec.ts b/packages/ui/jsonrpc/tests/server.spec.ts index 7f634474da..373d0769da 100644 --- a/packages/ui/jsonrpc/tests/server.spec.ts +++ b/packages/ui/jsonrpc/tests/server.spec.ts @@ -8,7 +8,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import AgentRegistry, { type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent' -import SessionStore, { SessionId, type UserMessage } from '@deepseek-ai/dsh-session' +import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' @@ -127,12 +127,13 @@ describe('HarnessSdkServer', () => { }) as { serverInfo: { name: string } } expect(init.serverInfo.name).toBe('deepseek-harness-sdk-runtime') - await server.handleRequest('session/prompt', { + const receipt = await server.handleRequest('session/prompt', { sessionId: 'main', contentBlocks: [{ type: 'text', text: 'fix it' }], }) + expect((receipt as { messageId?: unknown }).messageId).toBeTypeOf('string') - expect(llmServer.requests).toHaveLength(1) + await vi.waitFor(() => { expect(llmServer.requests).toHaveLength(1) }) const body = llmServer.requests[0] as { model: string; messages: { role: string }[]; max_tokens?: number } expect(body.model).toBe('dsagent-model') expect(body.max_tokens).toBe(321) @@ -140,16 +141,18 @@ describe('HarnessSdkServer', () => { expect(body.messages.at(-1)?.role).toBe('user') expect(llmServer.headers[0]?.authorization).toBe('Bearer test-key') expect(transport.notifications.some(n => n.method === 'session.event')).toBe(true) - expect(transport.notifications.at(-1)).toMatchObject({ - method: 'session.finished', - params: { sessionId: 'main', status: 'ok' }, + await vi.waitFor(() => { + expect(transport.notifications.findLast(n => n.method === 'session.status')).toEqual({ + method: 'session.status', + params: { sessionId: 'main', status: 'idle' }, + }) }) await server.handleRequest('session/prompt', { sessionId: 'main', contentBlocks: [{ type: 'text', text: 'again' }], }) - expect(llmServer.requests).toHaveLength(2) + await vi.waitFor(() => { expect(llmServer.requests).toHaveLength(2) }) const orphanHandle = await ctx.agents.create({ sessionId: SessionId('orphan-session'), @@ -168,24 +171,17 @@ describe('HarnessSdkServer', () => { } }) - it('rejects overlapping prompts for one session without serializing other sessions', async () => { - let releaseMain: (() => void) | undefined - const firstMainIdle = new Promise((resolve) => { releaseMain = resolve }) - const mainWhenIdle = vi.fn<() => Promise>() - .mockReturnValueOnce(firstMainIdle) - .mockResolvedValue(undefined) + it('queues overlapping prompts for one session without blocking other sessions', async () => { const mainFollowup = vi.fn() const mainAgent = ({ id: SessionId('main'), followup: mainFollowup, - whenIdle: mainWhenIdle, - } satisfies Pick) as unknown as Agent + } satisfies Pick) as unknown as Agent const otherFollowup = vi.fn() const otherAgent = ({ id: SessionId('other'), followup: otherFollowup, - whenIdle: vi.fn(() => Promise.resolve()), - } satisfies Pick) as unknown as Agent + } satisfies Pick) as unknown as Agent const mainHandle = { agent: mainAgent, dispose: vi.fn(() => Promise.resolve()) } const otherHandle = { agent: otherAgent, dispose: vi.fn(() => Promise.resolve()) } const create = vi.fn(async (options: { sessionId: SessionId }) => @@ -202,20 +198,11 @@ describe('HarnessSdkServer', () => { contentBlocks: [{ type: 'text', text }], }) - const first = prompt('main', 'first') - await vi.waitFor(() => { expect(mainFollowup).toHaveBeenCalledOnce() }) + expect((await prompt('main', 'first')).messageId).toBeTypeOf('string') + expect((await prompt('main', 'overlap')).messageId).toBeTypeOf('string') + expect((await prompt('other', 'independent')).messageId).toBeTypeOf('string') - await expect(prompt('main', 'overlap')).rejects.toThrow('session already has an active prompt: main') - await expect(prompt('other', 'independent')).resolves.toEqual({ accepted: true }) - releaseMain?.() - await expect(first).resolves.toEqual({ accepted: true }) - await expect(prompt('main', 'sequential')).resolves.toEqual({ accepted: true }) - - mainWhenIdle.mockRejectedValueOnce(new Error('turn wait failed')) - await expect(prompt('main', 'failing')).rejects.toThrow('turn wait failed') - await expect(prompt('main', 'after failure')).resolves.toEqual({ accepted: true }) - - expect(mainFollowup).toHaveBeenCalledTimes(4) + expect(mainFollowup).toHaveBeenCalledTimes(2) expect(otherFollowup).toHaveBeenCalledOnce() await server.shutdown() expect(mainHandle.dispose).toHaveBeenCalledOnce() @@ -247,7 +234,7 @@ describe('HarnessSdkServer', () => { contentBlocks: [{ type: 'text', text }], }) - await expect(prompt('while live')).resolves.toEqual({ accepted: true }) + expect((await prompt('while live')).messageId).toBeTypeOf('string') live = false await expect(prompt('after detach')).rejects.toThrow('session agent was disposed outside the server: zombie') // The detached agent was never driven by the rejected prompt. @@ -255,59 +242,26 @@ describe('HarnessSdkServer', () => { await server.shutdown() }) - it('reports the final whole-agent outcome after later activity settles', async () => { + it('forwards whole-agent status without attributing a turn outcome', async () => { const ctx = new Context() await ctx.plugin(SessionStore) await ctx.plugin(AgentRegistry) const transport = new FakeTransport() - const server = new HarnessSdkServer(ctx, transport) as unknown as { - prompt(params: { sessionId: string; contentBlocks: { type: 'text'; text: string }[] }): Promise - sessions: Map - shutdown(): Promise> - } + const server = new HarnessSdkServer(ctx, transport) const session = ctx.sessions.create(SessionId('message-outcome')) const agent = ({ id: SessionId('message-outcome'), session, - followup(input: UserMessage) { - session.append('turn/start', { - turn: 1, - }) - session.append('user/message', input, { surfaceOp: 'append' }) - session.append('turn/end', { turn: 1, reason: { kind: 'max-tokens' } }) - session.append('turn/start', { - turn: 2, - }) - session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'late metadata' }], - source: { kind: 'plugin', plugin: 'late-metadata' }, - }), { surfaceOp: 'append' }) - session.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) - return input.id - }, - whenIdle: () => Promise.resolve(), - } satisfies Pick) as unknown as Agent - ctx.agents.register(agent) - server.sessions.set('message-outcome', { - handle: { agent, dispose: () => Promise.resolve() }, - lastTurnEnd: undefined, - activePrompt: false, - }) + } satisfies Pick) as Agent - await server.prompt({ - sessionId: 'message-outcome', - contentBlocks: [{ type: 'text', text: 'bounded prompt' }], - }) + ctx.emit('agent/status', agent, 'running') + ctx.emit('agent/status', agent, 'idle') - expect(transport.notifications.findLast(notification => notification.method === 'session.finished')) - .toEqual({ - method: 'session.finished', - params: { - sessionId: 'message-outcome', - status: 'ok', - reason: { kind: 'completed' }, - }, - }) + expect(transport.notifications.filter(notification => notification.method === 'session.status')) + .toEqual([ + { method: 'session.status', params: { sessionId: 'message-outcome', status: 'running' } }, + { method: 'session.status', params: { sessionId: 'message-outcome', status: 'idle' } }, + ]) await server.shutdown() await ctx.fiber.dispose() }) @@ -356,7 +310,7 @@ describe('HarnessSdkServer', () => { contentBlocks: [{ type: 'text', text: 'hello' }], }) - expect(llmServer.requests).toHaveLength(1) + await vi.waitFor(() => { expect(llmServer.requests).toHaveLength(1) }) await server.shutdown() } finally { await ctx.fiber.dispose() @@ -881,43 +835,6 @@ describe('HarnessSdkServer', () => { }, ) - it('classifies defensive finish states', async () => { - const storageDir = await mkdtemp(join(tmpdir(), 'dsh-jsonrpc-finish-states-')) - const ctx = await makeHarness(storageDir) - try { - const server = new HarnessSdkServer(ctx, new FakeTransport()) as unknown as { - finishedStatus(reason: unknown): 'ok' | 'error' - shutdown(): Promise> - } - - expect(server.finishedStatus(undefined)).toBe('error') - expect(server.finishedStatus({ kind: 'max-tokens' })).toBe('error') - expect(server.finishedStatus({ kind: 'error' })).toBe('error') - await server.shutdown() - } finally { - await ctx.fiber.dispose() - await rm(storageDir, { recursive: true, force: true }) - } - }) - - it('can report max-token turn termination as an accepted evaluation result', async () => { - const storageDir = await mkdtemp(join(tmpdir(), 'dsh-jsonrpc-max-tokens-success-')) - const ctx = await makeHarness(storageDir) - try { - const server = new HarnessSdkServer(ctx, new FakeTransport(), { maxTokensAsSuccess: true }) as unknown as { - finishedStatus(reason: unknown): 'ok' | 'error' - shutdown(): Promise> - } - - expect(server.finishedStatus({ kind: 'max-tokens' })).toBe('ok') - expect(server.finishedStatus({ kind: 'error' })).toBe('error') - await server.shutdown() - } finally { - await ctx.fiber.dispose() - await rm(storageDir, { recursive: true, force: true }) - } - }) - it('reports no adapter when the LLM service is absent', async () => { const ctx = new Context() try { @@ -1045,6 +962,6 @@ describe('HarnessSdkServer', () => { const server = new HarnessSdkServer(ctx, new FakeTransport()) await expect(server.shutdown()).rejects.toBe(listenerFailure) - expect(on).toHaveBeenCalledTimes(3) + expect(on).toHaveBeenCalledTimes(4) }) }) diff --git a/packages/ui/user-approval/src/index.ts b/packages/ui/user-approval/src/index.ts index e4f60da037..d037f7edb2 100644 --- a/packages/ui/user-approval/src/index.ts +++ b/packages/ui/user-approval/src/index.ts @@ -277,10 +277,10 @@ export class ApprovalService extends Service { const cause = overrideSource === 'delegation' ? 'inherited from the delegating session' : overrideIndex > headerIndex ? 'changed by the user' : 'changed by the operator/config' - agent.inject(createUserMessage({ + session.append('user/message', createUserMessage({ content: [{ type: 'text', text: `The approval policy changed from "${told}" to "${current}" (${cause}).` }], source: { kind: 'plugin', plugin: 'user-approval' }, - })) + }), { surfaceOp: 'append' }) }) } diff --git a/packages/ui/user-approval/tests/approval.spec.ts b/packages/ui/user-approval/tests/approval.spec.ts index f779b1e250..cdc8be1d7a 100644 --- a/packages/ui/user-approval/tests/approval.spec.ts +++ b/packages/ui/user-approval/tests/approval.spec.ts @@ -358,23 +358,27 @@ describe('approval policy (the approval/policy fold)', () => { * An agent stand-in over a REAL Session — gate, section, and narrator fold * real events; the opened turn satisfies request()'s enclosure precondition. */ - function sessionAgent(id: string): { agent: Agent; session: Session; injected: string[] } { + function sessionAgent(id: string): { agent: Agent; session: Session } { const session = new Session(SessionId(id)) session.append('turn/start', { turn: 1 }) - const injected: string[] = [] const agent = { id, session, - inject: (input: { content: Array<{ type: string; text: string }> }) => { - injected.push(input.content[0]?.text ?? '') - }, + inject: () => { throw new Error('step-boundary narration must not use agent.inject()') }, } as unknown as Agent - return { agent, session, injected } + return { agent, session } } const preStep = (ctx: Context, agent: Agent): Promise => agentEvents(ctx, agent).serial('agent/step', 1, 1, new AbortController().signal) + const narrations = (session: Session): string[] => session.events.flatMap(event => + event.type === 'user/message' + && event.data.source.kind === 'plugin' + && event.data.source.plugin === 'user-approval' + ? [event.data.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('')] + : []) + /** Append a `request/header` snapshot whose system text is exactly `system`. */ function appendHeader(session: Session, system: string): void { session.append('request/header', { header: { config: { provider: 'mock', model: 'mock' }, system }, reason: 'initial' }) @@ -482,20 +486,20 @@ describe('approval policy (the approval/policy fold)', () => { it('narrates nothing cold, once per coalesced switch (user wording), and idempotently', async () => { const ctx = new Context() await ctx.plugin(ApprovalService) - const { agent, session, injected } = sessionAgent('sess-narr-1') + const { agent, session } = sessionAgent('sess-narr-1') await preStep(ctx, agent) - expect(injected).toEqual([]) + expect(narrations(session)).toEqual([]) setApprovalPolicy(session, 'never') setApprovalPolicy(session, 'ask') setApprovalPolicy(session, 'never') await preStep(ctx, agent) - expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).']) + expect(narrations(session)).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).']) await preStep(ctx, agent) - expect(injected).toHaveLength(1) + expect(narrations(session)).toHaveLength(1) setApprovalPolicy(session, 'ask') setApprovalPolicy(session, 'never') await preStep(ctx, agent) - expect(injected).toHaveLength(1) + expect(narrations(session)).toHaveLength(1) }) it('reads what the model was told back from the folded header text after a restart', async () => { @@ -503,69 +507,69 @@ describe('approval policy (the approval/policy fold)', () => { // an ask default: the narrator attributes the change to the operator. const ctx = new Context() await ctx.plugin(ApprovalService) - const { agent, session, injected } = sessionAgent('sess-narr-2') + const { agent, session } = sessionAgent('sess-narr-2') appendHeader(session, `persona\n\n${NEVER_SENTENCE}\n${NEVER_MARKER}`) await preStep(ctx, agent) - expect(injected).toEqual(['The approval policy changed from "never" to "ask" (changed by the operator/config).']) + expect(narrations(session)).toEqual(['The approval policy changed from "never" to "ask" (changed by the operator/config).']) }) it('attributes a constructor-seeded policy event to delegation', async () => { const ctx = new Context() await ctx.plugin(ApprovalService) - const { agent, session, injected } = sessionAgent('sess-narr-inherited') + const { agent, session } = sessionAgent('sess-narr-inherited') appendHeader(session, ASK_MARKER) session.append('approval/policy', { policy: 'never', source: 'delegation' }) await preStep(ctx, agent) - expect(injected).toEqual(['The approval policy changed from "ask" to "never" (inherited from the delegating session).']) + expect(narrations(session)).toEqual(['The approval policy changed from "ask" to "never" (inherited from the delegating session).']) }) it('narrates a config default drift from the logged ask marker', async () => { const ctx = new Context() await ctx.plugin(ApprovalService, { policy: 'never' }) - const { agent, session, injected } = sessionAgent('sess-narr-3') + const { agent, session } = sessionAgent('sess-narr-3') appendHeader(session, `persona only\n${ASK_MARKER}`) await preStep(ctx, agent) - expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the operator/config).']) + expect(narrations(session)).toEqual(['The approval policy changed from "ask" to "never" (changed by the operator/config).']) }) it('a pinned override survives a default change silently', async () => { const ctx = new Context() await ctx.plugin(ApprovalService, { policy: 'never' }) - const { agent, session, injected } = sessionAgent('sess-narr-4') + const { agent, session } = sessionAgent('sess-narr-4') appendHeader(session, `persona only\n${ASK_MARKER}`) setApprovalPolicy(session, 'ask') appendHeader(session, `persona only\n${ASK_MARKER}`) await preStep(ctx, agent) - expect(injected).toEqual([]) + expect(narrations(session)).toEqual([]) }) it('does not infer never from deployment prose that quotes the never sentence', async () => { const ctx = new Context() await ctx.plugin(ApprovalService) - const { agent, session, injected } = sessionAgent('sess-narr-spoof-prose') + const { agent, session } = sessionAgent('sess-narr-spoof-prose') appendHeader(session, `persona quotes this warning: ${NEVER_SENTENCE}\n${ASK_MARKER}`) await preStep(ctx, agent) - expect(injected).toEqual([]) + expect(narrations(session)).toEqual([]) }) it('treats a legacy header with no source-owned marker as untold', async () => { const ctx = new Context() await ctx.plugin(ApprovalService, { policy: 'never' }) - const { agent, session, injected } = sessionAgent('sess-narr-unmarked-header') + const { agent, session } = sessionAgent('sess-narr-unmarked-header') appendHeader(session, 'legacy persona-only header') await preStep(ctx, agent) - expect(injected).toEqual([]) + expect(narrations(session)).toEqual([]) }) it('uses the service marker after an earlier persona marker', async () => { const ctx = new Context() await ctx.plugin(ApprovalService) - const { agent, session, injected } = sessionAgent('sess-narr-spoof-marker') + const { agent, session } = sessionAgent('sess-narr-spoof-marker') appendHeader(session, `persona quotes ${NEVER_MARKER}\n${ASK_MARKER}`) await preStep(ctx, agent) - expect(injected).toEqual([]) + expect(narrations(session)).toEqual([]) }) it('disposes the service prompt section and pre-step narrator together (HMR safety)', async () => { @@ -581,7 +585,7 @@ describe('approval policy (the approval/policy fold)', () => { appendHeader(live.session, `persona\n${ASK_MARKER}`) setApprovalPolicy(live.session, 'never') await preStep(ctx, live.agent) - expect(live.injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).']) + expect(narrations(live.session)).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).']) appendHeader(afterDispose.session, `persona\n${ASK_MARKER}`) setApprovalPolicy(afterDispose.session, 'never') @@ -589,6 +593,6 @@ describe('approval policy (the approval/policy fold)', () => { expect(await sectionFor()).toBeUndefined() await preStep(ctx, afterDispose.agent) - expect(afterDispose.injected).toEqual([]) + expect(narrations(afterDispose.session)).toEqual([]) }) }) From 349cf35135c60a8f6c055b5f01073009e9c7a6c9 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:18:13 +0800 Subject: [PATCH 028/689] docs: mark owned-run boundary decision implemented --- ...-followup-enqueue-and-owned-runs.i18n.yaml | 6 +++ ...6-07-30-followup-enqueue-and-owned-runs.md | 42 ++++++++++++++++++ ...7-30-followup-enqueue-and-owned-runs.zh.md | 27 ++++++------ ...-followup-enqueue-and-owned-runs.i18n.yaml | 6 --- ...6-07-30-followup-enqueue-and-owned-runs.md | 43 ------------------- docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 2 +- docs/core-data-structures/core.i18n.yaml | 4 +- docs/core-data-structures/core.md | 2 +- docs/core-data-structures/core.zh.md | 2 +- packages/core/agent/README.i18n.yaml | 4 +- packages/core/agent/README.md | 2 +- packages/core/agent/README.zh.md | 2 +- 14 files changed, 73 insertions(+), 75 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md rename .agents/notes/{proposed => implemented}/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md (51%) delete mode 100644 .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml delete mode 100644 .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml new file mode 100644 index 0000000000..fec50c4b67 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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/architecture/2026-07-30-followup-enqueue-and-owned-runs.md +2026-07-30-followup-enqueue-and-owned-runs.md: 12da1d770c9346e79394c194f33e7faae2254cdf +2026-07-30-followup-enqueue-and-owned-runs.zh.md: c7b839d1207151002a0cff1a470245198561b2d8 diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md new file mode 100644 index 0000000000..12da1d770c --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md @@ -0,0 +1,42 @@ +# Agent Note: Follow-up enqueue and owned run boundaries + +Status: implemented + +English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md) + +## Problem + +`Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input. + +The [one-send-one-turn decision](../simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers that pair one prompt request with a turn result manufacture that missing relationship downstream. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome. + +## Decision + +Keep `Agent.followup(message): void` as an enqueue-only operation. `Agent.whenIdle()` and `agent/status` remain whole-agent lifecycle observations; neither settles an individual message. Inbox durability records the identified message and its admission or cancellation, without assigning later output to it. + +The low-level SDK protocol answers `session/prompt` as soon as enqueue succeeds with `{ messageId }`. It streams durable facts through `session.event`, publishes whole-agent transitions through `session.status`, and has no `session.finished`. A low-level client may observe that receipt and later idleness, but receives no prompt result. + +High-level automation APIs return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their `finalResponse` is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may report a result because its caller owns the complete child lifecycle and any steering belongs to that run. + +ACP must return a protocol `stopReason`. Its bridge serializes one in-flight prompt per ACP session, waits for whole-agent idle, reports `cancelled` only for explicit ACP cancellation or disposal, and otherwise reports the generic `end_turn`. It does not infer token-limit or error attribution for the prompt. + +Goal continuation retains `MessageId` only to recognize its durable queued and admitted goal message. It advances from durable goal state at whole-agent idle, without mapping the message to a turn result. + +## Alternatives considered + +**Map `MessageId` to the turn that admits it.** A turn may consume steering and injected context and may continue through multiple model/tool steps. The mapping identifies admission, not causal ownership of the resulting output or stop reason. + +**Return a per-follow-up completion handle.** A handle would imply a result boundary that the shared agent lifecycle does not have. It would either omit work that influenced the activity or silently absorb unrelated later input. + +**Use the last `turn/end` observed before idle.** This is a useful run-level observation for an explicitly owned interval, but naming it as the submitted message's outcome recreates the false causal claim. + +## Verification + +- Agent and inbox tests pin enqueue-only follow-up, durable admission or cancellation, and whole-agent idle observation. +- SDK protocol, TypeScript SDK, and Python SDK tests pin the `{ messageId }` receipt, `session.status`, the absence of `session.finished`, and receipt-to-idle `RunResult` collection without prompt-level `status` or `reason`. +- ACP, one-shot CLI, goal continuation, and subagent tests pin the distinct activity ownership each integration possesses. +- Consumer tests pin that no production integration derives a follow-up result by correlating `MessageId` with `turn/end`. + +## Consequences + +An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications disappear from SDK and ACP results; callers that need those facts must inspect the durable event stream without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result. diff --git a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md similarity index 51% rename from .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md rename to .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md index 03a321c761..c7b839d120 100644 --- a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md @@ -1,6 +1,6 @@ # Agent Note: follow-up 入队与自有运行边界 -Status: proposed +Status: implemented [English](2026-07-30-followup-enqueue-and-owned-runs.md) | 中文 @@ -8,19 +8,19 @@ Status: proposed `Agent.followup()` 会标识一条用户消息并将其排入队列，但单次 follow-up 并不拥有随后发生的活动。在 agent（智能体）下一次进入 idle 前，steering（中途引导）、注入的上下文、工具续行、恢复和后续排队消息都可能参与活动。因此，`MessageId` 可以证明 inbox 已准入，但不能标识哪一条 assistant 消息或哪一个 `turn/end` 是该输入的结果。 -[one-send-one-turn 决策](../../implemented/simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。协议层和 SDK 层仍会在下游配对一项提示词请求与一个轮次结果，人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。 +[one-send-one-turn 决策](../simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。凡是把一项提示词请求与一个轮次结果配对的协议层和 SDK 层，都会在下游人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。 -## 提案 +## 决策 保留 `Agent.followup(message): void`，使其仅执行入队。`Agent.whenIdle()` 和 `agent/status` 仍用于观察整个 agent 的生命周期；二者都不结算单条消息。Inbox 持久性会记录已标识消息及其准入或取消，但不会把后续输出归属于该消息。 -底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，并删除 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。 +底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。 -只有明确拥有一个活动区间时，高层自动化 API 才可以返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法会从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行仍可报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。 +只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。 -ACP（Agent Client Protocol）仍必须返回协议规定的 `stopReason`。其桥接层会串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，仅在显式 ACP 取消或资源释放时报告 `cancelled`，其他情况均报告通用的 `end_turn`。它不会推断 token 上限或错误是否归属于该提示词。 +ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，仅在显式 ACP 取消或资源释放时报告 `cancelled`，其他情况均报告通用的 `end_turn`。它不推断 token 上限或错误是否归属于该提示词。 -Goal 续行只会保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它会在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。 +Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。 ## 考虑过的替代方案 @@ -30,14 +30,13 @@ Goal 续行只会保留 `MessageId`，用于识别持久排队和已准入的 go **使用进入 idle 前观察到的最后一个 `turn/end`。** 对于明确拥有的区间，这是一项有用的运行级观测；但如果将其命名为已提交消息的结果，就会再次作出错误的因果声明。 -## 验收标准 +## 验证 -- `Agent.followup()` 仍仅执行入队，其文档不承诺单条消息的完成状态或结果。 -- SDK 协议格式（wire format）由 `session/prompt` 返回 `MessageId`、发布 `session.status`，且不包含 `session.finished`。 -- TypeScript 和 Python 高层 SDK 公开不带提示词级 `status` 或 `reason` 的 `RunResult`，并定义从回执到 idle 的收集窗口。 -- ACP、单次 CLI、goal 续行和 subagent 提供方分别记录自己实际拥有的活动边界。 -- 生产消费方都不会通过关联 `MessageId` 与 `turn/end` 来推导 follow-up 结果。 +- Agent 与 inbox 测试固定 follow-up 仅入队、持久准入或取消以及整个 agent 的 idle 观测。 +- SDK 协议、TypeScript SDK 和 Python SDK 测试固定 `{ messageId }` 回执、`session.status`、不存在 `session.finished`，以及不含提示词级 `status` 或 `reason` 的回执到 idle `RunResult` 收集。 +- ACP、单次 CLI、goal 续行和 subagent 测试固定各集成实际拥有的不同活动边界。 +- 消费方测试固定生产集成都不会通过关联 `MessageId` 与 `turn/end` 来推导 follow-up 结果。 -## 风险 +## 后果 自有活动区间可以包含进入 idle 前提交的 steering、注入上下文或其他工作，因此其最终响应和事件有意比初始消息涵盖更广。SDK 和 ACP 结果不再包含提示词级模型错误和 token 上限分类；需要这些事实的调用方必须检查持久事件流，但不能声称这些事实具有因果归属。在同一会话上并发执行自动化操作时，必须采用显式串行或所有权策略，不能依赖隐式的按提示词结果。 diff --git a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml deleted file mode 100644 index 1027cfb0f0..0000000000 --- a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each -# 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/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md -2026-07-30-followup-enqueue-and-owned-runs.md: 73dfb501cb5c18a7a9219861eba37e73499af5e0 -2026-07-30-followup-enqueue-and-owned-runs.zh.md: 03a321c761eda385acb665d26a33ef618c70dee5 diff --git a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md b/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md deleted file mode 100644 index 73dfb501cb..0000000000 --- a/.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md +++ /dev/null @@ -1,43 +0,0 @@ -# Agent Note: Follow-up enqueue and owned run boundaries - -Status: proposed - -English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md) - -## Problem - -`Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input. - -The [one-send-one-turn decision](../../implemented/simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers currently manufacture that missing relationship downstream by pairing one prompt request with a turn result. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome. - -## Proposal - -Keep `Agent.followup(message): void` as an enqueue-only operation. `Agent.whenIdle()` and `agent/status` remain whole-agent lifecycle observations; neither settles an individual message. Inbox durability records the identified message and its admission or cancellation, without assigning later output to it. - -The low-level SDK protocol will answer `session/prompt` as soon as enqueue succeeds with `{ messageId }`. It will stream durable facts through `session.event`, publish whole-agent transitions through `session.status`, and remove `session.finished`. A low-level client may observe that receipt and later idleness, but receives no prompt result. - -High-level automation APIs may return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods will collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their `finalResponse` is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may still report a result because its caller owns the complete child lifecycle and any steering belongs to that run. - -ACP must still return a protocol `stopReason`. Its bridge will serialize one in-flight prompt per ACP session, wait for whole-agent idle, report `cancelled` only for explicit ACP cancellation or disposal, and otherwise report the generic `end_turn`. It will not infer token-limit or error attribution for the prompt. - -Goal continuation will retain `MessageId` only to recognize its durable queued and admitted goal message. It will advance from durable goal state at whole-agent idle, without mapping the message to a turn result. - -## Alternatives considered - -**Map `MessageId` to the turn that admits it.** A turn may consume steering and injected context and may continue through multiple model/tool steps. The mapping identifies admission, not causal ownership of the resulting output or stop reason. - -**Return a per-follow-up completion handle.** A handle would imply a result boundary that the shared agent lifecycle does not have. It would either omit work that influenced the activity or silently absorb unrelated later input. - -**Use the last `turn/end` observed before idle.** This is a useful run-level observation for an explicitly owned interval, but naming it as the submitted message's outcome recreates the false causal claim. - -## Acceptance criteria - -- `Agent.followup()` remains enqueue-only, and its documentation promises no per-message completion or result. -- The SDK wire protocol returns `MessageId` from `session/prompt`, publishes `session.status`, and has no `session.finished`. -- TypeScript and Python high-level SDKs expose `RunResult` without prompt-level `status` or `reason`, and define the receipt-to-idle collection window. -- ACP, the one-shot CLI, goal continuation, and subagent providers document the distinct activity ownership they actually possess. -- No production consumer derives a follow-up result by correlating `MessageId` with `turn/end`. - -## Risks - -An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications disappear from SDK and ACP results; callers that need those facts must inspect the durable event stream without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result. diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index c05e2c0bc9..b02f0d58bb 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: d8e5f8a2e8d36acb7d27ed0571645f6166eff3af -architecture.zh.md: 96948aa5283e0114b1883335b91148ce3b720e06 +architecture.md: 7a160bd6eb26e96688699110ed15696b941825d0 +architecture.zh.md: 26b71962d312375aa8d69c8dce7abac32d541f2f diff --git a/docs/architecture.md b/docs/architecture.md index d8e5f8a2e8..7a160bd6eb 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -131,7 +131,7 @@ Turn and step events are turn-enclosed; idle injected `user/message` events may ### Agent Handles -`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. `followup()` only queues an identified message: its `MessageId` follows durable inbox admission, not a prompt-specific output or turn ending. `agent/status` and `whenIdle()` describe whole-agent activity; only a caller that explicitly owns an activity interval may summarize that interval as a run result ([proposal](../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). +`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. `followup()` only queues an identified message: its `MessageId` follows durable inbox admission, not a prompt-specific output or turn ending. `agent/status` and `whenIdle()` describe whole-agent activity; only a caller that explicitly owns an activity interval may summarize that interval as a run result ([decision](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). ### Agent Scope diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index 96948aa528..26b71962d3 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -131,7 +131,7 @@ idle inject: ### Agent 句柄 -`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。`followup()` 只会将一条带标识的消息排队：其 `MessageId` 跟踪持久 inbox 准入，而不标识某个提示词特有的输出或轮次结束。`agent/status` 与 `whenIdle()` 描述整个 agent 的活动；只有显式拥有某个活动区间的调用方才能将该区间概括为一次运行的结果（[提案](../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。 +`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。`followup()` 只会将一条带标识的消息排队：其 `MessageId` 跟踪持久 inbox 准入，而不标识某个提示词特有的输出或轮次结束。`agent/status` 与 `whenIdle()` 描述整个 agent 的活动；只有显式拥有某个活动区间的调用方才能将该区间概括为一次运行的结果（[决策](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。 ### Agent 作用域 diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index f0ab5d462e..84c2a906c4 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md -core.md: b7e1c11b488dc751f4d50f4616a6bf20186d06d5 -core.zh.md: 0e204ef9ce51db66dac491ffcb2a32682b8f4826 +core.md: 3bbfe3c4c763a24edb6ec1362344cef6ce50f650 +core.zh.md: d54159c25659a89baded31b8e3aa5207715e0c12 diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index b7e1c11b48..3bbfe3c4c7 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -503,7 +503,7 @@ interface Agent { } ``` -`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox and admission facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([proposal](../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission leaves the provider default in control. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default. +`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox and admission facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission leaves the provider default in control. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default. The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result. diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 0e204ef9ce..d54159c256 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -511,7 +511,7 @@ interface Agent { } ``` -`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 与准入事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[提案](../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时由提供方默认值控制。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。 +`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 与准入事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[决策](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时由提供方默认值控制。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。 cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。 diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml index 1797e084d2..7d9a997167 100644 --- a/packages/core/agent/README.i18n.yaml +++ b/packages/core/agent/README.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 packages/core/agent/README.md -README.md: 987386c363705ded9ab074ed012dd0219e6c8308 -README.zh.md: 593a079bcf93e4c7a0785fb58c6abcb5be53693c +README.md: cf9b0569a8c689222b46a551139178f2e353f680 +README.zh.md: 259eeb97555795d4d3a57fcd8deffadf00291b29 diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 987386c363..cf9b0569a8 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -68,7 +68,7 @@ The handle every plugin programs against: - `agent.whenIdle()` — observe whole-agent quiescence, including replacement work scheduled before the current driver retires. It does not settle any particular message. - `agent.session`, `agent.status`, `agent.options`, `agent.id`, `agent.ctx` -`running` describes a driver-wide drain interval, not proof that a turn is still open; it can cover turn close, the durability checkpoint, and consecutive queued turns. Only a caller that owns a complete interval may summarize it as a run result ([proposal](../../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). +`running` describes a driver-wide drain interval, not proof that a turn is still open; it can cover turn close, the durability checkpoint, and consecutive queued turns. Only a caller that owns a complete interval may summarize it as a run result ([decision](../../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). ### Extension points diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md index 593a079bcf..259eeb9755 100644 --- a/packages/core/agent/README.zh.md +++ b/packages/core/agent/README.zh.md @@ -68,7 +68,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供， - `agent.whenIdle()`：观察整个 agent 达到完全停稳，包括当前驱动器退役前调度的替代工作。它不结算任何特定消息。 - `agent.session`、`agent.status`、`agent.options`、`agent.id`、`agent.ctx` -`running` 描述驱动器范围的 drain 区间，而不是轮次仍打开的证明；它可以覆盖轮次关闭、持久性检查点和连续的排队轮次。只有拥有完整区间的调用方才能将其概括为一次运行的结果（[提案](../../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。 +`running` 描述驱动器范围的 drain 区间，而不是轮次仍打开的证明；它可以覆盖轮次关闭、持久性检查点和连续的排队轮次。只有拥有完整区间的调用方才能将其概括为一次运行的结果（[决策](../../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。 ### 扩展点 From 250dcfd1ce3bd8eb0a91aeb50372dfa2d5fea08c Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:27:36 +0800 Subject: [PATCH 029/689] fix(jsonrpc): drain runtime before protocol exit --- ...e-executable-sdk-runtime-distribution.i18n.yaml | 4 ++-- ...gle-file-executable-sdk-runtime-distribution.md | 2 +- ...-file-executable-sdk-runtime-distribution.zh.md | 2 +- .../tests/subagent-dsh-sdk.spec.ts | 11 +++++------ packages/ui/jsonrpc/README.i18n.yaml | 4 ++-- packages/ui/jsonrpc/README.md | 2 +- packages/ui/jsonrpc/README.zh.md | 2 +- packages/ui/jsonrpc/src/index.ts | 14 ++++++++------ packages/ui/jsonrpc/tests/plugin-apply.spec.ts | 9 ++++++++- 9 files changed, 29 insertions(+), 21 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml index 27e43ef4b2..36be9000b6 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md -2026-07-10-single-file-executable-sdk-runtime-distribution.md: f749d6a72b4c32a189a9f848595076457819d9b9 -2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 2b511573bc68e5378279cec8d22ce960af0966e9 +2026-07-10-single-file-executable-sdk-runtime-distribution.md: f3da981c478ef08672a82f23ab9cd42e0f38ebab +2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 7db7efde7e555985a541b14a678d550fe5891159 diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md index f749d6a72b..f3da981c47 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md @@ -27,7 +27,7 @@ Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's t The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `acp/acp` + `examples/acp-demo` pattern — the serving surface is itself a plugin: -- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering the `shutdown` request it disposes its own fiber, then `exit(0)`; an HMR-style unload only stops the service without exiting the process). +- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process). - [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130). Config discovery has two channels and fails loudly when both are missing: the `DSH_CORDIS_CONFIG` environment variable first (the SDK client convention), then an argv positional argument; no default path and no built-in fallback whatsoever — "the plugins actually booted are decided by an external cordis.yml" is a hard semantic. diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md index 2b511573bc..7db7efde7e 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md @@ -27,7 +27,7 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后 确定性协议实现（`server.ts` / `transport.ts`）按 `acp/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件： -- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答 `shutdown` 请求后 dispose 自身 fiber，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。 +- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。 - [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——“实际启动的插件由外部 `cordis.yml` 决定”是硬语义。 diff --git a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts index 2b22174eca..074d17f06b 100644 --- a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts +++ b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts @@ -218,16 +218,15 @@ describe('dsh-subagent-dsh-sdk provider', () => { } }) - it('keeps accumulated streamed text when the turn is cut short before a full message', async () => { - // The fake streams one text-delta chunk and then violates the protocol on - // the same pipe; frame order guarantees the chunk was dispatched before - // the failure settles, so the accumulated partial text (no complete - // assistant/message ever arrived) must survive into the error result. + it('does not attribute streamed text when prompt acceptance is malformed', async () => { + // The fake streams one text-delta chunk but never returns the MessageId + // needed to establish this run's durable inbox receipt. The text therefore + // lies outside an owned activity interval and cannot become its output. const ctx = await setup({ FAKE_STREAM_THEN_MALFORMED: '1' }, { shutdownTimeoutMs: 100, disposeEofGraceMs: 200, disposeGraceMs: 200 }) const run = await ctx.subagents.start('dsh-sdk', request()) const result = await run.result expect(result.stopReason).toBe('error') - expect(text(result.output)).toBe('streamed then cut short') + expect(result.output).toEqual([]) await run.dispose() await ctx.fiber.dispose() }) diff --git a/packages/ui/jsonrpc/README.i18n.yaml b/packages/ui/jsonrpc/README.i18n.yaml index c6ffdca04f..e43d22718e 100644 --- a/packages/ui/jsonrpc/README.i18n.yaml +++ b/packages/ui/jsonrpc/README.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 packages/ui/jsonrpc/README.md -README.md: 976c63ee4f00336cd68e30288e569d514e7ee65b -README.zh.md: e7862aaa335c3277863647e0931eb815ef2ccc1a +README.md: 7eb0336a770397df280fbaf95a6ad88243d28944 +README.zh.md: 993d227d464c460d2c1a3b309542a9c59d1fd18c diff --git a/packages/ui/jsonrpc/README.md b/packages/ui/jsonrpc/README.md index 976c63ee4f..7eb0336a77 100644 --- a/packages/ui/jsonrpc/README.md +++ b/packages/ui/jsonrpc/README.md @@ -18,7 +18,7 @@ Stdout carries only JSON-RPC frames. The deployment must not compose a stdout lo ## Shutdown and exit semantics -The plugin answers `shutdown`, disposes SDK-owned agents and subscriptions to quiescence, closes the transport, then exits with code 0. EOF and signal exits belong to the app bin, which disposes the root context. Unloading only this plugin stops serving without exiting the process. +The plugin answers `shutdown`, flushes the response, disposes the root context so SDK-owned agents, subscriptions, and persistence reach quiescence, then exits with code 0. EOF and signal exits belong to the app bin, which also disposes the root context. Unloading only this plugin stops serving without exiting the process. ## Wire notes diff --git a/packages/ui/jsonrpc/README.zh.md b/packages/ui/jsonrpc/README.zh.md index e7862aaa33..993d227d46 100644 --- a/packages/ui/jsonrpc/README.zh.md +++ b/packages/ui/jsonrpc/README.zh.md @@ -18,7 +18,7 @@ Stdout 只承载 JSON-RPC 帧。部署不得组合 stdout logger；诊断应写 ## 关闭与退出语义 -插件响应 `shutdown`，将 SDK 持有的 agent 和订阅 dispose（资源释放）至完全停稳，关闭传输层，然后以代码 0 退出。EOF 和信号退出由 app bin 处理，后者会 dispose 根上下文。仅卸载此插件会停止服务，但不会退出进程。 +插件响应 `shutdown`，刷新响应并 dispose（资源释放）根上下文，使 SDK 持有的 agent、订阅和持久化全部停稳，然后以代码 0 退出。EOF 和信号退出由 app bin 处理，后者也会 dispose 根上下文。仅卸载此插件会停止服务，但不会退出进程。 ## 协议说明 diff --git a/packages/ui/jsonrpc/src/index.ts b/packages/ui/jsonrpc/src/index.ts index 78ac9ef2be..423f338877 100644 --- a/packages/ui/jsonrpc/src/index.ts +++ b/packages/ui/jsonrpc/src/index.ts @@ -2,7 +2,7 @@ * SDK-facing JSON-RPC plugin over stdio. An external `cordis.yml` decides * whether to load it; see the single-executable Agent Note and package README. * Stdout is reserved for protocol frames, so the tree must not load a stdout logger. - * This plugin answers `shutdown`, disposes its own fiber, and exits 0; the app bin + * This plugin answers `shutdown`, disposes the complete root runtime, and exits 0; the app bin * owns EOF and signal exits. Keep named plugin exports with no default export so * Loader `unwrapExports` preserves `name`, `inject`, `Config`, and `apply`. * @@ -40,14 +40,15 @@ export const Config: Schema = Schema.object({ /** * Serve SDK requests over the configured streams. Effect disposal shuts down * SDK-created agents and closes the transport. A `shutdown` response is flushed - * before this plugin's fiber is disposed and the process exits 0; the app bin + * before the root runtime is disposed and the process exits 0; the app bin * owns root-context disposal for EOF and signals. */ export function apply(ctx: Context, config: JsonRpcConfig): void { // Cordis applies the schema default before invoking the plugin. const resolvedConfig = config as JsonRpcConfig & { maxTokensAsSuccess: boolean } - // The later transport callback must dispose this plugin's fiber, not its ambient context. - const fiber = ctx.fiber + // Protocol shutdown owns the complete runtime process, so it must await the + // root lifecycle (including persistence) before exiting. + const rootFiber = ctx.root.fiber /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */ const input = config.input ?? process.stdin /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */ @@ -60,12 +61,13 @@ export function apply(ctx: Context, config: JsonRpcConfig): void { maxTokensAsSuccess: resolvedConfig.maxTokensAsSuccess, }) - // Share one exit task and attempt flush and disposal independently before exiting. + // Share one exit task so racing shutdown requests cannot dispose the root or + // exit the process more than once. let exitTask: Promise | undefined const disposeAndExit = (): Promise => { exitTask ??= (async () => { await Promise.allSettled([Promise.resolve().then(() => transport.flush())]) - await Promise.allSettled([Promise.resolve().then(() => fiber.dispose())]) + await Promise.allSettled([Promise.resolve().then(() => rootFiber.dispose())]) exit(0) })() return exitTask diff --git a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts b/packages/ui/jsonrpc/tests/plugin-apply.spec.ts index 816f60d522..9b5c67a69b 100644 --- a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts +++ b/packages/ui/jsonrpc/tests/plugin-apply.spec.ts @@ -20,6 +20,7 @@ import * as jsonrpc from '../src/index.ts' type WireEvent = | { kind: 'frame'; frame: Record } | { kind: 'write-complete'; ids: (string | number)[] } + | { kind: 'root-disposed' } | { kind: 'exit'; code: number } interface ApplyHarness { @@ -99,6 +100,7 @@ async function mountPlugin( output.on('error', (error: Error) => { outputErrors.push(error) }) const exit = (code: number): void => { events.push({ kind: 'exit', code }) } + ctx.effect(() => () => { events.push({ kind: 'root-disposed' }) }, 'jsonrpc test root-disposal witness') const fiber = await ctx.plugin(jsonrpc, { input, output, exit }) const frames = (): Record[] => @@ -229,16 +231,19 @@ describe('dsh-jsonrpc plugin apply', () => { const firstComplete = harness.events.findIndex(event => event.kind === 'write-complete' && event.ids.includes('sd-1')) const secondComplete = harness.events.findIndex(event => event.kind === 'write-complete' && event.ids.includes('sd-2')) const flushComplete = harness.events.findIndex(event => event.kind === 'write-complete' && event.ids.length === 0) + const rootDisposed = harness.events.findIndex(event => event.kind === 'root-disposed') expect(firstResponse).toBeGreaterThanOrEqual(0) expect(secondResponse).toBeGreaterThanOrEqual(0) expect(firstComplete).toBeGreaterThan(firstResponse) expect(secondComplete).toBeGreaterThan(secondResponse) expect(flushComplete).toBeGreaterThan(firstComplete) expect(flushComplete).toBeGreaterThan(secondComplete) - expect(exitIndex).toBeGreaterThan(flushComplete) + expect(rootDisposed).toBeGreaterThan(flushComplete) + expect(exitIndex).toBeGreaterThan(rootDisposed) await settle() expect(harness.exits()).toEqual([0]) + expect(harness.events.filter(event => event.kind === 'root-disposed')).toHaveLength(1) const before = harness.frames().length harness.send({ jsonrpc: '2.0', id: 'after-exit', method: 'initialize', params: { cwd: storageDir, provider: 'deepseek', model: 'x' } }) @@ -259,6 +264,7 @@ describe('dsh-jsonrpc plugin apply', () => { await waitFor(() => harness.exits().length > 0 ? true : undefined, 'exit after flush failure') await settle() expect(harness.exits()).toEqual([0]) + expect(harness.events.filter(event => event.kind === 'root-disposed')).toHaveLength(1) expect(harness.outputErrors.map(error => error.message)).toEqual(['flush callback failed']) const before = harness.frames().length @@ -284,6 +290,7 @@ describe('dsh-jsonrpc plugin apply', () => { }) await harness.fiber.dispose() + expect(harness.events.some(event => event.kind === 'root-disposed')).toBe(false) const before = harness.frames().length harness.send({ jsonrpc: '2.0', id: 'probe-2', method: 'initialize', params: { cwd: storageDir, provider: 'deepseek', model: 'x' } }) From 934e5e957c3a63af6a0509b55c18a95768e519e2 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:27:36 +0800 Subject: [PATCH 030/689] test(cli): accept durable inbox receipt before turn --- packages/examples/cli-demo/tests/built-bin.e2e.ts | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/packages/examples/cli-demo/tests/built-bin.e2e.ts b/packages/examples/cli-demo/tests/built-bin.e2e.ts index 8dc3fd7362..c58d2657fb 100644 --- a/packages/examples/cli-demo/tests/built-bin.e2e.ts +++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts @@ -167,7 +167,19 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => { const stream = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'stream-json', 'stream task']) const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record) - expect(lines[0]).toMatchObject({ type: 'session_event', event: { type: 'turn/start' } }) + expect(lines[0]).toMatchObject({ + type: 'session_event', + event: { + type: 'agent/inbox/spliced', + data: { + target: 'next-turn', + start: 0, + inserted: [{ content: [{ type: 'text', text: 'stream task' }], source: { kind: 'user' } }], + }, + }, + }) + expect(lines.findIndex(line => + (line['event'] as { type?: string } | undefined)?.type === 'turn/start')).toBeGreaterThan(0) expect(lines.at(-1)).toMatchObject({ type: 'result', output: 'BUILT: stream task' }) const sessionsRoot = join(consumer, '.sessions') const files = await readdir(sessionsRoot, { recursive: true }) From c891cb6f6f6b85392f142518e23c68664d87c33e Mon Sep 17 00:00:00 2001 From: _Kerman Date: Thu, 30 Jul 2026 18:54:19 +0800 Subject: [PATCH 031/689] fix(agent): address initial review findings --- docs/persistence-catalog.md | 8 +++-- packages/core/agent-loop/src/agent.ts | 8 ++--- packages/core/agent/src/inbox.ts | 9 ++++-- packages/core/agent/src/types.ts | 6 +++- packages/goal/goal-session/src/index.ts | 1 + .../goal-session/tests/goal-session.spec.ts | 2 +- packages/host/apiproxy/src/api-proxy.ts | 14 ++++++++ packages/host/apiproxy/src/api/events.ts | 6 ++-- .../apiproxy/tests/api-proxy-commands.spec.ts | 32 ++++++++++++++++--- .../tests/api-proxy-projections.spec.ts | 7 ++-- 10 files changed, 72 insertions(+), 21 deletions(-) diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 8878521ba8..9ac1f466f1 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -87,7 +87,11 @@ Sources: [`packages/core/session/src/types.ts:258`](../packages/core/session/src #### `agent/inbox/spliced` — log-only ```ts persistence-catalog -/** One normalized mutation of an agent's durable pending-message lists. */ +/** + * One normalized mutation of an agent's durable pending-message lists. + * Live dispatch precedes projection mutation, so synchronous observers may + * read the pre-splice inbox to recover the removed messages. + */ 'agent/inbox/spliced': { target: InboxTarget start: number @@ -97,7 +101,7 @@ Sources: [`packages/core/session/src/types.ts:258`](../packages/core/session/src } ``` -Source: [`packages/core/agent/src/types.ts:268`](../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) ### `approval/*` diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index f33e36a3e3..144a12634c 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -144,10 +144,10 @@ export class ReactLoopAgent implements Agent { } private async admit(onTurnBoundary: boolean): Promise { - if (this.phase.kind !== 'running') throw new Error() + if (this.phase.kind !== 'running') throw new Error(`agent "${this.id}": admit outside running phase`) const signal = this.phase.abort.signal const claimed = [...this.inbox.nextStep] - const outboxLength = this.inbox.nextStep.length + const outboxLength = claimed.length const queued = onTurnBoundary ? this.inbox.nextTurn[0] : undefined if (queued !== undefined) claimed.push(queued) if (claimed.length === 0) return { kind: 'empty' } @@ -167,7 +167,7 @@ export class ReactLoopAgent implements Agent { /** Admitted input stays unowned until `turn/start` commits. */ private async turn(): Promise { - if (this.phase.kind === 'idle') throw new Error() + if (this.phase.kind === 'idle') throw new Error(`agent "${this.id}": turn without driver reservation`) const abort = this.phase.kind === 'collecting' ? this.phase.abort : new AbortController() const { signal } = abort const lastTurn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn @@ -227,7 +227,7 @@ export class ReactLoopAgent implements Agent { } private async step(): Promise { - if (this.phase.kind !== 'running') throw new Error() + if (this.phase.kind !== 'running') throw new Error(`agent "${this.id}": step outside running phase`) const { turn, step, abort: { signal } } = this.phase signal.throwIfAborted() await this.loopCtx.serial(agentCarrier(this), 'agent/step', this, turn, step, signal) diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts index d6dafa7e4e..2cdacfddfd 100644 --- a/packages/core/agent/src/inbox.ts +++ b/packages/core/agent/src/inbox.ts @@ -44,6 +44,9 @@ export class Inbox { /** * Apply standard splice semantics and durably record the normalized result. + * The durable event commits before the live projection mutates, so synchronous + * `session/event` observers see the pre-splice lists and can reconstruct the + * removed messages from the normalized coordinates. * @param target - pending list to mutate. * @param start - splice position. * @param deleteCount - maximum number of messages to remove. @@ -59,12 +62,14 @@ export class Inbox { outcome?: 'admitted' | 'canceled', ): UserMessage[] { const inbox = this.state[target] - const offset = Math.trunc(start) || 0 + const truncatedStart = Math.trunc(start) + const offset = Number.isNaN(truncatedStart) ? 0 : truncatedStart const actualStart = offset < 0 ? Math.max(inbox.length + offset, 0) : Math.min(offset, inbox.length) + const truncatedDeleteCount = Math.trunc(deleteCount) const actualDeleteCount = Math.min( - Math.max(Math.trunc(deleteCount) || 0, 0), + Math.max(Number.isNaN(truncatedDeleteCount) ? 0 : truncatedDeleteCount, 0), inbox.length - actualStart, ) if (actualDeleteCount === 0 && inserted.length === 0) return [] diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index b1451768ca..29f536e2c0 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -264,7 +264,11 @@ declare module 'cordis' { declare module '@deepseek-ai/dsh-session' { interface SessionEventMap { - /** One normalized mutation of an agent's durable pending-message lists. */ + /** + * One normalized mutation of an agent's durable pending-message lists. + * Live dispatch precedes projection mutation, so synchronous observers may + * read the pre-splice inbox to recover the removed messages. + */ 'agent/inbox/spliced': { target: InboxTarget start: number diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index 583734a3db..e65fb41aa6 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -418,6 +418,7 @@ export function apply(ctx: Context): void { attempt.stale = true if (attempt.phase === 'admitted' && state.agent.status === 'running') { state.agent.cancel({ kind: 'parent' }) + waits.push(state.agent.whenIdle()) } } if (state.run !== undefined) waits.push(state.run) diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index 4cff18d80f..7cd8090e07 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -735,7 +735,7 @@ describe('same-session goal driving', () => { activation: 'disarmed', roundsStarted: 1, }) - await test.agent.whenIdle() + expect(test.agent.status).toBe('idle') expect(test.adapter.requests).toHaveLength(1) }) diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index 10c3102122..6f600f114a 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -1502,6 +1502,20 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro const view = viewFor(ctx, event, callId => openCalls.get(session.id)?.get(callId) ?? backscanArgs(session.events, callId)) queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } })) + if (event.type === 'agent/inbox/spliced' && event.data.target === 'next-turn') { + const agent = ctx.agents.get(session.id) + if (agent?.session === session) { + queue.push(frame({ + type: 'session/queue', + sessionId: session.id, + items: agent.inbox.nextTurn.toSpliced( + event.data.start, + event.data.removedCount ?? 0, + ...event.data.inserted, + ), + })) + } + } }), ctx.on('session/created', (session: Session) => { subscribeSession(queue, session) diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts index 859f4e1bc2..c6742e5352 100644 --- a/packages/host/apiproxy/src/api/events.ts +++ b/packages/host/apiproxy/src/api/events.ts @@ -62,9 +62,9 @@ export type MuxFrame = | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] } | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' } /** - * Complete next-turn queue baseline emitted when a mux stream opens. Live - * mutations arrive through durable `agent/inbox/spliced` session events. - * Pending next-step input is outside this Web queue projection. + * Complete next-turn queue snapshot emitted when a mux stream opens and + * after every live next-turn mutation. Pending next-step input is outside + * this Web queue projection. */ | { type: 'session/queue'; sessionId: SessionId; items: UserMessage[] } /** diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts index 73a3a793e6..6008b16922 100644 --- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts @@ -20,7 +20,7 @@ import ToolRegistry from '@deepseek-ai/dsh-tools' import UserInteractionService from '@deepseek-ai/dsh-user-interaction' import CommandService from '@deepseek-ai/dsh-commands' import SkillService from '@deepseek-ai/dsh-skill' -import type { HostFrame, MuxFrame } from '../src/api/index.ts' +import type { HostFrame } from '../src/api/index.ts' import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts' import { RpcId } from '../src/api/rpc.ts' import { createApiProxy } from '../src/api-proxy.ts' @@ -85,6 +85,13 @@ async function collect(iterable: AsyncIterable>, count: number, return frames } +/** Read the next payload from an open stream. */ +async function nextFrame(iterator: AsyncIterator>): Promise { + const result = await iterator.next() + if (result.done) throw new Error('stream ended') + return result.value.payload +} + describe('command.list', () => { it('serves the addressed agent\'s name-sorted catalog', async () => { const ctx = await harness() @@ -332,24 +339,41 @@ describe('session.updateQueue', () => { }) describe('session/queue frames', () => { - it('publishes the durable next-turn baseline without duplicating message identity', async () => { + it('publishes authoritative next-turn snapshots without duplicating message identity', async () => { const ctx = await harness() const api = createApiProxy(ctx, DEFAULTS) const agent = stubAgent(ctx) const queued = inboxMessage('m-1', 'queued prompt') + const edited = inboxMessage('m-1', 'edited prompt') const steering = inboxMessage('m-2', 'steering prompt') agent.inbox.splice('next-turn', 0, 0, [queued]) agent.inbox.splice('next-step', 0, 0, [steering]) const abort = new AbortController() - const frames = await collect( - api.events.mux({ rpcId: RpcId('t-mux-baseline'), payload: {} }, abort.signal), 2, abort) + const iterator = api.events.mux({ + rpcId: RpcId('t-mux-baseline'), + payload: {}, + }, abort.signal)[Symbol.asyncIterator]() + const frames = [ + await nextFrame(iterator), + await nextFrame(iterator), + ] + agent.inbox.splice('next-turn', 0, 1, [edited]) + frames.push(await nextFrame(iterator), await nextFrame(iterator)) + abort.abort() + await iterator.return?.() + expect(frames.filter(frame => frame.type === 'session/queue')).toEqual([ { type: 'session/queue', sessionId: agent.id, items: [queued], }, + { + type: 'session/queue', + sessionId: agent.id, + items: [edited], + }, ]) }) }) diff --git a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts index 4916f93e32..f6acfe81d4 100644 --- a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts @@ -10,7 +10,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import { z } from 'zod' -import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { createUserMessage } from '@deepseek-ai/dsh-llm' import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' @@ -53,9 +53,8 @@ async function harness(withRegistry: boolean): Promise<{ ctx: Context; session: await ctx.plugin(AgentRegistry) if (withRegistry) await ctx.plugin(SessionProjectionRegistry) const session = ctx.sessions.create() - // history resolves the agent first; a live structural stub is enough (only - // .session is read on this path). - ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent) + // The gateway reads both the session and durable inbox baseline. + ctx.agents.register({ id: session.id, session, inbox: new Inbox(session), status: 'idle', ctx } as Agent) return { ctx, session } } From eb101230154e40dea237209e047759acf9d47cb0 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 03:57:57 -0700 Subject: [PATCH 032/689] test(web): simplify approval snapshot assertions --- apps/web/tests/built-boot.snapshot.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts index d436d41866..7ca9b5fbbb 100644 --- a/apps/web/tests/built-boot.snapshot.ts +++ b/apps/web/tests/built-boot.snapshot.ts @@ -106,11 +106,10 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn // distinguishes a blocked running session from an ordinarily busy one. const waitingTitle = await within(tree).findByText('Fixture 历史会话') const waitingRow = waitingTitle.closest('[role="treeitem"]') - expect(waitingRow).not.toBeNull() if (waitingRow === null) throw new Error('fixture Session title must belong to a tree row') expect(waitingRow.querySelector('[data-state="warning"]')).not.toBeNull() expect(waitingRow.querySelector('[data-state="ongoing"]')).toBeNull() - expect(within(waitingRow).getByText('Waiting for approval')).not.toBeNull() + within(waitingRow).getByText('Waiting for approval') // Opening a session reaches chat content through the fixture transport. fireEvent.click(waitingTitle) From e1fe6696dfe01ee03a42dae529bc162286a1c58e Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 19:52:46 +0800 Subject: [PATCH 033/689] test(web): refresh question composer disclosure --- .../tests/snapshots/question-composer/answered.expected.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/apps/web/tests/snapshots/question-composer/answered.expected.md b/apps/web/tests/snapshots/question-composer/answered.expected.md index 7f7603eb8a..692e0a5968 100644 --- a/apps/web/tests/snapshots/question-composer/answered.expected.md +++ b/apps/web/tests/snapshots/question-composer/answered.expected.md @@ -11,7 +11,10 @@ - img - button "编辑": - img -- button "▸ 上下文注入" +- button "上下文注入": + - img + - img + - text: 上下文注入 - button "Think The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that.": - img - img From e55a904e1d0b534a133cd998cc0918720fff0f5f Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 20:26:33 +0800 Subject: [PATCH 034/689] feat(web): render remote Markdown images --- ...026-07-23-web-assistant-markdown.i18n.yaml | 6 +- .../2026-07-23-web-assistant-markdown.md | 4 +- .../2026-07-23-web-assistant-markdown.zh.md | 4 +- ...07-30-web-remote-markdown-images.i18n.yaml | 6 + .../2026-07-30-web-remote-markdown-images.md | 29 +++ ...026-07-30-web-remote-markdown-images.zh.md | 29 +++ apps/web/tests/markdown-images.e2e.ts | 205 ++++++++++++++++++ .../snapshots/markdown-images/ui.expected.md | 33 +++ apps/web/tsconfig.json | 1 + .../client/ui-primitives/README.i18n.yaml | 4 +- packages/client/ui-primitives/README.md | 2 +- packages/client/ui-primitives/README.zh.md | 3 +- .../src/markdown/MarkdownText.module.css | 11 + .../src/markdown/MarkdownText.tsx | 27 ++- .../ui-primitives/tests/markdown.spec.tsx | 32 ++- tsconfig.host.json | 1 + 16 files changed, 381 insertions(+), 16 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.md create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.zh.md create mode 100644 apps/web/tests/markdown-images.e2e.ts create mode 100644 apps/web/tests/snapshots/markdown-images/ui.expected.md diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml index 1f52492649..656a52d300 100644 --- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-07-23-web-assistant-markdown.md: 38d193271d88b3a8f32ba1b191e8a6d432176281 -2026-07-23-web-assistant-markdown.zh.md: be3cd041c6012af142fc27934fda125dfc4cf6de +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md +2026-07-23-web-assistant-markdown.md: d5074e6090699229f5c43dd93eef0fdfbfedab76 +2026-07-23-web-assistant-markdown.zh.md: 31f0fd6835c9921f544f4b6217a0c834dff79859 diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md index 38d193271d..d5074e6090 100644 --- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md +++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md @@ -20,7 +20,7 @@ The dependency is explicit in `ui-primitives`; because that pure library is seed ## Untrusted output policy -Assistant-authored destinations are restricted to absolute HTTP, HTTPS, and mailto URLs. HTTP(S) links open in a new tab with `rel="noopener noreferrer"`; relative destinations and other protocols render as non-navigable text. Markdown images render only their alt text, so model output cannot initiate a remote image request. Raw HTML remains inert source text because no HTML parser enters the pipeline. Shiki output is a static span tree generated from the fence text (no scripts or user HTML). +Assistant-authored link destinations are restricted to absolute HTTP, HTTPS, and mailto URLs. HTTP(S) links open in a new tab with `rel="noopener noreferrer"`; relative destinations and other protocols render as non-navigable text. Markdown images follow the separate [remote-image policy](2026-07-30-web-remote-markdown-images.md). Raw HTML remains inert source text because no HTML parser enters the pipeline. Shiki output is a static span tree generated from the fence text (no scripts or user HTML). Fenced code and GFM tables own horizontal overflow so long content cannot widen the conversation column. @@ -32,7 +32,7 @@ Fenced code and GFM tables own horizontal overflow so long content cannot widen **Parse Markdown into session snapshots.** This would make React nodes or presentation ASTs durable runtime state and reintroduce a final-versus-streaming mode boundary. Parsing stays at the presentation leaf instead. -**Enable raw HTML or remote images with sanitization.** Neither capability has a current product need, while both enlarge the executable or network privacy boundary. They remain disabled rather than adding sanitizer and image-policy dependencies. +**Enable raw HTML with sanitization.** Raw HTML has no current product need and would enlarge the executable-content boundary, so it remains disabled rather than adding a sanitizer dependency. Remote images are governed by the later [image policy](2026-07-30-web-remote-markdown-images.md). **Port deepsuite Prism `highlight.css` and the mdast pipeline.** Appearance parity is owned by CSS Modules and shared `--dsw-*` tokens; highlighting stays on the existing shiki allowlist so the client does not take a second highlighter or Prism class contract. diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md index be3cd041c6..31f0fd6835 100644 --- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md +++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md @@ -20,7 +20,7 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd ## 不受信任输出策略 -assistant 生成的目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。HTTP(S) 链接会在新标签页中打开，并带有 `rel="noopener noreferrer"`；相对目标地址与其他协议会渲染为不可导航的文本。Markdown 图片仅渲染替代文本，因此模型输出无法发起远程图片请求。由于管线中未引入 HTML 解析器，原始 HTML 仍是不会生效的源文本。Shiki 输出是由围栏文本生成的静态 span 树（不含脚本或用户 HTML）。 +assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。HTTP(S) 链接会在新标签页中打开，并带有 `rel="noopener noreferrer"`；相对目标地址与其他协议会渲染为不可导航的文本。Markdown 图片遵循独立的[远程图片策略](2026-07-30-web-remote-markdown-images.md)。由于流水线中未引入 HTML 解析器，原始 HTML 仍是不会生效的源文本。Shiki 输出是由围栏文本生成的静态 span 树（不含脚本或用户 HTML）。 围栏代码与 GFM 表格各自处理横向溢出，因此较长内容无法撑宽对话栏。 @@ -32,7 +32,7 @@ assistant 生成的目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。HTTP(S **将 Markdown 解析为会话快照。**这会让 React 节点或呈现层 AST 成为持久的运行时状态，并重新引入最终输出与流式输出之间的模式边界。解析仍留在呈现层的叶节点中。 -**通过净化启用原始 HTML 或远程图片。**当前产品并不需要这两项功能，但二者都会扩大可执行行为或网络隐私边界。因此它们保持禁用，无需增加净化器与图片策略依赖。 +**通过净化启用原始 HTML。** 原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。 **移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 契约。 diff --git a/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.i18n.yaml new file mode 100644 index 0000000000..afe776d402 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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/feature/2026-07-30-web-remote-markdown-images.md +2026-07-30-web-remote-markdown-images.md: 23dc699aab87597b7b5bfee83d0d745d4798303e +2026-07-30-web-remote-markdown-images.zh.md: 54db9b25e9f558d77c84bb67c05fadea2c9086ac diff --git a/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.md b/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.md new file mode 100644 index 0000000000..23dc699aab --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.md @@ -0,0 +1,29 @@ +# Agent Note: Remote Web Markdown images + +Status: implemented + +English | [中文](2026-07-30-web-remote-markdown-images.zh.md) + +## Problem + +Assistant Markdown can name diagrams and screenshots with standard image syntax, but the Web renderer replaces every image with italic alt text. Even absolute HTTP(S) destinations therefore lose ordinary Markdown behavior. + +## Decision + +`MarkdownText` renders absolute HTTP(S) image destinations as lazy, responsive `` elements with asynchronous decoding and `referrerPolicy="no-referrer"`. Relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain the existing alt-text fallback. Raw HTML stays disabled, so an assistant cannot bypass the Markdown image component with a hand-authored ``. + +The image component reuses the renderer's absolute-URL policy without adding a host proxy, local-file route, Session dependency, sanitizer, or image fetcher. Finalized history, streaming output, interrupted partials, and every other `MarkdownText` consumer receive the same behavior. + +## Alternatives considered + +**Keep all images as alt text.** This preserves the smallest network boundary but defeats the product need to inspect network-hosted visual artifacts inline. + +**Proxy remote images through the host.** A proxy could hide the browser's network address from the image origin, but it would make the host perform arbitrary outbound fetches and require a separate redirect, DNS, size, and content policy. Direct HTTP(S) loading keeps that request visible to browser controls; omitting the referrer limits conversation-origin disclosure. + +**Support local paths in the same change.** Web origins cannot directly load host files. A safe implementation needs a separately reviewed authority boundary, so relative paths, absolute local paths, and `file:` URLs remain disabled. + +**Allow `data:` images.** Large data URLs duplicate binary content into durable transcript text. The HTTP(S)-only policy covers the current need without expanding session logs. + +## Consequences + +Assistant replies display remote images during streaming and replay without changing session events or host protocols. Remote origins still observe the image request, client network address, and any credentials that browser policy permits for that origin. Local and unsupported destinations remain inert alt text. diff --git a/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.zh.md new file mode 100644 index 0000000000..54db9b25e9 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-web-remote-markdown-images.zh.md @@ -0,0 +1,29 @@ +# Agent Note: Web 中的远程 Markdown 图片 + +Status: implemented + +[English](2026-07-30-web-remote-markdown-images.md) | 中文 + +## 问题 + +assistant Markdown 可以使用标准图片语法引用图表和截图，但 Web 渲染器会把每张图片替换为斜体替代文本。因此，即使目标地址是绝对 HTTP(S) URL，也无法获得普通的 Markdown 图片行为。 + +## 决策 + +`MarkdownText` 将绝对 HTTP(S) 图片目标地址渲染为延迟加载的响应式 `` 元素，并使用异步解码与 `referrerPolicy="no-referrer"`。相对路径、绝对本地路径、`file:` URL 与不支持的协议继续沿用现有的替代文本回退。原始 HTML 保持禁用，因此 assistant 无法通过手写 `` 绕过 Markdown 图片组件。 + +图片组件复用渲染器的绝对 URL 策略，不新增主机代理、本地文件路由、Session 依赖、净化器或图片抓取器。已完成的历史消息、流式输出、被中断的部分输出以及其他所有 `MarkdownText` 消费方均获得同一行为。 + +## 考虑过的替代方案 + +**将所有图片都保留为替代文本。** 这种方案维持了最小的网络边界，但无法满足在行内查看网络托管的视觉产物这一产品需求。 + +**通过主机代理远程图片。** 代理可以向图片源站隐藏浏览器的网络地址，但这会让主机执行任意出站请求，并且需要单独制定重定向、DNS、大小与内容策略。直接加载 HTTP(S) 图片可让浏览器控制机制继续观察该请求；不发送 referrer 可减少对话来源信息的暴露。 + +**在同一变更中支持本地路径。** Web 源无法直接加载主机文件。安全的实现需要单独评审的权限边界，因此相对路径、绝对本地路径与 `file:` URL 保持禁用。 + +**允许 `data:` 图片。** 大型 data URL 会将二进制内容以文本形式重复写入持久化的 transcript（文本记录）。仅允许 HTTP(S) 的策略足以满足当前需求，且不会扩大会话日志。 + +## 后果 + +assistant 回复会在流式输出与回放期间显示远程图片，且不改变会话事件或主机协议。远程源站仍可观察到图片请求、客户端网络地址，以及浏览器策略允许发送给该源站的任何凭据。本地及不支持的目标地址仍只显示不会发起请求的替代文本。 diff --git a/apps/web/tests/markdown-images.e2e.ts b/apps/web/tests/markdown-images.e2e.ts new file mode 100644 index 0000000000..8dce7f405b --- /dev/null +++ b/apps/web/tests/markdown-images.e2e.ts @@ -0,0 +1,205 @@ +// Web e2e scenario: absolute HTTP(S) Markdown images. A validated session +// assembled through the Session API is seeded cold into the real web +// composition, then a separate image origin proves that the browser receives +// a real network image while local-path Markdown remains inert alt text. +import { createServer, type Server } from 'node:http' +import { fileURLToPath } from 'node:url' +import type { Browser, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm' +import { + SESSION_FORMAT_VERSION, + Session, + SessionId, +} from '@deepseek-ai/dsh-session' +import type {} from '@deepseek-ai/dsh-session-title' +import { + assertFixtureInventory, + captureStableAria, + compareOrRefreshGolden, + launchWebScaffold, + seedSession, + watchConsole, + webSnapshotMode, + type WebScaffold, +} from './scaffold.ts' +import { newEnglishPage, saveFailureShot } from './support.ts' + +const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/markdown-images', import.meta.url)) +const UI_EXPECTED = fileURLToPath(new URL('./snapshots/markdown-images/ui.expected.md', import.meta.url)) +const MODE = webSnapshotMode() +const SEED_ID = 'markdown-images-web-e2e' +const REMOTE_ALT = 'Remote test image' +const LOCAL_ALT = 'Local test image' +const PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', + 'base64', +) + +interface ImageOrigin { + server: Server + url: string + requests: Array<{ path: string | undefined; referer: string | undefined }> +} + +/** Start the deterministic remote image origin used by this browser scenario. */ +async function startImageOrigin(): Promise { + const requests: ImageOrigin['requests'] = [] + const server = createServer((request, response) => { + requests.push({ path: request.url, referer: request.headers.referer }) + response.writeHead(200, { + 'cache-control': 'no-store', + 'content-length': PNG.length, + 'content-type': 'image/png', + }) + response.end(PNG) + }) + await new Promise((resolve, reject) => { + server.once('error', reject) + server.listen(0, '127.0.0.1', resolve) + }) + const address = server.address() + if (address === null || typeof address === 'string') { + throw new Error('image origin did not expose an IP socket') + } + return { + server, + url: `http://127.0.0.1:${String(address.port)}/image.png`, + requests, + } +} + +/** Stop one image origin after the browser and host release their requests. */ +async function stopServer(server: Server): Promise { + await new Promise((resolve, reject) => { + server.close((error) => { + if (error === undefined) resolve() + else reject(error) + }) + }) +} + +/** Build one closed, invariant-checked session fixture with remote and local image Markdown. */ +function markdownImageFixture(remoteUrl: string): string { + const session = new Session(SessionId('markdown-image-source')) + session.append('turn/start', { + turn: 1, + trigger: { kind: 'message', source: { kind: 'user' } }, + }) + const user = session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'Show the Markdown image policy.' }], + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + session.append('session/title', { + title: 'Markdown image policy', + messageSeqs: [user.seq], + source: { kind: 'fallback' }, + }) + session.append('step/start', { turn: 1, step: 1 }) + session.append('assistant/message', { + turn: 1, + step: 1, + message: createMessage({ + role: 'assistant', + content: [{ + type: 'text', + text: [ + '## Markdown images', + '', + `![${REMOTE_ALT}](${remoteUrl})`, + '', + `![${LOCAL_ALT}](./local-image.png)`, + '', + 'REMOTE_IMAGE_DONE', + ].join('\n'), + }], + source: { kind: 'model', provider: 'fixture', model: 'fixture' }, + }), + }, { surfaceOp: 'append' }) + session.append('step/end', { turn: 1, step: 1 }) + session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + + const header = { + type: 'session', + version: SESSION_FORMAT_VERSION, + id: '{{sessionId}}', + createdAt: 0, + cwd: '{{cwd}}', + } + return [ + JSON.stringify(header), + ...session.events.map(event => JSON.stringify(event)), + '', + ].join('\n') +} + +describe('web e2e: remote Markdown image rendering', () => { + let scaffold: WebScaffold + let imageOrigin: ImageOrigin + let browser: Browser + let page: Page + let tripwire: ReturnType + + beforeAll(async () => { + imageOrigin = await startImageOrigin() + scaffold = await launchWebScaffold({}) + await seedSession(scaffold, markdownImageFixture(imageOrigin.url), SEED_ID) + browser = await chromium.launch() + page = await newEnglishPage(browser) + tripwire = watchConsole(page) + await page.goto(scaffold.baseUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + }, 120_000) + + afterAll(async () => { + await browser?.close() + await scaffold?.close() + await stopServer(imageOrigin.server) + }) + + it.skipIf(MODE === 'record')('loads only the remote image and matches the conversation golden', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-images')) + const groupRow = page.locator('[role="treeitem"]').first() + await groupRow.waitFor({ timeout: 15_000 }) + await groupRow.click() + const sessionRow = page.locator('[role="treeitem"]').nth(1) + await sessionRow.waitFor({ timeout: 10_000 }) + await sessionRow.click() + await expect.poll(() => page.getByText('REMOTE_IMAGE_DONE', { exact: true }).count(), { + timeout: 15_000, + }).toBe(1) + + const image = page.getByRole('img', { name: REMOTE_ALT }) + await image.waitFor({ timeout: 10_000 }) + await expect.poll(() => image.evaluate(element => (element as HTMLImageElement).naturalWidth), { + timeout: 10_000, + }).toBeGreaterThan(0) + expect(await image.evaluate((element) => { + const computed = getComputedStyle(element) + return { + borderRadius: computed.borderRadius, + decoding: element.getAttribute('decoding'), + loading: element.getAttribute('loading'), + maxWidth: computed.maxWidth, + referrerPolicy: element.getAttribute('referrerpolicy'), + } + })).toEqual({ + borderRadius: '8px', + decoding: 'async', + loading: 'lazy', + maxWidth: '100%', + referrerPolicy: 'no-referrer', + }) + expect(await page.getByRole('img', { name: LOCAL_ALT }).count()).toBe(0) + expect(await page.getByText(LOCAL_ALT, { exact: true }).count()).toBe(1) + expect(imageOrigin.requests).toEqual([{ path: '/image.png', referer: undefined }]) + + const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)) + .split(SEED_ID).join('{{seededId}}') + await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md']) + }, 60_000) +}) diff --git a/apps/web/tests/snapshots/markdown-images/ui.expected.md b/apps/web/tests/snapshots/markdown-images/ui.expected.md new file mode 100644 index 0000000000..cd33a09eb9 --- /dev/null +++ b/apps/web/tests/snapshots/markdown-images/ui.expected.md @@ -0,0 +1,33 @@ +- banner: + - navigation "Session hierarchy": + - button "Markdown image policy" [disabled] + - tablist: + - tab "Chat" [selected] + - tab "Trajectory" +- text: Show the Markdown image policy. {{clock}} +- button "复制": + - img +- button "在新对话中分支": + - img +- button "编辑": + - img +- heading "Markdown images" [level=2] +- paragraph: + - img "Remote test image" +- paragraph: Local test image +- paragraph: REMOTE_IMAGE_DONE +- button "复制": + - img +- button "在新对话中分支": + - img +- text: {{clock}} +- textbox "Message the agent" +- button "Add attachment": + - img +- 'button "Access mode, current: Danger Full Access"': Danger Full Access +- button "Plan mode off, press to turn on": Plan off +- button "Select model, current deepseek-v4-flash": + - text: deepseek-v4-flash + - img +- button "Send message" [disabled] +- text: 1 turns · 1 steps Input 0 tok · Output 0 tok diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 7a7f228fb0..ce1f2105af 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -37,6 +37,7 @@ "tests/code-mode-round.e2e.ts", "tests/cordis-tool-round.e2e.ts", "tests/message-actions.e2e.ts", + "tests/markdown-images.e2e.ts", "tests/queue-actions.e2e.ts", "tests/skill-invocation-policy.e2e.ts" ], diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index b5e4b5c078..e24142ebcf 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.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 packages/client/ui-primitives/README.md -README.md: 0ef3c20f848b3d331c007911d0837f11cd72c024 -README.zh.md: af94551bfb9e12dbadcef6a96a54f9bf7ea71299 +README.md: 929d2edd9ddbd4610f84dd901486f74700cbf4e2 +README.zh.md: 5c6df2ce58e274a53b7792597259749f9a45d4ca diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index 0ef3c20f84..929d2edd9d 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -6,7 +6,7 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/ ## Markdown rendering -`MarkdownText` renders GFM from untrusted assistant output through React elements. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders image alt text without loading remote resources; `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars). +`MarkdownText` renders GFM from untrusted assistant output through React elements. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars). ## Terminal output diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index af94551bfb..5c6df2ce58 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -6,7 +6,8 @@ ## Markdown 渲染 -`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并只渲染图片 alt 文本而不加载远程资源；`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。 +`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不携带 referrer 的情况下渲染绝对 HTTP(S) 图片；相对路径、绝对本地路径、`file:` URL 与不支持的协议仍保留其替代文本。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。 + ## 终端输出 `TerminalBlock` 将一条 shell 命令渲染为终端表层：命令的每一行各占一个提示行（缩短后的 `cwd` 标签只出现在第一行，因为视图只知道一个工作目录，而一个 `cd` 就会让后面的行去到别处，标签之后是该行）、命令输出、非零退出码或终止信号对应的状态胶囊，以及写入原始 `output` prop 的复制控件。一枚运行状态 `StateDot` 为整次调用标记一次，位于第一行，以脱离文档流的方式落在卡片以自身左内边距预留的落区中，因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画，与渲染状态胶囊相同的退出状态为红色，其余为绿色——因此卡片直接陈述其命令是否仍在运行，而不是让人从有无输出中推断；由于 `StateDot` 是 `aria-hidden`，它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之：退出状态属于整次调用，因此每行一枚就会声称一个视图并不携带的逐行结果。命令文本使用 `white-space: pre`，因此重复空格、制表符与缩进续行都原样呈现，同时该行仍保持单行并以省略号截断。ANSI 转义序列通过运行时依赖 `anser` 解析为 React span；光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲，因为回车与退格**只移动**光标：单是 `100%` 加回车再加 `OK` 显示为 `OK0%`，而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴，因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循，光标按终端列推进（8 列制表位；emoji 与 CJK 占两列；组合标记不占列），SGR 状态按单元格归一化存储，与终端一致，并跨行延续、在行结束时的状态处收束；基础 16 色前景色映射到 `--dsw-*` token，而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动，因此按列对齐的输出保留其对齐而不会软换行；超过 `maxLines`（默认 16，与 TUI 转录相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。原理：[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)。 diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css index a189528bc9..03bec019bd 100644 --- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css +++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css @@ -224,3 +224,14 @@ color: var(--dsw-alias-label-tertiary); font-style: italic; } + +.image { + display: block; + width: auto; + max-width: 100%; + height: auto; + margin: 0; + border-radius: 8px; + background: var(--dsw-alias-bg-base); + object-fit: contain; +} diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx index 639f53dbb1..ff6f543ebc 100644 --- a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx +++ b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx @@ -24,6 +24,15 @@ function sanitizeUrl(url: string): string { const safeUrl: UrlTransform = url => sanitizeUrl(url) +function remoteImageUrl(url: string): string | undefined { + try { + const protocol = new URL(url).protocol + return protocol === 'http:' || protocol === 'https:' ? url : undefined + } catch { + return undefined + } +} + /** Build the component table; while `streaming`, fences render the plain arm (see CodeBlock). */ function buildComponents(streaming: boolean): Components { return { @@ -40,7 +49,20 @@ function buildComponents(streaming: boolean): Components { ) }, - img: ({ alt = '' }) => {alt}, + img: ({ alt = '', src = '' }) => { + const imageSrc = remoteImageUrl(src) + if (imageSrc === undefined) return {alt} + return ( + {alt} + ) + }, table: ({ children }) => (
{children}
@@ -74,7 +96,8 @@ const streamingComponents = buildComponents(true) * Render untrusted assistant-authored Markdown as semantic React elements. * @param props - Markdown source text preserved by the session projection; * `streaming` renders fences plain (highlighting lands on the finalize swap). - * @returns A GFM document with raw HTML, relative links, unsafe protocols, and remote images disabled. + * @returns A GFM document with raw HTML, relative destinations, and unsafe + * protocols disabled; absolute HTTP(S) images render directly. */ export function MarkdownText({ text, streaming = false }: { text: string; streaming?: boolean }) { return ( diff --git a/packages/client/ui-primitives/tests/markdown.spec.tsx b/packages/client/ui-primitives/tests/markdown.spec.tsx index b7f665c78a..40295e16cb 100644 --- a/packages/client/ui-primitives/tests/markdown.spec.tsx +++ b/packages/client/ui-primitives/tests/markdown.spec.tsx @@ -94,13 +94,35 @@ describe('MarkdownText', () => { expect(done.container.querySelector('pre.shiki')).not.toBeNull() }) - it('neutralizes raw HTML, unsafe or relative links, and remote images', () => { + it('renders absolute HTTP(S) images with bounded presentation', () => { + const markdown = [ + '![secure diagram](https://example.com/secure.png)', + '![plain diagram](http://example.com/plain.png)', + ].join('\n\n') + const { container } = render() + const images = [...container.querySelectorAll('img')] + expect(images.map(image => image.getAttribute('src'))).toEqual([ + 'https://example.com/secure.png', + 'http://example.com/plain.png', + ]) + for (const image of images) { + expect(image.getAttribute('loading')).toBe('lazy') + expect(image.getAttribute('decoding')).toBe('async') + expect(image.getAttribute('referrerpolicy')).toBe('no-referrer') + } + }) + + it('neutralizes raw HTML, unsafe or relative links, and unsupported images', () => { const markdown = [ '', '', '[script](javascript:alert(1)) [relative](/settings)', '[mail](mailto:dev@example.com) [web](http://example.com) [upper](HTTPS://example.com)', - '![remote diagram](https://example.com/private.png)', + '![relative diagram](private.png)', + '![absolute diagram](/workspace/private.png)', + '![file diagram](file:///workspace/private.png)', + '![script diagram](javascript:alert(1))', + '![mail diagram](mailto:dev@example.com)', ].join('\n\n') const { container } = render() @@ -112,7 +134,11 @@ describe('MarkdownText', () => { expect(screen.getByRole('link', { name: 'mail' }).getAttribute('target')).toBeNull() expect(screen.getByRole('link', { name: 'web' }).getAttribute('rel')).toBe('noopener noreferrer') expect(screen.getByRole('link', { name: 'upper' }).getAttribute('target')).toBe('_blank') - expect(screen.getByText('remote diagram')).toBeTruthy() + expect(screen.getByText('relative diagram')).toBeTruthy() + expect(screen.getByText('absolute diagram')).toBeTruthy() + expect(screen.getByText('file diagram')).toBeTruthy() + expect(screen.getByText('script diagram')).toBeTruthy() + expect(screen.getByText('mail diagram')).toBeTruthy() }) it('keeps incomplete streaming Markdown renderable', () => { diff --git a/tsconfig.host.json b/tsconfig.host.json index b32c410961..795f5ae8d5 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -24,6 +24,7 @@ "apps/web/tests/code-mode-round.e2e.ts", "apps/web/tests/cordis-tool-round.e2e.ts", "apps/web/tests/message-actions.e2e.ts", + "apps/web/tests/markdown-images.e2e.ts", "apps/web/tests/queue-actions.e2e.ts", "apps/web/tests/skill-invocation-policy.e2e.ts", "apps/cli/tests/**/*.ts", From 060c0f78f08a684ff8bc238284068394cfe330da Mon Sep 17 00:00:00 2001 From: _Kerman Date: Fri, 31 Jul 2026 10:01:35 +0800 Subject: [PATCH 035/689] fix(agent): restore public send method --- docs/cordis-catalog/events.md | 20 +++++++++---------- docs/core-data-structures/core.i18n.yaml | 4 ++-- docs/core-data-structures/core.md | 11 +++++++++- docs/core-data-structures/core.zh.md | 11 +++++++++- .../time-context/tests/time-context.spec.ts | 1 + .../tmux-context/tests/tmux-context.spec.ts | 1 + .../tests/workspace-context.spec.ts | 1 + .../cordis/tool-cordis/src/api-catalog.ts | 2 +- packages/core/agent-loop/src/agent.ts | 10 +++++----- packages/core/agent/src/types.ts | 9 +++++++++ packages/core/agent/tests/agent.spec.ts | 1 + .../tests/tools.spec.ts | 1 + .../command-goal/tests/command-goal.spec.ts | 1 + packages/goal/goal/tests/goal.spec.ts | 1 + packages/goal/goal/tests/projection.spec.ts | 1 + .../goal/tool-goal/tests/tool-goal.spec.ts | 1 + .../tests/api-proxy-workspace.spec.ts | 1 + packages/pty/pty-local/tests/index.spec.ts | 6 +++--- packages/pty/pty-local/tests/local.spec.ts | 2 +- packages/pty/pty/tests/service.spec.ts | 1 + .../tests/loader-composition.spec.ts | 1 + .../tool-bash-persistent/tests/tools.spec.ts | 1 + .../tool-pty/tests/loader-composition.spec.ts | 2 +- packages/pty/tool-pty/tests/tools.spec.ts | 2 +- .../skill/tool-skill/tests/tool-skill.spec.ts | 2 ++ .../tasks/tasks-local/tests/tasks.spec.ts | 1 + packages/ui/tui/tests/harness.ts | 1 + packages/ui/tui/tests/tui.spec.ts | 12 +++++------ 28 files changed, 76 insertions(+), 32 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 0c012e58da..2fd95806b1 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -33,7 +33,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:151`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:160`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -53,7 +53,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:160`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:169`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -75,7 +75,7 @@ A step or turn errored. The machine reports a failure here (plus the logger) eve Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:261`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:270`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -98,7 +98,7 @@ Allow, rewrite, or block one claimed inbox batch before it becomes model-visible Types: [Agent](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) -Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:205`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall @@ -122,7 +122,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:222`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:231`](../../packages/core/agent/src/types.ts) ### `agent/request-error` — waterfall @@ -145,7 +145,7 @@ Handle one failed model-request attempt before the loop retries or closes its st Types: [Agent](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [RequestFailureContext](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:234`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -167,7 +167,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:182`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:191`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -188,7 +188,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:170`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:179`](../../packages/core/agent/src/types.ts) ### `agent/step` — serial @@ -212,7 +212,7 @@ Awaited serial checkpoint before EVERY request of a turn is built (the first as Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:209`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:218`](../../packages/core/agent/src/types.ts) ### `agent/turn-stopping` — serial @@ -238,7 +238,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:249`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:258`](../../packages/core/agent/src/types.ts) ## `agent-loop/*` diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index 84c2a906c4..5b8ffc1995 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md -core.md: 3bbfe3c4c763a24edb6ec1362344cef6ce50f650 -core.zh.md: d54159c25659a89baded31b8e3aa5207715e0c12 +core.md: 9c1015ddeedcf3355d03678088ec7bcc6759d677 +core.zh.md: 840cc929a7c63b63b3eb2d860b59ace2f1a63ed5 diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 3bbfe3c4c7..9c1015ddee 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -441,7 +441,7 @@ type AgentCancelCause = | { readonly kind: 'disposed' } ``` -`Agent` is an interface over the public live-agent contract. Concrete drivers implement `followup`, `steer`, and `inject`; routing policy remains private to the driver. +`Agent` is an interface over the public live-agent contract. Its unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases. ```ts type-equiv /** Public live-agent handle. */ @@ -476,6 +476,15 @@ interface Agent { */ whenIdle(): Promise + /** + * Route identified input to an inbox boundary and optionally wake the driver. + * Waking input submitted after active cancellation is queued for the next turn. + * @param message - identified content and its producer provenance. + * @param target - the preferred next-turn or next-step inbox boundary. + * @param wakeup - whether delivery may wake the driver. + */ + send(message: UserMessage, target: InboxTarget, wakeup: boolean): void + /** * Queue an ordinary follow-up turn and wake the driver. The item becomes the * sole ordinary message of its own turn. diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index d54159c256..840cc929a7 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -449,7 +449,7 @@ type AgentCancelCause = | { readonly kind: 'disposed' } ``` -`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器实现 `followup`、`steer` 和 `inject`；路由策略仍为驱动器私有。 +`Agent` 是覆盖公开活跃 agent 契约的接口。它的统一 `send` 方法直接公开目标与唤醒路由；`followup`、`steer` 和 `inject` 是固定预设别名。 ```ts type-equiv /** Public live-agent handle. */ @@ -484,6 +484,15 @@ interface Agent { */ whenIdle(): Promise + /** + * Route identified input to an inbox boundary and optionally wake the driver. + * Waking input submitted after active cancellation is queued for the next turn. + * @param message - identified content and its producer provenance. + * @param target - the preferred next-turn or next-step inbox boundary. + * @param wakeup - whether delivery may wake the driver. + */ + send(message: UserMessage, target: InboxTarget, wakeup: boolean): void + /** * Queue an ordinary follow-up turn and wake the driver. The item becomes the * sole ordinary message of its own turn. diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts index 17e86c3562..fb246cf068 100644 --- a/packages/context/time-context/tests/time-context.spec.ts +++ b/packages/context/time-context/tests/time-context.spec.ts @@ -43,6 +43,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { inbox: new Inbox(session), status: 'running', ctx: new Context(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => { throw new Error('time-context must append directly to the open step') }, diff --git a/packages/context/tmux-context/tests/tmux-context.spec.ts b/packages/context/tmux-context/tests/tmux-context.spec.ts index 097cc66802..941838c001 100644 --- a/packages/context/tmux-context/tests/tmux-context.spec.ts +++ b/packages/context/tmux-context/tests/tmux-context.spec.ts @@ -99,6 +99,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent { inbox: new Inbox(session), status: 'running', ctx: new Context(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => { throw new Error('tmux-context must append directly to the open step') }, diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index 04e7fa4fdc..1ed1140624 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -178,6 +178,7 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent { session, inbox: new Inbox(session), status: 'idle', + send: () => {}, followup: () => {}, steer: () => {}, inject: () => { throw new Error('workspace-context must append directly to the open step') }, diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index ad9e760157..9747c667d7 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -1419,7 +1419,7 @@ export const EVENT_API: readonly EventApiEntry[] = [ export const TYPE_API: readonly TypeApiEntry[] = [ { name: 'Agent', - declaration: 'export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly inbox: Inbox;\n readonly status: AgentStatus;\n readonly ctx: Context;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n}', + declaration: 'export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly inbox: Inbox;\n readonly status: AgentStatus;\n readonly ctx: Context;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n}', }, { name: 'AgentCancelCause', diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 144a12634c..c125837462 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -81,7 +81,7 @@ export class ReactLoopAgent implements Agent { } } - private send(message: UserMessage, target: InboxTarget, wakeup: boolean): void { + send(message: UserMessage, target: InboxTarget, wakeup: boolean): void { // Waking input cannot join an aborted admission or turn, so it starts the next turn. const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted const resolvedTarget = wakingAfterAbort ? 'next-turn' : target @@ -180,7 +180,7 @@ export class ReactLoopAgent implements Agent { if (admission.kind !== 'admitted') return false signal.throwIfAborted() } catch (error: unknown) { - // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- cancel may abort while admission awaits + // oxlint-disable-next-line typescript/no-unnecessary-condition -- cancel may abort while admission awaits if (signal.aborted) return this.inbox.hasPending throw error } @@ -216,11 +216,11 @@ export class ReactLoopAgent implements Agent { if (admission.kind === 'empty' && turnEnds) break } } catch (error: unknown) { - // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- cancel may abort during any awaited turn operation + // oxlint-disable-next-line typescript/no-unnecessary-condition -- cancel may abort during any awaited turn operation if (signal.aborted) turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } else turnEnds = { kind: 'error', error: errorChain(error) } } finally { - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the turn is always ended in this block + // oxlint-disable-next-line typescript/no-non-null-assertion -- the turn is always ended in this block this.session.append('turn/end', { turn, reason: turnEnds! }) } return this.inbox.hasPending @@ -317,7 +317,7 @@ export class ReactLoopAgent implements Agent { : undefined const maxTokens = this.options.maxTokens const seedConfig = this.requestHeaderLogged - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the instance logged the frozen header it now folds + // oxlint-disable-next-line typescript/no-non-null-assertion -- the instance logged the frozen header it now folds ? persistedConfig! : deepFreeze({ ...route, diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 29f536e2c0..456a7f95fe 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -109,6 +109,15 @@ export interface Agent { */ whenIdle(): Promise + /** + * Route identified input to an inbox boundary and optionally wake the driver. + * Waking input submitted after active cancellation is queued for the next turn. + * @param message - identified content and its producer provenance. + * @param target - the preferred next-turn or next-step inbox boundary. + * @param wakeup - whether delivery may wake the driver. + */ + send(message: UserMessage, target: InboxTarget, wakeup: boolean): void + /** * Queue an ordinary follow-up turn and wake the driver. The item becomes the * sole ordinary message of its own turn. diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts index 8ffc467e20..7d9b4399fa 100644 --- a/packages/core/agent/tests/agent.spec.ts +++ b/packages/core/agent/tests/agent.spec.ts @@ -24,6 +24,7 @@ function stubAgent(rawId: string, overrides: Partial = {}): Agent { inbox: new Inbox(session), status: 'idle', ctx: new Context(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts index 268fa8fa28..ef776d4de4 100644 --- a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts +++ b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts @@ -36,6 +36,7 @@ function agent(ctx: Context, cwd: string): Agent { inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/goal/command-goal/tests/command-goal.spec.ts b/packages/goal/command-goal/tests/command-goal.spec.ts index f7a1a5b304..78ba5abd6c 100644 --- a/packages/goal/command-goal/tests/command-goal.spec.ts +++ b/packages/goal/command-goal/tests/command-goal.spec.ts @@ -37,6 +37,7 @@ function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } inbox: new Inbox(session), ctx: new Context(), get status() { return status }, + send: () => {}, followup: () => {}, steer: () => {}, inject(input) { appendInjection(session, input) }, diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts index b4802204dc..47c9b6b1ad 100644 --- a/packages/goal/goal/tests/goal.spec.ts +++ b/packages/goal/goal/tests/goal.spec.ts @@ -47,6 +47,7 @@ function stubAgentForSession(session: Session): StubAgent { inbox: new Inbox(session), ctx: new Context(), get status() { return status }, + send: () => {}, followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/goal/goal/tests/projection.spec.ts b/packages/goal/goal/tests/projection.spec.ts index 23496935e6..ccff0b7491 100644 --- a/packages/goal/goal/tests/projection.spec.ts +++ b/packages/goal/goal/tests/projection.spec.ts @@ -38,6 +38,7 @@ function liveAgent(ctx: Context, session: Session): Agent { inbox: new Inbox(session), ctx, get status() { return status }, + send: () => {}, followup: () => {}, steer: () => {}, inject(input: UserMessage) { diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts index 89ff0206a6..b99463a586 100644 --- a/packages/goal/tool-goal/tests/tool-goal.spec.ts +++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts @@ -32,6 +32,7 @@ function stubAgent(rawId: string, supplied?: Session): StubAgent { inbox: new Inbox(session), get status() { return status }, ctx: new Context(), + send: () => {}, followup: () => {}, steer: () => {}, inject(input) { diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts index c8f522f950..1b324a9794 100644 --- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts @@ -47,6 +47,7 @@ function stubAgent(session: Session): Agent { inbox: new Inbox(session), status: 'idle', ctx: new Context(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts index 46cc691a38..1000d0e78a 100644 --- a/packages/pty/pty-local/tests/index.spec.ts +++ b/packages/pty/pty-local/tests/index.spec.ts @@ -43,7 +43,7 @@ function agent(ctx: Context): Agent { const session = new Session(id) return { id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } @@ -250,7 +250,7 @@ describe('pty-local plugin shape', () => { const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: ownerFiber.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession()) @@ -293,7 +293,7 @@ describe('pty-local plugin shape', () => { const ownerFiber = await ctx.plugin(() => {}) const owner: Agent = { id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: ownerFiber.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(owner) const gate = Promise.withResolvers() diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts index 1a52bcc672..96d59367ec 100644 --- a/packages/pty/pty-local/tests/local.spec.ts +++ b/packages/pty/pty-local/tests/local.spec.ts @@ -36,7 +36,7 @@ function stubAgent(ctx: Context, rawId: string): Agent { const session = new Session(id) return { id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } } diff --git a/packages/pty/pty/tests/service.spec.ts b/packages/pty/pty/tests/service.spec.ts index 5cb1dea2d0..1b885e1c5e 100644 --- a/packages/pty/pty/tests/service.spec.ts +++ b/packages/pty/pty/tests/service.spec.ts @@ -29,6 +29,7 @@ function stubAgent(ctx: Context, rawId: string): Agent { inbox: new Inbox(session), status: 'idle', ctx: scopeFiber.ctx, + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts index 68f08223ff..e49c652f1d 100644 --- a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts +++ b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts @@ -46,6 +46,7 @@ function agent(ctx: Context, cwd: string): Agent { inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/pty/tool-bash-persistent/tests/tools.spec.ts b/packages/pty/tool-bash-persistent/tests/tools.spec.ts index b0e64b770c..76cd72f2e8 100644 --- a/packages/pty/tool-bash-persistent/tests/tools.spec.ts +++ b/packages/pty/tool-bash-persistent/tests/tools.spec.ts @@ -42,6 +42,7 @@ function agent(ctx: Context, cwd: string | undefined): Agent { inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts index 29ad29e65d..ca7bc6a3e8 100644 --- a/packages/pty/tool-pty/tests/loader-composition.spec.ts +++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts @@ -41,7 +41,7 @@ function agent(ctx: Context): Agent { const session = new Session(id) const value: Agent = { id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(value) return value diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts index bc25489fcf..13bd8b9e23 100644 --- a/packages/pty/tool-pty/tests/tools.spec.ts +++ b/packages/pty/tool-pty/tests/tools.spec.ts @@ -19,7 +19,7 @@ function fakeAgent(ctx: Context, rawId: string): Agent { const session = new Session(id) const agent: Agent = { id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx: scope.ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } ctx.agents.register(agent) return agent diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts index c633e8faca..cf9ed4b1c7 100644 --- a/packages/skill/tool-skill/tests/tool-skill.spec.ts +++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts @@ -46,6 +46,7 @@ function agentForCwd(cwd: string): Agent { session, inbox: new Inbox(session), status: 'idle', + send: () => {}, followup: () => {}, steer: () => {}, inject: () => { throw new Error('step-boundary catalog must not use agent.inject()') }, @@ -62,6 +63,7 @@ function sessionAgent(session: Session, id = 'tool-skill-agent'): Agent { inbox: new Inbox(session), status: 'running', ctx: new Context(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => { throw new Error('step-boundary catalog must not use agent.inject()') }, diff --git a/packages/tasks/tasks-local/tests/tasks.spec.ts b/packages/tasks/tasks-local/tests/tasks.spec.ts index c3495a1cd2..3f5fd22db1 100644 --- a/packages/tasks/tasks-local/tests/tasks.spec.ts +++ b/packages/tasks/tasks-local/tests/tasks.spec.ts @@ -26,6 +26,7 @@ function stubAgent(ctx: Context, rawId: string): Agent { inbox: new Inbox(session), status: 'idle' as const, ctx: scopeFiber.ctx, + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts index 8e3ae3d634..95b94d7b73 100644 --- a/packages/ui/tui/tests/harness.ts +++ b/packages/ui/tui/tests/harness.ts @@ -202,6 +202,7 @@ export async function createTuiTestHarness { const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() mountTui(ctx, { theme: { color: false } }, { terminal, exit: vi.fn() }) @@ -4930,7 +4930,7 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main')) ctx.agents.register({ id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() // Mirror dsh-tui's own inject (minus loader, the absence under test). @@ -4965,14 +4965,14 @@ describe('terminal mounting', () => { const otherSession = ctx.sessions.create(SessionId('other-session')) ctx.agents.register({ id: otherSession.id, options: {}, session: otherSession, inbox: new Inbox(otherSession), status: 'idle', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) expect(terminal.started).toBe(0) const session = ctx.sessions.create(SessionId('late-session')) const agent = { id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), } as Agent ctx.agents.register(agent) await tick() @@ -5003,7 +5003,7 @@ describe('terminal mounting', () => { const session = ctx.sessions.create(SessionId('main-session')) ctx.agents.register({ id: session.id, options: {}, session, inbox: new Inbox(session), status: 'idle', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) await tick() expect(terminal.started).toBe(0) @@ -5047,7 +5047,7 @@ describe('terminal mounting', () => { session.append('step/start', { turn: 1, step: 1 }) ctx.agents.register({ id: session.id, options: {}, session, inbox: new Inbox(session), status: 'running', ctx, - followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), + send: () => {}, followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(), }) const terminal = new FakeTerminal() terminal.start = () => { throw new Error('terminal startup failed') } From e98cd522eef808f62f67dd21f656c523b654af69 Mon Sep 17 00:00:00 2001 From: kingwl Date: Fri, 31 Jul 2026 11:41:16 +0800 Subject: [PATCH 036/689] fix TUI diff context line accounting --- ...tui-diff-context-line-accounting.i18n.yaml | 6 ++ ...-07-31-tui-diff-context-line-accounting.md | 29 ++++++++++ ...-31-tui-diff-context-line-accounting.zh.md | 29 ++++++++++ packages/ui/tui/README.i18n.yaml | 4 +- packages/ui/tui/README.md | 2 +- packages/ui/tui/README.zh.md | 2 +- packages/ui/tui/package.json | 1 + packages/ui/tui/src/components/transcript.ts | 49 +++++++++++++--- .../advanced-cards-collapsed.expected.txt | 4 +- .../advanced-cards-expanded.expected.txt | 56 +++++++++---------- packages/ui/tui/tests/tui.spec.ts | 17 ++++-- pnpm-lock.yaml | 3 + 12 files changed, 153 insertions(+), 49 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml new file mode 100644 index 0000000000..2d43863567 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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-31-tui-diff-context-line-accounting.md +2026-07-31-tui-diff-context-line-accounting.md: 71593022b56d9e675025f3a7a6d1e5e3edfa9b57 +2026-07-31-tui-diff-context-line-accounting.zh.md: df374c23b73fc5667cf733b4916d9d0d2ecb9198 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md new file mode 100644 index 0000000000..71593022b5 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md @@ -0,0 +1,29 @@ +# Agent Note: TUI diff context lines stay neutral + +Status: implemented + +English | [中文](2026-07-31-tui-diff-context-line-accounting.zh.md) + +## Problem + +Result-time filesystem diffs carry the applied change with three surrounding context lines in each `FileDiff.oldText` and `FileDiff.newText`. The TUI rendered every old-side row as removed and every new-side row as added, including the identical context present on both sides. A one-line edit therefore appeared as seven removals plus seven additions, and the footer repeated those inflated totals. + +## Decision + +The TUI compares each non-create `FileDiff.oldText` and `FileDiff.newText` at render time. Added and removed rows retain their green `+` and red `-` markers; equal context rows use the recessed body tone with a neutral two-space prefix. The footer sums only the rows classified as added or removed. A create (`oldText: null`) continues to classify every non-empty new-content row as added. + +This remains a consumer-side interpretation of the existing `FileDiff` contract. Filesystem tools continue to persist contextual before/after snippets, so other consumers keep their placement context and existing session logs replay with corrected TUI presentation. The TUI uses the same maintained `diff` package as `dsh-tool-fs` instead of introducing a second line-diff implementation. + +## Alternatives considered + +**Remove context from filesystem result metadata.** Rejected: contextual applied hunks are intentional producer output used by capable editors, and changing them would weaken every consumer while leaving old session logs misleading in the TUI. + +**Extend `FileDiff` with persisted per-line tags.** Rejected: the tags can be derived deterministically from the existing before/after pair; persisting them would widen the cross-package and session-log contract solely for one renderer. + +**Match equal lines by position without a diff algorithm.** Rejected: insertions and deletions shift subsequent context, so positional pairing would misclassify valid hunks. + +## Consequences + +TUI diff cards distinguish evidence-bearing context from the mutation itself, and their `+A -R` footer reports the actual line delta. Replaying an existing contextual diff gains the corrected rendering without a migration. Rendering performs one additional line comparison per non-create hunk; result-time hunks are already context-bounded, while create cards bypass the comparison. + +The focused TUI test covers neutral context and exact totals. The assembled `advanced-cards` terminal snapshots pin the neutral context style, semantic change colors, and `+1 -1` footer through collapsed and expanded card states. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md new file mode 100644 index 0000000000..df374c23b7 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md @@ -0,0 +1,29 @@ +# Agent Note: TUI diff 上下文行保持中性 + +Status: implemented + +[English](2026-07-31-tui-diff-context-line-accounting.md) | 中文 + +## 问题 + +文件系统 diff 返回结果时，每个 `FileDiff.oldText` 和 `FileDiff.newText` 都会包含已应用的变更及其前后各 3 行上下文。TUI 将旧侧的每一行都渲染为删除行，将新侧的每一行都渲染为新增行，其中包括两侧相同的上下文。因此，一行编辑会显示为删除 7 行并新增 7 行，页脚还会重复这些虚高的合计值。 + +## 决策 + +对于每个不对应文件创建的 `FileDiff`，TUI 在渲染时比较 `FileDiff.oldText` 和 `FileDiff.newText`。新增行和删除行仍分别使用绿色 `+` 和红色 `-` 标记；相同的上下文行则使用弱化的正文色调，并带有由两个空格构成的中性前缀。页脚只汇总归类为新增或删除的行。创建操作（`oldText: null`）仍将新内容中的每个非空行归类为新增行。 + +该行为仍然只是消费方对现有 `FileDiff` 契约的解释。文件系统工具仍会持久化带上下文的变更前后片段，因此其他消费方仍能获得定位上下文，已有会话日志在回放时也会采用修正后的 TUI 呈现。TUI 与 `dsh-tool-fs` 共用同一个受维护的 `diff` 包（package），无需引入第二套逐行 diff 实现。 + +## 考虑过的替代方案 + +**从文件系统结果元数据中移除上下文。** 不予采纳：带上下文的已应用 hunk 是有意保留的生产方输出，供具备相应能力的编辑器使用；更改这些内容会让所有消费方丢失信息，同时旧会话日志在 TUI 中仍会产生误导。 + +**为 `FileDiff` 扩展持久化的逐行标签。** 不予采纳：这些标签可以根据现有的变更前后文本对确定性派生；仅为一个渲染器持久化标签，会扩大跨包契约和会话日志契约。 + +**不使用 diff 算法，按位置匹配相同行。** 不予采纳：插入和删除会使后续上下文发生位移，因此按位置配对会把有效 hunk 错误分类。 + +## 后果 + +TUI diff 卡片会区分用于佐证的上下文与变更本身，其 `+A -R` 页脚报告实际的行变更量。回放已有的上下文 diff 无需迁移即可获得修正后的渲染。渲染每个不对应文件创建的 hunk 时，会额外执行一次逐行比较；结果时刻的 hunk 本就受上下文范围限制，创建卡片则会跳过比较。 + +聚焦的 TUI 测试覆盖中性上下文和精确合计值。组装后的 `advanced-cards` 终端快照在卡片折叠和展开状态下固定了中性上下文样式、变更行的语义色彩，以及 `+1 -1` 页脚。 diff --git a/packages/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml index e94be1a857..92bfb18e29 100644 --- a/packages/ui/tui/README.i18n.yaml +++ b/packages/ui/tui/README.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 packages/ui/tui/README.md -README.md: 63c888b1d51c02fa85a8f0cc1617874debd87c4e -README.zh.md: ca5efc9ae26a9833d271991f73a21c607d8fb09d +README.md: b021789d660fd831c3fa0dad20d0bc174538eb57 +README.zh.md: b9cd7210932558a3a2feb0d5c1bfaf7e115703f6 diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index 63c888b1d5..b021789d66 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -83,7 +83,7 @@ Every SGR code the TUI emits lives in one table, `paletteSpec` in `components/th There is one role per visual meaning: `dim` is the single recessed tone and `accent` the single emphasis color, while `success` and `error` double as a diff's added and removed lines. Colors and attributes are separately typed, so `bold(accent(x))` compiles and `accent(error(x))` does not — SGR has no color stack, so nesting one color inside another silently drops the outer color at the inner one's close. Attributes occupy independent SGR groups and compose with any color in either order. Run `/palette` to see every role as your terminal renders it, with its SGR pair. -Grouped regions (user prompts, assistant replies, tool cards) are separated by a bold, underlined role header in the role color and blank-line spacing rather than a filled block or a per-line prefix, so a mouse drag-select copies the message text without any leading bar or indent; a tool card's status (pending, error, success) shows in its colored, underlined title glyph and title. Inside a tool card, the whole body — presenter title, a terminal `$` command and cwd, and the tool's own output — renders in one dim tone, so only the status-colored header carries color and the body reads as one recessed block instead of a run of competing shades; an injected-context card's prose is the same tone as its header. A diff card's `+`/`-` lines and a `[signal …]` marker stay colored, because there the color is the meaning rather than emphasis. The question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling. +Grouped regions (user prompts, assistant replies, tool cards) are separated by a bold, underlined role header in the role color and blank-line spacing rather than a filled block or a per-line prefix, so a mouse drag-select copies the message text without any leading bar or indent; a tool card's status (pending, error, success) shows in its colored, underlined title glyph and title. Inside a tool card, the whole body — presenter title, a terminal `$` command and cwd, and the tool's own output — renders in one dim tone, so only the status-colored header carries color and the body reads as one recessed block instead of a run of competing shades; an injected-context card's prose is the same tone as its header. A diff card colors and counts only added `+` and removed `-` lines; unchanged context stays dim and uncounted. A `[signal …]` marker remains colored because there the color is the meaning rather than emphasis. The question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling. ## Model Experience diff --git a/packages/ui/tui/README.zh.md b/packages/ui/tui/README.zh.md index ca5efc9ae2..b9cd721093 100644 --- a/packages/ui/tui/README.zh.md +++ b/packages/ui/tui/README.zh.md @@ -83,7 +83,7 @@ TUI 发出的所有 SGR 代码都集中在一个表中，即 `components/theme.t 每种视觉语义只对应一个角色：`dim` 是唯一的弱化色调，`accent` 是唯一的强调色，`success` 和 `error` 还分别充当 diff 的新增行与删除行。颜色和属性分属不同类型，因此 `bold(accent(x))` 可以通过编译，`accent(error(x))` 则不行——SGR 没有颜色栈；在一种颜色内嵌套另一种颜色时，内层颜色闭合时会静默丢弃外层颜色。各属性占用彼此独立的 SGR 组，可以按任一顺序与任何颜色组合。运行 `/palette` 可查看每个角色在你的终端上的实际渲染效果及其 SGR 码对。 -成组区域（用户提示词、assistant 回复、工具卡片）通过以角色色渲染的粗体带下划线角色标题和空行分隔，而非填充背景块或逐行前缀，因此用鼠标框选复制时不会带上任何左侧竖条或缩进；工具卡片的状态（进行中、错误、成功）由其彩色带下划线的标题字形与标题体现。在工具卡片内部，整个正文——presenter 标题、终端 `$` 命令与 cwd，以及工具自身的输出——统一以同一种暗色渲染，因此只有带状态色的表头携带颜色，正文读作一个整体弱化的区块，而不是一串互相竞争的色调；注入上下文卡片的正文与其表头也是同一种色调。diff 卡片的 `+`/`-` 行与 `[signal …]` 标记保留颜色，因为那里的颜色本身就是语义，而非强调。问题面板使用粗体强调色文本突出活跃行，选择器则使用反色。所有效果都只作用于前景色，因此不会与终端背景冲突。设置 `color: false` 可移除所有样式。 +成组区域（用户提示词、assistant 回复、工具卡片）通过以角色色渲染的粗体带下划线角色标题和空行分隔，而非填充背景块或逐行前缀，因此用鼠标框选复制时不会带上任何左侧竖条或缩进；工具卡片的状态（进行中、错误、成功）由其彩色带下划线的标题字形与标题体现。在工具卡片内部，整个正文——presenter 标题、终端 `$` 命令与 cwd，以及工具自身的输出——统一以同一种暗色渲染，因此只有带状态色的表头携带颜色，正文读作一个整体弱化的区块，而不是一串互相竞争的色调；注入上下文卡片的正文与其表头也是同一种色调。diff 卡片只为新增的 `+` 行和删除的 `-` 行着色并计数；未变更的上下文保持暗色且不纳入计数。`[signal …]` 标记仍保留颜色，因为那里的颜色本身就是语义，而非强调。问题面板使用粗体强调色文本突出活跃行，选择器则使用反色。所有效果都只作用于前景色，因此不会与终端背景冲突。设置 `color: false` 可移除所有样式。 ## 模型体验 diff --git a/packages/ui/tui/package.json b/packages/ui/tui/package.json index c3506ea338..a68fe7968a 100644 --- a/packages/ui/tui/package.json +++ b/packages/ui/tui/package.json @@ -66,6 +66,7 @@ }, "dependencies": { "@earendil-works/pi-tui": "0.80.7", + "diff": "^9.0.0", "saxes": "6.0.0", "schemastery": "^3.18.0" }, diff --git a/packages/ui/tui/src/components/transcript.ts b/packages/ui/tui/src/components/transcript.ts index 774e982f81..5c8b9bf749 100644 --- a/packages/ui/tui/src/components/transcript.ts +++ b/packages/ui/tui/src/components/transcript.ts @@ -15,6 +15,7 @@ import { type Component, type MarkdownTheme, } from '@earendil-works/pi-tui' +import { diffLines as compareLines } from 'diff' import type { Agent } from '@deepseek-ai/dsh-agent' import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm' import type { JsonValue, SessionEvent, TodoItem } from '@deepseek-ai/dsh-session' @@ -52,16 +53,45 @@ function pretty(value: unknown): string { return displayText(serialized ?? String(value)) } -/** A file diff as colored `+`/`-` lines, optionally prefixed with its path. */ -function diffLines(diff: FileDiff, palette: Palette): string[] { +interface RenderedDiff { + lines: string[] + added: number + removed: number +} + +/** Split one diff change into display rows without counting its trailing line terminator. */ +function diffValueLines(value: string): string[] { + if (value === '') return [] + const safe = displayText(value) + return (safe.endsWith('\n') ? safe.slice(0, -1) : safe).split('\n') +} + +/** A file diff whose unchanged context stays neutral and does not affect change totals. */ +function renderDiff(diff: FileDiff, palette: Palette): RenderedDiff { // The card header is a fixed `Tool / ` frame that never names a file, so // each hunk always carries its own path header (no redundancy to suppress). const lines = [palette.bold(displayText(diff.path))] - if (diff.oldText !== null) { - for (const line of displayText(diff.oldText).split('\n')) lines.push(palette.error(`- ${line}`)) + let added = 0 + let removed = 0 + if (diff.oldText === null) { + const newLines = diffValueLines(diff.newText) + added = newLines.length + for (const line of newLines) lines.push(palette.success(`+ ${line}`)) + return { lines, added, removed } } - for (const line of displayText(diff.newText).split('\n')) lines.push(palette.success(`+ ${line}`)) - return lines + for (const change of compareLines(diff.oldText, diff.newText)) { + const changedLines = diffValueLines(change.value) + if (change.added) { + added += changedLines.length + for (const line of changedLines) lines.push(palette.success(`+ ${line}`)) + } else if (change.removed) { + removed += changedLines.length + for (const line of changedLines) lines.push(palette.error(`- ${line}`)) + } else { + for (const line of changedLines) lines.push(palette.dim(` ${line}`)) + } + } + return { lines, added, removed } } /** @@ -505,9 +535,10 @@ export class ToolCardComponent implements Component { let added = 0 let removed = 0 const hunks = view.diffs.flatMap((diff, index) => { - if (diff.oldText !== null) removed += displayText(diff.oldText).split('\n').length - added += displayText(diff.newText).split('\n').length - return [...index > 0 ? [''] : [], ...diffLines(diff, this.palette)] + const rendered = renderDiff(diff, this.palette) + added += rendered.added + removed += rendered.removed + return [...index > 0 ? [''] : [], ...rendered.lines] }) const files = view.diffs.length const footer = this.palette.dim(`└ +${added} -${removed} · ${files} file${files === 1 ? '' : 's'}`) diff --git a/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt b/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt index 2a005383e1..62f69c641f 100644 --- a/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt +++ b/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt @@ -31,9 +31,9 @@ buffer style 0-10 bold 14| "- old line " style 0-9 fg=red -15| "… +3 lines (Ctrl+O to expand) " +15| "… +2 lines (Ctrl+O to expand) " style 0-28 dim -16| "└ +2 -2 · 1 file " +16| "└ +1 -1 · 1 file " style 0-15 dim 17| 18| "● Tool / subagent" diff --git a/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt b/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt index 6f9aa094f3..55479a6f34 100644 --- a/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt +++ b/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt @@ -1,7 +1,7 @@ -terminal 100x40 buffer=normal length=43 base=3 viewport=3 +terminal 100x40 buffer=normal length=42 base=2 viewport=2 lifecycle started=1 stopped=0 progress=inactive title "DSH snapshot" -cursor hidden column=7 viewportRow=39 bufferRow=42 +cursor hidden column=7 viewportRow=39 bufferRow=41 buffer 0| " DEEPSEEK HARNESS" style 1-8 fg=bright-magenta bold @@ -37,54 +37,52 @@ buffer style 0-10 bold 17| "- old line " style 0-9 fg=red -18| "- keep " - style 0-5 fg=red -19| "+ new line " +18| "+ new line " style 0-9 fg=green -20| "+ keep " - style 0-5 fg=green -21| "└ +2 -2 · 1 file " +19| " keep " + style 0-5 dim +20| "└ +1 -1 · 1 file " style 0-15 dim -22| -23| "● Tool / subagent" +21| +22| "● Tool / subagent" style 0-16 fg=green -24| "Delegate renderer audit " +23| "Delegate renderer audit " style 0-99 dim -25| "The renderer has explicit lifecycle ownership. " +24| "The renderer has explicit lifecycle ownership. " style 0-99 dim -26| -27| "● Tool / task_output" +25| +26| "● Tool / task_output" style 0-19 fg=green -28| "Read output from background task subagent-7 " +27| "Read output from background task subagent-7 " style 0-99 dim -29| " " -30| "console " +28| " " +29| "console " style 0-6 dim -31| " started background task bash-5 " +30| " started background task bash-5 " style 0-1 dim style 2-31 fg=cyan dim style 32-99 dim -32| " " -33| -34| "● Tool / skill" +31| " " +32| +33| "● Tool / skill" style 0-13 fg=green -35| "Load skill dsh-code-review " +34| "Load skill dsh-code-review " style 0-99 dim -36| "Loaded review instructions. " +35| "Loaded review instructions. " style 0-99 dim -37| "Model wait 0.0s " +36| "Model wait 0.0s " style 0-14 dim -38| -39| "Tool and context cards expanded. " +37| +38| "Tool and context cards expanded. " style 0-31 dim -40| -41| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" +39| +40| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" style 0-17 fg=bright-magenta bold style 18-31 dim style 34-50 dim style 53-57 dim style 60-69 dim -42| " dsh > " +41| " dsh > " style 1-3 fg=bright-magenta bold style 5-6 dim style 7-7 inverse diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 79aa6f4f97..1b28fa65c5 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -4315,7 +4315,11 @@ describe('tool cards and surface replay', () => { presentCall: () => ({ card: 'diff', title: 'Edit src/only.ts', - diffs: [{ path: 'src/only.ts', oldText: 'old', newText: 'new' }], + diffs: [{ + path: 'src/only.ts', + oldText: 'my: my-MM\nne: ne-NP\nnl: nl-NL\nnb: no-NO\npa: pa-Guru-IN\npl: pl-PL\npt_pt: pt-PT', + newText: 'my: my-MM\nne: ne-NP\nnl: nl-NL\nnb: nb-NO\npa: pa-Guru-IN\npl: pl-PL\npt_pt: pt-PT', + }], }), }, generic: { @@ -4622,7 +4626,7 @@ describe('tool cards and surface replay', () => { }) it('names a single-file diff in the body once, under a fixed Tool header', async () => { - const result = await setup({ tools }) + const result = await setup({ tools, config: { maxToolOutputLines: 20 } }) appendUser(result.session, 'edit one file') appendAssistant(result.session, [ { type: 'text', text: 'Editing' }, @@ -4638,9 +4642,12 @@ describe('tool cards and surface replay', () => { expect(output).toContain('Tool / singleDiff') expect(output).not.toContain('Edit src/only.ts') expect(output.split('src/only.ts').length - 1).toBe(1) - expect(output).toContain('- old') - expect(output).toContain('+ new') - expect(output).toContain('· 1 file') + expect(output).toContain(' my: my-MM') + expect(output).not.toContain('- my: my-MM') + expect(output).not.toContain('+ my: my-MM') + expect(output).toContain('- nb: no-NO') + expect(output).toContain('+ nb: nb-NO') + expect(output).toContain('└ +1 -1 · 1 file') await dispose(result) }) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5ca1ec67f6..300b2731a7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -5458,6 +5458,9 @@ importers: '@earendil-works/pi-tui': specifier: 0.80.7 version: 0.80.7(patch_hash=6c30c5386c0159131e1361023cddf31377f5728962524841964373312c1ed946) + diff: + specifier: ^9.0.0 + version: 9.0.0 saxes: specifier: 6.0.0 version: 6.0.0 From 81ff2894ca63c1474d68829a4df98bf8b2c4f488 Mon Sep 17 00:00:00 2001 From: kingwl Date: Fri, 31 Jul 2026 12:58:30 +0800 Subject: [PATCH 037/689] fix(tui): bound diff rendering work --- ...tui-diff-context-line-accounting.i18n.yaml | 4 +- ...-07-31-tui-diff-context-line-accounting.md | 10 +- ...-31-tui-diff-context-line-accounting.zh.md | 10 +- docs/config-catalog.md | 4 +- packages/ui/tui/README.i18n.yaml | 4 +- packages/ui/tui/README.md | 4 +- packages/ui/tui/README.zh.md | 4 +- packages/ui/tui/src/components/transcript.ts | 50 +++++++--- packages/ui/tui/src/config.ts | 7 ++ packages/ui/tui/src/index.ts | 11 ++- .../advanced-cards-collapsed.expected.txt | 24 +++-- .../advanced-cards-expanded.expected.txt | 37 ++++++-- packages/ui/tui/tests/tui.snapshot.ts | 27 +++++- packages/ui/tui/tests/tui.spec.ts | 95 +++++++++++++++++++ 14 files changed, 246 insertions(+), 45 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml index 2d43863567..6cdec24e63 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.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-31-tui-diff-context-line-accounting.md -2026-07-31-tui-diff-context-line-accounting.md: 71593022b56d9e675025f3a7a6d1e5e3edfa9b57 -2026-07-31-tui-diff-context-line-accounting.zh.md: df374c23b73fc5667cf733b4916d9d0d2ecb9198 +2026-07-31-tui-diff-context-line-accounting.md: d1bc72ea030abd46f809ca3e746e6043f717baeb +2026-07-31-tui-diff-context-line-accounting.zh.md: a2a1dcce1325bca68c92cb4f206bfa35671e9d86 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md index 71593022b5..d1bc72ea03 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.md @@ -10,7 +10,9 @@ Result-time filesystem diffs carry the applied change with three surrounding con ## Decision -The TUI compares each non-create `FileDiff.oldText` and `FileDiff.newText` at render time. Added and removed rows retain their green `+` and red `-` markers; equal context rows use the recessed body tone with a neutral two-space prefix. The footer sums only the rows classified as added or removed. A create (`oldText: null`) continues to classify every non-empty new-content row as added. +The TUI compares each `FileDiff` whose old and new text are both available. Added and removed rows retain their green `+` and red `-` markers; equal context rows use the recessed body tone with a neutral two-space prefix. The footer sums only the rows classified as added or removed. `maxDiffEditLength` bounds the exact comparison by its combined added and removed line count; the default is 1000. Exceeding the bound renders the complete old side as removed and the complete new side as added, marks the footer approximate, and caches that result so redraws do not repeat the comparison. + +When `oldText` is `null`, the renderer cannot distinguish a create from a pending overwrite or an argument fallback whose prior text is unavailable. It therefore shows every non-empty new-side row as added, without claiming those rows were absent from an existing file. Empty new content renders no synthetic added row. This remains a consumer-side interpretation of the existing `FileDiff` contract. Filesystem tools continue to persist contextual before/after snippets, so other consumers keep their placement context and existing session logs replay with corrected TUI presentation. The TUI uses the same maintained `diff` package as `dsh-tool-fs` instead of introducing a second line-diff implementation. @@ -22,8 +24,10 @@ This remains a consumer-side interpretation of the existing `FileDiff` contract. **Match equal lines by position without a diff algorithm.** Rejected: insertions and deletions shift subsequent context, so positional pairing would misclassify valid hunks. +**Run every comparison to completion.** Rejected: pending tool views can contain unrestricted model-authored old and new strings, and an unbounded Myers comparison can block the synchronous terminal renderer. + ## Consequences -TUI diff cards distinguish evidence-bearing context from the mutation itself, and their `+A -R` footer reports the actual line delta. Replaying an existing contextual diff gains the corrected rendering without a migration. Rendering performs one additional line comparison per non-create hunk; result-time hunks are already context-bounded, while create cards bypass the comparison. +TUI diff cards distinguish evidence-bearing context from the mutation itself, and an exact `+A -R` footer reports the actual line delta. Replaying an existing contextual diff gains the corrected rendering without a migration. Result-time filesystem hunks are context-bounded; unrestricted pending views either complete within the configured edit-length budget or degrade to an explicitly approximate linear rendering. -The focused TUI test covers neutral context and exact totals. The assembled `advanced-cards` terminal snapshots pin the neutral context style, semantic change colors, and `+1 -1` footer through collapsed and expanded card states. +The focused TUI tests cover neutral context, exact totals, an empty create, bounded fallback, and cache reuse. The assembled `advanced-cards` terminal snapshots pin the neutral context style, semantic change colors, exact footer, and approximate fallback through collapsed and expanded card states. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md index df374c23b7..a2a1dcce13 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md @@ -10,7 +10,9 @@ Status: implemented ## 决策 -对于每个不对应文件创建的 `FileDiff`，TUI 在渲染时比较 `FileDiff.oldText` 和 `FileDiff.newText`。新增行和删除行仍分别使用绿色 `+` 和红色 `-` 标记；相同的上下文行则使用弱化的正文色调，并带有由两个空格构成的中性前缀。页脚只汇总归类为新增或删除的行。创建操作（`oldText: null`）仍将新内容中的每个非空行归类为新增行。 +TUI 会比较每个变更前后文本均可用的 `FileDiff`。新增行和删除行仍分别使用绿色 `+` 和红色 `-` 标记；相同的上下文行则使用弱化的正文色调，并带有由两个空格构成的中性前缀。页脚只汇总归类为新增或删除的行。`maxDiffEditLength` 以新增行与删除行的合计数为精确比较设置上限，默认值为 1000。超过上限时，TUI 会把完整旧侧渲染为删除内容、把完整新侧渲染为新增内容，将页脚标记为近似结果，并缓存该结果，避免后续重绘重复比较。 + +当 `oldText` 为 `null` 时，渲染器无法区分文件创建、待处理覆写，以及旧文本不可用的参数回退。因此，它会把新侧的每个非空行显示并计作新增行，但不会声称这些行原先不存在于已有文件中。新内容为空时，不会渲染虚构的新增行。 该行为仍然只是消费方对现有 `FileDiff` 契约的解释。文件系统工具仍会持久化带上下文的变更前后片段，因此其他消费方仍能获得定位上下文，已有会话日志在回放时也会采用修正后的 TUI 呈现。TUI 与 `dsh-tool-fs` 共用同一个受维护的 `diff` 包（package），无需引入第二套逐行 diff 实现。 @@ -22,8 +24,10 @@ Status: implemented **不使用 diff 算法，按位置匹配相同行。** 不予采纳：插入和删除会使后续上下文发生位移，因此按位置配对会把有效 hunk 错误分类。 +**让所有比较都运行至完成。** 不予采纳：待处理工具视图可能包含由模型生成且长度不受限制的新旧字符串，无界的 Myers 比较可能阻塞同步终端渲染器。 + ## 后果 -TUI diff 卡片会区分用于佐证的上下文与变更本身，其 `+A -R` 页脚报告实际的行变更量。回放已有的上下文 diff 无需迁移即可获得修正后的渲染。渲染每个不对应文件创建的 hunk 时，会额外执行一次逐行比较；结果时刻的 hunk 本就受上下文范围限制，创建卡片则会跳过比较。 +TUI diff 卡片会区分用于佐证的上下文与变更本身，精确的 `+A -R` 页脚会报告实际的行变更量。回放已有的上下文 diff 无需迁移即可获得修正后的渲染。结果时刻的文件系统 hunk 受上下文范围限制；不受限制的待处理视图要么在配置的编辑长度预算内完成比较，要么降级为明确标注为近似结果的线性渲染。 -聚焦的 TUI 测试覆盖中性上下文和精确合计值。组装后的 `advanced-cards` 终端快照在卡片折叠和展开状态下固定了中性上下文样式、变更行的语义色彩，以及 `+1 -1` 页脚。 +聚焦的 TUI 测试覆盖中性上下文、精确合计值、空文件创建、有界回退和缓存复用。组装后的 `advanced-cards` 终端快照在卡片折叠和展开状态下固定了中性上下文样式、变更行的语义色彩、精确结果页脚和近似回退。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 14446b91d8..0c76ccb449 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -2015,6 +2015,8 @@ export interface TuiConfig { showReasoning?: boolean /** Maximum tool-card body lines retained in its collapsed head/tail preview. */ maxToolOutputLines?: number + /** Maximum added and removed lines explored while deriving an exact line diff. */ + maxDiffEditLength?: number /** Maximum options visible at once in a user-question panel. */ maxQuestionOptions?: number /** Maximum models visible at once in the model selector. */ @@ -2060,7 +2062,7 @@ export interface TuiThemeConfig { } ``` -Source: [`packages/ui/tui/src/config.ts:117`](../packages/ui/tui/src/config.ts) +Source: [`packages/ui/tui/src/config.ts:121`](../packages/ui/tui/src/config.ts) ## `@deepseek-ai/dsh-typert-loader` diff --git a/packages/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml index 92bfb18e29..95332df16e 100644 --- a/packages/ui/tui/README.i18n.yaml +++ b/packages/ui/tui/README.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 packages/ui/tui/README.md -README.md: b021789d660fd831c3fa0dad20d0bc174538eb57 -README.zh.md: b9cd7210932558a3a2feb0d5c1bfaf7e115703f6 +README.md: 837e072ec63752d5f0f1b93bcff16871d32ad615 +README.zh.md: 15f3ad49f2d5b7cdd438532d7443b066a1eac87d diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index b021789d66..837e072ec6 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -50,6 +50,7 @@ A launcher can seed a fresh session's first turn by providing `INITIAL_SKILL_KEY | `sessionId` | `main` | Exact shared agent/session identity driven by the terminal | | `showReasoning` | `true` | Render reasoning blocks | | `maxToolOutputLines` | `6` | Output lines retained across a collapsed tool card's head/tail preview | +| `maxDiffEditLength` | `1000` | Maximum added and removed lines explored for an exact diff before whole-side fallback | | `maxQuestionOptions` | `8` | Visible options in a question panel | | `maxModelOptions` | `8` | Visible models in the model selector | | `maxResumeOptions` | `8` | Visible sessions in the resume selector | @@ -72,6 +73,7 @@ A launcher can seed a fresh session's first turn by providing `INITIAL_SKILL_KEY sessionId: main-session-123 showReasoning: true maxToolOutputLines: 6 + maxDiffEditLength: 1000 fileSearchExcludedDirectories: ['.git', 'node_modules', 'dist'] ``` @@ -83,7 +85,7 @@ Every SGR code the TUI emits lives in one table, `paletteSpec` in `components/th There is one role per visual meaning: `dim` is the single recessed tone and `accent` the single emphasis color, while `success` and `error` double as a diff's added and removed lines. Colors and attributes are separately typed, so `bold(accent(x))` compiles and `accent(error(x))` does not — SGR has no color stack, so nesting one color inside another silently drops the outer color at the inner one's close. Attributes occupy independent SGR groups and compose with any color in either order. Run `/palette` to see every role as your terminal renders it, with its SGR pair. -Grouped regions (user prompts, assistant replies, tool cards) are separated by a bold, underlined role header in the role color and blank-line spacing rather than a filled block or a per-line prefix, so a mouse drag-select copies the message text without any leading bar or indent; a tool card's status (pending, error, success) shows in its colored, underlined title glyph and title. Inside a tool card, the whole body — presenter title, a terminal `$` command and cwd, and the tool's own output — renders in one dim tone, so only the status-colored header carries color and the body reads as one recessed block instead of a run of competing shades; an injected-context card's prose is the same tone as its header. A diff card colors and counts only added `+` and removed `-` lines; unchanged context stays dim and uncounted. A `[signal …]` marker remains colored because there the color is the meaning rather than emphasis. The question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling. +Grouped regions (user prompts, assistant replies, tool cards) are separated by a bold, underlined role header in the role color and blank-line spacing rather than a filled block or a per-line prefix, so a mouse drag-select copies the message text without any leading bar or indent; a tool card's status (pending, error, success) shows in its colored, underlined title glyph and title. Inside a tool card, the whole body — presenter title, a terminal `$` command and cwd, and the tool's own output — renders in one dim tone, so only the status-colored header carries color and the body reads as one recessed block instead of a run of competing shades; an injected-context card's prose is the same tone as its header. A diff card with both sides available colors and counts exact added `+` and removed `-` lines, while unchanged context stays dim and uncounted. If exact comparison exceeds `maxDiffEditLength`, the card renders each old-side row as removed and each new-side row as added, marks the footer approximate, and caches that fallback for later redraws. When `oldText` is unavailable, including pending writes and replay fallbacks as well as creates, every non-empty new-side row is shown and counted as added; that count does not prove the rows were absent from an existing file. Empty new content produces no synthetic `+ ` row. A `[signal …]` marker remains colored because there the color is the meaning rather than emphasis. The question panel emphasizes its active row with bold accent text, while selectors use reverse video. These treatments are foreground-only, so they never collide with the terminal background. Set `color: false` to strip all styling. ## Model Experience diff --git a/packages/ui/tui/README.zh.md b/packages/ui/tui/README.zh.md index b9cd721093..15f3ad49f2 100644 --- a/packages/ui/tui/README.zh.md +++ b/packages/ui/tui/README.zh.md @@ -50,6 +50,7 @@ Footer 将会话报告的用量汇总为 `↑ ↓`；任 | `sessionId` | `main` | 由终端驱动的精确共享 agent／会话身份 | | `showReasoning` | `true` | 渲染 reasoning 块 | | `maxToolOutputLines` | `6` | 折叠工具卡片的头尾预览所保留的输出行数 | +| `maxDiffEditLength` | `1000` | 回退到整侧展示前，精确 diff 最多探索的新增与删除行总数 | | `maxQuestionOptions` | `8` | 问题面板中可见的选项数 | | `maxModelOptions` | `8` | 模型选择器中可见的模型数 | | `maxResumeOptions` | `8` | 恢复选择器中可见的会话数 | @@ -72,6 +73,7 @@ Footer 将会话报告的用量汇总为 `↑ ↓`；任 sessionId: main-session-123 showReasoning: true maxToolOutputLines: 6 + maxDiffEditLength: 1000 fileSearchExcludedDirectories: ['.git', 'node_modules', 'dist'] ``` @@ -83,7 +85,7 @@ TUI 发出的所有 SGR 代码都集中在一个表中，即 `components/theme.t 每种视觉语义只对应一个角色：`dim` 是唯一的弱化色调，`accent` 是唯一的强调色，`success` 和 `error` 还分别充当 diff 的新增行与删除行。颜色和属性分属不同类型，因此 `bold(accent(x))` 可以通过编译，`accent(error(x))` 则不行——SGR 没有颜色栈；在一种颜色内嵌套另一种颜色时，内层颜色闭合时会静默丢弃外层颜色。各属性占用彼此独立的 SGR 组，可以按任一顺序与任何颜色组合。运行 `/palette` 可查看每个角色在你的终端上的实际渲染效果及其 SGR 码对。 -成组区域（用户提示词、assistant 回复、工具卡片）通过以角色色渲染的粗体带下划线角色标题和空行分隔，而非填充背景块或逐行前缀，因此用鼠标框选复制时不会带上任何左侧竖条或缩进；工具卡片的状态（进行中、错误、成功）由其彩色带下划线的标题字形与标题体现。在工具卡片内部，整个正文——presenter 标题、终端 `$` 命令与 cwd，以及工具自身的输出——统一以同一种暗色渲染，因此只有带状态色的表头携带颜色，正文读作一个整体弱化的区块，而不是一串互相竞争的色调；注入上下文卡片的正文与其表头也是同一种色调。diff 卡片只为新增的 `+` 行和删除的 `-` 行着色并计数；未变更的上下文保持暗色且不纳入计数。`[signal …]` 标记仍保留颜色，因为那里的颜色本身就是语义，而非强调。问题面板使用粗体强调色文本突出活跃行，选择器则使用反色。所有效果都只作用于前景色，因此不会与终端背景冲突。设置 `color: false` 可移除所有样式。 +成组区域（用户提示词、assistant 回复、工具卡片）通过以角色色渲染的粗体带下划线角色标题和空行分隔，而非填充背景块或逐行前缀，因此用鼠标框选复制时不会带上任何左侧竖条或缩进；工具卡片的状态（进行中、错误、成功）由其彩色带下划线的标题字形与标题体现。在工具卡片内部，整个正文——presenter 标题、终端 `$` 命令与 cwd，以及工具自身的输出——统一以同一种暗色渲染，因此只有带状态色的表头携带颜色，正文读作一个整体弱化的区块，而不是一串互相竞争的色调；注入上下文卡片的正文与其表头也是同一种色调。当前后两侧文本均可用时，diff 卡片会为精确识别出的新增 `+` 行和删除 `-` 行着色并计数；未变更的上下文保持暗色且不纳入计数。如果精确比较超出 `maxDiffEditLength`，卡片会把旧侧每一行渲染为删除行、把新侧每一行渲染为新增行，将页脚标记为近似结果，并缓存该回退结果供后续重绘使用。当 `oldText` 不可用时（包括待处理写入、回放回退以及文件创建），新侧的每个非空行都会显示并计作新增行；该计数不能证明这些行原先不存在于已有文件中。新内容为空时，不会补出虚构的 `+ ` 行。`[signal …]` 标记仍保留颜色，因为那里的颜色本身就是语义，而非强调。问题面板使用粗体强调色文本突出活跃行，选择器则使用反色。所有效果都只作用于前景色，因此不会与终端背景冲突。设置 `color: false` 可移除所有样式。 ## 模型体验 diff --git a/packages/ui/tui/src/components/transcript.ts b/packages/ui/tui/src/components/transcript.ts index 5c8b9bf749..1bdc73e250 100644 --- a/packages/ui/tui/src/components/transcript.ts +++ b/packages/ui/tui/src/components/transcript.ts @@ -57,6 +57,7 @@ interface RenderedDiff { lines: string[] added: number removed: number + approximate: boolean } /** Split one diff change into display rows without counting its trailing line terminator. */ @@ -66,8 +67,12 @@ function diffValueLines(value: string): string[] { return (safe.endsWith('\n') ? safe.slice(0, -1) : safe).split('\n') } -/** A file diff whose unchanged context stays neutral and does not affect change totals. */ -function renderDiff(diff: FileDiff, palette: Palette): RenderedDiff { +/** + * A file diff whose unchanged context stays neutral and does not affect exact + * change totals. Comparisons beyond the edit-distance budget fall back to + * whole-side rendering so a model-authored pending edit cannot stall the TUI. + */ +function renderDiff(diff: FileDiff, maxDiffEditLength: number, palette: Palette): RenderedDiff { // The card header is a fixed `Tool / ` frame that never names a file, so // each hunk always carries its own path header (no redundancy to suppress). const lines = [palette.bold(displayText(diff.path))] @@ -77,9 +82,20 @@ function renderDiff(diff: FileDiff, palette: Palette): RenderedDiff { const newLines = diffValueLines(diff.newText) added = newLines.length for (const line of newLines) lines.push(palette.success(`+ ${line}`)) - return { lines, added, removed } + return { lines, added, removed, approximate: false } } - for (const change of compareLines(diff.oldText, diff.newText)) { + const changes = compareLines(diff.oldText, diff.newText, { maxEditLength: maxDiffEditLength }) + if (changes === undefined) { + const oldLines = diffValueLines(diff.oldText) + const newLines = diffValueLines(diff.newText) + lines.push(palette.dim(`[exact line diff omitted: >${maxDiffEditLength} changed lines]`)) + removed = oldLines.length + added = newLines.length + for (const line of oldLines) lines.push(palette.error(`- ${line}`)) + for (const line of newLines) lines.push(palette.success(`+ ${line}`)) + return { lines, added, removed, approximate: true } + } + for (const change of changes) { const changedLines = diffValueLines(change.value) if (change.added) { added += changedLines.length @@ -91,7 +107,7 @@ function renderDiff(diff: FileDiff, palette: Palette): RenderedDiff { for (const line of changedLines) lines.push(palette.dim(` ${line}`)) } } - return { lines, added, removed } + return { lines, added, removed, approximate: false } } /** @@ -354,12 +370,14 @@ export class ToolCardComponent implements Component { private visibility: ToolCardVisibility = 'collapsed' private callView: ToolCallView private resultView: ToolResultView | undefined + private diffBodyCache: { view: ToolCallView | ToolResultView; body: CardBody } | undefined constructor( private readonly name: string, private readonly parsed: ParsedArguments, private readonly definition: ToolDefinition | undefined, private readonly maxOutputLines: number, + private readonly maxDiffEditLength: number, private readonly palette: Palette, private readonly mdTheme: MarkdownTheme, ) { @@ -530,21 +548,27 @@ export class ToolCardComponent implements Component { return { prelude: prelude.filter(Boolean), lines: lines.filter(Boolean) } } if (view.card === 'diff') { + if (this.diffBodyCache?.view === view) return this.diffBodyCache.body // The header no longer names the file, so each diff keeps its own path // header. A trailing footer summarizes the change (`+A -R · N file(s)`). - let added = 0 - let removed = 0 - const hunks = view.diffs.flatMap((diff, index) => { - const rendered = renderDiff(diff, this.palette) - added += rendered.added - removed += rendered.removed + const renderedDiffs = view.diffs.map(diff => + renderDiff(diff, this.maxDiffEditLength, this.palette), + ) + const added = renderedDiffs.reduce((total, rendered) => total + rendered.added, 0) + const removed = renderedDiffs.reduce((total, rendered) => total + rendered.removed, 0) + const approximate = renderedDiffs.some(rendered => rendered.approximate) + const hunks = renderedDiffs.flatMap((rendered, index) => { return [...index > 0 ? [''] : [], ...rendered.lines] }) const files = view.diffs.length - const footer = this.palette.dim(`└ +${added} -${removed} · ${files} file${files === 1 ? '' : 's'}`) + const footer = this.palette.dim( + `└ +${added} -${removed} · ${files} file${files === 1 ? '' : 's'}${approximate ? ' · approximate' : ''}`, + ) // A diff's own `+`/`-` colors carry its meaning, so it renders verbatim // rather than under the dim result-output color. - return { prelude: [...hunks, footer], lines: [] } + const body = { prelude: [...hunks, footer], lines: [] } + this.diffBodyCache = { view, body } + return body } // The web card carries no `content` copy, so a `web` result view falls back // to the raw result content here (`view.card === 'generic'` narrows the diff --git a/packages/ui/tui/src/config.ts b/packages/ui/tui/src/config.ts index def548861f..43c8404fee 100644 --- a/packages/ui/tui/src/config.ts +++ b/packages/ui/tui/src/config.ts @@ -34,6 +34,8 @@ export interface TuiConfig { showReasoning?: boolean /** Maximum tool-card body lines retained in its collapsed head/tail preview. */ maxToolOutputLines?: number + /** Maximum added and removed lines explored while deriving an exact line diff. */ + maxDiffEditLength?: number /** Maximum options visible at once in a user-question panel. */ maxQuestionOptions?: number /** Maximum models visible at once in the model selector. */ @@ -64,6 +66,7 @@ export interface TuiConfig { const showReasoningSchema = z.boolean().default(true) const maxToolOutputLinesSchema = z.number().step(1).min(1).default(6) +const maxDiffEditLengthSchema = z.number().step(1).min(1).default(1000) const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8) const maxModelOptionsSchema = z.number().step(1).min(1).default(8) const maxResumeOptionsSchema = z.number().step(1).min(1).default(8) @@ -95,6 +98,7 @@ const titleSchema = z.string().default('DeepSeek Harness') const tuiConfigSchemaFields = { showReasoning: showReasoningSchema, maxToolOutputLines: maxToolOutputLinesSchema, + maxDiffEditLength: maxDiffEditLengthSchema, maxQuestionOptions: maxQuestionOptionsSchema, maxModelOptions: maxModelOptionsSchema, maxResumeOptions: maxResumeOptionsSchema, @@ -135,6 +139,7 @@ export const Config: z = z.object({ initialSkill: z.string(), showReasoning: tuiConfigSchemaFields.showReasoning, maxToolOutputLines: tuiConfigSchemaFields.maxToolOutputLines, + maxDiffEditLength: tuiConfigSchemaFields.maxDiffEditLength, maxQuestionOptions: tuiConfigSchemaFields.maxQuestionOptions, maxModelOptions: tuiConfigSchemaFields.maxModelOptions, maxResumeOptions: tuiConfigSchemaFields.maxResumeOptions, @@ -164,6 +169,7 @@ export interface ResolvedTuiThemeConfig { export interface ResolvedTuiConfig { showReasoning: boolean maxToolOutputLines: number + maxDiffEditLength: number maxQuestionOptions: number maxModelOptions: number maxResumeOptions: number @@ -189,6 +195,7 @@ export function resolveTuiConfig(config: TuiConfig | undefined): ResolvedTuiConf return { showReasoning: config?.showReasoning ?? true, maxToolOutputLines: config?.maxToolOutputLines ?? 6, + maxDiffEditLength: config?.maxDiffEditLength ?? 1000, maxQuestionOptions: config?.maxQuestionOptions ?? 8, maxModelOptions: config?.maxModelOptions ?? 8, maxResumeOptions: config?.maxResumeOptions ?? 8, diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index a1250bb5b3..9745f1f30f 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -605,6 +605,7 @@ export function createTuiChat( parsed, ctx.tools.get(event.data.name, agent), resolved.maxToolOutputLines, + resolved.maxDiffEditLength, palette, mdTheme, ) @@ -748,7 +749,15 @@ export function createTuiChat( const callId = event.data.message.source.callId let card = toolCards.get(callId) if (card === undefined) { - card = new ToolCardComponent('tool', { value: {}, valid: true }, undefined, resolved.maxToolOutputLines, palette, mdTheme) + card = new ToolCardComponent( + 'tool', + { value: {}, valid: true }, + undefined, + resolved.maxToolOutputLines, + resolved.maxDiffEditLength, + palette, + mdTheme, + ) card.setVisibility(toolsVisibility) chat.addChild(card) allToolCards.add(card) diff --git a/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt b/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt index 62f69c641f..20ec3ab324 100644 --- a/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt +++ b/packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt @@ -1,7 +1,7 @@ -terminal 100x40 buffer=normal length=40 base=0 viewport=0 +terminal 100x40 buffer=normal length=41 base=1 viewport=1 lifecycle started=1 stopped=0 progress=inactive title "DSH snapshot" -cursor hidden column=7 viewportRow=34 bufferRow=34 +cursor hidden column=7 viewportRow=39 bufferRow=40 buffer 0| " DEEPSEEK HARNESS" style 1-8 fg=bright-magenta bold @@ -58,17 +58,27 @@ buffer style 0-99 dim 30| "Loaded review instructions. " style 0-99 dim -31| "Model wait 0.0s " +31| +32| "● Tool / large_edit" + style 0-18 fg=green +33| "src/large.ts " + style 0-11 bold +34| "[exact line diff omitted: >2 changed lines] " + style 0-42 dim +35| "… +6 lines (Ctrl+O to expand) " + style 0-28 dim +36| "└ +3 -3 · 1 file · approximate " + style 0-29 dim +37| "Model wait 0.0s " style 0-14 dim -32| -33| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" +38| +39| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" style 0-17 fg=bright-magenta bold style 18-31 dim style 34-50 dim style 53-57 dim style 60-69 dim -34| " dsh > " +40| " dsh > " style 1-3 fg=bright-magenta bold style 5-6 dim style 7-7 inverse -35-39| diff --git a/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt b/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt index 55479a6f34..7752484db7 100644 --- a/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt +++ b/packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt @@ -1,7 +1,7 @@ -terminal 100x40 buffer=normal length=42 base=2 viewport=2 +terminal 100x40 buffer=normal length=53 base=13 viewport=13 lifecycle started=1 stopped=0 progress=inactive title "DSH snapshot" -cursor hidden column=7 viewportRow=39 bufferRow=41 +cursor hidden column=7 viewportRow=39 bufferRow=52 buffer 0| " DEEPSEEK HARNESS" style 1-8 fg=bright-magenta bold @@ -70,19 +70,40 @@ buffer style 0-99 dim 35| "Loaded review instructions. " style 0-99 dim -36| "Model wait 0.0s " +36| +37| "● Tool / large_edit" + style 0-18 fg=green +38| "src/large.ts " + style 0-11 bold +39| "[exact line diff omitted: >2 changed lines] " + style 0-42 dim +40| "- old one " + style 0-8 fg=red +41| "- old two " + style 0-8 fg=red +42| "- old three " + style 0-10 fg=red +43| "+ new one " + style 0-8 fg=green +44| "+ new two " + style 0-8 fg=green +45| "+ new three " + style 0-10 fg=green +46| "└ +3 -3 · 1 file · approximate " + style 0-29 dim +47| "Model wait 0.0s " style 0-14 dim -37| -38| "Tool and context cards expanded. " +48| +49| "Tool and context cards expanded. " style 0-31 dim -39| -40| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" +50| +51| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" style 0-17 fg=bright-magenta bold style 18-31 dim style 34-50 dim style 53-57 dim style 60-69 dim -41| " dsh > " +52| " dsh > " style 1-3 fg=bright-magenta bold style 5-6 dim style 7-7 inverse diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts index 18f0a9a793..db72a7290a 100644 --- a/packages/ui/tui/tests/tui.snapshot.ts +++ b/packages/ui/tui/tests/tui.snapshot.ts @@ -269,13 +269,32 @@ const ADVANCED_CARD_TOOLS: Record = { edit: visualTool( 'edit', () => ({ card: 'diff', title: 'Edit src/view.ts', diffs: [{ path: 'src/view.ts', oldText: 'old line', newText: 'new line' }] }), - // The real edit/write tools produce exactly one diff whose path the title - // already names, so the card omits the redundant per-file header. + // The fixed tool header never names a path, so the hunk retains its path. (): ToolResultView => ({ card: 'diff', diffs: [{ path: 'src/view.ts', oldText: 'old line\nkeep', newText: 'new line\nkeep' }], }), ), + large_edit: visualTool( + 'large_edit', + () => ({ + card: 'diff', + title: 'Edit src/large.ts', + diffs: [{ + path: 'src/large.ts', + oldText: 'old one\nold two\nold three', + newText: 'new one\nnew two\nnew three', + }], + }), + (): ToolResultView => ({ + card: 'diff', + diffs: [{ + path: 'src/large.ts', + oldText: 'old one\nold two\nold three', + newText: 'new one\nnew two\nnew three', + }], + }), + ), subagent: visualTool('subagent', args => ({ card: 'generic', title: 'Delegate renderer audit', @@ -585,7 +604,7 @@ describe('TUI terminal-state snapshots', () => { it('pins terminal, diff, subagent, task, skill, collapsed, and expanded cards', async () => { const harness = await setupSnapshot({ tools: ADVANCED_CARD_TOOLS, - config: { maxToolOutputLines: 3 }, + config: { maxToolOutputLines: 3, maxDiffEditLength: 2 }, }, { columns: 100, rows: 40 }) const calls = [ { id: 'advanced-1', name: 'bash', arguments: { command: 'pnpm run test:coverage' } }, @@ -593,6 +612,7 @@ describe('TUI terminal-state snapshots', () => { { id: 'advanced-3', name: 'subagent', arguments: { prompt: 'Review renderer ownership and report only gaps.' } }, { id: 'advanced-4', name: 'task_output', arguments: { task_id: 'subagent-7', wait: true } }, { id: 'advanced-5', name: 'skill', arguments: { name: 'dsh-code-review' } }, + { id: 'advanced-6', name: 'large_edit', arguments: { file_path: 'src/large.ts' } }, ] await renderAfter(harness, () => { appendToolCalls(harness.session, calls) @@ -601,6 +621,7 @@ describe('TUI terminal-state snapshots', () => { appendToolResult(harness.session, 'advanced-3', [{ type: 'text', text: 'The renderer has explicit lifecycle ownership.' }]) appendToolResult(harness.session, 'advanced-4', [{ type: 'text', text: 'audit complete\n[status: completed]' }]) appendToolResult(harness.session, 'advanced-5', [{ type: 'text', text: 'Loaded review instructions.' }]) + appendToolResult(harness.session, 'advanced-6', [{ type: 'text', text: 'large edit complete' }]) }) await checkpoint('advanced-cards-collapsed', harness.terminal, { includeScrollback: true }) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 1b28fa65c5..213169a89e 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -178,6 +178,7 @@ describe('TUI config', () => { expect(resolveTuiConfig(undefined)).toEqual({ showReasoning: true, maxToolOutputLines: 6, + maxDiffEditLength: 1000, maxQuestionOptions: 8, maxModelOptions: 8, maxResumeOptions: 8, @@ -202,6 +203,7 @@ describe('TUI config', () => { expect(resolveTuiConfig({ showReasoning: false, maxToolOutputLines: 2, + maxDiffEditLength: 12, maxQuestionOptions: 3, maxModelOptions: 4, maxResumeOptions: 5, @@ -218,6 +220,7 @@ describe('TUI config', () => { })).toEqual({ showReasoning: false, maxToolOutputLines: 2, + maxDiffEditLength: 12, maxQuestionOptions: 3, maxModelOptions: 4, maxResumeOptions: 5, @@ -4651,6 +4654,98 @@ describe('tool cards and surface replay', () => { await dispose(result) }) + it('renders an empty create without a synthetic added row', async () => { + const emptyCreate: Record = { + emptyCreate: { + name: 'emptyCreate', + description: '', + parameters: {}, + output: UNUSED_TOOL_OUTPUT, + execute: async () => [], + presentCall: () => ({ + card: 'diff', + title: 'Write empty.txt', + diffs: [{ path: 'empty.txt', oldText: null, newText: '' }], + }), + }, + } + const result = await setup({ + tools: emptyCreate, + config: { maxToolOutputLines: 20, theme: { color: false } }, + }) + appendAssistant(result.session, [ + { type: 'tool-call', id: 'empty-create' as never, name: 'emptyCreate', arguments: '{}' }, + ]) + result.session.append('tool/call', { + turn: 1, + step: 1, + callId: 'empty-create' as never, + name: 'emptyCreate', + arguments: '{}', + }) + await tick() + const rows = result.terminal.output.split('\n').map(row => row.trim()) + expect(result.terminal.output).toContain('empty.txt') + expect(result.terminal.output).toContain('└ +0 -0 · 1 file') + expect(rows).not.toContain('+') + await dispose(result) + }) + + it('bounds and caches exact diff comparison before whole-side fallback', async () => { + let oldTextReads = 0 + const boundedDiff = { + path: 'bounded.txt', + get oldText() { + oldTextReads += 1 + return 'old one\nold two' + }, + newText: 'new one\nnew two', + } + const bounded: Record = { + bounded: { + name: 'bounded', + description: '', + parameters: {}, + output: UNUSED_TOOL_OUTPUT, + execute: async () => [], + presentCall: () => ({ + card: 'diff', + title: 'Edit bounded.txt', + diffs: [boundedDiff], + }), + }, + } + const result = await setup({ + tools: bounded, + config: { + maxToolOutputLines: 20, + maxDiffEditLength: 1, + theme: { color: false }, + }, + }) + appendAssistant(result.session, [ + { type: 'tool-call', id: 'bounded-diff' as never, name: 'bounded', arguments: '{}' }, + ]) + result.session.append('tool/call', { + turn: 1, + step: 1, + callId: 'bounded-diff' as never, + name: 'bounded', + arguments: '{}', + }) + await tick() + expect(result.terminal.output).toContain('[exact line diff omitted: >1 changed lines]') + expect(result.terminal.output).toContain('- old one') + expect(result.terminal.output).toContain('+ new one') + expect(result.terminal.output).toContain('└ +2 -2 · 1 file · approximate') + const readsAfterFirstRender = oldTextReads + expect(readsAfterFirstRender).toBeGreaterThan(0) + result.terminal.resize(87) + await tick() + expect(oldTextReads).toBe(readsAfterFirstRender) + await dispose(result) + }) + it('drops blank rows from a terminal card result that the dim styling wraps', async () => { const blankRowTools: Record = { trailing: { From 8d3635315738ac45d91fce35a32ab90e2687c090 Mon Sep 17 00:00:00 2001 From: kingwl Date: Fri, 31 Jul 2026 12:58:46 +0800 Subject: [PATCH 038/689] docs: archive superseded TUI path note --- .../2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml | 4 ++-- .../bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md | 1 + .../2026-07-27-tui-diff-card-redundant-path-header.zh.md | 1 + .agents/notes/archived/manifest.json | 3 +++ 4 files changed, 7 insertions(+), 2 deletions(-) rename .agents/notes/{implemented => archived}/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml (66%) rename .agents/notes/{implemented => archived}/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md (99%) rename .agents/notes/{implemented => archived}/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md (99%) diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml b/.agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml similarity index 66% rename from .agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml rename to .agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml index a8472075e4..635e3fca62 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml +++ b/.agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.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-27-tui-diff-card-redundant-path-header.md -2026-07-27-tui-diff-card-redundant-path-header.md: 708e543ff079828b4929d2a50ac697a9c846608a -2026-07-27-tui-diff-card-redundant-path-header.zh.md: 863868ae707f37689bbc202267c5470d8c3163e9 +2026-07-27-tui-diff-card-redundant-path-header.md: 608a11892a20d020087180175eff847021dc0554 +2026-07-27-tui-diff-card-redundant-path-header.zh.md: bf7f1c1eeb994f9940b5f7dfb7db72d422293bd4 diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md b/.agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md similarity index 99% rename from .agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md rename to .agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md index 708e543ff0..608a11892a 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md +++ b/.agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md @@ -1,6 +1,7 @@ # Agent Note: TUI diff card dropped the duplicated file path Status: implemented +Archived: 2026-07-31 English | [中文](2026-07-27-tui-diff-card-redundant-path-header.zh.md) diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md b/.agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md similarity index 99% rename from .agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md rename to .agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md index 863868ae70..bf7f1c1eeb 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md +++ b/.agents/notes/archived/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md @@ -1,6 +1,7 @@ # Agent Note: TUI diff 卡片重复打印文件路径 Status: implemented +Archived: 2026-07-31 [English](2026-07-27-tui-diff-card-redundant-path-header.md) | 中文 diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json index e46d7c34cd..1ed77225ae 100644 --- a/.agents/notes/archived/manifest.json +++ b/.agents/notes/archived/manifest.json @@ -46,6 +46,9 @@ "bug-fix/2026-07-26-intent-draft-same-tick-echo.i18n.yaml": "sha256:c623947c4fa00e6d4b51792c7972ba09582bbcb7605beb373725c0dd666f2c81", "bug-fix/2026-07-26-intent-draft-same-tick-echo.md": "sha256:fa8b1417b2cdd3deecbf8e55bdddd73dd3a8c6e3486fd399b0b8bdf317e56373", "bug-fix/2026-07-26-intent-draft-same-tick-echo.zh.md": "sha256:00ce72552dbaa11562fbc541343a5d33f9449edabbe6dd354eb879a7d4d530f8", + "bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml": "sha256:8613a1cfcf4b9c7fafa78a8d8565e2a65ef0335b7b826af9b2bb32097836af55", + "bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md": "sha256:1bd344aec5454d2a2d6e1e6a32eff035c4a99c3df409f2624b39fd32e23ee402", + "bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md": "sha256:0a1747006efb1a4b67feceb9b627a437a0f023158e90ae86e1fe8aef76485384", "feature/2026-06-14-acp-agent-client-protocol.i18n.yaml": "sha256:006795baa43ae962a8d125cc0f1e9f134bc2ee9fb758b6e7669e3fa0126e1918", "feature/2026-06-14-acp-agent-client-protocol.md": "sha256:6828c0af74bb3fb96206ca6b21c0e56a000b50e4744aad4bc2c05092f3a5a31b", "feature/2026-06-14-acp-agent-client-protocol.zh.md": "sha256:ba104e841a1fb84edbd3b6c8119d50445b7785255a7a8d13bb9ac8a2cb4d2e69", From 741fc7dc793e078a4d696ef36bff0e5d0da8db44 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Fri, 31 Jul 2026 13:54:36 +0800 Subject: [PATCH 039/689] fix(agent-loop): report turn failures at source --- packages/core/agent-loop/src/agent.ts | 57 +++++++++++++------ .../tests/contract-regressions.spec.ts | 16 +++++- .../agent-loop/tests/coverage-edges.spec.ts | 5 +- packages/core/agent-loop/tests/loop.spec.ts | 31 +++++++--- .../tests/request-reconstruction.spec.ts | 7 ++- packages/core/session/src/types.ts | 2 + packages/goal/goal-session/src/index.ts | 4 ++ .../goal-session/tests/goal-session.spec.ts | 27 +++++---- packages/llm/llm/src/error.ts | 13 ++++- packages/llm/llm/tests/service.spec.ts | 2 + packages/ui/tui/src/index.ts | 2 +- packages/ui/tui/tests/tui.spec.ts | 3 +- 12 files changed, 125 insertions(+), 44 deletions(-) diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 78614aea25..5eb29db8f6 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -41,6 +41,8 @@ type Admission = | { kind: 'admitted'; messages: UserMessage[] } | { kind: 'blocked' } +type StepEndReason = Extract + /** Remove adapter-derived values before plugins propose the next request config. */ function requestProposal(header: EpochHeader): LlmCallConfig { if (header.adapterDefaults === undefined) return header.config @@ -136,15 +138,19 @@ export class ReactLoopAgent implements Agent { } while (driver !== this.driverDone) } + /** Report one failure at its live boundary, then preserve it for driver containment. */ + private throwError(error: unknown): never { + const turn = this.phase.kind === 'running' ? this.phase.turn : this.phase.lastTurn + const step = this.phase.kind === 'running' ? this.phase.step : 0 + emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error) + throw error + } + private async kick(): Promise { try { while (await this.turn()) {} - } catch (error: unknown) { - if (this.phase.kind !== 'idle') { - const turn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn - this.setPhase({ kind: 'idle', lastTurn: turn }) - emitAgentEvent(this.loopCtx, this, 'agent/error', turn, 0, error) - } + } catch (_error) { + // Admission and turn boundaries report before rethrowing; the driver only contains the rejection. } finally { if (this.phase.kind === 'running') { this.setPhase({ kind: 'idle', lastTurn: this.phase.turn }) @@ -176,7 +182,9 @@ export class ReactLoopAgent implements Agent { /** Admitted input stays unowned until `turn/start` commits. */ private async turn(): Promise { - if (this.phase.kind === 'idle') throw new Error(`agent "${this.id}": turn without driver reservation`) + if (this.phase.kind === 'idle') { + this.throwError(new Error(`agent "${this.id}": turn without driver reservation`)) + } const abort = this.phase.kind === 'collecting' ? this.phase.abort : new AbortController() const { signal } = abort const lastTurn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn @@ -191,10 +199,14 @@ export class ReactLoopAgent implements Agent { } catch (error: unknown) { // oxlint-disable-next-line typescript/no-unnecessary-condition -- cancel may abort while admission awaits if (signal.aborted) return this.inbox.hasPending - throw error + this.throwError(error) } const turn = ++phase.turn - this.session.append('turn/start', { turn }) + try { + this.session.append('turn/start', { turn }) + } catch (error: unknown) { + this.throwError(error) + } let turnEnds: TurnEndReason | null = null try { while (true) { @@ -218,7 +230,7 @@ export class ReactLoopAgent implements Agent { } admission = await this.admit(false) if (admission.kind === 'blocked') { - turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } + turnEnds = { kind: 'blocked' } return false } signal.throwIfAborted() @@ -226,16 +238,27 @@ export class ReactLoopAgent implements Agent { } } catch (error: unknown) { // oxlint-disable-next-line typescript/no-unnecessary-condition -- cancel may abort during any awaited turn operation - if (signal.aborted) turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } - else turnEnds = { kind: 'error', error: errorChain(error) } + if (signal.aborted) { + turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } + } else { + turnEnds = { + kind: 'error', + error: error instanceof LlmError ? error.failure : errorChain(error), + } + this.throwError(error) + } } finally { - // oxlint-disable-next-line typescript/no-non-null-assertion -- the turn is always ended in this block - this.session.append('turn/end', { turn, reason: turnEnds! }) + try { + // oxlint-disable-next-line typescript/no-non-null-assertion -- every exit assigns a turn ending + this.session.append('turn/end', { turn, reason: turnEnds! }) + } catch (error: unknown) { + this.throwError(error) + } } return this.inbox.hasPending } - private async step(): Promise { + private async step(): Promise { if (this.phase.kind !== 'running') throw new Error(`agent "${this.id}": step outside running phase`) const { turn, step, abort: { signal } } = this.phase signal.throwIfAborted() @@ -272,7 +295,9 @@ export class ReactLoopAgent implements Agent { () => Promise.resolve(undefined), ) signal.throwIfAborted() - if (action?.kind !== 'retry') return { kind: 'error', error: finish.failure } + if (action?.kind !== 'retry') { + throw new LlmError(finish.failure.message, finish.failure.code, finish.failure) + } continue } diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index a19bbfa9de..acfd5b7184 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import LlmService, { createUserMessage, freezeMessage, CallId, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm' +import LlmService, { createUserMessage, freezeMessage, CallId, LlmError, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason, type UserMessage } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture, type PostToolDecision } from '@deepseek-ai/dsh-tools' @@ -594,12 +594,20 @@ describe('a finish-error stream chunk ends the turn as error, not completed', () const agent = ctx.agentLoop.create(SessionId('a-finish-error'), { provider: 'mock', model: 'mock' }) const reasons: TurnEndReason[] = [] + const errors: unknown[] = [] + ctx.on('agent/error', (_agent, turn, step, error) => { + expect({ turn, step }).toEqual({ turn: 1, step: 1 }) + errors.push(error) + }) ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) }) send(agent, 'go') await waitForIdle(ctx, agent) expect(reasons).toEqual([{ kind: 'error', error: failure }]) + expect(errors).toHaveLength(1) + expect(errors[0]).toBeInstanceOf(LlmError) + expect((errors[0] as LlmError).failure).toEqual(failure) const events = [...agent.session.events] const turnEnd = events.find(event => event.type === 'turn/end') @@ -809,6 +817,7 @@ describe('turn and step boundary recovery', () => { expect(adapter.requests).toHaveLength(1) expect(errors.map(error => error.message)).toEqual([ + 'reject first step-end', 'invariant violated by "@deepseek-ai/dsh-session": turn/end 1 while step 1 is still open', ]) expect(boundaryCounts(agent)).toMatchObject({ @@ -842,6 +851,7 @@ describe('turn and step boundary recovery', () => { kind: 'error', error: { message: 'provider 500', code: 'SERVER' }, }) + expect(threw).toBe(true) // loop survives: a second turn runs to completion (invariants oracle would // throw on its turn/start if turn 1 had been left open). @@ -1012,7 +1022,9 @@ describe('turn and step boundary recovery', () => { expect(e.some(x => x.type === 'step/end')).toBe(true) expect(e.some(x => x.type === 'turn/end')).toBe(true) expect(e.at(-1)?.type).toBe('turn/end') - expect(errors).toEqual([]) + expect(errors).toHaveLength(1) + expect(errors[0]).toBeInstanceOf(LlmError) + expect((errors[0] as LlmError).failure).toEqual({ message: 'provider 500', code: 'SERVER' }) // loop survives. send(agent, 'again') diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts index 5235a81145..650d8493b7 100644 --- a/packages/core/agent-loop/tests/coverage-edges.spec.ts +++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts @@ -181,7 +181,10 @@ describe('durable error rendering', () => { const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd).toBeDefined() if (turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error') { - expect(turnEnd.data.reason.error).toBe('server overloaded') + expect(turnEnd.data.reason.error).toEqual({ + message: 'server overloaded', + code: 'RATE_LIMIT', + }) } }) }) diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index 2d856dd3ee..a0b7f1d935 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import LlmService, { createUserMessage, CallId, StreamChunk } from '@deepseek-ai/dsh-llm' +import LlmService, { createUserMessage, CallId, LlmError, StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools' @@ -200,7 +200,9 @@ describe('agent loop', () => { await waitForIdle(ctx, agent) expect(adapter.requests).toHaveLength(0) // the request was never sent - expect(errors).toEqual([]) + expect(errors.map(error => error.message)).toEqual([ + 'prompt variable "{{cwd}}" has no value for this assembly (section "deployment:persona")', + ]) const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('error') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' @@ -346,7 +348,7 @@ describe('agent loop', () => { expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('second idle steer') }) - it('contains a throwing step observer and carries steering into a replacement turn', async () => { + it('stops after a throwing step observer and retains steering until a later wakeup', async () => { const adapter = new MockAdapter([textResponse('recovered')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('failed-steering'), { provider: 'mock', model: 'mock' }) @@ -361,6 +363,13 @@ describe('agent loop', () => { send(agent, 'prompt') await waitForIdle(ctx, agent) + expect(adapter.requests).toHaveLength(0) + expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1) + expect(agent.inbox.nextStep).toHaveLength(1) + + send(agent, 'resume') + await waitForIdle(ctx, agent) + expect(adapter.requests).toHaveLength(1) expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2) expect(agent.session.events.some(event => event.type === 'steering/message')).toBe(false) @@ -658,7 +667,7 @@ describe('agent loop', () => { send(agent, 'first') await waitForIdle(ctx, agent) // The first turn failed at step 1 before a model call. - expect(errors).toEqual([]) + expect(errors.map(error => error.message)).toEqual(['boom in pre-step']) expect(adapter.requests.length).toBe(0) const firstTurnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(firstTurnEnd?.type === 'turn/end' && firstTurnEnd.data.reason).toMatchObject({ kind: 'error' }) @@ -1085,20 +1094,24 @@ describe('agent loop', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) - const errors: Error[] = [] + const errors: unknown[] = [] const reasons: TurnEndReason[] = [] ctx.on('agent/error', (_agent, _turn, _step, error) => { - if (error instanceof Error) errors.push(error) + errors.push(error) }) ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) }) send(agent, 'hi') await waitForIdle(ctx, agent) - expect(errors).toEqual([]) + expect(errors).toHaveLength(1) + expect(errors[0]).toBeInstanceOf(LlmError) + expect((errors[0] as LlmError).failure).toEqual({ + message: 'MockAdapter: script exhausted', + code: 'UNKNOWN', + }) expect(reasons[0]).toMatchObject({ kind: 'error' }) - // The durable failure lives entirely on turn/end.reason (with the failing - // step), not a standalone error event. + // The durable failure and live relay describe the same failed turn. const turnEnd = agent.session.events.find(e => e.type === 'turn/end') expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toMatchObject({ kind: 'error' }) }) diff --git a/packages/core/agent-loop/tests/request-reconstruction.spec.ts b/packages/core/agent-loop/tests/request-reconstruction.spec.ts index d9beaf898e..72524eaa6c 100644 --- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts +++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts @@ -359,7 +359,12 @@ describe('request stability across the loop', () => { await waitForIdle(ctx, agent) expect(agent.session.events.findLast(event => event.type === 'turn/end')).toMatchObject({ - data: { reason: { kind: 'error', error: failure.message } }, + data: { + reason: { + kind: 'error', + error: failure instanceof LlmError ? failure.failure : failure.message, + }, + }, }) expect(adapter.requests).toHaveLength(0) }, diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index 0db4f6d352..32ad54dcd6 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -100,6 +100,8 @@ export interface TurnEndReasonMap { completed: { kind: 'completed' } /** A cancellation request interrupted the live turn. */ aborted: { kind: 'aborted'; reason: AgentCancelCause } + + blocked: { kind: 'blocked' } /** * The turn failed. */ diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index e65fb41aa6..c65f317657 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -300,6 +300,10 @@ export function apply(ctx: Context): void { } return case 'turn/end': + if (event.data.reason.kind === 'max-tokens') { + disarm(state) + return + } if (event.data.reason.kind !== 'aborted') return if (state.attempt?.phase === 'admitted') state.attempt.cancelled = true else disarm(state) diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index 7cd8090e07..a0bc6defaf 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -224,15 +224,15 @@ describe('same-session goal driving', () => { ['rate limit', new LlmError('slow down', 'RATE_LIMIT')], ['request error', new Error('provider broke')], ['max tokens', maxTokensResponse('unfinished')], - ] as const)('does not attribute a %s to one goal follow-up', async (_label, response) => { - const test = await harness(Array.from({ length: 8 }, () => response)) + ] as const)('disarms automatic continuation after a %s', async (_label, response) => { + const test = await harness([response]) test.ctx.goals.create(test.agent, { objective: 'stop safely', maxGoalRounds: 8 }) - const goal = await waitForGoal(test.ctx, test.agent, current => current?.phase === 'blocked') + const goal = await waitForGoal(test.ctx, test.agent, current => + current?.phase === 'active' && current.activation === 'disarmed') - expect(goal).toMatchObject({ roundsStarted: 8, activation: 'disarmed' }) - expect(goal?.blockedReason?.code).toBe('round-limit') - expect(test.adapter.requests).toHaveLength(8) + expect(goal).toMatchObject({ roundsStarted: 1, activation: 'disarmed' }) + expect(test.adapter.requests).toHaveLength(1) }) it('maps a downstream prompt veto to blocked without admitting the round', async () => { @@ -827,7 +827,7 @@ describe('same-session goal driving', () => { expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('goal-session')) }) - it('ignores the failed outcome of a round made stale by human work queued at turn start', async () => { + it('keeps terminal agent failure disarmed and defers queued human work until another wakeup', async () => { const test = await harness([new Error('round one broke'), textResponse('human answer')]) let queued = false test.ctx.on('session/event', (session, event) => { @@ -841,13 +841,18 @@ describe('same-session goal driving', () => { }) test.ctx.goals.create(test.agent, { objective: 'survive a stale failure', maxGoalRounds: 1 }) - const goal = await waitForGoal(test.ctx, test.agent, current => current?.phase === 'blocked') + await waitForGoal(test.ctx, test.agent, current => + current?.phase === 'active' && current.activation === 'disarmed') + + expect(test.adapter.requests).toHaveLength(1) + expect(test.agent.inbox.nextTurn).toHaveLength(1) + + test.agent.steer(createUserMessage({ content: [{ type: 'text', text: 'resume after failure' }], source: { kind: 'user' } })) + await test.agent.whenIdle() - // The stale round's turn-error never blocks the goal; only the durable - // round budget does, after the interleaved human turn ran. - expect(goal?.blockedReason?.code).toBe('round-limit') expect(test.adapter.requests).toHaveLength(2) expect(requestText(test.adapter.requests[1]!)).toContain('human interleaved') + expect(requestText(test.adapter.requests[1]!)).toContain('resume after failure') }) it('waits for work queued by a pause observer before considering the next round', async () => { diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts index c4eb816ff6..fbb8bccca5 100644 --- a/packages/llm/llm/src/error.ts +++ b/packages/llm/llm/src/error.ts @@ -93,7 +93,8 @@ export function isQuotaExceededError(detail: string): boolean { /** * Render a thrown value with its full `cause` chain and AggregateError * members, so transport wrappers like undici's `TypeError: fetch failed` - * surface the underlying failure instead of masking it. Diagnostic-surface + * surface the underlying failure instead of masking it. Plain structured + * failures render their own data-backed `message`. Diagnostic-surface * rendering only (messages, notices, logs) — never parse the result; route on * {@link HarnessError.code}. * @param value - the caught value (`unknown` in catch clauses). @@ -109,7 +110,15 @@ export function errorChain(value: unknown): string { if (path.has(current)) return '' path.add(current) try { - if (!(current instanceof Error)) return String(current) + if (!(current instanceof Error)) { + if (typeof current === 'object' && current !== null) { + const descriptor = Object.getOwnPropertyDescriptor(current, 'message') + if (descriptor !== undefined && 'value' in descriptor && typeof descriptor.value === 'string') { + return descriptor.value + } + } + return String(current) + } const message = current.message === '' ? current.name : current.message const members = current instanceof AggregateError && current.errors.length > 0 ? ` [${current.errors.map(render).join('; ')}]` diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts index 95480b961c..6136daa81a 100644 --- a/packages/llm/llm/tests/service.spec.ts +++ b/packages/llm/llm/tests/service.spec.ts @@ -145,6 +145,8 @@ describe('LlmService', () => { it('errorChain survives non-Error values, hostile coercion, and circular causes', () => { expect(errorChain('plain string')).toBe('plain string') + expect(errorChain({ message: 'structured provider failure', code: 'SERVER' })) + .toBe('structured provider failure') expect(errorChain({ toString: () => { throw new Error('hostile') } })).toBe('') const circular = new Error('outer') circular.cause = circular diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 6960886b8e..afcae6bf17 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -794,7 +794,7 @@ export function createTuiChat( liveErrors.delete(key) alreadyReported = true } - const message = reason.error instanceof Error ? reason.error.message : String(reason.error) + const message = errorChain(reason.error) if (!alreadyReported) appendNotice(message, 'error') break } diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index a818dbb70c..4a09434cda 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -3755,7 +3755,7 @@ describe('pi-tui chat lifecycle and transcript', () => { events.session.append('turn/start', { turn: 6 }) events.session.append('turn/end', { turn: 6, - reason: { kind: 'error', error: 'structured provider failure' }, + reason: { kind: 'error', error: { message: 'structured provider failure', code: 'SERVER' } }, }) events.session.append('turn/start', { turn: 8 }) events.session.append('turn/end', { @@ -3771,6 +3771,7 @@ describe('pi-tui chat lifecycle and transcript', () => { expect(events.terminal.output).toContain('durable failure') expect(events.terminal.output).toContain('Turn cancelled') expect(events.terminal.output).toContain('structured provider failure') + expect(events.terminal.output).not.toContain('[object Object]') expect(events.terminal.output).toContain('output-token limit') expect(events.terminal.output).toContain('previous process ended') expect(events.terminal.output).toContain('Turn ended: plugin-policy') From a332f2f3330e9b3a3c6b649f6518567c968ad975 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Fri, 31 Jul 2026 14:08:59 +0800 Subject: [PATCH 040/689] feat(web): configure custom DeepSeek models --- .../2026-07-30-web-config-plane.i18n.yaml | 4 +- .../2026-07-30-web-config-plane.md | 6 +- .../2026-07-30-web-config-plane.zh.md | 6 +- ...07-24-web-session-model-selector.i18n.yaml | 4 +- .../2026-07-24-web-session-model-selector.md | 6 +- ...026-07-24-web-session-model-selector.zh.md | 6 +- apps/web/tests/message-actions.e2e.ts | 5 +- apps/web/tests/models-settings.e2e.ts | 2 +- .../tests/onboarding-deepseek-config.e2e.ts | 44 +- apps/web/tests/seeded-history.e2e.ts | 11 +- .../lifecycle-chrome/plan-active.expected.md | 4 +- .../snapshots/message-actions/ui.expected.md | 4 +- .../models-settings/configured.expected.md | 4 +- .../models.expected.md | 58 +++ .../seeded-history/command-row.expected.md | 4 +- .../snapshots/seeded-history/ui.expected.md | 4 +- packages/client/ui-model/README.i18n.yaml | 4 +- packages/client/ui-model/README.md | 2 +- packages/client/ui-model/README.zh.md | 2 +- .../src/client/ModelSelect.module.css | 7 +- .../ui-model/src/client/ModelSelect.tsx | 14 +- packages/client/ui-model/src/client/index.ts | 4 +- .../client/ui-model/src/client/locales.ts | 6 +- .../ui-model/tests/model-select.spec.tsx | 22 + packages/client/ui-models/README.i18n.yaml | 4 +- packages/client/ui-models/README.md | 7 +- packages/client/ui-models/README.zh.md | 7 +- .../src/client/DeepSeekModelsEditor.tsx | 196 +++++++++ .../src/client/ModelsSection.module.css | 412 ++++++++++++++---- .../ui-models/src/client/ModelsSection.tsx | 4 +- .../ui-models/src/client/ProviderEditor.tsx | 41 +- .../client/ui-models/src/client/locales.ts | 34 ++ .../ui-models/tests/components.spec.tsx | 153 ++++++- packages/host/apiproxy/README.i18n.yaml | 4 +- packages/host/apiproxy/README.md | 2 +- packages/host/apiproxy/README.zh.md | 2 +- packages/host/apiproxy/src/api-proxy.ts | 39 +- packages/host/apiproxy/src/api/llm.ts | 4 +- .../host/apiproxy/src/api/sessions.schema.ts | 1 - packages/host/apiproxy/src/api/sessions.ts | 2 - .../apiproxy/tests/api-proxy-models.spec.ts | 13 +- .../host/apiproxy/tests/rpc-schemas.spec.ts | 1 - 42 files changed, 948 insertions(+), 211 deletions(-) create mode 100644 apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md create mode 100644 packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml index ac37214ebf..d652bd075a 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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/architecture/2026-07-30-web-config-plane.md -2026-07-30-web-config-plane.md: 95ede6264026f7b32e95749d00fe841f57dbf867 -2026-07-30-web-config-plane.zh.md: 6e06b69218a405055621cbd40781f9fbda9f9e6b +2026-07-30-web-config-plane.md: e00c0ed8b5852d416baec73a993102aadded9cd3 +2026-07-30-web-config-plane.zh.md: d5dd5e3c044dc5788367eca55e1cc4110ff81180 diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md index 95ede62640..e00c0ed8b5 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md +++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md @@ -18,9 +18,9 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer **The llm seam declares configurability and announces topology.** `registerConfigurableProviders()` is an all-or-nothing, fiber-scoped directory of `{provider, displayName, settingsNs, settingsPath}` — the addressing a config page needs to open the right settings subtree for a route that may not exist yet; `listConfigurableProviders()` merges with live routes in the wire handler so undeclared live routes still report active. The zero-payload `'llm/adapters-updated'` event fires from all four registration/unregistration commit points with contained listener dispatch (INVARIANT rethrow), following the settings/commands precedent. `llm-deepseek`'s route renamed to `deepseek-official` because the pi-ai catalog legitimately owns `deepseek` as an aggregator entry; pre-release stance, no alias. -**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, plus `reasoningEffort` for deepseek / `reasoning` for pi-ai), with every other field owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, so a hand-coded field that drifts from its schema fails loud on save rather than silently. +**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog is one caption strip over a row of `id`/`name`/`contextWindow` fields per model rather than a labelled card each; every field keeps the indexed `aria-label` that names it, and the captions are hidden from assistive tech so that name is not announced twice. -**The Models page is a three-domain join with seam-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder; badges come from route liveness. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `_API_KEY` when none exists (the pi-ai profile records the derivation), so `settings.yaml` never carries a key value and the wholesale `settings.replace` a removal needs can never drop a sibling's secret. An edit without removals lands as a minimal `settings.update` merge patch; clearing a fold field back to inherited or deleting a row replaces the whole user section, because merge semantics cannot express removal. +**The Models page is a three-domain join with seam-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder; badges come from route liveness. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `_API_KEY` when none exists (the pi-ai profile records the derivation), so `settings.yaml` never carries a key value. Visible profile edits land as `settings.mutate` path operations against the stored redacted section, so a set or unset never rebuilds and drops an unseen secret. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. ## Alternatives considered @@ -33,4 +33,4 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer ## Consequences -The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card and configured states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models), a page address for live routes that never declared configurability, and the documented reset edge — a `settings.replace` cannot re-supply a stored *literal* secret in the replaced subtree, which the reference-based default makes unreachable. +The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card and configured states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. A page address for live routes that never declared configurability remains deferred. diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md index 6e06b69218..d5dd5e3c04 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md @@ -18,9 +18,9 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯 **llm seam 声明可配置性并公布拓扑。**`registerConfigurableProviders()` 是一个全有或全无、以 fiber 为作用域的目录，条目为 `{provider, displayName, settingsNs, settingsPath}`——这正是配置页要为一条可能尚不存在的路由打开正确设置子树时所需要的寻址；`listConfigurableProviders()` 在 wire 处理器里与存活路由合并，未声明的存活路由因此仍报告为激活。零负载的 `'llm/adapters-updated'` 事件从全部四个注册／注销提交点触发，listener 派发带异常隔离（INVARIANT 重抛），沿用 settings/commands 的先例。`llm-deepseek` 的路由重命名为 `deepseek-official`，因为 pi-ai catalog 名正言顺地拥有 `deepseek` 这个聚合器条目；依预发布立场，不设别名。 -**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，另加 deepseek 的 `reasoningEffort`／pi-ai 的 `reasoning`），其余每个字段都归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，因此偏离其 schema 的手写字段会在保存时大声失败，而非静默失败。 +**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录是一条列名说明行，其下每个模型占一行 `id`／`name`／`contextWindow` 字段，而不是每个模型各一张带标签的卡片；每个字段都保留那个为其命名的带序号 `aria-label`，列名则对辅助技术隐藏，以免该名称被播报两次。 -**Models 页是一次三领域联接，应用语义与 seam 同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目；徽标来自路由存活状态。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `_API_KEY`（pi-ai profile 会记录该派生），因此 `settings.yaml` 从不携带密钥值，删除所需的整体 `settings.replace` 也绝不可能丢掉兄弟条目的机密。不含删除的编辑以一次最小的 `settings.update` 合并 patch 落地；把折叠区字段清回继承值或删除整行则经 `settings.replace` 替换整个用户分节，因为合并语义表达不了删除。 +**Models 页是一次三领域联接，应用语义与 seam 同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目；徽标来自路由存活状态。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `_API_KEY`（pi-ai profile 会记录该派生），因此 `settings.yaml` 从不携带密钥值。可见的 profile 编辑以 `settings.mutate` 路径操作落到已存储的脱敏分节上，因此 set 或 unset 都不会重建分节并丢掉不可见的机密。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。 ## 曾考虑的替代方案 @@ -33,4 +33,4 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯 ## 后果 -整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态与已配置态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）、为从未声明可配置性的存活路由提供页面地址，以及已记录在案的重置边界情形——`settings.replace` 无法在被替换的子树里重新补上已存储的*字面量*机密，而基于引用的默认形态让这种情况根本无从出现。 +整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态与已配置态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。为从未声明可配置性的存活路由提供页面地址仍然暂缓。 diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml index b1e6e8b7d1..898a0142fb 100644 --- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.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/feature/2026-07-24-web-session-model-selector.md -2026-07-24-web-session-model-selector.md: 003c0b5ac1c6963701e1d93e4c3ff8615fc45dd5 -2026-07-24-web-session-model-selector.zh.md: ba76b87b9bd43fff97bf9ea76624f5f75b10e135 +2026-07-24-web-session-model-selector.md: ca13bebbb49aec5deabd147ed1c2a8f3b246ca42 +2026-07-24-web-session-model-selector.zh.md: 16c7d773b0eea82bf991bc17c44b26c8e820aba1 diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md index 003c0b5ac1..ca13bebbb4 100644 --- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md +++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md @@ -12,11 +12,11 @@ The Web conversation displayed and sent through the Host's fixed provider/model The Web Host reuses `installAgentLlmTarget` for every created or resumed agent. The provider/model/reasoning target starts from the latest `request/header` when the session has used a model, otherwise from the Host default route. `session.selectModel` changes the session-local mutable target, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed target persists through the existing full `request/header` snapshot, while a choice that has not reached a request remains process-local. -The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: the current model is inserted as an unlisted row when its registered provider omits it, while exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target. +The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. Exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target. The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete target, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so older responses cannot replace a newer result; connection reset discards the process-local projection before restoring the Host target. Failures retain the previous current target and usable groups. -`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the catalog model name and effective reasoning label, falling back to ids when metadata is absent. The upward menu first offers Model and, when the current exact model supports it, Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default. +`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current target is absent from the groups, the trigger instead displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model replaces the complete target through the existing selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default. The production browser roster is assembled from `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml`; the model feature is one `dshClient` row rather than a package hardcoded in Web boot code. Its package manifest orders it after the runtime and command feature, while Cordis service injection waits for the conversation slot before registering the composer occupant. @@ -40,4 +40,4 @@ Any Host-backed Web conversation, including a blank session, can switch among dy ## Testing -Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration, unlisted current targets, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-target submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, and effort submission. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids. +Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-target submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for a removed row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture removes the active catalog row and pins the fallback before choosing a replacement. diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md index ba76b87b9b..16c7d773b0 100644 --- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md +++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md @@ -12,11 +12,11 @@ Web 对话原本通过 Host 固定的提供方与模型路由显示并发送消 Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlmTarget`。如果会话已经使用过模型，提供方／模型／推理（reasoning）目标从最新的 `request/header` 开始；否则采用 Host 默认路由。`session.selectModel` 会更改会话级可变目标，提示词组装则将该目标与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一条实际采用的目标通过现有的完整 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。 -会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：如果当前模型的已注册提供方没有列出该模型，系统会将其作为未列出行插入；精确解析则决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。 +会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。精确解析决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。 浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整目标、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 目标。失败时保留先前的当前目标和可用分组。 -`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中的模型名称与生效的推理强度标签；元数据缺失时则回退到相应 ID。向上展开的菜单首先提供 Model，并在当前精确模型支持时提供 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。 +`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前目标不在分组中时，触发器改为显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过现有选择路径替换完整目标。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。 生产环境的浏览器名册由 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 共同组装；模型功能对应其中一行 `dshClient` 配置项，而不是 Web boot 代码中硬编码的包。其包 manifest（元数据清单）将加载顺序置于运行时与命令功能之后；Cordis 服务注入则等待 conversation slot 可用，再注册 composer 占用方。 @@ -40,4 +40,4 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm ## 测试 -Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复、当前未列出目标、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示与推理强度提交。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID。 +Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、建议性的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。 diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts index 4d798e11ed..c44bdfdd69 100644 --- a/apps/web/tests/message-actions.e2e.ts +++ b/apps/web/tests/message-actions.e2e.ts @@ -76,9 +76,8 @@ describe('web e2e: message IconActions and clocks on settled history', () => { it.skipIf(MODE === 'record')('matches the conversation aria golden with IconActions and clocks', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-message-actions-aria')) - await page.getByRole('button', { - name: 'Select model, current deepseek-v4-flash', - }).waitFor({ timeout: 10_000 }) + await page.getByRole('button', { name: 'Select model', exact: true }) + .waitFor({ timeout: 10_000 }) // Keep a footer focused so opacity-hidden actions stay in the a11y tree // as an active/focused control during the capture. await page.getByRole('button', { name: 'Copy' }).first().focus() diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts index 28c423b0a0..e23a5a9e1e 100644 --- a/apps/web/tests/models-settings.e2e.ts +++ b/apps/web/tests/models-settings.e2e.ts @@ -55,7 +55,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => { await dialog.getByText('填入各提供方的 API 密钥即可使用其模型。').waitFor({ timeout: 10_000 }) // The dormant pi-ai adapter contributes its whole installed catalog; no // provider is configured yet, so the page is one add button. - const add = dialog.getByRole('button', { name: '+ 添加提供方' }) + const add = dialog.getByRole('button', { name: '添加提供方' }) await add.waitFor({ timeout: 10_000 }) // The button enables once the dormant catalog lands in the join. await expect.poll(async () => add.isEnabled(), { timeout: 10_000 }).toBe(true) diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts index 62dd129982..9ce68c6318 100644 --- a/apps/web/tests/onboarding-deepseek-config.e2e.ts +++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts @@ -16,6 +16,7 @@ import { saveFailureShot } from './support.ts' const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/onboarding-deepseek-config', import.meta.url)) const MISSING_EXPECTED = join(SNAPSHOT_DIR, 'missing.expected.md') +const MODELS_EXPECTED = join(SNAPSHOT_DIR, 'models.expected.md') const MODE = webSnapshotMode() describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup', () => { @@ -85,7 +86,48 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup expect(tripwire.pageErrors).toEqual([]) }, 60_000) + it('configures arbitrary DeepSeek models and prompts after the selected model is removed', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-models')) + const settings = page.getByRole('dialog', { name: '设置' }) + await settings.getByText('自定义设置').click() + await settings.getByRole('button', { name: '删除模型' }).first().click() + await settings.getByRole('button', { name: '添加模型' }).click() + const customModelId = settings.getByLabel('模型 ID 2') + await customModelId.fill('private-preview') + await settings.getByLabel('显示名称 2').fill('Private Preview') + await settings.getByLabel('上下文窗口 2').fill('131072') + + const modelEditor = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(MODELS_EXPECTED, modelEditor, MODE) + await settings.getByRole('button', { name: '保存', exact: true }).click() + await customModelId.waitFor({ state: 'detached', timeout: 15_000 }) + + const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8') + expect(document).toContain('id: deepseek-v4-pro') + expect(document).toContain('id: private-preview') + expect(document).toContain('name: Private Preview') + expect(document).toContain('contextWindow: 131072') + expect(document).not.toContain('id: deepseek-v4-flash') + + await page.keyboard.press('Escape') + await page.getByRole('button', { name: '创建工作区', exact: true }).click() + await page.getByRole('menuitem', { name: '新建工作区', exact: true }).click() + const workspaceDialog = page.getByRole('dialog', { name: '新建工作区' }) + await workspaceDialog.getByLabel('新工作区名称').fill('model-fallback-e2e') + await workspaceDialog.getByRole('button', { name: '创建工作区', exact: true }).click() + await workspaceDialog.waitFor({ state: 'detached', timeout: 10_000 }) + + const modelTrigger = page.getByRole('button', { name: '选择模型', exact: true }) + await modelTrigger.waitFor({ timeout: 10_000 }) + await modelTrigger.click() + await page.getByRole('menuitem', { name: /模型/ }).click() + expect(await page.getByText('deepseek-v4-flash', { exact: true }).count()).toBe(0) + await page.getByRole('menuitemradio', { name: 'Private Preview' }).waitFor({ timeout: 10_000 }) + expect(tripwire.warnings).toEqual([]) + expect(tripwire.pageErrors).toEqual([]) + }, 60_000) + it('keeps the fixture inventory closed', async () => { - await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md']) + await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md', 'models.expected.md']) }) }) diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts index 3437c41e18..2e4882627a 100644 --- a/apps/web/tests/seeded-history.e2e.ts +++ b/apps/web/tests/seeded-history.e2e.ts @@ -152,12 +152,11 @@ describe('web e2e: seeded history renders through cold resume', () => { it.skipIf(MODE === 'record')('matches the historical conversation aria golden', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-aria')) - await page.getByRole('button', { - // This scenario deliberately leaves the LLM seam open to prove zero - // model calls. History still restores the selected id, but no catalog - // adapter exists to provide its presentation name. - name: 'Select model, current deepseek-v4-flash', - }).waitFor({ timeout: 10_000 }) + // This scenario deliberately leaves the LLM seam open to prove zero + // model calls. History still restores the routed id, but without an + // advertised catalog row the selector prompts for a listed replacement. + await page.getByRole('button', { name: 'Select model', exact: true }) + .waitFor({ timeout: 10_000 }) const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)) .split(SEED_ID).join('{{seededId}}') await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE) diff --git a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md index 8be9ff8b86..eb1002fd5d 100644 --- a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md +++ b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md @@ -30,8 +30,8 @@ - img - 'button "Access mode, current: Danger Full Access"': Danger Full Access - button "Plan mode on, press to turn off": Plan -- button "Select model, current deepseek-v4-flash": - - text: deepseek-v4-flash +- button "Select model": + - text: Select model - img - button "Send message" [disabled] - text: Details diff --git a/apps/web/tests/snapshots/message-actions/ui.expected.md b/apps/web/tests/snapshots/message-actions/ui.expected.md index d423f6f53a..6f7e8cf865 100644 --- a/apps/web/tests/snapshots/message-actions/ui.expected.md +++ b/apps/web/tests/snapshots/message-actions/ui.expected.md @@ -40,8 +40,8 @@ - button "Commands": - img - 'button "Access mode, current: Danger Full Access"': Danger Full Access -- button "Select model, current deepseek-v4-flash": - - text: deepseek-v4-flash +- button "Select model": + - text: Select model - img - button "Send message" [disabled] - text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok diff --git a/apps/web/tests/snapshots/models-settings/configured.expected.md b/apps/web/tests/snapshots/models-settings/configured.expected.md index 8b9c4ad6e1..e4697dfa4f 100644 --- a/apps/web/tests/snapshots/models-settings/configured.expected.md +++ b/apps/web/tests/snapshots/models-settings/configured.expected.md @@ -17,4 +17,6 @@ - text: minimax-cn 已启用 - button "编辑" - button "删除" - - button "+ 添加提供方" + - button "添加提供方": + - img + - text: 添加提供方 diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md new file mode 100644 index 0000000000..31b6c7b1b4 --- /dev/null +++ b/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md @@ -0,0 +1,58 @@ +- dialog "设置": + - navigation: + - text: 设置 + - button "通用设置": + - img + - text: 通用设置 + - button "模型": + - img + - text: 模型 + - button "关闭": + - img + - text: 关闭 + - heading "模型" [level=2] + - paragraph: 填入各提供方的 API 密钥即可使用其模型。 + - list: + - listitem: + - text: DeepSeek 已启用 + - button "编辑" + - text: DeepSeek deepseek-official API 密钥 + - textbox "API 密钥": + - /placeholder: 已配置——输入新值可替换 + - group: + - text: 自定义设置 API 地址 + - textbox "API 地址": + - /placeholder: https://api.deepseek.com + - text: 推理强度 + - combobox "推理强度": + - option "默认" [selected] + - option "off" + - option "high" + - option "max" + - region "模型目录": + - text: 模型目录 已自定义模型目录 + - button "恢复默认模型" + - textbox "模型 ID 1": deepseek-v4-pro + - textbox "显示名称 1": + - /placeholder: 留空时使用模型 ID + - text: DeepSeek-V4-Pro + - spinbutton "上下文窗口 1": "1000000" + - button "删除模型": + - img + - text: 删除模型 + - textbox "模型 ID 2": private-preview + - textbox "显示名称 2": + - /placeholder: 留空时使用模型 ID + - text: Private Preview + - spinbutton "上下文窗口 2": "131072" + - button "删除模型": + - img + - text: 删除模型 + - button "添加模型": + - img + - text: 添加模型 + - button "取消" + - button "保存" + - button "添加提供方": + - img + - text: 添加提供方 diff --git a/apps/web/tests/snapshots/seeded-history/command-row.expected.md b/apps/web/tests/snapshots/seeded-history/command-row.expected.md index f722bb36ae..2d8fb1fce9 100644 --- a/apps/web/tests/snapshots/seeded-history/command-row.expected.md +++ b/apps/web/tests/snapshots/seeded-history/command-row.expected.md @@ -45,8 +45,8 @@ - button "Commands": - img - 'button "Access mode, current: Workspace Write"': Workspace Write -- button "Select model, current deepseek-v4-flash": - - text: deepseek-v4-flash +- button "Select model": + - text: Select model - img - button "Send message" [disabled] - text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok diff --git a/apps/web/tests/snapshots/seeded-history/ui.expected.md b/apps/web/tests/snapshots/seeded-history/ui.expected.md index 61d3996414..a2d14e611a 100644 --- a/apps/web/tests/snapshots/seeded-history/ui.expected.md +++ b/apps/web/tests/snapshots/seeded-history/ui.expected.md @@ -43,8 +43,8 @@ - button "Commands": - img - 'button "Access mode, current: Danger Full Access"': Danger Full Access -- button "Select model, current deepseek-v4-flash": - - text: deepseek-v4-flash +- button "Select model": + - text: Select model - img - button "Send message" [disabled] - text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml index 9620b15513..5d40ab44b9 100644 --- a/packages/client/ui-model/README.i18n.yaml +++ b/packages/client/ui-model/README.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 packages/client/ui-model/README.md -README.md: 267717c78434f7a73b1c1eebca0cc0f9d65c3642 -README.zh.md: 6d6f433315336812a51b5110ceeac3eecbd9bbd4 +README.md: e456371095166569ed9e36fab19627ece9a751b0 +README.zh.md: c72eb33163aa5ef855489cbbd46cac9edb93afb2 diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md index 267717c784..e456371095 100644 --- a/packages/client/ui-model/README.md +++ b/packages/client/ui-model/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -Model selection plugin, browser half: TWO entries over ONE per-session directory owned by `ModelService` (`ctx.models`). The `/model` popupSelect contribution (registered through `ctx.command`) and the composer's named `conversation.input.model` seat both load the session's advisory directory through `session.models` and submit through `session.selectModel` via the same `ModelDirectory` instance. The compact composer trigger opens a two-level Model/Effort menu: models stay provider-grouped, while the selected exact model supplies its adapter-owned effort names, descriptions, and default. The Host-reported provider/model/reasoning target is the single fact both entries echo; `/model` applies the selected model's default effort, and the composer can then choose any advertised effort. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored target before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior target and directory. Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. +Model selection plugin, browser half: TWO entries over ONE per-session directory owned by `ModelService` (`ctx.models`). The `/model` popupSelect contribution (registered through `ctx.command`) and the composer's named `conversation.input.model` seat both load the session's advisory directory through `session.models` and submit through `session.selectModel` via the same `ModelDirectory` instance. The compact composer trigger opens a two-level Model/Effort menu: models stay provider-grouped, while the selected exact model supplies its adapter-owned effort names, descriptions, and default. The Host-reported provider/model/reasoning target is the single selection fact, but it is echoed only when the exact route remains in the advertised groups; removing that catalog row leaves the routable target intact while the trigger prompts `Select model`, no stale row is synthesized, and no Effort row is shown until the user picks an advertised model. `/model` applies the selected model's default effort, and the composer can then choose any advertised effort. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored target before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior target and directory. Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. The `/client` export surface is the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state shape, and the seat's injected face type. diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md index 6d6f433315..c72eb33163 100644 --- a/packages/client/ui-model/README.zh.md +++ b/packages/client/ui-model/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -模型选择插件（浏览器侧）：**两个入口共用一份会话级目录**，由 `ModelService`（`ctx.models`）持有。`/model` popupSelect 贡献项（经 `ctx.command` 注册）与 composer 的具名 `conversation.input.model` 坑位都通过同一个 `ModelDirectory` 实例，经 `session.models` 加载会话的建议目录，并经 `session.selectModel` 提交。紧凑型 composer 触发器会打开两级 Model/Effort 菜单：模型仍按提供方分组，所选具体模型则提供由其适配器持有的推理强度名称、说明和默认值。Host 报告的提供方／模型／推理（reasoning）目标是两个入口共同回显的唯一事实；`/model` 应用所选模型的默认推理强度，composer 随后可以选择任一已公布的推理强度。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。 +模型选择插件（浏览器侧）：**两个入口共用一份会话级目录**，由 `ModelService`（`ctx.models`）持有。`/model` popupSelect 贡献项（经 `ctx.command` 注册）与 composer 的具名 `conversation.input.model` 坑位都通过同一个 `ModelDirectory` 实例，经 `session.models` 加载会话的建议目录，并经 `session.selectModel` 提交。紧凑型 composer 触发器会打开两级 Model/Effort 菜单：模型仍按提供方分组，所选具体模型则提供由其适配器持有的推理强度名称、说明和默认值。Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择事实，但只有当该精确路由仍在已公布分组中时才会回显；删除该目录行会保留仍可路由的目标，但触发器会提示 `Select model`，系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。`/model` 应用所选模型的默认推理强度，composer 随后可以选择任一已公布的推理强度。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。 `/client` 导出面为插件本体（`apply`/`inject`）、`ModelService`、`ModelDirectory` 及其状态形状、坑位注入面类型。 diff --git a/packages/client/ui-model/src/client/ModelSelect.module.css b/packages/client/ui-model/src/client/ModelSelect.module.css index f9d6cc10e6..fce9b2c28f 100644 --- a/packages/client/ui-model/src/client/ModelSelect.module.css +++ b/packages/client/ui-model/src/client/ModelSelect.module.css @@ -197,8 +197,7 @@ white-space: nowrap; } -.description, -.unlisted { +.description { overflow: hidden; color: var(--dsw-alias-label-tertiary); font-size: 12px; @@ -207,10 +206,6 @@ white-space: nowrap; } -.unlisted { - color: var(--dsw-alias-state-warn-label); -} - .check { display: grid; place-items: center; diff --git a/packages/client/ui-model/src/client/ModelSelect.tsx b/packages/client/ui-model/src/client/ModelSelect.tsx index 4cc2687832..8396e42b5a 100644 --- a/packages/client/ui-model/src/client/ModelSelect.tsx +++ b/packages/client/ui-model/src/client/ModelSelect.tsx @@ -169,8 +169,13 @@ export function ModelSelect( }) } - const modelLabel = choices[selectedIndex]?.model.name ?? state.current?.model ?? t('trigger.fallback') + const modelLabel = currentChoice?.model.name ?? t('trigger.fallback') const triggerLabel = effortLabel === undefined ? modelLabel : `${modelLabel} · ${effortLabel}` + const triggerAria = currentChoice === undefined + ? t('trigger.selectAria') + : effortLabel === undefined + ? t('trigger.aria', { model: modelLabel }) + : t('trigger.ariaEffort', { model: modelLabel, effort: effortLabel }) itemRefs.current = [] let itemIndex = 0 const itemRef = () => { @@ -184,9 +189,7 @@ export function ModelSelect( ref={triggerRef} type="button" className={css.trigger} - aria-label={effortLabel === undefined - ? t('trigger.aria', { model: modelLabel }) - : t('trigger.ariaEffort', { model: modelLabel, effort: effortLabel })} + aria-label={triggerAria} aria-haspopup="menu" aria-expanded={open} aria-controls={open ? `${id}-menu` : undefined} @@ -272,9 +275,6 @@ export function ModelSelect( {model.description !== undefined && ( {model.description} )} - {model.unlisted === true && ( - {t('option.currentUnlisted')} - )} {selected ? : null} diff --git a/packages/client/ui-model/src/client/index.ts b/packages/client/ui-model/src/client/index.ts index a672c6935a..deebf3b000 100644 --- a/packages/client/ui-model/src/client/index.ts +++ b/packages/client/ui-model/src/client/index.ts @@ -49,9 +49,7 @@ function optionsOf(directory: SessionModels, t: TranslateNS<'model'>): SelectOpt rows.push({ id: rowId(group.id, model.id), label: model.name, - detail: model.unlisted === true - ? t('option.unlisted', { group: group.name }) - : model.description !== undefined ? `${group.name} · ${model.description}` : group.name, + detail: model.description !== undefined ? `${group.name} · ${model.description}` : group.name, ...(directory.current.provider === group.id && directory.current.model === model.id ? { active: true } : {}), }) diff --git a/packages/client/ui-model/src/client/locales.ts b/packages/client/ui-model/src/client/locales.ts index 856c95e470..8b83870c40 100644 --- a/packages/client/ui-model/src/client/locales.ts +++ b/packages/client/ui-model/src/client/locales.ts @@ -3,9 +3,9 @@ /** Simplified Chinese dictionary (the key-set source of truth). */ export const zh = { 'command.description': '选择本会话使用的模型', - 'option.unlisted': '{group} · 未列入目录', 'option.loadError': '目录加载失败：{message}', 'trigger.fallback': '选择模型', + 'trigger.selectAria': '选择模型', 'trigger.aria': '选择模型，当前 {model}', 'trigger.ariaEffort': '选择模型，当前 {model}，推理等级 {effort}', 'menu.aria': '模型与推理等级', @@ -16,7 +16,6 @@ export const zh = { 'error.action': '模型操作失败：{message}', 'action.reload': '重新加载', 'warning.groupLoad': '{name} 加载失败：{message}', - 'option.currentUnlisted': '当前模型 · 未列入目录', 'empty.models': '没有可用的模型。', 'empty.efforts': '当前模型未提供推理等级。', } satisfies Record @@ -27,9 +26,9 @@ export type ModelKey = keyof typeof zh /** English dictionary, checked complete against the zh key set. */ export const en = { 'command.description': 'Select the model for this conversation', - 'option.unlisted': '{group} · Not in catalog', 'option.loadError': 'Catalog failed to load: {message}', 'trigger.fallback': 'Select model', + 'trigger.selectAria': 'Select model', 'trigger.aria': 'Select model, current {model}', 'trigger.ariaEffort': 'Select model, current {model}, reasoning effort {effort}', 'menu.aria': 'Model and reasoning effort', @@ -40,7 +39,6 @@ export const en = { 'error.action': 'Model operation failed: {message}', 'action.reload': 'Reload', 'warning.groupLoad': '{name} failed to load: {message}', - 'option.currentUnlisted': 'Current model · Not in catalog', 'empty.models': 'No models available.', 'empty.efforts': 'This model provides no reasoning effort levels.', } satisfies Record diff --git a/packages/client/ui-model/tests/model-select.spec.tsx b/packages/client/ui-model/tests/model-select.spec.tsx index d1dc4f7d1b..3fc459b9c1 100644 --- a/packages/client/ui-model/tests/model-select.spec.tsx +++ b/packages/client/ui-model/tests/model-select.spec.tsx @@ -108,4 +108,26 @@ describe('ModelSelect reasoning effort', () => { expect(screen.getAllByRole('menuitemradio').map(item => item.textContent)) .toEqual(['Default', 'Standard']) }) + + it('prompts for a new selection when the current target is no longer advertised', () => { + const directory = createSnapshotStore(state({ + current: { provider: 'deepseek-official', model: 'removed-model' }, + })) + const select = vi.fn().mockResolvedValue(true) + render() + + const trigger = screen.getByRole('button', { name: '选择模型' }) + expect(trigger.textContent).toContain('选择模型') + fireEvent.click(trigger) + expect(screen.queryByRole('menuitem', { name: /推理等级/ })).toBeNull() + fireEvent.click(screen.getByRole('menuitem', { name: /模型/ })) + expect(screen.queryByText('removed-model')).toBeNull() + expect(screen.getByRole('menuitemradio', { name: 'DeepSeek-V4-Flash' })).toBeTruthy() + }) }) diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml index 951b1d04fe..2cf8870b64 100644 --- a/packages/client/ui-models/README.i18n.yaml +++ b/packages/client/ui-models/README.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 packages/client/ui-models/README.md -README.md: adfbc084e1b0e227d50032cb6c924401b81c6a79 -README.zh.md: 4ee7d4efa729fdccee392ab8e55078b5a4a239ef +README.md: bbd1ad70afd925b2c0b28f444cf8118e241a7723 +README.zh.md: 99ae1e432e261def378a5fac242d24d36a870905 diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md index adfbc084e1..bbd1ad70af 100644 --- a/packages/client/ui-models/README.md +++ b/packages/client/ui-models/README.md @@ -4,11 +4,11 @@ English | [中文](README.zh.md) Models settings plugin: the provider configuration page and official-DeepSeek first-run routing overlay. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time. -Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), plus `reasoningEffort` (deepseek) or `reasoning` (pi-ai); every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base). +Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries `baseURL` for both families, `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and the direct DeepSeek adapter's advisory model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits. A provider row is deletable only when the user layer alone carries it (removal restores the composition base). The first-run overlay projects `deepseek-official` readiness from that same joined snapshot. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference suppresses the prompt, including a read-only launch-environment credential. Only a mounted adapter with a missing writable reference shows the action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the overlay never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability is skipped so onboarding cannot block the rest of the product; the Models page remains the diagnostic surface. -Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling. +Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. Empty ids, duplicate ids, empty explicit names, and non-positive or fractional context windows fail before any write. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling. ## Model Experience @@ -20,7 +20,6 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work -- **Only the API key and the curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)); advanced fields (`models`, retry policy, timeouts…) are edited in `settings.yaml`, which the fold points at. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name. +- **Only the API key and curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)). DeepSeek exposes `baseURL`, `reasoningEffort`, and model `id`/`name`/`contextWindow`; pi-ai exposes `baseURL` and `reasoning`. Retry policy, timeouts, DeepSeek model descriptions, and other advanced fields remain in `settings.yaml`; existing model fields the editor does not show are preserved. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name. - **Deleting a row leaves its stored key in `.env`** — removal unsets the settings profile but deliberately does not unset the derived credential; re-adding the provider finds the key already configured. An explicit key-removal control is deferred. -- **No per-provider model listing on the page** — the picker surfaces models; this page shows route state only. A models preview per row is deferred until a consumer needs it. - **Undeclared live routes render nowhere** — a route registered without a configurable-provider declaration has no settings address; it stays visible in pickers but not on this page's rows. diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md index 4ee7d4efa7..99ae1e432e 100644 --- a/packages/client/ui-models/README.zh.md +++ b/packages/client/ui-models/README.zh.md @@ -4,11 +4,11 @@ 模型设置插件：提供方配置页和 DeepSeek 官方首次使用跳转浮层。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片。 -行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另加 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai）；其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base）。 +行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载两个家族的 `baseURL`、deepseek 的 `reasoningEffort` 或 pi-ai 的 `reasoning`，以及直接 DeepSeek 适配器的建议性模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留。只有当某个提供方行仅由用户层承载时它才可删除（删除会还原组合 base）。 首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此不会把同一提供方 ID 下没有相应声明的存活路由视为可通过配置修复。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。只有适配器已挂载、引用可写但尚未配置时，浮层才显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，浮层绝不持有 secret。适配器缺失、路由未激活、联接失败、部署只读、设置能力不可用或凭据能力不可用时均跳过，以免首次使用引导阻塞产品的其他部分；Models 页仍是诊断界面。 -每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除整行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。 +每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。空 ID、重复 ID、显式填写的空名称，以及非正数或非整数的上下文窗口都会在写入前失败。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。 ## 模型体验 @@ -20,7 +20,6 @@ ## 已知限制与暂缓事项 -- **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）；进阶字段（`models`、重试策略、超时……）在 `settings.yaml` 中编辑，折叠区会指向它。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。 +- **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）。DeepSeek 公开 `baseURL`、`reasoningEffort` 与模型的 `id`/`name`/`contextWindow`；pi-ai 公开 `baseURL` 与 `reasoning`。重试策略、超时、DeepSeek 模型说明及其他进阶字段仍留在 `settings.yaml` 中；编辑器未展示的现有模型字段会予以保留。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。 - **删除一行会把它已存储的密钥留在 `.env` 里**：删除取消设置的是 settings profile，却刻意不清除那条派生凭据；重新添加该提供方时会发现密钥已配置。显式的密钥移除控件暂缓。 -- **页面上没有逐提供方的模型列表**：模型由选择器呈现；本页只展示路由状态。逐行的模型预览暂缓，待有消费方需要时再实现。 - **未声明的存活路由无处渲染**：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。 diff --git a/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx b/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx new file mode 100644 index 0000000000..c79eb57412 --- /dev/null +++ b/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx @@ -0,0 +1,196 @@ +/** + * Curated editor for the direct DeepSeek adapter's advisory model catalog. + * The settings layer replaces `models` as one array, so the parent supplies + * the effective inherited rows until the first edit materializes a user + * override; reset removes that override instead of copying defaults into it. + */ + +import type { ReactNode } from 'react' +import { IconPlusOutline16, IconTrashOutline16 } from '@deepseek-ai/dsh-client-ui-primitives' +import type { en } from './locales.ts' +import styles from './ModelsSection.module.css' + +/** One catalog entry kept structurally open so hidden or future fields survive an edit. */ +export type DeepSeekModelDraft = Record + +/** A localized validation failure for one user-owned model array. */ +export interface DeepSeekModelsValidationFailure { + /** Zero-based model position. */ + index: number + /** Message key owned by the Models settings section. */ + key: 'modelIdRequired' | 'modelIdDuplicate' | 'modelNameInvalid' | 'modelContextInvalid' +} + +/** Convert a schema-validated catalog value into records without dropping hidden fields. */ +export function modelDrafts(value: unknown): DeepSeekModelDraft[] { + if (!Array.isArray(value)) return [] + return value.map(entry => + typeof entry === 'object' && entry !== null && !Array.isArray(entry) + ? entry as DeepSeekModelDraft + : {}) +} + +/** + * Validate adapter constraints that the serialized schema cannot express. + * @param value - user-owned `models` value, or undefined while inherited. + * @returns the first invalid row, or undefined when the adapter will accept it. + */ +export function validateDeepSeekModels(value: unknown): DeepSeekModelsValidationFailure | undefined { + if (value === undefined) return undefined + const models = modelDrafts(value) + const seen = new Set() + for (const [index, model] of models.entries()) { + const id = model['id'] + if (typeof id !== 'string' || id.length === 0) return { index, key: 'modelIdRequired' } + if (seen.has(id)) return { index, key: 'modelIdDuplicate' } + seen.add(id) + const name = model['name'] + if (name !== undefined && (typeof name !== 'string' || name.length === 0)) { + return { index, key: 'modelNameInvalid' } + } + const contextWindow = model['contextWindow'] + if (contextWindow !== undefined + && (typeof contextWindow !== 'number' || !Number.isInteger(contextWindow) || contextWindow <= 0)) { + return { index, key: 'modelContextInvalid' } + } + } + return undefined +} + +/** Props of {@link DeepSeekModelsEditor}. */ +export interface DeepSeekModelsEditorProps { + /** Effective rows: inherited until the parent materializes an override. */ + models: readonly DeepSeekModelDraft[] + /** Whether the user layer currently owns the whole array. */ + overridden: boolean + /** Fallback capacity used when a row omits its exact value. */ + defaultContextWindow: number | undefined + /** Section copy. */ + t: (key: keyof typeof en) => string + /** Disable every mutation. */ + disabled: boolean + /** Replace the user-owned array after one visible edit. */ + onChange: (models: DeepSeekModelDraft[]) => void + /** Remove the user-owned array and return to inheritance. */ + onReset: () => void +} + +/** + * Render the direct DeepSeek adapter's id/name/context-window catalog. + * @param props - effective rows plus the array-level override actions. + * @returns the catalog editor. + */ +export function DeepSeekModelsEditor(props: DeepSeekModelsEditorProps): ReactNode { + const update = (index: number, key: 'id' | 'name' | 'contextWindow', value: unknown): void => { + const next = props.models.map((model, at) => { + const copy = { ...model } + if (at !== index) return copy + if (value === undefined) Reflect.deleteProperty(copy, key) + else copy[key] = value + return copy + }) + props.onChange(next) + } + + const remove = (index: number): void => { + props.onChange(props.models.filter((_model, at) => at !== index).map(model => ({ ...model }))) + } + + return ( +
+
+
+ {props.t('models')} + + {props.overridden ? props.t('modelsCustomized') : props.t('modelsInherited')} + +
+ {props.overridden + ? ( + + ) + : null} +
+ {props.models.length === 0 + ?

{props.t('modelsEmpty')}

+ : ( +
+ {/* Captions sit above the rows and are hidden from assistive tech: + every field already carries the indexed `aria-label` naming it. */} + + {props.models.map((model, index) => ( +
+ { update(index, 'id', event.target.value) }} + /> + { + update(index, 'name', event.target.value === '' ? undefined : event.target.value) + }} + /> + { + update( + index, + 'contextWindow', + event.target.value === '' ? undefined : Number(event.target.value), + ) + }} + /> + +
+ ))} +
+ )} + +
+ ) +} diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css index a2be484a63..798f45126c 100644 --- a/packages/client/ui-models/src/client/ModelsSection.module.css +++ b/packages/client/ui-models/src/client/ModelsSection.module.css @@ -1,3 +1,13 @@ +/* Models settings section, in the settings-panel design language: 14/22 body, + * 12/18 caption, capsule controls (h36 r18; h28 r14 where a row is dense), + * 32px fields, and `border-l2` hairlines — the vocabulary GeneralSection and + * the Button/Input primitives already use. + * + * Every color resolves through a `--dsw-alias-*` token. The section used to + * name `--border` / `--surface` / `--text-*`, which nothing in this app + * defines, so it always rendered the light-mode literals written as their + * fallbacks and stayed light under the dark theme. */ + .section { display: flex; flex-direction: column; @@ -7,20 +17,24 @@ .title { margin: 0; - font-size: 18px; - font-weight: 600; + font-size: 16px; + line-height: 24px; + font-weight: 500; + color: var(--dsw-alias-label-primary); } .intro { margin: 0; - font-size: 13px; - color: var(--text-tertiary, #888); + font-size: 14px; + line-height: 22px; + color: var(--dsw-alias-label-tertiary); } .notice { margin: 0; font-size: 12px; - color: var(--text-warning, #a15c00); + line-height: 18px; + color: var(--dsw-alias-state-warn-label); } .rows { @@ -29,17 +43,18 @@ padding: 0; display: flex; flex-direction: column; - gap: 10px; + gap: 8px; } +/* A configured provider: outlined on the panel fill, so the filled editor + card it expands into reads as the nested object. */ .rowCard { - border: 1px solid var(--border, #e2e2e2); + border: 1px solid var(--dsw-alias-border-l2); border-radius: 12px; padding: 12px 14px; display: flex; flex-direction: column; gap: 12px; - background: var(--surface, #fff); } .rowHead { @@ -49,8 +64,10 @@ } .rowName { - font-size: 15px; - font-weight: 600; + font-size: 14px; + line-height: 22px; + font-weight: 500; + color: var(--dsw-alias-label-primary); } .badges { @@ -63,8 +80,9 @@ display: inline-flex; align-items: center; gap: 5px; - color: var(--text-success, #0a7d33); + color: var(--dsw-alias-state-success-primary); font-size: 12px; + line-height: 18px; } .badgeOk::before { @@ -76,59 +94,118 @@ } .badgeMuted { - color: var(--text-tertiary, #999); - font-size: 12px; -} - -.badgeWarn { - color: var(--text-warning, #a15c00); + color: var(--dsw-alias-label-tertiary); font-size: 12px; + line-height: 18px; } .rowActions { display: inline-flex; - gap: 8px; + align-items: center; + gap: 4px; +} + +/* `box-sizing` on every control here: the app has no global border-box reset, + so without it the outlined variants stand 2px taller than the filled ones + they sit beside (Cancel next to Apply, Edit next to Delete). */ +.primaryButton, +.secondaryButton, +.addButton { + box-sizing: border-box; + display: inline-flex; + align-items: center; + justify-content: center; + gap: 4px; + height: 36px; + padding: 0 14px; + border: none; + border-radius: 18px; + font: inherit; + font-size: 14px; + line-height: 22px; + cursor: pointer; } .primaryButton { - border: none; - border-radius: 999px; - padding: 8px 18px; - background: var(--accent-strong, #111); - color: var(--text-inverse, #fff); - font: inherit; - cursor: pointer; + background: var(--dsw-alias-button-primary-fill); + color: var(--dsw-alias-label-primary-foreground); } -.secondaryButton { - border: 1px solid var(--border, #d9d9d9); - border-radius: 999px; - padding: 6px 14px; - background: var(--surface, #fff); - color: inherit; - font: inherit; - cursor: pointer; +.primaryButton:hover:not(:disabled) { + background: var(--dsw-alias-button-primary-hover); +} + +.secondaryButton, +.addButton { + border: 1px solid var(--dsw-alias-border-l2); + background: transparent; + color: var(--dsw-alias-label-primary); +} + +.secondaryButton:hover:not(:disabled), +.addButton:hover:not(:disabled) { + background: var(--dsw-alias-interactive-bg-hover); } .dangerButton { + box-sizing: border-box; + display: inline-flex; + align-items: center; + justify-content: center; + height: 36px; + padding: 0 14px; border: none; - background: none; - color: var(--text-danger, #c0392b); + border-radius: 18px; + background: transparent; + color: var(--dsw-alias-state-error-primary); font: inherit; + font-size: 14px; + line-height: 22px; cursor: pointer; } +.dangerButton:hover:not(:disabled) { + background: var(--dsw-alias-interactive-bg-hover-danger); +} + +/* Provider-row controls take the dense capsule (Button `.sm`). */ +.rowActions .secondaryButton, +.rowActions .dangerButton { + height: 28px; + padding: 0 10px; + border-radius: 14px; + font-size: 12px; + line-height: 18px; +} + .primaryButton:disabled, .secondaryButton:disabled, -.dangerButton:disabled { - opacity: 0.5; +.dangerButton:disabled, +.addButton:disabled, +.linkButton:disabled, +.addModelButton:disabled, +.rowDelete:disabled { + opacity: 0.4; cursor: default; } +.primaryButton:focus-visible, +.secondaryButton:focus-visible, +.dangerButton:focus-visible, +.addButton:focus-visible, +.linkButton:focus-visible, +.addModelButton:focus-visible, +.rowDelete:focus-visible, +.customizedSummary:focus-visible { + outline: none; + box-shadow: 0 0 0 2px var(--dsw-alias-border-l3); +} + +/* Editing surface: a filled module on the panel, matching the settings + selector fill rather than adding another outline inside the row. */ .editor { - border: 1px solid var(--border, #e6e6e6); border-radius: 12px; - background: var(--surface-secondary, #f7f7f8); + background: var(--dsw-alias-bg-module-platform); padding: 14px 16px; display: flex; flex-direction: column; @@ -143,12 +220,15 @@ .editorTitle { font-size: 14px; - font-weight: 600; + line-height: 22px; + font-weight: 500; + color: var(--dsw-alias-label-primary); } .editorRoute { font-size: 12px; - color: var(--text-tertiary, #999); + line-height: 18px; + color: var(--dsw-alias-label-tertiary); } .field { @@ -162,30 +242,37 @@ align-items: center; gap: 10px; font-size: 12px; + line-height: 18px; font-weight: 500; - color: var(--text-secondary, #555); + color: var(--dsw-alias-label-secondary); } .linkButton { + box-sizing: border-box; + display: inline-flex; + align-items: center; + height: 28px; + padding: 0 10px; border: none; - background: none; - padding: 0; - color: var(--text-tertiary, #888); + border-radius: 14px; + background: transparent; + color: var(--dsw-alias-label-tertiary); font: inherit; font-size: 12px; - text-decoration: underline; + line-height: 18px; cursor: pointer; } -.linkButton:disabled { - opacity: 0.5; - cursor: default; +.linkButton:hover:not(:disabled) { + background: var(--dsw-alias-interactive-bg-hover); + color: var(--dsw-alias-label-secondary); } .advancedHint { margin: 0; font-size: 12px; - color: var(--text-tertiary, #999); + line-height: 18px; + color: var(--dsw-alias-label-tertiary); } .editorActions { @@ -202,26 +289,12 @@ .addButton { align-self: flex-start; - border: 1px solid var(--border, #d9d9d9); - border-radius: 999px; - padding: 8px 16px; - font: inherit; - font-size: 13px; - background: var(--surface, #fff); - color: inherit; - cursor: pointer; -} - -.addButton:disabled { - opacity: 0.5; - cursor: default; } .addCard, .setupCard { - border: 1px solid var(--border, #e6e6e6); border-radius: 12px; - background: var(--surface-secondary, #f7f7f8); + background: var(--dsw-alias-bg-module-platform); padding: 14px 16px; display: flex; flex-direction: column; @@ -229,24 +302,56 @@ list-style: none; } +/* Nested in a card that already carries the module chrome. */ .addCard .editor, .setupCard .editor { - border: none; background: none; padding: 0; } .customized { - border-top: 1px solid var(--border, #ececec); + border-top: 1px solid var(--dsw-alias-border-l2); padding-top: 10px; } +/* Native disclosure marker replaced by a rotating chevron: the built-in + triangle differs per engine and cannot take the label color. */ .customizedSummary { + display: flex; + align-items: center; + gap: 6px; + width: fit-content; + padding: 2px 4px; + margin-left: -4px; + border-radius: 6px; cursor: pointer; font-size: 12px; + line-height: 18px; font-weight: 500; - color: var(--text-secondary, #555); - list-style: revert; + color: var(--dsw-alias-label-secondary); + list-style: none; +} + +.customizedSummary::-webkit-details-marker { + display: none; +} + +.customizedSummary::before { + content: ''; + width: 5px; + height: 5px; + border-right: 1.5px solid currentcolor; + border-bottom: 1.5px solid currentcolor; + transform: rotate(-45deg) translate(-1px, -1px); + transition: transform 120ms ease; +} + +.customized[open] > .customizedSummary::before { + transform: rotate(45deg) translate(-1px, -1px); +} + +.customizedSummary:hover { + color: var(--dsw-alias-label-primary); } .customizedBody { @@ -256,28 +361,179 @@ padding-top: 12px; } +/* Model catalog: a table, not a stack of cards. The column captions are + written once above the rows, so a row is one line of fields plus its + delete control; each field still carries the indexed `aria-label` that + names it, and the caption strip is hidden from assistive tech to keep + that name from being announced twice. */ +.modelCatalog { + display: flex; + flex-direction: column; + gap: 10px; + padding-top: 12px; + border-top: 1px solid var(--dsw-alias-border-l2); +} + +.modelCatalogHeader { + display: flex; + align-items: flex-start; + justify-content: space-between; + gap: 12px; +} + +.modelCatalogHeading { + display: flex; + flex-direction: column; + gap: 2px; +} + +.modelCatalogTitle { + font-size: 12px; + line-height: 18px; + font-weight: 500; + color: var(--dsw-alias-label-secondary); +} + +.modelCatalogMeta, +.modelEmpty { + margin: 0; + color: var(--dsw-alias-label-tertiary); + font-size: 12px; + line-height: 18px; +} + +.modelTable { + display: flex; + flex-direction: column; + gap: 6px; +} + +/* Captions and rows share one track list so the columns line up. */ +.modelColumns, +.modelRow { + display: grid; + grid-template-columns: minmax(0, 1.25fr) minmax(0, 1.25fr) minmax(88px, 0.75fr) 28px; + align-items: center; + gap: 8px; +} + +.modelColumns { + color: var(--dsw-alias-label-tertiary); + font-size: 12px; + line-height: 18px; +} + +/* The inset belongs on the caption cell, not the strip: padding on the grid + container would narrow its tracks against the rows' and walk the captions + left column by column. 1px border + 10px padding is the field text inset. */ +.modelColumns > span { + padding-left: 11px; +} + +.rowDelete { + box-sizing: border-box; + position: relative; + display: grid; + place-items: center; + width: 28px; + height: 28px; + padding: 0; + border: none; + border-radius: 8px; + background: transparent; + color: var(--dsw-alias-label-tertiary); + cursor: pointer; +} + +.rowDelete:hover:not(:disabled) { + background: var(--dsw-alias-interactive-bg-hover-danger); + color: var(--dsw-alias-state-error-primary); +} + +.modelEmpty { + padding: 12px; + border: 1px dashed var(--dsw-alias-border-l3); + border-radius: 8px; + text-align: center; +} + +.addModelButton { + box-sizing: border-box; + align-self: flex-start; + display: inline-flex; + align-items: center; + gap: 4px; + height: 28px; + padding: 0 10px; + border: 1px solid var(--dsw-alias-border-l2); + border-radius: 14px; + background: transparent; + color: var(--dsw-alias-label-primary); + font: inherit; + font-size: 12px; + line-height: 18px; + cursor: pointer; +} + +.addModelButton:hover:not(:disabled) { + background: var(--dsw-alias-interactive-bg-hover); +} + .input { box-sizing: border-box; - padding: 9px 12px; - border: 1px solid var(--border, #d9d9d9); - border-radius: 10px; + width: 100%; + height: 32px; + padding: 0 10px; + border: 1px solid var(--dsw-alias-border-l2); + border-radius: 8px; font: inherit; - font-size: 13px; - background: var(--surface, #fff); - color: inherit; + font-size: 14px; + line-height: 22px; + background: var(--dsw-alias-bg-layer-1); + color: var(--dsw-alias-label-primary); +} + +/* Enum pickers hold a handful of short options; a field-width dropdown reads + as a text field the user is expected to fill. */ +select.input { + max-width: 240px; + cursor: pointer; } .input:focus { outline: none; - border-color: var(--accent-strong, #111); + border-color: var(--dsw-alias-brand-primary); } .input::placeholder { - color: var(--text-tertiary, #aaa); + color: var(--dsw-alias-label-dimmed); +} + +.input:disabled { + opacity: 0.6; + cursor: default; } .error { margin: 0; font-size: 12px; - color: var(--text-danger, #c0392b); + line-height: 18px; + color: var(--dsw-alias-state-error-primary); +} + +/* Icon-button label seat: named for assistive tech and for the tests that + query these controls by their text. */ +.hiddenLabel { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip: rect(0 0 0 0); + white-space: nowrap; +} + +@media (prefers-reduced-motion: reduce) { + .customizedSummary::before { + transition: none; + } } diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx index d095acb86c..4dea825a2d 100644 --- a/packages/client/ui-models/src/client/ModelsSection.tsx +++ b/packages/client/ui-models/src/client/ModelsSection.tsx @@ -11,6 +11,7 @@ import { useState } from 'react' import type { ReactNode } from 'react' import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client' +import { IconPlusOutline16 } from '@deepseek-ai/dsh-client-ui-primitives' import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react' import { messageOf } from './store.ts' import type { ModelsSettingsState, ModelsSettingsStore, ProviderRow } from './store.ts' @@ -272,7 +273,8 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode { setEditing(targetOf(first)) }} > - {`+ ${t('add')}`} + + {t('add')} )}
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx index 07b5dfae54..746d1cba35 100644 --- a/packages/client/ui-models/src/client/ProviderEditor.tsx +++ b/packages/client/ui-models/src/client/ProviderEditor.tsx @@ -5,19 +5,23 @@ * under the profile's reference, deriving `_API_KEY` when the profile * has none, and the pi-ai profile records that derivation as `apiKeyEnv`); * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for - * both families, plus `reasoningEffort` for deepseek / `reasoning` for - * pi-ai). Everything else stays owned by `settings.yaml`. Profile edits land as - * minimal `settings.mutate` path ops against the stored section — the card - * reads the redacted descriptor, so it names only the fields it can see and a - * stored literal secret is never collaterally removed. + * both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, and + * DeepSeek's id/name/context-window model catalog). Everything else stays + * owned by `settings.yaml`. Profile edits land as minimal `settings.mutate` + * path ops against the stored section — the card reads the redacted + * descriptor, so it names only the fields it can see and a stored literal + * secret is never collaterally removed. */ import { useEffect, useMemo, useState } from 'react' import type { ReactNode } from 'react' import type { CredentialView, IApiClient, SettingsNamespaceView, SettingsPathOpView } from '@deepseek-ai/dsh-client-connection/client' import { - deletePath, getPath, nodeAtPath, rehydrateSchema, setPath, validateDraft, + deletePath, getPath, hasPath, nodeAtPath, rehydrateSchema, setPath, validateDraft, } from '@deepseek-ai/dsh-client-schema-form' +import { + DeepSeekModelsEditor, modelDrafts, validateDeepSeekModels, +} from './DeepSeekModelsEditor.tsx' import { deriveKeyRef, messageOf } from './store.ts' import type { en } from './locales.ts' import styles from './ModelsSection.module.css' @@ -179,6 +183,12 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode { && stringAt(fallback, 'apiKeyEnv') === undefined ? setPath(draft, ['apiKeyEnv'], keyRef) : draft + if (layout === 'deepseek') { + const modelFailure = validateDeepSeekModels(getPath(next, ['models'])) + if (modelFailure !== undefined) { + return `${t('model')} ${String(modelFailure.index + 1)}: ${t(modelFailure.key)}` + } + } /* v8 ignore next -- apply is only reachable from the rendered card, which required a resolved node */ if (node !== undefined && settingsPath.length === 0) { const sectionError = validateDraft(node, next) @@ -236,6 +246,10 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode { */ const curatedFields = (family: 'deepseek' | 'pi-ai'): ReactNode => { const effortField = EFFORT_FIELD[family] + const customModels = getPath(draft, ['models']) + const modelsOverridden = hasPath(draft, ['models']) + const models = modelDrafts(modelsOverridden ? customModels : getPath(fallback, ['models'])) + const defaultContextWindow = getPath(fallback, ['defaultContextWindow']) return ( <>
@@ -289,6 +303,21 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode { ))}
+ {family === 'deepseek' + ? ( + { setDraft(current => setPath(current, ['models'], next)) }} + onReset={() => { setDraft(current => deletePath(current, ['models'])) }} + /> + ) + : null} diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts index 48431ddacf..c41846216b 100644 --- a/packages/client/ui-models/src/client/locales.ts +++ b/packages/client/ui-models/src/client/locales.ts @@ -27,6 +27,23 @@ export const en = { baseUrlDefault: 'Provider default', effort: 'Reasoning effort', effortInherit: 'Default', + models: 'Models', + modelsInherited: 'Using the adapter defaults', + modelsCustomized: 'Customized model catalog', + resetModels: 'Restore defaults', + model: 'Model', + modelId: 'Model ID', + modelName: 'Display name', + modelNamePlaceholder: 'Uses the model ID when empty', + contextWindow: 'Context window', + contextWindowPlaceholder: 'Uses the provider default', + addModel: 'Add model', + removeModel: 'Delete model', + modelsEmpty: 'No models will be shown in the selector. Unlisted IDs can still be sent directly.', + modelIdRequired: 'Model ID is required.', + modelIdDuplicate: 'Model ID must be unique.', + modelNameInvalid: 'Display name cannot be empty.', + modelContextInvalid: 'Context window must be a positive integer.', advancedHint: 'Other fields live in settings.yaml; edit that section directly.', onboardingTitle: 'Add an API key to get started', onboardingDescription: 'Configure the official DeepSeek provider to start building.', @@ -64,6 +81,23 @@ export const zh: typeof en = { baseUrlDefault: '提供方默认', effort: '推理强度', effortInherit: '默认', + models: '模型目录', + modelsInherited: '正在使用适配器默认模型', + modelsCustomized: '已自定义模型目录', + resetModels: '恢复默认模型', + model: '模型', + modelId: '模型 ID', + modelName: '显示名称', + modelNamePlaceholder: '留空时使用模型 ID', + contextWindow: '上下文窗口', + contextWindowPlaceholder: '使用提供方默认值', + addModel: '添加模型', + removeModel: '删除模型', + modelsEmpty: '模型选择器中将不显示任何模型；目录外 ID 仍可直接发送。', + modelIdRequired: '模型 ID 不能为空。', + modelIdDuplicate: '模型 ID 不能重复。', + modelNameInvalid: '显示名称不能为空。', + modelContextInvalid: '上下文窗口必须是正整数。', advancedHint: '其余字段在 settings.yaml 中，请直接编辑对应段。', onboardingTitle: '添加一个 API Key 开始使用', onboardingDescription: '配置 DeepSeek 官方模型，即可开始使用。', diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx index a4f3734fbd..bbfe4782da 100644 --- a/packages/client/ui-models/tests/components.spec.tsx +++ b/packages/client/ui-models/tests/components.spec.tsx @@ -8,6 +8,9 @@ import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-client import { ModelsSection, needsSetup, removeProviderProfile } from '../src/client/ModelsSection.tsx' import type { ModelsSectionInjected, ModelsSectionProps } from '../src/client/ModelsSection.tsx' import { pathOps } from '../src/client/ProviderEditor.tsx' +import { + DeepSeekModelsEditor, modelDrafts, validateDeepSeekModels, +} from '../src/client/DeepSeekModelsEditor.tsx' import { deriveKeyRef, ModelsSettingsStore } from '../src/client/store.ts' import type { ProviderRow } from '../src/client/store.ts' import { en } from '../src/client/locales.ts' @@ -32,15 +35,38 @@ const DeepSeekConfig = Schema.object({ apiKeyEnv: Schema.string().role('credential-ref'), baseURL: Schema.string().pattern(/^https:\/\//), reasoningEffort: Schema.union(['off', 'high', 'max']), + defaultContextWindow: Schema.number().step(1).min(1), + models: Schema.array(Schema.object({ + id: Schema.string().required(), + name: Schema.string(), + description: Schema.string(), + contextWindow: Schema.number().step(1).min(1), + })), }) +const DEFAULT_DEEPSEEK_MODELS = [ + { + id: 'deepseek-v4-flash', + name: 'DeepSeek-V4-Flash', + description: 'Preserved hidden detail', + contextWindow: 1_000_000, + }, + { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro', contextWindow: 1_000_000 }, +] + function wireNamespaces(): SettingsNamespaceView[] { return [ { ns: 'llm-deepseek', schema: JSON.parse(JSON.stringify(DeepSeekConfig.toJSON())) as unknown, - value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base', reasoningEffort: 'high' }, - base: {}, + value: { + apiKeyEnv: 'DEEPSEEK_API_KEY', + baseURL: 'https://base', + reasoningEffort: 'high', + defaultContextWindow: 1_000_000, + models: DEFAULT_DEEPSEEK_MODELS, + }, + base: { defaultContextWindow: 1_000_000, models: DEFAULT_DEEPSEEK_MODELS }, user: { reasoningEffort: 'high' }, applies: 'live', secrets: [{ path: ['apiKey'], set: false }], @@ -156,7 +182,7 @@ describe('ModelsSection', () => { expect(screen.getByText('openai')).toBeTruthy() expect(screen.getAllByText(en.active)).toHaveLength(1) expect(screen.getByText(en.dormant)).toBeTruthy() - expect(screen.getByText(`+ ${en.add}`)).toBeTruthy() + expect(screen.getByText(en.add)).toBeTruthy() }) it('turns the setup card into a row once the credential reports configured', async () => { @@ -245,6 +271,115 @@ describe('ModelsSection', () => { }) }) + it('materializes inherited models and adds an arbitrary DeepSeek id', async () => { + const { mutate } = await mountSection({ + mutate: vi.fn(() => Promise.resolve(ok(wireNamespaces()[0]))), + }) + fireEvent.click(screen.getByText(en.customized)) + expect(screen.getByText(en.modelsInherited)).toBeTruthy() + expect(screen.getAllByLabelText(new RegExp(en.modelId)).map(input => (input as HTMLInputElement).value)) + .toEqual(['deepseek-v4-flash', 'deepseek-v4-pro']) + + fireEvent.click(screen.getByText(en.addModel)) + const ids = screen.getAllByLabelText(new RegExp(en.modelId)) + const names = screen.getAllByLabelText(new RegExp(en.modelName)) + const windows = screen.getAllByLabelText(new RegExp(en.contextWindow)) + fireEvent.change(ids[2] as HTMLInputElement, { target: { value: 'private-preview' } }) + fireEvent.change(names[2] as HTMLInputElement, { target: { value: 'Private Preview' } }) + fireEvent.change(windows[2] as HTMLInputElement, { target: { value: '131072' } }) + fireEvent.click(screen.getByText(en.apply)) + + await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) }) + expect(mutate.mock.calls[0]?.[0]).toEqual({ + ns: 'llm-deepseek', + ops: [{ + op: 'set', + path: ['models'], + value: [ + ...DEFAULT_DEEPSEEK_MODELS, + { id: 'private-preview', name: 'Private Preview', contextWindow: 131_072 }, + ], + }], + expectedRevision: 0, + }) + }) + + it('rejects duplicate DeepSeek model ids before writing', async () => { + const { mutate } = await mountSection() + fireEvent.click(screen.getByText(en.customized)) + fireEvent.click(screen.getByText(en.addModel)) + const ids = screen.getAllByLabelText(new RegExp(en.modelId)) + fireEvent.change(ids[2] as HTMLInputElement, { target: { value: 'deepseek-v4-flash' } }) + fireEvent.click(screen.getByText(en.apply)) + + await screen.findByText(`Model 3: ${en.modelIdDuplicate}`) + expect(mutate).not.toHaveBeenCalled() + }) + + it('validates every adapter-owned model catalog invariant', () => { + expect(modelDrafts(undefined)).toEqual([]) + expect(modelDrafts([null, 'bad', { id: 'ok' }])).toEqual([{}, {}, { id: 'ok' }]) + expect(validateDeepSeekModels([{}])).toEqual({ index: 0, key: 'modelIdRequired' }) + expect(validateDeepSeekModels([{ id: 'same' }, { id: 'same' }])) + .toEqual({ index: 1, key: 'modelIdDuplicate' }) + expect(validateDeepSeekModels([{ id: 'model', name: '' }])) + .toEqual({ index: 0, key: 'modelNameInvalid' }) + expect(validateDeepSeekModels([{ id: 'model', contextWindow: null }])) + .toEqual({ index: 0, key: 'modelContextInvalid' }) + expect(validateDeepSeekModels([{ id: 'model', contextWindow: 1.5 }])) + .toEqual({ index: 0, key: 'modelContextInvalid' }) + expect(validateDeepSeekModels([{ id: 'model', contextWindow: 0 }])) + .toEqual({ index: 0, key: 'modelContextInvalid' }) + expect(validateDeepSeekModels([{ id: 'model', contextWindow: 1 }])).toBeUndefined() + }) + + it('renders malformed draft fallbacks without inventing catalog values', () => { + render() + expect(screen.getByLabelText(`${en.modelId} 1`).value).toBe('') + expect(screen.getByLabelText(`${en.contextWindow} 1`).placeholder) + .toBe(en.contextWindowPlaceholder) + }) + + it('can empty and reset the model override, then clear optional fields without dropping hidden data', async () => { + const { mutate } = await mountSection({ + mutate: vi.fn(() => Promise.resolve(ok(wireNamespaces()[0]))), + }) + fireEvent.click(screen.getByText(en.customized)) + fireEvent.click(screen.getAllByText(en.removeModel)[0] as HTMLElement) + fireEvent.click(screen.getByText(en.removeModel)) + expect(screen.getByText(en.modelsEmpty)).toBeTruthy() + fireEvent.click(screen.getByText(en.resetModels)) + expect(screen.getByText(en.modelsInherited)).toBeTruthy() + + const names = screen.getAllByLabelText(new RegExp(en.modelName)) + const windows = screen.getAllByLabelText(new RegExp(en.contextWindow)) + fireEvent.change(names[0] as HTMLInputElement, { target: { value: '' } }) + fireEvent.change(windows[0] as HTMLInputElement, { target: { value: '' } }) + fireEvent.click(screen.getByText(en.apply)) + + await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) }) + expect(mutate.mock.calls[0]?.[0]).toEqual({ + ns: 'llm-deepseek', + ops: [{ + op: 'set', + path: ['models'], + value: [ + { id: 'deepseek-v4-flash', description: 'Preserved hidden detail' }, + DEFAULT_DEEPSEEK_MODELS[1], + ], + }], + expectedRevision: 0, + }) + }) + it('clears an inherited override with an unset op, never a whole-section replace', async () => { // The data-loss shape: the old path rebuilt the section from the REDACTED // user layer and replaced it wholesale, deleting any stored literal key. @@ -333,7 +468,7 @@ describe('ModelsSection', () => { it('adds a dormant provider with a derived reference and stores its key', async () => { const { mutate, set } = await mountSection() - fireEvent.click(screen.getByText(`+ ${en.add}`)) + fireEvent.click(screen.getByText(en.add)) const pick = await screen.findByLabelText(en.provider) expect([...pick.options].map(option => option.value)).toEqual(['anthropic', 'broken', 'plain']) expect(pick.value).toBe('anthropic') @@ -357,7 +492,7 @@ describe('ModelsSection', () => { it('switches the add card target and degrades unknown or broken targets loudly', async () => { await mountSection() - fireEvent.click(screen.getByText(`+ ${en.add}`)) + fireEvent.click(screen.getByText(en.add)) const pick = await screen.findByLabelText(en.provider) fireEvent.change(pick, { target: { value: 'broken' } }) await screen.findByText(/unresolvable settings path/) @@ -375,7 +510,7 @@ describe('ModelsSection', () => { const { set } = await mountSection({ mutate: vi.fn(() => Promise.resolve(fail('llm-pi-ai: unknown pi-ai provider "bogus"'))), }) - fireEvent.click(screen.getByText(`+ ${en.add}`)) + fireEvent.click(screen.getByText(en.add)) await screen.findByLabelText(en.provider) const keys = screen.getAllByLabelText(en.keyInput) fireEvent.change(keys[keys.length - 1] as HTMLInputElement, { target: { value: 'sk-x' } }) @@ -515,7 +650,7 @@ describe('ModelsSection', () => { />) expect(screen.getByText(en.readOnly)).toBeTruthy() expect(screen.getAllByText(en.remove).every(button => button.disabled)).toBe(true) - expect(screen.getByText(`+ ${en.add}`).disabled).toBe(true) + expect(screen.getByText(en.add).disabled).toBe(true) }) it('toggles the row editor closed on a second edit click and on cancel', async () => { @@ -534,10 +669,10 @@ describe('ModelsSection', () => { it('cancels the add card back to the add button', async () => { await mountSection() - fireEvent.click(screen.getByText(`+ ${en.add}`)) + fireEvent.click(screen.getByText(en.add)) await screen.findByLabelText(en.provider) fireEvent.click(screen.getAllByText(en.cancel)[1] as HTMLElement) - await screen.findByText(`+ ${en.add}`) + await screen.findByText(en.add) expect(screen.queryByLabelText(en.provider)).toBeNull() }) diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml index 02cf787a27..a962d9dfeb 100644 --- a/packages/host/apiproxy/README.i18n.yaml +++ b/packages/host/apiproxy/README.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 packages/host/apiproxy/README.md -README.md: 73d8afb32f868ca82dfa2d350df089a5d0b9b358 -README.zh.md: 47af18f76302e261e18f682e0d3cf0ee903933db +README.md: e57ea657c5432612ef024fc585febc0896a3ab43 +README.zh.md: 57d2604dedbd86102ab5ef9fbe156792aeb5905f diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md index 73d8afb32f..e57ea657c5 100644 --- a/packages/host/apiproxy/README.md +++ b/packages/host/apiproxy/README.md @@ -18,7 +18,7 @@ Session titles ride the generic projection pair like every other domain — the `session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale. -Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target with provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. +Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. Pending queued input is a live control-plane contract, not session history. The gateway mirrors queued `InboxItem` occurrences from `agent/inbox/*` and broadcasts authoritative `session/queue` snapshots on every queued change and reconnect; pending steering stays outside this Web projection. `session.updateQueue` addresses one `InboxItemId`: edit replaces pending content and remove discards it. A driver claim wins races by retiring the address before admission; a later operation returns `queue-item-not-found`. The operation queries only an attached Agent and never resumes a cold session because process-local inbox identities do not survive restart or disposal. The client never infers retirement from turn or status events. diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md index 47af18f763..57d2604ded 100644 --- a/packages/host/apiproxy/README.zh.md +++ b/packages/host/apiproxy/README.zh.md @@ -18,7 +18,7 @@ `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。 -会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。 +会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。 待处理的 queued 输入属于实时控制平面契约，而非会话历史。网关镜像来自 `agent/inbox/*` 的 queued `InboxItem` 入队项，并在每次 queued 变更和重连时广播权威的 `session/queue` 快照；待处理 steering（中途引导）不进入此 Web 投影。`session.updateQueue` 通过 `InboxItemId` 寻址单个项：编辑会替换待处理内容，移除会将其丢弃。驱动器在接纳前退役寻址标识，因此认领会赢得竞态；之后的操作返回 `queue-item-not-found`。该操作只查询当前已挂载的 Agent，绝不恢复冷会话，因为进程本地 inbox 标识无法在重启或资源释放后存活。客户端绝不根据轮次或状态事件推断项已退役。 diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index e224608c72..018f1ea053 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -126,30 +126,19 @@ function ok(request: RpcRequest, value: T): RpcResponse { /** * Build the provider/model catalog over every registered route. Shared by the - * session-scoped `session.models` (which passes the session's current target - * so an unlisted current model still renders selectable) and the host-scoped - * `llm.models` (no current). Per-provider failures ride `failures` without - * failing the sound groups; groups that advertise nothing are dropped. + * session-scoped `session.models` and host-scoped `llm.models`. Catalog + * membership stays advisory: an unlisted session target remains valid for + * provider dispatch, but is not injected back into the selector after its + * owning catalog stops advertising it. Per-provider failures ride `failures` + * without failing the sound groups; groups that advertise nothing are dropped. */ -async function buildModelCatalog( - ctx: Context, - current?: { provider: string; model: string }, -): Promise<{ groups: ModelProviderGroup[]; failures: ModelCatalogFailure[] }> { +async function buildModelCatalog(ctx: Context): Promise<{ + groups: ModelProviderGroup[] + failures: ModelCatalogFailure[] +}> { const catalog = await Promise.all(ctx.llm.listProviders().map(async (provider) => { try { - const advertised = await ctx.llm.listModels(provider.id) - const models = [...advertised] - if ( - current !== undefined - && provider.id === current.provider - && !models.some(model => model.id === current.model) - ) { - models.push({ - provider: provider.id, - id: current.model, - name: current.model, - }) - } + const models = await ctx.llm.listModels(provider.id) const entries = await Promise.all(models.map(async (model) => { const resolved = await ctx.llm.resolveModelInfo(provider.id, model.id) const reasoning: ModelReasoning | undefined = resolved.reasoning === undefined @@ -170,12 +159,6 @@ async function buildModelCatalog( id: model.id, name: model.name, ...model.description === undefined ? {} : { description: model.description }, - ...current !== undefined - && provider.id === current.provider - && model.id === current.model - && !advertised.some(candidate => candidate.id === current.model) - ? { unlisted: true as const } - : {}, ...reasoning === undefined ? {} : { reasoning }, } })) @@ -1394,7 +1377,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro const found = await agentFor(sessionId) if ('error' in found) return err(request, found.error) const current = targetFor(found.agent).current - const { groups, failures } = await buildModelCatalog(ctx, current) + const { groups, failures } = await buildModelCatalog(ctx) return ok(request, { current: { ...current }, groups, failures }) }, diff --git a/packages/host/apiproxy/src/api/llm.ts b/packages/host/apiproxy/src/api/llm.ts index 59a21cf12a..a62319fd62 100644 --- a/packages/host/apiproxy/src/api/llm.ts +++ b/packages/host/apiproxy/src/api/llm.ts @@ -3,8 +3,8 @@ * surfaces. `llm.providers` merges the configurable-provider directory * (which providers CAN be configured, and where their settings live) with the * live route registry; `llm.models` is the session-independent model catalog - * (`session.models` minus the per-session current/unlisted logic). Both - * invalidate on the `host/models-changed` frame. + * (the same groups as `session.models`, without the per-session current + * target). Both invalidate on the `host/models-changed` frame. */ import type { RpcRequest, RpcResponse } from './rpc.ts' diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts index bb044d4428..5189a6a9ec 100644 --- a/packages/host/apiproxy/src/api/sessions.schema.ts +++ b/packages/host/apiproxy/src/api/sessions.schema.ts @@ -164,7 +164,6 @@ export const modelCatalogModelSchema = z.object({ id: z.string().min(1), name: z.string().min(1), description: z.string().optional(), - unlisted: z.literal(true).optional(), reasoning: modelReasoningSchema.optional(), }) satisfies z.ZodType> diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts index e6f93c0dae..0372fe3283 100644 --- a/packages/host/apiproxy/src/api/sessions.ts +++ b/packages/host/apiproxy/src/api/sessions.ts @@ -89,8 +89,6 @@ export interface ModelCatalogModel { name: string /** Optional provider-supplied description. */ description?: string - /** The current model was inserted because the advisory catalog omitted it. */ - unlisted?: true /** Exact-route reasoning metadata when the adapter exposes it. */ reasoning?: ModelReasoning } diff --git a/packages/host/apiproxy/tests/api-proxy-models.spec.ts b/packages/host/apiproxy/tests/api-proxy-models.spec.ts index 5197d96436..2a4754f144 100644 --- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts @@ -1,7 +1,8 @@ /** * Web session model-directory and selection behavior: dynamic provider grouping, - * provider-local catalog failures, logged-target restoration, advisory unlisted - * models, and the prompt-assembly boundary for a running selection change. + * provider-local catalog failures, logged-target restoration without stale + * catalog injection, advisory pass-through models, and the prompt-assembly + * boundary for a running selection change. */ import { describe, expect, it } from 'vitest' @@ -118,7 +119,7 @@ function expectValue(response: { result: { ok: true; value: T } | { ok: false } describe('Web session model selection', () => { - it('groups successful providers, isolates failures, and preserves an unlisted current model', async () => { + it('groups successful providers and leaves an unlisted current target out of the catalog', async () => { const { ctx, sessionId } = await harness({ provider: 'deepseek-official', model: 'private-preview', @@ -143,12 +144,6 @@ describe('Web session model selection', () => { description: 'Reasoning model', reasoning: REASONING, }, - { - id: 'private-preview', - name: 'private-preview', - unlisted: true, - reasoning: REASONING, - }, ], }]) expect(catalog.failures).toEqual([ diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts index aa9c46d9ae..fa6b5abe8c 100644 --- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts +++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts @@ -203,7 +203,6 @@ describe('sessions domain schemas', () => { id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash', description: 'fast', - unlisted: true, reasoning: { efforts: [ { id: 'off', name: 'Off' }, From 12a48558f22e70161b4c56be148a6ca217cf15df Mon Sep 17 00:00:00 2001 From: _Kerman Date: Fri, 31 Jul 2026 14:23:01 +0800 Subject: [PATCH 041/689] fix(agent-loop): stop driver after cancellation --- packages/core/agent-loop/src/agent.ts | 20 ++-- packages/core/agent-loop/tests/cancel.spec.ts | 112 +++++++++++++----- .../tests/contract-regressions.spec.ts | 31 +++-- .../core/agent-loop/tests/tool-calls.spec.ts | 24 +++- 4 files changed, 133 insertions(+), 54 deletions(-) diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 5eb29db8f6..aab8e2610b 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -150,7 +150,7 @@ export class ReactLoopAgent implements Agent { try { while (await this.turn()) {} } catch (_error) { - // Admission and turn boundaries report before rethrowing; the driver only contains the rejection. + // Reported failures and cancellation are contained at the driver boundary. } finally { if (this.phase.kind === 'running') { this.setPhase({ kind: 'idle', lastTurn: this.phase.turn }) @@ -190,15 +190,14 @@ export class ReactLoopAgent implements Agent { const lastTurn = this.phase.kind === 'collecting' ? this.phase.lastTurn : this.phase.turn const phase = { kind: 'running' as const, abort, turn: lastTurn, step: 0 } this.setPhase(phase) - if (signal.aborted) return this.inbox.hasPending + signal.throwIfAborted() let admission: Admission try { admission = await this.admit(true) if (admission.kind !== 'admitted') return false signal.throwIfAborted() } catch (error: unknown) { - // oxlint-disable-next-line typescript/no-unnecessary-condition -- cancel may abort while admission awaits - if (signal.aborted) return this.inbox.hasPending + if (signal.aborted) throw error this.throwError(error) } const turn = ++phase.turn @@ -237,16 +236,15 @@ export class ReactLoopAgent implements Agent { if (admission.kind === 'empty' && turnEnds) break } } catch (error: unknown) { - // oxlint-disable-next-line typescript/no-unnecessary-condition -- cancel may abort during any awaited turn operation if (signal.aborted) { turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } - } else { - turnEnds = { - kind: 'error', - error: error instanceof LlmError ? error.failure : errorChain(error), - } - this.throwError(error) + throw error } + turnEnds = { + kind: 'error', + error: error instanceof LlmError ? error.failure : errorChain(error), + } + this.throwError(error) } finally { try { // oxlint-disable-next-line typescript/no-non-null-assertion -- every exit assigns a turn ending diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index e86d1f9636..4461ec9cb7 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -73,7 +73,7 @@ describe('Agent.cancel()', () => { }) it('cancel({ keepInbox: true }) preserves queued work and emits no discard', async () => { - const adapter = new MockAdapter([textResponse('reply')]) + const adapter = new MockAdapter([textResponse('preserved reply'), textResponse('wake reply')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -85,11 +85,43 @@ describe('Agent.cancel()', () => { agent.cancel({ kind: 'user' }, { keepInbox: true }) expect(agent.session.events.some(event => event.type === 'agent/inbox/spliced' && event.data.outcome === 'canceled')).toBe(false) + await agent.whenIdle() + expect(agent.inbox.nextTurn).toHaveLength(1) + expect(userTexts(agent)).toEqual([]) + expect(adapter.requests).toHaveLength(0) // The preserved item still runs once a later follow-up wakes the driver. + const idle = waitForIdle(ctx, agent) send(agent, 'wake it') - await waitForIdle(ctx, agent) + await idle expect(userTexts(agent)).toEqual(['preserved', 'wake it']) + expect(adapter.requests).toHaveLength(2) + }) + + it('cancel({ keepInbox: true }) parks queued work after an active turn aborts', async () => { + const adapter = new MockAdapter([ + 'hang', + textResponse('preserved reply'), + textResponse('wake reply'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(SessionId('keep-after-abort'), { provider: 'mock', model: 'mock' }) + + send(agent, 'active') + await new Promise(resolve => setTimeout(resolve, 30)) + send(agent, 'preserved') + agent.cancel({ kind: 'user' }, { keepInbox: true }) + await agent.whenIdle() + + expect(userTexts(agent)).toEqual(['active']) + expect(agent.inbox.nextTurn).toHaveLength(1) + expect(adapter.requests).toHaveLength(1) + + const idle = waitForIdle(ctx, agent) + send(agent, 'wake it') + await idle + expect(userTexts(agent)).toEqual(['active', 'preserved', 'wake it']) + expect(adapter.requests).toHaveLength(3) }) it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => { @@ -195,8 +227,12 @@ describe('Agent.cancel()', () => { expect(userTexts(agent)).toEqual(['first', 'later']) }) - it('replacement work queued after idle-listener cancellation still runs', async () => { - const adapter = new MockAdapter([textResponse('first reply'), textResponse('replacement reply')]) + it('replacement work queued after idle-listener cancellation waits for another wakeup', async () => { + const adapter = new MockAdapter([ + textResponse('first reply'), + textResponse('replacement reply'), + textResponse('wake reply'), + ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('idle-listener-post-cancel-send'), { provider: 'mock', model: 'mock' }) @@ -216,8 +252,15 @@ describe('Agent.cancel()', () => { if (replacementIdle === undefined) throw new Error('idle listener did not register replacement work') await replacementIdle - expect(adapter.requests).toHaveLength(2) - expect(userTexts(agent)).toEqual(['first', 'surviving replacement']) + expect(adapter.requests).toHaveLength(1) + expect(userTexts(agent)).toEqual(['first']) + expect(agent.inbox.nextTurn).toHaveLength(1) + + const idle = waitForIdle(ctx, agent) + send(agent, 'wake it') + await idle + expect(adapter.requests).toHaveLength(3) + expect(userTexts(agent)).toEqual(['first', 'surviving replacement', 'wake it']) }) it('cancel() mid-step aborts the active turn and drops every queued tail item', async () => { @@ -462,8 +505,7 @@ describe('Agent.cancel()', () => { expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false) }) - it('window 2: whenIdle() does NOT resolve early when a running listener cancels then queues replacement work', async () => { - // Cancellation must not settle idle while replacement work remains queued. + it('a running-listener cancellation parks replacement work until another wakeup', async () => { const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -481,16 +523,17 @@ describe('Agent.cancel()', () => { await idle dispose() - // whenIdle() resolved only AFTER B's turn ran: B's user message + a turn/end - // are in the log, and A was dropped. - expect(userTexts(agent)).toContain('B') - expect(userTexts(agent)).not.toContain('A') - expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(true) + expect(userTexts(agent)).toEqual([]) + expect(agent.inbox.nextTurn).toHaveLength(1) + + const replacementIdle = waitForIdle(ctx, agent) + send(agent, 'C') + await replacementIdle + expect(userTexts(agent)).toEqual(['B', 'C']) + expect(agent.session.events.filter(event => event.type === 'turn/end')).toHaveLength(2) }) - it('whenIdle() does NOT resolve early when a new prompt is queued during a pre-step cancel', async () => { - // The subtle race: a whenIdle() waiter is registered for prompt A; cancel() clears A; - // prompt B is queued before the loop resumes from the idle wait. + it('a prompt queued during pre-step cancellation waits for another wakeup', async () => { const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) @@ -500,13 +543,15 @@ describe('Agent.cancel()', () => { agent.cancel({ kind: 'user' }) // arms marker, clears A send(agent, 'B') // B races in before the loop resumes - // whenIdle() must resolve only after B's turn fully ran — by which point B's user message - // and a turn/end are in the log. await idle - expect(userTexts(agent)).toContain('B') - expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(true) - // A was dropped (never ran); only B's turn is recorded. - expect(userTexts(agent)).not.toContain('A') + expect(userTexts(agent)).toEqual([]) + expect(agent.inbox.nextTurn).toHaveLength(1) + + const replacementIdle = waitForIdle(ctx, agent) + send(agent, 'C') + await replacementIdle + expect(userTexts(agent)).toEqual(['B', 'C']) + expect(agent.session.events.filter(event => event.type === 'turn/end')).toHaveLength(2) }) it("cancel clears the turn's steering — it is not re-enqueued as a fresh turn", async () => { @@ -537,8 +582,12 @@ describe('Agent.cancel()', () => { expect(flat).not.toContain('steer text') }) - it('keeps replacement work queued synchronously by an abort observer', async () => { - const adapter = new MockAdapter(['hang', textResponse('replacement reply')]) + it('parks replacement work queued synchronously by an abort observer', async () => { + const adapter = new MockAdapter([ + 'hang', + textResponse('replacement reply'), + textResponse('wake reply'), + ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('abort-observer-replacement'), { provider: 'mock', model: 'mock' }) @@ -547,7 +596,7 @@ describe('Agent.cancel()', () => { const signal = adapter.requests[0]?.signal if (signal === undefined) throw new Error('model request omitted its turn signal') signal.addEventListener('abort', () => { send(agent, 'replacement') }, { once: true }) - const idle = waitForIdle(ctx, agent) + const idle = agent.whenIdle() agent.cancel({ kind: 'user' }) await Promise.race([ idle, @@ -563,12 +612,19 @@ describe('Agent.cancel()', () => { }), ]) - expect(adapter.requests).toHaveLength(2) - expect(userTexts(agent)).toEqual(['original', 'replacement']) + expect(adapter.requests).toHaveLength(1) + expect(userTexts(agent)).toEqual(['original']) + expect(agent.inbox.nextTurn).toHaveLength(1) const reasons = agent.session.events .filter(event => event.type === 'turn/end') .map(event => event.type === 'turn/end' ? event.data.reason : undefined) - expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }]) + expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }]) + + const replacementIdle = waitForIdle(ctx, agent) + send(agent, 'wake it') + await replacementIdle + expect(adapter.requests).toHaveLength(3) + expect(userTexts(agent)).toEqual(['original', 'replacement', 'wake it']) }) it('keeps the first typed cause for an active turn', async () => { diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index acfd5b7184..76bee1dd5b 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -128,8 +128,11 @@ describe('assistant replay provenance', () => { }) describe('abort during tool execution ends the turn', () => { - it('records context finalized after a tool-step abort in the next turn', async () => { - const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})]) + it('parks context finalized after a tool-step abort until another wakeup', async () => { + const adapter = new MockAdapter([ + toolCallResponse('c1', 'aborter', {}), + textResponse('after wake'), + ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' }) ctx.tools.register(defineContentToolFixture({ @@ -153,14 +156,20 @@ describe('abort during tool execution ends the turn', () => { send(agent, 'go') await waitForIdle(ctx, agent) - const events = [...agent.session.events] - expect(events + expect(agent.session.events .filter(event => event.type === 'tool/result' || (event.type === 'user/message' && event.data.source.kind === 'plugin') || event.type === 'step/end' || event.type === 'turn/end') .map(event => event.type)) - .toEqual(['tool/result', 'step/end', 'turn/end', 'user/message', 'step/end', 'turn/end']) - expect(events + .toEqual(['tool/result', 'step/end', 'turn/end']) + expect(agent.inbox.nextStep.map(inboxText)) + .toEqual(['accepted result context after abort']) + + const idle = waitForIdle(ctx, agent) + send(agent, 'wake') + await idle + + expect(agent.session.events .flatMap(event => event.type === 'user/message' && event.data.source.kind === 'plugin' ? [event.data.content] : [])) @@ -224,7 +233,7 @@ describe('abort during tool execution ends the turn', () => { .toBeUndefined() }) - it('records result context finalized after disposal cancellation', async () => { + it('parks result context finalized after disposal cancellation without opening another turn', async () => { const adapter = new MockAdapter([toolCallResponse('c1', 'waiter', {})]) const ctx = await harness(adapter) const started = Promise.withResolvers() @@ -264,9 +273,11 @@ describe('abort during tool execution ends the turn', () => { .flatMap(event => event.type === 'user/message' && event.data.source.kind === 'plugin' ? [event.data.content] : [])) - .toEqual([ - [{ type: 'text', text: 'accepted result context during disposal' }], - ]) + .toEqual([]) + expect(agent.inbox.nextStep.map(inboxText)) + .toEqual(['accepted result context during disposal']) + expect(agent.session.events.filter(event => event.type === 'turn/start')) + .toHaveLength(1) expect(agent.session.events.find(event => event.type === 'turn/end')?.data.reason) .toEqual({ kind: 'aborted', reason: { kind: 'disposed' } }) }) diff --git a/packages/core/agent-loop/tests/tool-calls.spec.ts b/packages/core/agent-loop/tests/tool-calls.spec.ts index 98ac46270f..7393122109 100644 --- a/packages/core/agent-loop/tests/tool-calls.spec.ts +++ b/packages/core/agent-loop/tests/tool-calls.spec.ts @@ -518,10 +518,10 @@ describe('tool-call scheduler: abort handling', () => { ]) }) - it('stops replenishing after abort, commits started results, and drains accepted additional contexts', async () => { + it('stops replenishing after abort, commits started results, and parks accepted additional contexts', async () => { const adapter = new MockAdapter([ multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))), - textResponse('should never be requested'), + textResponse('after wake'), ]) const ctx = await harness(adapter, 2) const gated = gatedParallelTool('p') @@ -566,9 +566,23 @@ describe('tool-call scheduler: abort handling', () => { const settled = events(agent).filter(e => e.type === 'tool/result' || (e.type === 'user/message' && e.data.source.kind === 'plugin')) expect(settled.map(e => e.type)) - .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result', 'user/message', 'user/message']) - expect(settled.filter(e => e.type === 'user/message') - .map(e => (e.data.content[0] as { text: string }).text)) + .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result']) + expect(agent.inbox.nextStep.map(message => message.content[0])) + .toEqual([ + { type: 'text', text: 'ctx-c1' }, + { type: 'text', text: 'ctx-c2' }, + ]) + + const idle = waitForIdle(ctx, agent) + agent.followup(createUserMessage({ content: [{ type: 'text', text: 'wake' }], source: { kind: 'user' } })) + await idle + + expect(events(agent).flatMap(e => + e.type === 'user/message' + && e.data.source.kind === 'plugin' + && e.data.content[0]?.type === 'text' + ? [e.data.content[0].text] + : [])) .toEqual(['ctx-c1', 'ctx-c2']) }) From c2ff9ddec89c7f89f52532001f3f97da5843728c Mon Sep 17 00:00:00 2001 From: _Kerman Date: Fri, 31 Jul 2026 14:35:58 +0800 Subject: [PATCH 042/689] fix(agent-loop): scope blocked admission cleanup --- docs/core-data-structures/core.md | 9 +- docs/core-data-structures/core.zh.md | 9 +- packages/acp/acp/tests/turns.spec.ts | 8 +- packages/core/agent-loop/README.md | 2 +- packages/core/agent-loop/README.zh.md | 2 +- packages/core/agent-loop/src/agent.ts | 6 +- .../agent-loop/tests/interception.spec.ts | 113 ++++++++++++++---- packages/core/agent/README.md | 2 +- packages/core/agent/README.zh.md | 2 +- packages/core/agent/src/types.ts | 7 +- packages/examples/cli-demo/tests/cli.spec.ts | 8 +- packages/goal/goal-session/src/index.ts | 4 +- .../goal-session/tests/goal-session.spec.ts | 13 +- packages/hooks/hooks-claude/src/index.ts | 6 +- .../hooks-claude/tests/coverage-cases.ts | 6 +- packages/hooks/hooks-codex/src/index.ts | 8 +- .../hooks/hooks-codex/tests/coverage-cases.ts | 6 +- packages/ui/tui/tests/tui.spec.ts | 2 +- 18 files changed, 162 insertions(+), 51 deletions(-) diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 1a0f6d0cc7..85bf93c42b 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -595,17 +595,18 @@ Prompt decisions use the same identified `UserMessage` shape as durable user-rol Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) -`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow supplies the complete admitted batch; block rejects admission without creating turn events and may leave the claimed messages pending: +`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow supplies the complete admitted batch; block rejects admission without creating turn events and must choose whether to discard the claimed messages. Messages not claimed by that admission remain pending: ```ts type-equiv /** * Prompt interception result. An allowed batch replaces the submitted - * messages. A listener wrapping `next()` preserves the returned batch unless - * it intentionally replaces it. + * messages; a listener wrapping `next()` preserves that batch unless it + * intentionally replaces it. A blocked batch explicitly chooses whether to + * discard the claimed messages; unclaimed work remains pending. */ type PromptDecision = | { kind: 'allow'; messages: UserMessage[] } - | { kind: 'block'; reason: string; keepInbox?: boolean } + | { kind: 'block'; reason: string; discardClaimed: boolean } ``` `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal. diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 28d1b57f48..0453d62a0b 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -603,17 +603,18 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) -`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 提供完整的准入批次；block 拒绝准入且不产生任何轮次事件，并可以让已领取的消息保持待处理： +`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 提供完整的准入批次；block 拒绝准入且不产生任何轮次事件，并且必须选择是否丢弃已领取的消息。未被此次接纳领取的消息会继续保持待处理： ```ts type-equiv /** * Prompt interception result. An allowed batch replaces the submitted - * messages. A listener wrapping `next()` preserves the returned batch unless - * it intentionally replaces it. + * messages; a listener wrapping `next()` preserves that batch unless it + * intentionally replaces it. A blocked batch explicitly chooses whether to + * discard the claimed messages; unclaimed work remains pending. */ type PromptDecision = | { kind: 'allow'; messages: UserMessage[] } - | { kind: 'block'; reason: string; keepInbox?: boolean } + | { kind: 'block'; reason: string; discardClaimed: boolean } ``` `agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。 diff --git a/packages/acp/acp/tests/turns.spec.ts b/packages/acp/acp/tests/turns.spec.ts index 65305ba672..9aa8acb76e 100644 --- a/packages/acp/acp/tests/turns.spec.ts +++ b/packages/acp/acp/tests/turns.spec.ts @@ -214,7 +214,11 @@ describe('ACP prompt lifecycle', () => { it('an admission-blocked prompt settles instead of hanging', async () => { harness = await makeBridgeHarness({ script: [] }) - harness.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy said no' })) + harness.ctx.on('agent/prompt-submit', async () => ({ + kind: 'block' as const, + reason: 'policy said no', + discardClaimed: true, + })) const sessionId = await newSession(harness) await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })) .resolves.toEqual({ stopReason: 'end_turn' }) @@ -227,7 +231,7 @@ describe('ACP prompt lifecycle', () => { harness.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'defer forever', - keepInbox: true, + discardClaimed: false, })) const sessionId = await newSession(harness) const agent = harness.ctx.agents.get(SessionId(sessionId))! diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index 8dee1ed49f..39622bc584 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -55,7 +55,7 @@ Configured agents start automatically. A model call requires both `provider` and The concrete `ReactLoopAgent`, its queued input, outbox, and run controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy. -The unified `send()` primitive routes content and source by (`target` × `wakeup`); `followup`/`steer`/`inject` are its fixed-preset aliases. A `next-turn` item joins the queued FIFO, waking the driver unless `wakeup: false`; admission happens before any turn opens. The loop opens a private next-step acceptance window before `agent/prompt-submit` and closes it before `turn/end`. During that window, `steer()` and `inject()` stage in one outbox; an allowed admission opens the turn, records the prompt and returned `additionalContexts`, then drains the staged input before the first request. A blocked or failed admission writes no prompt or hook-produced context. A caller-staged context-only batch then takes idle injection's immediate append, while steering and context staged beside it remain pending for retry or a later admitted prompt. Outside the window, steering becomes a waking queued prompt and injection immediately appends `user/message` without opening a turn or running the model. +The unified `send()` primitive routes content and source by (`target` × `wakeup`); `followup`/`steer`/`inject` are its fixed-preset aliases. A `next-turn` item joins the queued FIFO, waking the driver unless `wakeup: false`; admission happens before any turn opens. The loop opens a private next-step acceptance window before `agent/prompt-submit` and closes it before `turn/end`. During that window, `steer()` and `inject()` stage in one outbox; an allowed admission opens the turn, records the prompt and returned `additionalContexts`, then drains the staged input before the first request. A blocked or failed admission writes no prompt or hook-produced context. A block's mandatory `discardClaimed` controls only its submitted batch; later next-step input and queued prompts remain pending for a later admitted prompt. Outside the window, steering becomes a waking queued prompt and injection immediately appends `user/message` without opening a turn or running the model. Every FIFO acceptance mints an `InboxItemId` and publishes `agent/inbox/enqueue` with the complete occurrence. `updateInbox()` owns the synchronous queued-item boundary: edit freezes replacement content without changing message identity or position, while remove publishes discard. Edit publishes `agent/inbox/update`; steering and claimed occurrences return `not-found`. Claim publishes `agent/inbox/dequeue` and irrevocably removes the live address before prompt admission, so a racing update cannot rewrite durable history; `cancel()` without `keepInbox` publishes `agent/inbox/discard`. diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md index 5d69c5c28f..232b15d91f 100644 --- a/packages/core/agent-loop/README.zh.md +++ b/packages/core/agent-loop/README.zh.md @@ -55,7 +55,7 @@ interface Config { 实体 `ReactLoopAgent`、其排队输入、outbox 与运行控制均为包内部实现。包根只导出插件／服务／配置契约，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个实体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。 -统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`next-turn` 项加入排队 FIFO，除非 `wakeup: false`，否则会唤醒驱动器；接纳发生在任何轮次开启之前。循环在 `agent/prompt-submit` 之前打开一个私有的 next-step 接收窗口，并在 `turn/end` 之前关闭它。在该窗口内，`steer()` 与 `inject()` 会暂存到同一个 outbox；接纳获准后会开启轮次，记录提示词及其返回的 `additionalContexts`，再于首次请求前排空暂存输入。接纳被阻止或失败时，不会写入提示词或钩子生成的上下文。之后，仅含调用方暂存上下文的批次会采用空闲注入的立即追加行为，而 steering（中途引导）及与其一同暂存的上下文则继续待处理，以供重试或之后获准的提示词使用。窗口之外，steering 会成为唤醒驱动器的排队提示词，而注入会立即追加 `user/message`，不开启轮次也不运行模型。 +统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`next-turn` 项加入排队 FIFO，除非 `wakeup: false`，否则会唤醒驱动器；接纳发生在任何轮次开启之前。循环在 `agent/prompt-submit` 之前打开一个私有的 next-step 接收窗口，并在 `turn/end` 之前关闭它。在该窗口内，`steer()` 与 `inject()` 会暂存到同一个 outbox；接纳获准后会开启轮次，记录提示词及其返回的 `additionalContexts`，再于首次请求前排空暂存输入。接纳被阻止或失败时，不会写入提示词或钩子生成的上下文。block 必须通过 `discardClaimed` 选择是否丢弃本次提交的批次；之后到达的 next-step 输入和排队提示词会继续保持待处理，等待后续获准的提示词。窗口之外，steering 会成为唤醒驱动器的排队提示词，而注入会立即追加 `user/message`，不开启轮次也不运行模型。 每次 FIFO 接受项时都会铸造一个 `InboxItemId`，并通过 `agent/inbox/enqueue` 发布完整的单次入队项。`updateInbox()` 持有同步 queued 项边界：编辑会冻结替换内容，但不改变消息标识或位置；移除会发布 discard。编辑会发布 `agent/inbox/update`；steering 项和已被认领的项会返回 `not-found`。认领操作会发布 `agent/inbox/dequeue`，并在提示词接纳前不可逆地移除实时寻址标识，因此竞态中的更新无法改写持久历史；`cancel()` 在不带 `keepInbox` 时会发布 `agent/inbox/discard`。 diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index aab8e2610b..ee096cd75c 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -176,7 +176,11 @@ export class ReactLoopAgent implements Agent { if (queued !== undefined) this.inbox.splice('next-turn', 0, 1, [], 'admitted') return { kind: 'admitted', messages: decision.messages } } - this.cancel({ kind: 'hook', reason: decision.reason }, { keepInbox: decision.keepInbox }) + if (decision.discardClaimed) { + this.inbox.splice('next-step', 0, outboxLength, [], 'canceled') + if (queued !== undefined) this.inbox.splice('next-turn', 0, 1, [], 'canceled') + } + this.cancel({ kind: 'hook', reason: decision.reason }, { keepInbox: true }) return { kind: 'blocked' } } diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index 6998ccb7f4..c37779e8fb 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -212,7 +212,7 @@ describe('agent/prompt-submit', () => { const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) ctx.on('agent/prompt-submit', async (): Promise => - ({ kind: 'block', reason: 'blocked by policy' })) + ({ kind: 'block', reason: 'blocked by policy', discardClaimed: true })) const reasons: TurnEndReason[] = [] ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) }) @@ -230,6 +230,26 @@ describe('agent/prompt-submit', () => { expect(reasons).toEqual([]) }) + it('block can retain the claimed prompt without opening a turn', async () => { + const adapter = new MockAdapter([]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(SessionId('retained-claim'), { provider: 'mock', model: 'mock' }) + + ctx.on('agent/prompt-submit', async (): Promise => ({ + kind: 'block', + reason: 'try later', + discardClaimed: false, + })) + + send(agent, 'retained') + await agent.whenIdle() + + expect(agent.inbox.nextTurn.map(message => message.content[0])) + .toEqual([{ type: 'text', text: 'retained' }]) + expect(events(agent).some(event => event.type === 'turn/start')).toBe(false) + expect(adapter.requests).toEqual([]) + }) + it('stages inject and steer during admission for the admitted turn', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) @@ -291,7 +311,7 @@ describe('agent/prompt-submit', () => { expect(nextRequest).toContain('admission steering') }) - it('cancels admission-time input when admission is blocked', async () => { + it('preserves input staged after the blocked batch was claimed', async () => { const adapter = new MockAdapter([textResponse('retried')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('blocked-admission-outbox'), { provider: 'mock', model: 'mock' }) @@ -310,10 +330,14 @@ describe('agent/prompt-submit', () => { source: { kind: 'plugin', plugin: 'test' }, })) agent.steer(createUserMessage({ content: [{ type: 'text', text: 'staged steering' }], source: { kind: 'user' } })) - decision.resolve({ kind: 'block', reason: 'policy' }) + decision.resolve({ kind: 'block', reason: 'policy', discardClaimed: true }) await blockedIdle - expect(agent.inbox.nextStep).toHaveLength(0) + expect(agent.inbox.nextStep.map(message => message.content[0])) + .toEqual([ + { type: 'text', text: 'staged context' }, + { type: 'text', text: 'staged steering' }, + ]) expect(events(agent).some(event => event.type === 'turn/start')).toBe(false) expect(adapter.requests).toEqual([]) @@ -323,14 +347,21 @@ describe('agent/prompt-submit', () => { const staged = events(agent).filter(event => event.type === 'user/message' || event.type === 'steering/message') - expect(staged.map(event => event.type)).toEqual(['user/message']) + expect(staged.map(event => event.type)).toEqual([ + 'user/message', + 'user/message', + 'user/message', + ]) expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('blocked prompt') - expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('staged context') - expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('staged steering') + expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('staged context') + expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('staged steering') }) - it('cancels later queued work when an admission is blocked', async () => { - const adapter = new MockAdapter([textResponse('continued')]) + it('preserves later queued work when an admission is blocked', async () => { + const adapter = new MockAdapter([ + textResponse('continued'), + textResponse('wake reply'), + ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('rejected-admission-order'), { provider: 'mock', @@ -340,7 +371,7 @@ describe('agent/prompt-submit', () => { const decision = await next() return messages.some(message => message.content.some(block => block.type === 'text' && block.text === 'blocked prompt')) - ? { kind: 'block', reason: 'policy' } + ? { kind: 'block', reason: 'policy', discardClaimed: true } : decision }) ctx.on('agent/prompt-submit', async (subject, messages, _signal, next) => { @@ -364,17 +395,32 @@ describe('agent/prompt-submit', () => { await idle expect(events(agent).some(event => event.type === 'turn/start')).toBe(false) - expect(agent.inbox.hasPending).toBe(false) + expect(agent.inbox.nextStep.map(message => message.content[0])) + .toEqual([ + { type: 'text', text: 'earlier state change' }, + { type: 'text', text: 'earlier steering' }, + ]) + expect(agent.inbox.nextTurn.map(message => message.content[0])) + .toEqual([{ type: 'text', text: 'later prompt' }]) expect(adapter.requests).toEqual([]) + + const resumed = waitForIdle(ctx, agent) + send(agent, 'wake') + await resumed + const request = JSON.stringify(adapter.requests[0]?.messages) + expect(request).toContain('earlier state change') + expect(request).toContain('earlier steering') + expect(request).toContain('later prompt') + expect(request).not.toContain('blocked prompt') }) - it('cancels context-only injection when admission closes without a turn', async () => { - const adapter = new MockAdapter([]) + it('preserves context-only injection staged after admission began', async () => { + const adapter = new MockAdapter([textResponse('continued')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('blocked-admission-context'), { provider: 'mock', model: 'mock' }) const entered = Promise.withResolvers() const decision = Promise.withResolvers() - ctx.on('agent/prompt-submit', async () => { + const disposeBlock = ctx.on('agent/prompt-submit', async () => { entered.resolve(undefined) return decision.promise }) @@ -386,13 +432,21 @@ describe('agent/prompt-submit', () => { content: [{ type: 'text', text: 'independent context' }], source: { kind: 'plugin', plugin: 'test' }, })) - decision.resolve({ kind: 'block', reason: 'policy' }) + decision.resolve({ kind: 'block', reason: 'policy', discardClaimed: true }) await idle const log = events(agent) expect(log.some(event => event.type === 'user/message')).toBe(false) - expect(agent.inbox.hasPending).toBe(false) + expect(agent.inbox.nextStep.map(message => message.content[0])) + .toEqual([{ type: 'text', text: 'independent context' }]) expect(adapter.requests).toEqual([]) + + disposeBlock() + const resumed = waitForIdle(ctx, agent) + send(agent, 'wake') + await resumed + expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('independent context') + expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('blocked prompt') }) it('leaves inbox state unchanged when its durable append fails', async () => { @@ -414,15 +468,20 @@ describe('agent/prompt-submit', () => { expect(agent.status).toBe('idle') }) - it('a blocked prompt cancels adjacent queued prompts', async () => { - const adapter = new MockAdapter([textResponse('ran once')]) + it('a blocked prompt preserves adjacent queued prompts', async () => { + const adapter = new MockAdapter([ + textResponse('safe reply'), + textResponse('wake reply'), + ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next): Promise => { const text = messages.flatMap(message => message.content) .map(b => (b.type === 'text' ? b.text : '')).join('') - return text === 'secret' ? { kind: 'block', reason: 'policy: no secrets' } : next() + return text === 'secret' + ? { kind: 'block', reason: 'policy: no secrets', discardClaimed: true } + : next() }) const reasons: TurnEndReason[] = [] @@ -437,6 +496,14 @@ describe('agent/prompt-submit', () => { expect(adapter.requests).toHaveLength(0) expect(log.filter(e => e.type === 'turn/start')).toHaveLength(0) expect(reasons).toEqual([]) + expect(agent.inbox.nextTurn.map(message => message.content[0])) + .toEqual([{ type: 'text', text: 'safe' }]) + + const resumed = waitForIdle(ctx, agent) + send(agent, 'wake') + await resumed + expect(JSON.stringify(adapter.requests[0]?.messages)).toContain('safe') + expect(JSON.stringify(adapter.requests[0]?.messages)).not.toContain('secret') }) it('a throwing prompt-submit listener reports the driver error and retains adjacent work', async () => { @@ -653,7 +720,13 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se ctx.on('agent/prompt-submit', async (_agent, messages, _signal, next): Promise => { const text = messages.flatMap(message => message.content) .map(b => (b.type === 'text' ? b.text : '')).join('') - if (text.includes('rm -rf')) return { kind: 'block', reason: 'destructive prompt blocked' } + if (text.includes('rm -rf')) { + return { + kind: 'block', + reason: 'destructive prompt blocked', + discardClaimed: true, + } + } return next() }) // 3. PreToolUse: deny a dangerous tool by name. diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index b21ec0dc49..69b1724fdf 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -52,7 +52,7 @@ The lifecycle edges have two important local caveats. `agent/created` runs after Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement. -`PromptDecision.allow.messages` is the complete identified, frozen batch admitted by prompt interception. A listener that wraps a downstream allow preserves that batch unless it intentionally replaces it. +`PromptDecision.allow.messages` is the complete identified, frozen batch admitted by prompt interception. A listener that wraps a downstream allow preserves that batch unless it intentionally replaces it. A block must choose `discardClaimed`; this affects only the submitted batch, while messages not claimed by that admission remain pending. Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md). diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md index 2cf6960310..8517fcfa41 100644 --- a/packages/core/agent/README.zh.md +++ b/packages/core/agent/README.zh.md @@ -52,7 +52,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供， 大多数拦截点都是协作式 waterfall（瀑布式事件）。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。 -`PromptDecision.allow.messages` 是提示词拦截所准入的完整、带标识且冻结的批次。包装下游 allow 的监听器会保留该批次，除非有意替换它。 +`PromptDecision.allow.messages` 是提示词拦截所准入的完整、带标识且冻结的批次。包装下游 allow 的监听器会保留该批次，除非有意替换它。block 必须指定 `discardClaimed`；该字段仅影响本次提交的批次，未被此次接纳认领的消息会继续保持待处理。 轮次和步骤边界以及模型 token 流是持久 `session/event` 事实，而不是镜像的 `agent/*` 通知。消费方从会话事件流读取 `turn/*`、`step/*` 和 `assistant/chunk`；工具策略与结果观测属于 [`dsh-tools`](../tools/README.md) 记录的完整流水线。 diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 456a7f95fe..33f6c9ca26 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -50,12 +50,13 @@ export type AgentStatus = 'idle' | 'running' /** * Prompt interception result. An allowed batch replaces the submitted - * messages. A listener wrapping `next()` preserves the returned batch unless - * it intentionally replaces it. + * messages; a listener wrapping `next()` preserves that batch unless it + * intentionally replaces it. A blocked batch explicitly chooses whether to + * discard the claimed messages; unclaimed work remains pending. */ export type PromptDecision = | { kind: 'allow'; messages: UserMessage[] } - | { kind: 'block'; reason: string; keepInbox?: boolean } + | { kind: 'block'; reason: string; discardClaimed: boolean } /** One failed model-request attempt presented to recovery listeners. */ export interface RequestFailureContext { diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts index ff1916fe42..5c162e0fdd 100644 --- a/packages/examples/cli-demo/tests/cli.spec.ts +++ b/packages/examples/cli-demo/tests/cli.spec.ts @@ -448,14 +448,18 @@ describe('runOneShot and executeCli', () => { it('settles blocked tasks at whole-agent idle without attributing a result', async () => { const blocked = await harness([]) - blocked.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'denied' })) + blocked.ctx.on('agent/prompt-submit', async () => ({ + kind: 'block' as const, + reason: 'denied', + discardClaimed: true, + })) await expect(runOneShot(blocked.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' }) const retained = await harness([]) retained.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'deferred', - keepInbox: true, + discardClaimed: false, })) await expect(runOneShot(retained.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' }) expect(retained.agent.status).toBe('idle') diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts index c65f317657..5a32195213 100644 --- a/packages/goal/goal-session/src/index.ts +++ b/packages/goal/goal-session/src/index.ts @@ -350,7 +350,7 @@ export function apply(ctx: Context): void { cancelReservation(agent, attempt) } requestDrive(state) - return { kind: 'block', reason: STALE_ROUND_REASON, keepInbox: true } + return { kind: 'block', reason: STALE_ROUND_REASON, discardClaimed: false } } let decision: PromptDecision try { @@ -398,7 +398,7 @@ export function apply(ctx: Context): void { cancelReservation(agent, attempt) } requestDrive(state) - return { kind: 'block', reason: STALE_ROUND_REASON, keepInbox: true } + return { kind: 'block', reason: STALE_ROUND_REASON, discardClaimed: false } } return decision }) diff --git a/packages/goal/goal-session/tests/goal-session.spec.ts b/packages/goal/goal-session/tests/goal-session.spec.ts index a0bc6defaf..6226372d13 100644 --- a/packages/goal/goal-session/tests/goal-session.spec.ts +++ b/packages/goal/goal-session/tests/goal-session.spec.ts @@ -238,7 +238,7 @@ describe('same-session goal driving', () => { it('maps a downstream prompt veto to blocked without admitting the round', async () => { const test = await harness([]) test.ctx.on('agent/prompt-submit', (_agent, messages, _signal, next) => messages[0]?.source.kind === 'goal' - ? Promise.resolve({ kind: 'block', reason: 'deployment policy' }) + ? Promise.resolve({ kind: 'block', reason: 'deployment policy', discardClaimed: true }) : next()) test.ctx.goals.create(test.agent, { objective: 'respect policy' }) @@ -253,7 +253,7 @@ describe('same-session goal driving', () => { it('does not reserve again when a stopped-goal observer queues cancel-scoped work', async () => { const test = await harness([textResponse('human follow-up')]) test.ctx.on('agent/prompt-submit', (_agent, messages, _signal, next) => messages[0]?.source.kind === 'goal' - ? Promise.resolve({ kind: 'block', reason: 'stop this round' }) + ? Promise.resolve({ kind: 'block', reason: 'stop this round', discardClaimed: true }) : next()) test.ctx.on('goal/changed', (agent, change) => { if (change.operation === 'block') agent.followup(createUserMessage({ content: [{ type: 'text', text: 'inspect the blocker' }], source: { kind: 'user' } })) @@ -264,7 +264,8 @@ describe('same-session goal driving', () => { await test.agent.whenIdle() expect(test.adapter.requests).toHaveLength(0) - expect(test.agent.inbox.nextTurn).toHaveLength(0) + expect(test.agent.inbox.nextTurn.map(message => message.content[0])) + .toEqual([{ type: 'text', text: 'inspect the blocker' }]) }) it('pauses and drops a reserved round when cancellation lands before admission', async () => { @@ -884,7 +885,11 @@ describe('same-session goal driving', () => { if (messages[0]?.source.kind === 'goal' && !vetoed) { vetoed = true agent.cancel({ kind: 'user' }) - return Promise.resolve({ kind: 'block', reason: 'cancelled by policy' }) + return Promise.resolve({ + kind: 'block', + reason: 'cancelled by policy', + discardClaimed: true, + }) } return next() }) diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts index bd3d979a14..e16c27dac5 100644 --- a/packages/hooks/hooks-claude/src/index.ts +++ b/packages/hooks/hooks-claude/src/index.ts @@ -222,7 +222,11 @@ export function apply(ctx: Context, config: Config): void { const content = messages.flatMap(message => message.content) const merged = await runPoint('UserPromptSubmit', '', promptPayload(ctx, agent, content), { agent, signal }) if (merged.decision === 'deny') { - return { kind: 'block', reason: merged.reason ?? 'blocked by UserPromptSubmit hook' } + return { + kind: 'block', + reason: merged.reason ?? 'blocked by UserPromptSubmit hook', + discardClaimed: true, + } } // Delegate so later listeners may still rewrite or block, then prepend our // context only to a downstream allow decision. diff --git a/packages/hooks/hooks-claude/tests/coverage-cases.ts b/packages/hooks/hooks-claude/tests/coverage-cases.ts index 33e098b4da..b0a0a2a363 100644 --- a/packages/hooks/hooks-claude/tests/coverage-cases.ts +++ b/packages/hooks/hooks-claude/tests/coverage-cases.ts @@ -495,7 +495,11 @@ export function defineCoverageCases(group: CoverageGroup): void { const adapter = new MockAdapter([textResponse('should not run')]) const ctx = await harness(path, adapter) // A later listener that blocks every prompt (registered AFTER the bridge). - ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy veto' })) + ctx.on('agent/prompt-submit', async () => ({ + kind: 'block' as const, + reason: 'policy veto', + discardClaimed: true, + })) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })) await waitForIdle(ctx, agent) diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts index 19d1c43f7d..1aee38fff2 100644 --- a/packages/hooks/hooks-codex/src/index.ts +++ b/packages/hooks/hooks-codex/src/index.ts @@ -209,7 +209,13 @@ export function apply(ctx: Context, config: Config): void { } const merged = await runPoint('UserPromptSubmit', '', payload, { agent, plainStdoutAsContext: true, signal }) /* jscpd:ignore-start */ - if (merged.decision === 'deny') return { kind: 'block', reason: merged.reason ?? 'blocked by UserPromptSubmit hook' } + if (merged.decision === 'deny') { + return { + kind: 'block', + reason: merged.reason ?? 'blocked by UserPromptSubmit hook', + discardClaimed: true, + } + } // Context alone is not a veto: DELEGATE so a later prompt-submit listener can // still block/rewrite, then fold our context onto its decision. const downstream = await next() diff --git a/packages/hooks/hooks-codex/tests/coverage-cases.ts b/packages/hooks/hooks-codex/tests/coverage-cases.ts index 6cd2cd4617..419792ca08 100644 --- a/packages/hooks/hooks-codex/tests/coverage-cases.ts +++ b/packages/hooks/hooks-codex/tests/coverage-cases.ts @@ -109,7 +109,11 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"bridge ctx"}}\'\n') }] }] }) const adapter = new MockAdapter([textResponse('should not run')]) const ctx = await harness(join(d, 'hooks.json'), adapter) - ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy veto' })) + ctx.on('agent/prompt-submit', async () => ({ + kind: 'block' as const, + reason: 'policy veto', + discardClaimed: true, + })) const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' }) agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })); await waitForIdle(ctx, agent) expect(adapter.requests).toHaveLength(0) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 4a09434cda..85616e8243 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -2743,7 +2743,7 @@ describe('pi-tui chat lifecycle and transcript', () => { // must be discarded with it, not stranded for the next prompt. let blockPrompts = true result.ctx.on('agent/prompt-submit', async (_agent, _message, _signal, next) => - blockPrompts ? { kind: 'block' as const, reason: 'policy' } : next()) + blockPrompts ? { kind: 'block' as const, reason: 'policy', discardClaimed: true } : next()) result.terminal.send('@blocked-source') await vi.waitFor(() => { expect(result.terminal.output).toContain('Session · blocked-source') }) From 935578ed9878d5cc8388204c7344cabe181bfaa6 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Fri, 31 Jul 2026 14:36:16 +0800 Subject: [PATCH 043/689] feat(web): accept K and M suffixes in the context window field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The catalog's context window is now a text field that reads a decimal K or M suffix — 1M is 1000K, matching how model capacities are quoted — and stores the plain token count, so settings.yaml and the adapter are unchanged. A stored count reads back in the shortest form that round-trips: 1000000 as 1M, 256000 as 256K, and 131072 written out, because it is not a whole number of thousands. The field holds the typed text while its row has focus, since re-deriving it from the parsed count on every keystroke would rewrite 1000 to 1K mid-word; text that does not parse stays on screen so the save-time rejection names a row the user can still see and correct. --- .../2026-07-30-web-config-plane.i18n.yaml | 4 +- .../2026-07-30-web-config-plane.md | 2 +- .../2026-07-30-web-config-plane.zh.md | 2 +- .../models.expected.md | 10 ++- packages/client/ui-models/README.i18n.yaml | 4 +- packages/client/ui-models/README.md | 2 +- packages/client/ui-models/README.zh.md | 2 +- .../src/client/DeepSeekModelsEditor.tsx | 81 ++++++++++++++--- .../client/ui-models/src/client/locales.ts | 4 +- .../ui-models/tests/components.spec.tsx | 90 ++++++++++++++++++- 10 files changed, 177 insertions(+), 24 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml index 2421df88f6..32137fe409 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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/architecture/2026-07-30-web-config-plane.md -2026-07-30-web-config-plane.md: 0e457b6d712cf9e7e2b005f61b97c580a0f2597e -2026-07-30-web-config-plane.zh.md: 4b2a0bd87040e60bc6602c48482bc936e90011ec +2026-07-30-web-config-plane.md: a4d474d450009b3bcf929eaea870e045602268ac +2026-07-30-web-config-plane.zh.md: db7201408f46a1e68b4359346d1c74b8d728a0d3 diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md index 0e457b6d71..a4d474d450 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md +++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md @@ -18,7 +18,7 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer **The llm seam declares configurability and announces topology.** `registerConfigurableProviders()` is an all-or-nothing, fiber-scoped directory of `{provider, displayName, settingsNs, settingsPath}` — the addressing a config page needs to open the right settings subtree for a route that may not exist yet; `listConfigurableProviders()` merges with live routes in the wire handler so undeclared live routes still report active. The zero-payload `'llm/adapters-updated'` event fires from all four registration/unregistration commit points with contained listener dispatch (INVARIANT rethrow), following the settings/commands precedent. `llm-deepseek`'s route renamed to `deepseek-official` because the pi-ai catalog legitimately owns `deepseek` as an aggregator entry; pre-release stance, no alias. -**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog is one caption strip over a row of `id`/`name`/`contextWindow` fields per model rather than a labelled card each; every field keeps the indexed `aria-label` that names it, and the captions are hidden from assistive tech so that name is not announced twice. +**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog is one caption strip over a row of `id`/`name`/`contextWindow` fields per model rather than a labelled card each; every field keeps the indexed `aria-label` that names it, and the captions are hidden from assistive tech so that name is not announced twice. The context window is a text field reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: the field holds the typed text while the row has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. **The Models page is a three-domain join with seam-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `_API_KEY` when none exists (the pi-ai profile records the derivation), so `settings.yaml` never carries a key value. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized model-provider confirmation dialog; cancellation, its close button, and its mask leave the profile untouched, while the destructive confirmation submits the single unset and blocks duplicate submission until it settles. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md index 4b2a0bd870..db7201408f 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md @@ -18,7 +18,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯 **llm seam 声明可配置性并公布拓扑。**`registerConfigurableProviders()` 是一个全有或全无、以 fiber 为作用域的目录，条目为 `{provider, displayName, settingsNs, settingsPath}`——这正是配置页要为一条可能尚不存在的路由打开正确设置子树时所需要的寻址；`listConfigurableProviders()` 在 wire 处理器里与存活路由合并，未声明的存活路由因此仍报告为激活。零负载的 `'llm/adapters-updated'` 事件从全部四个注册／注销提交点触发，listener 派发带异常隔离（INVARIANT 重抛），沿用 settings/commands 的先例。`llm-deepseek` 的路由重命名为 `deepseek-official`，因为 pi-ai catalog 名正言顺地拥有 `deepseek` 这个聚合器条目；依预发布立场，不设别名。 -**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录是一条列名说明行，其下每个模型占一行 `id`／`name`／`contextWindow` 字段，而不是每个模型各一张带标签的卡片；每个字段都保留那个为其命名的带序号 `aria-label`，列名则对辅助技术隐藏，以免该名称被播报两次。 +**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录是一条列名说明行，其下每个模型占一行 `id`／`name`／`contextWindow` 字段，而不是每个模型各一张带标签的卡片；每个字段都保留那个为其命名的带序号 `aria-label`，列名则对辅助技术隐藏，以免该名称被播报两次。上下文窗口是一个文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：该行持有焦点期间，字段保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。 **Models 页是一次三领域联接，应用语义与 seam 同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `_API_KEY`（pi-ai profile 会记录该派生），因此 `settings.yaml` 从不携带密钥值。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化的模型提供方确认对话框；取消操作、关闭按钮和遮罩均不会改动 profile，而破坏性确认会提交唯一一条 unset，并在其完成前阻止重复提交。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。 diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md index 31b6c7b1b4..4a709fdf5a 100644 --- a/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md +++ b/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md @@ -14,7 +14,7 @@ - paragraph: 填入各提供方的 API 密钥即可使用其模型。 - list: - listitem: - - text: DeepSeek 已启用 + - text: DeepSeek - button "编辑" - text: DeepSeek deepseek-official API 密钥 - textbox "API 密钥": @@ -36,7 +36,9 @@ - textbox "显示名称 1": - /placeholder: 留空时使用模型 ID - text: DeepSeek-V4-Pro - - spinbutton "上下文窗口 1": "1000000" + - textbox "上下文窗口 1": + - /placeholder: 1M + - text: 1M - button "删除模型": - img - text: 删除模型 @@ -44,7 +46,9 @@ - textbox "显示名称 2": - /placeholder: 留空时使用模型 ID - text: Private Preview - - spinbutton "上下文窗口 2": "131072" + - textbox "上下文窗口 2": + - /placeholder: 1M + - text: "131072" - button "删除模型": - img - text: 删除模型 diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml index 8f7f098dfc..7b4f1ef045 100644 --- a/packages/client/ui-models/README.i18n.yaml +++ b/packages/client/ui-models/README.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 packages/client/ui-models/README.md -README.md: 97dd6cca4ba1715dc75211929c47fc6f3e632d78 -README.zh.md: d142e9a94c86a4df3f49ad2ee210e24c267f92e0 +README.md: a1d5233eb47043f86d3ae562419ac9ec22404d60 +README.zh.md: 0a5f3fd97f1d54c91d1305ec7b759c5f2934d961 diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md index 97dd6cca4b..a1d5233eb4 100644 --- a/packages/client/ui-models/README.md +++ b/packages/client/ui-models/README.md @@ -8,7 +8,7 @@ Rows are the *configured* providers (their profile resolves in the owning namesp The first-run overlay projects `deepseek-official` readiness from that same joined snapshot. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference suppresses the prompt, including a read-only launch-environment credential. Only a mounted adapter with a missing writable reference shows the action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the overlay never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability is skipped so onboarding cannot block the rest of the product; the Models page remains the diagnostic surface. -Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. Empty ids, duplicate ids, empty explicit names, and non-positive or fractional context windows fail before any write. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling. +Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A context window is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional context windows fail before any write. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling. ## Model Experience diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md index d142e9a94c..0a5f3fd97f 100644 --- a/packages/client/ui-models/README.zh.md +++ b/packages/client/ui-models/README.zh.md @@ -8,7 +8,7 @@ 首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此不会把同一提供方 ID 下没有相应声明的存活路由视为可通过配置修复。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。只有适配器已挂载、引用可写但尚未配置时，浮层才显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，浮层绝不持有 secret。适配器缺失、路由未激活、联接失败、部署只读、设置能力不可用或凭据能力不可用时均跳过，以免首次使用引导阻塞产品的其他部分；Models 页仍是诊断界面。 -每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。空 ID、重复 ID、显式填写的空名称，以及非正数或非整数的上下文窗口都会在写入前失败。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。 +每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。上下文窗口按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的上下文窗口都会在写入前失败。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。 ## 模型体验 diff --git a/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx b/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx index c79eb57412..d80ab9f741 100644 --- a/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx +++ b/packages/client/ui-models/src/client/DeepSeekModelsEditor.tsx @@ -5,6 +5,7 @@ * override; reset removes that override instead of copying defaults into it. */ +import { useState } from 'react' import type { ReactNode } from 'react' import { IconPlusOutline16, IconTrashOutline16 } from '@deepseek-ai/dsh-client-ui-primitives' import type { en } from './locales.ts' @@ -13,6 +14,47 @@ import styles from './ModelsSection.module.css' /** One catalog entry kept structurally open so hidden or future fields survive an edit. */ export type DeepSeekModelDraft = Record +/** Accepted context-window spellings: a decimal count with an optional K/M suffix. */ +const CONTEXT_WINDOW_PATTERN = /^(\d+(?:\.\d+)?)([km])?$/i + +/** Decimal suffix scales — `1M` is 1000K, matching how model capacities are quoted. */ +const CONTEXT_WINDOW_SCALE = { k: 1_000, m: 1_000_000 } as const + +/** + * Read a typed context window, so a user can write `256K` or `1M` instead of + * counting zeroes. The stored value stays a plain token count. + * @param text - raw field text. + * @returns the count; `undefined` when blank (inherit), `NaN` when unreadable + * (rejected by {@link validateDeepSeekModels} before any write). + */ +export function parseContextWindow(text: string): number | undefined { + const trimmed = text.trim() + if (trimmed.length === 0) return undefined + const match = CONTEXT_WINDOW_PATTERN.exec(trimmed) + if (match === null) return Number.NaN + const suffix = match[2]?.toLowerCase() + const scale = suffix === 'k' || suffix === 'm' ? CONTEXT_WINDOW_SCALE[suffix] : 1 + const scaled = Number(match[1]) * scale + // A decimal multiple is exact in intent but not in binary floating point + // (2.3 * 1e6 lands a few ULPs high), so an integral intent snaps back. + const rounded = Math.round(scaled) + return Math.abs(scaled - rounded) < 1e-6 ? rounded : scaled +} + +/** + * Spell a stored count back in the shortest form that survives a round trip + * through {@link parseContextWindow}; a count that is not a whole number of + * thousands stays written out. + * @param value - stored context window. + * @returns the field text. + */ +export function formatContextWindow(value: number): string { + if (!Number.isInteger(value) || value <= 0) return String(value) + if (value % CONTEXT_WINDOW_SCALE.m === 0) return `${String(value / CONTEXT_WINDOW_SCALE.m)}M` + if (value % CONTEXT_WINDOW_SCALE.k === 0) return `${String(value / CONTEXT_WINDOW_SCALE.k)}K` + return String(value) +} + /** A localized validation failure for one user-owned model array. */ export interface DeepSeekModelsValidationFailure { /** Zero-based model position. */ @@ -81,6 +123,11 @@ export interface DeepSeekModelsEditorProps { * @returns the catalog editor. */ export function DeepSeekModelsEditor(props: DeepSeekModelsEditorProps): ReactNode { + // The context-window field is edited as text, so the keystrokes are held + // here while one row has focus: re-deriving the text from the parsed count + // on every change would rewrite `1000` to `1K` mid-word. + const [editing, setEditing] = useState<{ index: number; text: string } | undefined>(undefined) + const update = (index: number, key: 'id' | 'name' | 'contextWindow', value: unknown): void => { const next = props.models.map((model, at) => { const copy = { ...model } @@ -93,9 +140,27 @@ export function DeepSeekModelsEditor(props: DeepSeekModelsEditorProps): ReactNod } const remove = (index: number): void => { + setEditing(undefined) props.onChange(props.models.filter((_model, at) => at !== index).map(model => ({ ...model }))) } + /** The row's field text: the live keystrokes, else the stored count spelled short. */ + const contextText = (model: DeepSeekModelDraft, index: number): string => { + if (editing?.index === index) return editing.text + const value = model['contextWindow'] + return typeof value === 'number' ? formatContextWindow(value) : '' + } + + const settleContext = (index: number): void => { + setEditing((current) => { + if (current?.index !== index) return current + // Unreadable text stays on screen: the save-time rejection names a row + // the user can still see and correct. + const parsed = parseContextWindow(current.text) + return parsed !== undefined && Number.isNaN(parsed) ? current : undefined + }) + } + return (
@@ -152,22 +217,18 @@ export function DeepSeekModelsEditor(props: DeepSeekModelsEditorProps): ReactNod /> { - update( - index, - 'contextWindow', - event.target.value === '' ? undefined : Number(event.target.value), - ) + setEditing({ index, text: event.target.value }) + update(index, 'contextWindow', parseContextWindow(event.target.value)) }} + onBlur={() => { settleContext(index) }} /> @@ -203,6 +232,12 @@ export function DeepSeekModelsEditor(props: DeepSeekModelsEditorProps): ReactNod aria-label={`${props.t('modelId')} ${String(index + 1)}`} disabled={props.disabled} onChange={(event) => { update(index, 'id', event.target.value) }} + onBlur={(event) => { + // Settle a pasted id rather than trimming per keystroke, + // which would stop the user typing an interior space. + const trimmed = event.target.value.trim() + if (trimmed !== event.target.value) update(index, 'id', trimmed) + }} /> { - setEditing({ index, text: event.target.value }) - update(index, 'contextWindow', parseContextWindow(event.target.value)) + const text = event.target.value + setEditing(current => new Map(current).set(index, text)) + update(index, 'contextWindow', parseContextWindow(text)) }} onBlur={() => { settleContext(index) }} /> diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx index d9ebadd1f3..7346332a2f 100644 --- a/packages/client/ui-models/tests/components.spec.tsx +++ b/packages/client/ui-models/tests/components.spec.tsx @@ -477,6 +477,91 @@ describe('ModelsSection', () => { .toEqual(base === undefined ? ['deepseek-v4-flash', 'deepseek-v4-pro'] : ['pinned-by-deployment']) }) + it('keeps every row\'s unreadable text, not just the last one edited', async () => { + // The regression: one active buffer meant editing a second row displaced + // the first, which then fell back to rendering its stored NaN as `NaN` — + // losing the text the user was told they could still correct. + await mountSection() + fireEvent.click(screen.getByText(en.customized)) + const windows = screen.getAllByLabelText(new RegExp(en.contextWindow)) + fireEvent.change(windows[0] as HTMLInputElement, { target: { value: 'not a number' } }) + fireEvent.blur(windows[0] as HTMLInputElement) + fireEvent.change(windows[1] as HTMLInputElement, { target: { value: '2M' } }) + + expect((windows[0] as HTMLInputElement).value).toBe('not a number') + expect((windows[1] as HTMLInputElement).value).toBe('2M') + }) + + it('re-keys the typed text around a removed row', async () => { + await mountSection() + fireEvent.click(screen.getByText(en.customized)) + const windows = (): HTMLInputElement[] => + screen.getAllByLabelText(new RegExp(en.contextWindow)) + const removeRow = (at: number): void => { + fireEvent.click(screen.getAllByText(en.removeModel)[at] as HTMLElement) + } + // Three rows, with text parked on the outer two. + fireEvent.click(screen.getByText(en.addModel)) + fireEvent.change(windows()[0] as HTMLInputElement, { target: { value: 'top text' } }) + fireEvent.blur(windows()[0] as HTMLInputElement) + fireEvent.change(windows()[2] as HTMLInputElement, { target: { value: 'bottom text' } }) + fireEvent.blur(windows()[2] as HTMLInputElement) + + // Dropping the middle row leaves the row above untouched and carries the + // row below down with its own text, rather than stranding it. + removeRow(1) + expect(windows()).toHaveLength(2) + expect((windows()[0] as HTMLInputElement).value).toBe('top text') + expect((windows()[1] as HTMLInputElement).value).toBe('bottom text') + + // Dropping a row that holds text takes that text with it; the survivor + // keeps its own rather than inheriting the deleted row's. + removeRow(0) + expect(windows()).toHaveLength(1) + expect((windows()[0] as HTMLInputElement).value).toBe('bottom text') + }) + + it('drops the typed text when reset replaces the rows it annotated', async () => { + // The regression: reset removed the override but left the buffer, so an + // inherited row displayed text no settings layer stores — and because an + // unreadable buffer never settles, it stayed there indefinitely. + const { mutate } = await mountSection({ + mutate: vi.fn(() => Promise.resolve(ok(wireNamespaces()[0]))), + }) + fireEvent.click(screen.getByText(en.customized)) + const windows = screen.getAllByLabelText(new RegExp(en.contextWindow)) + fireEvent.change(windows[0] as HTMLInputElement, { target: { value: 'garbage' } }) + fireEvent.blur(windows[0] as HTMLInputElement) + fireEvent.click(screen.getByText(en.resetModels)) + + const restored = screen.getAllByLabelText(new RegExp(en.contextWindow)) + expect((restored[0] as HTMLInputElement).value).toBe('1M') + + // Reset put the draft back where it started, so Apply writes nothing at + // all rather than persisting whatever the stale text had parsed to. + fireEvent.click(screen.getByText(en.apply)) + await waitFor(() => { expect(screen.getByText(en.apply)).toBeTruthy() }) + expect(mutate).not.toHaveBeenCalled() + }) + + it('settles a pasted id and refuses whitespace that would never match', async () => { + await mountSection() + fireEvent.click(screen.getByText(en.customized)) + const ids = screen.getAllByLabelText(new RegExp(en.modelId)) + fireEvent.change(ids[0] as HTMLInputElement, { target: { value: ' deepseek-v4-flash ' } }) + fireEvent.blur(ids[0] as HTMLInputElement) + expect((ids[0] as HTMLInputElement).value).toBe('deepseek-v4-flash') + // A settled id needs no second trim. + fireEvent.blur(ids[0] as HTMLInputElement) + expect((ids[0] as HTMLInputElement).value).toBe('deepseek-v4-flash') + + // An id that is only whitespace is as absent as an empty one, and a padded + // id no longer slips past the duplicate check against its own twin. + expect(validateDeepSeekModels([{ id: ' ' }])).toEqual({ index: 0, key: 'modelIdRequired' }) + expect(validateDeepSeekModels([{ id: 'model' }, { id: 'model ' }])) + .toEqual({ index: 1, key: 'modelIdDuplicate' }) + }) + it('renders malformed draft fallbacks without inventing catalog values', () => { render( Date: Fri, 31 Jul 2026 15:11:02 +0800 Subject: [PATCH 048/689] testing(web): pin the row card against the editor it expands into The previous assertion pinned the literal `bg-layer-3` fill that was just reverted. What matters is the relationship it broke: `bg-layer-3` and `bg-module-platform` both resolve to neutral-bluish-800 under the dark theme, so filling the row with either erases the nested editor's boundary. --- .../client/ui-models/tests/styles.spec.ts | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/packages/client/ui-models/tests/styles.spec.ts b/packages/client/ui-models/tests/styles.spec.ts index 478046454b..9139d01f4e 100644 --- a/packages/client/ui-models/tests/styles.spec.ts +++ b/packages/client/ui-models/tests/styles.spec.ts @@ -4,10 +4,28 @@ import { describe, expect, it } from 'vitest' const css = readFileSync(fileURLToPath(new URL('../src/client/ModelsSection.module.css', import.meta.url)), 'utf8') +/** The declarations of one top-level rule, by selector. */ +function block(selector: string): string { + const match = new RegExp(`^\\${selector} \\{([^}]*)\\}`, 'm').exec(css) + if (match === null) throw new Error(`ModelsSection.module.css has no \`${selector}\` rule`) + return match[1] ?? '' +} + describe('ModelsSection theme styles', () => { it('uses the shared theme tokens without light-only fallbacks', () => { + // The section once named `--border`/`--surface`/`--text-*`/`--accent-strong`, + // which nothing in this app defines, so it rendered the light-mode literals + // written as their fallbacks and stayed light under the dark theme. expect(css).not.toMatch(/var\(--(?:surface|text-|border|accent-strong)/) - expect(css).toContain('background: var(--dsw-alias-bg-layer-3)') expect(css).toContain('color: var(--dsw-alias-label-primary)') }) + + it('separates the row card from the editor it expands into', () => { + // `bg-layer-3` and `bg-module-platform` both resolve to neutral-bluish-800 + // under the dark theme, so filling the row with either erases the nested + // editor's boundary. The row is outlined; the fill is the editor's alone. + expect(block('.editor')).toContain('background: var(--dsw-alias-bg-module-platform)') + expect(block('.rowCard')).toContain('border: 1px solid var(--dsw-alias-border-l2)') + expect(block('.rowCard')).not.toMatch(/\bbackground\s*:/) + }) }) From f12d4f698e53456eb768b507f1e7fdb64b7349b0 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Fri, 31 Jul 2026 15:11:11 +0800 Subject: [PATCH 049/689] doc(web): own the Web/TUI split on an unlisted current model The TUI still renders the unlisted current model as its own row and marks it current; Web shows the unset trigger label and asks for a replacement. The note recorded the Host decision but not that the two surfaces present it differently, which reads as a missed migration rather than a choice. Also records why `trigger.selectAria` and `trigger.fallback` hold identical strings, so a future coalescing cleanup does not merge them. --- .../2026-07-24-web-session-model-selector.i18n.yaml | 4 ++-- .../feature/2026-07-24-web-session-model-selector.md | 2 +- .../2026-07-24-web-session-model-selector.zh.md | 2 +- packages/client/ui-model/src/client/locales.ts | 10 +++++++++- 4 files changed, 13 insertions(+), 5 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml index 898a0142fb..f79f7d9955 100644 --- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.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/feature/2026-07-24-web-session-model-selector.md -2026-07-24-web-session-model-selector.md: ca13bebbb49aec5deabd147ed1c2a8f3b246ca42 -2026-07-24-web-session-model-selector.zh.md: 16c7d773b0eea82bf991bc17c44b26c8e820aba1 +2026-07-24-web-session-model-selector.md: 05e923fb3b5df72485ffb8d6ff5aa0104b19a8a0 +2026-07-24-web-session-model-selector.zh.md: 705b7acaf809597d1ead450e2ff5b86e0f3af049 diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md index ca13bebbb4..05e923fb3b 100644 --- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md +++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md @@ -12,7 +12,7 @@ The Web conversation displayed and sent through the Host's fixed provider/model The Web Host reuses `installAgentLlmTarget` for every created or resumed agent. The provider/model/reasoning target starts from the latest `request/header` when the session has used a model, otherwise from the Host default route. `session.selectModel` changes the session-local mutable target, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed target persists through the existing full `request/header` snapshot, while a choice that has not reached a request remains process-local. -The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. Exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target. +The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently on purpose: the TUI still renders the unlisted current model as its own row and marks it current, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so a target the user just deleted should read as a decision to make rather than a selection to keep; the TUI, which only picks from what exists, has no such edit to reconcile. The cost is real and accepted — a Web composer showing the unset label can still send to the routed target — and the divergence is deliberate, not a missed migration. Exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target. The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete target, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so older responses cannot replace a newer result; connection reset discards the process-local projection before restoring the Host target. Failures retain the previous current target and usable groups. diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md index 16c7d773b0..705b7acaf8 100644 --- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md +++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md @@ -12,7 +12,7 @@ Web 对话原本通过 Host 固定的提供方与模型路由显示并发送消 Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlmTarget`。如果会话已经使用过模型，提供方／模型／推理（reasoning）目标从最新的 `request/header` 开始；否则采用 Host 默认路由。`session.selectModel` 会更改会话级可变目标，提示词组装则将该目标与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一条实际采用的目标通过现有的完整 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。 -会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。精确解析决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。 +会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门有意对这一状态给出不同回答：TUI 仍把未列出的当前模型渲染为独立一行并标记为当前，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 正是编辑目录所在的前门，因此用户刚刚删除的目标应当读作一个有待作出的决定，而不是一项可以保留的选择；TUI 只在已存在的模型中挑选，没有这类编辑需要调和。这一代价真实存在且已被接受——显示未设置标签的 Web composer 仍会发送到实际路由的目标——这一分歧是有意为之，而不是一处遗漏的迁移。精确解析决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。 浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整目标、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 目标。失败时保留先前的当前目标和可用分组。 diff --git a/packages/client/ui-model/src/client/locales.ts b/packages/client/ui-model/src/client/locales.ts index 8b83870c40..f2b8bf1f01 100644 --- a/packages/client/ui-model/src/client/locales.ts +++ b/packages/client/ui-model/src/client/locales.ts @@ -1,4 +1,12 @@ -/** `model` namespace dictionaries. */ +/** + * `model` namespace dictionaries. + * + * `trigger.selectAria` reads identically to `trigger.fallback` today and is + * still a separate key: the visible fallback label and the accessible name of + * an unset trigger are free to diverge per locale, and folding it into + * `trigger.aria` would announce the degenerate "Select model, current Select + * model". + */ /** Simplified Chinese dictionary (the key-set source of truth). */ export const zh = { From 00e08d1ec034e7d3389598823d81a2a22b71e738 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Fri, 31 Jul 2026 15:19:13 +0800 Subject: [PATCH 050/689] testing(web): open the settings dialog in the model catalog test The test inherited an open dialog with the DeepSeek editor already expanded from the credential test above it. That test now reloads the page to exercise the welcome step, so nothing carries the dialog across and the catalog test timed out looking for a fold that was no longer on screen. The review flagged this coupling as two links deep; the merge proved it. --- apps/web/tests/onboarding-deepseek-config.e2e.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts index e3fd668343..5f24ca5a6d 100644 --- a/apps/web/tests/onboarding-deepseek-config.e2e.ts +++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts @@ -162,7 +162,15 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup it('configures arbitrary DeepSeek models and prompts after the selected model is removed', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-models')) + // Opened here rather than inherited: the credential test reloads the page + // to exercise the welcome step, so nothing carries an open dialog across. + await page.getByRole('button', { name: '设置', exact: true }).click() const settings = page.getByRole('dialog', { name: '设置' }) + await settings.waitFor({ timeout: 10_000 }) + await settings.getByRole('button', { name: '模型' }).click() + const deepSeek = settings.getByText('DeepSeek', { exact: true }).first() + await deepSeek.waitFor({ timeout: 10_000 }) + await deepSeek.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click() await settings.getByText('自定义设置').click() await settings.getByRole('button', { name: '删除模型' }).first().click() await settings.getByRole('button', { name: '添加模型' }).click() From 49f8cdd40145709247a9797ba973b9cd0d7919f4 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Fri, 31 Jul 2026 15:25:29 +0800 Subject: [PATCH 051/689] fix(web): bind the composer's caret to its glyphs with one scrollport MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The composer paints its draft in two layers — the textarea owns the value, the selection and the caret, the backdrop paints every visible glyph — and they had one scroll offset each, kept equal by a `scroll` listener. That holds at rest and not in motion: a wheel gesture scrolls the textarea on the compositor, the listener runs afterwards, and for those frames the caret sits at the new offset with the words at the old one. Measured on a harness of the same geometry, a 200px offset change separates caret from glyphs by ~200px (chromium 203, firefox 202, WebKit 203) until a later frame — the caret flying out of its own text when a user swipes a long draft quickly. Both layers now ride one scrollport: `[data-input-scroll]` carries the 14-line cap, the auto-grow stack inside it is as tall as the whole draft, and the textarea holds no scrollable overflow of its own. The browser applies one offset to both layers in the same frame, so the coupling is structural rather than maintained. The backdrop's trailing-line sentinel and the cross-engine wrap-width premise go with the mirror: the layers now share a containing block, which closes the WebKit 768-against-776 gap by construction. --- ...omposer-glyph-layer-tracks-the-textarea.md | 77 ----- ...oser-glyph-layer-tracks-the-textarea.zh.md | 77 ----- ...ext-layers-share-one-scrollport.i18n.yaml} | 6 +- ...mposer-text-layers-share-one-scrollport.md | 73 +++++ ...ser-text-layers-share-one-scrollport.zh.md | 73 +++++ apps/web/tests/approval-composer.e2e.ts | 12 +- apps/web/tests/composer-draft-scroll.e2e.ts | 287 ++++++++++-------- .../geometry.expected.md | 18 +- .../src/client/skeleton/InputBar.module.css | 59 ++-- .../src/client/skeleton/InputBar.tsx | 110 +++---- .../ui-conversation/tests/input-bar.spec.tsx | 50 ++- 11 files changed, 412 insertions(+), 430 deletions(-) delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.md delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.zh.md rename .agents/notes/implemented/bug-fix/{2026-07-31-composer-glyph-layer-tracks-the-textarea.i18n.yaml => 2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml} (53%) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.md deleted file mode 100644 index d60a100be9..0000000000 --- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.md +++ /dev/null @@ -1,77 +0,0 @@ -# Agent Note: The composer's glyph layer tracks the textarea's scroll offset - -Status: implemented - -English | [中文](2026-07-31-composer-glyph-layer-tracks-the-textarea.zh.md) - -## Problem - -A composer draft longer than the 14-line cap could not be scrolled. The caret moved and the selection moved, but the words stayed frozen at line 1 — no wheel gesture, drag, or arrow key brought the end of a long draft on screen, so the bottom of anything past ~14 lines was unreachable and unreadable while writing it. - -The cap itself was working. The composer paints its text in two stacked layers ([InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)): the `