diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml index c1a0acb3d7..12c82b20bb 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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-05-reconstructable-requests.md -2026-07-05-reconstructable-requests.md: bc8ba640c400b18598f18aa303f2bd1b5c5b9cdc -2026-07-05-reconstructable-requests.zh.md: de1802aac83f1e0980172d2d541a093f2d729e4a +2026-07-05-reconstructable-requests.md: bca93a60bf07484d73f1faf50359b72a0d00b9a3 +2026-07-05-reconstructable-requests.zh.md: c9d2a4a5d05456df8b0bd065bade8a41dd7e4e84 diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md index bc8ba640c4..bca93a60bf 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -24,7 +24,7 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro `EpochHeader` records the request's non-history state: call config, rendered system prompt, and tool schemas, with empty values canonicalized to absence. Adapter-supplied effort and token defaults retain their `adapterDefaults` provenance; a Web model selection restored from the log omits an adapter-owned effort so the next resolution cannot reclassify the same effective config as an explicit selection and a false change. `request/header` always writes a full snapshot: the first loop instance uses reason `initial`, later instances use `resume`, an in-instance change uses `change`, and an unchanged envelope beginning an explicitly declared message series or following a surface replacement uses `series`. A `change` snapshot carries `startsSeries: true` when the changed request also starts a series, preserving the two independent facts without a duplicate header. Ordinary append-only later Turns, further same-series Steps, and retries inherit the latest snapshot. `foldRequestHeader` selects the latest snapshot. Legacy `request/header-delta` events and the removed `fallback` reason are rejected when appended or loaded. -Each proposed step first claims its inbox batch and runs `agent/pre-step`. Rejection opens no step; enter opens `step/start`, records the final message batch as `user/message` events, and may use `startsRequestSeries: true` to declare a distinct series. The step then assembles the system prompt and tools, while `agent/request` may replace only the frozen call-config seed. The loop records the owed initial, resume, change, or series full snapshot, builds `GenerateOptions` from derived messages and that header, and deep-freezes it while leaving `AbortSignal` live. The first call config starts from explicit `AgentOptions`, preserving fork overrides and resume reconfiguration; later calls start from the folded header. +Each proposed step first claims its inbox batch and runs `agent/pre-step`. Rejection opens no step; enter opens `step/start`, records the final message batch as `user/message` events, and may use `startsRequestSeries: true` to declare a distinct series. The step then assembles the system prompt and tools, while `agent/request` may replace only the frozen call-config seed. The loop records the owed initial, resume, change, or series full snapshot, builds `GenerateOptions` from derived messages and that header, and freezes it while leaving `AbortSignal` live. The [request-freeze provenance decision](../simplification/2026-09-06-agent-request-freeze-provenance.md) owns reuse of completed message freezes and per-request local header freezing. The first call config starts from explicit `AgentOptions`, preserving fork overrides and resume reconfiguration; later calls start from the folded header. **The open step is the reconstruction boundary.** Its entered `user/message` batch and any newly written `request/header` precede request dispatch. Injection after the atomic claim joins a later request, while a listener that must affect this request returns messages through `agent/pre-step`. Header reconstruction selects the step's `request/header`, or carries the prior snapshot when no new header is written. diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md index de1802aac8..c9d2a4a5d0 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md @@ -24,7 +24,7 @@ Status: implemented `EpochHeader` 记录请求的非历史状态：调用配置、渲染后的系统提示词和工具 schema，空值规范化为缺失。适配器提供的推理强度与 token 默认值会保留其 `adapterDefaults` 来源信息；Web 从日志恢复模型选择时会省略适配器持有的推理强度，因此下一次解析不会把相同的有效配置重新归类为显式选择并产生虚假变更。`request/header` 始终写入完整快照：首个循环实例使用 reason `initial`，后续实例使用 `resume`，实例内变更使用 `change`，内容未变的封装显式开启消息序列或跟随表层替换时使用 `series`。如果发生变化的请求同时开启序列，`change` 快照会携带 `startsSeries: true`，无需重复 header 即可保留这两个独立事实。普通的仅追加后续 Turn、同一序列内后续的 Step 与重试沿用最新快照。`foldRequestHeader` 选择最新快照。旧的 `request/header-delta` 事件和已移除的 `fallback` reason 在追加或加载时都会被拒绝。 -每个拟议步骤先领取其 inbox 批次，再运行 `agent/pre-step`。reject 不打开步骤；enter 打开 `step/start`，把最终消息批次记录为 `user/message` 事件，并可使用 `startsRequestSeries: true` 声明独立序列。随后步骤组装系统提示词与工具，`agent/request` 只能替换冻结的调用配置种子。循环记录所需的 initial、resume、change 或 series 完整快照，从派生消息与该 header 构建 `GenerateOptions`，对其深度冻结但保持 `AbortSignal` 活跃。首次调用配置从显式的 `AgentOptions` 出发，保留 fork 覆盖和恢复重配置；后续调用从折叠后的 header 出发。 +每个拟议步骤先领取其 inbox 批次，再运行 `agent/pre-step`。reject 不打开步骤；enter 打开 `step/start`，把最终消息批次记录为 `user/message` 事件，并可使用 `startsRequestSeries: true` 声明独立序列。随后步骤组装系统提示词与工具，`agent/request` 只能替换冻结的调用配置种子。循环记录所需的 initial、resume、change 或 series 完整快照，从派生消息与该 header 构建 `GenerateOptions`，冻结请求但保持 `AbortSignal` 活跃。[请求冻结来源证明决策](../simplification/2026-09-06-agent-request-freeze-provenance.zh.md)拥有消息完整冻结的复用规则和每次请求的本地 header 冻结规则。首次调用配置从显式的 `AgentOptions` 出发，保留 fork 覆盖和恢复重配置；后续调用从折叠后的 header 出发。 **已打开步骤是重建边界。** 进入步骤的 `user/message` 批次与任何新写入的 `request/header` 都位于请求分派之前。原子领取后发生的注入加入后续请求；必须影响本次请求的监听器则通过 `agent/pre-step` 返回消息。header 重建选择该步骤的 `request/header`，或在无新 header 写入时沿用前一个快照。 diff --git a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml index 14b785c51c..45b4faa5d6 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.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-09-05-read-only-session-migration-preparation.md -2026-09-05-read-only-session-migration-preparation.md: c343ca457184554f4b47a0795dcb33b8b07e9d39 -2026-09-05-read-only-session-migration-preparation.zh.md: 3a283259729eda6a01fa4208cac5399f45978fac +2026-09-05-read-only-session-migration-preparation.md: ab23e7e61dcdf0762cae6185de5fd16c4070fcbf +2026-09-05-read-only-session-migration-preparation.zh.md: 89377d4d84776bebbc6d2ca6acea92ac15f74df3 diff --git a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md index c343ca4571..ab23e7e61d 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md +++ b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md @@ -59,7 +59,7 @@ interface MigrationPreparation { } ``` -A new read or write open joins the existing entry only when its source path and revision still match. `waitWithAbort()` races each caller's AbortSignal against the shared Promise without forwarding that signal to shared work. The backend-owned controller is aborted only when the last waiter leaves while preparation is still running. +A new read or write open joins the existing entry only when its source path and revision still match. `waitWithAbort()` races each caller's AbortSignal against the shared Promise without forwarding that signal to shared work. The backend-owned controller is aborted only when the last waiter leaves while preparation is still running. The cancellation test pauses the physical read and observes two registered waiters before aborting one caller; an event-loop yield alone cannot establish admission after asynchronous path and revision lookup. Completed results enter the existing bounded `coldLogMemo`. The `StoredLog` discriminant separates published current state from `PreparedStoredLog`, whose `publication` field binds current logical events to their matching publication operation. A query followed by Agent resume therefore reuses the same Decode and migration result. The in-flight map owns only running work; it is not a second completed-result cache. diff --git a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md index 3a28325972..89377d4d84 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md @@ -59,7 +59,7 @@ interface MigrationPreparation { } ``` -新的 read/write open 只有在 source path 与 revision 仍匹配时才加入已有 entry。`waitWithAbort()` 让每个 caller 的 AbortSignal 与 shared Promise 竞争，但不会把 caller signal 传给共享工作。只有最后一个 waiter 在 preparation 仍运行时离开，backend-owned controller 才会 abort。 +新的 read/write open 只有在 source path 与 revision 仍匹配时才加入已有 entry。`waitWithAbort()` 让每个 caller 的 AbortSignal 与 shared Promise 竞争，但不会把 caller signal 传给共享工作。只有最后一个 waiter 在 preparation 仍运行时离开，backend-owned controller 才会 abort。取消测试暂停物理读取，并在取消一个 caller 前观察到两个已注册的 waiter；仅让出一次事件循环不能证明异步路径与 revision 查找后的加入已经完成。 完成结果进入既有 bounded `coldLogMemo`。`StoredLog` 判别字段把已发布 current state 与 `PreparedStoredLog` 分开，后者的 `publication` 字段把 current logical events 与匹配的 publication operation 绑定，使 query 后紧接的 Agent resume 复用同一次 Decode 与 migration。In-flight map 只拥有运行中的工作，不是第二个 completed-result cache。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.i18n.yaml index c30e2a0d4e..367d6acded 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.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-08-17-subagent-message-settlement-ordering.md -2026-08-17-subagent-message-settlement-ordering.md: cdc996643c84c5f50a3bd1836e82645660dc8c57 -2026-08-17-subagent-message-settlement-ordering.zh.md: 1143da1560e4969dcc4f6a0c6d5ca18060b56191 +2026-08-17-subagent-message-settlement-ordering.md: 7462a670766664745e46204dcb01e578b4f86219 +2026-08-17-subagent-message-settlement-ordering.zh.md: bba8fe0e7c543982176def4dbcc6f94dda204339 diff --git a/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.md b/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.md index cdc996643c..7462a67076 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.md +++ b/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.md @@ -14,7 +14,7 @@ The child instruction says to send a finding whenever it changes what the parent Every model-authored adjacent-Agent message uses fixed Steer delivery through `SubagentRuntime.sendMessage()`. A running parent reads the child message at its nearest safe step boundary and an idle parent starts a turn. There is no quiet or next-turn model delivery option. -The continuation manager retains `sendWaking()` and `admitWaking()` around messages delivered to resident continuable parents. Their purpose is waking-send admission accounting: the receiving Activation remains live between synchronous inbox insertion and the microtask that observes the wake. +The continuation manager retains `sendWaking()` around messages delivered to resident continuable parents and routes the synchronous send through the parent's private `SubagentInbox`. The wrapper accepts the send before its closing promise is installed or rejects it afterwards, and an accepted attempt renews the Activation's wake generation before returning. The receiving Activation therefore cannot settle over an accepted waking send. ### Ordering across parent states diff --git a/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.zh.md b/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.zh.md index 1143da1560..bba8fe0e7c 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-17-subagent-message-settlement-ordering.zh.md @@ -14,7 +14,7 @@ child 指令要求在发现会改变 parent 下一步动作时发送该发现。 每条模型编写的相邻 Agent 消息都通过 `SubagentRuntime.sendMessage()` 使用固定 Steer 投递。运行中的 parent 在最近安全 step 边界读取 child 消息，空闲 parent 则启动一个轮次。模型没有静默或 next-turn 投递选项。 -继续执行管理器在投递到驻留可继续 parent 的消息周围保留 `sendWaking()` 与 `admitWaking()`。它们负责唤醒发送准入记账：接收方 Activation 会在同步 inbox 插入与观察到唤醒的微任务之间保持在线。 +继续执行管理器会在投递到驻留可继续 parent 的消息周围保留 `sendWaking()`，并通过 parent 的私有 `SubagentInbox` 执行同步发送。包装层会在安装 closing promise 前接受发送，并在安装后拒绝发送；被接受的尝试会在返回前更新 Activation 的 wake generation。因此，接收方 Activation 不会越过一条已接受的唤醒发送完成结算。 ### 不同 parent 状态下的顺序 diff --git a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.i18n.yaml new file mode 100644 index 0000000000..5df3dbdf86 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.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-09-07-pinned-scroll-delivery-before-layout.md +2026-09-07-pinned-scroll-delivery-before-layout.md: f3b428dbe0d2fdc7cbaedf0383d2ab80ea1bfd45 +2026-09-07-pinned-scroll-delivery-before-layout.zh.md: 9b200f45535c67cfbbb75feaf3025c5a3b5c1fa2 diff --git a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md new file mode 100644 index 0000000000..f3b428dbe0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md @@ -0,0 +1,23 @@ +# Agent Note: Settle pinned scroll deliveries before layout changes + +Status: implemented + +English | [中文](2026-09-07-pinned-scroll-delivery-before-layout.zh.md) + +## Problem + +A delayed scroll sample compares positions from different layouts. While Chat is pinned, a composer or transcript shrink can move the browser floor; subsequent growth can move the browser position again before `scrollend` or the sampling timer. Deferring follow during that interval leaves the observed-top ledger stale and can classify browser layout movement as reader input, disabling follow without a reader gesture. + +## Decision + +[ChatView](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) uses the existing observed-top comparison to sample non-reader pinned scroll deliveries synchronously through the same sample operation that clears pending work. This releases layout follow before further growth. Genuine reader movement remains pending until the existing interval or `scrollend`, even within the follow threshold: growth must not erase small gestures before they accumulate into a scroll-away. Immediate pinned samples use scroll metrics, not semantic-row geometry. + +## Alternatives considered + +**Defer every delivery.** Coalescing reduces geometry work while reading history, but a pinned browser position and its floor must be attributed in the same layout. A longer timeout or retry cannot recover ownership once the stale comparison disarms it. + +**Sample every delivery synchronously.** This restores attribution but also repeats semantic-anchor and reading-line measurements throughout an away-reader scroll burst. Only pinned ownership needs the immediate path. + +## Consequences + +Pinned deliveries incur immediate scroll-metric reads. History reading retains its bounded sampling cadence, and explicit return-to-bottom deliveries clear any pending away sample. [Focused tests](../../../../packages/client/ui-chat/tests/chat-view.client.spec.tsx) cover shrink/regrowth before scrollend, observer growth without row measurements, repinning with a pending sample, timer and scrollend sampling, and unmount cancellation. The [keyless browser scenario](../../../../apps/web/tests/chat-scroll-contract.e2e.ts) covers pinned Send, real scroll-away input, streaming, and tool disclosure across the long transcript. diff --git a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.zh.md b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.zh.md new file mode 100644 index 0000000000..9b200f4553 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.zh.md @@ -0,0 +1,23 @@ +# Agent Note: 在布局变化前处理贴底滚动事件 + +Status: implemented + +[English](2026-09-07-pinned-scroll-delivery-before-layout.md) | 中文 + +## Problem + +延迟的滚动采样会比较来自不同布局的位置。Chat 贴底时，输入框或 transcript（文本记录）收缩可能改变浏览器底部位置；随后的增长又可能在 `scrollend` 或采样定时器触发前改变浏览器位置。在此期间推迟跟随会使已观察顶部位置记录过期，把浏览器布局移动误判为读者输入，在没有读者操作时关闭跟随。 + +## Decision + +[ChatView](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) 使用现有的已观察顶部位置比较，通过同一个清除待处理工作的采样操作，同步采样非读者引起的贴底滚动事件。这会在后续增长前恢复布局跟随。真实读者移动即使位于跟随阈值内，也保持待处理直到现有周期或 `scrollend`：增长不能在小幅操作累积为离底滚动前将其抵消。立即执行的贴底采样只读取滚动指标，不读取语义行几何。 + +## Alternatives considered + +**延迟所有事件。** 合并采样减少阅读历史时的几何计算，但贴底浏览器位置及其底部必须在同一布局中完成归因。过期比较关闭跟随后，延长超时或重试都无法恢复归属。 + +**同步采样所有事件。** 这能恢复归因，却也会在离底读者连续滚动时重复测量语义锚点和阅读线。只有贴底归属需要立即处理。 + +## Consequences + +贴底事件会立即读取滚动指标。历史阅读保留有界采样节奏，显式回到底部的滚动事件会清除任何待处理的离底采样。[聚焦测试](../../../../packages/client/ui-chat/tests/chat-view.client.spec.tsx) 覆盖 scrollend 前的收缩与增长、无需行测量的观察器增长、存在待处理采样时重新贴底、定时器与 scrollend 采样，以及卸载取消。[无密钥浏览器场景](../../../../apps/web/tests/chat-scroll-contract.e2e.ts) 覆盖长 transcript 中贴底发送、真实离底输入、流式输出与工具详情展开。 diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml index 3032ff0e9c..cd51630220 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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-27-web-subagent-conversations.md -2026-07-27-web-subagent-conversations.md: 28e06d1db9103de53e6e2fb266a03e168428d0d2 -2026-07-27-web-subagent-conversations.zh.md: e93abe89e855d688d822bfd20fd1644f24bdf3e9 +2026-07-27-web-subagent-conversations.md: d0713731de86df639a426ee56c39857c50af6bc7 +2026-07-27-web-subagent-conversations.zh.md: 0f4f6467484ee1caa3cdf28f44e016ff674ac1dc diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md index 28e06d1db9..d0713731de 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md @@ -16,11 +16,11 @@ The UI must also preserve the membership, modes, and diagnostics of the [durable The Web product exposes the selected session's direct session-backed subagents from the current-title lineage region in the header. Users can lazily expand descendant catalogs and open either mode in the existing conversation region. A one-shot child is permanently read-only. A continuable child accepts human follow-ups only while its exact direct-parent Agent is live; otherwise its persisted transcript remains readable with a recovery explanation. -Every opened child carries a catalog-derived address `{ parentSessionId, childSessionId, mode }`. The mode-bearing address, not lineage or the coarse origin marker, selects dedicated history and prompt transports. History reads the persisted session without activation. A continuable prompt calls `ctx.subagents.followup()` and succeeds at inbox acceptance with `{ messageId }`; it does not steer an open turn, expose an Activation, wait for completion, or return an outcome. +Every opened child carries a catalog-derived address `{ parentSessionId, childSessionId, mode }`. The mode-bearing address, not lineage or the coarse origin marker, selects dedicated history and prompt transports. History reads the persisted session without activation. A continuable prompt carries Queue or Steer delivery through `subagent.prompt` and succeeds at inbox acceptance with `{ messageId }`; it does not expose an Activation, wait for completion, or return an outcome. Adjacent-Agent model messages use the separately owned fixed-Steer operation. The generic Host domain preserves the same ownership boundary. `session.history` and the source side of `session.fork` read an attached Session or inspect persistence without acquiring an Agent; history folds cold projection values from that exact inspected prefix, while a fork publishes an ordinary independent session. Generic Agent-bound session, command, and goal routes return `agent-busy` for session-backed subagents, as do explicit-id `session.create` adoption and attached-only queue controls. The denial classifier accepts the coarse `origin` marker, a `subagent/descriptor` in the session's own suffix, or exact live runtime ownership by the parent; these signals only prevent generic ownership and never replace catalog mode or direct-parent authorization. -Stopping an addressed child never falls through to `session.cancel`. `SubagentRuntime.followup()` owns admission only until inbox acceptance and grants no cancellation handle; a running continuable child is stopped through the dedicated `subagent.interrupt` route under the [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md), which parks pending work instead of discarding it. One-shot children remain uncancellable from the Web. +Stopping an addressed child never falls through to `session.cancel`. Browser prompt delivery owns admission only until inbox acceptance and grants no cancellation handle; a running continuable child is stopped through the dedicated `subagent.interrupt` route under the [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md), which parks pending work instead of discarding it. One-shot children remain uncancellable from the Web. This decision covers Web discovery, transcript viewing, and parent-authorized human continuation. It does not make a subagent independently user-owned; that product remains [interactive side sessions](../../proposed/feature/2026-07-08-interactive-side-sessions.md). @@ -45,7 +45,7 @@ Healthy rows reuse the standard session projections retained in the list mirror. Selecting a row records its exact address before opening the resident client `Session`. History pagination, event folding, tool render intents, titles, and live mux reconciliation reuse the ordinary conversation machinery. Breadcrumbs follow parent links only through `origin: 'subagent'` rows, include the first ordinary owner, and keep ordinary forks single-level. Each subagent breadcrumb gets its direct-parent sibling catalog and uses that catalog's label when available. Forking an addressed subagent creates an ordinary fork with direct source lineage and attaches it to the nearest workspace-owning ancestor. The catalog is an ARIA tree with lazy ArrowRight/ArrowLeft disclosure, linear ArrowUp/ArrowDown navigation, Home/End, Escape, and focus restoration. -A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input and Send action disabled so independent Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter and Send admit another FIFO turn even while the child runs, while independent Stop routes through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior. +A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input and Send action disabled so independent Stop and live QueueDock controls stay reachable, and the read-only takeover returns once it stops. With a live parent, the ordinary Enter/Cmd+Enter preference selects Queue or best-effort Steer even while the child runs. QueueDock Edit, Remove, and Steer remain available for a live continuable child even when its parent is offline, while independent Stop routes through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior. Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation path. @@ -55,13 +55,13 @@ Agent-bound auxiliary controls are unavailable in addressed child views. In part - `subagent.list` takes `parentSessionId`, calls `ctx.subagents.listChildren(parentSessionId, signal)`, returns the complete ordered entries with each healthy row's boolean `hasChildren` snapshot, replaces each healthy row's corpus activity with whether its exact Agent driver is running, and includes whether the exact parent currently resolves from `ctx.agents`. - `subagent.history` takes the full mode-bearing address plus ordinary page arguments. It verifies the child and mode against the direct catalog, reads through `ctx.sessionQuery.readSession()`, rechecks direct lineage, and returns the ordinary raw-event, render-intent, pagination, and host-computed session-projection baseline without publishing an Agent. -- `subagent.prompt` accepts only a `mode: 'continuable'` address and upload-shaped `PromptContentPart[]`; the Host admits and persists image parts into durable references before delivery ([image delivery](../../archived/bug-fix/2026-08-27-steer-followup-image-delivery.md)). It requires the exact live parent, revalidates the catalog address, calls `ctx.subagents.followup(parent, childId, content, { source, signal })`, and returns the accepted `MessageId`. +- `subagent.prompt` accepts only a `mode: 'continuable'` address, `delivery: 'queue' | 'steer'`, and upload-shaped `PromptContentPart[]`; the Host admits and persists image parts into durable references before delivery ([image delivery](../../archived/bug-fix/2026-08-27-steer-followup-image-delivery.md)). It requires the exact live parent, revalidates the catalog address, uses the continuation manager's shared human-delivery admission, and returns the accepted `MessageId`. The gateway maps missing parent, missing or diagnostic catalog entries, not-resumable and unauthorized children, request cancellation, image admission and image-capability refusals (`subagent/attachment-invalid`), and temporarily unavailable continuation admission to typed RPC errors. It does not expose descriptor or provider details. A list/prompt race is normal: the prompt result, not the earlier availability or activity snapshot, is authoritative. Viewing persisted history creates no mux subscription by itself. When a follow-up materializes a cold child Activation, the existing Host and mux streams publish its lifecycle and events. Reconnect rebuilds the addressed window through `subagent.history`. -The ordinary `session.history` route is likewise observation-only for both ordinary and subagent sessions, but it does not carry the catalog address or grant continuation authority. Every ordinary route that needs an Agent resolves through the shared ownership fence before cold resume; `session.cancel` and `session.updateQueue` apply the same check directly because they intentionally query only attached Agents. +The ordinary `session.history` route is likewise observation-only for both ordinary and subagent sessions, but it does not carry the catalog address or grant continuation authority. Every ordinary route that needs an Agent resolves through the shared ownership fence before cold resume; `session.cancel` retains that fence. `session.updateQueue` has one target-local exception for a live child whose current projected identity is continuable and comes from its own non-seed suffix; one-shot, missing, unknown, corrupt, seed-only, or cold children remain fenced. The adapter stays behind the generated Remote namespace; `dsh-host-webserver` remains a carrier. Browser code imports the contract through the existing connection package and never reaches host `ctx`, preserving the [archived GUI RPC layering decision](../../archived/architecture/2026-07-19-gui-layering-and-rpc-protocol.md). diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md index e93abe89e8..0f4f646748 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md @@ -16,11 +16,11 @@ UI 还必须保留[持久化目录](../../archived/feature/2026-07-22-durable-su Web 产品通过页头的当前 title 谱系区域公开选中会话中由会话支撑的直接 subagent。用户可以懒加载展开后代目录，并在现有对话区域中打开任一 mode。one-shot child 永久只读。可继续 child 只有在其确切直接 parent agent 存活时才接受用户后续消息；否则，其持久化 transcript 仍然可读，并附带恢复说明。 -每个打开的 child 都携带目录派生地址 `{ parentSessionId, childSessionId, mode }`。选择专用历史与提示词传输的是包含 mode 的地址，而不是谱系或粗粒度 origin 标记。历史操作会从持久化存储读取会话，而不触发激活。可继续提示词操作会调用 `ctx.subagents.followup()`，并在 inbox 接受消息时以 `{ messageId }` 成功返回；它不会对进行中的轮次执行 steering（中途引导）、公开 Activation、等待完成或返回结果。 +每个打开的 child 都携带目录派生地址 `{ parentSessionId, childSessionId, mode }`。选择专用历史与提示词传输的是包含 mode 的地址，而不是谱系或粗粒度 origin 标记。历史操作会从持久化存储读取会话，而不触发激活。可继续提示词通过 `subagent.prompt` 携带 Queue 或 Steer 投递，并在 inbox 接受消息时以 `{ messageId }` 成功返回；它不会公开 Activation、等待完成或返回结果。相邻 Agent 的模型消息使用单独拥有的固定 Steer 操作。 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。 -停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentRuntime.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.zh.md)，该约定会停放并保留待处理工作，而不是将其丢弃。one-shot child 在 Web 端仍不可取消。 +停止一个已寻址 child 绝不回退到 `session.cancel`。浏览器 prompt 投递只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.zh.md)，该约定会停放并保留待处理工作，而不是将其丢弃。one-shot child 在 Web 端仍不可取消。 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.zh.md)。 @@ -45,7 +45,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。每一级 subagent 面包屑都会获得其直接 parent 的 sibling 目录，并在目录可用时采用其中的 label。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。 -one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.zh.md)）。提示词失败会通过普通错误行为保留草稿。 +one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 与在线 QueueDock 控制保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，普通 Enter／Cmd+Enter 偏好也会选择 Queue 或 best-effort Steer。对在线可继续 child，QueueDock Edit、Remove 与 Steer 在 parent 离线时仍可用；独立 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.zh.md)）。提示词失败会通过普通错误行为保留草稿。 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行路径之外激活持久化 child 历史。 @@ -55,13 +55,13 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。 - `subagent.list` 接受 `parentSessionId`，调用 `ctx.subagents.listChildren(parentSessionId, signal)`，返回完整有序的条目以及每个健康行的布尔 `hasChildren` 快照，把每个健康行的语料活动状态替换为其确切 Agent driver 是否正在运行，并说明当前能否从 `ctx.agents` 解析出确切 parent。 - `subagent.history` 接受包含 mode 的完整地址与普通页参数。它对照直接目录校验 child 与 mode，通过 `ctx.sessionQuery.readSession()` 读取，再次检查直接谱系，并在不发布 agent 的情况下返回普通原始事件、渲染意图、分页与由 Host 计算的会话投影基线。 -- `subagent.prompt` 只接受 `mode: 'continuable'` 地址与上传形态的 `PromptContentPart[]`；Host 在投递前把图片部分准入并持久化为持久引用（[图片投递](../../archived/bug-fix/2026-08-27-steer-followup-image-delivery.md)）。它要求确切的存活 parent，重新校验目录地址，调用 `ctx.subagents.followup(parent, childId, content, { source, signal })`，并返回已接受的 `MessageId`。 +- `subagent.prompt` 只接受 `mode: 'continuable'` 地址、`delivery: 'queue' | 'steer'` 与上传形态的 `PromptContentPart[]`；Host 在投递前把图片部分准入并持久化为持久引用（[图片投递](../../archived/bug-fix/2026-08-27-steer-followup-image-delivery.md)）。它要求确切的存活 parent，重新校验目录地址，使用 continuation manager 共享的人类投递准入，并返回已接受的 `MessageId`。 网关会将 parent 缺失、目录条目缺失或为 diagnostic、child 不可恢复或未授权、请求取消、图片准入或图片能力拒绝（`subagent/attachment-invalid`）以及继续执行准入暂时不可用等失败映射为类型化 RPC 错误。它不会公开描述符或提供方细节。list／prompt 竞态属于正常情况：权威依据是提示词操作的结果，而不是更早的可用性或活动快照。 查看持久化历史本身不会创建 mux 订阅。当后续消息物化冷态 child Activation 时，现有 Host 与 mux 流会发布其生命周期与事件。重新连接时，系统通过 `subagent.history` 重建已寻址窗口。 -普通 `session.history` 路由对于普通会话和 subagent 会话同样只执行观察，但它既不携带目录地址，也不授予继续执行权限。每条需要 Agent 的普通路由都会在恢复冷会话前经过共享所有权栅栏；`session.cancel` 与 `session.updateQueue` 会直接执行同一检查，因为它们有意只查询已附加的 Agent。 +普通 `session.history` 路由对于普通会话和 subagent 会话同样只执行观察，但它既不携带目录地址，也不授予继续执行权限。每条需要 Agent 的普通路由都会在恢复冷会话前经过共享所有权栅栏；`session.cancel` 保留该栅栏。`session.updateQueue` 只有一个目标本地例外：目标是在线 child，且其当前 projection identity 为 continuable 并来自自身的非 seed suffix；one-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 仍受栅栏阻挡。 适配器仍位于生成的 Remote 命名空间之后；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包导入约定，绝不直接访问宿主 `ctx`，从而保持[已归档的 GUI RPC 分层决策](../../archived/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。 diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml index 9741d3bdd5..fc2a00aa26 100644 --- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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-28-continuable-subagent-conversations.md -2026-07-28-continuable-subagent-conversations.md: fef7aba2080521253d7a67dd5169880fa5146dc0 -2026-07-28-continuable-subagent-conversations.zh.md: 875d6ab7ea5b8dd78276c3a7a9e789646340bc15 +2026-07-28-continuable-subagent-conversations.md: 8c3f2e1da593157f17528f13fc8842012aad0284 +2026-07-28-continuable-subagent-conversations.zh.md: 886e31fa3d88b78f875d51058bb2ec8c525837fe diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md index fef7aba208..8c3f2e1da5 100644 --- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md +++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md @@ -62,14 +62,14 @@ The internal residency lifecycle has three conditions and no separate `queued` s ```text running - | Agent quiescent with live children + | Agent quiescent with pending inbox or live children v waiting - | next-turn + | waking delivery +--------------------------> running running or waiting - | Agent quiescent and no live children + | Agent quiescent, empty inbox, and no live children v settled | AgentHandle.dispose completes @@ -77,15 +77,15 @@ settled no Activation ``` -`running` means the Agent has an active admission or turn, or its inbox contains waking work. `waiting` means the Agent is quiescent but the Activation still owns at least one child Activation that has not completed disposal. `settled` means the Agent is quiescent and every owned child is disposed; the manager then disposes the `AgentHandle` and removes the Activation. +`running` means the Agent has an active admission or turn. `waiting` means the Agent is quiescent but its Inbox is nonempty or the Activation still owns at least one child Activation that has not completed disposal. `settled` means the Agent is quiescent, its Inbox is empty, and every owned child is disposed; the manager then disposes the `AgentHandle` and removes the Activation. -The manager derives these states from Agent quiescence and the owned-child set rather than maintaining a second execution state machine. A `next-turn` delivered while `running` joins the Agent inbox. A `next-turn` delivered while `waiting` wakes the same Agent and returns the Activation to `running`. Delivery after disposal cold-resumes a new Activation. +The manager derives these states from Agent quiescence, the Inbox's pending state, and the owned-child set rather than maintaining a second execution state machine. A `next-turn` delivered while `running` joins the Agent inbox. A waking delivery while `waiting` wakes the same Agent and returns the Activation to `running`. Delivery after disposal cold-resumes a new Activation. -The manager linearizes delivery, child release, and disposal for each durable child. If a delivery races with final disposal, exactly one side wins the admission cutoff: delivery either enters the still-live Agent inbox, or waits for disposal and cold-resumes a new Activation. No caller can send to a handle after its disposal transaction begins. +The manager linearizes manager-owned delivery, child release, and disposal for each durable child. A private `SubagentInbox` delegates Queue and Steer to the Agent inbox and owns the Activation's existing close transaction. If manager delivery races with final disposal, exactly one side wins this admission cutoff: delivery either enters the still-live Agent inbox, or observes closing and follows its operation-specific rejection or cold-resume path. Direct Agent work does not use this wrapper, so natural settlement uses short maintenance claims to validate the idle phase before the final flush and final disposal decision, then revalidates the Session sequence, Inbox pending state, wake generation, and owned-child set under the child lock. Accepted work that remains active or changes Session, Inbox, or ownership state invalidates that settlement attempt instead of being cancelled by it; maintenance that starts and finishes entirely during the flush has completed before the cutoff. ### One inbox and follow-up delivery -The Agent inbox is the only queue. Every continuation message uses `Agent.followup()` and becomes one FIFO turn; neither the continuation manager nor the host maintains another message queue. Every accepted waking item keeps the current Activation live until `Agent.whenIdle()` observes the complete waking suffix. +The Agent inbox is the only queue. Every continuation message uses `Agent.followup()` and becomes one FIFO turn; neither the continuation manager nor the host maintains another message queue. Every pending Inbox occurrence keeps the current Activation live until it is claimed or discarded. This conservative rule also retains injected context: a quiet injection that remains after quiescence can keep the Activation and its live ancestors resident until a waking delivery claims it, a queue mutation removes it, or manager teardown disposes the tree. Routing depends only on Activation residency: @@ -103,21 +103,21 @@ Every Activation owns its `AgentHandle` and an `ownedChildren: Set`. When the authenticated parent is itself a continuation-managed Activation, starting a child or submitting parent-originated work adds the child Session id to that parent's `ownedChildren` before the child can run or the message can enter its inbox. That parent cannot settle or dispose while this set is non-empty. A top-level or other non-continuation Agent has no Activation and does not join this waiting graph. -Child release occurs only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. The manager awaits `ctx.sessions.flush(child.session)` but does not interpret its participation boolean: an arbitrary listener cannot prove that the selected persistence backend stored the state. A rejection is logged without preventing handle disposal or ownership release, because retaining a child would permanently pin its ancestors in `waiting`. If the child is owned, the manager then resolves the live parent through `SessionHeader.parentSession` and removes the child Session id from its `ownedChildren`. Manager teardown uses the same child-first order. +Child release occurs only after the child Agent is quiescent, its Inbox is empty, every child of that child is disposed, the best-effort final session flush settles, the same settlement facts survive a child-lock revalidation, and the child's `AgentHandle` completes disposal. The manager awaits `ctx.sessions.flush(child.session)` before closing admission but does not interpret its participation boolean: an arbitrary listener cannot prove that the selected persistence backend stored the state. A rejection is logged without preventing revalidation, handle disposal, or ownership release, because retaining a child would permanently pin its ancestors in `waiting`. If the child is owned, the manager then resolves the live parent through `SessionHeader.parentSession` and removes the child Session id from its `ownedChildren`. Manager teardown uses the same child-first order but closes admission and stops work immediately rather than performing natural-settlement revalidation. Ownership is retained until the child Activation is disposed. A later refinement may release a request-scoped lease earlier, but it would require an exact turn-completion correlation that this Task-free design deliberately does not add. Top-level teardown is host-owned rather than represented as another Activation. Manager unload invokes its internal manager-wide drain to close admission synchronously, await every admitted materialization through publication or rollback, stop the stable live forest, and release it child-first. A host that owns selected top-level Agents uses `drainContinuableDescendants(parents)`: exact Agent identities close admission only below those roots until each leaves the registry, while unrelated forests and manager-wide admission remain live; the manager stops their visible descendants before its first await, waits only materializations admitted below those roots, and releases only the selected branches. Every materialized start and live delivery rechecks caller cancellation, the applicable draining scope, Activation disposal, and exact parent authority in the same synchronous span as inbox submission, so teardown or parent replacement that wins before acceptance prevents delivery to the closing handle. Only after the applicable drain settles may the host dispose its top-level Agents; only manager-wide drain precedes manager-scope disposal. -The activation-owner scope exists because ordinary Cordis owner effects unwind in reverse registration order, which cannot express the dynamic child graph. Manager initialization registers the private scope's structural disposer first and its drain disposer afterward, so reverse unwind invokes the drain before releasing that scope; merely registering a cleanup effect on the same scope as later Agent handles would allow structural handle disposal to bypass child-first ordering. Each materialization registers its barrier participant and snapshots its exact live ancestry before starting the inner transaction, then remains tracked until it installs an Activation or fully rolls back. The Activation retains weak membership of that ancestry, so an intermediate Agent may leave the registry without hiding a still-live descendant from its host root. Each Activation installs one memoized disposal promise before cancellation or recursive callbacks, allowing scoped host shutdown, global manager unload, child release, and normal settlement to converge without double release. Cancellation propagates top-down before slow descendant cleanup; handle release remains child-first. Sibling branches drain independently; one disposal failure is recorded but does not prevent the manager from attempting the remaining selected handles, and the aggregate drain reports failure after all selected branches settle. Durable child Sessions survive this process-local teardown. +The activation-owner scope exists because ordinary Cordis owner effects unwind in reverse registration order, which cannot express the dynamic child graph. Manager initialization registers the private scope's structural disposer first and its drain disposer afterward, so reverse unwind invokes the drain before releasing that scope; merely registering a cleanup effect on the same scope as later Agent handles would allow structural handle disposal to bypass child-first ordering. Each materialization registers its barrier participant and snapshots its exact live ancestry before starting the inner transaction, then remains tracked until it installs an Activation or fully rolls back. The Activation retains weak membership of that ancestry, so an intermediate Agent may leave the registry without hiding a still-live descendant from its host root. Its private `SubagentInbox` installs one memoized closing promise before cancellation or recursive callbacks, allowing scoped host shutdown, global manager unload, child release, and normal settlement to converge without double release. Cancellation propagates top-down before slow descendant cleanup; handle release remains child-first. Sibling branches drain independently; one disposal failure is recorded but does not prevent the manager from attempting the remaining selected handles, and the aggregate drain reports failure after all selected branches settle. Durable child Sessions survive this process-local teardown. ### Adjacent-Agent messaging The shared `sendMessage(sender, targetId, content, options)` service operation adds no second queue. It accepts an exact live sender, permits only its direct parent or direct continuable child, and uses fixed Steer scheduling through the Agent inbox. The global `send_message({ agent_id, message })` tool exposes that same operation in both directions; the child's initial task identifies its direct parent when the tool is visible. The [adjacent-Agent messaging Agent Note](../architecture/2026-08-27-adjacent-agent-steer-messaging.md) owns its schema, authority, attribution, and prompt placement. -### Fixed Steer scheduling +### Agent and human scheduling -Every accepted Agent message uses `Agent.steer()`. A running target claims it at the nearest step boundary; an idle or cold-resumed target starts a turn. The continuation layer does not expose a caller-selectable quiet, next-turn, or follow-up mode. +Every accepted Agent message uses `Agent.steer()`. A running target claims it at the nearest step boundary; an idle or cold-resumed target starts a turn. Browser-authored human input separately carries `delivery: 'queue' | 'steer'` through `subagent.prompt`: Queue opens a later FIFO turn, while Steer uses the same best-effort nearest-step scheduling without changing the message's human provenance. The public service exposes no caller-selectable scheduling mode for Agent messages. ### Authority and recorded sender identity @@ -133,7 +133,7 @@ Without Jobs there is no `job_output`, `job_kill`, Task status, or per-message r Host and manager teardown remains the lifecycle stop path. Manager unload applies it globally; a host applies it only below the exact top-level Agents it owns. Each form closes the applicable admission scope, stops the selected visible Activations, awaits admitted materializations in that scope, releases child-first, and preserves the durable Sessions. -Each turn requests the Session durability checkpoint, while final Activation settlement additionally awaits `ctx.sessions.flush()` as a best-effort barrier. The manager deliberately ignores the boolean result because listener participation cannot identify a persistence backend. A rejection is logged without changing the lifecycle result or host-drain outcome; the manager still disposes the handle and releases ownership, and the persisted child state may be missing or stale on a later resume. +Each turn requests the Session durability checkpoint, while final Activation settlement additionally awaits `ctx.sessions.flush()` as a best-effort barrier before closing admission. The manager then revalidates that no Agent, Inbox, Session, or owned-child state changed during the await; a changed observation retries settlement and flushes the newer state. The manager deliberately ignores the flush boolean because listener participation cannot identify a persistence backend. A rejection is logged without changing the lifecycle result or host-drain outcome; the manager still performs the final revalidation, disposes the handle when it succeeds, and releases ownership, while the persisted child state may be missing or stale on a later resume. Only messages written to the child Session log are reconstructable with the source that supplied them; inbox acceptance alone provides no restart guarantee. @@ -189,13 +189,13 @@ The implementation pins these behaviors: - An idle Agent with live owned children yields a `waiting` Activation whose `AgentHandle` remains retained. - A `next-turn` delivered to `waiting` wakes the same Activation; delivery after completed disposal cold-resumes a new Activation. - Every continuation-managed parent Activation disposes only after all directly owned child Activations complete `AgentHandle` disposal; top-level Agents do not join the waiting graph. -- Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, logs rejection without interpreting listener participation as durability proof, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation. +- Final Activation settlement awaits `ctx.sessions.flush(child.session)` with admission open, logs rejection without interpreting listener participation as durability proof, revalidates the final state under the child lock, then closes admission, disposes the child handle, and releases parent ownership so a flush failure cannot leak a `waiting` Activation. - Manager teardown closes admission globally; a host owning selected top-level Agents instead closes admission only below their exact identities until those roots leave the registry. Both track admitted materializations by exact ancestry, install one memoized disposal cutoff per selected visible Activation, propagate cancellation top-down, release handles child-first, await every selected branch despite individual failures, and only then dispose the corresponding top-level Agents or manager scope. - The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup hook. - Session logs reconstruct only messages that were actually written, with the source that supplied each message; inbox-accepted but unlogged messages have no restart guarantee. - No continuable-subagent path creates or depends on a Task, `JobId`, Task completion notice, Task cancellation, or intermediate result-bearing execution wrapper. - Unit coverage pins the `startContinuable()` inbox-acceptance return boundary, complete rollback for each pre-acceptance and lifecycle-publication failure, global and parent-scoped drain quiescence for materialization caught between Agent publication and Activation registration, sibling-forest isolation, exact ancestry after an intermediate Agent leaves the registry, provider-independent cold resume, final exact-parent reauthorization after cold-resume materialization, caller-signal and teardown ownership on both sides of acceptance, and the absence of automatic replay for accepted-but-unlogged messages. -- Unit coverage pins the residency-only routing table, single-inbox ordering, `MessageId` correlation through inbox events, follow-up during an open turn, waiting wakeup, cold resume, ownership registration and release, child-first disposal, send-versus-dispose races, best-effort final flush with absent and failing listeners, and the absence of public subagent cancellation and steering. +- Unit coverage pins the residency-only routing table, single-inbox ordering, `MessageId` correlation through inbox events, follow-up during an open turn, waiting wakeup, cold resume, ownership registration and release, child-first disposal, send-versus-dispose races, direct Agent turns, Session-only work, and maintenance accepted during the final-flush await, best-effort final flush with absent and failing listeners, and the absence of public subagent cancellation and steering. - Report-package unit coverage separately pins child-only visibility, setup revocation, authority, delivery modes, stable message identity, and lifecycle races. - A keyless assembled-app snapshot covers parent delegation and follow-up queueing, the absence of subagent steering and implicit report delivery, retained waiting `AgentHandle`, and child-first disposal. A separate report snapshot covers the optional explicit return channel. diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md index 875d6ab7ea..886e31fa3d 100644 --- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md @@ -62,14 +62,14 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的 ```text running - | Agent quiescent with live children + | Agent quiescent with pending inbox or live children v waiting - | next-turn + | waking delivery +--------------------------> running running or waiting - | Agent quiescent and no live children + | Agent quiescent, empty inbox, and no live children v settled | AgentHandle.dispose completes @@ -77,15 +77,15 @@ settled no Activation ``` -`running` 表示 Agent 正在执行准入或轮次，或者 inbox 中存在会唤醒 Agent 的工作。`waiting` 表示 Agent 已经完全停稳，但激活仍持有至少一个尚未完成 dispose 的 child 激活。`settled` 表示 Agent 已经完全停稳且所有持有的 child 都已 dispose；随后管理器会 dispose `AgentHandle` 并移除激活。 +`running` 表示 Agent 正在执行准入或轮次。`waiting` 表示 Agent 已经完全停稳，但其 Inbox 非空，或激活仍持有至少一个尚未完成 dispose 的 child 激活。`settled` 表示 Agent 已经完全停稳、其 Inbox 为空且所有持有的 child 都已 dispose；随后管理器会 dispose `AgentHandle` 并移除激活。 -管理器根据 Agent 是否完全停稳以及所持 child 集合派生这些状态，而不是维护第二套执行状态机。在 `running` 时投递的 `next-turn` 会进入 Agent inbox。在 `waiting` 时投递的 `next-turn` 会唤醒同一个 Agent，并使激活回到 `running`。在 dispose 完成后投递消息则会冷恢复新激活。 +管理器根据 Agent 是否完全停稳、Inbox 的待处理状态以及所持 child 集合派生这些状态，而不是维护第二套执行状态机。在 `running` 时投递的 `next-turn` 会进入 Agent inbox。在 `waiting` 时到达的唤醒投递会唤醒同一个 Agent，并使激活回到 `running`。在 dispose 完成后投递消息则会冷恢复新激活。 -管理器会针对每个持久化 child，将投递、child 释放和 dispose 线性化。如果投递与最终 dispose 发生竞争，只有一方能越过准入截止点：投递要么进入仍在线的 Agent inbox，要么等待 dispose 完成后冷恢复新激活。任何调用方都不能向已经开始 dispose 事务的 handle 发送消息。 +管理器会针对每个持久化 child，将 manager 所有的投递、child 释放和 dispose 线性化。私有 `SubagentInbox` 会把 Queue 与 Steer 委托给 Agent inbox，并持有 Activation 既有的关闭事务。如果 manager 投递与最终 dispose 发生竞争，只有一方能越过这条准入截止点：投递要么进入仍在线的 Agent inbox，要么观察到正在关闭，并遵循该操作特有的拒绝或冷恢复路径。直接操作 Agent 的工作不经过这层包装，因此自然结算会通过短暂的 maintenance 占用，在最终 flush 与最终 dispose 决策之前验证 idle 阶段，并在 child lock 内重新验证 Session 序号、Inbox 待处理状态、wake generation 与 owned-child set。仍然活跃或改变 Session、Inbox 或所有权状态的已接受工作会让本次结算尝试失效，而不会被它取消；完全在 flush 期间开始并结束的 maintenance 已在截止点前完成。 ### 一个 inbox 与 follow-up 投递 -Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup()`，并成为一个 FIFO 轮次；继续执行管理器和宿主都不维护另一条消息队列。每个已接受且会唤醒 Agent 的条目都会让当前激活保持在线，直至 `Agent.whenIdle()` 观察到完整的唤醒工作后缀已经结束。 +Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup()`，并成为一个 FIFO 轮次；继续执行管理器和宿主都不维护另一条消息队列。每个待处理 Inbox occurrence 都会让当前激活保持在线，直到它被 claim 或 discard。这条保守规则也会保留注入 context：完全停稳后仍存在的静默注入可以让 Activation 及其在线祖先继续驻留，直到唤醒投递将其 claim、queue 变更将其移除，或 manager teardown dispose 整棵树。 路由只取决于激活的驻留状态： @@ -103,21 +103,21 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup( 当经过身份认证的 parent 自身是由继续执行管理器管理的激活时，启动 child 或提交由 parent 发起的工作，会在 child 可以运行或消息可以进入其 inbox 前，将 child 会话 id 加入该 parent 的 `ownedChildren`。该集合非空时，这个 parent 不能结算或 dispose。顶层 Agent 或其他非继续执行 Agent 没有激活，也不会加入该等待图。 -只有在 child Agent 完全停稳、该 child 持有的每个 child 都已 dispose、best-effort 的最终会话 flush 结算且 child 的 `AgentHandle` 完成 dispose 后，系统才释放 child。管理器会等待 `ctx.sessions.flush(child.session)`，但不解释其参与布尔值：任意 listener 都无法证明所选持久化后端已存储该状态。rejection 会被记录，但不会阻止 handle dispose 或释放所有权，因为保留 child 会让其祖先永久固定在 `waiting`。如果 child 归 parent 所有，管理器随后会通过 `SessionHeader.parentSession` 解析在线 parent，并从其 `ownedChildren` 中移除 child 会话 id。管理器拆卸使用相同的 child-first 顺序。 +只有在 child Agent 完全停稳、其 Inbox 为空、该 child 持有的每个 child 都已 dispose、best-effort 的最终会话 flush 结算、相同结算事实通过 child-lock 重验且 child 的 `AgentHandle` 完成 dispose 后，系统才释放 child。管理器会在关闭准入前等待 `ctx.sessions.flush(child.session)`，但不解释其参与布尔值：任意 listener 都无法证明所选持久化后端已存储该状态。系统会记录 rejection，但不会让它阻止重验、handle dispose 或释放所有权，因为保留 child 会让其祖先永久固定在 `waiting`。如果 child 归 parent 所有，管理器随后会通过 `SessionHeader.parentSession` 解析在线 parent，并从其 `ownedChildren` 中移除 child 会话 id。Manager teardown 使用相同的 child-first 顺序，但会立即关闭准入并停止工作，而不执行自然结算重验。 系统会一直保留所有权，直至 child 激活完成 dispose。后续改进可以更早释放限定到请求的 lease，但这需要精确关联轮次完成，而本 Task-free 设计特意不增加该机制。 顶层拆卸由宿主负责，而不表示为另一次激活。管理器卸载会调用其内部的管理器全局 drain，同步关闭准入，等待每个已获准的物化过程完成发布或回滚，停止稳定的在线森林，并按 child-first 顺序释放。拥有选定顶层 Agent 的宿主使用 `drainContinuableDescendants(parents)`：确切的 Agent 身份只关闭这些根之下的准入，直到每个身份离开注册表，而无关森林和管理器全局准入保持在线；管理器会在第一次 await 之前停止其可见后代，只等待这些根之下已获准的物化过程，并且只释放选定分支。每个已物化的 start 和在线投递都会在与 inbox 提交相同的同步区间内重新检查调用方取消、适用的 draining 作用域、Activation dispose 和确切的 parent 权限，因此只要拆卸或 parent 替换先于接受发生，就会阻止向正在关闭的 handle 投递。只有适用的 drain 结算后，宿主才能 dispose 自己的顶层 Agent；只有管理器全局 drain 会先于管理器作用域 dispose。 -activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 按注册逆序撤销，无法表达动态 child 图。管理器初始化时先注册私有作用域的结构化 disposer，再注册自身的 drain disposer，使逆序撤销先执行 drain、再释放该作用域；如果只在与后续 Agent handle 相同的作用域上注册 cleanup effect，结构化 handle dispose 就可能绕过 child-first 顺序。每个物化过程都会在启动内部事务前注册其屏障参与项，并对其确切的在线祖先建立快照，然后保持跟踪，直到安装 Activation 或完全回滚。Activation 会保留其在这组祖先中的弱成员关系，因此中间 Agent 即使离开注册表，也不会让仍在线的后代脱离宿主根节点的可见范围。每个 Activation 都会在取消或递归回调前安装一个记忆化的 dispose promise，使限定作用域的宿主关闭、全局管理器卸载、child 释放和正常结算能够汇合，而不会重复释放。取消会在等待缓慢的后代清理之前自顶向下传播；handle 释放仍是 child-first。同级分支独立 drain；系统会记录单次 dispose 失败，但仍会尝试其余选中 handle，聚合 drain 则在所有选中分支结算后报告失败。这次进程内拆卸不会销毁持久化 child 会话。 +activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 按注册逆序撤销，无法表达动态 child 图。管理器初始化时先注册私有作用域的结构化 disposer，再注册自身的 drain disposer，使逆序撤销先执行 drain、再释放该作用域；如果只在与后续 Agent handle 相同的作用域上注册 cleanup effect，结构化 handle dispose 就可能绕过 child-first 顺序。每个物化过程都会在启动内部事务前注册其屏障参与项，并对其确切的在线祖先建立快照，然后保持跟踪，直到安装 Activation 或完全回滚。Activation 会保留其在这组祖先中的弱成员关系，因此中间 Agent 即使离开注册表，也不会让仍在线的后代脱离宿主根节点的可见范围。其私有 `SubagentInbox` 会在取消或递归回调前安装一个记忆化的 closing promise，使限定作用域的宿主关闭、全局管理器卸载、child 释放和正常结算能够汇合，而不会重复释放。取消会在等待缓慢的后代清理之前自顶向下传播；handle 释放仍是 child-first。同级分支独立 drain；系统会记录单次 dispose 失败，但仍会尝试其余选中 handle，聚合 drain 则在所有选中分支结算后报告失败。这次进程内拆卸不会销毁持久化 child 会话。 ### 相邻 Agent 消息 共享的 `sendMessage(sender, targetId, content, options)` 服务操作不会增加第二条队列。它接收确切在线 sender，只允许其直接 parent 或直接可继续 child，并通过 Agent inbox 使用固定 Steer 调度。全局 `send_message({ agent_id, message })` 工具在两个方向暴露同一个操作；当 child 可以看到该工具时，其初始任务会标明直接 parent。[相邻 Agent 消息 Agent Note](../architecture/2026-08-27-adjacent-agent-steer-messaging.zh.md)规定其 schema、权限、来源信息与提示词位置。 -### 固定 Steer 调度 +### Agent 与人类调度 -每条已接受的 Agent 消息都使用 `Agent.steer()`。运行中的目标会在最近的 step 边界领取消息；空闲或冷恢复的目标会启动一个轮次。继续执行层不暴露由调用方选择的 quiet、next-turn 或 follow-up 模式。 +每条已接受的 Agent 消息都使用 `Agent.steer()`。运行中的目标会在最近的 step 边界领取消息；空闲或冷恢复的目标会启动一个轮次。浏览器编写的人类输入会另行通过 `subagent.prompt` 携带 `delivery: 'queue' | 'steer'`：Queue 开启后续 FIFO 轮次，Steer 使用相同的 best-effort 最近 step 调度，并保留消息的人类来源。公开服务不为 Agent 消息提供调用方可选的调度模式。 ### 权限与已记录的发送方身份 @@ -133,7 +133,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 宿主和管理器拆卸仍是生命周期停止路径。管理器卸载会全局应用它；宿主只会在自己确切拥有的顶层 Agent 之下应用它。两种形式都会关闭适用的准入作用域，停止选中的可见 Activation，等待该作用域中已获准的物化过程，按 child-first 顺序释放，并保留持久化 Session。 -每个轮次都会请求执行会话持久性检查点，而 Activation 最终结算还会等待 `ctx.sessions.flush()`，将其作为 best-effort 屏障。管理器特意忽略布尔结果，因为 listener 是否参与无法标识持久化后端。rejection 会被记录，但不会改变生命周期结果或宿主 drain 的结果；管理器仍会 dispose handle 并释放所有权，后续恢复时持久化 child 状态可能缺失或陈旧。 +每个轮次都会请求执行会话持久性检查点，而 Activation 最终结算还会在关闭准入前等待 `ctx.sessions.flush()`，将其作为 best-effort 屏障。管理器随后会重新验证 await 期间没有 Agent、Inbox、Session 或 owned-child 状态发生变化；观察发生变化时，系统会重试结算并 flush 更新后的状态。管理器特意忽略 flush 布尔结果，因为 listener 是否参与无法标识持久化后端。系统会记录 rejection，但不会改变生命周期结果或宿主 drain 的结果；管理器仍会执行最终重验，在重验成功时 dispose handle 并释放所有权，后续恢复时持久化 child 状态可能缺失或陈旧。 只有实际写入 child 会话日志的消息，才能在重建时保留提供它的来源；仅被 inbox 接受并不提供重启保证。 @@ -189,13 +189,13 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect - 带有在线所持 child 的空闲 Agent 会产生 `waiting` 激活，其 `AgentHandle` 继续保留。 - 向 `waiting` 投递 `next-turn` 会唤醒同一个激活；完成 dispose 后投递消息会冷恢复新激活。 - 每个由继续执行管理器管理的 parent 激活只会在直接持有的所有 child 激活完成 `AgentHandle` dispose 后进行 dispose；顶层 Agent 不加入等待图。 -- Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。 +- Activation 最终结算会在准入开放时等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，随后在 child lock 内重新验证最终状态，再关闭准入、dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。 - 管理器拆卸会全局关闭准入；拥有选定顶层 Agent 的宿主则只关闭这些确切身份之下的准入，直到这些根离开注册表。两者都会按确切祖先关系跟踪已获准的物化过程，为每个选中的可见 Activation 安装一个记忆化 dispose 截止点，自顶向下传播取消，按 child-first 顺序释放 handle，即使个别分支失败也会等待所有选中分支，之后才 dispose 对应的顶层 Agent 或管理器作用域。 - 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup 钩子贡献一个显式的 child 作用域工具。 - 会话日志只会重建实际写入的消息，并保留每条消息的提供来源；已被 inbox 接受但未写入日志的消息没有重启保证。 - 可继续 subagent 路径不创建或依赖 Task、`JobId`、Task 完成通知、Task 取消或中间的带结果执行包装层。 - 单元覆盖固定 `startContinuable()` 在 inbox 接受消息时的返回边界、每条接受前和生命周期发布失败路径的完整回滚、全局和限定到 parent 作用域的 drain 都会等待夹在 Agent 发布与 Activation 注册之间的物化过程完全停稳、同级森林隔离、中间 Agent 离开注册表后的确切祖先关系、不依赖提供方的冷恢复、冷恢复物化后的最终确切 parent 再授权、接受前后两个阶段的调用方 signal 与拆卸所有权，以及已接受但未写入日志的消息不会自动回放。 -- 单元覆盖固定仅由驻留状态决定的路由表、单 inbox 顺序、通过 inbox 事件关联 `MessageId`、在开放轮次期间 follow-up、等待唤醒、冷恢复、所有权注册与释放、child-first dispose、发送与 dispose 的竞争、没有 listener 和 listener 失败时的 best-effort 最终 flush，以及不存在公开 subagent 取消和 steering。 +- 单元覆盖固定仅由驻留状态决定的路由表、单 inbox 顺序、通过 inbox 事件关联 `MessageId`、在开放轮次期间 follow-up、等待唤醒、冷恢复、所有权注册与释放、child-first dispose、发送与 dispose 的竞争、在最终 flush await 期间接受的直接 Agent 轮次、仅修改 Session 的工作与 maintenance、没有 listener 和 listener 失败时的 best-effort 最终 flush，以及不存在公开 subagent 取消和 steering。 - report 包的单元覆盖会分别固定仅 child 可见性、setup 撤销、权限、投递模式、稳定消息身份和生命周期竞争。 - 一项无密钥整套应用快照覆盖 parent 委派和 follow-up 排队、不存在 subagent steering 和隐式 report 投递、保留 waiting 中的 `AgentHandle` 以及 child-first dispose。另一项 report 快照覆盖可选的显式返回通道。 diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml index 860f113f10..ae2bffad1a 100644 --- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.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-08-06-manager-owned-subagent-settlement-delivery.md -2026-08-06-manager-owned-subagent-settlement-delivery.md: d06245eacd3b7453a031716b1921015a5e38a25c -2026-08-06-manager-owned-subagent-settlement-delivery.zh.md: e5259e97f185203ed77ae9427e5523ac29d4162f +2026-08-06-manager-owned-subagent-settlement-delivery.md: f223571dc91300d085b7fcf0a9e3196daa48b760 +2026-08-06-manager-owned-subagent-settlement-delivery.zh.md: 4bbee373aa2b50902af5319f9398a89da9cc3143 diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md index d06245eacd..f223571dc9 100644 --- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md +++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md @@ -26,9 +26,9 @@ The notice carries `{ kind: 'subagent-settled', form: 'notice', summary, senderS An external `ctx.on('subagent/end')` listener looks more decoupled and is wrong. `SubagentRunEndInfo` names no parent, the child handle is already disposed when the edge fires so the parent cannot be recovered from it, and the ownership release that wakes the parent's own settlement watcher has already run. The manager holds the parent reference throughout disposal, so none of those obstacles exist for it. -**The send happens before `releaseOwnership`.** At that point the parent still counts this child, so `stateOf(parent)` is `waiting` and the parent is structurally unable to be judged settled. Delivering after the release instead races a watcher that resumes one microtask later, finds itself childless and quiet, and disposes an Agent whose `cancel()` clears the very inbox the notice is sitting in. The failure mode is a silently missing message with no error anywhere. +**The send happens before `releaseOwnership`.** At that point the parent's owned-child set still contains this child, so the settlement predicate cannot succeed. Delivering after the release instead races a watcher that resumes one microtask later, finds itself childless and quiet, and disposes an Agent whose `cancel()` clears the very inbox the notice is sitting in. The failure mode is a silently missing message with no error anywhere. -**A resident parent receives it through `admitWaking`.** Registering the message id before the synchronous send is what keeps the window between `followup()` and the microtask that admits it from being read as quiescence. This is not belt-and-braces over the first rule: `Agent.status` folds context maintenance into `idle`, and a waking send behind maintenance only arms a deferred wake, so a parent compacting its context is judged quiet by both `status` and the owned-child set the moment the release lands. +**A resident parent receives it through its private `SubagentInbox`.** The wrapper checks the Activation's closing promise immediately before the synchronous waking send, and the manager renews the wake generation before returning. The final settlement decision rechecks that generation, the Session sequence, the pending Inbox, and the owned-child set under the child lock, then claims the Agent's idle phase through `runMaintenance()` before closing admission. This is not redundant with the first rule: `Agent.status` folds context maintenance into `idle`, and a waking send behind maintenance only arms a deferred wake. Both rules are pinned by tests that fail when the ordering is reversed or the accounting removed. diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md index e5259e97f1..4bbee373aa 100644 --- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md +++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.zh.md @@ -26,9 +26,9 @@ Status: implemented 外部 `ctx.on('subagent/end')` listener 看起来更解耦，但它是错的。`SubagentRunEndInfo` 不指名父级；该边触发时 child handle 已被 dispose，因此无法从中恢复父级；而唤醒父级自身结算 watcher 的所有权释放也已经执行过了。管理器在整个 dispose 过程中都持有父级引用，因此这些障碍对它都不存在。 -**发送发生在 `releaseOwnership` 之前。** 此刻父级仍然计入这个 child，因此 `stateOf(parent)` 为 `waiting`，父级在结构上不可能被判定为已结算。改在释放之后投递，则会与一个在下一个 microtask 恢复的 watcher 竞争：它会发现自己没有 child 且处于静止，于是 dispose 一个 Agent，而该 Agent 的 `cancel()` 会清空正装着这条通知的那个 inbox。失效表现是一条静默丢失的消息，任何地方都不会报错。 +**发送发生在 `releaseOwnership` 之前。** 此刻 parent 的 owned-child set 仍然包含这个 child，因此结算判据不可能成立。改在释放之后投递，则会与一个在下一个 microtask 恢复的 watcher 竞争：它会发现自己没有 child 且处于静止，于是 dispose 一个 Agent，而该 Agent 的 `cancel()` 会清空正装着这条通知的那个 inbox。失效表现是一条静默丢失的消息，任何地方都不会报错。 -**驻留父级通过 `admitWaking` 接收它。** 在同步发送之前登记消息 id，正是让 `followup()` 与承认它的那个 microtask 之间的窗口不被读作静止的原因。这不是对第一条规则的多余保险：`Agent.status` 会把上下文维护折叠成 `idle`，而维护期间的唤醒发送只会预置一次延后唤醒，因此正在压缩上下文的父级，在所有权释放落地的那一刻会同时被 `status` 与已拥有 child 集合判定为静止。 +**驻留 parent 通过私有 `SubagentInbox` 接收它。** 包装层会在同步唤醒发送前立即检查 Activation 的 closing promise，manager 则会在返回前更新 wake generation。最终结算决策会在 child lock 内重新检查该 generation、Session 序号、待处理 Inbox 与 owned-child set，再通过 `runMaintenance()` 占用 Agent 的 idle 阶段，然后关闭准入。这并非对第一条规则的重复保护：`Agent.status` 会把 context maintenance 折叠成 `idle`，而 maintenance 期间的唤醒发送只会预置一次延后唤醒。 两条规则都有测试固定：把顺序反转或去掉记账，测试就会失败。 diff --git a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.i18n.yaml b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.i18n.yaml new file mode 100644 index 0000000000..e8f658dfe7 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.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-08-27-continuable-subagent-human-inbox-control.md +2026-08-27-continuable-subagent-human-inbox-control.md: cf5dfd070dfd600fb64bc529b4a1476a258c1181 +2026-08-27-continuable-subagent-human-inbox-control.zh.md: 081fb84f75afcc94339ae3bf627480081bc56d89 diff --git a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md new file mode 100644 index 0000000000..cf5dfd070d --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md @@ -0,0 +1,51 @@ +# Agent Note: Human inbox controls for continuable subagents + +Status: implemented + +English | [中文](2026-08-27-continuable-subagent-human-inbox-control.zh.md) + +## Problem + +Continuable children use the same Agent loop and inbox as ordinary Agents, but the human delivery path exposed only FIFO follow-up. The Client discarded its existing Queue/Steer choice when it selected the dedicated subagent prompt Remote, and the generic Session ownership fence rejected every queue mutation for a subagent-owned identity. The browser therefore hid controls that the live child inbox already supported. + +Opening generic Session control indiscriminately would weaken the subagent ownership rule. Prompt delivery still needs exact live direct-parent authorization and cold-resume accounting, while queue mutation must reject one-shot, unknown, corrupt, and cold children. A valid continuable descriptor in the child's own log suffix identifies which live subagent-owned Sessions may use occurrence mutation. Settlement must also retain an idle Agent while a delivery a driver will claim is still pending, and must not tear down an Agent that claimed the idle phase for a maintenance task after `whenIdle()` resolved. + +## Decision + +A live continuable child exposes the ordinary human inbox controls without adding another queue, Remote endpoint, queue action, or Host-facing subagent operation. One-shot children remain read-only. + +The existing `SubagentPromptRequest` carries `delivery: 'queue' | 'steer'`. The Client forwards the mode already selected by `Session.prompt(content, mode)` through `subagent.prompt`. The Remote still requires the exact live direct parent and then uses one package-internal continuation-manager delivery operation. Queue calls `Agent.followup(message)`; steer calls `Agent.steer(message)`. Both paths share child locking, cold resume, final parent reauthorization, caller-signal cutoff, `MessageId` creation, rollback, and disposal-race handling. This human choice adds no public scheduling method or model tool; the separately owned `sendMessage()` and model-facing `send_message` operation keep their fixed adjacent-Agent Steer semantics. + +The browser gives a continuable child the ordinary busy Enter/Cmd+Enter Queue/Steer preference, QueueDock Edit/Remove/Steer actions, and empty-draft steer-all gesture. Send and Stop remain independent controls. Composer prompts still require the live parent because their Remote mints new admitted work. QueueDock mutations address already-live inbox work directly, so they remain available when the parent is offline; the parent-offline composer stays locked. + +The existing `session.updateQueue(itemId, action)` resolves the exact live Agent and admits a subagent-owned Session only when its current projected identity is continuable and the descriptor sequence belongs to the child's own non-seed suffix. A live one-shot Agent and a missing, inherited-only, or invalid identity retain the ownership failure. An absent Agent returns `queue-item-not-found` and does not cold-resume the child. The target Session id is sufficient human authority for a live inbox occurrence mutation; a parent address is not required. Edit and Remove retain their complete existing `nextTurn` and `nextStep` semantics, including plugin-injected context, while Steer requires a queued occurrence and an Agent that reports running when the command begins. + +The continuation manager keeps no second message-reservation state. One private `SubagentInbox` delegates Queue and Steer to the Agent inbox and owns the Activation's existing closing promise. Natural settlement waits for `Agent.whenIdle()`, an empty child Inbox, and disposal of every owned child. The manager confirms the Inbox, owned-child set, and wake generation under the child lock, then flushes final Session state while admission remains open. The final child-lock decision revalidates the Session sequence and the same residency facts, then synchronously starts an `Agent.runMaintenance()` task whose entry claims the idle phase and closes the wrapper in the same JavaScript turn. Every pending Inbox occurrence retains the Activation regardless of its delivery mode or provenance. Manager-owned deliveries, Inbox claims or discards, and owned-child release renew the wake generation. Direct Agent work accepted during the flush either changes the final Session or residency observation, remains active and prevents the final maintenance task from starting, or completes before revalidation. + +QueueDock Steer uses the Agent's best-effort delivery after the command admits a running queued occurrence. If the queued occurrence was claimed first, `queue-item-not-found` leaves its ordinary Queue delivery underway. If active cancellation wins during the synchronous transfer, Agent steering appends the message to `nextTurn`, latches a wake, and the Session command still succeeds. The selected message moves behind the remaining Queue in that fallback case. Newly composed Steer uses the same fallback and remains deliverable when it misses the nearest step. + +This decision partially supersedes the human-control exclusions in [Web subagent catalog and human continuation](2026-07-27-web-subagent-conversations.md), [Continuable subagents](2026-07-28-continuable-subagent-conversations.md), [Steer a queued Web message](../../archived/feature/2026-07-30-web-queue-steer-action.md), and [Steer the whole Web queue with an empty-draft Cmd/Ctrl+Enter](../../archived/feature/2026-08-06-web-queue-steer-all-gesture.md). The active records own catalog authorization and Activation lifecycle; the archived records preserve the original QueueDock Steer and gesture decisions. + +## Alternatives considered + +**Add `SubagentRuntime.steer()` and a new Remote.** Rejected because human prompt delivery already has a mode-bearing Client method and one authenticated Remote. A new public operation would expand both the service and model-adjacent surface without adding an execution primitive. + +**Add `subagents.updateQueue`.** Rejected because `session.updateQueue` already owns exact inbox occurrence mutation and its race failures. The projected continuable identity provides the narrow ownership-fence exception without adding another operation. + +**Route every subagent control through generic Session APIs.** Rejected because prompt and cancellation require subagent lineage authorization, cold-resume accounting, and dedicated failure mapping. Only live inbox occurrence mutation has enough target-local state to use the narrow ownership-fence exception. + +**Restrict continuable queue mutation to `nextTurn`.** Rejected because human inbox parity intentionally includes editing or removing pending steering and injected context. If a plugin needs a stronger transaction around its `nextStep` input, that protection belongs to the shared Agent inbox semantics rather than a subagent-only restriction. + +**Track waking work by `MessageId` and transfer that record across mutation.** Rejected because it duplicates the Inbox's pending set with a second activity ledger and couples residency to occurrence identity. `whenIdle()` waits for existing Agent activity, `Inbox.hasPending` conservatively retains every occurrence, the Activation generation invalidates stale observations, and the final maintenance task atomically joins idle ownership to admission closure. This choice can retain quiet injected context, but it avoids both an additional mutation protocol and silent loss of accepted steering. + +**Derive residency from `MessageSource.kind`, treating `plugin` as parked context.** Rejected because `kind` records who produced a message, not how it was delivered, and `MessageSourceMap` is merge-extensible. Plugins steer with a plugin source (`cordis-host-runner` failure reports, blocking Stop hooks) and hosts inject with non-plugin sources (`dsh-experimental-agent-team` quiet mail), so the correspondence fails in both directions. Treating all pending occurrences alike avoids that unsupported inference. + +## Consequences + +Continuable child conversations and ordinary Sessions share one human inbox interaction model and one Agent-loop queue. Human steering can affect a resident or cold-resumed child without changing public model controls. QueueDock remains useful for a live child after its parent goes offline, while new messages continue to respect direct-parent authorization. + +The generic Session command has one narrow ownership-fence exception for a live subagent-owned Agent with a valid own-suffix continuable identity. Because the operation addresses either inbox destination, a caller that knows a pending `MessageId` can edit or remove plugin-supplied next-step input, exactly as on an ordinary Session. QueueDock renders only `queued`-placement rows, so no browser gesture reaches that input; an edit there also keeps the original producer's `MessageSource`, which would attribute human text to that producer. + +Inbox notifications retain their occurrence semantics and do not carry continuation residency. Claim and discard notifications only wake settlement after pending work changes; `whenIdle()`, the final idle-phase maintenance task, `Inbox.hasPending`, the owned-child set, the Activation generation, and the Session sequence decide whether disposal is safe without depending on scheduler ordering, message identity, or provenance. The final flush precedes the closing cutoff, so a detached hook, job completion, or direct Agent delivery accepted during that await invalidates the observation instead of being stopped by the resulting disposal. Maintenance that remains active prevents the final task from claiming the idle phase; maintenance that starts and finishes during the flush has completed before disposal. A child left holding only injected context remains resident even though no driver is obliged to claim it; without a later waking delivery, queue removal, or manager teardown, that child and its live ancestors can remain resident for the process lifetime. A replayed Inbox follows the same conservative rule without reconstructing how each pending message was delivered. + +Model-side scheduling remains fixed rather than caller-selectable. The adjacent-Agent `send_message` tool always uses Steer, while only the browser human path chooses Queue or Steer. diff --git a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md new file mode 100644 index 0000000000..081fb84f75 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md @@ -0,0 +1,51 @@ +# Agent Note: 可继续 subagent 的人类 inbox 控制 + +Status: implemented + +[English](2026-08-27-continuable-subagent-human-inbox-control.md) | 中文 + +## 问题 + +可继续子级与普通 Agent 使用相同的 agent loop（智能体循环）和 inbox，但人类投递路径只公开 FIFO 后续轮次。Client 选择专用 subagent prompt Remote 时会丢弃既有的 Queue／Steer 选择，通用 Session ownership fence 又拒绝 subagent 所有身份的全部 queue 变更。因此，浏览器隐藏了在线子级 inbox 已经支持的控制。 + +无差别开放通用 Session 控制会削弱 subagent 所有权规则。Prompt 投递仍需要确切在线直接父级鉴权与冷恢复记账，而 queue 变更必须拒绝一次性、未知、损坏和冷子级。child 自身 log suffix 中的有效 continuable descriptor 可标识哪些在线 subagent-owned Session 能使用 occurrence mutation。Settlement 还必须在 idle Agent 仍有会被 driver 认领的待投递工作时保留该 Agent，也不得拆除在 `whenIdle()` 兑现后才占用 idle 阶段执行 maintenance 任务的 Agent。 + +## 决策 + +在线可继续子级公开普通的人类 inbox 控制，不增加另一套 queue、Remote endpoint、queue action 或面向 Host 的 subagent 操作。一次性子级继续只读。 + +现有 `SubagentPromptRequest` 携带 `delivery: 'queue' | 'steer'`。Client 把 `Session.prompt(content, mode)` 已选出的 mode 经 `subagent.prompt` 原样转发。Remote 仍要求确切在线直接父级，随后使用一个包内 continuation manager 投递操作。Queue 调用 `Agent.followup(message)`；steer 调用 `Agent.steer(message)`。两条路径共享 child lock、冷恢复、最终父级重新鉴权、调用方 signal 截止、`MessageId` 创建、回滚与 dispose 竞态处理。该人类选择不新增公开调度方法或模型工具；由其他决策拥有的 `sendMessage()` 与面向模型的 `send_message` 操作保留固定的相邻 Agent Steer 语义。 + +浏览器为可继续子级提供普通的繁忙态 Enter／Cmd+Enter Queue／Steer 偏好、QueueDock Edit／Remove／Steer 操作，以及空草稿 steer-all 手势。Send 与 Stop 继续是独立控制。Composer prompt 会创建新的已准入工作，因此仍要求在线父级。QueueDock 变更直接寻址已经在线的 inbox 工作，所以父级离线时仍可使用；父级离线的 composer 继续锁定。 + +现有 `session.updateQueue(itemId, action)` 会解析确切在线 Agent，并且只有 subagent-owned Session 的当前 projected identity 为 continuable、descriptor 序号属于 child 自身的非 seed suffix 时才会准入。在线 one-shot Agent 以及缺失、仅继承或无效的 identity 都会继续触发所有权失败。Agent 不存在时返回 `queue-item-not-found`，且不会冷恢复子级。对在线 inbox occurrence 变更而言，目标 Session id 已是充分的人类权限；无需 parent 地址。Edit 与 Remove 保留既有完整 `nextTurn` 和 `nextStep` 语义，包括插件注入的 context；Steer 要求排队 occurrence，且 command 开始时 Agent 必须报告 running。 + +Continuation manager 不保留第二套消息 reservation 状态。一个私有 `SubagentInbox` 会把 Queue 与 Steer 委托给 Agent inbox，并持有 Activation 既有的 closing promise。自然结算会等待 `Agent.whenIdle()`、child Inbox 为空以及所拥有的每个子级完成 dispose。管理器会在 child lock 内确认 Inbox、owned-child set 与 wake generation，再在准入保持开放时 flush 最终 Session 状态。最终 child-lock 决策会重新验证 Session 序号与相同的驻留事实，然后同步启动一个 `Agent.runMaintenance()` 任务；该任务的入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭包装层。每个待处理 Inbox occurrence 都会保留 Activation，无论其投递模式或来源如何。由 manager 所有的投递、Inbox claim 或 discard，以及所拥有子级的释放都会更新 wake generation。flush 期间直接接受的 Agent 工作要么改变最终 Session 或驻留观察，要么保持活跃并阻止最终 maintenance 任务启动，要么在重验前完成。 + +QueueDock Steer 在 command 准入一个正在运行的排队 occurrence 后，采用 Agent 的 best-effort 投递。如果排队 occurrence 先被 claim，`queue-item-not-found` 表示其普通 Queue 投递已经开始。如果活跃取消在同步转移期间先发生，Agent steering 会把消息追加到 `nextTurn`、锁存唤醒，Session command 仍然成功。在该 fallback 情况下，选中消息会移到 Queue 剩余项之后。新组合的 Steer 使用同样的 fallback，错过最近步骤时仍保证可投递。 + +本决策部分取代 [Web subagent 目录与人类 continuation](2026-07-27-web-subagent-conversations.zh.md)、[可继续 subagent](2026-07-28-continuable-subagent-conversations.zh.md)、[Steer Web 已排队消息](../../archived/feature/2026-07-30-web-queue-steer-action.md)和[用空草稿 Cmd/Ctrl+Enter steer 整个 Web queue](../../archived/feature/2026-08-06-web-queue-steer-all-gesture.md)中的人类控制排除项。活跃记录拥有目录鉴权与 Activation 生命周期；归档记录保留最初的 QueueDock Steer 与手势决策。 + +## 考虑过的替代方案 + +**新增 `SubagentRuntime.steer()` 与 Remote。** 拒绝，因为人类 prompt 投递已经拥有带 mode 的 Client 方法和一个已鉴权 Remote。新的公开操作会扩大 service 与模型相邻接口，却不增加执行原语。 + +**新增 `subagents.updateQueue`。** 拒绝，因为 `session.updateQueue` 已经拥有准确 inbox occurrence 变更及其竞态失败。Projected continuable identity 提供狭窄的 ownership-fence 例外，无需新增操作。 + +**把所有 subagent 控制都路由到通用 Session API。** 拒绝，因为 prompt 与取消需要 subagent 血缘鉴权、冷恢复记账与专用失败映射。只有在线 inbox occurrence 变更拥有足够的目标本地状态，可使用狭窄的 ownership-fence 例外。 + +**把可继续 queue 变更限制在 `nextTurn`。** 拒绝，因为人类 inbox 对齐有意包括编辑或删除待处理 steering 与注入 context。如果插件需要围绕其 `nextStep` 输入建立更强事务，该保护应属于共享 Agent inbox 语义，而非 subagent 专属限制。 + +**按 `MessageId` 跟踪唤醒工作，并在 mutation 中转移该记录。** 拒绝，因为这会用第二套活动账本重复 Inbox 的待处理集合，并让驻留依赖 occurrence 身份。`whenIdle()` 会等待既有 Agent 活动，`Inbox.hasPending` 保守地保留每个 occurrence，Activation generation 会让过期观察失效，而最终 maintenance 任务则以原子方式衔接 idle ownership 与准入关闭。这项选择可能保留静默注入的 context，但既避免额外的 mutation 协议，也避免静默丢失已接受的 steering。 + +**用 `MessageSource.kind` 推导驻留，把 `plugin` 视为停放 context。** 拒绝，因为 `kind` 记录的是消息由谁产生，而非如何投递，且 `MessageSourceMap` 可合并扩展。插件会以 plugin 来源 steer（`cordis-host-runner` 的失败报告、阻断式 Stop hook），host 也会以非 plugin 来源 inject（`dsh-experimental-agent-team` 的静默邮件），因此该对应关系在两个方向上都不成立。统一对待所有待处理 occurrence 可以避免这种没有依据的推断。 + +## 结果 + +可继续子级会话与普通 Session 共享一套人类 inbox 交互模型和一套 Agent-loop queue。人类 steering 可以影响驻留或冷恢复的子级，而不改变公开模型控制。父级离线后，QueueDock 对在线子级仍有用；新消息则继续遵守直接父级鉴权。 + +通用 Session command 为拥有有效自身 suffix continuable identity 的在线 subagent-owned Agent 提供一个狭窄的 ownership-fence 例外。因为该操作可寻址两个 inbox 目标，知道待处理 `MessageId` 的调用方可以像操作普通 Session 一样，编辑或删除插件提供的 next-step 输入。QueueDock 只渲染 `queued` placement 的行，因此没有浏览器手势能到达该输入；在那里编辑还会保留原产出方的 `MessageSource`，从而把人类文本归属给该产出方。 + +Inbox notification 保留 occurrence 语义，不携带 continuation 驻留状态。Claim 与 discard notification 只负责在待处理工作变化后唤醒 settlement；`whenIdle()`、最终 idle 阶段 maintenance 任务、`Inbox.hasPending`、owned-child set、Activation generation 与 Session 序号无需依赖调度顺序、消息身份或来源即可决定何时安全 dispose。最终 flush 位于 closing cutoff 之前，因此 detached hook、job completion 或直接 Agent 投递只要在该 await 期间被接受，就会让观察失效，而不会被随后发生的 dispose 停止。仍然活跃的 maintenance 会阻止最终任务占用 idle 阶段；在 flush 期间开始并结束的 maintenance 已在 dispose 前完成。仅持有被注入 context 的 child 即使没有 driver 必须认领它，也会保持驻留；如果之后没有唤醒投递、queue removal 或 manager teardown，该 child 及其在线祖先可以在进程生命周期内一直驻留。重放出的 Inbox 遵循同一条保守规则，无需重建每条待处理消息的投递方式。 + +模型侧调度保持固定，不由调用方选择。相邻 Agent 的 `send_message` 工具始终使用 Steer，只有浏览器人类路径选择 Queue 或 Steer。 diff --git a/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.i18n.yaml b/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.i18n.yaml index 28b23cf5f9..79c0b25705 100644 --- a/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.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/process/2026-08-18-in-job-partitioned-coverage.md -2026-08-18-in-job-partitioned-coverage.md: ef22245354bbeb26d551e227a6b5ca26ca22306c -2026-08-18-in-job-partitioned-coverage.zh.md: 67b434a8559f32da5bd2f863f526ce2b10e36b4c +2026-08-18-in-job-partitioned-coverage.md: 8a3eb202255ecbf680dfa0af656fd5b89e958001 +2026-08-18-in-job-partitioned-coverage.zh.md: e7ca2692485fa4f9f0135821963e64347c3cdfdd diff --git a/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.md b/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.md index ef22245354..8a3eb20225 100644 --- a/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.md +++ b/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.md @@ -30,7 +30,7 @@ A normal failed test still emits a blob through `--coverage.reportOnFailure`, al `scripts/coverage-partitions.spec.ts` pins argument construction, package-script separator removal, one-worker partitions, weighted longest-processing-time assignment (including a case that fails when assignment ignores recorded weights), the single merged threshold command, failed-test merging, failure diagnostics before complete-blob validation, waiting for sibling partitions after a spawn failure, and link-safe cleanup. `scripts/run-gates.spec.ts` pins opt-in selection, invalid-count rejection, both native Windows coverage gates' complete-build dependency, the complete Windows inventory with its blocking split, and unbuffered streamed output. React fake-timer cases that can move between partitions advance timers inside `act()`; geometry-dependent portal tests stub their element rectangles so a different shard schedule cannot turn deferred updates or jsdom coordinates into coverage-only failures. -Completed native Windows comparisons measured two partitions near 405 seconds and sixteen partitions at 112.66–122.01 seconds under the earlier gate ordering; those values compare partition latency, not the current peak. The current coverage phase runs four instrumented partition processes beside two exempt workers, for six coverage execution units. Sixteen partitions would raise that phase to eighteen before any still-running production-site work or system overhead. Four partitions keep separate-process isolation and match Linux, at the cost of a longer single-job coverage wall time; the trade-off is accepted to reduce vitest worker startup failures under high self-hosted concurrency. Two Linux samples measured the conservative two-partition configuration at 276.68 and 282.27 seconds; that configuration was stable but halved the ordinary path's four instrumented workers. Four partitions restore that fan-out, for six total coverage execution units on the 16-core hosted runner and at most 36 across the failover VM's six runner instances. These values come from completed runs or fixed capacity bounds; an unfinished run crossing an arbitrary elapsed-time mark is not evidence for increasing concurrency. +Completed native Windows comparisons measured two partitions near 405 seconds and sixteen partitions at 112.66–122.01 seconds under the earlier gate ordering; those values compare partition latency, not the current peak. The current coverage phase runs four instrumented partition processes beside two exempt workers, for six coverage execution units. Sixteen partitions would raise that phase to eighteen before any still-running production-site work or system overhead. Four partitions keep separate-process isolation and match Linux, at the cost of a longer single-job coverage wall time; the trade-off is accepted to reduce vitest worker startup failures under high self-hosted concurrency. Two Linux samples measured the conservative two-partition configuration at 276.68 and 282.27 seconds; that configuration was stable but halved the ordinary path's four instrumented workers. Four partitions restore that fan-out, for six total coverage execution units on the 16-core hosted runner and at most 192 across the failover VM's 32 runner instances. These values come from completed runs or fixed capacity bounds; an unfinished run crossing an arbitrary elapsed-time mark is not evidence for increasing concurrency. ## Alternatives considered diff --git a/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.zh.md b/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.zh.md index 67b434a855..e7ca269248 100644 --- a/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.zh.md +++ b/.agents/notes/implemented/process/2026-08-18-in-job-partitioned-coverage.zh.md @@ -30,7 +30,7 @@ Status: implemented `scripts/coverage-partitions.spec.ts` 固定了参数构造、包脚本分隔符移除、单 worker 分区、加权最长处理时间分配（含一个在分配忽略记录权重时必然失败的用例）、唯一一次合并阈值命令、失败测试合并、完整 blob 校验前的失败诊断、spawn 失败后等待兄弟分区，以及链接安全清理。`scripts/run-gates.spec.ts` 固定了显式启用、非法数量拒绝、两道原生 Windows 覆盖率门禁对完整构建的依赖、完整 Windows 清单及其阻断性划分，以及不缓冲的流式输出。可能在分区间移动的 React fake-timer 用例会在 `act()` 内推进计时器；依赖几何位置的 portal 测试会固定元素矩形，使不同分片调度不会把延迟更新或 jsdom 坐标变成只在覆盖率运行中出现的失败。 -已完成的原生 Windows 对比中，双分区耗时约 405 秒，16 分区耗时 112.66–122.01 秒；这些数据来自先前的门禁顺序，只用于比较分区延迟，不代表当前峰值。当前的覆盖率阶段会让 4 个插桩分区进程与 2 个豁免 worker 并行，共形成 6 个覆盖率执行单元。若改为 16 个分区，则在尚未结束的生产网站工作或系统开销计入之前，该阶段就会达到 18 个执行单元。4 个分区保留独立进程隔离并与 Linux 对齐，代价是单 job 覆盖率墙钟更长；这是为了降低自托管高并发下 vitest worker 启动失败而接受的取舍。两个 Linux 样本中，保守的双分区配置耗时 276.68 秒和 282.27 秒；该配置运行稳定，却把普通路径原有的 4 个插桩 worker 减半。4 个分区恢复这份并发，使 16 核托管 runner 上的覆盖率执行单元总数为 6，故障切换虚拟机的 6 个 runner 实例最多合计 36 个执行单元。这些数值来自完整运行或固定容量上限；运行尚未结束时跨过任意耗时刻度，不构成增加并发的证据。 +已完成的原生 Windows 对比中，双分区耗时约 405 秒，16 分区耗时 112.66–122.01 秒；这些数据来自先前的门禁顺序，只用于比较分区延迟，不代表当前峰值。当前的覆盖率阶段会让 4 个插桩分区进程与 2 个豁免 worker 并行，共形成 6 个覆盖率执行单元。若改为 16 个分区，则在尚未结束的生产网站工作或系统开销计入之前，该阶段就会达到 18 个执行单元。4 个分区保留独立进程隔离并与 Linux 对齐，代价是单 job 覆盖率墙钟更长；这是为了降低自托管高并发下 vitest worker 启动失败而接受的取舍。两个 Linux 样本中，保守的双分区配置耗时 276.68 秒和 282.27 秒；该配置运行稳定，却把普通路径原有的 4 个插桩 worker 减半。4 个分区恢复这份并发，使 16 核托管 runner 上的覆盖率执行单元总数为 6，故障切换虚拟机的 32 个 runner 实例最多合计 192 个执行单元。这些数值来自完整运行或固定容量上限；运行尚未结束时跨过任意耗时刻度，不构成增加并发的证据。 ## 曾考虑的替代方案 diff --git a/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.i18n.yaml b/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.i18n.yaml new file mode 100644 index 0000000000..4fd1361ca9 --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.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/process/2026-08-28-ci-node-compile-cache-data-disk.md +2026-08-28-ci-node-compile-cache-data-disk.md: 3f5f7eb2f00a37b635b63093f60c66688b82316b +2026-08-28-ci-node-compile-cache-data-disk.zh.md: c55a6c73cf98f0dd0b31b50d64e7937ee9e14305 diff --git a/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md b/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md new file mode 100644 index 0000000000..3f5f7eb2f0 --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md @@ -0,0 +1,43 @@ +# Agent Note: Redirect the Node compile cache to the data-volume runner temp + +Status: implemented + +English | [中文](2026-08-28-ci-node-compile-cache-data-disk.zh.md) + +## Problem + +The self-hosted Linux CI VM (`vm-backup` pool, 32 runner instances on one host) exhausts the root partition's inode capacity. Issue #3134's residue (`/tmp/dsh-*`) is one source; a second, larger source is the Node.js module compile cache. Tools in the CI toolchain call `module.enableCompileCache()` explicitly: pnpm 11.7.0 enables the cache in its entry (`module.enableCompileCache?.()` in `bin/pnpm.mjs`) on every invocation, and TypeScript does so in `tsc`/`tsserver`; vitest forwards the API but does not enable it itself. Every such call writes the serialized V8 bytecode cache under `os.tmpdir()/node-compile-cache`. On the shared VM that is the root partition's `/tmp`: measured 2026-08-28 at **697,389 inodes and 9.2 GB**, with 34,110 files younger than 1 hour — the cache grows on every CI run and is never cleaned, so the root partition's 3,276,800 inodes trend toward exhaustion even after the `dsh-*` residue is controlled. + +## Decision + +Each Linux lane that can run on the `vm-backup` pool under failover (`ci.yml` static/coverage/snapshots — hosted by default, self-hosted only when `DSH_CI_FAILOVER_LINUX=selfhosted` — and `ci-master.yml` serial standby, always self-hosted) redirects `NODE_COMPILE_CACHE` to the per-runner data-volume temp dir `${{ runner.temp }}/node-compile-cache`. `runner.temp` lives on `/data_local` (1 TB, ~1% inode used) and is per-runner (`_workNN/_temp`), so the cache stops consuming root-partition inodes. + +The redirect is a step right after `actions/checkout` that writes `NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache` into `$GITHUB_ENV`, so every later step in the lane — `pnpm/action-setup`, the store-path probe, install, Playwright install, and the test gate — inherits it. Injection is required because the `runner` context is unavailable in job-level `env` (the same constraint as the earlier TMPDIR work), and a step-level env on the gate step alone would leave the earlier pnpm calls writing to the root partition's `/tmp`. A confined child (bwrap/Landlock) whose sandbox does not grant the `runner.temp` path inherits the variable but **silently skips caching** — verified on the VM: with `NODE_COMPILE_CACHE` pointing at an ungranted path inside bwrap, `node` runs normally (exit 0), unlike `mkdtemp` which fails hard with a read-only filesystem error. The compile cache is best-effort by design; a failed write is a cache miss, not a crash. + +## Verification + +- VM probe: `NODE_COMPILE_CACHE=/data_local/ci/compile-cache-probe node -e 'require("node:fs")'` wrote a `v22.23.2-x64-*` cache subdirectory on the data disk (location switch effective). +- VM probe (bwrap): with `NODE_COMPILE_CACHE` set to a path the bwrap profile does not grant, `node` ran normally (exit 0) — cache write failure is tolerated. +- `scripts/ci-workflow.spec.ts` asserts every Linux lane injects `NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache` (a `$GITHUB_ENV` `KEY=VALUE` line) into `$GITHUB_ENV` before `pnpm/action-setup`; the position assertion fails if the injection moves after the first pnpm call. +- CI lanes: the three required Linux jobs (hosted by default, self-hosted `vm-backup` under `DSH_CI_FAILOVER_LINUX`) run the full suite under the new env; a regression in cache handling would surface as lane failure. + +## Alternatives considered + +### Why not disable the compile cache entirely? + +`NODE_DISABLE_COMPILE_CACHE=1` would stop root-partition growth immediately but forfeit the startup speedup on every run, and the cache is a legitimately useful Node feature (enabled explicitly by pnpm and TypeScript). Redirecting preserves the benefit while moving the cost off the constrained partition. + +### Why not add `node-compile-cache` to the `dsh-*` residue sweep? + +The CI sweep (added in the residue-cleanup change) targets test residue; the compile cache is a cache, not residue. Deleting it every run would discard the speedup the cache exists to provide. Redirecting is the structural fix: the cache's growth moves to the volume sized for it. + +### Why not job-level env or gate-step env only? + +The `runner` context is only available in step-level `env`; job-level `env` evaluates it to an empty string (GitHub contexts-availability), which would silently leave the cache on the root partition. A step-level env on the gate step alone would cover only that step: every earlier pnpm invocation in the lane (setup, store-path probe, install) would still write to the root partition's `/tmp`. Injecting into `$GITHUB_ENV` in a step between checkout and `pnpm/action-setup` sets the variable before the lane's first pnpm call, so one step covers the whole lane. + +## Consequences + +- **Bought**: the Node compile cache stops consuming root-partition inodes; inode pressure from this source is removed without losing the cache's startup benefit. The cache now lives in per-runner `_workNN/_temp` on the data volume. +- **Cost**: the cache accumulates in `runner.temp`, which the runner does not empty between jobs (measured earlier) — but on the data volume (~1% inode used) that is harmless. +- **Cost**: confined children without the `runner.temp` grant skip caching for their own `node` invocations; this is a cache miss, not a failure, and matches Node's best-effort contract. +- **Cost**: the change touches CI configuration only; local development keeps the default `os.tmpdir()` location. diff --git a/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.zh.md b/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.zh.md new file mode 100644 index 0000000000..c55a6c73cf --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.zh.md @@ -0,0 +1,43 @@ +# Agent Note: 将 Node 编译缓存重定向到数据卷 runner 临时目录 + +Status: implemented + +[English](2026-08-28-ci-node-compile-cache-data-disk.md) | 中文 + +## 问题 + +自托管 Linux CI 虚拟机（`vm-backup` 池，32 个 runner 实例共宿一机）的根分区 inode 正在耗尽。issue #3134 的残留（`/tmp/dsh-*`）是来源之一；第二个、更大的来源是 Node.js 模块编译缓存。CI 工具链中的工具显式调用 `module.enableCompileCache()`：pnpm 11.7.0 在入口（`bin/pnpm.mjs` 中的 `module.enableCompileCache?.()`）每次调用都启用缓存，TypeScript 在 `tsc`/`tsserver` 中启用；vitest 转发该 API 但自身不启用。每次这样的调用都把序列化 V8 字节码缓存写到 `os.tmpdir()/node-compile-cache`。在共享虚拟机上即根分区的 `/tmp`：2026-08-28 实测为 **697,389 个 inode、9.2 GB**，其中 34,110 个文件不足 1 小时——缓存每次 CI 运行都在增长且从不清理，即使 `dsh-*` 残留被控制，根分区 3,276,800 个 inode 仍趋向耗尽。 + +## 决策 + +每个可能运行在 `vm-backup` 池的 Linux lane（`ci.yml` static/coverage/snapshots——默认 hosted，仅 `DSH_CI_FAILOVER_LINUX=selfhosted` 时自托管；`ci-master.yml` serial standby——始终自托管）都把 `NODE_COMPILE_CACHE` 重定向到 per-runner 数据卷临时目录 `${{ runner.temp }}/node-compile-cache`。`runner.temp` 在 `/data_local`（1 TB，inode 用量约 1%）上，per-runner（`_workNN/_temp`），因此缓存不再消耗根分区 inode。 + +重定向是在 `actions/checkout` 之后的一个 step，把 `NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache` 写入 `$GITHUB_ENV`，因此 lane 中后续每个 step——`pnpm/action-setup`、store 路径探测、安装、Playwright 安装和测试门禁——都会继承该变量。必须用注入而非 job 级 env：`runner` 上下文在 job 级 `env` 不可用（与早前 TMPDIR 工作相同的约束）；而仅给门禁 step 设 step 级 env 会让更早的 pnpm 调用继续写根分区 `/tmp`。sandbox（bwrap/Landlock）未授权 `runner.temp` 路径的受限子进程会继承该变量但**静默跳过缓存**——已在虚拟机上验证：`NODE_COMPILE_CACHE` 指向 bwrap 内未授权路径时，`node` 正常运行（exit 0），与 `mkdtemp` 的只读文件系统硬失败不同。编译缓存按设计是尽力而为；写失败只是缓存未命中，不是崩溃。 + +## 验证 + +- VM 探针：`NODE_COMPILE_CACHE=/data_local/ci/compile-cache-probe node -e 'require("node:fs")'` 在数据盘写出了 `v22.23.2-x64-*` 缓存子目录（位置切换生效）。 +- VM 探针（bwrap）：`NODE_COMPILE_CACHE` 指向 bwrap profile 未授权的路径时，`node` 正常运行（exit 0）——缓存写失败被容忍。 +- `scripts/ci-workflow.spec.ts` 断言每个 Linux lane 都在 `pnpm/action-setup` 之前把 `NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache`（`$GITHUB_ENV` 的 `KEY=VALUE` 行）注入 `$GITHUB_ENV`；位置断言在注入移出首次 pnpm 调用之后时会失败。 +- CI lane：三个必需的 Linux job（默认 hosted，`DSH_CI_FAILOVER_LINUX` 时自托管 `vm-backup`）会在新 env 下跑完整套件；缓存处理回归会表现为 lane 失败。 + +## 备选方案 + +### 为什么不彻底禁用编译缓存？ + +`NODE_DISABLE_COMPILE_CACHE=1` 会立即停止根分区增长，但会放弃每次运行的启动加速，而缓存是 Node 正当有用的特性（由 pnpm 和 TypeScript 显式启用）。重定向在保留收益的同时把成本移出受限分区。 + +### 为什么不把 `node-compile-cache` 纳入 `dsh-*` 清理？ + +CI 清理（残留清理改动中新增）针对测试残留；编译缓存是缓存而非残留。每次运行删掉它会丢弃缓存本要提供的加速。重定向是结构性修复：缓存的增长移到为它准备的卷上。 + +### 为什么不用 job 级 env 或只给门禁 step 设 env？ + +`runner` 上下文只在 step 级 `env` 可用；job 级 `env` 会求值为空字符串（GitHub contexts-availability），静默让缓存留在根分区。只给门禁 step 设 step 级 env 也只覆盖那一个 step：lane 中更早的每次 pnpm 调用（setup、store 路径探测、安装）仍会写根分区 `/tmp`。在 checkout 与 `pnpm/action-setup` 之间的 step 注入 `$GITHUB_ENV`，使变量在 lane 首次 pnpm 调用之前生效，一个 step 即可覆盖整条 lane。 + +## 后果 + +- **买到**：Node 编译缓存不再消耗根分区 inode；该来源的 inode 压力被移除且不损失缓存的启动收益。缓存现在位于数据卷上的 per-runner `_workNN/_temp`。 +- **代价**：缓存在 `runner.temp` 累积，而 runner 不会在 job 之间清空它（早前实测）——但在数据卷（inode 用量约 1%）上无碍。 +- **代价**：没有 `runner.temp` 授权的受限子进程会为其自身的 `node` 调用跳过缓存；这是缓存未命中而非失败，符合 Node 的尽力而为契约。 +- **代价**：改动只涉及 CI 配置；本地开发保持默认 `os.tmpdir()` 位置。 diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.i18n.yaml new file mode 100644 index 0000000000..5f3f78b3bf --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.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-09-06-agent-request-freeze-provenance.md +2026-09-06-agent-request-freeze-provenance.md: 7a4816df61f6490647aba6f0603719e1b4662a20 +2026-09-06-agent-request-freeze-provenance.zh.md: 239d7e69df1596010ef0f3c8789250f654a75cb1 diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md new file mode 100644 index 0000000000..7a4816df61 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md @@ -0,0 +1,65 @@ +# Agent Note: Reuse only loop-proven message freezes + +Status: implemented + +English | [中文](2026-09-06-agent-request-freeze-provenance.zh.md) + +## Problem + +Long tool conversations repeatedly traverse immutable history while constructing requests. The [backend continuation baseline](../testing/2026-09-06-backend-continuation-performance.md) attributes 132.876 ms of sampled CPU self time to `buildRequest`'s `deepFreeze` during a 211.300 ms request-history operation. Skipping all frozen roots is unsafe: restore adopts independently owned graphs without freezing them, and a shallow-frozen message can still contain mutable content. + +## Decision + +Each `ReactLoopAgent` owns a private WeakSet containing only identities whose complete `deepFreeze` call succeeded in that instance. Every unseen message is deep-frozen in place, then added. Later requests reuse that proof. A fresh loop proves each identity again; equal message ids do not establish object identity. Weak references add no ownership of compacted history. + +The loop deep-freezes the small local canonical header on every request. `canonicalHeader` shares nested values, and `Session.append` freezes a separate snapshot: neither operation proves the local tools or a `NO_ADAPTER` fallback's stop array immutable. The loop separately freezes its fresh messages array and request envelope, retains `markAgentLoopRequest`, and leaves the live `AbortSignal` mutable. Restored message identity and containing event-wrapper mutability remain unchanged. + +This specializes request construction, not Session ownership or general `deepFreeze` behavior. `Session.deriveMessages` and `fromRestore` remain unchanged. LLM file, image, and replay projections retain their own freezes because their newly produced values have no loop-local proof. The [reconstructable-request decision](../architecture/2026-07-05-reconstructable-requests.md) continues to own observable immutability and logged request reconstruction. + +## Measurement evidence + +Apple M4 Pro, macOS arm64, Node 24.19.0; independent worktree dependencies and built artifacts. The exact parent Agent source at 1dc3296eba is rebuilt for the negative control, then the optimized source is restored and rebuilt. Each row retains all five fresh-process totals in sampling order; all timings are milliseconds. Exclusive slots do not overlap repository builds or sibling benchmarks. + +| Implementation and UTC interval (2026-09-06) | Request-history raw totals | Median | 175 ms verdict | +|---|---|---:|---| +| Optimized, 07:15:40–07:15:51 | 65.737375, 67.292833, 68.035208, 65.380417, 67.919167 | 67.292833 | Pass | +| Original, 07:17:06–07:17:10 | 249.050708, 238.275291, 242.172084, 250.093166, 246.130875 | 246.130875 | Fail | +| Optimized repeat, 07:18:17–07:18:20 | 66.693500, 67.402083, 68.665000, 66.642083, 66.609125 | 66.693500 | Pass | + +The same 800-turn, four-tools-per-historical-turn history and 40 live requests complete in every sample: 13,923 events, no live tool calls. The repeat median is 72.9% below the isolated original. The historical 70 ms M4 expectation rounds above both optimized medians; applying the shared 2× CI scale and 1.25× headroom produced the 175 ms budget used in the table. These remain local reference measurements, not hosted-runner expectations. The explicit hosted calibration below owns the enforced request-history budget; no other case or memory budget changes here. + +The first optimized slot also measures cold tool continuation: totals 185.839958, 185.235583, 185.865917, 189.213459, 185.279417; median 185.839958 ms. Every sample completes 40 requests and 160 tool calls with 14,143 events. Retained heap samples are 22.591591, 22.590355, 22.594795, 22.591743, 22.594681 MiB, below the unchanged 28.75 MiB budget. The earlier baseline's approximately 22.295 MiB highlights the small provenance-table cost; weak keys prevent the table itself retaining replaced messages. + +The same slot's shipped SDK profile completes 100 turns, 200 requests, and 800 real reads per sample. Totals are 1428.555292, 1160.396333, 1139.843500, 1135.834750, 1155.890334 ms; median 1155.890334 ms. The first sample includes 461.829250 ms boot time versus 164–169 ms for the others and is retained, not discarded. Provider serialization, network time, and browser rendering remain excluded as specified by the baseline owner. + +An earlier original-code run at 06:58:28 UTC overlaps a sibling build because of scheduling-message latency: totals 264.269792, 282.442000, 365.836334, 293.172791, 288.719500 ms; median 288.719500 ms. It also fails 175 ms but is not calibration evidence. The isolated original row replaces that comparison, without removing or averaging away the contaminated samples. + +### Standard hosted CI calibration + +The standard two-CPU `ubuntu-24.04` lane runs Node 24.20.0. [Run 34033336380, job 101487280801](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336380/job/101487280801) measures the optimized request path at merge commit `8fba64d9ae06d1a9a778a95487bb915d24cb0644` in Azure eastus: 183.355397, 184.468253, 185.042397, 182.160790, 182.924728 ms; median 183.355397 ms. Every sample completes the same 40 requests and 13,923 events. All five exceed the historical 175 ms budget without changing the WeakSet implementation or workload. + +A second hosted run of the same request implementation, [run 34033336246, job 101487216170](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336246/job/101487216170), records 145.644577, 144.204300, 143.072572, 145.985903, 146.834474 ms; median 145.644577 ms. It uses the same Ubuntu image and Node version but a different worker in Azure westus3 at merge commit `c366e49`. This faster run does not replace the eastus evidence or establish why the workers differ. The older self-hosted `VM-7-113-ubuntu-ci-9` run with Node 24.18.1 ([run 34021903421, job 101456015028](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34021903421/job/101456015028)) records 110.025154, 119.958978, 108.266860, 107.557950, 108.538902 ms; median 108.538902 ms. Its runner and Node version do not calibrate the standard hosted lane. + +The request-history CI expectation is 190 ms, rounded above this observed range. The enforced median budget is `ceil(190 × 1.25) = 238 ms`; the shared 2× reference-machine scale does not apply again to a CI measurement. This matches the direct-CI calibration method of the [63 ms Session-reopen budget](../../../../benchmarks/session-open/session-open.bench.ts), rather than relabeling the M4 reference as hosted evidence. The 238 ms budget remains below the isolated original implementation’s 246.130875 ms M4 median. + +Deterministic controls call the same `assertRequestHistoryBudget` assertion as the timed case. They accept the recorded hosted median and maximum (185.042397 ms), reject the recorded original M4 median, and reject a synthetic 250 ms median from 248, 250, 252, 251, 249 ms inputs. The synthetic inputs model a material regression; they are not runtime measurements. Replaying recorded values verifies the assertion, not a new hosted run. The acceptance control fails at 175 ms before calibration; all three controls and the five request-freeze behavior tests pass at 238 ms. + +## Alternatives considered + +**Return immediately for `Object.isFrozen`.** A frozen root does not prove its descendants frozen. Applying this shortcut to the shared helper would weaken every caller, including restore and projection paths. + +**Trust every Session message or cache message ids.** Restore explicitly permits owned unfrozen data; replacements can preserve an id while changing identity and content. Only completed traversal of that exact object proves the request's requirement. + +**Retain a strong Set or share a global proof cache.** Strong references extend old history lifetime. Global caching expands ownership beyond the Agent and is unnecessary for repeated requests from one loop. + +**Remove downstream projection freezes.** Projected file/image/replay messages are distinct values with separate ownership. Optimizing them requires their own evidence and is not implied by freezing canonical history. + +## Consequences + +Request construction still scans message identities and allocates a fresh array; it avoids recursively traversing already-proven history. Each loop pays one complete traversal for restored history. Local headers remain a per-request cost. Message values, request markers, previous request snapshots, cancellation, and serialized SDK outputs keep their existing behavior. + +The [focused tests](../../../../packages/core/agent-loop/tests/request-freeze.spec.ts) exercise shallow-frozen restored roots with mutable descendants, wrapper identity and mutability, successful-only provenance, repeated requests, same-id compaction replacements, a fresh loop, nested tool schemas, adapter and `NO_ADAPTER` stop arrays, held requests, and live cancellation. Reconstruction and cancellation suites cover adjacent loop semantics. Performance measurements use the unchanged [continuation workload](../../../../benchmarks/agent-continuation/workload.ts), not a smaller synthetic microbenchmark. + +Validation runs 646 Agent-loop and LLM tests with 100% statement, branch, function, and line coverage of agent.ts. Keyless TypeScript SDK bash-tool and multi-turn snapshots pass against rebuilt libraries. Python sdk-minimal and sdk-snapshot checks pass against an independently packaged node24-macos-arm64 executable. Neither SDK requires an expected-output change. The packaging deploy temporarily removes workspace dependency links; a frozen-lockfile install restores them before source checks, without a tracked dependency change. + +The active immutability, message-identity, observable-state-machine, and backend-baseline notes remain independently useful; none is fully superseded or archived. This note specializes the request-freezing mechanism and cross-links its reconstructability owner. diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md new file mode 100644 index 0000000000..239d7e69df --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md @@ -0,0 +1,65 @@ +# Agent Note: 仅复用循环已证明的消息冻结 + +Status: implemented + +[English](2026-09-06-agent-request-freeze-provenance.md) | 中文 + +## 问题 + +长工具对话在构造请求时反复遍历不可变历史。[后端续跑基线](../testing/2026-09-06-backend-continuation-performance.zh.md)在一次 211.300 ms 的请求历史操作中，将 132.876 ms 的采样 CPU 自耗时归因于 `buildRequest` 的 `deepFreeze`。跳过所有已冻结根对象并不安全：恢复操作会接管独立拥有的对象图而不冻结它们，浅冻结消息仍可能包含可变内容。 + +## 决策 + +每个 `ReactLoopAgent` 拥有私有 WeakSet，其中只记录该实例中完整 `deepFreeze` 调用成功的对象身份。每个未见消息先原地深冻结，再加入集合。后续请求复用该证明。新循环会重新证明每个对象；消息 id 相等不能证明对象身份相同。弱引用不会增加对已压缩历史的所有权。 + +循环每次请求都深冻结较小的本地规范化 header。`canonicalHeader` 共享嵌套值，`Session.append` 冻结的是独立快照：两者都不能证明本地 tools 或 `NO_ADAPTER` 回退中的 stop 数组不可变。循环分别冻结新消息数组与请求封装，保留 `markAgentLoopRequest`，并保持实时 `AbortSignal` 可变。恢复消息的对象身份及其外围事件包装对象的可变性保持不变。 + +该决策专门优化请求构造，不改变 Session 所有权或通用 `deepFreeze` 行为。`Session.deriveMessages` 与 `fromRestore` 保持不变。LLM（大语言模型）的文件、图像和回放投影保留各自的冻结，因为它们新生成的值没有循环本地证明。[可重建请求决策](../architecture/2026-07-05-reconstructable-requests.zh.md)继续拥有可观察的不可变性与基于日志的请求重建规则。 + +## 测量证据 + +Apple M4 Pro、macOS arm64、Node 24.19.0；worktree 使用独立依赖和构建产物。负对照重新构建 1dc3296eba 中精确的父版本 Agent 源码，随后恢复并重新构建优化源码。每行按采样顺序保留全部五个新进程总耗时；时间单位均为毫秒。独占时段不与仓库构建或其他基准重叠。 + +| 实现与 UTC 时段（2026-09-06） | 请求历史原始总耗时 | 中位数 | 175 ms 判定 | +|---|---|---:|---| +| 优化版，07:15:40–07:15:51 | 65.737375, 67.292833, 68.035208, 65.380417, 67.919167 | 67.292833 | 通过 | +| 原版，07:17:06–07:17:10 | 249.050708, 238.275291, 242.172084, 250.093166, 246.130875 | 246.130875 | 失败 | +| 优化版复测，07:18:17–07:18:20 | 66.693500, 67.402083, 68.665000, 66.642083, 66.609125 | 66.693500 | 通过 | + +每个样本都完成相同的 800 轮历史（每个历史轮次四个工具）和 40 个实时请求：13,923 个事件，无实时工具调用。复测中位数比独占原版低 72.9%。历史 M4 期望值 70 ms 向上取整并高于两次优化版中位数；应用共享 2× CI 系数和 1.25× 余量，得到表中使用的 175 ms 预算。这些仍是本地参考测量，而非托管运行器期望值。下文的显式托管校准拥有实际执行的请求历史预算；本文不改变其他场景或内存预算。 + +首个优化版时段还测量冷启动工具续跑：总耗时 185.839958, 185.235583, 185.865917, 189.213459, 185.279417；中位数 185.839958 ms。每个样本都完成 40 个请求、160 个工具调用和 14,143 个事件。保留堆样本为 22.591591, 22.590355, 22.594795, 22.591743, 22.594681 MiB，低于不变的 28.75 MiB 预算。先前基线约 22.295 MiB，显示了证明表的小额成本；弱键防止表本身保留已替换消息。 + +同一时段的随产品发布 SDK profile 每个样本都完成 100 轮、200 个请求和 800 次真实读取。总耗时为 1428.555292, 1160.396333, 1139.843500, 1135.834750, 1155.890334 ms；中位数 1155.890334 ms。首个样本包含 461.829250 ms 启动时间，其他样本为 164–169 ms；首个样本被保留而非丢弃。供应商序列化、网络时间和浏览器渲染仍按基线所属说明排除。 + +较早的原版运行始于 06:58:28 UTC，因调度消息延迟而与其他构建重叠：总耗时 264.269792, 282.442000, 365.836334, 293.172791, 288.719500 ms；中位数 288.719500 ms。它也超过 175 ms，但不属于校准证据。独占原版行替代该比较，没有删除受污染样本或通过取平均掩盖它们。 + +### 标准托管 CI 校准 + +标准双 CPU `ubuntu-24.04` 测试通道运行 Node 24.20.0。[运行 34033336380、任务 101487280801](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336380/job/101487280801)在 Azure eastus 上测量合并提交 `8fba64d9ae06d1a9a778a95487bb915d24cb0644` 的优化请求路径：183.355397, 184.468253, 185.042397, 182.160790, 182.924728 ms；中位数 183.355397 ms。每个样本都完成相同的 40 个请求和 13,923 个事件。在 WeakSet 实现与工作负载未变的情况下，全部五个样本均超过历史 175 ms 预算。 + +相同请求实现的另一次托管运行，[运行 34033336246、任务 101487216170](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336246/job/101487216170)，记录了 145.644577, 144.204300, 143.072572, 145.985903, 146.834474 ms；中位数 145.644577 ms。它在合并提交 `c366e49` 上使用相同的 Ubuntu 镜像和 Node 版本，但运行于 Azure westus3 的另一台工作机。较快的运行不能替代 eastus 证据，也不能证明工作机差异的原因。较早的自托管 `VM-7-113-ubuntu-ci-9` 运行使用 Node 24.18.1（[运行 34021903421、任务 101456015028](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34021903421/job/101456015028)），记录了 110.025154, 119.958978, 108.266860, 107.557950, 108.538902 ms；中位数 108.538902 ms。其运行器和 Node 版本不能校准标准托管通道。 + +请求历史的 CI 期望值为 190 ms，向上取整并高于该观测范围。实际执行的中位数预算为 `ceil(190 × 1.25) = 238 ms`；CI 测量不再应用共享的参考机器 2× 系数。这与 [Session 重开 63 ms 预算](../../../../benchmarks/session-open/session-open.bench.ts)的直接 CI 校准方法一致，而非将 M4 参考值重新标注为托管证据。238 ms 预算仍低于独占原版实现的 M4 中位数 246.130875 ms。 + +确定性对照调用与计时场景相同的 `assertRequestHistoryBudget` 断言。它们接受已记录的托管中位数和最大值（185.042397 ms），拒绝已记录的原版 M4 中位数，并拒绝由 248, 250, 252, 251, 249 ms 输入得到的合成 250 ms 中位数。合成输入模拟显著回归，并非运行时测量。回放已记录数值验证的是断言，而非新的托管运行。接受对照在校准前以 175 ms 预算失败；三个对照和五个请求冻结行为测试在 238 ms 预算下均通过。 + +## 考虑过的替代方案 + +**`Object.isFrozen` 为真时立即返回。** 已冻结根对象不能证明其后代已冻结。在共享辅助函数中使用此捷径会削弱所有调用方，包括恢复与投影路径。 + +**信任所有 Session 消息或缓存消息 id。** 恢复明确允许拥有独立所有权的未冻结数据；替换操作可保留 id，同时改变对象身份与内容。只有对该精确对象完成遍历才能证明请求要求。 + +**保留强引用 Set 或共享全局证明缓存。** 强引用会延长旧历史的生命周期。全局缓存将所有权扩大到 agent（智能体）之外，对同一循环的重复请求并无必要。 + +**移除下游投影冻结。** 投影后的文件／图像／回放消息是拥有独立所有权的不同值。优化它们需要独立证据，不能由规范历史已冻结推导出来。 + +## 影响 + +请求构造仍扫描消息身份并分配新数组，但避免递归遍历已证明的历史。每个循环都为恢复历史支付一次完整遍历成本。本地 header 仍是每次请求的成本。消息值、请求标记、先前请求快照、取消及 SDK 序列化输出保持现有行为。 + +[聚焦测试](../../../../packages/core/agent-loop/tests/request-freeze.spec.ts)覆盖具有可变后代的浅冻结恢复根对象、包装对象身份与可变性、仅成功遍历的证明、重复请求、同 id 压缩替换、新循环、嵌套工具 schema、适配器与 `NO_ADAPTER` stop 数组、持有的旧请求以及实时取消。重建与取消测试集覆盖相邻循环语义。性能测量采用不变的[续跑工作负载](../../../../benchmarks/agent-continuation/workload.ts)，而非缩小的合成微基准。 + +验证运行了 646 个 agent loop 与 LLM 测试，agent.ts 的语句、分支、函数和行覆盖率均为 100%。无密钥 TypeScript SDK bash-tool 与 multi-turn 快照通过重新构建的库执行并通过。Python sdk-minimal 与 sdk-snapshot 检查使用独立打包的 node24-macos-arm64 可执行文件并通过。两个 SDK 均无需修改期望输出。打包部署暂时移除了工作区依赖链接；执行冻结 lockfile 安装可在源码检查前恢复它们，无需修改受版本管理的依赖文件。 + +现行不可变性、消息身份、可观察状态机和后端基线说明仍各自具有价值；没有说明被完全取代或归档。本文专门规定请求冻结机制，并与可重建性所属说明交叉链接。 diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml index 7bbae78b83..48e9139ebb 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.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/testing/2026-07-24-web-gui-browser-e2e-lane.md -2026-07-24-web-gui-browser-e2e-lane.md: a996b380a55fc33f44cfdc2e31e179bc11f40be3 -2026-07-24-web-gui-browser-e2e-lane.zh.md: 1a413b6b8277ac696c6b728de740494bbf056695 +2026-07-24-web-gui-browser-e2e-lane.md: 07a37ada9c2a43f04612048f9bff6b22d022ec40 +2026-07-24-web-gui-browser-e2e-lane.zh.md: 668e612712175821d6ad123ce364a7cb96e01272 diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md index a996b380a5..07a37ada9c 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md @@ -93,4 +93,4 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot ## Consequences -The web surface gains its record-once/replay-forever tier: the real chromium → SSE → apiproxy → loop → tools → persistence chain runs keylessly in ~10-30s, deterministic across repeat runs, with fixtures owned and re-recordable by the lane itself. Costs accepted: every intentional conversation-UI change ends with a keyless `DSH_SNAPSHOT=refresh` (golden churn is reviewed diff, anchors keep semantic green); the aria format is Playwright-owned — the one committed snapshot format the repo does not control — so playwright version bumps must be deliberate bump-and-refresh commits (the dependency floats `^1.49.0` in `apps/web/package.json`; pin exactly if churn bites); replay's first-call-order binding constrains scenarios to one prompting session each, with the consumption assertion as the tripwire; `compaction-basic` shares the session's replay cursor and stays inert only under the published 128k catalog window; and the required consumer job pays for Chromium provisioning and one browser run so the PR that changes the assembled UI owns its expected-output diff. The opt-in performance lane preserves a repeatable diagnostic workload without adding host-sensitive duration or memory expectations to CI; performance regressions remain a manually interpreted signal until the repository owns a calibrated benchmark environment. +The web surface gains its record-once/replay-forever tier: the real chromium → SSE → apiproxy → loop → tools → persistence chain runs keylessly in ~10-30s, deterministic across repeat runs, with fixtures owned and re-recordable by the lane itself. Costs accepted: every intentional conversation-UI change ends with a keyless `DSH_SNAPSHOT=refresh` (golden churn is reviewed diff, anchors keep semantic green); the aria format is Playwright-owned — the one committed snapshot format the repo does not control — so playwright version bumps must be deliberate bump-and-refresh commits (the dependency floats `^1.49.0` in `apps/web/package.json`; pin exactly if churn bites); replay's first-call-order binding constrains scenarios to one prompting session each, with the consumption assertion as the tripwire; `compaction-basic` shares the session's replay cursor and stays inert only under the published 128k catalog window; and the required consumer job pays for Chromium provisioning and one browser run so the PR that changes the assembled UI owns its expected-output diff. The opt-in performance lane preserves a repeatable, threshold-free diagnostic workload whose measurements require manual interpretation. The separate required [frontend performance benchmarks](2026-09-06-frontend-performance-budgets.md) enforce calibrated budgets in the isolated benchmark CI job; they do not add thresholds to the manual inventory. diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md index 1a413b6b82..668e612712 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md @@ -93,4 +93,4 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu ## 后果 -Web 表面获得了录制一次/永久回放的层级：真实 chromium → SSE → apiproxy → 循环 → 工具 → 持久化的链路以约 10-30 秒无密钥运行，重复运行结果确定，fixture 由车道自身持有并可重录。接受的成本：每次有意的会话 UI 变更都以一次无密钥 `DSH_SNAPSHOT=refresh` 收尾（预期输出变动是受评审的 diff，锚断言保住语义绿色）；aria 格式归 Playwright 所有——仓库唯一不受自己控制的提交快照格式——因此 playwright 版本升级必须是刻意的升级加刷新提交（依赖在 `apps/web/package.json` 中浮动为 `^1.49.0`；若变动伤人则改为精确锁定）；回放的首次调用顺序绑定把每个场景限制为至多一个发起提示的会话，消费断言是绊线；`compaction-basic` 与会话共享回放游标，仅在目录中发布的 128k 上下文窗口下保持闲置；必需的消费方任务承担 Chromium 供给与一次浏览器运行的成本，使改动组装后 UI 的 PR（Pull Request）持有相应的预期输出 diff。按需启用的性能车道保留了可重复的诊断工作负载，又不会向 CI 添加受 host 差异影响的时长或内存预期；在仓库拥有经校准的基准测试环境之前，性能回归仍是需要人工解读的信号。 +Web 表面获得了录制一次/永久回放的层级：真实 chromium → SSE → apiproxy → 循环 → 工具 → 持久化的链路以约 10-30 秒无密钥运行，重复运行结果确定，fixture 由车道自身持有并可重录。接受的成本：每次有意的会话 UI 变更都以一次无密钥 `DSH_SNAPSHOT=refresh` 收尾（预期输出变动是受评审的 diff，锚断言保住语义绿色）；aria 格式归 Playwright 所有——仓库唯一不受自己控制的提交快照格式——因此 playwright 版本升级必须是刻意的升级加刷新提交（依赖在 `apps/web/package.json` 中浮动为 `^1.49.0`；若变动伤人则改为精确锁定）；回放的首次调用顺序绑定把每个场景限制为至多一个发起提示的会话，消费断言是绊线；`compaction-basic` 与会话共享回放游标，仅在目录中发布的 128k 上下文窗口下保持闲置；必需的消费方任务承担 Chromium 供给与一次浏览器运行的成本，使改动组装后 UI 的 PR（Pull Request）持有相应的预期输出 diff。按需启用的性能车道保留可重复、无阈值的诊断工作负载，其测量需要人工解读。独立的必需[前端性能基准](2026-09-06-frontend-performance-budgets.zh.md)在隔离的基准 CI job 中执行经校准的预算；它们不向手动清单添加阈值。 diff --git a/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.i18n.yaml b/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.i18n.yaml index 22cf5283e3..bfd2d60086 100644 --- a/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.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/testing/2026-09-04-session-open-performance-gate.md -2026-09-04-session-open-performance-gate.md: 2820c9d7d0e5b7d9382c7f8d6540154440175f26 -2026-09-04-session-open-performance-gate.zh.md: 965b9035074504870bcb2f1ca8166962c264d75a +2026-09-04-session-open-performance-gate.md: 2937a2aec1dbddb31fde82d2617d69852a611d90 +2026-09-04-session-open-performance-gate.zh.md: b6608ca79d07c3e9fb00d62801038ecefbdf944c diff --git a/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.md b/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.md index 2820c9d7d0..2937a2aec1 100644 --- a/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.md +++ b/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.md @@ -12,13 +12,13 @@ Measuring only `SessionPersistence.open()` does not stably describe the result f ## Decision -Linux pull requests run a required `node 24 / benchmarks` job that executes `pnpm run check:ci:bench` → `pnpm run test:bench`. The private `@deepseek-ai/dsh-benchmarks` workspace owns benchmark-only dependencies. The command first builds workspace libraries and dedicated workers under `benchmarks/.dsh-build/`, then invokes `vitest.bench.config.ts`. The [standard hosted runner decision](2026-09-06-standard-hosted-benchmark-runner.md) owns runner selection and the outer job timeout. The job runs the benchmark lane alone; Vitest runs one file at a time and only prepares input, starts measurement children, aggregates results, and enforces budgets. Every timed CPU path executes compiled JavaScript under plain Node with `NODE_OPTIONS` removed and no TypeScript loader; bare workspace imports therefore resolve from `benchmarks/node_modules` through package exports to built `lib/` entries. +Linux pull requests run a required `node 24 / benchmarks` job that executes `pnpm run check:ci:bench` → `pnpm run test:bench`. The private `@deepseek-ai/dsh-benchmarks` workspace owns benchmark-only dependencies. The command first builds workspace libraries and dedicated workers under `benchmarks/.dsh-build/`, then invokes `vitest.bench.config.ts`. The [standard hosted runner decision](2026-09-06-standard-hosted-benchmark-runner.md) owns runner selection and the outer job timeout. The job runs the benchmark lane alone; Vitest runs one file at a time and only prepares input, starts measurement children, aggregates results, and enforces budgets. Every timed Node CPU path executes compiled JavaScript under plain Node with `NODE_OPTIONS` removed and no TypeScript loader; bare workspace imports therefore resolve from `benchmarks/node_modules` through package exports to built `lib/` entries. Required performance gates live under top-level `benchmarks/`, grouped by measured user path rather than package ownership. Host files use `*.bench.ts`, Client-face files use `*.bench.client.ts`, and scenario-specific workers and fixtures stay beside their benchmark without a benchmark suffix. Package-local `.perf.ts` files remain non-gating diagnostics; `scripts/` owns orchestration rather than benchmark cases. The Session benchmarks synthesize a released-v0 input from fixed parameters: 200 turns with 500 text deltas and 125 reasoning deltas per turn, for 127,400 logical events. The input uses Zstandard with fixed logical-row grouping and frame partitioning, so every run processes the same events, bytes, and frame distribution. The fixture constructs the immutable released-v0 physical rows directly instead of depending on a current-runtime historical encoder; compression and every measured read or migration entry point still use production code. Setup writes the input into a private temporary directory for each sample before timing starts; benchmarks never use recorded Sessions. -Every Session endpoint runs at two user-lifecycle points. `first-open` starts with only the released V0 generation and therefore includes migration and successor publication. Setup produces `post-upgrade-reopen` once through that same production migration outside measurement, then copies both the unchanged V0 predecessor and published V2 successor into each sample root. Reopen samples use a fresh process, so they measure an upgraded user's later disk open without migration or process-local caches. +Every Session endpoint runs at two user-lifecycle points. `first-open` starts with only the released V0 generation and includes migration; read-only consumers do not publish a successor, while writable Agent resume does. Setup produces `post-upgrade-reopen` once through that same production migration outside measurement, then copies both the unchanged V0 predecessor and published V2 successor into each sample root. Reopen samples use a fresh process, so they measure an upgraded user's later disk open without migration or process-local caches. Each access-kind and endpoint sample runs in a fresh compiled Node child process. Module imports, Host service initialization, and fixture preparation finish before measurement; the measured process performs no extra parse warm-up. Normal-heap mode runs five independent samples, reports every sample plus minimum, median, and maximum, and enforces access-specific fixed budgets against the median. Another child runs the same path under a fixed 128 MB old-space limit and checks only that it completes; extra GC caused by the constrained heap does not enter the normal timing baseline. @@ -26,7 +26,7 @@ The lane contains three independent Session-opening benchmarks and retains the C | Benchmark | Measured path | Timing metrics | |---|---|---| -| Phase profile | Executes the real persistence open, handle read, Session restore, and projection for both first open and post-upgrade reopen | `openMs`, `readMs`, `sessionRestoreMs`, and `projectionMs` each have a fixed budget; encoding, writes, verification, and publication awaited by migration all belong to first-open `openMs` | +| Phase profile | Executes the real persistence open, handle read, Session restore, and projection for both first open and post-upgrade reopen | `openMs`, `readMs`, `sessionRestoreMs`, and `projectionMs` each have a fixed budget; read-only migration belongs to first-open `openMs`; successor encoding, verification, and publication belong to writable Agent resume | | First history | Reads each access kind through the Host Session history controller until it produces the first paginated snapshot | Separate first-open and reopen end-to-end budgets; each includes source stat, reading, restoration, projection, pagination, and snapshot construction, while first open additionally includes migration; both exclude Gateway network transport, Client fold, and browser paint | | Agent resume | Calls `ctx.agents.resume()` for each access kind until Agent creation, setup, publication, and loop startup finish | Separate first-open and reopen end-to-end budgets; neither path runs after first-history or reuses that benchmark's cache | | Client fold | Folds small and large v2 history windows through the real `ConversationNodeAssembler` and every Chat Definition | The large window's absolute time and scaling relative to the small window each have a fixed budget | @@ -102,4 +102,4 @@ The calibrated source budgets are: Every pull request pays for one required Linux job; its Session portion runs several short-lived child processes in exchange for cold caches, isolated V8 heaps, explicit GC state, and attributable failures. The repository-level benchmark tree accepts deliberate cross-package test dependencies without changing product package manifests. The fixed Zstandard workload covers both event volume and frame topology; first-open measurements protect the one-time upgrade experience, reopen measurements prevent regressions in later opens, phase budgets locate cost, first-history budgets protect user-visible waiting, Agent-resume budgets and post-GC deltas protect complete cold activation and resident memory, and the 128 MB mode protects the transient allocation ceiling. -The gate does not measure network transfer, browser rendering, or recorded Sessions, and it is not a continuous performance-trend system. A Node or runner change requires resampling the same workload and reviewing the budgets; a business-implementation change must not relax a budget without new positive and negative control data. +The Session and Node-fold scenarios do not measure network transfer, browser rendering, or recorded Sessions, and they are not a continuous performance-trend system. [Frontend performance budgets](2026-09-06-frontend-performance-budgets.md) own browser workflow measurements. A Node or runner change requires resampling the same workload and reviewing the budgets; a business-implementation change must not relax a budget without new positive and negative control data. diff --git a/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.zh.md b/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.zh.md index 965b903507..b6608ca79d 100644 --- a/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.zh.md +++ b/.agents/notes/implemented/testing/2026-09-04-session-open-performance-gate.zh.md @@ -12,13 +12,13 @@ Session format v2 的推出改变了两条成本随模型输出增长的路径 ## 决定 -Linux pull request 运行必需的 `node 24 / benchmarks` job，执行 `pnpm run check:ci:bench` → `pnpm run test:bench`。私有 `@deepseek-ai/dsh-benchmarks` workspace 拥有 benchmark 专属依赖。该命令先构建 workspace library 和 `benchmarks/.dsh-build/` 下的专用 worker，再调用 `vitest.bench.config.ts`。[标准托管运行器决策](2026-09-06-standard-hosted-benchmark-runner.zh.md)拥有运行器选择及外层 job 超时。该 job 单独运行 benchmark lane；Vitest 逐文件运行，只负责准备输入、启动测量子进程、汇总结果和执行预算断言。每条被计时的 CPU 路径都以纯 Node 执行编译后的 JavaScript，并移除 `NODE_OPTIONS` 且不加载 TypeScript runtime；workspace 裸导入因此从 `benchmarks/node_modules` 通过 package exports 解析到构建后的 `lib/` 入口。 +Linux pull request 运行必需的 `node 24 / benchmarks` job，执行 `pnpm run check:ci:bench` → `pnpm run test:bench`。私有 `@deepseek-ai/dsh-benchmarks` workspace 拥有 benchmark 专属依赖。该命令先构建 workspace library 和 `benchmarks/.dsh-build/` 下的专用 worker，再调用 `vitest.bench.config.ts`。[标准托管运行器决策](2026-09-06-standard-hosted-benchmark-runner.zh.md)拥有运行器选择及外层 job 超时。该 job 单独运行 benchmark lane；Vitest 逐文件运行，只负责准备输入、启动测量子进程、汇总结果和执行预算断言。每条被计时的 Node CPU 路径都以纯 Node 执行编译后的 JavaScript，并移除 `NODE_OPTIONS` 且不加载 TypeScript runtime；workspace 裸导入因此从 `benchmarks/node_modules` 通过 package exports 解析到构建后的 `lib/` 入口。 必需性能 gate 位于顶层 `benchmarks/`，按被测用户路径而非 package 归属组织。Host 文件使用 `*.bench.ts`，Client 面文件使用 `*.bench.client.ts`，场景专属 worker 与 fixture 留在对应 benchmark 旁且不带 benchmark 后缀。包内 `.perf.ts` 文件仍是非门禁诊断；`scripts/` 负责编排而不承载 benchmark case。 Session benchmark 使用固定参数合成 released-v0 输入：200 轮，每轮 500 个 text delta 与 125 个 reasoning delta，共 127,400 个逻辑事件。输入使用 Zstandard，并固定 logical rows 的分组与 frame 拆分，使每次运行处理相同的事件、字节与 frame 分布。fixture 直接构造不可变的 released-v0 physical rows，不依赖当前 runtime 的历史 encoder；压缩以及所有被测读取和 migration 入口仍使用生产代码。输入在计时前写入每个样本独占的临时目录；benchmark 不使用录制的 Session。 -每个 Session endpoint 都针对用户生命周期中的两个时点运行。`first-open` 最初只有 released V0 generation，因此包含 migration 与后继 generation 发布。测试准备阶段在计时外通过同一套生产 migration 生成一次 `post-upgrade-reopen`，再把未改动的 V0 前代和已发布的 V2 后继一起复制到每个样本目录。Reopen 样本使用全新进程，因此测量用户升级完成后的磁盘再次打开，不包含 migration 或进程内 cache。 +每个 Session endpoint 都针对用户生命周期中的两个时点运行。`first-open` 最初只有 released V0 generation，包含 migration；只读消费者不发布后继文件，可写 Agent resume 才会发布。测试准备阶段在计时外通过同一套生产 migration 生成一次 `post-upgrade-reopen`，再把未改动的 V0 前代和已发布的 V2 后继一起复制到每个样本目录。Reopen 样本使用全新进程，因此测量用户升级完成后的磁盘再次打开，不包含 migration 或进程内 cache。 每个 access kind 与 endpoint 的样本都在全新、已编译的 Node 子进程中运行。模块加载、Host 服务初始化和 fixture 准备在测量开始前完成；测量进程不执行额外的预热解析。正常堆模式运行五个独立样本，报告全部样本及最小值、中位数和最大值，并以中位数执行各访问状态独立的固定预算。另一个子进程使用固定 128 MB old-space 上限运行同一路径，只判断能否完成；低堆限制引起的额外 GC 不进入正常时间基线。 @@ -26,7 +26,7 @@ Session benchmark 使用固定参数合成 released-v0 输入：200 轮，每轮 | Benchmark | 被测路径 | 时间指标 | |---|---|---| -| 阶段剖面 | 分别为 first open 与 post-upgrade reopen 执行真实 persistence open、handle read、Session restore 与 projection | `openMs`、`readMs`、`sessionRestoreMs`、`projectionMs` 各自使用固定预算；migration 所等待的编码、写入、verify 与 publish 全部归入 first-open `openMs` | +| 阶段剖面 | 分别为 first open 与 post-upgrade reopen 执行真实 persistence open、handle read、Session restore 与 projection | `openMs`、`readMs`、`sessionRestoreMs`、`projectionMs` 各自使用固定预算；只读 migration 归入 first-open `openMs`；后继编码、verify 与 publish 属于可写 Agent resume | | 首屏历史 | 两种 access kind 分别经 Host Session history controller 读取到首个分页 snapshot | First open 与 reopen 各有一个端到端预算；均包含 source stat、读取、Session restore、projection、分页与 snapshot 构造，first open 还包含 migration；两者都不包含 Gateway 网络传输、Client fold 或浏览器 paint | | Agent resume | 对两种 access kind 分别调用 `ctx.agents.resume()`，直到 Agent 创建、setup、发布与 loop 启动完成 | First open 与 reopen 各有一个端到端预算；两条路径都不与首屏历史串行，也不依赖它留下的 cache | | Client fold | 大小两个 v2 history window 经真实 `ConversationNodeAssembler` 与全部 Chat Definition fold | 大窗口的绝对时间与相对小窗口的缩放比各自使用固定预算 | @@ -50,7 +50,7 @@ Session benchmark 使用固定参数合成 released-v0 输入：200 轮，每轮 | First open | 栈前参考版本 | 249.0 ms | 253.8 ms | 100.7 ms | 26.1 MB | 完成 | | First open | 重复 snapshot 退化实现 | 4,197.5 ms | 4,284.8 ms | 4,197.9 ms | 4.4 MB | 堆耗尽 | | Post-upgrade reopen | 栈前参考版本 | 251.1 ms | 253.8 ms | 100.7 ms | 26.1 MB | 完成 | -| Post-upgrade reopen | 重复 snapshot 退化实现 | 49.2 ms | 50.4 ms | 43.8 ms | 完成 | +| Post-upgrade reopen | 重复 snapshot 退化实现 | 49.2 ms | 50.4 ms | 43.8 ms | 4.5 MB | 完成 | 栈前实现以 V0 作为当前格式，因此 first open 不改变磁盘表示；它的原生 V0 首屏历史与 Agent resume 测量同时适用于两个生命周期行。 @@ -102,4 +102,4 @@ Session benchmark 使用固定参数合成 released-v0 输入：200 轮，每轮 每个 pull request 多付出一个必需 Linux job；该 job 的 Session 部分运行多个短生命周期子进程，以换取冷 cache、独立 V8 heap、明确 GC 状态和可归因的失败。仓库级 benchmark 目录接受有意的跨包测试依赖，而不修改产品 package manifest。固定 Zstandard workload 同时覆盖事件规模与 frame 拓扑；first-open 测量保护一次性升级体验，reopen 测量防止后续打开退化，四阶段预算定位成本归属，首屏预算保护用户可见等待，Agent resume 预算与 GC 后增量保护完整冷恢复及常驻内存，128 MB 模式保护瞬时分配上限。 -该 gate 不测量网络传输、浏览器渲染或真实录制 Session，也不是持续性能趋势系统。Node 或 runner 变化需要用同一 workload 重新采样并评审预算；修改业务实现时不得顺带放宽预算而不提供新的正反例数据。 +Session 与 Node-fold 场景不测量网络传输、浏览器渲染或真实录制 Session，也不是持续性能趋势系统。[前端性能预算](2026-09-06-frontend-performance-budgets.zh.md)拥有浏览器工作流测量。Node 或 runner 变化需要用同一 workload 重新采样并评审预算；修改业务实现时不得顺带放宽预算而不提供新的正反例数据。 diff --git a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.i18n.yaml b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.i18n.yaml new file mode 100644 index 0000000000..dfa20e45f0 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.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/testing/2026-09-06-backend-continuation-performance.md +2026-09-06-backend-continuation-performance.md: f4316e790cf62f5027a0f7bfb2d3148cc79e7536 +2026-09-06-backend-continuation-performance.zh.md: 0fb36ba5375c61e907791b31d96f09062b7f62a3 diff --git a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md new file mode 100644 index 0000000000..f4316e790c --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md @@ -0,0 +1,68 @@ +# Agent Note: Performance baselines for tool-heavy backend continuation + +Status: implemented + +English | [中文](2026-09-06-backend-continuation-performance.zh.md) + +## Problem + +Opening one Session does not measure the repeated cost of preparing model requests after a long tool conversation, executing another tool-heavy turn, or discovering multiple inactive fork children. The [Session-opening gate](2026-09-04-session-open-performance-gate.md) covers first history and activation but deliberately stops before new model work. Its text/reasoning workload also lacks historical tool-call arguments and large tool results. + +## Decision + +The [agent-continuation benchmark](../../../../benchmarks/agent-continuation/agent-continuation.bench.ts) adds three scenario groups, including a shipped-profile variant, without changing product implementations. They use current-generation Zstandard Sessions authored through production append, stream accumulation, and persistence APIs. A separate seed process creates the deterministic source before measurement; each sample copies that source into its private root and starts a fresh compiled plain-Node worker. No recorded Session, ambient repository, network, private Harness home, or deployed GUI supplies input. + +The shared history has 800 completed two-step turns, four tool calls per turn, and 2,048-character tool results: 13,600 events and 5,600 conversation messages. Each assistant reply carries reasoning, text, and compact streamed records; tool replies additionally carry fragmented arguments. Fixed timestamps and ids describe the seed. Live synthetic replies use the real loop's clocks and ids without overriding process globals. + +| Case | Timed operation | Endpoint | +|---|---|---| +| Request history | After unmeasured cold resume, deliver 40 sequential text-only turns over the tool-heavy history, then flush | Idle Agent with all 40 model requests completed; reports turn and final-flush time separately | +| Tool continuation | Cold resume, 20 sequential turns with eight parallel-safe synthetic tool calls and a final reply per turn, then flush | Idle Agent with 40 model requests and 160 completed tool executions; reports resume, turns, and final flush separately | +| Shipped SDK workflow | Launch built dsh with the sdk-minimal profile, deliver 100 sequential turns with eight real file-view calls per turn, then close the SDK | SDK receives 200 assistant messages and 800 successful file results; includes Loader boot, stdio JSON-RPC, persistence, and shutdown | +| Child catalog | List 16 inactive seeded fork children twice through the real subagent and Session query services | Two complete healthy catalogs with observations released; each child inherits 80 tool-heavy turns and owns its descriptor after the exact fork cut | + +The tool execution pipeline, request preparation, Session projections required by those services, persistence, and catalog observations remain production code. Only the model adapter and bounded tool body are synthetic. The adapter retains a request counter, not request objects, so the fixture cannot manufacture a growing retention cost. Sequential input means each idle interval belongs to the one request delivered by this worker; it does not generalize idle to a per-message completion API under concurrent input. + +Five samples report raw wall time, CPU user/system time, peak RSS, endpoint counts, and the minimum, median, and maximum total wall time. Budgets enforce the unrounded median. Continuation additionally measures retained heap against an initialized Host: two explicit GCs separated by an event-loop yield precede and follow the timed operation, while the idle Agent remains reachable. The measured delta therefore includes the resident historical Session and live additions, not just newly appended turns. GC and teardown are outside timing; flush is inside. Request-history retention starts after resume and is diagnostic only. Catalog peak RSS is diagnostic; no retained-heap budget claims to measure already-released child observations. + +The parent bounds every child to 60 seconds, checks timeout, signal, exit, and report independently, awaits process close, and removes private roots after failures. Context and Agent teardown run in finally blocks. Seed processes cannot warm the measured process's caches. Filesystem caches are not forcibly evicted: cold means a fresh process, not cold physical storage. + +## Calibration evidence + +The implementation reference is `925e012340f033f0521e802ba8569ce6dd7ef1ac` on Apple M4 Pro, macOS arm64, Node 24.19.0. Two exclusive five-sample runs use the same seed and no product optimization. Durations below are milliseconds; source expectations round above the observed run medians rather than imposing an unimplemented optimization target. + +| Case | Run 1 raw totals | Run 2 raw totals | Medians | Historical M4 expectation | Historical scaled budget | +|---|---|---|---|---:|---:| +| Request history | 209.134, 210.333, 208.959, 236.355, 238.685 | 222.833, 213.911, 208.089, 211.494, 209.137 | 210.333 / 211.494 | 220 | 550 | +| Tool continuation | 358.953, 324.790, 318.861, 320.119, 322.896 | 324.280, 321.952, 340.409, 325.470, 324.312 | 322.896 / 324.312 | 340 | 850 | +| Child catalog | 318.730, 309.006, 311.404, 308.565, 310.105 | 308.670, 310.030, 280.086, 303.084, 284.829 | 310.105 / 303.084 | 320 | 800 | + +Continuation retains approximately 22.295 MiB; its source expectation is 23 MiB and its budget is 28.75 MiB. SDK time expectations use the existing [calibration helper](../../../../benchmarks/support/calibration.ts): 2× shared CI time scale and 1.25× variance headroom. Request history uses the direct hosted expectation in the [request-freeze calibration](../simplification/2026-09-06-agent-request-freeze-provenance.md), without the 2× scale. Memory uses only 1.25× headroom. The scale is inherited from the existing lane's calibration, not a new Linux measurement of these cases; CI evidence remains necessary when runner characteristics change. Baseline budgets protect the measured implementation; tighter budgets belong with a measured behavior-preserving fix. + +A separate plain-Node request-history CPU profile attributes 132.876 ms of sampled self time to deepFreeze called by buildRequest during a 211.300 ms operation. This identifies repeated traversal of already-frozen history as a focused investigation target, not a proven optimization result. Catalog first/repeat timings remain separate because a second listing still reads body-bearing seeded children after observations are released. + +The shipped SDK variant completes 100 turns, 200 requests, and 800 real file reads. Its five-sample smoke totals are 1,521.773, 1,463.465, 1,689.701, 1,365.485, and 1,417.106 ms (median 1,463.465 ms); a full-suite repeat reports 1,596.183, 1,784.536, 2,120.082, 1,405.365, and 1,355.894 ms (median 1,596.183 ms). Its 1,700 ms reference expectation yields a 4,250 ms CI budget. The repeat also slows the unchanged service cases, so it is validation under variable host load rather than evidence to relax their exclusive calibration. The SDK process receives an allowlisted environment and private home/workspace. A 40-second deadline starts SDK shutdown; every path awaits the same memoized close promise before the outer worker’s 60-second deadline. Profile timing includes boot, all turns, and shutdown, reported separately; no parent-process CPU or heap metric is presented as server memory. The adapter does not serialize requests for an external model provider. + +The first Linux x64 CI measurement at commit `1dc3296eba631d51fbb3bb50e249bf3cc0fce9f6` ran on `VM-7-113-ubuntu-ci-10` with Node 24.18.1 ([run 34017868081, attempt 1, job 101444810498](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34017868081/job/101444810498)). The SDK median was 2,753.441 ms against its 4,250 ms budget, and tool-continuation retained-heap median was 22.274 MiB against 28.75 MiB. Request-history and tool-continuation time budgets failed: 785.498 ms against 550 ms and 1,077.285 ms against 850 ms, respectively. The unchanged Session-reopen open phase also failed at 31.6 ms against 30 ms. [Attempt 2, job 101447076381](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34017868081/job/101447076381) passed every benchmark on the same commit and unchanged budgets, but used `VM-7-113-ubuntu-ci-29` with Node 24.19.0. The gate runner suppressed successful child output, so that attempt supplies a passing verdict rather than raw medians. The changed runner and Node version prevent attributing the difference solely to contention or claiming stable repeated CI calibration; neither the budgets nor the shared scale are changed on this evidence. + +Catalog uses an explicit 900 ms expected CI duration and only the existing 1.25× headroom, yielding 1,125 ms without applying the reference-machine scale again. The standard two-CPU hosted `ubuntu-24.04` [run 34033336380, job 101487280801](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336380/job/101487280801) reports five unchanged-catalog totals of 797.374, 883.157, 858.364, 790.569, and 904.579 ms: median 858.364 ms exceeds the historical 800 ms budget. The 320 ms M4 expectation above remains historical evidence, not a CI measurement. This follows the explicit-CI calibration used by Session reopening (50 ms expected CI); shared factors, workloads, timing endpoints, and product implementations remain unchanged. Deterministic controls use the same assertion as the measured verdict: the unrounded recorded median passes 1,125 ms and fails 800 ms, while a synthetic 1,400 ms median fails 1,125 ms. A passing run on a faster host does not calibrate the standard hosted runner. + +Tool continuation also uses a 900 ms expected CI duration with 1.25× headroom (1,125 ms). At unchanged implementation `79c052ab29`, standard two-CPU hosted [run 34034524265, job 101490056074](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34034524265/job/101490056074) reports totals of 917.007, 892.091, 887.839, 905.659, and 898.252 ms: median 898.252 ms exceeds the historical 850 ms budget. The 340 ms M4 expectation remains historical evidence. The same measured-verdict assertion accepts the recorded unrounded median under 1,125 ms, rejects it under 850 ms, and rejects a synthetic 1,400 ms regression. Workload, timing, product code, and the 28.75 MiB retained-heap budget remain unchanged. + +Baseline request history uses a 600 ms expected CI duration with 1.25× headroom (750 ms). At unchanged implementation `54d1190a75`, standard two-CPU hosted [run 34035306987, job 101492163630](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34035306987/job/101492163630) reports totals of 618.598, 618.606, 582.035, 582.304, and 581.832 ms: median 582.304 ms exceeds the historical 550 ms budget. The 220 ms M4 expectation remains historical evidence. The same measured-verdict assertion accepts the recorded unrounded median under 750 ms, rejects it under 550 ms, and rejects a synthetic 900 ms regression. This calibrates the unoptimized baseline only; workload, timing, product code, and memory budgets remain unchanged. + +## Alternatives considered + +**Repeat existing migration and first-open variants.** Rejected: those twelve cases already distinguish read-only preparation from writable publication. These cases use the current generation and begin or continue actual model work, or enumerate a corpus rather than open one Session. + +**Measure only deriveMessages.** Rejected: its incremental cache does not include complete request freezing, adapter dispatch, live append, or persistence. Actual sequential requests protect the cost the Agent pays per step. + +**Use only unseeded children with warm projection-cache rows.** Rejected: that path bypasses body observations and misses the exact inherited-cut requirement of fork children. The catalog intentionally omits the optional projection cache and reports the seeded fallback path; it does not characterize cache-hit discovery. + +**Apply an optimization and its desired budget together with the first measurements.** Rejected: a baseline-only layer remains independently mergeable and records the current workload before attribution or implementation changes. Source constants cannot be overridden by environment variables. + +## Consequences + +The lane adds four cases in three scenario groups and twenty measured workers, plus two seed processes. The integrated continuation case spans resume through completed model/tool work and durable flush. The shipped SDK workflow additionally includes profile boot, SDK transport, real file tools, and shutdown; only its model adapter is synthetic. It starts a fresh Session because the public SDK prompt API creates rather than resumes stored identities. Neither path includes network model latency, provider-specific request serialization, optional user plugins, compaction, failed tool results, images, cancellation, or browser rendering. Functional tests retain responsibility for event contents, immutable messages, tool semantics, fork lineage, and read-only versus writable side effects; endpoint counts prevent timing a skipped workload without duplicating those assertions. + +This note supplements, rather than supersedes, the Session-opening gate's isolation and calibration rationale. No existing active decision is retired. diff --git a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md new file mode 100644 index 0000000000..0fb36ba537 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md @@ -0,0 +1,68 @@ +# Agent Note: 工具密集后端续聊的性能基线 + +Status: implemented + +[English](2026-09-06-backend-continuation-performance.md) | 中文 + +## 问题 + +打开一个 Session 不能衡量长工具对话后重复准备模型请求、执行更多工具密集轮次或发现多个非活动 fork 子会话的成本。[Session 打开门禁](2026-09-04-session-open-performance-gate.zh.md)覆盖首屏历史和激活，但有意停在新的模型工作开始前。它的文本与推理负载也不包含历史工具调用参数和大型工具结果。 + +## 决定 + +[agent-continuation 基准](../../../../benchmarks/agent-continuation/agent-continuation.bench.ts)增加三个场景组，包含一个已发布 profile 变体，不修改产品实现。它们通过生产追加、流累积和持久化 API 构造当前代际的 Zstandard Session。独立播种进程在测量前生成确定性源数据；每个样本将其复制到私有根目录，并启动新的已编译纯 Node worker。输入不来自录制 Session、环境仓库、网络、私有 Harness 主目录或已部署 GUI。 + +共享历史包含 800 个已完成的双步骤轮次，每轮四次工具调用，工具结果为 2,048 字符：共 13,600 个事件和 5,600 条对话消息。每条助手回复携带推理、文本和紧凑流记录；请求工具的回复还携带分片参数。播种数据使用固定时间戳和 id。实时合成回复使用真实循环的时钟和 id，不覆盖进程全局状态。 + +| 用例 | 计时操作 | 终点 | +|---|---|---| +| 请求历史 | 在不计时的冷恢复后，向工具密集历史顺序提交 40 个纯文本轮次，然后 flush | 空闲 Agent，已完成全部 40 次模型请求；分别报告轮次和最终 flush 时间 | +| 工具续聊 | 冷恢复，顺序执行 20 个轮次，每轮八次可安全并行的合成工具调用和一条最终回复，然后 flush | 空闲 Agent，已完成 40 次模型请求和 160 次工具执行；分别报告恢复、轮次和最终 flush 时间 | +| 已发布 SDK 工作流 | 使用 sdk-minimal profile 启动已构建 dsh，顺序提交 100 个轮次，每轮八次真实文件查看调用，然后关闭 SDK | SDK 收到 200 条助手消息和 800 个成功文件结果；包含 Loader 启动、stdio JSON-RPC、持久化和关闭 | +| 子会话目录 | 通过真实 subagent 和 Session 查询服务，两次列出 16 个非活动、带种子的 fork 子会话 | 两份完整健康目录，观察已释放；每个子会话继承 80 个工具密集轮次，并在精确 fork 切点后拥有自己的描述符 | + +工具执行管线、请求准备、这些服务所需的 Session 投影、持久化和目录观察均保留生产代码。只有模型适配器和有界工具体是合成的。适配器只保留请求计数，不保留请求对象，因此 fixture（测试前置数据）不会制造不断增长的保留成本。顺序输入使每个空闲区间对应此 worker 提交的唯一请求；这不代表并发输入时可以把空闲状态推广为逐消息完成 API。 + +五个样本报告原始壁钟时间、CPU 用户态／内核态时间、峰值 RSS、终点计数及总壁钟时间的最小值、中位数和最大值。预算约束未经舍入的中位数。续聊还相对已初始化 Host 测量保留堆内存：计时操作前后各执行两次显式 GC，中间让出一次事件循环，空闲 Agent 始终可达。因此该增量包含常驻历史 Session 和实时追加，而不只是新轮次。GC 与资源释放不计时；flush 计时。请求历史的内存基线从恢复后开始，只作诊断。目录峰值 RSS 仅作诊断；没有保留堆预算声称衡量已经释放的子会话观察。 + +父进程为每个子进程设置 60 秒上限，独立检查超时、信号、退出状态和报告，等待进程关闭，并在失败后删除私有根目录。Context 和 Agent 在 finally 中释放。播种进程无法预热被测进程的缓存。不强制清除文件系统缓存：冷指新进程，不指冷物理存储。 + +## 校准证据 + +实现参考为 Apple M4 Pro、macOS arm64、Node 24.19.0 上的 `925e012340f033f0521e802ba8569ce6dd7ef1ac`。两轮独占的五样本运行使用相同播种数据，没有产品优化。下表时间单位为毫秒；源码期望值向上取整至实测各轮中位数以上，而不是施加尚未实现的优化目标。 + +| 用例 | 第一轮原始总时间 | 第二轮原始总时间 | 中位数 | 历史 M4 期望 | 历史缩放预算 | +|---|---|---|---|---:|---:| +| 请求历史 | 209.134, 210.333, 208.959, 236.355, 238.685 | 222.833, 213.911, 208.089, 211.494, 209.137 | 210.333 / 211.494 | 220 | 550 | +| 工具续聊 | 358.953, 324.790, 318.861, 320.119, 322.896 | 324.280, 321.952, 340.409, 325.470, 324.312 | 322.896 / 324.312 | 340 | 850 | +| 子会话目录 | 318.730, 309.006, 311.404, 308.565, 310.105 | 308.670, 310.030, 280.086, 303.084, 284.829 | 310.105 / 303.084 | 320 | 800 | + +续聊保留约 22.295 MiB；源码期望值为 23 MiB，预算为 28.75 MiB。SDK 时间期望值使用现有[校准辅助函数](../../../../benchmarks/support/calibration.ts)：2× 共享 CI 时间比例和 1.25× 波动余量。请求历史使用[请求冻结校准](../simplification/2026-09-06-agent-request-freeze-provenance.zh.md)中的直接托管期望值，不乘以 2× 比例。内存只使用 1.25× 余量。比例继承现有通道的校准，并非这些用例的新 Linux 实测值；runner 特征变化时仍需 CI 证据。基线预算保护实测实现；更紧预算属于有测量依据且保持行为的修复。 + +独立的纯 Node 请求历史 CPU profile 在一次 211.300 ms 操作中，将 132.876 ms 采样自身时间归因于 buildRequest 调用的 deepFreeze。这把重复遍历已冻结历史定位为聚焦调查目标，不是已证实的优化结果。目录首次／重复时间分别保留，因为观察释放后第二次列举仍读取带种子子会话的正文。 + +已发布 SDK 变体完成 100 个轮次、200 次请求和 800 次真实文件读取。五样本 smoke 总时间为 1,521.773、1,463.465、1,689.701、1,365.485 和 1,417.106 ms（中位数 1,463.465 ms）；完整套件重复运行报告 1,596.183、1,784.536、2,120.082、1,405.365 和 1,355.894 ms（中位数 1,596.183 ms）。1,700 ms 参考期望对应 4,250 ms CI 预算。重复运行中未改变的服务用例也变慢，因此这是可变主机负载下的验证，不是放宽其独占校准预算的依据。SDK 进程使用白名单环境和私有主目录／工作区。40 秒截止时间启动 SDK 关闭；所有路径等待同一个记忆化 close Promise，并早于外层 worker 的 60 秒截止时间。Profile 时间包含启动、全部轮次和关闭，分别报告；不把父进程 CPU 或堆指标当作服务端内存。适配器不为外部模型服务商序列化请求。 + +提交 `1dc3296eba631d51fbb3bb50e249bf3cc0fce9f6` 的首次 Linux x64 CI 测量使用 `VM-7-113-ubuntu-ci-10` 和 Node 24.18.1（[run 34017868081，attempt 1，job 101444810498](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34017868081/job/101444810498)）。SDK 中位数为 2,753.441 ms，预算为 4,250 ms；工具续聊保留堆中位数为 22.274 MiB，预算为 28.75 MiB。请求历史与工具续聊时间预算失败：分别为 785.498 ms 对 550 ms、1,077.285 ms 对 850 ms。未修改的 Session 重开 open 阶段也以 31.6 ms 对 30 ms 失败。[Attempt 2，job 101447076381](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34017868081/job/101447076381) 在同一提交和未修改预算下通过全部基准，但使用 `VM-7-113-ubuntu-ci-29` 和 Node 24.19.0。门禁运行器隐藏成功子进程的输出，因此该次运行只提供通过结论，不提供原始中位数。Runner 与 Node 版本同时变化，不能把差异仅归因于资源争用，也不能宣称已获得稳定的重复 CI 校准；这些证据不改变预算或共享比例。 + +目录用例使用显式的 900 ms CI 期望时间，仅乘现有 1.25× 余量，得到 1,125 ms，不再应用参考机器比例。标准双 CPU 托管 `ubuntu-24.04` 的 [run 34033336380，job 101487280801](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336380/job/101487280801) 报告未修改目录实现的五个总时间为 797.374、883.157、858.364、790.569 和 904.579 ms：中位数 858.364 ms 超出历史 800 ms 预算。上表 320 ms M4 期望保留为历史证据，不是 CI 测量。此方法与 Session 重开使用的显式 CI 校准一致（CI 期望为 50 ms）；共享系数、负载、计时终点和产品实现均不改变。确定性对照与实测判定使用同一断言：未经舍入的录制中位数通过 1,125 ms 并被 800 ms 拒绝，合成的 1,400 ms 中位数则被 1,125 ms 拒绝。更快主机上的通过结果不能校准标准托管 runner。 + +工具续聊同样使用 900 ms CI 期望时间与 1.25× 余量（1,125 ms）。未修改实现的 `79c052ab29` 在标准双 CPU 托管 [run 34034524265，job 101490056074](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34034524265/job/101490056074) 中报告总时间为 917.007、892.091、887.839、905.659 和 898.252 ms：中位数 898.252 ms 超出历史 850 ms 预算。340 ms M4 期望保留为历史证据。与实测判定相同的断言在 1,125 ms 下接受未经舍入的录制中位数，在 850 ms 下拒绝它，并拒绝合成的 1,400 ms 回退。负载、计时、产品代码和 28.75 MiB 保留堆预算均不改变。 + +基线请求历史使用 600 ms CI 期望时间与 1.25× 余量（750 ms）。未修改实现的 `54d1190a75` 在标准双 CPU 托管 [run 34035306987，job 101492163630](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34035306987/job/101492163630) 中报告总时间为 618.598、618.606、582.035、582.304 和 581.832 ms：中位数 582.304 ms 超出历史 550 ms 预算。220 ms M4 期望保留为历史证据。与实测判定相同的断言在 750 ms 下接受未经舍入的录制中位数，在 550 ms 下拒绝它，并拒绝合成的 900 ms 回退。此校准仅针对未优化基线；负载、计时、产品代码和内存预算均不改变。 + +## 考虑过的替代方案 + +**重复现有迁移和首次打开变体。** 拒绝：现有十二个用例已经区分只读准备与可写发布。这些用例使用当前代际并开始或继续实际模型工作，或者列举语料集合而不是打开单个 Session。 + +**只测 deriveMessages。** 拒绝：它的增量缓存不包含完整请求冻结、适配器分发、实时追加或持久化。实际顺序请求保护 Agent 每一步支付的成本。 + +**只使用投影缓存行已预热的无种子子会话。** 拒绝：该路径绕过正文观察，遗漏 fork 子会话的精确继承切点要求。目录用例有意不挂载可选投影缓存，报告带种子的回退路径；它不代表缓存命中的发现过程。 + +**将优化及其目标预算与首次测量一起应用。** 拒绝：纯基线层可以独立合并，并在归因或实现改变前记录当前负载。环境变量不能覆盖源码常量。 + +## 后果 + +通道增加三个场景组中的四个用例、二十个测量 worker 和两个播种进程。集成续聊用例覆盖恢复、完成模型／工具工作及持久化 flush。已发布 SDK 工作流额外包含 profile 启动、SDK 传输、真实文件工具和关闭；只有模型适配器是合成的。它创建新 Session，因为公共 SDK prompt API 创建而非恢复已存储身份。两条路径均不包含网络模型延迟、服务商专属请求序列化、可选用户插件、压缩、失败工具结果、图像、取消或浏览器渲染。功能测试仍负责事件内容、不可变消息、工具语义、fork 谱系以及只读／可写副作用；终点计数防止把跳过的工作当作测量结果，不重复这些断言。 + +本记录补充而非取代 Session 打开门禁的隔离和校准依据。不退役任何现有活跃决策。 diff --git a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.i18n.yaml b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.i18n.yaml new file mode 100644 index 0000000000..1e2848dfde --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.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/testing/2026-09-06-frontend-performance-budgets.md +2026-09-06-frontend-performance-budgets.md: 7dc7af97d8bb65c17109ab675c250085c9c5831c +2026-09-06-frontend-performance-budgets.zh.md: 9935e382ec4c3c3ede762b23339f14c014b67c4e diff --git a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md new file mode 100644 index 0000000000..7dc7af97d8 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md @@ -0,0 +1,85 @@ +# Agent Note: Frontend large-session performance budgets + +Status: implemented + +English | [中文](2026-09-06-frontend-performance-budgets.zh.md) + +## Problem + +A fast Node conversation fold does not prove that a browser paints a long conversation or remains responsive while a response streams. Active reconnect also reconstructs a different representation from settled history: a compact prefix becomes public per-chunk Client entries. The [Session performance policy](2026-09-04-session-open-performance-gate.md) supplies an isolated CI job but does not measure these user paths. + +## Decision + +The existing serial benchmark inventory includes two frontend owners: [active reconnect](../../../../benchmarks/active-stream-reconnect/README.md) and a [browser workflow](../../../../benchmarks/long-session-browser/README.md). The browser workflow combines cold open, older-page navigation, first Trajectory activation, return to Chat, and a paced response with trusted keyboard input into one sequential scenario. These are endpoints of one workflow, not independent cold scenarios. The settled conversation-fold benchmark remains unchanged. + +`build:bench` keeps the Node-only library and worker build. `test:bench` additionally builds the Web shell before running all cases; the required benchmark CI job follows the [standard hosted runner decision](2026-09-06-standard-hosted-benchmark-runner.md), unconditionally provisions Chromium and its Linux dependencies on that hosted runner, and enables the existing verbose gate output so successful raw samples remain available for calibration. Browser cases reuse the shipped-composition Web scaffold with private temporary roots and an atomically assigned loopback port. Only the nondeterministic model is replaced by synthetic replay. The scaffold Host runs under the existing Vitest source resolver; measured Client rendering runs built bundles in fresh Chromium processes. Browser wall times therefore include this test Host, transport, Playwright actionability, and rendering, and are not claims about a published Host process. + +The browser input contains 240 closed turns, 40 tool results, and 20 code fences, plus mixed-language prose and reasoning. Historical Assistant records carry matching compact streams built through the production accumulator with 12-character reasoning/text deltas and 8-character tool-argument deltas; empty streams would omit stored and transferred payload costs. Nine older-page actions exhaust this input from its observed 25-turn initial window; the readiness probe follows mounted turn growth rather than duplicating the pagination algorithm. Each sample uses a fresh scaffold and browser. Setup, seeding, browser launch, initial shell load, and sidebar expansion are excluded from open timing. Open ends at transcript availability and an editable composer; page and navigation timings end at their target DOM state. Two animation frames include a rendering opportunity, not hardware presentation or a guarantee that every offscreen node painted. + +The continuation sends 120 text deltas at 16 ms replay pacing. The input witness is installed before Send; typing starts immediately after the first visible marker, without a separate pre-input animation-frame wait. Send lookup stays inside the composer seat; first/final marker lookups stay inside the latest Assistant step and retain visible-state waits. The synchronous input witness reads that same bounded reply. Whole-history text and accessibility queries add observer CPU and garbage collection to the measured interval, so reducing that observer work is benchmark repair, not product optimization. It records click-to-first-visible-reply, trusted draft typing whose first actual input event observes the first reply but no completion marker, complete reply wall time through settled persistence and the new rendered turn-tail, and Chromium main-thread task duration. The complete wall budget adds the fixed 1984 ms scripted pacing to a scaled overhead allowance; input and completion have their own enforced budgets. Post-GC browser heap and DOM counts remain diagnostics because one endpoint does not prove a leak. + +Reconnect uses three fresh compiled plain-Node children. Each creates a 100,000-delta reasoning prefix with distinct timestamps and two compact records before timing `ClientAssistantStream.replace()`. GC precedes the baseline and follows replacement while the result remains reachable; replacement time excludes both collections. The report consumes the result after collection and checks that the next dense live frame remains accepted. This measures reconstruction, not transport, rendering, or an entire reconnect workflow. + +## Calibration + +Three-sample medians on the arm64 reference machine, Node 24.19 and Chromium 149.0.7827.55, at product revision `925e012340`, establish the baseline below. An isolated repeat follows a complete workflow smoke. Each browser sample reports raw endpoint values and every page; the paging verdict uses the median of the sample maxima. Reconnect reports all child measurements. The following historical reference table uses 8 ms replay pacing and includes a two-frame wait in first-reply timing. Standard-hosted open, paging, Trajectory, and reconnect expectations are recorded separately below; other source reference constants retain these allowances. The bounded-observer 261.60 ms paging median exceeds its 260 ms reference allowance but remains below its 650 ms CI limit; the shared 2× time scale and 1.25× variance allowance produce CI limits. Memory uses only variance allowance. The shared scale originates in Node CI calibration. Both actual x64 browser runs below pass the fixed budgets on unchanged benchmark code; this supplies repeated-run evidence for these runners, not a universal browser speed ratio. + +| Endpoint | Measured median | Reference allowance | Historical CI limit | +|---|---:|---:|---:| +| Browser open | 184.62 ms | 200 ms | 500 ms | +| Slowest older page | 261.60 ms | 260 ms | 650 ms | +| First Trajectory | 136.46 ms | 160 ms | 400 ms | +| First reply | 373.72 ms | 1100 ms | 2750 ms | +| Stream main-thread task | 1053.87 ms | 1800 ms | 4500 ms | +| Draft typing | 487.35 ms | 500 ms | 1250 ms | +| Complete response | 1366.36 ms | 1000 ms overhead + 992 ms pacing | 3492 ms | +| Reconnect replacement | 13.83 ms | 16 ms | 40 ms | +| Reconnect retained heap | 23.03 MiB | 24 MiB | 30 MiB | + +Draft typing spans 124.97–504.96 ms across the three isolated samples; the reference remains 500 ms and the scaled CI limit covers that observed spread; the median is not a per-keystroke bound. No budget is an environment override. Temporary zero allowances exercise every rejection path; these negative controls prove enforcement, not an optimization or a historical regression. A separate control waits for the final reply marker before typing and fails the actual-input overlap assertion. The compact synthetic JSONL is 3,262,577 bytes; all three corrected samples report an overlapping trusted input event and end after the 241st rendered turn-tail. + +### Actual CI runs + +[Run 34020120425, benchmark job 101451135853](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34020120425/job/101451135853) passes the complete benchmark inventory at `6d1ba089e5052680961825c08aa4de19b4fe137a`. The runner is `VM-7-113-ubuntu-ci-19` in `dsh-selfhosted-ci`, using x64 Node 24.19.0 and Chromium 149.0.7827.55. [Attempt 2, benchmark job 101453296071](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34020120425/job/101453296071) also passes the complete inventory at the same commit, on `VM-7-113-ubuntu-ci-25` with the same Node and Chromium versions. The following medians use three fresh samples per scenario in each run and leave the local reference table and source budgets unchanged. + +| Endpoint | First CI median | Second CI median | +|---|---:|---:| +| Browser open | 303.066 ms | 284.726 ms | +| Slowest older page | 432.979 ms | 413.798 ms | +| First Trajectory | 298.608 ms | 267.372 ms | +| First reply | 740.265 ms | 658.906 ms | +| Stream main-thread task | 1614.594 ms | 1035.385 ms | +| Draft typing | 932.746 ms | 142.148 ms | +| Complete response | 1677.882 ms | 1641.702 ms | +| Reconnect replacement | 29.232 ms | 31.674 ms | +| Reconnect retained heap | 23.028 MiB | 23.028 MiB | + +All six browser samples report `inputOverlapped: true` and finish after the 241st rendered turn-tail. Post-GC browser heap is approximately 52.94 MiB in the first run and 53.00 MiB in the second, with 17,064 DOM elements in both; these remain diagnostic endpoints. Both runs support the existing budgets on these runners, not a universal 2× browser speed ratio. Draft-typing medians vary from 932.746 ms to 142.148 ms because the endpoint measures the entire typed draft, including scheduling and Playwright actionability, rather than a per-key latency guarantee. These are self-hosted measurements, not standard-hosted calibration; no product optimization is claimed. + +### Standard hosted expectations and input scheduling + +[Run 34033336246, job 101487216170](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336246/job/101487216170) on standard hosted Ubuntu with two CPUs records reconnect replacements of 46.574411, 46.067910, and 44.193704 ms, with 23.028 MiB retained heap. The endpoint-specific expectation is 50 ms; the existing 1.25× headroom gives a 63 ms integer ceiling. The 30 MiB memory budget and shared machine factor remain unchanged. Browser open records 681.276514 and 541.051233 ms before the third sample fails input overlap; both exceed the historical 500 ms limit. Repeated hosted open measurements below set its expectation and ceiling. Deterministic controls pass these recorded values and reject values above the new ceilings through the same assertions as the measured verdicts. Complete repeated hosted verdicts remain required; the two open values are not a three-sample median. + +A local diagnostic with temporary 3× Chromium CPU throttling reproduces the overlap failure: the first marker becomes visible at 1321 ms, two animation frames finish at 1370 ms, and the composer click finishes at 1660 ms; the actual input is trusted but already sees DONE. Removing the frame wait and installing the witness before Send still leaves a run with first visibility at 1415 ms and click completion at 1726 ms, after the original 992 ms scripted stream. The fixed 16 ms cadence keeps the same 120 deltas and payload, providing 1984 ms of scripted pacing for this workload. Only that pacing term changes in the complete-wall allowance (4484 ms); input, first-reply, and main-thread overhead allowances remain unchanged. With the same diagnostic slowdown, three 16 ms samples reach first visibility at 1307/1479/1599 ms and accept trusted input before DONE; their post-DONE controls reject it. The diagnostic is not a CPU-ratio calibration. Each measured sample still requires trusted input while FIRST is present and DONE absent; a post-measurement trusted key after DONE must fail that same assertion. Host settlement and the 241st rendered turn-tail remain completion witnesses. + +[Run 34034524861, job 101490135303](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34034524861/job/101490135303) records three complete browser samples with trusted input overlap and passing post-DONE rejection controls. Slowest-page samples are 843.941625/672.834329/684.461818 ms (median 684.461818); first-Trajectory samples are 605.788061/367.754027/485.931656 ms (median 485.931656). Their endpoint-specific hosted expectations are 700 and 500 ms, with the same 1.25× headroom producing 875 and 625 ms limits. Recorded-median controls reject the historical 650/400 ms limits, accept these hosted limits, and reject one millisecond above each limit through the measured verdict's assertion. Open, first reply, main-thread task, input, and complete-wall medians are 713.910/1486.206/2806.415/947.398/2986.983 ms; only the open limit is recalibrated by the repeated measurements below. This run supplies calibration data, not a passing benchmark verdict; a complete hosted repeat remains required. + +[Run 34036109842, job 101494445658](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34036109842/job/101494445658) records open samples of 875.306861/1083.683529/814.700998 ms, with a median of 875.306861 ms versus 713.909727 ms in the preceding hosted run. The endpoint-specific expectation is 900 ms, rounding up the larger repeated median rather than adding an epsilon to the 875 ms limit; unchanged 1.25× headroom gives 1125 ms. The same enforced assertion accepts the recorded median, rejects it at both historical 500 and 875 ms limits, and rejects a synthetic 1126 ms value at the current limit. All three samples retain trusted input overlap and post-DONE rejection; every other frontend median remains within its unchanged limit. This calibration does not claim a green CI run. + +## Alternatives considered + +**Use the Node fold as paint evidence.** Rejected because it never performs DOM mutation, layout, or browser scheduling. The focused reconnect case likewise makes no GUI speed claim. + +**Promote the entire manual browser diagnostic into CI.** Rejected because its 1,000-session sidebar and 100-turn soak cover a much broader workload. The bounded required case reuses its shipped scaffold and measurement approach without importing a test module or changing the manual inventory. + +**Coalesce active reconnect chunks.** Rejected as a benchmark shortcut: Client entries expose per-member ordering and timestamps to conversation definitions. The benchmark retains that production behavior; reducing retained entries requires a separate semantic design, not copied product algorithms or a synthetic approximation. + +**Search the entire loaded history for every stream marker.** Rejected because Playwright injects text and accessibility scans into the same renderer whose CPU the benchmark measures. Scoping queries to the composer and latest Assistant preserves visible completion checks without making observer cost proportional to loaded history. + +**Measure stream CPU alone.** Rejected because transport stalls and final-settlement delays can leave main-thread CPU low. The independent input, first-reply, and complete-wall budgets cover those waits. + +## Consequences + +The benchmark layer changes no product implementation or user-visible behavior. It adds approximately fifteen seconds of local browser/reconnect execution plus Web build and browser provisioning to the existing isolated CI lane. A fresh browser discards previous caches, but each workflow deliberately retains its own loaded history and previously activated Trajectory during continuation. + +The baseline is independently mergeable and protects current performance; optimization layers tighten budgets only with repeated measurements and focused semantic tests. It does not cover sidebar cardinality, an hours-long soak, GPU presentation, real model latency, a published Host launch, or reconnect rendering. The [Web browser lane](2026-07-24-web-gui-browser-e2e-lane.md) retains its separate threshold-free manual diagnostics and functional browser tests; calibrated required measurements belong to this benchmark lane. The existing Session performance note remains active because it owns Node calibration and persistence rationale; this note extends rather than supersedes it. diff --git a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md new file mode 100644 index 0000000000..9935e382ec --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md @@ -0,0 +1,85 @@ +# Agent Note: 前端长 Session 性能预算 + +Status: implemented + +[English](2026-09-06-frontend-performance-budgets.md) | 中文 + +## 问题 + +Node 对话折叠很快，并不能证明浏览器能绘制长对话或在流式回复期间保持响应。活跃重连还会重建与已结算历史不同的表示：紧凑前缀变成公开的逐 chunk Client 条目。[Session 性能策略](2026-09-04-session-open-performance-gate.zh.md)提供隔离的 CI job，但不测量这些用户路径。 + +## 决策 + +现有串行基准清单包含两个前端所有者：[活跃重连](../../../../benchmarks/active-stream-reconnect/README.zh.md)和[浏览器工作流](../../../../benchmarks/long-session-browser/README.zh.md)。浏览器工作流在一个顺序场景中组合冷打开、更早分页导航、首次激活 Trajectory、返回 Chat，以及伴随真实键盘输入的有节奏回复。这些是同一工作流的测量终点，而不是相互独立的冷场景。已结算对话折叠基准保持不变。 + +`build:bench` 保留仅 Node 的 library 与 worker 构建。`test:bench` 额外构建 Web shell 后再运行所有用例；必需的基准 CI job 遵循[标准托管运行器决策](2026-09-06-standard-hosted-benchmark-runner.zh.md)，在该托管运行器上无条件安装 Chromium 及其 Linux 依赖，并启用现有门禁详细输出，使成功用例的原始样本可用于校准。浏览器用例复用产品组合的 Web scaffold，使用私有临时目录和原子分配的回环端口。只有不确定的模型被合成重放替代。scaffold Host 通过现有 Vitest 源码解析器运行；被测 Client 渲染在全新 Chromium 进程中执行构建后的 bundle。因此浏览器壁钟时间包含测试 Host、传输、Playwright 可交互性等待及渲染，不代表发布版 Host 进程。 + +浏览器输入包含 240 个已关闭轮次、40 个工具结果和 20 个代码块，以及混合语言正文和推理。历史 Assistant 记录携带匹配的紧凑 stream，通过生产 accumulator 按 12 字符推理/文本 delta 和 8 字符工具参数 delta 构建；空 stream 会遗漏存储与传输负载成本。从观察到的初始 25 轮窗口开始，九次更早分页操作读完该输入；就绪探针跟踪已挂载轮次增长，不复制分页算法。每个样本使用全新 scaffold 和浏览器。环境准备、数据播种、浏览器启动、初始 shell 加载及侧栏展开不计入打开时间。打开测量在对话可用且输入框可编辑时结束；分页与导航测量在目标 DOM 状态出现时结束。两次动画帧包含一次渲染机会，不代表硬件显示或保证每个屏幕外节点都已绘制。 + +续接以 16 ms 重放间隔发送 120 个文本 delta。输入观察器在发送前安装；首个标记可见后立即开始键入，不单独等待输入前动画帧。发送控件查找限制在 composer seat；首段/最终标记查找限制在最新 Assistant step，并保留可见状态等待。同步输入证据读取同一个受限回复。全历史文本与无障碍查询会向测量区间加入观察器 CPU 和垃圾回收成本，因此减少此类观察工作属于基准修正，而非产品优化。它记录点击到首段可见回复的时间、首个实际输入事件观察到首段回复且完成标记尚未出现时的真实草稿键入、直到持久化结算并渲染新 turn-tail 的完整回复壁钟时间，以及 Chromium 主线程任务时间。完整壁钟预算在缩放后的额外开销额度上加固定的 1984 ms 脚本节奏；输入和完成均有独立执行的预算。强制 GC 后的浏览器 heap 和 DOM 数量仍仅供诊断，因为单个终点不能证明泄漏。 + +重连使用三个全新编译后的纯 Node 子进程。各进程在计时 `ClientAssistantStream.replace()` 前创建包含不同时间戳、两条紧凑记录和 100,000 个 delta 的推理前缀。在基线前执行 GC，并在结果仍可达时于替换后再次 GC；替换时间不含两次回收。报告在回收后消费结果，并检查下一个稠密序号的实时 frame 仍被接受。这测量重建，不测量传输、渲染或完整重连工作流。 + +## 校准 + +在 arm64 参考机器、Node 24.19、Chromium 149.0.7827.55 和产品版本 `925e012340` 上，三个样本的中位数建立下表基线。完整工作流 smoke 后执行一次隔离重复测量。每个浏览器样本报告原始终点数据和每一页；分页判定使用各样本最大值的中位数。重连报告全部子进程测量。下列历史参考表使用 8 ms 重放节奏，首段回复计时包含两帧等待。标准托管打开、分页、Trajectory 和重连预期在下文单独记录；其他源码参考常量保留这些额度。受限观察器的分页中位数 261.60 ms 超过 260 ms 参考额度，但仍低于 650 ms CI 限制；共享的 2× 时间倍率和 1.25× 方差余量产生 CI 限制。内存仅使用方差余量。共享倍率源自 Node CI 校准。下述两次实际 x64 浏览器运行在基准代码不变的情况下均通过固定预算；这提供这些 runner 的重复运行证据，而非普遍适用的浏览器速度比。 + +| 终点 | 实测中位数 | 参考额度 | 历史 CI 限制 | +|---|---:|---:|---:| +| 浏览器打开 | 184.62 ms | 200 ms | 500 ms | +| 最慢更早分页 | 261.60 ms | 260 ms | 650 ms | +| 首次 Trajectory | 136.46 ms | 160 ms | 400 ms | +| 首段回复 | 373.72 ms | 1100 ms | 2750 ms | +| 流式主线程任务 | 1053.87 ms | 1800 ms | 4500 ms | +| 草稿键入 | 487.35 ms | 500 ms | 1250 ms | +| 完整回复 | 1366.36 ms | 1000 ms 额外开销 + 992 ms 节奏 | 3492 ms | +| 重连替换 | 13.83 ms | 16 ms | 40 ms | +| 重连保留 heap | 23.03 MiB | 24 MiB | 30 MiB | + +三个隔离样本中的草稿键入时间为 124.97–504.96 ms；参考额度保持 500 ms，缩放后的 CI 限制覆盖观察到的波动；中位数不是单次按键上限。预算不能通过环境变量覆盖。临时零额度覆盖每条拒绝路径；这些负向对照证明预算执行，而非优化或历史回归。另一项对照在键入前等待最终回复标记，实际输入重叠断言因此失败。紧凑合成 JSONL 为 3,262,577 字节；三个修正样本均报告重叠的真实输入事件，并在第 241 个 turn-tail 渲染后结束。 + +### 实际 CI 运行 + +[运行 34020120425，基准 job 101451135853](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34020120425/job/101451135853) 在 `6d1ba089e5052680961825c08aa4de19b4fe137a` 上通过完整基准清单。runner 为 `dsh-selfhosted-ci` 中的 `VM-7-113-ubuntu-ci-19`，使用 x64 Node 24.19.0 和 Chromium 149.0.7827.55。[第 2 次执行，基准 job 101453296071](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34020120425/job/101453296071) 在相同 commit 上也通过完整清单，runner 为 `VM-7-113-ubuntu-ci-25`，Node 和 Chromium 版本相同。下列中位数来自每次运行中每个场景的三个全新样本，本地参考表和源码预算保持不变。 + +| 终点 | 首次 CI 中位数 | 第二次 CI 中位数 | +|---|---:|---:| +| 浏览器打开 | 303.066 ms | 284.726 ms | +| 最慢更早分页 | 432.979 ms | 413.798 ms | +| 首次 Trajectory | 298.608 ms | 267.372 ms | +| 首段回复 | 740.265 ms | 658.906 ms | +| 流式主线程任务 | 1614.594 ms | 1035.385 ms | +| 草稿键入 | 932.746 ms | 142.148 ms | +| 完整回复 | 1677.882 ms | 1641.702 ms | +| 重连替换 | 29.232 ms | 31.674 ms | +| 重连保留 heap | 23.028 MiB | 23.028 MiB | + +六个浏览器样本均报告 `inputOverlapped: true`，并在第 241 个 turn-tail 渲染后结束。强制 GC 后浏览器 heap 首次运行约为 52.94 MiB，第二次约为 53.00 MiB，两次 DOM 元素均为 17,064 个；这些仍为诊断终点。两次运行支持这些 runner 上的现有预算，而不证明普遍适用的 2× 浏览器速度比。草稿键入中位数从 932.746 ms 变化到 142.148 ms，因为该终点测量整个草稿键入，包含调度和 Playwright 可交互性等待，而非单次按键延迟保证。这些是自托管测量，而非标准托管校准；不声称产品优化。 + +### 标准托管预期与输入调度 + +[运行 34033336246，job 101487216170](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34033336246/job/101487216170) 在双 CPU 标准托管 Ubuntu 上记录重连替换时间 46.574411、46.067910 和 44.193704 ms，保留 heap 为 23.028 MiB。该终点的预期为 50 ms；现有 1.25× 余量产生向上取整后的 63 ms 上限。30 MiB 内存预算及共享机器倍率不变。浏览器打开记录 681.276514 和 541.051233 ms，第三个样本因输入重叠失败而中止；两个值均超过历史 500 ms 上限。下文的托管打开重复测量决定其预期与上限。确定性对照通过这些记录值，并使用与测量判定相同的断言拒绝超过新上限的值。仍需完整的托管重复运行判定；这两个打开值不是三样本中位数。 + +临时使用 3× Chromium CPU 降速的本地诊断复现重叠失败：首个标记在 1321 ms 可见，两次动画帧在 1370 ms 结束，输入框点击在 1660 ms 完成；实际输入是真实事件，但已看到 DONE。移除帧等待并在发送前安装观察器后，一次运行仍在 1415 ms 才看到首个标记，点击在 1726 ms 完成，晚于原先 992 ms 的脚本流。固定 16 ms 节奏保留相同的 120 个 delta 和负载，为该工作负载提供 1984 ms 脚本节奏。完整壁钟额度仅改变该节奏项（4484 ms）；输入、首段回复及主线程额外开销额度不变。在相同诊断降速下，三个 16 ms 样本在 1307/1479/1599 ms 达到首段可见状态，并接受 DONE 之前的真实输入；其 DONE 之后的对照拒绝该输入。该诊断不是 CPU 比率校准。每个测量样本仍要求真实输入发生时 FIRST 存在且 DONE 不存在；测量后在 DONE 之后发送的真实按键必须无法通过同一个断言。Host 结算和第 241 个已渲染 turn-tail 仍是完成证据。 + +[运行 34034524861，job 101490135303](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34034524861/job/101490135303) 记录三个完整浏览器样本，均具有真实输入重叠，并通过 DONE 之后的拒绝对照。最慢分页样本为 843.941625/672.834329/684.461818 ms（中位数 684.461818）；首次 Trajectory 样本为 605.788061/367.754027/485.931656 ms（中位数 485.931656）。两者的终点专属托管预期分别为 700 和 500 ms，相同的 1.25× 余量产生 875 和 625 ms 上限。记录中位数对照拒绝历史 650/400 ms 上限，接受这些托管上限，并通过测量判定所用断言拒绝超过各上限一毫秒的值。打开、首段回复、主线程任务、输入及完整壁钟的中位数为 713.910/1486.206/2806.415/947.398/2986.983 ms；仅打开上限根据下文的重复测量重新校准。该运行提供校准数据，不代表基准判定通过；仍需完整的托管重复运行。 + +[运行 34036109842，job 101494445658](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34036109842/job/101494445658) 记录打开样本 875.306861/1083.683529/814.700998 ms，中位数为 875.306861 ms，前一次托管运行的中位数为 713.909727 ms。该终点的预期为 900 ms，向上取整较大的重复测量中位数，而非向 875 ms 上限增加微量余量；不变的 1.25× 余量产生 1125 ms 上限。同一个强制断言接受记录中位数，在历史 500 和 875 ms 上限下均拒绝它，并在当前上限下拒绝合成的 1126 ms 值。三个样本均保留真实输入重叠与 DONE 之后的拒绝；其他所有前端中位数均在不变的上限内。此校准不代表 CI 运行通过。 + +## 考虑过的替代方案 + +**用 Node 折叠作为绘制证据。** 拒绝，因为它不执行 DOM 修改、布局或浏览器调度。聚焦重连用例同样不声称 GUI 提速。 + +**把整个手动浏览器诊断提升到 CI。** 拒绝，因为其 1,000 Session 侧栏和 100 轮 soak 覆盖更广的工作负载。受限的必需用例复用其产品 scaffold 和测量方式，不导入测试模块，也不改变手动清单。 + +**合并活跃重连 chunk。** 不能作为基准捷径：Client 条目向对话定义公开每个成员的顺序和时间戳。基准保留该生产行为；减少保留条目需要独立的语义设计，而非复制产品算法或使用合成近似。 + +**每次流式标记查找都搜索全部已加载历史。** 拒绝，因为 Playwright 把文本与无障碍扫描注入同一个被测 CPU 的渲染进程。将查询限定在输入框和最新 Assistant 中，可保留可见完成检查，同时避免观察器成本随已加载历史增长。 + +**只测量流式 CPU。** 拒绝，因为传输停顿和最终结算延迟可能不增加主线程 CPU。独立的输入、首段回复和完整壁钟预算覆盖这些等待。 + +## 影响 + +基准层不改变产品实现或用户可见行为。它在现有隔离 CI lane 中增加约十五秒的本地浏览器与重连执行，以及 Web 构建和浏览器安装成本。全新浏览器丢弃此前的缓存，但每个工作流刻意在续接期间保留自身已加载历史和曾激活的 Trajectory。 + +基线可独立合并并保护现有性能；优化层只有在重复测量与聚焦语义测试支持下才收紧预算。它不覆盖侧栏数量级、数小时 soak、GPU 显示、真实模型延迟、发布版 Host 启动或重连渲染。[Web 浏览器车道](2026-07-24-web-gui-browser-e2e-lane.zh.md)保留独立的无阈值手动诊断与功能浏览器测试；经校准的必需测量由本基准车道负责。现有 Session 性能记录保持活跃，因为它拥有 Node 校准和持久化理由；本记录扩展而不替代它。 diff --git a/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.i18n.yaml b/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.i18n.yaml new file mode 100644 index 0000000000..0429f627ee --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.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/testing/2026-09-07-subagent-teardown-test-budgets.md +2026-09-07-subagent-teardown-test-budgets.md: 4fe83c421383aa768ffa0d33520407ed8d099d14 +2026-09-07-subagent-teardown-test-budgets.zh.md: 1487351d498c9d0ef9eb6c2e83e47425ac82b9c9 diff --git a/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.md b/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.md new file mode 100644 index 0000000000..4fe83c4213 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.md @@ -0,0 +1,28 @@ +# Agent Note: Subagent teardown tests inherit their execution lane budgets + +Status: implemented + +English | [中文](2026-09-07-subagent-teardown-test-budgets.zh.md) + +## Problem + +The [Windows coverage run](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34085536250/job/101628739668) reports two teardown failures despite granting tests and hooks 90 seconds. The ACP ignored-EOF test races disposal against its own five-second timer. The real Codex test overrides the hook budget with 30 seconds. Neither deadline tests a product latency guarantee. The Codex body has already observed process-tree exit before its hook fails; the log does not identify whether context disposal, HTTP closure, or temporary-directory removal exceeded the hook budget. + +## Decision + +The [ACP test](../../../../packages/subagent/subagent-acp/tests/subagent-acp.spec.ts) awaits disposal under the execution lane’s test budget, then checks the actual child outcome. Failure cleanup awaits disposal and child completion before removing the private directory. A deferred exit observation proves that disposal cannot finish merely because termination was requested. The production EOF and termination grace periods remain unchanged. + +The [Codex test](../../../../packages/subagent/subagent-codex/tests/real-product.spec.ts) inherits the execution lane’s hook budget. Cleanup captures its contexts, HTTP fixtures, and temporary roots before its first asynchronous wait, so an overdue hook cannot drain resources registered by another test. It preserves context-disposal, server-closure, and directory-removal ordering, waits for every captured disposer, and attempts the remaining cleanup stages after a rejection. Collected errors identify each failing stage or path and retain their causes; cleanup reports them only after all captured resources have been attempted. + +The [native Windows CI decision](../process/2026-08-08-native-windows-pull-request-ci.md) continues to own lane scheduling and budgets. This change only removes conflicting local deadlines and strengthens resource-lifetime assertions; it does not establish a Windows process-kill or filesystem defect. + +## Alternatives considered + +- Increase production grace periods or filesystem retries: the failures do not demonstrate incorrect product timing or exhausted removal retries. +- Replace local deadlines with larger constants: that would still override future lane budgets. +- Return from cleanup immediately after requesting termination: that would permit children or sockets to outlive the fixture. +- Serialize coverage: unrelated tests need not lose concurrency to accommodate two local deadline overrides. + +## Consequences + +The lane timeout remains a bound on hangs. Focused tests verify observed child completion and cleanup ownership instead of host termination speed. Native Windows runs remain necessary for taskkill, process-exit delivery, and NTFS removal evidence; passing macOS tests cannot prove those mechanisms. No model-visible output, Session fixture, production timeout, or CI routing changes. diff --git a/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.zh.md b/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.zh.md new file mode 100644 index 0000000000..1487351d49 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-07-subagent-teardown-test-budgets.zh.md @@ -0,0 +1,28 @@ +# Agent Note: 子代理清理测试继承执行通道的时间预算 + +Status: implemented + +[English](2026-09-07-subagent-teardown-test-budgets.md) | 中文 + +## 问题 + +[Windows 覆盖率运行](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34085536250/job/101628739668) 为测试和钩子提供 90 秒预算，却报告了两个清理失败。ACP 忽略 EOF 测试让清理与自设的五秒定时器竞争。真实 Codex 测试将钩子预算覆盖为 30 秒。这两个期限都不用于验证产品延迟保证。Codex 测试正文在钩子失败前已经观察到进程树退出；日志未指出究竟是上下文释放、HTTP 关闭还是临时目录删除超出了钩子预算。 + +## 决策 + +[ACP 测试](../../../../packages/subagent/subagent-acp/tests/subagent-acp.spec.ts) 在执行通道的测试预算内等待清理完成，然后检查真实子进程的结果。失败清理先等待释放和子进程完成，再删除私有目录。延迟的退出观察证明，清理不能仅因已请求终止而完成。生产环境的 EOF 与终止宽限期保持不变。 + +[Codex 测试](../../../../packages/subagent/subagent-codex/tests/real-product.spec.ts) 继承执行通道的钩子预算。清理在第一次异步等待前取得其上下文、HTTP 夹具和临时根目录，因此超时钩子不能取走其他测试注册的资源。清理保留上下文释放、服务器关闭、目录删除的顺序，等待所有已取得的释放操作，并在拒绝后继续尝试其余清理阶段。收集的错误指出各自失败的阶段或路径并保留原始原因；只有全部已取得资源都尝试清理后才报告错误。 + +[原生 Windows CI 决策](../process/2026-08-08-native-windows-pull-request-ci.zh.md) 继续负责通道调度和预算。本次改动仅移除冲突的局部期限并加强资源生命周期断言；它并不证明 Windows 进程终止或文件系统存在缺陷。 + +## 曾考虑的替代方案 + +- 增加生产环境宽限期或文件系统重试次数：这些失败不能证明产品时序错误或删除重试耗尽。 +- 用更大的常量替换局部期限：这样仍会覆盖未来的通道预算。 +- 请求终止后立即结束清理：这样会允许子进程或套接字存活超过夹具的生命周期。 +- 将覆盖率测试串行化：无关测试不应为两个局部期限覆盖而失去并发能力。 + +## 后果 + +通道超时仍为挂起提供时间上限。定向测试验证观察到的子进程完成和清理所有权，而不是宿主机终止速度。taskkill、进程退出通知和 NTFS 删除仍需原生 Windows 运行提供证据；macOS 测试通过不能证明这些机制。模型可见输出、Session 夹具、生产环境超时与 CI 路由均不变。 diff --git a/.github/workflows/ci-master.yml b/.github/workflows/ci-master.yml index c795413067..df9f7f2bcc 100644 --- a/.github/workflows/ci-master.yml +++ b/.github/workflows/ci-master.yml @@ -146,6 +146,12 @@ jobs: with: fetch-depth: 0 + # Redirect the Node compile cache (enabled by pnpm and TypeScript) off + # the root partition's /tmp before the first pnpm call in this lane — + # see .agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md. + - name: Redirect Node compile cache to runner temp + run: echo "NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache" >> "$GITHUB_ENV" + - uses: pnpm/action-setup@v4 with: dest: ${{ runner.temp }}/setup-pnpm-${{ github.run_id }}-${{ github.run_attempt }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9b09e46671..0eaa6f6335 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,6 +56,12 @@ jobs: fetch-depth: 0 persist-credentials: false + # Redirect the Node compile cache (enabled by pnpm and TypeScript) off + # the root partition's /tmp before the first pnpm call in this lane — + # see .agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md. + - name: Redirect Node compile cache to runner temp + run: echo "NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache" >> "$GITHUB_ENV" + - uses: pnpm/action-setup@v4 with: dest: ${{ runner.temp }}/setup-pnpm-${{ github.run_id }}-${{ github.run_attempt }} @@ -113,6 +119,12 @@ jobs: with: persist-credentials: false + # Redirect the Node compile cache (enabled by pnpm and TypeScript) off + # the root partition's /tmp before the first pnpm call in this lane — + # see .agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md. + - name: Redirect Node compile cache to runner temp + run: echo "NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache" >> "$GITHUB_ENV" + - uses: pnpm/action-setup@v4 with: dest: ${{ runner.temp }}/setup-pnpm-${{ github.run_id }}-${{ github.run_attempt }} @@ -194,6 +206,9 @@ jobs: - name: Install (immutable) run: pnpm install --frozen-lockfile + - name: Install benchmark browser and hosted dependencies + run: pnpm --filter @deepseek-ai/dsh-benchmarks exec playwright install --with-deps chromium + - name: Run performance benchmarks env: DSH_GATE_VERBOSE: '1' @@ -224,6 +239,12 @@ jobs: with: persist-credentials: false + # Redirect the Node compile cache (enabled by pnpm and TypeScript) off + # the root partition's /tmp before the first pnpm call in this lane — + # see .agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md. + - name: Redirect Node compile cache to runner temp + run: echo "NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache" >> "$GITHUB_ENV" + - uses: pnpm/action-setup@v4 with: dest: ${{ runner.temp }}/setup-pnpm-${{ github.run_id }}-${{ github.run_attempt }} diff --git a/apps/web/tests/chat-scroll-contract.e2e.ts b/apps/web/tests/chat-scroll-contract.e2e.ts index 3dae7b93ff..d7ee3ae289 100644 --- a/apps/web/tests/chat-scroll-contract.e2e.ts +++ b/apps/web/tests/chat-scroll-contract.e2e.ts @@ -660,6 +660,7 @@ describe('web e2e: long Chat scroll contract', () => { await liveRow.waitFor({ timeout: 15_000 }) expect(await liveRow.getAttribute('data-state')).toBe('running') await expectBottom(world.page) + expect(await world.page.getByRole('button', { name: 'Back to bottom', exact: true }).count()).toBe(0) await wheelTranscript(world.page, -1_200) await world.page.getByRole('button', { name: 'Back to bottom', exact: true }).waitFor({ timeout: 10_000 }) diff --git a/apps/web/tests/steering.e2e.ts b/apps/web/tests/steering.e2e.ts index f96fbdbe1f..f9581e0a09 100644 --- a/apps/web/tests/steering.e2e.ts +++ b/apps/web/tests/steering.e2e.ts @@ -110,8 +110,8 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => { { timeout: 10_000 }, ).toBe(true) - // Enter remains the Queue gesture. The row action then atomically moves - // this exact occurrence into the current turn's steering outbox. + // Enter remains the Queue gesture. In this live window the row action + // atomically moves this exact occurrence into the current turn's steering outbox. await page.locator('[data-composer-input][contenteditable="true"]').first().waitFor({ timeout: 10_000 }) await input.fill(STEER) await input.press('Enter') @@ -121,8 +121,8 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => { await expect.poll(() => steerButton.isEnabled(), { timeout: 10_000 }).toBe(true) await steerButton.click({ timeout: 10_000 }) const pendingSteering = page.locator('[data-pending-steering]').filter({ hasText: STEER }) - // A timeout while the Queue row remains means strict steer lost to a - // closing window (`steer-unavailable`); inspect replay pacing first. + // A timeout while the Queue row remains means the command observed a + // stopped Agent (`steer-unavailable`); inspect replay pacing first. await pendingSteering.waitFor({ timeout: 10_000 }) // The blocked composer keeps steering pending long enough to observe the diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts index 5cf3efa820..8898c6943b 100644 --- a/apps/web/tests/subagent-interrupt-ui.e2e.ts +++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts @@ -37,6 +37,7 @@ const INITIAL = 'Explain event sourcing in one sentence.' const REARM = 'Keep working until I stop you again.' const REARM_WAKE = 'Start that queued work now.' const FOLLOWUP = 'Now give the same explanation to a human reader.' +const EDITED_FOLLOWUP = 'Explain the same idea for a human reader.' const WAKING = 'And add one concrete example.' const REARMED_ANSWER = 're-armed setup answer' const PARKED_ANSWER = 'parked follow-up answer' @@ -213,22 +214,26 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co const send = page.getByRole('button', { name: 'Send message' }) expect(await send.count()).toBe(1) expect(await send.isDisabled()).toBe(true) + // Keep the continuable Activation resident after this first abort. The + // direct setup queue also proves the ordinary row controls remain + // available while this parent-offline composer cannot submit new input. + await scaffold.ctx.subagents.prompt({ + requestId: 'interrupt-ui-rearm' as SubagentPromptRequestId, + parentSessionId: parent.id, + childSessionId: childId, + mode: 'continuable', + delivery: 'queue', + content: [{ type: 'text', text: REARM }], + }, new AbortController().signal) + await page.getByRole('button', { name: 'Edit queued message' }).waitFor({ timeout: 15_000 }) + expect(await page.getByRole('button', { name: 'Remove queued message' }).count()).toBe(1) + expect(await page.getByRole('button', { name: 'Steer queued message' }).count()).toBe(1) await compareOrRefreshGolden( OFFLINE_COMPOSER_EXPECTED, await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd), MODE, ) - // Keep the continuable Activation resident after this first abort. The - // direct setup queue does not change the parent-offline UI contract: its - // input and Send remain disabled throughout the exercised browser path. - await scaffold.ctx.subagents.prompt({ - requestId: 'interrupt-ui-rearm' as SubagentPromptRequestId, - parentSessionId: parent.id, - childSessionId: childId, - mode: 'continuable', - content: [{ type: 'text', text: REARM }], - }, new AbortController().signal) const aborted = waitForAbortedTurn(scaffold, childId) const interruptResponse = page.waitForResponse(response => new URL(response.url()).pathname === '/api/subagents/interruptByParent') @@ -247,6 +252,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co parentSessionId: parent.id, childSessionId: childId, mode: 'continuable', + delivery: 'queue', content: [{ type: 'text', text: REARM_WAKE }], }, new AbortController().signal) await waitFor(() => existsSync(rearmedReadyFile), 'the re-armed child turn to open') @@ -263,8 +269,13 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co .getByRole('button').first().click() await page.getByRole('button', { name: /1 subagent/ }).click() await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click() - const input = page.getByRole('textbox', { name: 'Message or run a task... / commands, @ files or sessions' }) - await input.waitFor({ timeout: 15_000 }) + // A live continuable child advertises the ordinary steer-all gesture, so + // that placeholder is the composer's accessible name in this window. It + // changes back as the queue drains, so later interactions address the + // stable composer node instead. + await page.getByRole('textbox', { name: 'Cmd/Ctrl+Enter steers all queued messages' }) + .waitFor({ timeout: 15_000 }) + const input = page.locator('[data-composer-input]').first() expect(await input.isDisabled()).toBe(false) // Queue a follow-up through Send while independent Stop remains available. @@ -275,6 +286,19 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result) .toMatchObject({ ok: true }) + await page.getByRole('button', { name: '2 queued messages' }).click() + const followupRow = page.locator('[data-queue-dock] li', { hasText: FOLLOWUP }) + await followupRow.getByRole('button', { name: 'Edit queued message' }).click() + const editor = page.getByRole('textbox', { name: 'Edit queued message' }) + await editor.fill(EDITED_FOLLOWUP) + const updateResponse = page.waitForResponse(response => + new URL(response.url()).pathname === '/api/session/updateQueue') + await page.getByRole('button', { name: 'Save queued message' }).click() + expect(((await (await updateResponse).json()) as { result: { ok: boolean } }).result) + .toMatchObject({ ok: true }) + await page.getByText(EDITED_FOLLOWUP, { exact: true }).waitFor() + expect(apiCalls.filter(path => path === '/api/subagents/updateQueue')).toEqual([]) + const aborted = waitForAbortedTurn(scaffold, childId) const stop = page.getByRole('button', { name: 'Stop generating' }) expect(await stop.count()).toBe(1) @@ -314,7 +338,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co : []) expect(userTexts[0]).toBe(INITIAL) expect(userTexts[1]).toMatch(/^Your parent agent id is .+send_message\(\{ agent_id: /) - expect(userTexts.slice(2)).toEqual([REARM, REARM_WAKE, FOLLOWUP, WAKING]) + expect(userTexts.slice(2)).toEqual([REARM, REARM_WAKE, EDITED_FOLLOWUP, WAKING]) const turnEndKinds = events .filter(event => event.type === 'turn/end') .map(event => event.data.reason.kind) diff --git a/apps/web/tests/subagent-interrupt.e2e.ts b/apps/web/tests/subagent-interrupt.e2e.ts index 0d674dee86..71e25c5918 100644 --- a/apps/web/tests/subagent-interrupt.e2e.ts +++ b/apps/web/tests/subagent-interrupt.e2e.ts @@ -136,6 +136,7 @@ describe.skipIf(MODE === 'record')('web e2e: subagents/interruptByParent over th parentSessionId: parentId, childSessionId: childId, mode: 'continuable', + delivery: 'queue', content: [{ type: 'text', text: FOLLOWUP }], }, }) @@ -170,6 +171,7 @@ describe.skipIf(MODE === 'record')('web e2e: subagents/interruptByParent over th parentSessionId: parentId, childSessionId: childId, mode: 'continuable', + delivery: 'queue', content: [{ type: 'text', text: WAKING }], }, }) diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md index 933d4d25bf..2f40d70afb 100644 --- a/benchmarks/AGENTS.md +++ b/benchmarks/AGENTS.md @@ -5,6 +5,7 @@ This tree owns required, repository-level performance gates whose measured user - Organize benchmarks by measured user path, one directory per path. Do not mirror the package tree. - Host cases use `*.bench.ts`; Client-face cases use `*.bench.client.ts`. Worker, fixture, and support modules do not carry a benchmark suffix. - The private `@deepseek-ai/dsh-benchmarks` workspace owns benchmark-only dependencies. `test:bench` builds workspace libraries and `benchmarks/.dsh-build/` workers before Vitest orchestration. Timed CPU work runs in those workers under plain Node, without a TypeScript loader; runtime package imports must resolve to built `lib/` entries. +- Browser workflow cases drive built Client bundles through the shared shipped-composition Web scaffold. Report its source-resolved test Host separately from published-Host evidence; two animation frames prove a rendering opportunity, not hardware presentation. Use fresh browsers and private scaffold worlds per sample. - Synthesize fixed inputs from reviewed constants. Never use recorded Sessions, user material, ambient repositories, or network services. - Run process-level wall-clock and retained-memory samples in fresh children with private `mkdtemp` roots. Pure synchronous folds create a fresh object graph per sample and must not mutate process-global state. Bound every child, await exit, and remove owned roots after failure as well as success. - Record reference-machine expectations separately from the shared CI time scale and variance headroom. Do not apply the time scale to memory or dimensionless ratios. diff --git a/benchmarks/active-stream-reconnect/README.i18n.yaml b/benchmarks/active-stream-reconnect/README.i18n.yaml new file mode 100644 index 0000000000..107b140b68 --- /dev/null +++ b/benchmarks/active-stream-reconnect/README.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 benchmarks/active-stream-reconnect/README.md +README.md: e75a41eba3952bb4db343c2018e217e6f5e88f96 +README.zh.md: acf0260f53855f9f4e643b2e72c67aa7a8afd6bb diff --git a/benchmarks/active-stream-reconnect/README.md b/benchmarks/active-stream-reconnect/README.md new file mode 100644 index 0000000000..e75a41eba3 --- /dev/null +++ b/benchmarks/active-stream-reconnect/README.md @@ -0,0 +1,7 @@ +# Active Assistant reconnect benchmark + +English | [中文](README.zh.md) + +[reconnect.bench.client.ts](reconnect.bench.client.ts) measures the production Client fold when a reconnect carries an unfinished 100,000-delta reasoning prefix. A compiled private adapter reaches `ClientAssistantStream.replace()` without adding product exports. Three fresh plain-Node workers synthesize the compact baseline before timing; replacement time and retained heap after forced GC have separate median budgets. The next dense live frame must still be accepted. Standard hosted CI uses a 50 ms replacement expectation with the shared 1.25× headroom (63 ms ceiling); the retained-heap budget remains 30 MiB. Recorded-sample and synthetic-regression controls exercise the same time assertion as the worker verdict. + +Build with `pnpm run build:bench`, then select `benchmarks/active-stream-reconnect` in `vitest.bench.config.ts`. This focused Node workload neither builds nor measures browser rendering. [Frontend performance budgets](../../.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md) records calibration and exclusions. diff --git a/benchmarks/active-stream-reconnect/README.zh.md b/benchmarks/active-stream-reconnect/README.zh.md new file mode 100644 index 0000000000..acf0260f53 --- /dev/null +++ b/benchmarks/active-stream-reconnect/README.zh.md @@ -0,0 +1,7 @@ +# 活跃 Assistant 重连基准 + +[English](README.md) | 中文 + +[reconnect.bench.client.ts](reconnect.bench.client.ts) 测量重连携带未完成的 100,000 个 reasoning delta 前缀时，生产 Client 的折叠成本。编译后的私有适配器调用 `ClientAssistantStream.replace()`，不增加产品导出。三个全新纯 Node worker 在计时前合成紧凑 baseline；替换时间与强制 GC 后的保留 heap 分别执行中位数预算检查。下一个稠密序号的实时 frame 仍须被接受。标准托管 CI 使用 50 ms 替换预期及共享的 1.25× 余量（向上取整为 63 ms）；保留 heap 预算仍为 30 MiB。记录样本和合成回归对照使用与 worker 判定相同的时间断言。 + +通过 `pnpm run build:bench` 构建，再在 `vitest.bench.config.ts` 中选择 `benchmarks/active-stream-reconnect`。该聚焦 Node workload 既不构建也不测量浏览器渲染。[前端性能预算](../../.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md)记录校准与排除项。 diff --git a/benchmarks/active-stream-reconnect/reconnect.bench.client.ts b/benchmarks/active-stream-reconnect/reconnect.bench.client.ts new file mode 100644 index 0000000000..3388f9e3b9 --- /dev/null +++ b/benchmarks/active-stream-reconnect/reconnect.bench.client.ts @@ -0,0 +1,48 @@ +/** Required baseline budgets for reconnecting during a large active Assistant stream. */ +import { join } from 'node:path' +import { expect, it } from 'vitest' +import { runBuiltBenchmarkWorker } from '../support/built-worker.ts' +import { ciTimeBudget, PERFORMANCE_BUDGET_HEADROOM } from '../support/calibration.ts' +import type { ReconnectReport } from './reconnect.worker.client.ts' + +const EXPECTED_REPLACE_CI_MS = 50 +const REPLACE_BUDGET_MS = Math.ceil(EXPECTED_REPLACE_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +const REFERENCE_RETAINED_MB = 24 +const SAMPLES = 3 + +function expectReplacementWithinBudget(value: number, budget: number): void { + expect(value).toBeLessThanOrEqual(budget) +} + +it('accepts recorded hosted reconnect samples and rejects replacement regressions', () => { + const recordedMedian = [46.574411, 46.067910, 44.193704].toSorted((a, b) => a - b)[1]! + expect(() => expectReplacementWithinBudget(recordedMedian, ciTimeBudget(16))).toThrow() + expectReplacementWithinBudget(recordedMedian, REPLACE_BUDGET_MS) + expect(REPLACE_BUDGET_MS).toBe(63) + expect(() => expectReplacementWithinBudget(75, REPLACE_BUDGET_MS)).toThrow() + expect(() => expectReplacementWithinBudget(REPLACE_BUDGET_MS + 1, REPLACE_BUDGET_MS)).toThrow() +}) + +it('reconstructs a 100000-delta live prefix within baseline time and retained-memory budgets', async () => { + const samples: ReconnectReport[] = [] + for (let sample = 0; sample < SAMPLES; sample++) { + const run = await runBuiltBenchmarkWorker({ + worker: join(import.meta.dirname, '../.dsh-build/active-stream-reconnect/reconnect.worker.js'), + exposeGc: true, timeoutMs: 30000, + }) + expect(run.timedOut, run.stderr).toBe(false) + expect(run.signal, run.stderr).toBeNull() + expect(run.exitCode, run.stderr).toBe(0) + if (run.report === undefined) throw new Error('reconnect worker omitted report') + expect(run.report.nextFrame).toBe('transient') + expect(run.report.entries).toBeGreaterThan(0) + samples.push(run.report) + } + const replaceMs = samples.map(sample => sample.replaceMs).toSorted((a, b) => a - b)[1]! + const retainedMb = samples.map(sample => sample.retainedMb).toSorted((a, b) => a - b)[1]! + const budgetMs = REPLACE_BUDGET_MS + const budgetMb = REFERENCE_RETAINED_MB * PERFORMANCE_BUDGET_HEADROOM + console.log(JSON.stringify({ benchmark: 'active-stream-reconnect', samples, median: { replaceMs, retainedMb }, expectedCiMs: EXPECTED_REPLACE_CI_MS, referenceMb: REFERENCE_RETAINED_MB, budgetMs, budgetMb })) + expectReplacementWithinBudget(replaceMs, budgetMs) + expect.soft(retainedMb).toBeLessThanOrEqual(budgetMb) +}) diff --git a/benchmarks/active-stream-reconnect/reconnect.worker.client.ts b/benchmarks/active-stream-reconnect/reconnect.worker.client.ts new file mode 100644 index 0000000000..a1a315a263 --- /dev/null +++ b/benchmarks/active-stream-reconnect/reconnect.worker.client.ts @@ -0,0 +1,49 @@ +/** Compiled production Client fold for a reconnect during a long Assistant attempt. */ +import { performance } from 'node:perf_hooks' +import { AssistantStreamAccumulator } from '@deepseek-ai/dsh-llm/assistant-stream' +import { LlmAttemptId } from '@deepseek-ai/dsh-llm/brand' +import type { SessionAssistantStreamBaseline } from '@deepseek-ai/dsh-api-session-controller/types' +// The Client implementation has no plain-Node export; only this adapter is bundled. +import { ClientAssistantStream } from '../../packages/api/session-controller/src/client/sessions/assistant-stream.ts' +import { assertBuiltBenchmarkRuntime } from '../support/built-worker.ts' + +/** Measurements of replace() only; fixture construction and forced GC are excluded. */ +export interface ReconnectReport { + readonly deltas: number + readonly records: number + readonly entries: number + readonly replaceMs: number + readonly retainedMb: number + readonly nextFrame: string | undefined +} + +assertBuiltBenchmarkRuntime(import.meta.url, { + '@deepseek-ai/dsh-llm/assistant-stream': import.meta.resolve('@deepseek-ai/dsh-llm/assistant-stream'), +}) +const deltas = 100000 +const accumulator = new AssistantStreamAccumulator() +accumulator.push({ time: 1700000000000, chunk: { type: 'block-start', index: 0, blockType: 'reasoning' } }) +for (let index = 0; index < deltas; index++) { + accumulator.push({ time: 1700000000001 + index, chunk: { type: 'reasoning-delta', index: 0, text: 'token ' } }) +} +const attemptId = LlmAttemptId('synthetic-reconnect') +const nextIndex = deltas + 1 +const baseline: SessionAssistantStreamBaseline = { + revision: nextIndex + 1, + activeAttempt: { + attemptId, startedAfterSeq: -1, turn: 1, step: 1, nextIndex, + stream: JSON.parse(JSON.stringify(accumulator.snapshot())) as NonNullable['stream'], + }, +} +if (globalThis.gc === undefined) throw new Error('reconnect benchmark requires --expose-gc') +globalThis.gc() +const before = process.memoryUsage().heapUsed +const client = new ClientAssistantStream() +const start = performance.now() +const visible = client.replace([], baseline) +const replaceMs = performance.now() - start +globalThis.gc() +const retainedMb = (process.memoryUsage().heapUsed - before) / 1048576 +const next = client.acceptFrame({ type: 'chunk', attemptId, revision: nextIndex + 2, index: nextIndex, time: 1700000000001 + deltas, chunk: { type: 'reasoning-delta', index: 0, text: 'suffix' } }) +const report: ReconnectReport = { deltas, records: baseline.activeAttempt!.stream.length, entries: visible.length, replaceMs, retainedMb, nextFrame: next?.type } +process.stdout.write(JSON.stringify(report) + '\n') diff --git a/benchmarks/agent-continuation/README.i18n.yaml b/benchmarks/agent-continuation/README.i18n.yaml new file mode 100644 index 0000000000..1db841dc14 --- /dev/null +++ b/benchmarks/agent-continuation/README.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 benchmarks/agent-continuation/README.md +README.md: 5f76b67805a906ea13321ab22eb671d41bfc3190 +README.zh.md: 54d9e1a0e950d14ce5a01568bc9e1cdb61de597a diff --git a/benchmarks/agent-continuation/README.md b/benchmarks/agent-continuation/README.md new file mode 100644 index 0000000000..5f76b67805 --- /dev/null +++ b/benchmarks/agent-continuation/README.md @@ -0,0 +1,31 @@ +# Backend continuation benchmarks + +English | [中文](README.zh.md) + +## Summary + +Measure long-history request processing, cold tool-heavy continuation, and repeated discovery of inactive fork children without network services or recorded user data. The SDK variant drives 100 turns and 800 real file reads through the shipped sdk-minimal profile; other cases isolate backend service costs. No case renders a browser. + +## Table of Contents + +- [Run](#run) +- [Measurements](#measurements) +- [Dev Note](#dev-note) + + + +## Run + +From the repository root, build the libraries and workers with `pnpm run build:bench`, then run `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/agent-continuation/agent-continuation.bench.ts`. Do not overlap timing runs with builds or other benchmarks. + +The test reports all five fresh-process samples and enforces reviewed median budgets. Catalog and tool continuation each use a 900 ms standard hosted CI expectation with 1.25× headroom (1,125 ms); request history uses a 190 ms hosted expectation with the same headroom (238 ms), and SDK continuation uses reference-machine scaling. A failed worker reports its exit, signal, timeout, and stderr; temporary roots are removed even on failure. The required benchmark lane discovers this file automatically. + + + +## Measurements + +[workload.ts](workload.ts) owns synthetic dimensions. [The Agent Note](../../.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md) owns timing endpoints, calibration evidence, memory interpretation, and exclusions. The model adapter does not perform provider serialization or network calls; integrated cases run synthetic tool bodies through the real tool-execution pipeline, while the SDK profile variant performs real file reads. + +## Dev Note + +None. diff --git a/benchmarks/agent-continuation/README.zh.md b/benchmarks/agent-continuation/README.zh.md new file mode 100644 index 0000000000..54d9e1a0e9 --- /dev/null +++ b/benchmarks/agent-continuation/README.zh.md @@ -0,0 +1,31 @@ +# 后端续聊基准 + +[English](README.md) | 中文 + +## Summary + +在不使用网络服务或录制用户数据的情况下，测量长历史请求处理、冷工具密集续聊和重复发现非活动 fork 子会话。SDK 变体通过已发布 sdk-minimal profile 执行 100 个轮次和 800 次真实文件读取；其他用例隔离后端服务成本。所有用例均不渲染浏览器。 + +## Table of Contents + +- [运行](#run) +- [测量](#measurements) +- [Dev Note](#dev-note) + + + +## 运行 + +在仓库根目录使用 `pnpm run build:bench` 构建库和 worker，然后运行 `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/agent-continuation/agent-continuation.bench.ts`。不要让计时运行与构建或其他基准重叠。 + +测试报告全部五个新进程样本，并约束经审查的中位数预算。目录和工具续聊用例均使用标准托管 CI 的 900 ms 期望值与 1.25× 余量（1,125 ms）；请求历史使用 190 ms 托管期望值与相同余量（238 ms），SDK 续聊使用参考机器缩放。worker 失败时报告退出状态、信号、超时和 stderr；失败时也会删除临时根目录。必需基准通道自动发现此文件。 + + + +## 测量 + +[workload.ts](workload.ts)拥有合成维度。[Agent Note](../../.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md)拥有计时终点、校准证据、内存解释和排除项。模型适配器不执行服务商序列化或网络调用；集成用例通过真实工具执行管线运行合成工具体，SDK profile 变体则执行真实文件读取。 + +## Dev Note + +无。 diff --git a/benchmarks/agent-continuation/agent-continuation.bench.ts b/benchmarks/agent-continuation/agent-continuation.bench.ts new file mode 100644 index 0000000000..957c694819 --- /dev/null +++ b/benchmarks/agent-continuation/agent-continuation.bench.ts @@ -0,0 +1,175 @@ +/** Baseline budgets for long-history requests, tool continuation, and fork-child discovery. */ + +import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { runBuiltBenchmarkWorker } from '../support/built-worker.ts' +import { ciTimeBudget, PERFORMANCE_BUDGET_HEADROOM } from '../support/calibration.ts' +import type { ContinuationReport } from './agent-continuation.worker.ts' +import type { CatalogReport } from './child-catalog.worker.ts' +import type { ProfileReport } from './profile-continuation.worker.ts' +import { WORKLOAD } from './workload.ts' + +const ATTEMPTS = 5 +const WORKER_TIMEOUT_MS = 60_000 +/** M4 Pro / Node 24.19 baseline expectations, before shared CI scaling and variance headroom. */ +const EXPECTED_MS = { 'profile-continuation': 1_700 } as const +/** Standard two-CPU hosted CI baseline request-history median is 582.304 ms. */ +const EXPECTED_BASELINE_REQUEST_CI_MS = 600 +const BASELINE_REQUEST_BUDGET_MS = Math.ceil(EXPECTED_BASELINE_REQUEST_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +/** Standard two-CPU hosted CI tool-continuation median is 898.252 ms. */ +const EXPECTED_TOOL_CONTINUATION_CI_MS = 900 +const TOOL_CONTINUATION_BUDGET_MS = Math.ceil(EXPECTED_TOOL_CONTINUATION_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +/** Standard two-CPU hosted CI catalog median is 858.364 ms; 900 ms is the rounded expectation. */ +const EXPECTED_CATALOG_CI_MS = 900 +const CATALOG_BUDGET_MS = Math.ceil(EXPECTED_CATALOG_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +/** Two-CPU ubuntu-24.04 / Node 24.20 samples span 182.161–185.042 ms; rounded CI expectation. */ +const EXPECTED_REQUEST_HISTORY_CI_MS = 190 +const REQUEST_HISTORY_BUDGET_MS = Math.ceil(EXPECTED_REQUEST_HISTORY_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +const EXPECTED_RETAINED_HEAP_MB = 23 +const WORKERS = join(import.meta.dirname, '..', '.dsh-build', 'agent-continuation') + +type Scenario = 'request-history' | 'catalog' | 'tool-continuation' | keyof typeof EXPECTED_MS +type Report = ContinuationReport | CatalogReport | ProfileReport + +function workerName(scenario: Scenario): string { + if (scenario === 'profile-continuation') return 'profile-continuation.worker.js' + return scenario === 'catalog' ? 'child-catalog.worker.js' : 'agent-continuation.worker.js' +} + +async function run(root: string, scenario: Scenario, mode: string): Promise { + const outcome = await runBuiltBenchmarkWorker({ + worker: join(WORKERS, workerName(scenario)), args: [root, mode], + timeoutMs: WORKER_TIMEOUT_MS, exposeGc: true, + }) + if (outcome.timedOut || outcome.signal !== null || outcome.exitCode !== 0 || outcome.report === undefined) { + throw new Error('backend worker failed: ' + JSON.stringify(outcome)) + } + return outcome.report +} + +function median(values: readonly number[]): number { + return [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)] as number +} + +function expectTotalWithinBudget(value: number, budget: number): void { + expect(value).toBeLessThanOrEqual(budget) +} + +describe('standard hosted catalog calibration', () => { + it('accepts the recorded two-CPU samples that exceed the historical budget', () => { + const recordedMedian = median([797.373945, 883.157358, 858.363927, 790.568538, 904.5785669999999]) + + expect(recordedMedian).toBe(858.363927) + expect(() => expectTotalWithinBudget(recordedMedian, 800)).toThrow() + expectTotalWithinBudget(recordedMedian, CATALOG_BUDGET_MS) + expect(CATALOG_BUDGET_MS).toBe(1_125) + }) + + it('rejects a synthetic material catalog regression', () => { + const regressionMedian = median([1_380, 1_400, 1_420, 1_410, 1_390]) + + expect(regressionMedian).toBe(1_400) + expect(() => expectTotalWithinBudget(regressionMedian, CATALOG_BUDGET_MS)).toThrow() + }) +}) + +describe('standard hosted tool-continuation calibration', () => { + it('accepts recorded two-CPU samples but rejects a material regression', () => { + const recordedMedian = median([917.006744, 892.091482, 887.838867, 905.6594390000001, 898.2517579999999]) + + expect(recordedMedian).toBe(898.2517579999999) + expect(() => expectTotalWithinBudget(recordedMedian, 850)).toThrow() + expectTotalWithinBudget(recordedMedian, TOOL_CONTINUATION_BUDGET_MS) + expect(TOOL_CONTINUATION_BUDGET_MS).toBe(1_125) + expect(() => expectTotalWithinBudget(1_400, TOOL_CONTINUATION_BUDGET_MS)).toThrow() + }) +}) + +describe('standard hosted baseline request-history calibration', () => { + it('accepts recorded two-CPU samples but rejects a material regression', () => { + const recordedMedian = median([618.598065, 618.606407, 582.0351149999999, 582.303506, 581.8318300000001]) + + expect(recordedMedian).toBe(582.303506) + expect(() => expectTotalWithinBudget(recordedMedian, 550)).toThrow() + expectTotalWithinBudget(recordedMedian, BASELINE_REQUEST_BUDGET_MS) + expect(BASELINE_REQUEST_BUDGET_MS).toBe(750) + expect(() => expectTotalWithinBudget(900, BASELINE_REQUEST_BUDGET_MS)).toThrow() + }) +}) + +function assertRequestHistoryBudget(value: number): void { + expect(value).toBeLessThanOrEqual(REQUEST_HISTORY_BUDGET_MS) +} + +describe('standard hosted request-history calibration', () => { + it('accepts the recorded two-CPU samples above the historical budget', () => { + const recorded = [183.355397, 184.468253, 185.042397, 182.160790, 182.924728] + const recordedMedian = median(recorded) + + expect(recordedMedian).toBe(183.355397) + expect(recordedMedian).toBeGreaterThan(ciTimeBudget(70)) + assertRequestHistoryBudget(recordedMedian) + assertRequestHistoryBudget(Math.max(...recorded)) + expect(REQUEST_HISTORY_BUDGET_MS).toBe(238) + }) + + it('rejects a synthetic material request-history regression', () => { + const regressionMedian = median([248, 250, 252, 251, 249]) + expect(() => assertRequestHistoryBudget(regressionMedian)).toThrow() + }) + + it('rejects the recorded original implementation on the M4 reference', () => { + const originalMedian = median([249.050708, 238.275291, 242.172084, 250.093166, 246.130875]) + expect(originalMedian).toBe(246.130875) + expect(() => assertRequestHistoryBudget(originalMedian)).toThrow() + }) +}) + +describe('continuing tool-heavy Sessions with large histories', () => { + let scratch: string | undefined + const sources = new Map() + + beforeAll(async () => { + scratch = await mkdtemp(join(tmpdir(), 'dsh-agent-continuation-bench-')) + for (const scenario of ['request-history', 'catalog'] as const) { + const root = join(scratch, 'source-' + scenario) + await run(root, scenario, 'seed') + sources.set(scenario, root) + } + sources.set('tool-continuation', sources.get('request-history') as string) + }) + afterAll(async () => { + if (scratch !== undefined) await rm(scratch, { recursive: true, force: true }) + }) + + for (const scenario of ['request-history', 'tool-continuation', 'catalog', 'profile-continuation'] as const) { + it(scenario, async () => { + const samples: Report[] = [] + for (let attempt = 0; attempt < ATTEMPTS; attempt++) { + const root = join(scratch as string, scenario + '-' + String(attempt)) + if (scenario === 'profile-continuation') await mkdir(root) + else await cp(sources.get(scenario) as string, root, { recursive: true }) + try { samples.push(await run(root, scenario, scenario)) } + finally { await rm(root, { recursive: true, force: true }) } + } + const totalMs = samples.map(sample => sample.totalMs) + const budgetMs = scenario === 'request-history' ? REQUEST_HISTORY_BUDGET_MS + : scenario === 'catalog' ? CATALOG_BUDGET_MS + : scenario === 'tool-continuation' ? TOOL_CONTINUATION_BUDGET_MS : ciTimeBudget(EXPECTED_MS[scenario]) + const retainedHeapBudgetMb = EXPECTED_RETAINED_HEAP_MB * PERFORMANCE_BUDGET_HEADROOM + console.log(JSON.stringify({ + benchmark: 'agent-continuation/' + scenario, workload: WORKLOAD, + samples, totalMs: { min: Math.min(...totalMs), median: median(totalMs), max: Math.max(...totalMs) }, + budgetMs, ...(scenario === 'tool-continuation' ? { retainedHeapBudgetMb } : {}), + })) + if (scenario === 'request-history') assertRequestHistoryBudget(median(totalMs)) + else expectTotalWithinBudget(median(totalMs), budgetMs) + if (scenario === 'tool-continuation') { + expect(median((samples as ContinuationReport[]).map(sample => sample.retainedHeapMb))) + .toBeLessThanOrEqual(retainedHeapBudgetMb) + } + }) + } +}) diff --git a/benchmarks/agent-continuation/agent-continuation.worker.ts b/benchmarks/agent-continuation/agent-continuation.worker.ts new file mode 100644 index 0000000000..7e676e9971 --- /dev/null +++ b/benchmarks/agent-continuation/agent-continuation.worker.ts @@ -0,0 +1,144 @@ +/** Plain-Node measurements of active request history and cold tool-heavy continuation. */ + +import { performance } from 'node:perf_hooks' +import { scheduler } from 'node:timers/promises' +import { Context } from '@deepseek-ai/cordis' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent' +import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' +import { createUserMessage, LlmAdapter } from '@deepseek-ai/dsh-llm' +import type { GenerateOptions, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm' +import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session' +import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl' +import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' +import { defineContentToolFixture } from '@deepseek-ai/dsh-tools' +import { assertBuiltBenchmarkRuntime } from '../support/built-worker.ts' +import { PARENT_ID, response, resultText, syntheticHistory, TIME_ZERO, WORKLOAD } from './workload.ts' + +/** Raw timing and retained-memory report from one isolated backend process. */ +export interface ContinuationReport { + readonly totalMs: number + readonly resumeMs: number + readonly turnsMs: number + readonly flushMs: number + readonly cpuUserMs: number + readonly cpuSystemMs: number + readonly retainedHeapMb: number + readonly peakRssMb: number + readonly requests: number + readonly toolCalls: number + readonly events: number +} + +class SyntheticAdapter extends LlmAdapter { + requests = 0 + constructor(private readonly toolsPerTurn: number) { super() } + + override resolveModel(provider: string, model: string): Promise { + return Promise.resolve({ provider, id: model, name: model }) + } + + async * stream(_options: GenerateOptions): AsyncIterable { + const tools = this.toolsPerTurn > 0 && this.requests % 2 === 0 ? this.toolsPerTurn : 0 + const reply = response(100_000 + this.requests++, tools) + yield* reply.chunks + } +} + +async function collectHeap(): Promise { + if (globalThis.gc === undefined) throw new Error('backend benchmark requires --expose-gc') + globalThis.gc() + await scheduler.yield() + globalThis.gc() + return process.memoryUsage().heapUsed / 1_048_576 +} + +async function seed(root: string): Promise { + const ctx = new Context() + try { + await mountAgentLoopTestDependencies(ctx) + await ctx.plugin(JsonlSessionPersistence, { root, compression: 'zstd' }) + const handle = await ctx.sessionPersistence.create({ + version: SESSION_FORMAT_VERSION, id: PARENT_ID, createdAt: TIME_ZERO, cwd: '/bench', isSeeded: false, + }, {}) + try { + await handle.append(syntheticHistory(WORKLOAD.historyTurns)) + await handle.flush() + } finally { await handle.close() } + } finally { await ctx.fiber.dispose() } +} + +async function runTurns(agent: Agent, turns: number): Promise { + for (let turn = 0; turn < turns; turn++) { + agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Continue synthetic task ' + String(turn) }], source: { kind: 'user' } })) + await agent.whenIdle() + } +} + +async function measure(root: string, scenario: string): Promise { + const ctx = new Context() + let handle: AgentHandle | undefined + const toolHeavy = scenario === 'tool-continuation' + const adapter = new SyntheticAdapter(toolHeavy ? WORKLOAD.toolsPerLiveTurn : 0) + let toolCalls = 0 + try { + await ctx.plugin(SessionProjectionRegistry) + await mountAgentLoopTestDependencies(ctx) + await ctx.plugin(JsonlSessionPersistence, { root, compression: 'zstd' }) + await ctx.plugin(AgentLoop, { agents: [] }) + ctx.effect(() => ctx.llm.registerAdapter(['bench'], adapter)) + ctx.effect(() => ctx.tools.register(defineContentToolFixture({ + name: 'bench_tool', description: 'Read a bounded synthetic module.', + parameters: { ordinal: { type: 'number', required: true } }, + isConcurrencySafe: () => true, + execute(args) { + toolCalls++ + return Promise.resolve([{ type: 'text', text: resultText(args.ordinal) }]) + }, + }))) + if (!toolHeavy) { + handle = await ctx.agents.resume({ resumeSessionId: PARENT_ID, agentOptions: { provider: 'bench', model: 'bench' } }) + } + const beforeHeap = await collectHeap() + const cpuStart = process.cpuUsage() + const start = performance.now() + if (handle === undefined) { + handle = await ctx.agents.resume({ resumeSessionId: PARENT_ID, agentOptions: { provider: 'bench', model: 'bench' } }) + } + const resumed = performance.now() + await runTurns(handle.agent, toolHeavy ? WORKLOAD.continuationTurns : WORKLOAD.requestTurns) + const turnsDone = performance.now() + await ctx.sessions.flush(handle.agent.session) + const end = performance.now() + const cpu = process.cpuUsage(cpuStart) + const retainedHeapMb = (await collectHeap()) - beforeHeap + if (adapter.requests !== (toolHeavy ? WORKLOAD.continuationTurns * 2 : WORKLOAD.requestTurns) + || toolCalls !== (toolHeavy ? WORKLOAD.continuationTurns * WORKLOAD.toolsPerLiveTurn : 0)) { + throw new Error('backend benchmark did not complete every requested model/tool step') + } + return { + totalMs: end - start, resumeMs: resumed - start, turnsMs: turnsDone - resumed, flushMs: end - turnsDone, + cpuUserMs: cpu.user / 1_000, cpuSystemMs: cpu.system / 1_000, + retainedHeapMb, peakRssMb: process.resourceUsage().maxRSS / 1_024, + requests: adapter.requests, toolCalls, events: handle.agent.session.seq, + } + } finally { + await handle?.dispose() + await ctx.fiber.dispose() + } +} + +assertBuiltBenchmarkRuntime(import.meta.url, Object.fromEntries([ + '@deepseek-ai/dsh-agent-loop', '@deepseek-ai/dsh-session', '@deepseek-ai/dsh-llm', + '@deepseek-ai/dsh-tools', '@deepseek-ai/dsh-session-persistence-jsonl', +].map(name => [name, import.meta.resolve(name)]))) +const [root, scenario] = process.argv.slice(2) +if (root === undefined || scenario === undefined || !['seed', 'request-history', 'tool-continuation'].includes(scenario)) { + throw new Error('usage: agent-continuation.worker.js ') +} +if (scenario === 'seed') { + await seed(root) + process.stdout.write(JSON.stringify({ seeded: true }) + '\n') +} else { + process.stdout.write(JSON.stringify(await measure(root, scenario)) + '\n') +} diff --git a/benchmarks/agent-continuation/child-catalog.worker.ts b/benchmarks/agent-continuation/child-catalog.worker.ts new file mode 100644 index 0000000000..e12cb97d2f --- /dev/null +++ b/benchmarks/agent-continuation/child-catalog.worker.ts @@ -0,0 +1,95 @@ +/** Cold catalog observations of persisted fork children with tool-heavy inherited histories. */ + +import { performance } from 'node:perf_hooks' +import { Context } from '@deepseek-ai/cordis' +import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl' +import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' +import SessionQueryEngine from '@deepseek-ai/dsh-session-query' +import SubagentRuntime, { SUBAGENT_DESCRIPTOR_VERSION } from '@deepseek-ai/dsh-subagent' +import { assertBuiltBenchmarkRuntime } from '../support/built-worker.ts' +import { PARENT_ID, syntheticHistory, TIME_ZERO, WORKLOAD } from './workload.ts' + +/** Two complete catalog reads in one fresh Host, with every child observation released. */ +export interface CatalogReport { + readonly totalMs: number + readonly firstMs: number + readonly repeatMs: number + readonly cpuUserMs: number + readonly cpuSystemMs: number + readonly children: number + readonly peakRssMb: number +} + +class CatalogQuery extends SessionQueryEngine { + override searchSessions(): Promise { + return Promise.reject(new Error('search is outside the child-catalog benchmark')) + } + override searchEvents(): Promise { + return Promise.reject(new Error('search is outside the child-catalog benchmark')) + } +} + +async function seed(ctx: Context): Promise { + const inherited = syntheticHistory(WORKLOAD.childHistoryTurns) + for (let child = 0; child < WORKLOAD.children; child++) { + const id = SessionId('bench-child-' + String(child)) + const events: SessionEvent[] = [ + ...inherited, + { type: 'session/end-seed', seq: SessionSeq(inherited.length), time: TIME_ZERO + inherited.length, data: { inherited: true } }, + { type: 'subagent/descriptor', seq: SessionSeq(inherited.length + 1), time: TIME_ZERO + inherited.length + 1, data: { + version: SUBAGENT_DESCRIPTOR_VERSION, mode: 'continuable', provider: 'fork', label: 'Synthetic child ' + String(child), + } }, + ] + const handle = await ctx.sessionPersistence.create({ + version: SESSION_FORMAT_VERSION, id, createdAt: TIME_ZERO + child, cwd: '/bench', + parentSession: PARENT_ID, isSeeded: true, origin: 'subagent', delegationDepth: 1, + }, { inheritedEventCount: SessionLogOffset(inherited.length) }) + try { + await handle.append(events) + await handle.flush() + } finally { await handle.close() } + } +} + +async function run(root: string, mode: string): Promise { + const ctx = new Context() + try { + await ctx.plugin(SessionStore) + await ctx.plugin(SessionProjectionRegistry) + await ctx.plugin(JsonlSessionPersistence, { root, compression: 'zstd' }) + await ctx.plugin(CatalogQuery) + await ctx.plugin(SubagentRuntime) + if (mode === 'seed') { + await seed(ctx) + return { seeded: true } + } + const cpuStart = process.cpuUsage() + const start = performance.now() + const first = await ctx.subagents.listChildren(PARENT_ID) + const firstDone = performance.now() + const repeated = await ctx.subagents.listChildren(PARENT_ID) + const end = performance.now() + const cpu = process.cpuUsage(cpuStart) + if (first.length !== WORKLOAD.children || repeated.length !== WORKLOAD.children + || [...first, ...repeated].some(row => row.kind !== 'child')) { + throw new Error('child-catalog benchmark did not reach the complete healthy catalog') + } + return { + totalMs: end - start, firstMs: firstDone - start, repeatMs: end - firstDone, + cpuUserMs: cpu.user / 1_000, cpuSystemMs: cpu.system / 1_000, + children: first.length, peakRssMb: process.resourceUsage().maxRSS / 1_024, + } + } finally { await ctx.fiber.dispose() } +} + +assertBuiltBenchmarkRuntime(import.meta.url, Object.fromEntries([ + '@deepseek-ai/dsh-subagent', '@deepseek-ai/dsh-session-query', + '@deepseek-ai/dsh-session-persistence-jsonl', +].map(name => [name, import.meta.resolve(name)]))) +const [root, mode] = process.argv.slice(2) +if (root === undefined || (mode !== 'seed' && mode !== 'catalog')) { + throw new Error('usage: child-catalog.worker.js ') +} +process.stdout.write(JSON.stringify(await run(root, mode)) + '\n') diff --git a/benchmarks/agent-continuation/profile-adapter.ts b/benchmarks/agent-continuation/profile-adapter.ts new file mode 100644 index 0000000000..8c42c27fb9 --- /dev/null +++ b/benchmarks/agent-continuation/profile-adapter.ts @@ -0,0 +1,42 @@ +/** Compiled synthetic model for the shipped sdk-minimal profile; tools remain production plugins. */ + +import type { Context } from '@deepseek-ai/cordis' +import { LlmAdapter, ToolCallId } from '@deepseek-ai/dsh-llm' +import type { GenerateOptions, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm' +import { response, WORKLOAD } from './workload.ts' + +class ProfileAdapter extends LlmAdapter { + private requests = 0 + override resolveModel(provider: string, model: string): Promise { + return Promise.resolve({ provider, id: model, name: model, contextWindow: 1_000_000 }) + } + + async * stream(_options: GenerateOptions): AsyncIterable { + const serial = this.requests++ + if (serial % 2 === 1) { + yield* response(200_000 + serial, 0).chunks + return + } + for (let index = 0; index < WORKLOAD.toolsPerLiveTurn; index++) { + const id = ToolCallId('profile-call-' + String(serial) + '-' + String(index)) + const args = JSON.stringify({ command: 'view', path: process.cwd() + '/synthetic.txt' }) + yield { type: 'block-start', index, blockType: 'tool-call' } + yield { type: 'tool-call-delta', index, id, name: 'str_replace_editor', argumentsDelta: args } + yield { type: 'block-end', index, block: { type: 'tool-call', id, name: 'str_replace_editor', arguments: args } } + } + yield { type: 'finish', reason: { kind: 'tool-calls' } } + } +} + +/** Loader plugin identity. */ +export const name = 'backend-profile-benchmark-model' +/** The scripted provider requires the production LLM registry. */ +export const inject = ['llm'] + +/** + * Register the synthetic provider without changing any runtime services or tools. + * @param ctx - profile-owned plugin context. + */ +export function apply(ctx: Context): void { + ctx.effect(() => ctx.llm.registerAdapter(['bench'], new ProfileAdapter())) +} diff --git a/benchmarks/agent-continuation/profile-continuation.worker.ts b/benchmarks/agent-continuation/profile-continuation.worker.ts new file mode 100644 index 0000000000..4e0fade29b --- /dev/null +++ b/benchmarks/agent-continuation/profile-continuation.worker.ts @@ -0,0 +1,85 @@ +/** End-to-end SDK continuation through the built dsh sdk-minimal profile and real file tools. */ + +import { mkdir, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { performance } from 'node:perf_hooks' +import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client' +import { assertBuiltBenchmarkRuntime } from '../support/built-worker.ts' +import { PARENT_ID, resultText, WORKLOAD } from './workload.ts' + +/** Parent-observed wall time, including profile launch and SDK shutdown. */ +export interface ProfileReport { + readonly totalMs: number + readonly bootMs: number + readonly turnsMs: number + readonly closeMs: number + readonly requests: number + readonly toolCalls: number +} + +async function run(root: string): Promise { + const home = join(root, 'home') + const cwd = join(root, 'workspace') + await mkdir(cwd, { recursive: true }) + await mkdir(home, { recursive: true }) + await writeFile(join(cwd, 'synthetic.txt'), resultText(0)) + const patch = join(root, 'profile.patch.yml') + await writeFile(patch, [ + '- id: llm-deepseek', ' disabled: true', + '- id: sessions', ' config:', ' root: ' + JSON.stringify(join(root, 'profile-sessions')), ' compression: zstd', + '- insert:', ' - id: benchmark-model', ' name: ' + JSON.stringify(join(import.meta.dirname, 'profile-adapter.js')), + '', + ].join('\n')) + const env: NodeJS.ProcessEnv = { + PATH: process.env.PATH, HOME: home, USERPROFILE: home, + DSH_AGENTS_HOME: join(home, 'agents'), + } + const harness = new DeepSeekHarness({ + dshBin: join(import.meta.dirname, '..', '..', '..', 'apps', 'cli', 'lib', 'bin.js'), + profile: 'sdk-minimal', dshHome: home, processCwd: cwd, cwd, + provider: 'bench', model: 'bench', patches: [patch], env, + initializeTimeoutMs: 15_000, requestTimeoutMs: 15_000, + }) + let closing: Promise | undefined + const close = (): Promise => closing ??= harness.close() + let expired = false + const deadline = setTimeout(() => { + expired = true + // The awaited finally close below reports shutdown failures; this only requests cancellation. + void close().catch(() => undefined) + }, 40_000) + let requests = 0 + let toolCalls = 0 + const start = performance.now() + try { + await harness.start() + const booted = performance.now() + for (let turn = 0; turn < WORKLOAD.profileTurns; turn++) { + const result = await harness.run('Read the synthetic file ' + String(turn), { sessionId: PARENT_ID }) + requests += result.events.filter(event => event.type === 'assistant/message').length + for (const event of result.events) { + if (event.type !== 'tool/result') continue + const result = event.data.message.content[0] + if (result.isError || !result.content.some(block => block.type === 'text' && block.text.includes('export const synthetic = 42;'))) { + throw new Error('profile benchmark did not read the synthetic file') + } + toolCalls++ + } + } + const turnsDone = performance.now() + await close() + const end = performance.now() + if (expired || requests !== WORKLOAD.profileTurns * 2 || toolCalls !== WORKLOAD.profileTurns * WORKLOAD.toolsPerLiveTurn) { + throw new Error('profile benchmark did not finish every model request and real tool call') + } + return { totalMs: end - start, bootMs: booted - start, turnsMs: turnsDone - booted, closeMs: end - turnsDone, requests, toolCalls } + } finally { + clearTimeout(deadline) + await close() + } +} + +assertBuiltBenchmarkRuntime(import.meta.url, { '@deepseek-ai/dsh-sdk-client': import.meta.resolve('@deepseek-ai/dsh-sdk-client') }) +const [root] = process.argv.slice(2) +if (root === undefined) throw new Error('usage: profile-continuation.worker.js ') +process.stdout.write(JSON.stringify(await run(root)) + '\n') diff --git a/benchmarks/agent-continuation/workload.ts b/benchmarks/agent-continuation/workload.ts new file mode 100644 index 0000000000..6785585574 --- /dev/null +++ b/benchmarks/agent-continuation/workload.ts @@ -0,0 +1,110 @@ +/** Reviewed synthetic tool history shared by continuation and child-catalog measurements. */ + +import { AssistantStreamAccumulator } from '@deepseek-ai/dsh-llm/assistant-stream' +import { MessageId, ToolCallId } from '@deepseek-ai/dsh-llm' +import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' + +/** Workload dimensions, independent of environment and recorded user material. */ +export const WORKLOAD = { + historyTurns: 800, + toolsPerHistoricalTurn: 4, + toolResultChars: 2_048, + requestTurns: 40, + continuationTurns: 20, + profileTurns: 100, + toolsPerLiveTurn: 8, + children: 16, + childHistoryTurns: 80, +} as const + +/** Fixed clock used only to author persisted synthetic input. */ +export const TIME_ZERO = 1_700_000_000_000 +/** Durable parent identity of the measured continuation. */ +export const PARENT_ID = SessionId('bench-parent') + +/** + * Construct a deterministic model reply without retaining past requests. + * @param serial - unique response ordinal. + * @param tools - number of synthetic tool calls, or zero for a final text reply. + * @returns streamed chunks and their known final blocks. + */ +export function response(serial: number, tools: number): { chunks: StreamChunk[]; content: ContentBlock[] } { + const content: ContentBlock[] = [ + { type: 'reasoning', text: 'Inspect the synthetic result. '.repeat(8) }, + { type: 'text', text: 'Synthetic response. '.repeat(8) }, + ...Array.from({ length: tools }, (_, index): ContentBlock => ({ + type: 'tool-call', id: ToolCallId('call-' + String(serial) + '-' + String(index)), name: 'bench_tool', + arguments: JSON.stringify({ ordinal: serial * 100 + index }), + })), + ] + const chunks: StreamChunk[] = [] + content.forEach((block, index) => { + chunks.push({ type: 'block-start', index, blockType: block.type }) + if (block.type === 'text' || block.type === 'reasoning') { + for (let offset = 0; offset < block.text.length; offset += 16) { + chunks.push({ type: block.type === 'text' ? 'text-delta' : 'reasoning-delta', index, text: block.text.slice(offset, offset + 16) }) + } + } else if (block.type === 'tool-call') { + for (let offset = 0; offset < block.arguments.length; offset += 8) { + chunks.push({ type: 'tool-call-delta', index, id: block.id, name: block.name, argumentsDelta: block.arguments.slice(offset, offset + 8) }) + } + } + chunks.push({ type: 'block-end', index, block }) + }) + chunks.push({ type: 'usage', usage: { inputTokens: 10_000, outputTokens: 100 } }) + chunks.push({ type: 'finish', reason: { kind: tools === 0 ? 'stop' : 'tool-calls' } }) + return { chunks, content } +} + +/** + * Author completed two-step turns through production Session append and stream compaction. + * @param turns - completed historical turns. + * @returns detached current-generation events with fixed ids, timestamps and payloads. + */ +export function syntheticHistory(turns: number): SessionEvent[] { + const session = Session.create(PARENT_ID) + for (let turn = 1; turn <= turns; turn++) { + session.append('turn/start', { turn }) + session.append('step/start', { turn, step: 1 }) + session.append('user/message', { + id: MessageId('prompt-' + String(turn)), role: 'user', + content: [{ type: 'text', text: 'Inspect synthetic module ' + String(turn) }], source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + for (const step of [1, 2]) { + if (step === 2) session.append('step/start', { turn, step }) + const reply = response(turn * 2 + step, step === 1 ? WORKLOAD.toolsPerHistoricalTurn : 0) + const stream = new AssistantStreamAccumulator() + reply.chunks.forEach((chunk, index) => { stream.push({ time: TIME_ZERO + turn * 1_000 + step * 100 + index, chunk }) }) + session.append('assistant/message', { + turn, step, + message: { id: MessageId('reply-' + String(turn) + '-' + String(step)), role: 'assistant', content: reply.content, source: { kind: 'model', provider: 'bench', model: 'bench' } }, + stream: [...stream.snapshot()], + }, { surfaceOp: 'append' }) + for (const block of reply.content) { + if (block.type !== 'tool-call') continue + const call = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments }) + session.append('tool/result', { + turn, step, + message: { + id: MessageId('result-' + block.id), role: 'user', source: { kind: 'tool', callId: block.id }, + content: [{ type: 'tool-result', toolCallId: block.id, content: [{ type: 'text', text: resultText(turn) }], isError: false }], + }, + }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] }) + } + session.append('step/end', { turn, step }) + } + session.append('turn/end', { turn, reason: { kind: 'completed' } }) + } + return session.snapshotEvents().map(event => ({ ...event, time: TIME_ZERO + event.seq })) +} + +/** + * Build a bounded synthetic file-read result with a varying prefix. + * @param ordinal - deterministic result identifier. + * @returns exactly the reviewed number of UTF-16 characters. + */ +export function resultText(ordinal: number): string { + return ('module ' + String(ordinal) + '\n' + 'export const synthetic = 42;\n'.repeat(100)).slice(0, WORKLOAD.toolResultChars) +} diff --git a/benchmarks/long-session-browser/README.i18n.yaml b/benchmarks/long-session-browser/README.i18n.yaml new file mode 100644 index 0000000000..dfb24532ca --- /dev/null +++ b/benchmarks/long-session-browser/README.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 benchmarks/long-session-browser/README.md +README.md: 6b6777687947bee42337568ad3748e37a563be87 +README.zh.md: 139bd237d45275ea165a3e90f055f8ce507c5c53 diff --git a/benchmarks/long-session-browser/README.md b/benchmarks/long-session-browser/README.md new file mode 100644 index 0000000000..6b67776879 --- /dev/null +++ b/benchmarks/long-session-browser/README.md @@ -0,0 +1,17 @@ +# Long-session browser benchmark + +English | [中文](README.zh.md) + +This reference describes the required Chromium workflow in [long-session.bench.ts](long-session.bench.ts). It opens a synthetic 240-turn Session, loads every older page, visits Trajectory, returns to Chat, and submits a paced reply while typing another draft. The shipped Web scaffold owns the isolated home, persistence, replay adapter, and loopback listener; Chromium loads the built Web artifacts, not a replacement development server. + +## Run + +`pnpm run test:bench` builds libraries, workers, and Web artifacts before running the serial benchmark inventory. With artifacts already built, select this directory through `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/long-session-browser`. Install Chromium through the benchmark workspace before the first run. + +## Measurements + +Three fresh browser processes and scaffold worlds produce raw samples and median verdicts. Open and paging end after the expected transcript state and two animation frames; this includes a rendering opportunity, not a hardware presentation timestamp. Paging reports every page and gates the median of each sample’s slowest page. Stream reports first visible reply, trusted draft typing, complete reply wall time, and Chromium main-thread task duration. Send lookup is scoped to the composer seat; reply-marker lookups and the input-event text witness read only the latest Assistant step, avoiding repeated whole-history text and accessibility scans. The input witness is installed before Send, and draft typing starts as soon as the first marker is visible, without an extra pre-input animation-frame wait. The actual first input event must observe an unfinished reply; completion waits for the new rendered turn-tail after Host settlement. After measurement, a trusted keystroke after DONE must fail the same overlap assertion. Open, the slowest older page, and first Trajectory use standard-hosted expectations of 900/700/500 ms. Shared 1.25× headroom gives limits of 1125/875/625 ms respectively; stream endpoint overhead budgets are unchanged. Heap after forced GC and DOM counts are diagnostics, not leak budgets. + +The fixture contains mixed-language prompts, prose, reasoning, 20 code fences, and 40 synthetic tool results. Every historical Assistant includes a compact stream built by the production accumulator from matching reasoning, text, tool arguments, usage, and finish chunks. No model, tool, external network, recorded Session, or private Harness home supplies its content. Streaming uses 120 text deltas at 16 ms replay pacing through the real composer, agent loop, transport, and persistence. + +The [decision record](../../.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md) owns calibration, exclusions, and alternatives. The larger [manual diagnostic](../../apps/web/tests/complex-history.perf.ts) remains separate. diff --git a/benchmarks/long-session-browser/README.zh.md b/benchmarks/long-session-browser/README.zh.md new file mode 100644 index 0000000000..139bd237d4 --- /dev/null +++ b/benchmarks/long-session-browser/README.zh.md @@ -0,0 +1,17 @@ +# 长 Session 浏览器基准 + +[English](README.md) | 中文 + +本文说明 [long-session.bench.ts](long-session.bench.ts) 中必需的 Chromium 工作流。它打开一个合成的 240 轮 Session，加载所有更早的分页，访问 Trajectory，返回 Chat，并在流式回复期间输入下一条草稿。随产品维护的 Web scaffold 拥有隔离的主目录、持久化、重放适配器和回环监听器；Chromium 加载构建后的 Web 产物，而非替代开发服务器。 + +## 运行 + +`pnpm run test:bench` 先构建 library、worker 和 Web 产物，再串行运行基准清单。产物已构建时，通过 `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/long-session-browser` 选择此目录。首次运行前，通过 benchmark workspace 安装 Chromium。 + +## 测量 + +三个全新浏览器进程与 scaffold 环境产生原始样本及中位数判定。打开和分页在预期对话状态出现且经过两次动画帧后结束；这包含一次渲染机会，而非硬件显示时间戳。分页报告每一页，并对各样本最慢分页时间的中位数执行预算检查。流式报告首段可见回复、真实草稿键入、完整回复壁钟时间和 Chromium 主线程任务时间。发送控件查找限定在 composer seat；回复标记查找与输入事件文本证据仅读取最新 Assistant step，避免重复扫描全部历史文本与无障碍属性。输入观察器在发送前安装，首个标记可见后立即开始草稿键入，不额外等待输入前动画帧。实际首个输入事件必须观察到未完成的回复；完成测量在 Host 结算后等待新 turn-tail 渲染。测量后，在 DONE 之后发送的真实按键必须无法通过同一个重叠断言。打开、最慢更早分页和首次 Trajectory 使用标准托管预期 900/700/500 ms。共享的 1.25× 余量分别产生 1125/875/625 ms 上限；流式终点的额外开销预算不变。强制 GC 后的 heap 与 DOM 数量仅供诊断，不作为泄漏预算。 + +fixture（测试前置数据）包含混合语言提示、正文、推理、20 个代码块和 40 个合成工具结果。每条历史 Assistant 都含紧凑 stream，由生产 accumulator 从匹配的推理、文本、工具参数、usage 和 finish chunk 构建。其内容不来自模型、工具、外部网络、录制 Session 或私有 Harness 主目录。流式回复以 16 ms 重放间隔发送 120 个文本 delta，经过真实输入框、agent loop（智能体循环）、传输与持久化。 + +[决策记录](../../.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md)拥有校准、排除项与替代方案。更大规模的[手动诊断](../../apps/web/tests/complex-history.perf.ts)保持独立。 diff --git a/benchmarks/long-session-browser/long-session.bench.ts b/benchmarks/long-session-browser/long-session.bench.ts new file mode 100644 index 0000000000..789ebeea9a --- /dev/null +++ b/benchmarks/long-session-browser/long-session.bench.ts @@ -0,0 +1,209 @@ +/** Required browser budgets for opening, paging and continuing synthetic long history. */ +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { performance } from 'node:perf_hooks' +import { chromium, type Page, type CDPSession, type Locator } from 'playwright' +import { expect, it } from 'vitest' +import { launchWebScaffold, seedSession, watchConsole, webSnapshotMode } from '../../apps/web/tests/scaffold.ts' +import { newEnglishPage } from '../../apps/web/tests/support.ts' +import { ciTimeBudget, PERFORMANCE_BUDGET_HEADROOM } from '../support/calibration.ts' +import { HISTORY_TURNS, SESSION_ID, FIRST, DONE, DELTAS, PACE_MS, syntheticHistory, syntheticReply } from './synthetic-history.ts' + +const SAMPLES = 3 +const TAIL = '[data-chat-flow-key^="9:turn-tail"]' +const REFERENCE = { open: 200, page: 260, trajectory: 160, first: 1100, streamTask: 1800, input: 500, streamWall: 1000 } +const EXPECTED_OPEN_CI_MS = 900 +const EXPECTED_PAGE_CI_MS = 700 +const EXPECTED_TRAJECTORY_CI_MS = 500 +const OPEN_BUDGET_MS = Math.ceil(EXPECTED_OPEN_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +const PAGE_BUDGET_MS = Math.ceil(EXPECTED_PAGE_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +const TRAJECTORY_BUDGET_MS = Math.ceil(EXPECTED_TRAJECTORY_CI_MS * PERFORMANCE_BUDGET_HEADROOM) +const REPLAY_DURATION_MS = (DELTAS + 4) * PACE_MS + +async function painted(page: Page): Promise { + // Two rAF callbacks include a rendering opportunity, not a GPU presentation timestamp. + await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve())))) +} + +async function measure(page: Page, action: () => Promise): Promise { + const start = performance.now() + await action() + await painted(page) + return performance.now() - start +} + +async function taskMs(cdp: CDPSession): Promise { + const result = await cdp.send('Performance.getMetrics') + const metric = result.metrics.find(metric => metric.name === 'TaskDuration') + if (metric === undefined) throw new Error('Chromium TaskDuration missing') + return metric.value * 1000 +} + +function median(values: number[]): number { + return values.toSorted((a, b) => a - b)[Math.floor(values.length / 2)]! +} + +function expectEndpointWithinBudget(value: number, budget: number): void { + expect(value).toBeLessThanOrEqual(budget) +} + +function expectInputOverlap(value: boolean): void { + expect(value).toBe(true) +} + +async function watchInputOverlap(composer: Locator): Promise { + await composer.evaluate((element, markers) => { + element.removeAttribute('data-benchmark-input-witness') + element.removeAttribute('data-benchmark-input-overlap') + element.addEventListener('input', (event) => { + const transcript = Array.from(document.querySelectorAll('[data-chat-flow-kind="assistant-step"]')).at(-1)?.textContent ?? '' + element.setAttribute('data-benchmark-input-overlap', String(event.isTrusted && transcript.includes(markers.first) && !transcript.includes(markers.done))) + element.setAttribute('data-benchmark-input-witness', JSON.stringify({ trusted: event.isTrusted, first: transcript.includes(markers.first), done: transcript.includes(markers.done) })) + }, { once: true }) + }, { first: FIRST, done: DONE }) +} + +it('accepts recorded hosted open samples and rejects slower endpoints', () => { + for (const value of [681.276514, 541.051233]) { + expect(() => expectEndpointWithinBudget(value, ciTimeBudget(REFERENCE.open))).toThrow() + expectEndpointWithinBudget(value, OPEN_BUDGET_MS) + } + const repeatedMedian = median([875.306861, 1083.683529, 814.700998]) + expect(repeatedMedian).toBe(875.306861) + expect(() => expectEndpointWithinBudget(repeatedMedian, ciTimeBudget(REFERENCE.open))).toThrow() + expect(() => expectEndpointWithinBudget(repeatedMedian, 875)).toThrow() + expectEndpointWithinBudget(repeatedMedian, OPEN_BUDGET_MS) + expect(OPEN_BUDGET_MS).toBe(1125) + expect(() => expectEndpointWithinBudget(OPEN_BUDGET_MS + 1, OPEN_BUDGET_MS)).toThrow() + expect(() => expectEndpointWithinBudget(2000, OPEN_BUDGET_MS)).toThrow() +}) + +it('accepts recorded hosted paging and Trajectory medians and rejects slower endpoints', () => { + const endpoints = [ + { samples: [843.941625, 672.834329, 684.461818], reference: REFERENCE.page, budget: PAGE_BUDGET_MS, expectedBudget: 875 }, + { samples: [605.788061, 367.754027, 485.931656], reference: REFERENCE.trajectory, budget: TRAJECTORY_BUDGET_MS, expectedBudget: 625 }, + ] + for (const { samples, reference, budget, expectedBudget } of endpoints) { + const value = median(samples) + expect(() => expectEndpointWithinBudget(value, ciTimeBudget(reference))).toThrow() + expectEndpointWithinBudget(value, budget) + expect(budget).toBe(expectedBudget) + expect(() => expectEndpointWithinBudget(budget + 1, budget)).toThrow() + } +}) + +it('opens, pages, navigates and streams into a 240-turn browser history', async () => { + if (webSnapshotMode() !== 'replay') throw new Error('browser benchmarks require keyless replay mode') + const samples: { open: number; page: number; trajectory: number; first: number; streamTask: number; streamWall: number; input: number; inputOverlapped: boolean; heapMb: number; nodes: number }[] = [] + for (let sample = 0; sample < SAMPLES; sample++) { + const failures: unknown[] = [] + const root = await mkdtemp(join(tmpdir(), 'dsh-browser-benchmark-')) + try { + const replayOverride = join(root, 'reply.json') + await writeFile(replayOverride, JSON.stringify([{ kind: 'chunks', chunks: syntheticReply() }])) + const scaffold = await launchWebScaffold({ replayFixture: join(root, 'override-only.jsonl'), replayOverride, paceMs: PACE_MS, replayContextWindow: 10000000 }) + try { + const history = syntheticHistory() + await seedSession(scaffold, history, SESSION_ID) + console.log(JSON.stringify({ benchmark: 'long-session-browser/fixture', bytes: Buffer.byteLength(history) })) + const browser = await chromium.launch({ headless: true }) + try { + const page = await newEnglishPage(browser) + const consoleWatch = watchConsole(page) + page.setDefaultTimeout(30000) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + expect(new URL(page.url()).origin).toBe(scaffold.baseUrl) + console.log(JSON.stringify({ benchmark: 'long-session-browser/server', url: scaffold.baseUrl, browser: browser.version(), sample })) + await page.waitForSelector('[class*="frame"]') + await page.getByRole('treeitem').first().click() + const result = page.getByRole('treeitem').nth(1) + await result.waitFor() + const open = await measure(page, async () => { + await result.click() + await page.locator(TAIL).last().waitFor() + await page.locator('[data-composer-input][contenteditable="true"]').last().waitFor() + }) + const pages: number[] = [] + const initialTurns = await page.locator(TAIL).count() + expect(initialTurns).toBeGreaterThan(0) + expect(initialTurns).toBeLessThan(HISTORY_TURNS) + let count = initialTurns + while (count < HISTORY_TURNS) { + pages.push(await measure(page, async () => { + await page.getByRole('button', { name: 'Load earlier', exact: true }).click() + await page.waitForFunction(({ selector, previous }) => document.querySelectorAll(selector).length > previous, { selector: TAIL, previous: count }) + })) + count = await page.locator(TAIL).count() + } + const trajectory = await measure(page, async () => { + await page.getByRole('tab', { name: 'Trajectory', exact: true }).click() + await page.getByRole('searchbox', { name: 'Search trajectory', exact: true }).waitFor() + await page.getByRole('row').last().waitFor() + }) + await page.getByRole('tab', { name: 'Chat', exact: true }).click() + await page.waitForFunction(({ selector, expected }) => document.querySelectorAll(selector).length === expected, { selector: TAIL, expected: HISTORY_TURNS }) + const composer = page.locator('[data-composer-input][contenteditable="true"]').last() + await composer.fill('Continue the synthetic review and summarize the validation. '.repeat(30)) + const cdp = await page.context().newCDPSession(page) + await cdp.send('Performance.enable') + const beforeTask = await taskMs(cdp) + const settled = scaffold.whenTurnSettled(60000).then( + () => ({ ok: true as const }), + (error: unknown) => ({ ok: false as const, error }), + ) + await watchInputOverlap(composer) + const started = performance.now() + await page.locator('[data-composer-seat]').getByRole('button', { name: 'Send message', exact: true }).click() + const reply = page.locator('[data-chat-flow-kind="assistant-step"]').last() + await reply.getByText(FIRST, { exact: false }).last().waitFor() + const first = performance.now() - started + // Observe the actual trusted input event, not state before asynchronous click/typing. + const input = await measure(page, async () => { + await composer.click() + await page.keyboard.type('next synthetic question') + await expect.poll(() => composer.textContent()).toBe('next synthetic question') + }) + const inputOverlapped = await composer.getAttribute('data-benchmark-input-overlap') === 'true' + console.log(JSON.stringify({ benchmark: 'long-session-browser/input', sample, first, input, witness: await composer.getAttribute('data-benchmark-input-witness') })) + expectInputOverlap(inputOverlapped) + await reply.getByText(DONE, { exact: false }).last().waitFor() + const settlement = await settled + if (!settlement.ok) throw settlement.error + await page.waitForFunction(({ selector, expected }) => document.querySelectorAll(selector).length === expected, { selector: TAIL, expected: HISTORY_TURNS + 1 }) + await painted(page) + const streamWall = performance.now() - started + const streamTask = await taskMs(cdp) - beforeTask + await cdp.send('HeapProfiler.collectGarbage') + const metrics = (await cdp.send('Performance.getMetrics')).metrics + const heap = metrics.find(metric => metric.name === 'JSHeapUsedSize') + if (heap === undefined) throw new Error('Chromium heap metric missing') + samples.push({ open, page: Math.max(...pages), trajectory, first, streamTask, streamWall, input, inputOverlapped, heapMb: heap.value / 1048576, nodes: await page.locator('*').count() }) + console.log(JSON.stringify({ benchmark: 'long-session-browser/sample', sample, initialTurns, pages, ...samples.at(-1) })) + await watchInputOverlap(composer) + await composer.click() + await page.keyboard.type('!') + const lateInputOverlapped = await composer.getAttribute('data-benchmark-input-overlap') === 'true' + expect(await composer.getAttribute('data-benchmark-input-witness')).toBe(JSON.stringify({ trusted: true, first: true, done: true })) + expect(() => expectInputOverlap(lateInputOverlapped)).toThrow() + expect(consoleWatch.pageErrors).toEqual([]) + expect(consoleWatch.warnings).toEqual([]) + } catch (error) { failures.push(error) } finally { + await browser.close().catch((error: unknown) => failures.push(error)) + } + } catch (error) { failures.push(error) } finally { + await scaffold.close().catch((error: unknown) => failures.push(error)) + } + } catch (error) { failures.push(error) } finally { + await rm(root, { recursive: true, force: true }).catch((error: unknown) => failures.push(error)) + } + if (failures.length > 0) throw new AggregateError(failures, 'browser benchmark failed') + } + const aggregate = Object.fromEntries(Object.keys(REFERENCE).map(key => [key, median(samples.map(sample => sample[key as keyof typeof REFERENCE]))])) + const budgets: Record = { + ...Object.fromEntries(Object.entries(REFERENCE).map(([key, value]) => [key, ciTimeBudget(value) + (key === 'streamWall' ? REPLAY_DURATION_MS : 0)])), + open: OPEN_BUDGET_MS, page: PAGE_BUDGET_MS, trajectory: TRAJECTORY_BUDGET_MS, + } + console.log(JSON.stringify({ benchmark: 'long-session-browser/median', turns: HISTORY_TURNS, deltas: DELTAS, paceMs: PACE_MS, samples, aggregate, referenceMs: REFERENCE, expectedOpenCiMs: EXPECTED_OPEN_CI_MS, expectedPageCiMs: EXPECTED_PAGE_CI_MS, expectedTrajectoryCiMs: EXPECTED_TRAJECTORY_CI_MS, budgets })) + for (const [key, value] of Object.entries(aggregate)) expectEndpointWithinBudget(value, budgets[key]!) +}) diff --git a/benchmarks/long-session-browser/synthetic-history.ts b/benchmarks/long-session-browser/synthetic-history.ts new file mode 100644 index 0000000000..106c9950a3 --- /dev/null +++ b/benchmarks/long-session-browser/synthetic-history.ts @@ -0,0 +1,92 @@ +/** Synthetic current-generation history and paced reply for browser measurements. */ +import { createAssistantMessage, createUserMessage, createToolResultMessage, ToolCallId } from '@deepseek-ai/dsh-llm' +import type { StreamChunk } from '@deepseek-ai/dsh-llm' +import { AssistantStreamAccumulator } from '@deepseek-ai/dsh-llm/assistant-stream' +import { Session, SessionId, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session' +import type {} from '@deepseek-ai/dsh-session-title' + +/** Closed turns in the browser history workload. */ +export const HISTORY_TURNS = 240 +/** Identity private to each isolated scaffold. */ +export const SESSION_ID = 'benchmark-browser-history' +const TITLE = 'SYNTHETIC_BROWSER_HISTORY' +/** First streamed text marker. */ +export const FIRST = 'SYNTHETIC_REPLY_FIRST' +/** Last streamed text marker. */ +export const DONE = 'SYNTHETIC_REPLY_DONE' +/** Paced text chunks per continuation. */ +export const DELTAS = 120 +/** Replay delay per stream chunk, in milliseconds. */ +export const PACE_MS = 16 + +/** Create mixed prose, code, reasoning and tool history without reading user data. + * @returns Current Session JSONL accepted by the shared Web seeder. + */ +export function syntheticHistory(): string { + const session = Session.create(SessionId(SESSION_ID)) + for (let turn = 1; turn <= HISTORY_TURNS; turn++) { + session.append('turn/start', { turn }) + const user = session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'Review synthetic change ' + String(turn) + ': 检查增量渲染。 '.repeat(30) }], + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + if (turn === 1) session.append('session/title', { title: TITLE, messageSeqs: [user.seq], source: { kind: 'fallback' } }) + session.append('step/start', { turn, step: 1 }) + const callId = ToolCallId('synthetic-tool-' + String(turn)) + const tool = turn % 6 === 0 + const code = turn % 12 === 0 + ? '\n\n```ts\n' + Array.from({ length: 60 }, (_, i) => 'const value' + String(i) + ' = ' + String(i)).join('\n') + '\n```' + : '' + const reasoning = 'Compare the synthetic module and test. '.repeat(40) + const text = 'Synthetic answer ' + String(turn) + '. ' + 'Preserve ordering and validate the output. '.repeat(30) + code + const args = '{"path":"src/example.ts"}' + const stream = new AssistantStreamAccumulator() + let time = 1700000000000 + turn * 10000 + const push = (chunk: StreamChunk): void => { stream.push({ time: time++, chunk }) } + for (const [index, block] of [{ type: 'reasoning' as const, text: reasoning }, { type: 'text' as const, text }].entries()) { + push({ type: 'block-start', index, blockType: block.type }) + for (let offset = 0; offset < block.text.length; offset += 12) { + push({ type: block.type === 'reasoning' ? 'reasoning-delta' : 'text-delta', index, text: block.text.slice(offset, offset + 12) }) + } + push({ type: 'block-end', index, block }) + } + if (tool) { + push({ type: 'block-start', index: 2, blockType: 'tool-call' }) + for (let offset = 0; offset < args.length; offset += 8) { + push({ type: 'tool-call-delta', index: 2, id: callId, ...offset === 0 ? { name: 'synthetic_tool' } : {}, argumentsDelta: args.slice(offset, offset + 8) }) + } + push({ type: 'block-end', index: 2, block: { type: 'tool-call', id: callId, name: 'synthetic_tool', arguments: args } }) + } + push({ type: 'usage', usage: { inputTokens: 4000, outputTokens: 800 } }) + push({ type: 'finish', reason: { kind: tool ? 'tool-calls' : 'stop' } }) + session.append('assistant/message', { + turn, step: 1, stream: [...stream.snapshot()], + message: createAssistantMessage({ + source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' }, + content: [ + { type: 'reasoning', text: reasoning }, + { type: 'text', text }, + ...tool ? [{ type: 'tool-call' as const, id: callId, name: 'synthetic_tool', arguments: args }] : [], + ], + }), + usage: { inputTokens: 4000, outputTokens: 800 }, + }, { surfaceOp: 'append' }) + if (tool) { + const call = session.append('tool/call', { turn, step: 1, callId, name: 'synthetic_tool', arguments: args }) + session.append('tool/result', { turn, step: 1, message: createToolResultMessage({ + callId, isError: false, content: [{ type: 'text', text: 'Synthetic tool output line.\n'.repeat(160) }], + }) }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] }) + } + session.append('step/end', { turn, step: 1 }) + session.append('turn/end', { turn, reason: { kind: 'completed' } }) + } + return [JSON.stringify({ type: 'session', version: SESSION_FORMAT_VERSION, id: '{{sessionId}}', createdAt: 1700000000000, cwd: '{{cwd}}', isSeeded: false, delegationDepth: 0 }), ...session.snapshotEvents().map(event => JSON.stringify(event)), ''].join('\n') +} + +/** Create one paced response; replay owns delays outside the browser. + * @returns Stream chunks ending in a visible completion marker. + */ +export function syntheticReply(): StreamChunk[] { + const deltas = Array.from({ length: DELTAS }, (_, i) => i === 0 ? FIRST + ' ' : i === DELTAS - 1 ? DONE : 'Synthetic response ' + String(i) + '. ') + return [{ type: 'block-start', index: 0, blockType: 'text' }, ...deltas.map(text => ({ type: 'text-delta' as const, index: 0, text })), { type: 'block-end', index: 0, block: { type: 'text', text: deltas.join('') } }, { type: 'usage', usage: { inputTokens: 4000, outputTokens: 800 } }, { type: 'finish', reason: { kind: 'stop' } }] +} diff --git a/benchmarks/package.json b/benchmarks/package.json index 673146977e..cc8c60cf71 100644 --- a/benchmarks/package.json +++ b/benchmarks/package.json @@ -5,6 +5,8 @@ "private": true, "type": "module", "devDependencies": { + "playwright": "^1.49.0", + "@deepseek-ai/dsh-llm-replay": "workspace:^", "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", @@ -15,6 +17,7 @@ "@deepseek-ai/dsh-client-ui-chat": "workspace:^", "@deepseek-ai/dsh-deque": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-sdk-client": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", @@ -23,6 +26,8 @@ "@deepseek-ai/dsh-session-stats": "workspace:^", "@deepseek-ai/dsh-session-title": "workspace:^", "@deepseek-ai/dsh-session-turn-outline": "workspace:^", + "@deepseek-ai/dsh-subagent": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^" }, diff --git a/benchmarks/tsdown.config.ts b/benchmarks/tsdown.config.ts index 2f3112308f..2b7a7d2bb9 100644 --- a/benchmarks/tsdown.config.ts +++ b/benchmarks/tsdown.config.ts @@ -14,6 +14,25 @@ const shared = { /** Compile measured benchmark workers while keeping workspace packages on their built `lib` entries. */ export default defineConfig([ + { + ...shared, + entry: { 'reconnect.worker': 'active-stream-reconnect/reconnect.worker.client.ts' }, + outDir: '.dsh-build/active-stream-reconnect', + clean: true, + tsconfig: 'tsconfig.client.json', + }, + { + ...shared, + entry: { + 'agent-continuation.worker': 'agent-continuation/agent-continuation.worker.ts', + 'child-catalog.worker': 'agent-continuation/child-catalog.worker.ts', + 'profile-continuation.worker': 'agent-continuation/profile-continuation.worker.ts', + 'profile-adapter': 'agent-continuation/profile-adapter.ts', + }, + outDir: '.dsh-build/agent-continuation', + clean: true, + tsconfig: 'tsconfig.host.json', + }, { ...shared, entry: { 'session-open.worker': 'session-open/session-open.worker.ts' }, diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 46d8c636b6..12a7a1d617 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: bbd6a7e09b6af2fe5e90acab33ad220d3f1b62d1 -architecture.zh.md: b05670f8f715c5c3dd5c8cdd76ec81e9d426ace6 +architecture.md: fcb9c1e59b60dc059ab66b64ac26acd3c9157c96 +architecture.zh.md: d7a0a3833ebf9397837967065249d7fe1650d707 diff --git a/docs/architecture.md b/docs/architecture.md index bbd6a7e09b..fcb9c1e59b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -100,6 +100,8 @@ Input reaches the driver through one inbox. Some messages wake it immediately; i `agent/pre-step` decides what the model sees. Listeners may rewrite the claimed messages or reject them outright; a rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt. An enter decision may also set `startsRequestSeries` to begin a distinct model-message series: the loop then logs a fresh `request/header` (reason `series`, or `change` carrying `startsSeries: true` when the envelope changed too). A listener that rebuilds a downstream enter decision must spread it (`{ ...decision, messages }`) so the declaration survives. Each step reads the prompt sections and tool schemas that plugins registered. +The loop sends immutable requests while keeping cancellation live. It reuses message-freeze provenance only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction rules. + Details: the [sequence diagram](agent-lifecycle.md), the [tool pipeline](tool-execution-pipeline.md), and [cancellation and error recovery](subsystems/core.md#the-agent-handle). ## Session log diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index b05670f8f7..d7a0a3833e 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -104,6 +104,8 @@ turn/end `agent/pre-step` 决定模型看到什么。监听器可以改写已领取的消息，也可以直接拒绝它们；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，因此日志会记录这次尝试。enter 决策还可以设置 `startsRequestSeries` 来开启独立的模型消息序列：loop 会随之记录一个新的 `request/header`（原因为 `series`，或在封装同时变化时为携带 `startsSeries: true` 的 `change`）。重建下游 enter 决策的监听器必须展开它（`{ ...decision, messages }`），该声明才能存活。每个步骤读取插件注册的提示词片段和工具 schema。 +循环发送不可变请求，同时保留实时取消能力。只有已由该循环完整冻结的消息对象身份才能复用冻结证明；[agent-loop](../packages/core/agent-loop/README.zh.md)拥有请求构造规则。 + 详情见[时序图](agent-lifecycle.zh.md)、[工具流水线](tool-execution-pipeline.zh.md)和[取消与错误恢复](subsystems/core.zh.md#the-agent-handle)。 ## 会话日志 diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 8a94a10eaa..598d2c1187 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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/event-producer-consumer.md -event-producer-consumer.md: ae4119a08d4150a9d3284e6fbcfb33ba7207923a +event-producer-consumer.md: 7cecb1f362c311cf9b7b617466c1eaa06721a05e event-producer-consumer.zh.md: 57af4848a79065cc4ca65d6f56f4d543ec979441 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index ae4119a08d..7cecb1f362 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -54,10 +54,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` | | `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:298`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - | -| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:172`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) | -| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:146`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | -| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:152`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | -| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:163`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) | +| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:168`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) | +| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | +| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:148`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | +| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:159`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`session-reference`](../packages/context/session-reference), [`system-prompt`](../packages/core/system-prompt) | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:199`](../packages/core/tools/src/index.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`), [`tools`](../packages/core/tools) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) | diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 2f666d64cc..726a365742 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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/module-graph.md -module-graph.md: 5307a62360f2c01d03df4693081c02c5d6e56a39 -module-graph.zh.md: fa6e5b3cd98e3dc80aad906d01d1d1a07ef91842 +module-graph.md: 83b68cf3398e8f24d0332dd572679efe8fa75ceb +module-graph.zh.md: b680094f342034e21a25f22f35404b2865d4318e diff --git a/docs/module-graph.md b/docs/module-graph.md index 5307a62360..83b68cf339 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -1075,6 +1075,7 @@ flowchart TD pkg_api_session_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_typert_registry pkg_api_session_controller --> pkg_util_time + pkg_api_session_controller --> pkg_util_values pkg_api_session_controller --> pkg_util_workspace_path pkg_api_session_controller --> pkg_workspace pkg_experimental_agent_team --> pkg_agent @@ -1401,7 +1402,7 @@ flowchart TD | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | +| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index fa6e5b3cd9..b680094f34 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -1077,6 +1077,7 @@ flowchart TD pkg_api_session_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_typert_registry pkg_api_session_controller --> pkg_util_time + pkg_api_session_controller --> pkg_util_values pkg_api_session_controller --> pkg_util_workspace_path pkg_api_session_controller --> pkg_workspace pkg_experimental_agent_team --> pkg_agent @@ -1403,7 +1404,7 @@ flowchart TD | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | +| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml index c656b49ab0..3c53237bad 100644 --- a/docs/subsystems/subagent.i18n.yaml +++ b/docs/subsystems/subagent.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/subsystems/subagent.md -subagent.md: 616300f92ffa827f14c4780a7648f60f52df56ad -subagent.zh.md: 059dc4af988ad5ce66bed64827b72449f5a781ca +subagent.md: cf711185d02808f70a71a46c6d6c1af4da4a7334 +subagent.zh.md: e97b4ab965d279f04ddda5e8ae66621b0198a5cd diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md index 616300f92f..cf711185d0 100644 --- a/docs/subsystems/subagent.md +++ b/docs/subsystems/subagent.md @@ -141,13 +141,15 @@ persisted Session | `waiting` | wake and steer the same Activation | | no Activation | cold-resume a new Activation, then steer it | -`running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine. +`running` means the Agent has an active driver or maintenance task; `waiting` means no Agent activity is active but its Inbox is nonempty or it owns at least one child Activation that has not completed disposal; `settled` means no Agent activity is active, the Inbox is empty, and every owned child is disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from `Agent.whenIdle()`, `Agent.inbox.hasPending`, the owned-child set, and an Activation generation that invalidates stale observations, rather than maintaining a second execution state machine. After the final Session flush, the child-lock decision uses the synchronous task entry of `Agent.runMaintenance()` to claim the idle phase and close admission in the same JavaScript turn. This conservative rule does not distinguish delivery modes: context parked by `Agent.inject()` can keep an idle Activation and its live ancestors resident until a waking delivery claims it, a queue mutation removes it, or manager teardown discards it. -The Agent inbox is the only queue. Every Agent message uses `Agent.steer()`: an idle target starts a turn, while a running target claims it at the nearest step boundary. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/inserted`, `agent/inbox/claimed`, and `agent/inbox/discarded` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route. +The Agent inbox is the only queue. Every Agent message uses `Agent.steer()`: an idle target starts a turn, while a running target claims it at the nearest step boundary. The browser `subagent.prompt` Remote separately carries `delivery: 'queue' | 'steer'` through the same internal admission path; Queue opens a later FIFO turn, while Steer retains the Agent loop's best-effort nearest-step behavior and the message's human source. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/inserted`, `agent/inbox/claimed`, and `agent/inbox/discarded` events remain the message-lifecycle observations, and the continuation layer defines no second queue. Authority comes from the exact live sender. Parent-to-child delivery requires the target's `SessionHeader.parentSession` to name the sender; child-to-parent delivery requires the sender's resident Activation to name the target. Siblings, ancestors beyond one edge, self-targets, stale Agent objects, and one-shot children are rejected. Each accepted message is framed as `Agent sent a message:` and records `AgentMessageSource`; provenance records the sender but grants no authority. -For `startContinuable()` and `sendMessage()`, the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child. Human browser prompts remain a separate private Queue adapter and therefore still produce distinct FIFO turns. +For `startContinuable()`, `sendMessage()`, and browser prompt delivery, the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child. The public subagent service exposes no caller-selected Agent-message scheduling; browser human Queue and Steer remain internal adapter choices. + +Live queue occurrence mutation remains in the Session domain. `session.updateQueue` admits ordinary Edit, Remove, and QueueDock Steer for a live subagent-owned Agent only when its current projected identity is continuable and its descriptor sequence is in that child's own non-seed suffix. The identity projection folds descriptors last-wins so a child descriptor supersedes descriptors retained from fork lineage; the own-suffix sequence check prevents a seed-only ancestor identity from authorizing mutation. One-shot, missing, unknown, corrupt, or cold children remain rejected, and queue mutation never cold-resumes a child. The target Session id is the human authority for these mutations, including pending `nextStep` steering or injected context. Steer requires a queued `MessageId` and an Agent that reports running when the command begins; cancellation after admission uses the Agent's accepted waking `nextTurn` fallback. Edit rewrites content under the same `MessageId`, and both Edit and Steer complete their Inbox work synchronously, so settlement observes only the final state. `agent/inbox/claimed` and `agent/inbox/discarded` wake the watcher to re-read whether any pending occurrence remains; this lets direct Agent delivery resume parked work and lets removing the last parked occurrence settle an idle child. The [human inbox-control Agent Note](../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md) owns these semantics. `SubagentRuntime.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its unclaimed pending inbox work, and published descendants are untouched; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup. @@ -162,7 +164,7 @@ type SubagentInterruptAuthority = | { readonly kind: 'ancestor'; readonly agent: Agent } ``` -Every Activation owns its `AgentHandle` and an `ownedChildren: Set`; because one Session has at most one live Activation, the child Session id identifies the live child without another runtime-incarnation reference. Starting a child or submitting parent-originated work registers the child in a continuation-managed parent's set before the child can run, and that parent cannot settle while the set is non-empty. A top-level or other non-continuation Agent has no Activation and stays outside the waiting graph. Child release happens only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. +Every Activation owns its `AgentHandle` and an `ownedChildren: Set`; because one Session has at most one live Activation, the child Session id identifies the live child without another runtime-incarnation reference. Starting a child or submitting parent-originated work registers the child in a continuation-managed parent's set before the child can run, and that parent cannot settle while the set is non-empty. A top-level or other non-continuation Agent has no Activation and stays outside the waiting graph. Child release happens only after the child has no active Agent work, its Inbox is empty, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. Final settlement awaits `ctx.sessions.flush(session)` but ignores its participation boolean because an arbitrary listener cannot prove that a persistence backend stored the state. Rejection is logged without failing the Activation, and the manager still disposes the handle and releases ownership; the persisted child state may then be missing or stale on a later resume. Manager unload invokes an internal manager-wide drain that closes admission and disposes every live forest; `drainContinuableDescendants(parents)` closes admission only below exact live host-owned Agents and disposes their continuable descendants while unrelated forests remain live. Both await already-admitted materializations in their scope, propagate cancellation top-down, release handles child-first, and await every selected branch despite individual failures. Durable child Sessions survive that process-local teardown. @@ -195,7 +197,7 @@ interface ContinuableStart { } ``` -When a resident Activation settles, the manager delivers one notice to the child's durable direct parent describing how that epoch ended and carrying its final assistant content. That delivery is unconditional for every child whose id a caller received, happens before the ownership release that would let the parent be judged settled, and reaches a resident parent through the same waking-admission accounting as an Agent message. A parent whose own lineage is already tearing down receives it without a wake, because waking a quiescent Agent starts a turn rather than queueing work. Its provenance is a distinct kind so a transcript never presents a runtime account as something the child wrote. +When a resident Activation settles, the manager delivers one notice to the child's durable direct parent describing how that epoch ended and carrying its final assistant content. That delivery is unconditional for every child whose id a caller received, happens before the ownership release that would let the parent be judged settled, and reaches a resident parent through the same waking Agent delivery as an Agent message. A parent whose own lineage is already tearing down receives it without a wake, because waking an idle Agent starts a turn rather than queueing work. Its provenance is a distinct kind so a transcript never presents a runtime account as something the child wrote. ```ts type-equiv /** @@ -611,11 +613,12 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise sent a message:` 作为前缀，并记录 `AgentMessageSource`；来源信息记录 sender，但不授予权限。 -对于 `startContinuable()` 与 `sendMessage()`，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent。浏览器中的人类提示仍由私有 Queue 适配器处理，因此继续产生独立 FIFO 轮次。 +对于 `startContinuable()`、`sendMessage()` 与浏览器 prompt 投递，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent。公开 subagent 服务不暴露由调用方选择的 Agent 消息调度；浏览器人类 Queue 与 Steer 仍是内部适配器选择。 + +在线 queue occurrence 变更属于 Session 域。只有在线 subagent-owned Agent 的当前 projection identity 为 continuable，且其 descriptor 序号位于该 child 自身的非 seed suffix 时，`session.updateQueue` 才会接纳普通 Edit、Remove 与 QueueDock Steer。Identity projection 以 last-wins 方式折叠 descriptor，因此 child descriptor 会覆盖 fork lineage 保留的 descriptor；own-suffix 序号检查会阻止仅来自 seed 的祖先 identity 授权变更。One-shot、缺失、未知、损坏或冷 child 会被拒绝，queue 变更绝不会冷恢复 child。这些变更以目标 Session id 作为人类权限，包括待处理 `nextStep` steering 或注入 context。Steer 要求 queued `MessageId`，且 command 开始时 Agent 必须报告 running；准入后发生取消时，会使用 Agent 已接受的唤醒 `nextTurn` fallback。Edit 会在同一个 `MessageId` 下改写内容，且 Edit 与 Steer 都会同步完成 Inbox 变更，因此 settlement 只会观察最终状态。`agent/inbox/claimed` 与 `agent/inbox/discarded` 都会唤醒 watcher 重新读取是否仍有待处理 occurrence；这样，直接 Agent 投递可以恢复停放工作，而移除最后一个停放 occurrence 可使 idle child 结算。[人类 inbox 控制 Agent Note](../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md)拥有这些语义。 `SubagentRuntime.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待完全停稳即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；陈旧的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。 @@ -162,7 +164,7 @@ type SubagentInterruptAuthority = | { readonly kind: 'ancestor'; readonly agent: Agent } ``` -每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已完全停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。 +每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 没有活跃工作、其 Inbox 为空、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。 最终结算会等待 `ctx.sessions.flush(session)`，但会忽略其参与布尔值，因为任意 listener 都无法证明某个持久化后端已存储该状态。rejection 会被记录，但不会使 Activation 失败；管理器仍会 dispose 该 handle 并释放所有权，此后持久化的子 agent 状态在后续恢复时可能缺失或陈旧。管理器卸载会调用内部的管理器全局 drain，关闭准入并 dispose 每片在线森林；`drainContinuableDescendants(parents)` 只关闭由 host 确切拥有的在线 Agent 之下的准入，并 dispose 其可继续后代，而无关森林保持在线。两者都会等待各自作用域内已获准的物化过程，自顶向下传播取消，按 child-first 顺序释放 handle，并且即使个别分支失败也会等待所有选中分支。持久化子会话不受该进程内拆卸的影响。 @@ -195,7 +197,7 @@ interface ContinuableStart { } ``` -当驻留 Activation 结算时，管理器会向该 child 持久化的直接 parent 投递一条通知，说明该 epoch 如何结束，并携带其最终 assistant 内容。对每个调用方拿到过 id 的 child，这条投递都是无条件的；它发生在会让 parent 被判定为已结算的所有权释放之前，并通过与 Agent 消息相同的唤醒准入记账到达驻留 parent。若 parent 自身所在的谱系已在拆卸中，这条通知会以不唤醒的方式送达，因为唤醒一个静息 Agent 是开启一个轮次，而不是排队等待工作。其来源信息使用一个独立的 kind，因此 transcript（文本记录）绝不会把运行时的记账呈现为 child 自己写下的内容。 +当驻留 Activation 结算时，管理器会向该 child 持久化的直接 parent 投递一条通知，说明该 epoch 如何结束，并携带其最终 assistant 内容。对每个调用方拿到过 id 的 child，这条投递都是无条件的；它发生在会让 parent 被判定为已结算的所有权释放之前，并通过与 Agent 消息相同的唤醒 Agent 投递到达驻留 parent。若 parent 自身所在的谱系已在拆卸中，这条通知会以不唤醒的方式送达，因为唤醒一个 idle Agent 是开启一个轮次，而不是排队等待工作。其来源信息使用一个独立的 kind，因此 transcript（文本记录）绝不会把运行时的记账呈现为 child 自己写下的内容。 ```ts type-equiv /** @@ -615,11 +617,12 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise> /** - * Apply one edit, remove, or strict steer action to a still-pending queue occurrence. + * Apply one edit, remove, or Steer action to a still-pending queue occurrence. * @param itemId - agent-owned inbox occurrence identity. * @param action - requested queue operation. * @returns acceptance, or a business/transport error. diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts index 10f9702aab..2945f0b5c4 100644 --- a/packages/api/session-controller/src/client/sessions/session.ts +++ b/packages/api/session-controller/src/client/sessions/session.ts @@ -271,6 +271,7 @@ export class Session implements SessionFace { parentSessionId: this.address.parentSessionId, childSessionId: this.address.childSessionId, mode: 'continuable', + delivery: mode, content: routedContent, clientTimeZone: resolvedClientTimeZone(), }, signal) diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts index 3a6d81b2ab..f3fa473e6c 100644 --- a/packages/api/session-controller/src/commands.ts +++ b/packages/api/session-controller/src/commands.ts @@ -19,6 +19,7 @@ import type { SessionEvent, SessionHeader, SessionId, UserMessage } from '@deeps import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query' import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title' import { canonicalClientTimeZone } from '@deepseek-ai/dsh-util-time' +import { assertNever } from '@deepseek-ai/dsh-util-values' import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol' import type { Workspace } from '@deepseek-ai/dsh-workspace' import { @@ -415,12 +416,18 @@ export class SessionCommandController { ) } const agent = this.ctx.agents.get(request.sessionId) - if (agent !== undefined && hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) { - throw apiSessionSubagentOwnershipError(request.sessionId) - } if (agent === undefined) { throw new RemoteError('session/queue-item-not-found', 'queued item is no longer pending', { itemId: request.itemId }) } + if (hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) { + const identity = this.ctx.sessionProjections + .snapshot(agent.session, ['subagent']) + .values.subagent + if (identity?.mode !== 'continuable' + || !agent.session.isOwnSeq(identity.seq)) { + throw apiSessionSubagentOwnershipError(request.sessionId) + } + } const nextTurn = agent.inbox.nextTurn.find(message => message.id === request.itemId) const nextStep = agent.inbox.nextStep.find(message => message.id === request.itemId) const located = nextTurn === undefined @@ -433,20 +440,28 @@ export class SessionCommandController { if (request.action.kind === 'steer' && (target !== 'next-turn' || agent.status !== 'running')) { throw new RemoteError('session/steer-unavailable', 'current turn no longer accepts steering', { itemId: request.itemId }) } - if (request.action.kind === 'edit') { - agent.inbox.replace(request.itemId, freezeMessage({ - ...message, - content: [...request.action.content], - })) - } else { - agent.inbox.remove(request.itemId) - if (request.action.kind === 'remove') { + switch (request.action.kind) { + case 'edit': + agent.inbox.replace(request.itemId, freezeMessage({ + ...message, + content: [...request.action.content], + })) + break + case 'remove': { + agent.inbox.remove(request.itemId) const source = message.source if (source.kind === 'user' && 'rpcId' in source) { this.ctx.fileUploads.retirePrompt(agent, source.rpcId) } + break } - if (request.action.kind === 'steer') agent.steer(message) + case 'steer': + agent.inbox.remove(request.itemId) + agent.steer(message) + break + /* v8 ignore next 2 -- closed-union exhaustiveness guard */ + default: + assertNever(request.action, 'queue action') } return { accepted: true } } diff --git a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts index 8fdf62c451..30665e979c 100644 --- a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts +++ b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts @@ -4,14 +4,20 @@ import type { Agent, ModelSelectionRef } from '@deepseek-ai/dsh-agent' import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import { createAssistantMessage, createUserMessage, MessageId } from '@deepseek-ai/dsh-llm' -import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session' -import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session' +import SessionStore, { + SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset, SessionSeq, +} from '@deepseek-ai/dsh-session' +import type { SessionEvent, SessionHeader, UserMessage } from '@deepseek-ai/dsh-session' +import { snapshotSubagentDescriptor, SUBAGENT_DESCRIPTOR_VERSION } from '@deepseek-ai/dsh-subagent' +import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts' import { describe, expect, it, vi } from 'vitest' import { ApiSessionAgentController } from '../src/agent.ts' import { SessionCommandController } from '../src/commands.ts' import { installSessionReadTestServices, testSessionPersistence } from './test-remote.ts' -async function commandHarness(): Promise<{ +async function commandHarness( + childMode?: 'continuable' | 'seeded-continuable' | 'seed-only' | 'one-shot' | 'unknown' | 'corrupt', +): Promise<{ ctx: Context controller: SessionCommandController agent: Agent @@ -22,9 +28,48 @@ async function commandHarness(): Promise<{ const ctx = new Context() await ctx.plugin(SessionStore) await ctx.plugin(AgentRegistry) - const session = ctx.sessions.create(SessionId('commands-session'), { meta: { cwd: '/workspace' } }) + installSessionReadTestServices(ctx) + ctx.sessionProjections.register(subagentIdentityProjectionDefinition) + const sessionId = SessionId('commands-session') + const ancestor = Session.create(SessionId('ancestor')) + ancestor.append('subagent/descriptor', snapshotSubagentDescriptor({ + mode: 'continuable', provider: 'test', label: 'ancestor', + })) + // A seeded child inherits exactly the ancestor prefix; its own descriptor + // is appended after creation, as the continuation manager does. `seed-only` + // never appends one: the identity folds as continuable, but from the + // inherited prefix rather than this Session's own suffix. + const lineage = childMode === 'seeded-continuable' || childMode === 'seed-only' + ? ancestor.snapshotEvents() + : undefined + const session = ctx.sessions.create(sessionId, { + ...lineage === undefined ? {} : { seed: lineage, inheritedEventCount: SessionLogOffset(lineage.length) }, + meta: { + cwd: '/workspace', + ...(childMode === undefined ? {} : { + origin: 'subagent' as const, + parentSession: SessionId('offline-parent'), + }), + ...lineage === undefined ? {} : { isSeeded: true }, + }, + }) + if (childMode === 'continuable' || childMode === 'seeded-continuable') { + session.append('subagent/descriptor', snapshotSubagentDescriptor({ + mode: 'continuable', provider: 'test', label: 'child', + })) + } else if (childMode === 'one-shot') { + session.append('subagent/descriptor', snapshotSubagentDescriptor({ + mode: 'one-shot', provider: 'test', label: 'child', + })) + } else if (childMode === 'corrupt') { + session.append('subagent/descriptor', { + version: SUBAGENT_DESCRIPTOR_VERSION, + mode: 'continuable', + provider: 1, + } as never) + } const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }) - const steer = vi.fn() + const steer = vi.fn((message: UserMessage) => { inbox.append('next-step', message) }) const cancel = vi.fn() const agent = { id: session.id, @@ -52,7 +97,14 @@ async function commandHarness(): Promise<{ serializeImageAdmission: (_agent: Agent, operation: () => Promise) => operation(), composeAgent: () => Promise.resolve({ setup: () => {} }), } as unknown as ApiSessionAgentController - return { ctx, controller: new SessionCommandController(ctx, agents, '/workspace'), agent, inbox, steer, cancel } + return { + ctx, + controller: new SessionCommandController(ctx, agents, '/workspace'), + agent, + inbox, + steer, + cancel, + } } async function expectFailure(operation: Promise, code: string): Promise { @@ -100,6 +152,9 @@ describe('Session queue commands', () => { action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] }, })).toEqual({ accepted: true }) expect(inbox.nextTurn[0]?.content).toEqual([{ type: 'text', text: 'edited' }]) + // An edit rewrites content in place, so the occurrence a client addressed + // by id stays addressable. + expect(inbox.nextTurn[0]?.id).toBe(queued.id) expect(controller.updateQueue({ sessionId: agent.id, itemId: nextStep.id, action: { kind: 'remove' }, })).toEqual({ accepted: true }) @@ -136,6 +191,81 @@ describe('Session queue commands', () => { expect(cancel).toHaveBeenCalledWith({ kind: 'user' }, { keepInbox: true }) await ctx.fiber.dispose() }) + + it.each(['continuable', 'seeded-continuable'] as const)( + 'mutates both inbox destinations of a live %s child while its parent is offline', + async (childMode) => { + const { ctx, controller, agent, inbox, steer } = await commandHarness(childMode) + const queued = createUserMessage({ + content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' }, + }) + const context = createUserMessage({ + content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' }, + }) + inbox.append('next-turn', queued) + inbox.append('next-step', context) + + expect(controller.updateQueue({ + sessionId: agent.id, + itemId: context.id, + action: { kind: 'edit', content: [{ type: 'text', text: 'edited context' }] }, + })).toEqual({ accepted: true }) + const editedContext = inbox.nextStep[0] + expect(editedContext).toMatchObject({ + content: [{ type: 'text', text: 'edited context' }], + source: context.source, + }) + expect(editedContext?.id).toBe(context.id) + if (editedContext === undefined) throw new Error('missing edited context') + expect(controller.updateQueue({ + sessionId: agent.id, itemId: editedContext.id, action: { kind: 'remove' }, + })).toEqual({ accepted: true }) + expect(controller.updateQueue({ + sessionId: agent.id, itemId: queued.id, action: { kind: 'steer' }, + })).toEqual({ accepted: true }) + expect(steer).toHaveBeenCalledWith(queued) + await ctx.fiber.dispose() + }, + ) + + it('removes the selected message before handing it to Agent steering', async () => { + const { ctx, controller, agent, inbox, steer } = await commandHarness('continuable') + const first = createUserMessage({ + content: [{ type: 'text', text: 'first' }], source: { kind: 'user' }, + }) + const second = createUserMessage({ + content: [{ type: 'text', text: 'second' }], source: { kind: 'user' }, + }) + inbox.append('next-turn', first) + inbox.append('next-turn', second) + // Stand in for the Agent's cancellation-convergence destination; the + // command must accept whichever boundary `Agent.steer()` selects. + steer.mockImplementation((message: UserMessage) => { inbox.append('next-turn', message) }) + + expect(controller.updateQueue({ + sessionId: agent.id, itemId: first.id, action: { kind: 'steer' }, + })).toEqual({ accepted: true }) + expect(steer).toHaveBeenCalledWith(first) + // Ordering proves the removal happened before delivery rather than after. + expect(inbox.nextTurn).toEqual([second, first]) + expect(inbox.nextStep).toEqual([]) + await ctx.fiber.dispose() + }) + + it('keeps one-shot, seed-only, missing, and malformed child descriptors behind the ownership fence', async () => { + for (const mode of ['one-shot', 'seed-only', 'unknown', 'corrupt'] as const) { + const { ctx, controller, agent, inbox } = await commandHarness(mode) + const queued = createUserMessage({ + content: [{ type: 'text', text: mode }], source: { kind: 'user' }, + }) + inbox.append('next-turn', queued) + await expectFailure(Promise.resolve().then(() => controller.updateQueue({ + sessionId: agent.id, itemId: queued.id, action: { kind: 'remove' }, + })), 'session/agent-busy') + expect(inbox.nextTurn).toEqual([queued]) + await ctx.fiber.dispose() + } + }) }) function imageRef(id: string): ImageAttachmentRef { diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts index 629e3d4a76..2608887137 100644 --- a/packages/api/session-controller/tests/manager.client.spec.ts +++ b/packages/api/session-controller/tests/manager.client.spec.ts @@ -320,6 +320,7 @@ describe('subagent catalogs', () => { requestId: expect.any(String) as unknown as string, parentSessionId: S1, childSessionId: S2, mode: 'continuable', + delivery: 'queue', content: [{ type: 'text', text: 'continue' }], clientTimeZone: new Intl.DateTimeFormat().resolvedOptions().timeZone, }, diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts index 20893c01e2..c5a62a27df 100644 --- a/packages/api/session-controller/tests/session.client.spec.ts +++ b/packages/api/session-controller/tests/session.client.spec.ts @@ -400,9 +400,11 @@ describe('prompt and cancel errors', () => { }) await session.open() const prompted = await session.prompt([{ type: 'text', text: '继续' }], 'queue') + const steered = await session.prompt([{ type: 'text', text: '现在处理' }], 'steer') const cancelled = await session.cancel() expect(prompted).toEqual({ ok: true, value: { accepted: true } }) + expect(steered).toEqual({ ok: true, value: { accepted: true } }) expect(cancelled).toEqual({ ok: true, value: { accepted: true } }) expect(api.callsOf('session.follow')).toEqual([ { @@ -419,9 +421,18 @@ describe('prompt and cancel errors', () => { requestId: expect.any(String) as unknown as string, parentSessionId: PARENT, childSessionId: SID, mode: 'continuable', + delivery: 'queue', content: [{ type: 'text', text: '继续' }], clientTimeZone: new Intl.DateTimeFormat().resolvedOptions().timeZone, }, + { + requestId: expect.any(String) as unknown as string, + parentSessionId: PARENT, childSessionId: SID, + mode: 'continuable', + delivery: 'steer', + content: [{ type: 'text', text: '现在处理' }], + clientTimeZone: new Intl.DateTimeFormat().resolvedOptions().timeZone, + }, ]) expect(api.callsOf('subagents.interruptByParent')).toEqual([ { childSessionId: SID, parentSessionId: PARENT, mode: 'continuable' }, @@ -456,6 +467,7 @@ describe('prompt and cancel errors', () => { requestId: expect.any(String) as unknown as string, parentSessionId: PARENT, childSessionId: SID, mode: 'continuable', + delivery: 'queue', content, clientTimeZone: new Intl.DateTimeFormat().resolvedOptions().timeZone, }, diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json index ad7751119f..85366bd632 100644 --- a/packages/api/session-controller/tsconfig.host.json +++ b/packages/api/session-controller/tsconfig.host.json @@ -44,6 +44,7 @@ { "path": "../../skill/skill" }, { "path": "../../subagent/subagent" }, { "path": "../../util/time" }, + { "path": "../../util/values" }, { "path": "../../typert/protocol" }, { "path": "../../typert/registry" }, { "path": "../../workspace/workspace" } diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml index a2b157652e..746b9fc2a6 100644 --- a/packages/client/ui-chat/README.i18n.yaml +++ b/packages/client/ui-chat/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-chat/README.md -README.md: 405e5095d75c3e8b752c028bbc187307a9647bb6 -README.zh.md: 7f57bc3480ea0186e89d12e8e443926906677742 +README.md: fa9653f7acab47f352e59971b333c6e691f44191 +README.zh.md: f8dc1968fffc57336d6aece8fe07113d5b99893b diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md index 405e5095d7..fa9653f7ac 100644 --- a/packages/client/ui-chat/README.md +++ b/packages/client/ui-chat/README.md @@ -46,7 +46,7 @@ Settings → General exposes a persisted `Normal` / `Compact` conversation-displ ## Scroll ownership -Chat restores semantic anchors across history prepend and renderer remounts. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn. Turn-rail previews paint above sticky Markdown code-block banners, while the rail frame remains inside the transcript band above the composer. +Chat restores semantic anchors across history prepend and renderer remounts. Pinned scroll deliveries without reader movement update follow ownership immediately, before subsequent layout changes can invalidate their floor. Reader movement remains pending until the sampling interval or `scrollend`, even inside the follow threshold, so layout growth cannot erase small scroll gestures. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn. Turn-rail previews paint above sticky Markdown code-block banners, while the rail frame remains inside the transcript band above the composer. ----- diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md index 7f57bc3480..f8dc1968ff 100644 --- a/packages/client/ui-chat/README.zh.md +++ b/packages/client/ui-chat/README.zh.md @@ -46,7 +46,7 @@ Chat 会为非空的初始请求、显式消息序列起点、真实 system 字 ## 滚动归属 -Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点。读者跟随底部时，`ResizeObserver` 追随新的底部，并且无需读取行几何就选中最后一个已加载 Turn；读者离开底部后，高度变化会保持顶部位置，再由阅读线几何选择活跃 Turn。轮次导航预览位于 Markdown 代码块粘性头栏上方，而导航外框始终处于 composer 上方的 transcript 区域内。 +Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点。没有读者移动的贴底滚动事件会立即更新跟随归属，避免后续布局变化使其底部位置失效。读者移动即使位于跟随阈值内，也保持待处理直到采样周期或 `scrollend`，防止布局增长抵消小幅滚动操作。读者跟随底部时，`ResizeObserver` 追随新的底部，并且无需读取行几何就选中最后一个已加载 Turn；读者离开底部后，高度变化会保持顶部位置，再由阅读线几何选择活跃 Turn。轮次导航预览位于 Markdown 代码块粘性头栏上方，而导航外框始终处于 composer 上方的 transcript 区域内。 ----- diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx index a8dc57d321..21e1f78a29 100644 --- a/packages/client/ui-chat/src/client/chat/ChatView.tsx +++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx @@ -24,6 +24,11 @@ function scrollerOf(from: HTMLElement): HTMLElement { return (from.closest('[data-conversation-scroll]')) ?? from } +/** Browser shrink clamps and recorded writes do not transfer scroll ownership. */ +function readerMovedScroll(top: number, floor: number, observedTop: number): boolean { + return Math.abs(top - Math.min(observedTop, floor)) > 0.5 +} + interface PagingAnchor { /** Stable node/call identity, independent of boundary-spanning group keys. */ key: string @@ -555,7 +560,7 @@ export function ChatView({ // programmatic deliveries land on the ledger itself, so both preserve // the current ownership state. const floor = Math.max(0, el.scrollHeight - el.clientHeight) - const movedByReader = Math.abs(el.scrollTop - Math.min(observedTopRef.current, floor)) > 0.5 + const movedByReader = readerMovedScroll(el.scrollTop, floor, observedTopRef.current) const isAtBottom = movedByReader ? floor - el.scrollTop <= FOLLOW_THRESHOLD + 1 : atBottomRef.current @@ -579,8 +584,9 @@ export function ChatView({ scheduleActiveTurn() } - // Raw scroll events only schedule work. Geometry is sampled at most once - // per interval, with scrollend providing the final sample for a short burst. + // Non-reader pinned deliveries must settle before layout growth invalidates + // their floor. Reader movement stays pending even inside the follow threshold, + // so growth cannot erase small gestures before they accumulate off the floor. useEffect(() => { const local = listRef.current /* v8 ignore next -- ref-null guard: effect runs after the list node commits. */ @@ -597,6 +603,13 @@ export function ChatView({ } const onScroll = (): void => { scrollSamplePendingRef.current = true + if (atBottomRef.current) { + const floor = Math.max(0, el.scrollHeight - el.clientHeight) + if (!readerMovedScroll(el.scrollTop, floor, observedTopRef.current)) { + sample() + return + } + } sampleTimer ??= window.setTimeout(sample, SCROLL_SAMPLE_INTERVAL_MS) } el.addEventListener('scroll', onScroll, { passive: true }) diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx index 2c8fe220ea..074ae15330 100644 --- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx +++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx @@ -2387,6 +2387,162 @@ describe('ChatView', () => { expect(scroller.scrollTop).toBe(900) }) + it('keeps following when a shrink clamp regrows before scrollend', () => { + const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] }) + const view = render() + const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement + const metrics = installScrollMetrics(scroller, 1_000, 300) + scroller.scrollTop = 700 + fireEvent.scroll(scroller) + fireEvent(scroller, new Event('scrollend')) + + metrics.setLayout(800, 700) + fireEvent.scroll(scroller) + metrics.setHeight(962) + act(() => { h.setSession({ running: true }) }) + fireEvent(scroller, new Event('scrollend')) + + expect(scroller.scrollTop).toBe(662) + expect(view.queryByLabelText('回到底部')).toBeNull() + expect(h.chatScroll.read()).toBeNull() + }) + + it('settles pinned deliveries before observer growth without reading row geometry', () => { + let notify: (() => void) | undefined + class ResizeObserverStub { + constructor(callback: ResizeObserverCallback) { + notify = () => { callback([], this as unknown as ResizeObserver) } + } + + observe = vi.fn() + disconnect = vi.fn() + } + vi.stubGlobal('ResizeObserver', ResizeObserverStub) + const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] }) + const view = render() + const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement + const metrics = installScrollMetrics(scroller, 9_931, 300) + expect(notify).toBeDefined() + scroller.scrollTop = 9_631 + fireEvent.scroll(scroller) + fireEvent(scroller, new Event('scrollend')) + const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect') + rect.mockClear() + try { + metrics.setLayout(9_918, 9_631) + fireEvent.scroll(scroller) + metrics.setHeight(10_013) + act(() => { notify?.() }) + expect(scroller.scrollTop).toBe(9_713) + fireEvent.scroll(scroller) + metrics.setHeight(10_093) + act(() => { notify?.() }) + expect(scroller.scrollTop).toBe(9_793) + expect(rect).not.toHaveBeenCalled() + expect(h.chatScroll.read()).toBeNull() + } finally { + rect.mockRestore() + } + }) + + it('lets small reader movements accumulate past the follow threshold during growth', () => { + let notify: (() => void) | undefined + class ResizeObserverStub { + constructor(callback: ResizeObserverCallback) { + notify = () => { callback([], this as unknown as ResizeObserver) } + } + + observe = vi.fn() + disconnect = vi.fn() + } + vi.stubGlobal('ResizeObserver', ResizeObserverStub) + const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] }) + const view = render() + const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement + const metrics = installScrollMetrics(scroller, 1_000, 300) + expect(notify).toBeDefined() + scroller.scrollTop = 700 + fireEvent.scroll(scroller) + fireEvent(scroller, new Event('scrollend')) + scroller.scrollTop = 690 + fireEvent.scroll(scroller) + metrics.setHeight(1_020) + act(() => { notify?.() }) + expect(scroller.scrollTop).toBe(690) + scroller.scrollTop = 680 + fireEvent.scroll(scroller) + fireEvent(scroller, new Event('scrollend')) + expect(view.getByLabelText('回到底部')).toBeTruthy() + metrics.setHeight(1_040) + act(() => { notify?.() }) + expect(scroller.scrollTop).toBe(680) + }) + + it('clears an away sample when a back-to-bottom delivery restores pinned ownership', () => { + const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] }) + const view = render() + const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement + const metrics = installScrollMetrics(scroller, 1_000, 300) + scroller.scrollTop = 700 + fireEvent.scroll(scroller) + scroller.scrollTop = 500 + fireEvent.scroll(scroller) + fireEvent(scroller, new Event('scrollend')) + scroller.scrollTop = 400 + fireEvent.scroll(scroller) + fireEvent.click(view.getByLabelText('回到底部')) + fireEvent.scroll(scroller) + metrics.setHeight(1_200) + act(() => { h.setSession({ running: true }) }) + expect(scroller.scrollTop).toBe(900) + expect(h.chatScroll.read()).toBeNull() + }) + + it('samples away-reader geometry on the interval or scrollend and cancels it on unmount', () => { + vi.useFakeTimers() + try { + const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] }) + const view = render() + const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement + installScrollMetrics(scroller, 1_000, 300) + scroller.scrollTop = 700 + fireEvent.scroll(scroller) + scroller.scrollTop = 500 + fireEvent.scroll(scroller) + fireEvent(scroller, new Event('scrollend')) + expect(view.getByLabelText('回到底部')).toBeTruthy() + const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect') + try { + act(() => { vi.advanceTimersByTime(500) }) + rect.mockClear() + scroller.scrollTop = 400 + fireEvent.scroll(scroller) + scroller.scrollTop = 300 + fireEvent.scroll(scroller) + act(() => { vi.advanceTimersByTime(499) }) + expect(rect).not.toHaveBeenCalled() + act(() => { vi.advanceTimersByTime(1) }) + expect(rect).toHaveBeenCalled() + rect.mockClear() + scroller.scrollTop = 200 + fireEvent.scroll(scroller) + expect(rect).not.toHaveBeenCalled() + fireEvent(scroller, new Event('scrollend')) + expect(rect).toHaveBeenCalled() + scroller.scrollTop = 100 + fireEvent.scroll(scroller) + view.unmount() + rect.mockClear() + act(() => { vi.advanceTimersByTime(500) }) + expect(rect).not.toHaveBeenCalled() + } finally { + rect.mockRestore() + } + } finally { + vi.useRealTimers() + } + }) + it('uses the last delivered top when compositor scrolling precedes scroll delivery', () => { const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] }) const view = render() diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index a45c0a1cde..15a81cc65b 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/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-conversation/README.md -README.md: b615730842fbbed0ab63e7e51e0361e3077785d0 -README.zh.md: 36faa9a0f466f8d11d2dd350a51691cf7e8de931 +README.md: 9a1a12ed86afe4d5ccea63045aeade5860f309cc +README.zh.md: 372f24039a3c880520c2ad690a996754b2ed2e0b diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index b615730842..9a1a12ed86 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -48,8 +48,7 @@ Default sends commit optimistically: Enter clears the draft, occurrence table, a Queued submission echoes show “Sending…” beside disabled edit, remove, and steer buttons; a collapsed dock keeps the sending status in its header. A matching Host queue row replaces the echo and enables each action according to its normal text-content and running-state requirements. Prompt acknowledgement alone does not enable queue actions. A failed submission removes its echo and displays an error; the composer restores the failed draft when it is empty or still contains the previous automatic restoration, preserving subsequently typed text. -While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Queue Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting continues to select the Queue or Steer keyboard action. Plan mode and active goals do not change attachment intake. Continuable subagents keep separate Send and Stop actions but expose no paperclip, paste, or drop intake. - +While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Queue Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting selects the Queue or Steer keyboard action for ordinary Sessions and continuable children. Their QueueDock rows share Edit, Remove, and Steer, and an empty draft shares the steer-all chord. One-shot children remain read-only. Plan mode and active goals do not change attachment intake. Continuable children keep separate Send and Stop actions but expose no paperclip, paste, or drop intake; if their parent is offline, Send and the composer gestures lock while QueueDock controls for the live inbox remain available ([decisions](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md), [inbox controls](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md)). ## Temporary composer entries diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 36faa9a0f4..372f24039a 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -48,8 +48,7 @@ Session 首次绑定或缓存的 Session 成为 current 时，shell 会在渲染 排队提交的本地回显在禁用的编辑、删除、插话按钮旁显示“发送中…”；折叠后的队列在标题栏保留发送状态。匹配的 Host 队列行替换回显后，各操作按原有的纯文本内容和运行状态要求启用。仅收到 prompt 确认不会启用队列操作。提交失败会移除回显并显示错误；输入框为空或仍保留上一次自动恢复的内容时，composer 恢复失败草稿，保留用户随后输入的文字。 -普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Queue Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置继续选择 Queue 或 Steer 键盘操作。Plan Mode 与 active goal 不改变附件入口。continuable 子代理保留独立的 Send 与 Stop 操作，但不提供回形针、粘贴或拖放入口。 - +普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Queue Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置会为普通 Session 与可继续 child 选择 Queue 或 Steer 键盘操作。它们的 QueueDock 行共享 Edit、Remove 与 Steer，空草稿也共享 steer-all 组合键。One-shot child 继续只读。Plan Mode 与 active goal 不改变附件入口。可继续 child 保留独立的 Send 与 Stop 操作，但不提供回形针、粘贴或拖放入口；parent 离线时，Send 与 composer 手势锁定，但在线 inbox 的 QueueDock 控制仍可使用（[决策](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md)、[inbox 控制](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md)）。 ## 临时 composer entry diff --git a/packages/client/ui-conversation/src/client/input/hub.ts b/packages/client/ui-conversation/src/client/input/hub.ts index 00730b15f7..f255877ddb 100644 --- a/packages/client/ui-conversation/src/client/input/hub.ts +++ b/packages/client/ui-conversation/src/client/input/hub.ts @@ -187,14 +187,14 @@ export class InputHub implements SessionInputResolver { } /** - * Steer every still-pending queued message into the running turn, in FIFO - * order — the same strict-steer operation as the queue dock's per-row - * button. A turn closing mid-way (`session/steer-unavailable`) or a row already + * Submit every still-pending queued message through QueueDock Steer, in FIFO + * request order — the same operation as the queue dock's per-row button. + * An Agent stopping before a command (`session/steer-unavailable`) or a row already * claimed by the agent (`session/queue-item-not-found`) converges silently, while a * genuine failure surfaces as one composer notice. Repeated triggers * (e.g. two rapid empty-draft chords) rely on that `session/queue-item-not-found` * convergence: the snapshot may still list a row the host already steered, - * and the duplicate strict steer is a silent no-op. + * and the duplicate Steer is a silent no-op. * @param session - the addressed host session. * @param shell - the resident shell (notice outlet). */ diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx index 389ed42273..0dcbdda890 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx @@ -99,7 +99,7 @@ export function QueueDock({ useSession, updateQueue, notify, loadImage, t }: Que }, [pendingSubmissions, queue]) const rowCount = queue.length + pendingQueue.length const running = useSession(s => s.running) - const queueMutable = useSession(s => s.subagent === null) + const queueMutable = useSession(s => s.subagent === null || s.subagent.address.mode === 'continuable') const [editing, setEditing] = useState<{ id: QueueItemId; text: string } | null>(null) const [busy, setBusy] = useState(null) const [collapsed, setCollapsed] = useState(true) diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts index 29023e1b92..444238568e 100644 --- a/packages/client/ui-conversation/src/client/service.ts +++ b/packages/client/ui-conversation/src/client/service.ts @@ -51,10 +51,10 @@ export interface IConversation { */ send(text: string): Promise /** - * Apply one edit, remove, or strict steer operation to a pending queue occurrence. + * Apply one edit, remove, or Steer operation to a pending queue occurrence. * @param itemId - agent-owned inbox occurrence identity. * @param action - requested queue operation. - * @returns completion; converged strict-steer races resolve, while other failures reject. + * @returns completion; converged QueueDock races resolve, while other failures reject. */ updateQueue(itemId: QueueItemId, action: QueueAction): Promise /** diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx index 8747f70104..144df68c43 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx @@ -138,7 +138,8 @@ export const InputBar = memo(function InputBar({ const workspaceTrigger = inert && !removed && onRequestWorkspace !== undefined const editorDisabled = removed || (locked && !workspaceTrigger) const editable = live && !locked && !machineBusy - const canSteerQueue = !locked && !machineBusy && !commandMenuOpen && empty && running && subagent === null + const steeringAvailable = subagent === null || subagent.address.mode === 'continuable' + const canSteerQueue = !locked && !machineBusy && !commandMenuOpen && empty && running && steeringAvailable && input.queue.some(row => row.placement === 'queued') useEffect(() => { @@ -262,11 +263,11 @@ export const InputBar = memo(function InputBar({ // The keymap handlers read live bar state through this ref so the editor // registration survives re-renders without re-arming per keystroke. const gate = useRef({ - locked, machineBusy, canSteerQueue, running, subagent, resolveSubmitMode, + locked, machineBusy, canSteerQueue, running, steeringAvailable, resolveSubmitMode, intakeFiles, uploadsPending, showToast, t, }) gate.current = { - locked, machineBusy, canSteerQueue, running, subagent, resolveSubmitMode, + locked, machineBusy, canSteerQueue, running, steeringAvailable, resolveSubmitMode, intakeFiles, uploadsPending, showToast, t, } @@ -296,7 +297,7 @@ export const InputBar = memo(function InputBar({ keyboard.submit(g.resolveSubmitMode( g.running, accelerated ? 'accelerated' : 'enter', - g.subagent === null, + g.steeringAvailable, )) }, intakeFiles: (files) => { gate.current.intakeFiles(files) }, diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx index 78d53353ce..e5d7cd38e7 100644 --- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx @@ -462,12 +462,6 @@ describe('Enter semantics', () => { it('advertises the empty-draft whole-queue steering gesture when it is available', () => { const { placeholder } = bench({ running: true, queue: [row('q-1')], steerQueue: vi.fn() }) expect(placeholder).toBe('Cmd/Ctrl+Enter 插话发送全部排队消息') - }) - - it('keeps the owning placeholder or ordinary guidance when whole-queue steering is unavailable', () => { - expect(bench({ running: true }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') - expect(bench({ queue: [row('q-1')] }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') - expect(bench({ running: true, queue: [row('q-1')], draft: '消息' }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') expect(bench({ running: true, queue: [row('q-1')], @@ -475,7 +469,13 @@ describe('Enter semantics', () => { address: { parentSessionId: 'parent' as SessionId, childSessionId: SID, mode: 'continuable' }, parentAvailable: true, }, - }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') + }).placeholder).toBe('Cmd/Ctrl+Enter 插话发送全部排队消息') + }) + + it('keeps the owning placeholder or ordinary guidance when whole-queue steering is unavailable', () => { + expect(bench({ running: true }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') + expect(bench({ queue: [row('q-1')] }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') + expect(bench({ running: true, queue: [row('q-1')], draft: '消息' }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话') expect(bench({ running: true, queue: [row('q-1')], @@ -566,7 +566,7 @@ describe('Enter semantics', () => { expect(ctrl.sink).not.toHaveBeenCalled() }) - it('queue steering stays gated: idle, subagent, plain Enter, empty queue, or steering-only rows', () => { + it('queue steering stays gated by activity, gesture, capability, and queued rows', () => { // Idle: the gesture falls through to the machine's empty-draft no-op. const idle = bench({ queue: [row('q-1')], steerQueue: vi.fn() }) fireEvent.keyDown(idle.textarea, { key: 'Enter', metaKey: true }) @@ -579,7 +579,7 @@ describe('Enter semantics', () => { expect(plain.steerQueue).not.toHaveBeenCalled() expect(plain.sink).not.toHaveBeenCalled() - // Subagent sessions keep the queue transport (no steering face). + // Continuable children expose the same steering face as ordinary Sessions. const subagent = { address: { parentSessionId: 'parent' as SessionId, @@ -588,9 +588,10 @@ describe('Enter semantics', () => { }, parentAvailable: true, } - const child = bench({ running: true, subagent, queue: [row('q-1')], steerQueue: vi.fn() }) + const childSteerQueue = vi.fn() + const child = bench({ running: true, subagent, queue: [row('q-1')], steerQueue: childSteerQueue }) fireEvent.keyDown(child.textarea, { key: 'Enter', metaKey: true }) - expect(child.steerQueue).not.toHaveBeenCalled() + expect(childSteerQueue).toHaveBeenCalledTimes(1) expect(child.sink).not.toHaveBeenCalled() // No queued rows: the empty draft stays a no-op. @@ -859,7 +860,7 @@ describe('running and lock semantics', () => { expect(stop).not.toHaveBeenCalled() }) - it('keeps both running subagent Enter gestures on Queue transport', () => { + it('applies the ordinary Queue/Steer preference to a running continuable child', () => { const subagent = { address: { parentSessionId: 'parent' as SessionId, @@ -870,11 +871,15 @@ describe('running and lock semantics', () => { } const plain = bench({ running: true, busyEnter: 'steer', draft: 'plain', subagent }) fireEvent.keyDown(plain.textarea, { key: 'Enter' }) - expect(plain.sink).toHaveBeenCalledWith('plain', [], 'queue', expect.any(AbortSignal)) + expect(plain.sink).toHaveBeenCalledWith('plain', [], 'steer', expect.any(AbortSignal)) const accelerated = bench({ running: true, draft: 'accelerated', subagent }) fireEvent.keyDown(accelerated.textarea, { key: 'Enter', metaKey: true }) - expect(accelerated.sink).toHaveBeenCalledWith('accelerated', [], 'queue', expect.any(AbortSignal)) + expect(accelerated.sink).toHaveBeenCalledWith('accelerated', [], 'steer', expect.any(AbortSignal)) + + const opposite = bench({ running: true, busyEnter: 'steer', draft: 'opposite', subagent }) + fireEvent.keyDown(opposite.textarea, { key: 'Enter', metaKey: true }) + expect(opposite.sink).toHaveBeenCalledWith('opposite', [], 'queue', expect.any(AbortSignal)) }) it('disabled (session removed) locks the textarea and chrome', () => { diff --git a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx index 632885802e..07d13f9d13 100644 --- a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx +++ b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx @@ -1,7 +1,7 @@ // @vitest-environment jsdom /** * QueueDock rendering and operations: authoritative rows, inline editing, - * collapse state, removal, strict steering, failure notices, and live retirement. + * collapse state, removal, QueueDock Steer, failure notices, and live retirement. */ import { afterEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react' @@ -486,7 +486,7 @@ describe('QueueDock', () => { expect(rendered.getByLabelText('插话发送').getAttribute('title')).toBe('仅运行中可插话发送') }) - it('renders a session-backed subagent Queue without unsupported actions', () => { + it('renders ordinary queue actions for a continuable child', () => { const snap = { ...snapshotWith([row('i-subagent', 'pending child follow-up')]), subagent: { @@ -495,6 +495,29 @@ describe('QueueDock', () => { childSessionId: SID, mode: 'continuable' as const, }, + parentAvailable: false, + }, + } + const source = liveSession(snap) + const view = render( + , + ) + + expect(view.getByText('pending child follow-up')).toBeTruthy() + expect(view.getByLabelText('编辑排队消息')).toBeTruthy() + expect(view.getByLabelText('删除排队消息')).toBeTruthy() + expect(view.getByLabelText('插话发送')).toBeTruthy() + }) + + it('keeps a one-shot child Queue read-only', () => { + const snap = { + ...snapshotWith([row('i-subagent', 'pending child follow-up')]), + subagent: { + address: { + parentSessionId: 'parent' as SessionId, + childSessionId: SID, + mode: 'one-shot' as const, + }, parentAvailable: true, }, } diff --git a/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts index ff46ef3680..5e0521f0da 100644 --- a/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts +++ b/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts @@ -78,7 +78,7 @@ describe('ConversationController', () => { await b.runtime.dispose() }) - it('treats strict-steer races as converged Queue delivery', async () => { + it('treats QueueDock Steer pre-admission races as converged Queue delivery', async () => { const b = await bench() b.updateQueue.mockResolvedValueOnce({ ok: false, error: new RemoteError('session/steer-unavailable', 'closed', { itemId: 'item-1' as QueuedMessage['id'] }), @@ -822,7 +822,7 @@ describe('InputHub queue steering (empty-draft accelerated Enter)', () => { expect(b.shell.notices.getSnapshot()).toBeNull() // A row the host already claimed (e.g. a repeated empty-draft chord): - // the duplicate strict steer is a silent no-op. + // the duplicate Steer is a silent no-op. await b.runtime.sessions.updateSessionSnapshot('s1', (draft) => { draft.queue = [row('q-3')] }) diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml index 95a4edc69e..b1cc6893b2 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: c5985f585f92f38cb27ae1385b1052dbce1d9b9d -README.zh.md: 615cdd5a6e3e71ae129d782403f09d0309913929 +README.md: 55966a4b0eed0c1cc3484314e809de79341072de +README.zh.md: 1d27bf3743f54d8fe66a58e75565fc85d94ae1ed diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index c5985f585f..55966a4b0e 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -90,6 +90,8 @@ The package is the one concrete implementation of the public `Agent` contract. I After `agent/request`, `ctx.llm.prepareCall()` validates adapter-owned fields and resolves reasoning-effort and output-token defaults under the active turn signal. The loop retains that exact adapter through resolution, `request/header` logging, and dispatch. It writes a full header for the first request, a changed envelope, an explicit message-series start, a request after surface replacement, and resume; unchanged steps, retries, and ordinary later turns in the same series inherit the latest header. Before the next waterfall, the loop removes adapter-default fields so the current route resolves them again, while explicit settings persist. An unhandled route still fails with `NO_ADAPTER`. +The loop deep-freezes each derived message identity on its first request and reuses that proof only within the same agent. Restored messages keep their identity; request construction does not freeze their containing event wrappers. Each request freezes its local canonical header, fresh message array, and envelope while leaving the cancellation signal live. The [request-freeze decision](../../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md) explains ownership and measurement. + ### Source map | File | Role | diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md index 615cdd5a6e..1d27bf3743 100644 --- a/packages/core/agent-loop/README.zh.md +++ b/packages/core/agent-loop/README.zh.md @@ -90,6 +90,8 @@ const handle = await ctx.agents.create({ `agent/request` 返回后，`ctx.llm.prepareCall()` 会在活跃轮次信号下校验适配器持有的字段，并解析推理强度和输出 token 默认值。循环会在解析、`request/header` 记录与分派期间保留同一个适配器。循环会为首次请求、变化的 envelope、显式消息序列起点、表层替换后的请求及恢复写入完整 header；同一序列内内容未变的步骤、重试与普通后续轮次继承最新 header。下一次 waterfall 前，循环移除适配器默认字段，使当前路由重新解析它们；显式设置则保留。未处理的路由仍以 `NO_ADAPTER` 失败。 +循环在每个派生消息对象首次进入请求时执行深冻结，并且仅在同一 agent 内复用该证明。恢复的消息保留对象身份；构造请求不会冻结包含消息的事件包装对象。每个请求都会冻结本地规范化 header、新消息数组和请求封装，同时保留取消信号的可变性。[请求冻结决策](../../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md)解释了所有权与测量依据。 + ### 源码地图 | 文件 | 职责 | diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 5dd560cd99..634a1a52de 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -87,6 +87,8 @@ export class ReactLoopAgent implements Agent { /** Process-local revision of assistant frames for this attached Session. */ private assistantStreamRevision = 0 private assistantAttemptCounter = 0 + /** Identities fully frozen by this loop; weak references do not retain replaced history. */ + private readonly frozenMessages = new WeakSet() constructor( private loopCtx: Context, @@ -483,7 +485,8 @@ export class ReactLoopAgent implements Agent { /** * Compose one frozen request and bind it to the adapter registration that - * resolved its exact-model defaults. + * resolved its exact-model defaults. Message identities retain their first + * successful deep freeze; each local header is frozen afresh. The signal stays live. */ private async buildRequest( turn: number, @@ -576,7 +579,15 @@ export class ReactLoopAgent implements Agent { } signal.throwIfAborted() - const request = markAgentLoopRequest(deepFreeze({ + // canonicalHeader is shallow; append logs a detached snapshot, not these local values. + deepFreeze(header) + for (const message of boundaryMessages) { + if (this.frozenMessages.has(message)) continue + deepFreeze(message) + this.frozenMessages.add(message) + } + Object.freeze(boundaryMessages) + const request = markAgentLoopRequest(Object.freeze({ ...header.config, messages: boundaryMessages, ...header.system !== undefined ? { system: header.system } : {}, diff --git a/packages/core/agent-loop/tests/request-freeze.spec.ts b/packages/core/agent-loop/tests/request-freeze.spec.ts new file mode 100644 index 0000000000..cfb2c64da2 --- /dev/null +++ b/packages/core/agent-loop/tests/request-freeze.spec.ts @@ -0,0 +1,234 @@ +/** Request immutability through the real loop, including adopted restore graphs. */ + +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' +import { createAssistantMessage, createUserMessage, isAgentLoopRequest } from '@deepseek-ai/dsh-llm' +import type { GenerateOptions, ToolSchema } from '@deepseek-ai/dsh-llm' +import { Session, SessionId, SessionLogOffset, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session' +import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' +import * as values from '@deepseek-ai/dsh-util-values' +import { ReactLoopAgent } from '../src/agent.ts' +import { MockAdapter, textResponse } from './mock-adapter.ts' + +const cleanups: (() => Promise)[] = [] +afterEach(async () => { + try { + for (const cleanup of cleanups.reverse()) await cleanup() + } finally { + cleanups.length = 0 + vi.restoreAllMocks() + } +}) + +async function harness(adapter?: MockAdapter): Promise { + const ctx = new Context() + cleanups.push(() => ctx.fiber.dispose()) + await mountAgentLoopTestDependencies(ctx) + await ctx.plugin(SessionProjectionRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + if (adapter) ctx.effect(() => ctx.llm.registerAdapter(['mock'], adapter)) + return ctx +} + +async function send(agent: Agent, text: string): Promise { + agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })) + await agent.whenIdle() +} + +function expectFrozen(value: unknown): void { + if (value === null || typeof value !== 'object' || value instanceof AbortSignal) return + expect(Object.isFrozen(value)).toBe(true) + for (const child of Object.values(value)) expectFrozen(child) +} + +describe('loop-owned request freezing', () => { + it('adopts restored identities, freezes nested messages at dispatch, and leaves event wrappers mutable', async () => { + const ctx = await harness(new MockAdapter([textResponse('one'), textResponse('two'), textResponse('three'), textResponse('four')])) + const id = SessionId('restored-freeze') + const seed = Session.create(id) + seed.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'restored user' }], source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + seed.append('assistant/message', { + turn: 1, step: 1, + message: createAssistantMessage({ + content: [{ type: 'text', text: 'restored assistant' }], + source: { provider: 'mock', model: 'mock', replayState: { nested: ['opaque'] } }, + }), + stream: [], + }, { surfaceOp: 'append' }) + const events = structuredClone(seed.snapshotEvents()) + const userEvent = events.find(event => event.type === 'user/message')! + const assistantEvent = events.find(event => event.type === 'assistant/message')! + Object.freeze(userEvent.data) + const freeze = vi.spyOn(values, 'deepFreeze') + const session = Session.fromRestore(id, events, { + id, version: SESSION_FORMAT_VERSION, createdAt: 1, cwd: '/test', isSeeded: false, + }, SessionLogOffset(0), 'detached') + const before = session.deriveMessages() + expect(before[0]).toBe(userEvent.data) + expect(before[1]).toBe(assistantEvent.data.message) + expect(Object.isFrozen(before)).toBe(false) + expect(Object.isFrozen(userEvent.data.content)).toBe(false) + expect(Object.isFrozen(assistantEvent.data.message)).toBe(false) + ctx.effect(() => ctx.sessions.enter(session)) + const agent = new ReactLoopAgent(ctx, id, { provider: 'mock', model: 'mock' }, session) + cleanups.push(async () => { + agent.cancel({ kind: 'disposed' }) + await agent.whenIdle() + await agent.scope.dispose() + }) + const requests: GenerateOptions[] = [] + const errors: unknown[] = [] + ctx.on('agent/error', ({ error }) => { errors.push(error) }) + ctx.on('llm/stream', (request, next) => { + expect(isAgentLoopRequest(request)).toBe(true) + expectFrozen(request) + requests.push(request) + return next() + }) + await send(agent, 'first') + expect(errors).toEqual([]) + expect(requests).toHaveLength(1) + const first = requests[0]! + expect(first.messages[0]).toBe(before[0]) + expect(first.messages[1]).toBe(before[1]) + expect(Object.isFrozen(userEvent)).toBe(false) + expect(Object.isFrozen(assistantEvent.data)).toBe(false) + expect(Object.isFrozen(assistantEvent.data.stream)).toBe(false) + userEvent.time += 1 + assistantEvent.data.stream.push({ type: 'chunk', time: 2, chunk: { type: 'finish', reason: { kind: 'stop' } } }) + before.pop() + const held = JSON.stringify(first.messages) + await send(agent, 'second') + expect(requests).toHaveLength(2) + expect(requests[1]!.messages).not.toBe(first.messages) + expect(requests[1]!.messages[0]).toBe(first.messages[0]) + expect(requests[1]!.messages.length).toBeGreaterThan(first.messages.length) + const nodes = session.surface.nodes + const replacement = session.append('user/message', { + ...userEvent.data, content: [{ type: 'text', text: 'compacted' }], + }, { + surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, + sourceEventSeqs: [nodes[0]!, nodes[1]!], + }) + await send(agent, 'third') + expect(requests).toHaveLength(3) + expect(requests[2]!.messages[0]).toBe(replacement.data) + expect(requests[2]!.messages[0]!.id).toBe(first.messages[0]!.id) + expect(requests[2]!.messages[0]).not.toBe(first.messages[0]) + expect(JSON.stringify(first.messages)).toBe(held) + expect(Object.isFrozen(session.deriveMessages())).toBe(false) + expect(freeze.mock.calls.filter(([value]) => value === userEvent.data)).toHaveLength(1) + expect(freeze.mock.calls.filter(([value]) => value === replacement.data)).toHaveLength(1) + const resumed = new ReactLoopAgent(ctx, id, { provider: 'mock', model: 'mock' }, session) + cleanups.push(async () => { + resumed.cancel({ kind: 'disposed' }) + await resumed.whenIdle() + await resumed.scope.dispose() + }) + await send(resumed, 'fresh loop') + expect(requests).toHaveLength(4) + expect(freeze.mock.calls.filter(([value]) => value === replacement.data)).toHaveLength(2) + }) + + it('retries freezing an identity whose previous traversal failed', async () => { + const ctx = await harness(new MockAdapter([textResponse('done')])) + const agent = await ctx.agentLoop.create(SessionId('freeze-failure'), { provider: 'mock', model: 'mock' }) + const message = agent.session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'history' }], source: { kind: 'user' }, + }), { surfaceOp: 'append' }).data + const realFreeze = values.deepFreeze + let traversals = 0 + vi.spyOn(values, 'deepFreeze').mockImplementation((value) => { + if (value === message && ++traversals === 1) throw new Error('freeze traversal failed') + return realFreeze(value) + }) + const errors: unknown[] = [] + const requests: GenerateOptions[] = [] + ctx.on('agent/error', ({ error }) => { errors.push(error) }) + ctx.on('llm/stream', (request, next) => { requests.push(request); return next() }) + await send(agent, 'failed turn') + expect(errors).toEqual([new Error('freeze traversal failed')]) + expect(requests).toHaveLength(0) + await send(agent, 'retry turn') + expect(requests).toHaveLength(1) + expect(traversals).toBe(2) + expect(requests[0]!.messages[0]).toBe(message) + expectFrozen(requests[0]) + }) + + it.each([true, false])('freezes each local header with an adapter present: %s', async (registered) => { + const adapter = registered ? new MockAdapter([textResponse('one'), textResponse('two')]) : undefined + const ctx = await harness(adapter) + const schemas: ToolSchema[][] = [] + const stops: string[][] = [] + ctx.on('system-prompt/assemble', async (_assembly, _context, next) => { + const assembly = await next() + const tools: ToolSchema[] = [{ name: 'nested', description: 'test', parameters: { + type: 'object', properties: { value: { type: 'array', items: { type: 'string', enum: ['a', 'b'] } } }, + } }] + schemas.push(tools) + return { ...assembly, tools } + }) + ctx.on('agent/request', async (_payload, next) => { + const config = await next() + const stop = ['stop'] + stops.push(stop) + return { ...config, stop } + }) + const requests: GenerateOptions[] = [] + const errors: unknown[] = [] + ctx.on('agent/error', ({ error }) => { errors.push(error) }) + ctx.on('llm/stream', (request, next) => { + expect(isAgentLoopRequest(request)).toBe(true) + expectFrozen(request) + requests.push(request) + return registered ? next() : (async function* () { yield* textResponse('virtual') })() + }) + const agent = await ctx.agentLoop.create(SessionId('headers'), { provider: 'mock', model: 'mock' }) + await send(agent, 'first') + await send(agent, 'second') + expect(errors).toEqual([]) + expect(requests).toHaveLength(2) + for (const [index, request] of requests.entries()) { + expect(request.tools).toBe(schemas[index]) + expectFrozen(schemas[index]) + expect(() => request.stop!.push('mutate')).toThrow(TypeError) + if (!registered) expect(request.stop).toBe(stops[index]) + } + expect(agent.session.snapshotEvents().filter(event => event.type === 'request/header')).toHaveLength(1) + expect(agent.session.requestHeader()!.tools).not.toBe(requests[0]!.tools) + expect(agent.session.requestHeader()!.config.stop).not.toBe(requests[0]!.stop) + }) + + it('keeps the live request signal mutable and observes cancellation after dispatch', async () => { + const ctx = await harness(new MockAdapter(['hang'])) + const agent = await ctx.agentLoop.create(SessionId('cancel-freeze'), { provider: 'mock', model: 'mock' }) + const started = Promise.withResolvers() + ctx.on('llm/stream', (request, next) => { started.resolve(request); return next() }) + agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } })) + try { + const request = await started.promise + expect(Object.isFrozen(request)).toBe(true) + expect(Object.isFrozen(request.signal)).toBe(false) + expect(request.signal!.aborted).toBe(false) + const aborted = Promise.withResolvers() + request.signal!.addEventListener('abort', () => { aborted.resolve(undefined) }, { once: true }) + agent.cancel({ kind: 'user' }) + await aborted.promise + await agent.whenIdle() + expect(request.signal!.aborted).toBe(true) + expect(request.signal!.reason).toEqual({ kind: 'user' }) + expect(agent.session.snapshotEvents().at(-1)).toMatchObject({ + type: 'turn/end', data: { reason: { kind: 'aborted', reason: { kind: 'user' } } }, + }) + } finally { + agent.cancel({ kind: 'disposed' }) + await agent.whenIdle() + } + }) +}) diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 4ee42f7f55..0951aea6b1 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -2307,8 +2307,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: '@Remote(\'prompt\') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise', - description: 'Deliver one browser-authored message to a continuable child through the exact live direct parent, retaining the caller-minted request identity and validated browser zone on the accepted message. Success identifies the message the child\'s FIFO inbox accepted; later execution is independent of this call. Image parts are admitted and persisted through the attachment store before delivery, and the child\'s model must accept image input.', - parameters: [{ name: 'request', description: 'durable address, minted identity, content, and optional browser zone.' }, { name: 'signal', description: 'carrier cancellation, owning the call until inbox acceptance.' }], + description: 'Deliver one browser-authored message to a continuable child through the exact live direct parent, retaining the caller-minted request identity and validated browser zone on the accepted message. Success identifies the message the child\'s inbox accepted; later execution is independent of this call. Queue delivery targets a later turn; steer delivery targets the nearest step and retains the Agent loop\'s best-effort fallback semantics. Image parts are admitted and persisted through the attachment store before delivery, and the child\'s model must accept image input.', + parameters: [{ name: 'request', description: 'durable address, delivery, minted identity, content, and optional browser zone.' }, { name: 'signal', description: 'carrier cancellation, owning the call until inbox acceptance.' }], returns: 'the accepted message\'s inbox identity.', throws: ['{RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`, `subagent/invalid-time-zone`, `subagent/parent-unavailable`, `subagent/not-resumable`, `subagent/unauthorized`, `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.'], }, @@ -5631,7 +5631,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SubagentPromptRequest', - declaration: 'export interface SubagentPromptRequest {\n readonly requestId: SubagentPromptRequestId;\n readonly parentSessionId: SessionId;\n readonly childSessionId: SessionId;\n readonly mode: \'continuable\';\n readonly content: readonly PromptContentPart[];\n readonly clientTimeZone?: string;\n}', + declaration: 'export interface SubagentPromptRequest {\n readonly requestId: SubagentPromptRequestId;\n readonly parentSessionId: SessionId;\n readonly childSessionId: SessionId;\n readonly mode: \'continuable\';\n readonly delivery: \'queue\' | \'steer\';\n readonly content: readonly PromptContentPart[];\n readonly clientTimeZone?: string;\n}', }, { name: 'SubagentPromptRequestId', diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts index d3b5910909..ea81a53e69 100644 --- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts @@ -792,19 +792,17 @@ describe('JsonlSessionPersistence: immutable format generations', () => { readTally.enabled = true const controller = new AbortController() const reason = new Error('first historical waiter cancelled') - const secondController = new AbortController() - const firstListener = vi.spyOn(controller.signal, 'addEventListener') - const secondListener = vi.spyOn(secondController.signal, 'addEventListener') + const internals = ctx.sessionPersistence as unknown as { + migrationPreparations: Map + } const first = ctx.sessionPersistence.open(header.id, 'read', { signal: controller.signal }) - const second = ctx.sessionPersistence.open(header.id, 'read', { signal: secondController.signal }) + const second = ctx.sessionPersistence.open(header.id, 'read') + const settled = Promise.allSettled([first, second]) try { await pause.entered - // Both callers must be waiting on preparation, not still discovering the source. - await vi.waitFor(() => { - expect(firstListener).toHaveBeenCalledWith('abort', expect.any(Function), { once: true }) - expect(secondListener).toHaveBeenCalledWith('abort', expect.any(Function), { once: true }) - }) + // Both callers must join the preparation before either caller leaves it. + await expect.poll(() => internals.migrationPreparations.get(header.id)?.waiters).toBe(2) controller.abort(reason) await expect(first).rejects.toBe(reason) pause.release() @@ -812,9 +810,10 @@ describe('JsonlSessionPersistence: immutable format generations', () => { expect((await handle.read()).events).toEqual([]) expect(readTally.bySuffix.get(sourcePath)).toBe(1) } finally { + controller.abort(reason) pause.release() - for (const outcome of await Promise.allSettled([first, second])) { - if (outcome.status === 'fulfilled') await outcome.value.close() + for (const result of await settled) { + if (result.status === 'fulfilled') await result.value.close() } } }) diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index 0e0c61873f..c1085a6ff8 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import Loader from '@deepseek-ai/cordis-plugin-loader' import { chmodSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs' @@ -294,6 +294,57 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)', expectHostTermination(outcome, 'SIGKILL') }) + it('waits for observed tree exit after the EOF grace and termination request', async () => { + vi.useFakeTimers() + const exited = Promise.withResolvers() + const stdin = new PassThrough() + const calls: string[] = [] + const child: SubprocessHandle = { + pid: 123, + stdin, + stdout: undefined, + stderr: undefined, + collected: {}, + done: exited.promise.then(() => ({ exitCode: 1, signal: null })), + terminate: () => { calls.push('terminate') }, + waitForExit: (signal?: AbortSignal) => { + if (signal === undefined) { + calls.push('wait for exit') + return exited.promise + } + calls.push('wait for EOF') + return new Promise((resolve) => { + signal.addEventListener('abort', () => { resolve(false) }, { once: true }) + }) + }, + } + let disposal: Promise | undefined + try { + let disposed = false + disposal = disposeAcpChild(child, 150).then(() => { disposed = true }) + expect(stdin.writableEnded).toBe(true) + await vi.advanceTimersByTimeAsync(149) + expect(calls).toEqual(['wait for EOF']) + await vi.advanceTimersByTimeAsync(1) + expect(calls).toEqual(['wait for EOF', 'terminate', 'wait for exit']) + // Advancing the clock cannot stand in for the process owner's exit proof. + await vi.advanceTimersByTimeAsync(10_000) + expect(disposed).toBe(false) + exited.resolve(true) + await disposal + expect(disposed).toBe(true) + } finally { + exited.resolve(true) + try { + await vi.runAllTimersAsync() + await disposal + } finally { + stdin.destroy() + vi.useRealTimers() + } + } + }) + it('observes a spawn-level rejection and returns without a process to reap', async () => { const child = spawnSubprocess({ argv: [process.execPath, '--input-type=module', '--eval', ''], @@ -859,6 +910,8 @@ describe('dsh-subagent-acp', () => { const tmp = mkdtempSync(join(tmpdir(), 'acp-ignore-eof-')) const ready = join(tmp, 'ready') const sigterm = join(tmp, 'sigterm') + let child: SubprocessHandle | undefined + let run: Awaited> | undefined try { const spec: AcpRunSpec = { command: process.execPath, @@ -872,18 +925,32 @@ describe('dsh-subagent-acp', () => { // Tiny EOF grace so the ignored-EOF window elapses quickly. disposeEofGraceMs: 150, disposeGraceMs: 2000, - spawn: spawnSubprocess, + spawn: (spec) => { + child = spawnSubprocess(spec) + return child + }, } - const run = await startAcpRun(request(), spec) + run = await startAcpRun(request(), spec) await waitForFile(ready) - // Bound it so a hang fails loud rather than stalling the suite. - await expect(Promise.race([ - run.dispose(), - new Promise((_r, reject) => { setTimeout(() => { reject(new Error('dispose did not return')) }, 5000) }), - ])).resolves.toBeUndefined() + await run.dispose() + const outcome = await child!.done + expect(outcome.signal).toBeNull() + if (process.platform === 'win32') { + expect(outcome.exitCode).not.toBeNull() + expect(outcome.exitCode).not.toBe(0) + } else { + expect(outcome.exitCode).toBe(0) + } expect(existsSync(sigterm)).toBe(process.platform !== 'win32') } finally { - rmSync(tmp, { recursive: true, force: true }) + try { + await run?.dispose() + } finally { + child?.terminate() + await child?.waitForExit() + await child?.done + rmSync(tmp, { recursive: true, force: true }) + } } }) diff --git a/packages/subagent/subagent-codex/tests/real-product-cleanup.spec.ts b/packages/subagent/subagent-codex/tests/real-product-cleanup.spec.ts new file mode 100644 index 0000000000..a40bf336d4 --- /dev/null +++ b/packages/subagent/subagent-codex/tests/real-product-cleanup.spec.ts @@ -0,0 +1,157 @@ +import { existsSync, mkdtempSync, rmSync } from 'node:fs' +import { createServer } from 'node:http' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it, vi } from 'vitest' +import { cleanupRealProduct } from './real-product-cleanup.ts' + +it.each(['context', 'HTTP fixture'] as const)('attributes %s cleanup failures without losing the cause', async (stage) => { + const cause = new Error('fixture failure') + const fail = (): Promise => Promise.reject(cause) + await expect(cleanupRealProduct({ + contexts: stage === 'context' ? [{ fiber: { dispose: fail } }] : [], + fixtures: stage === 'HTTP fixture' ? [{ close: fail }] : [], + roots: [], + })).rejects.toMatchObject({ + message: stage === 'context' + ? 'Codex test context disposal failed' + : 'Codex test HTTP fixture closure failed', + cause, + }) +}) + +it('attributes root removal failures to the owned path', async () => { + const root = 'invalid\0root' + await expect(cleanupRealProduct({ contexts: [], fixtures: [], roots: [root] })) + .rejects.toMatchObject({ + message: `Codex test temporary root removal failed: ${root}`, + cause: { code: 'ERR_INVALID_ARG_VALUE' }, + }) +}) + +it('closes its real HTTP server and removes its root after context disposal rejects', async () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-codex-cleanup-rejected-')) + const server = createServer() + const close = (): Promise => new Promise((resolve, reject) => { + server.close((error) => { + if (error) reject(error) + else resolve() + }) + }) + try { + await new Promise((resolve, reject) => { + server.once('error', reject) + server.listen(0, '127.0.0.1', resolve) + }) + const cause = new Error('context disposal failed') + await expect(cleanupRealProduct({ + contexts: [{ fiber: { dispose: () => Promise.reject(cause) } }], + fixtures: [{ close }], + roots: [root], + })).rejects.toMatchObject({ cause }) + expect(server.listening).toBe(false) + expect(existsSync(root)).toBe(false) + } finally { + if (server.listening) await close() + rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) + } +}) + +it('removes sibling roots after an earlier root removal fails', async () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-codex-cleanup-sibling-')) + try { + await expect(cleanupRealProduct({ contexts: [], fixtures: [], roots: ['invalid\0root', root] })) + .rejects.toHaveProperty('cause.code', 'ERR_INVALID_ARG_VALUE') + expect(existsSync(root)).toBe(false) + } finally { + rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) + } +}) + +it.each(['context', 'HTTP fixture'] as const)('joins pending %s cleanup after a sibling rejects', async (stage) => { + const release = Promise.withResolvers() + const cause = new Error('sibling cleanup failed') + const fail = (): Promise => Promise.reject(cause) + const pending = (): Promise => release.promise + const laterFixture = vi.fn(async () => {}) + let settled = false + const cleanup = cleanupRealProduct({ + contexts: stage === 'context' ? [{ fiber: { dispose: fail } }, { fiber: { dispose: pending } }] : [], + fixtures: stage === 'context' ? [{ close: laterFixture }] : [{ close: fail }, { close: pending }], + roots: [], + }).catch((error: unknown) => { + settled = true + return error + }) + try { + await new Promise(resolve => setImmediate(resolve)) + expect(settled).toBe(false) + expect(laterFixture).not.toHaveBeenCalled() + release.resolve(undefined) + await expect(cleanup).resolves.toMatchObject({ cause }) + if (stage === 'context') expect(laterFixture).toHaveBeenCalledOnce() + } finally { + release.resolve(undefined) + await cleanup + } +}) + +it('reports failures from every cleanup stage together', async () => { + const contextCause = new Error('context failed') + const fixtureCause = new Error('fixture failed') + await expect(cleanupRealProduct({ + contexts: [{ fiber: { dispose: () => { throw contextCause } } }], + fixtures: [{ close: () => { throw fixtureCause } }], + roots: ['invalid\0root'], + })).rejects.toMatchObject({ + name: 'AggregateError', + errors: [ + { message: 'Codex test context disposal failed', cause: contextCause }, + { message: 'Codex test HTTP fixture closure failed', cause: fixtureCause }, + { cause: { code: 'ERR_INVALID_ARG_VALUE' } }, + ], + }) +}) + +it('keeps resources registered during pending cleanup for their own cleanup', async () => { + const oldRoot = mkdtempSync(join(tmpdir(), 'dsh-codex-cleanup-old-')) + const nextRoot = mkdtempSync(join(tmpdir(), 'dsh-codex-cleanup-next-')) + const releaseContext = Promise.withResolvers() + const oldContext = { fiber: { dispose: vi.fn(() => releaseContext.promise) } } + const nextContext = { fiber: { dispose: vi.fn(async () => {}) } } + const oldFixture = { close: vi.fn(async () => { + expect(existsSync(oldRoot)).toBe(true) + }) } + const nextFixture = { close: vi.fn(async () => {}) } + const resources: Parameters[0] = { + contexts: [oldContext], fixtures: [oldFixture], roots: [oldRoot], + } + const cleanup = cleanupRealProduct(resources) + try { + expect(oldContext.fiber.dispose).toHaveBeenCalledOnce() + expect(oldFixture.close).not.toHaveBeenCalled() + resources.contexts.push(nextContext) + resources.fixtures.push(nextFixture) + resources.roots.push(nextRoot) + releaseContext.resolve(undefined) + await cleanup + + expect(oldFixture.close).toHaveBeenCalledOnce() + expect(existsSync(oldRoot)).toBe(false) + expect(nextContext.fiber.dispose).not.toHaveBeenCalled() + expect(nextFixture.close).not.toHaveBeenCalled() + expect(existsSync(nextRoot)).toBe(true) + expect(resources).toEqual({ contexts: [nextContext], fixtures: [nextFixture], roots: [nextRoot] }) + + await cleanupRealProduct(resources) + expect(nextContext.fiber.dispose).toHaveBeenCalledOnce() + expect(nextFixture.close).toHaveBeenCalledOnce() + expect(existsSync(nextRoot)).toBe(false) + expect(resources).toEqual({ contexts: [], fixtures: [], roots: [] }) + } finally { + releaseContext.resolve(undefined) + await cleanup + rmSync(oldRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) + rmSync(nextRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) + } +}) diff --git a/packages/subagent/subagent-codex/tests/real-product-cleanup.ts b/packages/subagent/subagent-codex/tests/real-product-cleanup.ts new file mode 100644 index 0000000000..df45ccfbaf --- /dev/null +++ b/packages/subagent/subagent-codex/tests/real-product-cleanup.ts @@ -0,0 +1,43 @@ +import { rm } from 'node:fs/promises' +import type { Context } from '@deepseek-ai/cordis' +import type { ResponsesFixture } from './responses-fixture.ts' + +interface RealProductResources { + contexts: { fiber: Pick }[] + fixtures: Pick[] + roots: string[] +} + +/** + * Dispose Codex test contexts and HTTP fixtures before removing their files. + * Captures all registries before awaiting, so later tests retain their resources. + * Attempts every captured cleanup before reporting failures. + * @param resources - mutable registries of resources owned by the test. + */ +export async function cleanupRealProduct(resources: RealProductResources): Promise { + const contexts = resources.contexts.splice(0) + const fixtures = resources.fixtures.splice(0) + const roots = resources.roots.splice(0) + const failures: Error[] = [] + const contextOutcomes = await Promise.allSettled(contexts.map(async ctx => ctx.fiber.dispose())) + for (const outcome of contextOutcomes) { + if (outcome.status === 'rejected') { + failures.push(new Error('Codex test context disposal failed', { cause: outcome.reason })) + } + } + const fixtureOutcomes = await Promise.allSettled(fixtures.map(async fixture => fixture.close())) + for (const outcome of fixtureOutcomes) { + if (outcome.status === 'rejected') { + failures.push(new Error('Codex test HTTP fixture closure failed', { cause: outcome.reason })) + } + } + for (const root of roots) { + try { + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) + } catch (cause) { + failures.push(new Error(`Codex test temporary root removal failed: ${root}`, { cause })) + } + } + if (failures.length === 1) throw failures[0] + if (failures.length > 1) throw new AggregateError(failures, 'Codex test cleanup failed') +} diff --git a/packages/subagent/subagent-codex/tests/real-product.spec.ts b/packages/subagent/subagent-codex/tests/real-product.spec.ts index 120b0c5304..e21b384866 100644 --- a/packages/subagent/subagent-codex/tests/real-product.spec.ts +++ b/packages/subagent/subagent-codex/tests/real-product.spec.ts @@ -7,7 +7,6 @@ import { readFileSync, writeFileSync, } from 'node:fs' -import { rm } from 'node:fs/promises' import { createRequire } from 'node:module' import { tmpdir } from 'node:os' import { delimiter, dirname, join, resolve } from 'node:path' @@ -31,6 +30,7 @@ import { type ResponsesBehavior, type ResponsesFixture, } from './responses-fixture.ts' +import { cleanupRealProduct } from './real-product-cleanup.ts' const execFileAsync = promisify(execFile) const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url))) @@ -47,13 +47,7 @@ const roots: string[] = [] const fixtures: ResponsesFixture[] = [] const contexts: Context[] = [] -afterEach(async () => { - await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose())) - await Promise.all(fixtures.splice(0).map(fixture => fixture.close())) - for (const root of roots.splice(0)) { - await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) - } -}, 30_000) +afterEach(() => cleanupRealProduct({ contexts, fixtures, roots })) interface RealHarness { readonly ctx: Context diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml index 9f7ca0a2d5..90bc8ad8cb 100644 --- a/packages/subagent/subagent/README.i18n.yaml +++ b/packages/subagent/subagent/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/README.md -README.md: 9d99b27645e339de44d71c2df3f709fe28dc4f4b -README.zh.md: 9397c8ae92f7ff69c6ebbb3672a9e96247a816e1 +README.md: 60aea7d446acf2e01f46132ab03354bf17f74213 +README.zh.md: e46ee53436256afa5f0c8dd1c635cbd0f9585927 diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md index 9d99b27645..60aea7d446 100644 --- a/packages/subagent/subagent/README.md +++ b/packages/subagent/subagent/README.md @@ -48,7 +48,7 @@ One-shot children run once and settle with a single result, plus an optional str ### Messaging, interrupting, and discovering -Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Discovery covers both shapes: the service lists direct children and the full descendant tree — mode, activity, and lineage — reading live session state and optional persistence, without loading any child. +Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the Agent message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt independently selects Queue or Steer and may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Discovery covers both shapes: the service lists direct children and the full descendant tree — mode, activity, and lineage — reading live session state and optional persistence, without loading any child. ### Failure and recovery @@ -76,8 +76,11 @@ This section explains how the service is built and where the observable behavior | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Service entry: provider registry, start and continuation API, lifecycle events | -| [`src/continuation.ts`](src/continuation.ts) | Continuable children: identity reservation, Activation residency, adjacent messaging, interrupt, settlement | -| [`src/internal.ts`](src/internal.ts) | Host-only Queue and Steer adapters for browser and Team message protocols | +| [`src/continuation.ts`](src/continuation.ts) | Continuable orchestration: identity reservation, provider preparation, cold resume, authorization, routing | +| [`src/continuation-activation.ts`](src/continuation-activation.ts) | Process-local Activation graph, admission, settlement, and child-first disposal | +| [`src/continuation-messages.ts`](src/continuation-messages.ts) | Adjacent-Agent messages, return guidance, and settlement notices | +| [`src/internal.ts`](src/internal.ts) | Host-only Queue and Steer adapters plus standard adjacent-Agent messaging markers | +| [`src/inbox.ts`](src/inbox.ts) | Activation-local Queue and Steer admission plus the synchronous closing cutoff | | [`src/types.ts`](src/types.ts) | Public request, result, and provider contracts | | [`src/descriptor.ts`](src/descriptor.ts) | Versioned `subagent/descriptor` session-event vocabulary | | [`src/child-agent.ts`](src/child-agent.ts) | Child composition, delegated policy, depth helpers | @@ -91,7 +94,7 @@ A request is validated against the provider's advertised capabilities, a durable ### Continuable flow -The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; host protocols retain an internal Queue adapter for distinct turns. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream. +The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; browser human prompts choose Queue or best-effort Steer through an internal adapter, while other host protocols may retain Queue for distinct turns. A Session queue command admits a live subagent-owned Agent only from its own continuable descriptor. Settlement waits for Agent activity to finish, an empty Inbox, and no owned children, then flushes final Session state with admission open. Under the child lock, the manager revalidates the wake generation, Session sequence, Inbox, and owned children; the synchronous task entry of `Agent.runMaintenance()` claims the idle phase and closes the private subagent Inbox in the same JavaScript turn before handle disposal. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream. ### Ownership and invariants @@ -163,9 +166,10 @@ Prefix-stable within a child: the statement never changes during the child's lif These limits define when the seam is a poor fit or needs special operational care. They are current package constraints, not a general delegation comparison or a task backlog. - **ACP children remain one-shot and are not trace-enumerable** — an ACP run has no local child session in the parent's session corpus, and remote providers need an Activation ownership contract before they can support continuable children. -- **Adjacent model messaging only** — `sendMessage()` requires an exact live sender; every sender may target a direct continuable child, while only a sender with a resident continuable Activation may target its direct parent. Browser prompts use the separate Queue control path. +- **Adjacent model messaging only** — `sendMessage()` requires an exact live sender; every sender may target a direct continuable child, while only a sender with a resident continuable Activation may target its direct parent. Browser prompts use a separate human Queue-or-Steer control path. - **A direct parent must remain live for child-to-parent delivery** — the service has no durable parent mailbox; a missing parent rejects the message instead of accepting work it cannot wake. - **Wake gap during cancellation convergence** — a follow-up accepted after an interrupt signal but before the driver becomes idle stays queued until another waking send. +- **Pending injected context retains an Activation** — settlement conservatively treats every Inbox occurrence as unfinished. Context parked after the Agent becomes idle keeps the child and its live ancestors resident until a waking delivery claims it, a queue mutation removes it, or manager teardown discards it. - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store needs a durable mailbox and cross-process lease protocol. - **No replay of accepted-but-unlogged messages** — a crash can lose an accepted prompt that never reached the child's session log; the lost message is not replayed automatically. - **No durable parent mailbox** — child-to-parent messages require a resident continuable child and live direct parent, and provide acceptance identity rather than exactly-once delivery. diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md index 9397c8ae92..e46ee53436 100644 --- a/packages/subagent/subagent/README.zh.md +++ b/packages/subagent/subagent/README.zh.md @@ -48,7 +48,7 @@ kind: "package-reference" ### 消息、中断与发现 -每个确切在线 Agent 都可以对直接可继续 child 使用 `sendMessage()`；驻留的可继续 child 还可以对自己的直接 parent 使用它。正在工作的目标通过 Steer 在最近 step 接收消息；空闲目标启动轮次，且只有直接 child 可以冷恢复。parent 也可以随时中断正在运行的后代或列举自己的子级。浏览器发出的继续执行 prompt 可以携带图片部分：Host 先通过附件存储完成整批图片的准入与持久化，子级 inbox 才接受这条消息；当子级声明的模型不接受图片输入时拒绝投递。发现覆盖两种形态：服务列举直接子级与完整后代树——模式、活动状态与血缘——直接读取在线会话状态与可选持久化，不加载任何子 agent。 +每个确切在线 Agent 都可以对直接可继续 child 使用 `sendMessage()`；驻留的可继续 child 还可以对自己的直接 parent 使用它。正在工作的目标通过 Steer 在最近 step 接收 Agent 消息；空闲目标启动轮次，且只有直接 child 可以冷恢复。parent 也可以随时中断正在运行的后代或列举自己的子级。浏览器发出的继续执行 prompt 会独立选择 Queue 或 Steer，并且可以携带图片部分：Host 先通过附件存储完成整批图片的准入与持久化，子级 inbox 才接受这条消息；当子级声明的模型不接受图片输入时拒绝投递。发现覆盖两种形态：服务列举直接子级与完整后代树——模式、活动状态与血缘——直接读取在线会话状态与可选持久化，不加载任何子 agent。 ### 失败与恢复 @@ -76,8 +76,11 @@ kind: "package-reference" | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 服务入口：提供方注册表、启动与继续 API、生命周期事件 | -| [`src/continuation.ts`](src/continuation.ts) | 可继续子级：身份预留、Activation 驻留、相邻消息、中断、结算 | -| [`src/internal.ts`](src/internal.ts) | 供浏览器与 Team 消息协议使用的 host-only Queue 与 Steer 适配器 | +| [`src/continuation.ts`](src/continuation.ts) | 可继续子级编排：身份预留、提供方准备、冷恢复、授权与路由 | +| [`src/continuation-activation.ts`](src/continuation-activation.ts) | 进程内 Activation 图、准入、结算与子级优先释放 | +| [`src/continuation-messages.ts`](src/continuation-messages.ts) | 相邻 Agent 消息、返回指引与结算通知 | +| [`src/internal.ts`](src/internal.ts) | Host 专用 Queue 与 Steer 适配器，以及标准相邻 Agent 消息标记 | +| [`src/inbox.ts`](src/inbox.ts) | Activation 局部的 Queue 和 Steer 准入，以及同步 closing cutoff | | [`src/types.ts`](src/types.ts) | 公开的请求、结果与提供方约定 | | [`src/descriptor.ts`](src/descriptor.ts) | 版本化的 `subagent/descriptor` 会话事件词汇 | | [`src/child-agent.ts`](src/child-agent.ts) | 子级组装、委派策略、深度辅助函数 | @@ -91,7 +94,7 @@ kind: "package-reference" ### 可继续流程 -管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；host 协议保留内部 Queue 适配器以创建独立轮次。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。 +管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；浏览器人类 prompt 通过内部适配器选择 Queue 或 best-effort Steer，其他 host 协议仍可保留 Queue 以创建独立轮次。Session queue command 仅根据 child 自身的 continuable descriptor 准入在线 subagent-owned Agent。Settlement 会等待 Agent 活动结束、Inbox 为空且没有所拥有子级，再在准入开放时 flush 最终 Session 状态。管理器随后在 child lock 内重新验证 wake generation、Session 序号、Inbox 与所拥有子级；`Agent.runMaintenance()` 的同步 task 入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭私有 subagent Inbox，然后才 dispose handle。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。 ### 所有权与不变式 @@ -163,9 +166,10 @@ You are a delegated subagent: your permission scope was fixed when you were star 这些限制说明该 seam 何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用委派对比或任务积压。 - **ACP 子级仍为一次性，且无法通过追踪枚举**——ACP 运行在父级会话语料中没有本地子会话，远程提供方需要 Activation 所有权约定才能支持可继续子级。 -- **仅允许相邻模型消息**——`sendMessage()` 要求确切在线 sender；每个 sender 都可以指定直接可继续 child，只有具备驻留可继续 Activation 的 sender 可以指定自己的直接 parent。浏览器提示使用独立的 Queue 控制路径。 +- **仅允许相邻模型消息**——`sendMessage()` 要求确切在线 sender；每个 sender 都可以指定直接可继续 child，只有具备驻留可继续 Activation 的 sender 可以指定自己的直接 parent。浏览器提示使用独立的人类 Queue 或 Steer 控制路径。 - **child 到 parent 的投递要求直接 parent 保持在线**——服务没有持久 parent mailbox；parent 缺失时会拒绝消息，而非接受无法唤醒的工作。 - **取消收敛期间存在唤醒缺口**——中断信号发出后、driver 进入 idle 前被接受的后续消息会保持排队，直到另一条唤醒发送到达。 +- **待处理的注入 context 会保留 Activation**——settlement 会保守地把每个 Inbox occurrence 都视为未完成。Agent 进入 idle 后停放的 context 会让 child 及其在线祖先继续驻留，直到唤醒投递将其 claim、queue 变更将其移除，或 manager teardown 将其丢弃。 - **驻留仅限进程内**——Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问需要持久化邮箱与跨进程租约协议。 - **不回放已接受但未记录的消息**——崩溃可能丢失从未写入子会话日志、已被接受的提示词；丢失的消息不会自动回放。 - **没有持久化 parent mailbox**——child 到 parent 的消息要求驻留的可继续 child 与在线直接 parent，提供的是接受标识，不保证恰好一次投递。 diff --git a/packages/subagent/subagent/src/continuation-activation.ts b/packages/subagent/subagent/src/continuation-activation.ts new file mode 100644 index 0000000000..782332b3d9 --- /dev/null +++ b/packages/subagent/subagent/src/continuation-activation.ts @@ -0,0 +1,854 @@ +/** + * Process-local Activation ownership for continuable subagents: admission, + * parent-child residency, serialized delivery, settlement, and disposal. + * + * The continuation manager owns durable request orchestration and delegates + * every mutable residency decision to this registry, so delivery and teardown + * share one child lock and one Activation map. + * + * @module @deepseek-ai/dsh-subagent/continuation-activation + */ + +import type { Context } from '@deepseek-ai/cordis' +import type { + Agent, + AgentHandle, + AgentOptions, + CreateAgentOptions, +} from '@deepseek-ai/dsh-agent' +import { errorChain } from '@deepseek-ai/dsh-llm' +import type { MessageId } from '@deepseek-ai/dsh-llm' +import type { + SessionEvent, + SessionId, + SessionLogOffset as SessionLogOffsetType, + UserMessage, +} from '@deepseek-ai/dsh-session' +import type { ToolRestriction } from '@deepseek-ai/dsh-tools' +import { + appendDelegatedPolicyOverrides, + applyChildComposition, +} from './child-agent.ts' +import type { DelegatedPolicyOverrides } from './child-agent.ts' +import { createSettlementMessage } from './continuation-messages.ts' +import type { SubagentDescriptorData } from './descriptor.ts' +import { SubagentError } from './error.ts' +import { SubagentInbox } from './inbox.ts' +import type { SubagentDelivery } from './inbox.ts' +import type { ActivationObserver, ActivationTerminal } from './lifecycle.ts' + +/** + * One residency epoch for a reconstructed continuable child Agent. It directly + * owns the published `AgentHandle`; the registry's private activation-owner + * scope is its structural Cordis owner. + */ +export interface Activation { + /** The durable child this Activation is an epoch of. */ + readonly childId: SessionId + /** + * The durable direct parent, stored because settlement delivery must resolve + * that parent after the child handle is gone. {@link ancestry} cannot answer + * it: a `WeakSet` is not enumerable, and the child's own header is only + * reachable through a handle disposal has already released. + */ + readonly parentSession: SessionId + /** The provider name recorded in the durable descriptor. */ + readonly provider: string + /** The retained live Agent handle, disposed exactly once at settlement. */ + readonly handle: AgentHandle + /** The Activation-local admission and close wrapper around the handle's Agent inbox. */ + readonly inbox: SubagentInbox + /** + * Exact live Agent ancestry observed when this Activation materialized. + * Weak membership preserves host-scope identity across an intermediate + * ancestor leaving the registry without retaining that ancestor's runtime. + */ + readonly ancestry: WeakSet + /** + * Session ids of the child Activations this one owns. Because one Session has + * at most one live Activation, the id identifies the live child without + * another runtime-incarnation reference. Non-empty blocks settlement. + */ + readonly ownedChildren: Set + /** The lifecycle observer that emits this epoch's start and terminal edges. */ + readonly observer: ActivationObserver + /** + * Whether any delivery to this child was ever accepted. A materialization + * rolled back before its first acceptance is a child the caller was told does + * not exist, so its teardown owes the parent no settlement account. + */ + announced: boolean + /** Renewed whenever a settlement watcher must re-check residency state. */ + poke: PromiseWithResolvers +} + +/** Inputs shared by fresh and resumed Activation materialization. */ +export interface MaterializeInputs { + childId: SessionId + provider: string + parent: Agent + /** + * Creation inputs; absent for a cold resume, which loads the persisted + * session — including the delegation policy events a fresh creation seeded, + * so a resume never re-captures the parent's policy. + */ + create?: { + seed: readonly SessionEvent[] | undefined + meta: NonNullable + /** Exact parent-log prefix length inside {@link seed}. */ + inheritedEventCount: SessionLogOffsetType + /** Policy captured at delegation: the parent's sandbox override plus the approval pin. */ + delegatedPolicies: DelegatedPolicyOverrides + /** Child-owned composition record appended after the inherited marker. */ + descriptor: SubagentDescriptorData + } + agentOptions: AgentOptions + composition: { persona?: string | undefined; toolFilter?: ToolRestriction | undefined } + signal: AbortSignal +} + +/** + * One admitted materialization and the exact live ancestry observed at its + * synchronous admission point. Retaining identities lets a scoped teardown + * keep waiting even if an intermediate Agent leaves the registry meanwhile. + */ +interface Materialization { + readonly lineage: readonly Agent[] + readonly settled: Promise +} + +/** Residency state observed by the natural-settlement watcher. */ +type SettlementState = 'closed' | 'retry' | 'wait' | 'ready' + +/** Result of the final child-lock settlement decision. */ +type SettlementAttempt = + | Exclude + | { readonly done: Promise } + +/** Serialize each durable child's delivery, release, and disposal. */ +export class ChildLock { + private tails = new Map>() + + /** + * Run `operation` after every previously queued operation for `childId`. + * @param childId - the durable child whose operations are linearized. + * @param operation - the critical section to run in order. + * @returns the operation's own settlement. + */ + run(childId: SessionId, operation: () => Promise): Promise { + const previous = this.tails.get(childId) ?? Promise.resolve() + const result = previous.then(operation, operation) + // Absorb rejections in the chaining tail so one failed critical section + // cannot reject an unrelated later caller. + const tail = result.then(() => undefined, () => undefined) + this.tails.set(childId, tail) + void tail.then(() => { + if (this.tails.get(childId) === tail) this.tails.delete(childId) + }) + return result + } +} + +/** Own the complete process-local lifetime of continuable child Activations. */ +export class ContinuableActivationRegistry { + /** Child session id → its live Activation. Process-local, never durable. */ + private readonly resident = new Map() + /** Materializations admitted before drain, tracked through publication or rollback. */ + private readonly materializations = new Set() + /** Per-child serializer shared by delivery, release, and disposal. */ + readonly locks = new ChildLock() + /** Structural Cordis owner of every Activation handle. */ + readonly ownerCtx: Context + /** + * Exact roots whose host teardown has begun, with the live lineage members + * observed under each root. Entries remain until that exact root leaves the + * Agent registry, closing admission throughout its host's teardown without + * poisoning a later same-id replacement. + */ + private readonly closingScopes = new Map>() + private draining = false + + /** + * Build one registry inside the service's Agent-injected context. + * @param ctx - context providing Agents, Sessions, and teardown ownership. + * @param observeActivation - build the lifecycle observer for one residency epoch. + */ + constructor( + private readonly ctx: Context, + private readonly observeActivation: ( + provider: string, + childId: SessionId, + parent: Agent, + ) => ActivationObserver, + ) { + // Ordinary Cordis owner effects unwind in reverse registration order, which + // cannot express the dynamic child graph. Register the private scope's + // structural disposer FIRST and the drain SECOND, so reverse unwind invokes + // the drain before releasing the scope; a cleanup effect on the same scope + // as the Agent handles would let structural handle disposal bypass + // child-first ordering. + const scope = ctx.plugin(function activationOwner() {}) + this.ownerCtx = scope.ctx + ctx.on('agent/disposed', ({ agent }) => { + this.closingScopes.delete(agent) + }) + ctx.effect(function* (this: ContinuableActivationRegistry) { + yield scope.dispose + yield () => this.drain() + }.bind(this), 'subagents.continuations()') + } + + /** + * Return the live Activation for a durable child id, if resident. + * @param childId - durable child session id to look up. + * @returns the process-local Activation, or `undefined` when it is not resident. + */ + get(childId: SessionId): Activation | undefined { + return this.resident.get(childId) + } + + /** + * Reject one child identity already owned by a live Agent or Session. + * @param childId - proposed durable child session id. + */ + assertChildIdAvailable(childId: SessionId): void { + if (this.ctx.agents.get(childId) !== undefined || this.ctx.get('sessions')?.get(childId) !== undefined) { + throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD') + } + } + + /** + * Pre-register `childId` in a continuation-managed parent's owned set so the + * parent cannot settle while a caller is still establishing or resuming that + * child. Returns a releaser for the failure path; it removes only a hold + * this call added, and leaves ownership in place once a live Activation for + * the child exists. + * @param parent - the live direct parent the operation is admitted under. + * @param childId - the durable child the operation addresses. + * @returns the failure-path releaser; a no-op when nothing was added. + */ + holdOwnership(parent: Agent, childId: SessionId): () => void { + const parentActivation = this.resident.get(parent.id) + if (parentActivation === undefined || parentActivation.handle.agent !== parent) return () => {} + if (parentActivation.inbox.closing !== undefined) { + throw new SubagentError( + `subagent parent "${parent.id}" is being disposed; the child was not established`, + 'ACTIVATION_CLOSING', + ) + } + if (parentActivation.ownedChildren.has(childId)) return () => {} + parentActivation.ownedChildren.add(childId) + return () => { + const live = this.resident.get(childId) + /* v8 ignore next 4 -- reaching this arm needs another delivery to establish the child + * between this operation's failure and its releaser running, which no test can schedule + * deterministically: the ownership edge then belongs to that live Activation, so the + * conservative keep leaves it for finishDisposal's releaseOwnership. */ + if (live !== undefined && live.inbox.closing === undefined) return + if (parentActivation.ownedChildren.delete(childId)) this.wake(parentActivation) + } + } + + /** + * Interrupt one live continuable child's current turn under the supplied authority. + * @param targetSessionId - the durable child session id to interrupt. + * @param authority - the human parent address or exact live ancestor Agent. + */ + interrupt( + targetSessionId: SessionId, + authority: + | { readonly kind: 'user'; readonly parentSessionId: SessionId } + | { readonly kind: 'ancestor'; readonly agent: Agent }, + ): void { + if (authority.kind === 'ancestor') { + const caller = authority.agent + if (this.ctx.agents.get(caller.id) !== caller) { + throw new SubagentError( + `interrupting "${targetSessionId}" requires the exact live ancestor agent`, + 'UNAUTHORIZED', + ) + } + if (caller.id === targetSessionId) { + throw new SubagentError( + `agent "${caller.id}" cannot interrupt itself`, + 'UNAUTHORIZED', + ) + } + } + const activation = this.resident.get(targetSessionId) + if (activation === undefined) return + if (authority.kind === 'user') { + if (activation.handle.agent.session.header.parentSession !== authority.parentSessionId) { + throw new SubagentError( + `subagent "${targetSessionId}" belongs to another parent session`, + 'UNAUTHORIZED', + ) + } + } else if (!activation.ancestry.has(authority.agent)) { + throw new SubagentError( + `subagent "${targetSessionId}" is not a live descendant of agent "${authority.agent.id}"`, + 'UNAUTHORIZED', + ) + } + // Disposal already stopped the target with a whole-Activation teardown; + // a second cancel would be a redundant signal on a closing handle. + if (activation.inbox.closing !== undefined) return + activation.handle.agent.cancel( + authority.kind === 'user' ? { kind: 'user' } : { kind: 'parent' }, + { keepInbox: true }, + ) + } + + /** + * Send through a receiving parent's Activation inbox when it has one. + * @param parent - exact live Agent receiving the message. + * @param message - durable user message to deliver. + * @param delivery - receiving inbox destination. + */ + sendWaking(parent: Agent, message: UserMessage, delivery: SubagentDelivery): void { + const parentActivation = this.resident.get(parent.id) + if (parentActivation !== undefined && parentActivation.handle.agent === parent) { + try { + parentActivation.inbox.deliver(message, delivery) + } finally { + this.wake(parentActivation) + } + return + } + if (delivery === 'steer') parent.steer(message) + else parent.followup(message) + } + + /** + * Close admission, await every already-admitted materialization through + * publication or rollback, then dispose the stable live Activation graph + * child-first. + */ + async drain(): Promise { + this.draining = true + await Promise.all([...this.materializations].map(materialization => materialization.settled)) + const owned = new Set() + for (const activation of this.resident.values()) { + for (const child of activation.ownedChildren) owned.add(child) + } + const roots = [...this.resident.values()].filter(activation => !owned.has(activation.childId)) + await this.disposeRoots(roots, 'activation(s)') + } + + /** + * Stop only the continuable descendants of exact live host-owned parents. + * @param parents - exact live roots whose continuable descendants must stop. + */ + async drainDescendants(parents: readonly Agent[]): Promise { + const roots = new Set(parents.filter(parent => this.ctx.agents.get(parent.id) === parent)) + if (roots.size === 0) return + + for (const root of roots) { + this.closingMembers(root).add(root) + } + + const targets: Activation[] = [] + for (const activation of this.resident.values()) { + const lineage = this.liveLineage(activation.handle.agent) + const owners = [...roots].filter(root => activation.handle.agent !== root + && activation.ancestry.has(root)) + if (owners.length === 0) continue + targets.push(activation) + for (const owner of owners) { + const members = this.closingMembers(owner) + members.add(activation.handle.agent) + for (const agent of lineage) members.add(agent) + } + } + const materializations = [...this.materializations].filter((materialization) => { + const owners = [...roots].filter(root => materialization.lineage.includes(root)) + for (const owner of owners) { + const members = this.closingMembers(owner) + for (const agent of materialization.lineage) members.add(agent) + } + return owners.length > 0 + }) + + const ownedTargets = new Set() + for (const activation of targets) { + for (const child of activation.ownedChildren) ownedTargets.add(child) + } + const targetRoots = targets.filter(activation => !ownedTargets.has(activation.childId)) + + for (const activation of targets) { + const disposal = this.dispose(activation) + void disposal.catch(() => undefined) + } + + await Promise.all(materializations.map(materialization => materialization.settled)) + await this.disposeRoots(targetRoots, 'scoped activation(s)') + } + + /** + * Release selected resident direct children of one exact live parent. + * @param parent - exact live direct parent authorizing the selected release. + * @param childIds - durable direct-child ids to release when resident. + */ + async drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise { + if (this.ctx.agents.get(parent.id) !== parent) { + throw new SubagentError('selected child teardown requires the exact live parent agent', 'UNAUTHORIZED') + } + const targets: Activation[] = [] + for (const childId of new Set(childIds)) { + const activation = this.resident.get(childId) + if (activation === undefined) continue + if (activation.parentSession !== parent.id || !activation.ancestry.has(parent)) { + throw new SubagentError( + `subagent "${childId}" is not a direct child of agent "${parent.id}"`, + 'UNAUTHORIZED', + ) + } + targets.push(activation) + } + + for (const activation of targets) { + const disposal = this.dispose(activation) + void disposal.catch(() => undefined) + } + await this.disposeRoots(targets, 'selected activation(s)') + } + + /** + * Reject new admission once the registry or this exact parent tree began draining. + * @param agent - exact live Agent whose lineage determines admission. + */ + assertAdmitting(agent: Agent): void { + const closing = this.closingTeardownFor(agent) + if (closing === undefined) return + throw new SubagentError( + closing === 'manager' + ? 'continuable subagents are draining; the operation was not admitted' + : `continuable subagents below parent "${closing.id}" are draining; the operation was not admitted`, + 'DRAINING', + ) + } + + /** + * Authorize one operation against the durable direct-parent lineage. + * @param parent - exact live Agent claiming direct-parent authority. + * @param childId - durable child session id addressed by the operation. + * @param parentSession - durable direct-parent id recorded by the child. + */ + authorizeLineage( + parent: Agent, + childId: SessionId, + parentSession: SessionId | undefined, + ): void { + if (this.ctx.agents.get(parent.id) !== parent) { + throw new SubagentError( + `subagent "${childId}" delivery requires the exact live parent agent`, + 'UNAUTHORIZED', + ) + } + if (parentSession !== parent.id) { + throw new SubagentError(`subagent "${childId}" belongs to another parent session`, 'UNAUTHORIZED') + } + } + + /** + * Create or resume one child Agent and publish its Activation. + * @param inputs - reconstruction and admission inputs for the residency epoch. + * @returns the published process-local Activation. + */ + materialize(inputs: MaterializeInputs): Promise { + this.assertAdmitting(inputs.parent) + const settled = Promise.withResolvers() + const lineage = this.liveLineage(inputs.parent) + const materialization: Materialization = { + lineage, + settled: settled.promise, + } + this.materializations.add(materialization) + return this.materializeTracked(inputs, lineage).finally(() => { + this.materializations.delete(materialization) + settled.resolve() + }) + } + + /** + * Cross the final admission cutoff and submit without yielding. + * @param activation - the exact resident child receiving the message. + * @param message - the already-built durable user message. + * @param delivery - the Agent inbox destination. + * @param parent - exact live direct parent authorizing admission. + * @param signal - caller cancellation before inbox acceptance. + * @returns the accepted durable message id. + */ + submitAdmitted( + activation: Activation, + message: UserMessage, + delivery: SubagentDelivery, + parent: Agent, + signal: AbortSignal, + ): MessageId { + signal.throwIfAborted() + this.assertAdmitting(parent) + this.authorizeLineage( + parent, + activation.childId, + activation.handle.agent.session.header.parentSession, + ) + this.acquireOwnership(parent, activation.childId) + try { + activation.inbox.deliver(message, delivery) + } finally { + this.wake(activation) + } + activation.announced = true + return message.id + } + + /** + * Stop and release one Activation through its memoized close transaction. + * @param activation - exact residency epoch to close. + * @param finalStateFlushed - whether natural settlement already flushed final state. + * @returns the shared close transaction. + */ + dispose(activation: Activation, finalStateFlushed = false): Promise { + return activation.inbox.close(() => this.finishDisposal(activation, finalStateFlushed)) + } + + /** Dispose independent roots and report every branch failure after all settle. */ + private async disposeRoots( + roots: readonly Activation[], + failureSubject: 'activation(s)' | 'scoped activation(s)' | 'selected activation(s)', + ): Promise { + const failures = await Promise.all(roots.map(async (activation) => { + try { + await this.dispose(activation) + return undefined + } catch (error: unknown) { + return error + } + })) + const reasons = failures.filter(failure => failure !== undefined) + if (reasons.length > 0) { + throw new SubagentError( + `continuable subagent teardown failed for ${reasons.length} ${failureSubject}: ` + + reasons.map(reason => errorChain(reason)).join('; '), + 'ACTIVATION_TEARDOWN_FAILED', + ) + } + } + + /** Return the retained member set for one exact scoped-teardown root. */ + private closingMembers(root: Agent): Set { + const existing = this.closingScopes.get(root) + if (existing !== undefined) return existing + const members = new Set() + this.closingScopes.set(root, members) + return members + } + + /** Return the exact currently resolvable ancestry from `agent` upward. */ + private liveLineage(agent: Agent): Agent[] { + const lineage = [agent] + const seen = new Set([agent.id]) + let parentSession = agent.session.header.parentSession + while (parentSession !== undefined) { + const parent = this.ctx.agents.get(parentSession) + if (parent === undefined || seen.has(parent.id)) break + lineage.push(parent) + seen.add(parent.id) + parentSession = parent.session.header.parentSession + } + return lineage + } + + /** Return the teardown that closed continuable admission for this agent's lineage. */ + private closingTeardownFor(agent: Agent): Agent | 'manager' | undefined { + if (this.draining) return 'manager' + const lineage = this.liveLineage(agent) + for (const [root, members] of this.closingScopes) { + if (members.has(agent) || lineage.includes(root)) return root + } + return undefined + } + + /** Perform one tracked materialization through publication or rollback. */ + private async materializeTracked( + inputs: MaterializeInputs, + parentLineage: readonly Agent[], + ): Promise { + const { childId, provider, parent, create } = inputs + inputs.signal.throwIfAborted() + const setup = (childCtx: Context): void => { + const child = childCtx.agent as Agent + // Only fresh creation appends the descriptor and delegated policy after + // the inherited marker; a cold resume replays those persisted events. + if (create !== undefined) { + child.session.append('subagent/descriptor', create.descriptor) + appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies) + } + applyChildComposition(childCtx, parent, inputs.composition) + } + const observer = this.observeActivation(provider, childId, parent) + const handle: AgentHandle = create === undefined + ? await this.ownerCtx.agents.resume({ + resumeSessionId: childId, + agentOptions: inputs.agentOptions, + signal: inputs.signal, + setup, + }) + : await this.ownerCtx.agents.create({ + sessionId: childId, + meta: create.meta, + ...(create.seed === undefined ? {} : { seed: create.seed }), + inheritedEventCount: create.inheritedEventCount, + agentOptions: inputs.agentOptions, + signal: inputs.signal, + setup, + }) + + const activation: Activation = { + childId, + parentSession: parent.id, + provider, + handle, + inbox: new SubagentInbox(handle.agent), + ancestry: new WeakSet([handle.agent, ...parentLineage]), + ownedChildren: new Set(), + observer, + announced: false, + poke: Promise.withResolvers(), + } + this.resident.set(childId, activation) + try { + inputs.signal.throwIfAborted() + this.assertAdmitting(parent) + this.acquireOwnership(parent, childId) + const wakeOnInboxRemoval = (): void => { this.wake(activation) } + handle.agent.ctx.on('agent/inbox/claimed', wakeOnInboxRemoval) + handle.agent.ctx.on('agent/inbox/discarded', wakeOnInboxRemoval) + observer.start(handle.agent) + } catch (error: unknown) { + /* v8 ignore next -- rollback failure must not mask the admission failure + * that prevented this operation from returning an accepted message id. */ + await this.rollbackUnpublished(activation).catch(() => undefined) + throw error + } + this.watchSettlement(activation) + return activation + } + + /** Release an Activation whose start edge was not published. */ + private rollbackUnpublished(activation: Activation): Promise { + return activation.inbox.close(async () => { + try { + await activation.handle.dispose() + } finally { + this.resident.delete(activation.childId) + this.releaseOwnership(activation.childId) + } + }) + } + + /** Register the child in a continuation-managed parent's owned set. */ + private acquireOwnership(parent: Agent, childId: SessionId): void { + const parentActivation = this.resident.get(parent.id) + if (parentActivation === undefined) return + if (parentActivation.inbox.closing !== undefined) { + throw new SubagentError( + `subagent parent "${parent.id}" is being disposed; the child was not established`, + 'ACTIVATION_CLOSING', + ) + } + parentActivation.ownedChildren.add(childId) + } + + /** Remove one child from its live owner's set and let that owner re-check settlement. */ + private releaseOwnership(childId: SessionId): void { + for (const candidate of this.resident.values()) { + if (candidate.ownedChildren.delete(childId)) this.wake(candidate) + } + } + + /** Let a settlement watcher re-check residency after relevant state changes. */ + private wake(activation: Activation): void { + activation.poke.resolve() + activation.poke = Promise.withResolvers() + } + + /** Follow one Activation to natural settlement. */ + private watchSettlement(activation: Activation): void { + void (async () => { + while (true) { + const idleObservation = activation.poke + await activation.handle.agent.whenIdle() + if (activation.inbox.closing !== undefined) return + const readiness = await this.locks.run(activation.childId, () => Promise.resolve( + this.settlementState(activation, idleObservation), + )) + if (readiness === 'closed') return + if (readiness === 'retry') continue + if (readiness === 'wait') { + await idleObservation.promise + continue + } + + const finalSeq = activation.handle.agent.session.seq + await this.flushFinalState(activation) + const attempt = await this.locks.run(activation.childId, () => { + const state = this.settlementState(activation, idleObservation) + if (state !== 'ready') return Promise.resolve(state) + if (activation.handle.agent.session.seq !== finalSeq) { + return Promise.resolve('retry') + } + // The task starts synchronously, so idle ownership and Inbox closure share one turn. + let done!: Promise + try { + void activation.handle.agent.runMaintenance(() => { + done = this.dispose(activation, true) + return Promise.resolve() + }) + } catch { + // Another activity won the idle phase after the preceding observation. + return Promise.resolve('retry') + } + return Promise.resolve({ done }) + }) + + if (attempt === 'closed') return + if (attempt === 'retry') continue + if (attempt === 'wait') { + await idleObservation.promise + continue + } + try { + await attempt.done + } catch (error: unknown) { + this.ctx.logger.warn( + `subagent "${activation.childId}" activation teardown failed: ${errorChain(error)}`, + ) + } + return + } + })() + } + + /** Classify one Inbox and owned-child observation without reading Agent execution state. */ + private settlementState( + activation: Activation, + observation: PromiseWithResolvers, + ): SettlementState { + if (activation.inbox.closing !== undefined) return 'closed' + if (activation.poke !== observation) return 'retry' + if (activation.inbox.hasPending || activation.ownedChildren.size > 0) return 'wait' + return 'ready' + } + + /** Propagate stop synchronously, then finish the child-first release. */ + private async finishDisposal(activation: Activation, finalStateFlushed: boolean): Promise { + this.wake(activation) + const { childId } = activation + const failures: SubagentError[] = [] + if (finalStateFlushed) { + try { + activation.observer.capture(activation.handle.agent) + } catch (error: unknown) { + failures.push(new SubagentError( + `subagent "${childId}" activation teardown failed: ${errorChain(error)}`, + 'ACTIVATION_TEARDOWN_FAILED', + { cause: error }, + )) + } + } else { + activation.handle.agent.cancel({ kind: 'parent' }) + const idle = activation.handle.agent.whenIdle() + const children = [...activation.ownedChildren] + .map(child => this.resident.get(child)) + .filter((child): child is Activation => child !== undefined) + const childDisposals = children.map(child => this.dispose(child)) + try { + const childFailures = await Promise.all(childDisposals.map(async (disposal) => { + try { + await disposal + return undefined + } catch (error: unknown) { + return error + } + })) + const reasons = childFailures.filter(reason => reason !== undefined) + if (reasons.length > 0) { + failures.push(new SubagentError( + `subagent "${childId}" child teardown failed: ${reasons.map(reason => errorChain(reason)).join('; ')}`, + 'ACTIVATION_TEARDOWN_FAILED', + )) + } + await idle + await this.flushFinalState(activation) + activation.observer.capture(activation.handle.agent) + } catch (error: unknown) { + failures.push(new SubagentError( + `subagent "${childId}" activation teardown failed: ${errorChain(error)}`, + 'ACTIVATION_TEARDOWN_FAILED', + { cause: error }, + )) + } + } + try { + await activation.handle.dispose() + } catch (error: unknown) { + failures.push(new SubagentError( + `subagent "${childId}" activation handle disposal failed: ${errorChain(error)}`, + 'ACTIVATION_TEARDOWN_FAILED', + { cause: error }, + )) + } + + let failure: SubagentError | undefined + if (failures.length === 1) { + failure = failures[0] + } else if (failures.length > 1) { + failure = new SubagentError( + `subagent "${childId}" activation teardown failed at ${failures.length} boundaries: ` + + failures.map(item => errorChain(item)).join('; '), + 'ACTIVATION_TEARDOWN_FAILED', + { cause: new AggregateError(failures) }, + ) + } + this.resident.delete(childId) + this.notifySettlement(activation, activation.observer.terminal(failure)) + this.releaseOwnership(childId) + activation.observer.settle(failure) + if (failure !== undefined) throw failure + } + + /** Tell the durable direct parent how this Activation ended. */ + private notifySettlement(activation: Activation, terminal: ActivationTerminal): void { + if (!activation.announced) return + try { + const parent = this.ctx.agents.get(activation.parentSession) + if (parent === undefined) return + const message = createSettlementMessage(activation.childId, terminal) + if (this.closingTeardownFor(parent) !== undefined) { + parent.inject(message) + return + } + this.sendWaking(parent, message, parent.status === 'idle' ? 'queue' : 'steer') + } catch (error: unknown) { + this.ctx.logger.warn( + `subagent "${activation.childId}" settlement notice was not delivered to its parent: ` + + errorChain(error), + ) + } + } + + /** Request a best-effort final session flush before closing natural-settlement admission. */ + private async flushFinalState(activation: Activation): Promise { + const child = activation.handle.agent + try { + await child.ctx.sessions.flush(child.session) + } catch (error: unknown) { + this.ctx.logger.warn( + `subagent "${activation.childId}" best-effort final session flush failed; ` + + `the persisted state may be unavailable or stale on resume: ${errorChain(error)}`, + ) + } + } +} diff --git a/packages/subagent/subagent/src/continuation-messages.ts b/packages/subagent/subagent/src/continuation-messages.ts new file mode 100644 index 0000000000..31813c2c3a --- /dev/null +++ b/packages/subagent/subagent/src/continuation-messages.ts @@ -0,0 +1,154 @@ +/** + * Model-visible messages owned by continuable-subagent orchestration. + * + * @module @deepseek-ai/dsh-subagent/continuation-messages + */ + +import type { Agent } from '@deepseek-ai/dsh-agent' +import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { SessionId } from '@deepseek-ai/dsh-session' +import type { ActivationTerminal } from './lifecycle.ts' +import type { SubagentResult } from './types.ts' + +/** Durable attribution for one model-authored message between adjacent Agents. */ +export interface AgentMessageSource { + readonly kind: 'agent-message' + /** A message another agent addressed to this one (`relay` context form). */ + readonly form: 'relay' + /** Session id of the Agent whose tool call produced the message. */ + readonly senderSessionId: SessionId +} + +/** + * Durable attribution for the runtime's own account of a continuable child + * settling. Deliberately a different kind from + * {@link AgentMessageSource}: an Agent message is content the sender chose, + * while this message is the manager stating what became of the child, and a + * transcript that merged them would credit the child with words it never wrote. + */ +export interface SubagentSettledMessageSource { + readonly kind: 'subagent-settled' + /** A runtime account shown without expanding the row (`notice` context form). */ + readonly form: 'notice' + /** One-line account of how the child ended. */ + readonly summary: string + /** Session id of the child that settled. */ + readonly senderSessionId: SessionId +} + +declare module '@deepseek-ai/dsh-llm' { + interface MessageSourceMap { + 'agent-message': AgentMessageSource + 'subagent-settled': SubagentSettledMessageSource + } +} + +/** Build durable attribution for one adjacent-Agent message. */ +function agentMessageSource(sender: Agent): AgentMessageSource { + return { + kind: 'agent-message', + form: 'relay', + senderSessionId: sender.id, + } +} + +/** + * Build the model-visible and durable representation of one adjacent-Agent message. + * @param sender - exact live Agent that authored the message. + * @param content - model-visible message blocks supplied by the sender. + * @returns the durable user-message representation delivered to the recipient. + */ +export function createAgentMessage( + sender: Agent, + content: ContentBlock[], +): ReturnType { + return createUserMessage({ + content: [ + { type: 'text' as const, text: `Agent ${sender.id} sent a message: ` }, + ...content, + ], + source: agentMessageSource(sender), + }) +} + +/** + * Append adjacent-Agent return guidance to a continuable child's initial task. + * @param parentId - durable parent session id named in the guidance. + * @param prompt - initial model-visible task blocks. + * @returns task blocks followed by the continuable return guidance. + */ +export function withContinuableReturnGuidance( + parentId: SessionId, + prompt: ContentBlock[], +): ContentBlock[] { + const encodedParentId = JSON.stringify(parentId) + return [ + ...prompt, + { + type: 'text', + text: `Your parent agent id is ${encodedParentId}. Before you finish, send your result to that agent with ` + + `send_message({ agent_id: ${encodedParentId}, message: "" }). The parent shares ` + + 'your workspace but does not automatically receive your transcript, tool output, or reasoning. Send ' + + 'earlier messages as well when a finding changes what the parent should do next; sending a message ' + + 'does not end your turn.', + }, + ] +} + +/** + * One line telling a parent that a background child is finished and why, in + * the parent's own task vocabulary. + * @param childId - the durable child the parent knows by id. + * @param stopReason - how the child's last ordinary turn ended. + * @returns the model-facing opening line of the settlement notice. + */ +function settlementSummary(childId: SessionId, stopReason: SubagentResult['stopReason']): string { + const subject = `Background subagent ${childId}` + switch (stopReason) { + case 'completed': + return `${subject} finished and will do no further work unless you send it more.` + case 'aborted': + return `${subject} was stopped before it finished.` + case 'max-tokens': + return `${subject} ran out of room before it finished.` + // A pre-step rejection — a hook deny, a policy plugin — discarded input + // the child had claimed, so the parent must not treat the task as done. + case 'refusal': + return `${subject} declined the task.` + case 'error': + return `${subject} failed before it finished.` + /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm + * needs a backend that adds a variant; an unnameable ending is reported as unfinished + * rather than silently as success. */ + default: + return `${subject} ended abnormally (${String(stopReason)}) before it finished.` + } +} + +/** + * Build the runtime-owned settlement notice delivered to a child's parent. + * @param childId - durable child session id named in the notice. + * @param terminal - recorded terminal state for the settled Activation. + * @returns the durable user-message representation delivered to the parent. + */ +export function createSettlementMessage( + childId: SessionId, + terminal: ActivationTerminal, +): ReturnType { + const summary = settlementSummary(childId, terminal.stopReason) + return createUserMessage({ + content: [ + { type: 'text' as const, text: summary }, + ...terminal.output === undefined + ? [{ type: 'text' as const, text: 'It left no closing message.' }] + : [{ type: 'text' as const, text: 'Its closing message:' }, ...terminal.output], + ], + source: { + kind: 'subagent-settled' as const, + form: 'notice' as const, + summary: boundContextSummary(summary), + senderSessionId: childId, + }, + }) +} diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts index c5b8782e28..b5ffced75e 100644 --- a/packages/subagent/subagent/src/continuation.ts +++ b/packages/subagent/subagent/src/continuation.ts @@ -1,137 +1,57 @@ /** - * Internal continuable-subagent manager: stable child ids, descriptor - * persistence, activation admission, the live ownership graph, cold resume, - * child-first disposal, and settlement delivery to the parent, behind - * `ctx.subagents`. + * Continuable-subagent orchestration behind `ctx.subagents`: stable child ids, + * descriptor persistence, provider preparation, cold resume, authorization, + * and message routing. {@link ContinuableActivationRegistry} owns the mutable + * process-local Activation graph and its settlement and disposal lifecycle. * * A continuable child has one durable Session and at most one process-local - * {@link Activation} — one residency epoch for a reconstructed child Agent. An - * Activation is not a request, result, cancellation, or Task boundary: it may - * execute many FIFO turns and stays resident while descendants it created are - * still running. The Agent inbox is the only turn queue, so this manager owns - * residency while the Agent loop owns all turn ordering and execution. No - * continuable path creates a Task or an intermediate result-bearing wrapper. - * - * Because residency is this manager's alone to end, telling the parent that a - * child settled is its job too. An external `subagent/end` listener cannot do - * it correctly: that payload names no parent, the child handle is already - * disposed by then, and the release that wakes the parent's own settlement - * watcher has already run. See {@link SubagentContinuationManager.notifySettlement}. + * Activation. The Agent inbox is the only turn queue, so this manager owns + * durable orchestration while the Agent loop owns all turn ordering and + * execution. No continuable path creates a Task or an intermediate + * result-bearing wrapper. * * @module @deepseek-ai/dsh-subagent */ import { randomUUID } from 'node:crypto' import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' import { brandString } from '@deepseek-ai/dsh-brand' -import type { - Agent, - AgentHandle, - AgentOptions, - CreateAgentOptions, -} from '@deepseek-ai/dsh-agent' -import { ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain } from '@deepseek-ai/dsh-llm' +import { ReasoningEffortId, contentHasImage, createUserMessage } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm' import { SessionLogOffset } from '@deepseek-ai/dsh-session' -import type { SessionEvent, SessionId , SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session' +import type { SessionId } from '@deepseek-ai/dsh-session' import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence' import type { SessionObservation, SessionQueryEngine } from '@deepseek-ai/dsh-session-query' -import type { ToolRestriction } from '@deepseek-ai/dsh-tools' -import { foldSubagentDescriptor, snapshotSubagentDescriptor } from './descriptor.ts' -import type { SubagentDescriptorData } from './descriptor.ts' import { - appendDelegatedPolicyOverrides, - applyChildComposition, - captureDelegatedPolicyOverrides, childSessionMeta, + captureDelegatedPolicyOverrides, resolveChildAgentOptions, resolveChildDepth, } from './child-agent.ts' -import type { DelegatedPolicyOverrides } from './child-agent.ts' +import { + ContinuableActivationRegistry, +} from './continuation-activation.ts' +import type { Activation } from './continuation-activation.ts' +import { + createAgentMessage, + withContinuableReturnGuidance, +} from './continuation-messages.ts' import { assertSubagentMaxDepth } from './depth.ts' -import type { ContinuableCreateRequest, ContinuableCreateSpec, SubagentResult, SubagentStartRequest } from './types.ts' -import type { ActivationObserver, ActivationTerminal } from './lifecycle.ts' +import { foldSubagentDescriptor, snapshotSubagentDescriptor } from './descriptor.ts' import { SubagentError } from './error.ts' import { isAdjacentAgentSendMessageTool } from './internal.ts' +import type { ActivationObserver } from './lifecycle.ts' +import type { + ContinuableCreateRequest, + ContinuableCreateSpec, + ContinuableStart, + ContinuableStartSpec, + SubagentInterruptAuthority, + SubagentSendMessageOptions, +} from './types.ts' -/** Durable attribution for one model-authored message between adjacent Agents. */ -export interface AgentMessageSource { - readonly kind: 'agent-message' - /** A message another agent addressed to this one (`relay` context form). */ - readonly form: 'relay' - /** Session id of the Agent whose tool call produced the message. */ - readonly senderSessionId: SessionId -} - -/** - * Durable attribution for the runtime's own account of a continuable child - * settling. Deliberately a different kind from - * {@link AgentMessageSource}: an Agent message is content the sender chose, - * while this message is the manager stating what became of the child, and a - * transcript that merged them would credit the child with words it never wrote. - */ -export interface SubagentSettledMessageSource { - readonly kind: 'subagent-settled' - /** A runtime account shown without expanding the row (`notice` context form). */ - readonly form: 'notice' - /** One-line account of how the child ended. */ - readonly summary: string - /** Session id of the child that settled. */ - readonly senderSessionId: SessionId -} - -declare module '@deepseek-ai/dsh-llm' { - interface MessageSourceMap { - 'agent-message': AgentMessageSource - 'subagent-settled': SubagentSettledMessageSource - } -} - -/** What a caller asks for when starting a continuable background child. */ -export interface ContinuableStartSpec { - /** The `ctx.subagents` provider whose continuable-creation capability establishes the child. */ - readonly provider: string - /** The initial delegation's short `description`, persisted as the child's creation label. */ - readonly label: string - /** - * Optional caller-reserved child identity. Omission preserves the manager's - * UUID allocation; supplying one lets a durable parent record provisioning - * before child materialization without a second identity handshake. - */ - readonly childId?: SessionId - /** - * The delegation request. The manager reserves the stable child id, resolves - * the durable descriptor, and composes the child itself. - */ - readonly request: Omit - /** Caller cancellation, owning the operation only until inbox acceptance. */ - readonly signal: AbortSignal -} - -/** Identities returned once a continuable child accepted its initial prompt. */ -export interface ContinuableStart { - /** The durable child session id, stable across activations. */ - readonly childId: SessionId - /** The accepted initial prompt's inbox message id. */ - readonly messageId: MessageId -} - -/** - * Authority under which one interrupt request is admitted. `user` carries the - * durable direct-parent address a human client presented; `ancestor` carries - * the exact live Agent object whose recorded lineage must contain the caller. - */ -export type SubagentInterruptAuthority = - | { readonly kind: 'user'; readonly parentSessionId: SessionId } - | { readonly kind: 'ancestor'; readonly agent: Agent } - -/** Options for one model-authored message between adjacent Agents. */ -export interface SubagentSendMessageOptions { - /** Caller cancellation, owning the operation only until inbox acceptance. */ - readonly signal: AbortSignal -} - -/** Inputs shared by model steering and the human Queue adapter. */ +/** Inputs shared by model steering and human prompt delivery. */ type ChildDeliveryOptions = | { readonly delivery: 'steer' @@ -144,238 +64,14 @@ type ChildDeliveryOptions = } | { readonly delivery: 'queue'; readonly source: MessageSource; readonly signal: AbortSignal } -/** - * The residency state of one continuable child, derived from Agent quiescence - * and the owned-child set rather than a second state machine: - * `running` — the Agent has an active admission or turn, or waking inbox work; - * `waiting` — the Agent is quiescent but still owns undisposed children; - * `settled` — quiescent with every owned child disposed, so the manager - * disposes the `AgentHandle` and removes the Activation. - */ -type ActivationState = 'running' | 'waiting' | 'settled' - -/** - * Hooks the manager needs from the owning service. Declared here, by the - * dependent, so the manager states exactly what it requires instead of - * depending back on the whole {@link SubagentRuntime}. Package-private: no - * consumer outside this package supplies a host. - */ +/** Package-private hooks supplied by the owning service. */ interface ContinuationHost { - /** - * Resolve one provider's continuable-creation contribution, or reject when - * the provider is unknown or lacks the capability. - * @param name - the configured provider name. - * @param request - the reserved identity, delegating parent, and cancellation. - * @returns the provider's detached creation spec. - */ + /** Resolve one provider's detached continuable-creation contribution. */ prepareContinuable(name: string, request: ContinuableCreateRequest): Promise - /** - * Build the lifecycle observer for one Activation's residency epoch. - * @param provider - the provider name recorded in the durable descriptor. - * @param childId - the durable child session id. - * @param parent - the exact live direct parent for scoped dispatch. - * @returns the observer whose edges this epoch publishes. - */ + /** Build the lifecycle observer for one Activation residency epoch. */ observeActivation(provider: string, childId: SessionId, parent: Agent): ActivationObserver } -/** - * One residency epoch for a reconstructed continuable child Agent. It directly - * owns the published `AgentHandle`; the manager's private activation-owner - * scope is its structural Cordis owner. - */ -interface Activation { - /** The durable child this Activation is an epoch of. */ - readonly childId: SessionId - /** - * The durable direct parent, stored because settlement delivery must resolve - * that parent after the child handle is gone. {@link ancestry} cannot answer - * it: a `WeakSet` is not enumerable, and the child's own header is only - * reachable through a handle disposal has already released. - */ - readonly parentSession: SessionId - /** The provider name recorded in the durable descriptor. */ - readonly provider: string - /** The retained live Agent handle, disposed exactly once at settlement. */ - readonly handle: AgentHandle - /** - * Exact live Agent ancestry observed when this Activation materialized. - * Weak membership preserves host-scope identity across an intermediate - * ancestor leaving the registry without retaining that ancestor's runtime. - */ - readonly ancestry: WeakSet - /** - * Session ids of the child Activations this one owns. Because one Session has - * at most one live Activation, the id identifies the live child without - * another runtime-incarnation reference. Non-empty blocks settlement. - */ - readonly ownedChildren: Set - /** The lifecycle observer that emits this epoch's start and terminal edges. */ - readonly observer: ActivationObserver - /** - * The memoized disposal transaction. Presence IS the admission cutoff: it is - * assigned synchronously when disposal begins, so no delivery can join a - * handle being torn down, and a racing delivery awaits it before cold-resuming - * a new Activation. Every converging releaser shares this one teardown. - */ - disposal: Promise | undefined - /** - * Accepted waking message ids this manager has not yet seen leave the inbox. - * `Agent.status` is still `idle` in the window between a waking send and the - * microtask that admits it, so settlement must not treat that gap as quiet. - */ - readonly accepted: Set - /** - * Whether any delivery to this child was ever accepted. A materialization - * rolled back before its first acceptance is a child the caller was told does - * not exist, so its teardown owes the parent no settlement account. - */ - announced: boolean - /** Renewed whenever a settlement watcher must re-observe quiescence. */ - poke: PromiseWithResolvers -} - -/** Inputs shared by fresh and resumed Activation materialization. */ -interface MaterializeInputs { - childId: SessionId - provider: string - parent: Agent - /** - * Creation inputs; absent for a cold resume, which loads the persisted - * session — including the delegation policy events a fresh creation seeded, - * so a resume never re-captures the parent's policy. - */ - create?: { - seed: readonly SessionEvent[] | undefined - meta: NonNullable - /** Exact parent-log prefix length inside {@link seed}. */ - inheritedEventCount: SessionLogOffsetType - /** Policy captured at the delegation boundary: the parent's sandbox override plus the approval pin. */ - delegatedPolicies: DelegatedPolicyOverrides - /** Child-owned composition record appended after the inherited marker. */ - descriptor: SubagentDescriptorData - } - agentOptions: AgentOptions - composition: { persona?: string | undefined; toolFilter?: ToolRestriction | undefined } - signal: AbortSignal -} - -/** - * One admitted materialization and the exact live ancestry observed at its - * synchronous admission boundary. Retaining identities lets a scoped teardown - * keep waiting even if an intermediate Agent leaves the registry meanwhile. - */ -interface Materialization { - readonly lineage: readonly Agent[] - readonly settled: Promise -} - -/** - * Read one Activation's current disposal transaction. This indirection exists - * because TypeScript would otherwise narrow repeated reads of the mutable field - * inside a long-lived closure to constants instead of re-reading runtime state. - * @param activation - the Activation to inspect. - * @returns the in-flight or settled disposal, or `undefined` while resident. - */ -function disposalOf(activation: Activation): Promise | undefined { - return activation.disposal -} - -/** Build durable attribution for one adjacent-Agent message. */ -function agentMessageSource(sender: Agent): AgentMessageSource { - return { - kind: 'agent-message', - form: 'relay', - senderSessionId: sender.id, - } -} - -/** Build the model-visible and durable representation of one adjacent-Agent message. */ -function agentMessage(sender: Agent, content: ContentBlock[]) { - return createUserMessage({ - content: [ - { type: 'text' as const, text: `Agent ${sender.id} sent a message: ` }, - ...content, - ], - source: agentMessageSource(sender), - }) -} - -/** Append adjacent-Agent return guidance to a continuable child's initial task. */ -function continuableInitialPrompt(parentId: SessionId, prompt: ContentBlock[]): ContentBlock[] { - const encodedParentId = JSON.stringify(parentId) - return [ - ...prompt, - { - type: 'text', - text: `Your parent agent id is ${encodedParentId}. Before you finish, send your result to that agent with ` - + `send_message({ agent_id: ${encodedParentId}, message: "" }). The parent shares ` - + 'your workspace but does not automatically receive your transcript, tool output, or reasoning. Send ' - + 'earlier messages as well when a finding changes what the parent should do next; sending a message ' - + 'does not end your turn.', - }, - ] -} - -/** - * One line telling a parent that a background child is finished and why, in - * the parent's own task vocabulary. - * @param childId - the durable child the parent knows by id. - * @param stopReason - how the child's last ordinary turn ended. - * @returns the model-facing opening line of the settlement notice. - */ -function settlementSummary(childId: SessionId, stopReason: SubagentResult['stopReason']): string { - const subject = `Background subagent ${childId}` - switch (stopReason) { - case 'completed': - return `${subject} finished and will do no further work unless you send it more.` - case 'aborted': - return `${subject} was stopped before it finished.` - case 'max-tokens': - return `${subject} ran out of room before it finished.` - // A pre-step rejection — a hook deny, a policy plugin — discarded input - // the child had claimed, so the parent must not treat the task as done. - case 'refusal': - return `${subject} declined the task.` - case 'error': - return `${subject} failed before it finished.` - /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm - * needs a backend that adds a variant; an unnameable ending is reported as unfinished - * rather than silently as success. */ - default: - return `${subject} ended abnormally (${String(stopReason)}) before it finished.` - } -} - -/** Whether one settlement attempt opened the disposal transaction. */ -type SettlementAttempt = - | { readonly settling: false } - | { readonly settling: true; readonly done: Promise } - -/** Serialize each durable child's delivery, release, and disposal. */ -class ChildLock { - private tails = new Map>() - - /** - * Run `operation` after every previously queued operation for `childId`. - * @param childId - the durable child whose operations are linearized. - * @param operation - the critical section to run in order. - * @returns the operation's own settlement. - */ - run(childId: SessionId, operation: () => Promise): Promise { - const previous = this.tails.get(childId) ?? Promise.resolve() - const result = previous.then(operation, operation) - // Absorb rejections in the chaining tail so one failed critical section - // cannot reject an unrelated later caller. - const tail = result.then(() => undefined, () => undefined) - this.tails.set(childId, tail) - void tail.then(() => { - if (this.tails.get(childId) === tail) this.tails.delete(childId) - }) - return result - } -} - /** * The continuable-subagent orchestration service behind `ctx.subagents`. Tool * schema and host adapters are consumers of this one contract; foreground @@ -383,66 +79,33 @@ class ChildLock { * this lifecycle. */ export class SubagentContinuationManager { - /** Child session id → its live Activation. Process-local, never durable. */ - private activations = new Map() - /** Materializations admitted before drain, tracked through publication or rollback. */ - private readonly materializations = new Set() - private readonly locks = new ChildLock() - /** Structural Cordis owner of every Activation handle. */ - private readonly ownerCtx: Context - /** - * Exact roots whose host teardown has begun, with the live lineage members - * observed under each root. Entries remain until that exact root leaves the - * Agent registry, closing admission throughout its host's teardown without - * poisoning a later same-id replacement. - */ - private readonly closingScopes = new Map>() - private draining = false + private readonly activations: ContinuableActivationRegistry constructor( private readonly ctx: Context, private readonly host: ContinuationHost, ) { - // Ordinary Cordis owner effects unwind in reverse registration order, which - // cannot express the dynamic child graph. Register the private scope's - // structural disposer FIRST and the drain SECOND, so reverse unwind invokes - // the drain before releasing the scope; a cleanup effect on the same scope - // as the Agent handles would let structural handle disposal bypass - // child-first ordering. - const scope = ctx.plugin(function activationOwner() {}) - this.ownerCtx = scope.ctx - ctx.on('agent/disposed', ({ agent }) => { - this.closingScopes.delete(agent) - }) - ctx.effect(function* (this: SubagentContinuationManager) { - yield scope.dispose - yield () => this.drain() - }.bind(this), 'subagents.continuations()') + this.activations = new ContinuableActivationRegistry( + ctx, + (provider, childId, parent) => host.observeActivation(provider, childId, parent), + ) } /** - * Start one continuable background child: reserve its durable identity, - * resolve the provider's detached creation spec, create the child Agent - * through the private activation-owner scope, establish any continuable-parent - * ownership, and submit the initial prompt. Resolves when inbox acceptance - * yields the message id — without waiting for the turn to start or for the - * message to reach the Session log. - * - * Every failure before that acceptance rejects without either id, disposing - * any created handle and rolling back the Activation and parent ownership. - * The caller signal owns lookup, materialization, and admission only until - * acceptance; afterwards the manager owns the Activation independently. + * Start one continuable background child and resolve at initial inbox acceptance. + * Every earlier failure disposes any created handle and rolls back Activation + * and parent ownership without returning either id. * @param spec - provider, delegation request, and caller cancellation. - * @returns the durable child id and the accepted initial prompt's message id. + * @returns the durable child id and accepted initial prompt message id. */ async startContinuable(spec: ContinuableStartSpec): Promise { const request = spec.request const parent = request.parent - this.assertAdmitting(parent) + this.activations.assertAdmitting(parent) const persistence = this.requirePersistence() assertSubagentMaxDepth(request.maxDepth) const childId = spec.childId ?? brandString(randomUUID()) - this.assertChildIdAvailable(childId) + this.activations.assertChildIdAvailable(childId) const childDepth = resolveChildDepth(parent, request.maxDepth) // Snapshot before any await: invalid descriptor JSON rejects the call // before a child exists, and the detached value is what reaches the log. @@ -464,12 +127,10 @@ export class SubagentContinuationManager { // parent's future, not to this child. const delegatedPolicies = captureDelegatedPolicyOverrides(parent) - // Hold the parent's own Activation open across the establishment awaits: - // an idle continuation-managed parent must not settle while a caller is - // still creating its child, or the admitted delivery would find a stale - // parent identity. A turn-scoped delegation never needs this (the parent - // is `running`), but this service is also callable outside a turn. - const releaseHold = this.holdOwnership(parent, childId) + // An idle continuation-managed parent must not settle while a caller is + // still creating its child. A turn-scoped delegation does not need this, + // but the service is also callable outside a turn. + const releaseHold = this.activations.holdOwnership(parent, childId) try { const prepared = await this.host.prepareContinuable(spec.provider, { sessionId: childId, @@ -477,24 +138,24 @@ export class SubagentContinuationManager { signal: spec.signal, }) spec.signal.throwIfAborted() - this.assertAdmitting(parent) + this.activations.assertAdmitting(parent) const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0) const seed = prepared.seed - const messageId = await this.locks.run(childId, async () => { + const messageId = await this.activations.locks.run(childId, async () => { spec.signal.throwIfAborted() - this.assertAdmitting(parent) - this.assertChildIdAvailable(childId) + this.activations.assertAdmitting(parent) + this.activations.assertChildIdAvailable(childId) if (spec.childId !== undefined) { const persisted = await persistence.stat(childId, { signal: spec.signal }) spec.signal.throwIfAborted() - this.assertAdmitting(parent) - this.assertChildIdAvailable(childId) + this.activations.assertAdmitting(parent) + this.activations.assertChildIdAvailable(childId) if (persisted !== undefined) { throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD') } } - const activation = await this.materialize({ + const activation = await this.activations.materialize({ childId, provider: spec.provider, parent, @@ -512,7 +173,7 @@ export class SubagentContinuationManager { return this.submitMaterialized( activation, isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', activation.handle.agent)) - ? continuableInitialPrompt(parent.id, request.prompt) + ? withContinuableReturnGuidance(parent.id, request.prompt) : request.prompt, { source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' }, parent, @@ -525,60 +186,15 @@ export class SubagentContinuationManager { } } - /** - * Pre-register `childId` in a continuation-managed parent's owned set so the - * parent cannot settle while a caller is still establishing or resuming that - * child. Returns a releaser for the failure path; it removes only a hold - * this call added, and leaves ownership in place once a live Activation for - * the child exists (an admitted delivery owns it from then on). A parent - * without an Activation needs no hold: only this manager settles parents. - * @param parent - the live direct parent the operation is admitted under. - * @param childId - the durable child the operation addresses. - * @returns the failure-path releaser; a no-op when nothing was added. - * @throws {SubagentError} `ACTIVATION_CLOSING` when the parent's own - * disposal transaction is already open. - */ - private holdOwnership(parent: Agent, childId: SessionId): () => void { - const parentActivation = this.activations.get(parent.id) - if (parentActivation === undefined || parentActivation.handle.agent !== parent) return () => {} - if (parentActivation.disposal !== undefined) { - throw new SubagentError( - `subagent parent "${parent.id}" is being disposed; the child was not established`, - 'ACTIVATION_CLOSING', - ) - } - if (parentActivation.ownedChildren.has(childId)) return () => {} - parentActivation.ownedChildren.add(childId) - return () => { - const live = this.activations.get(childId) - /* v8 ignore next 4 -- reaching this arm needs another delivery to establish the child - * between this operation's failure and its releaser running, which no test can schedule - * deterministically: the ownership edge then belongs to that live Activation, so the - * conservative keep leaves it for finishDisposal's releaseOwnership. */ - if (live !== undefined && live.disposal === undefined) return - if (parentActivation.ownedChildren.delete(childId)) this.wake(parentActivation) - } - } - - /** Reject one child identity already owned by a live Agent or Session. */ - private assertChildIdAvailable(childId: SessionId): void { - if (this.ctx.agents.get(childId) !== undefined || this.ctx.get('sessions')?.get(childId) !== undefined) { - throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD') - } - } - /** * Deliver one model-authored message to a direct continuable child or to the - * sender's direct parent. Both directions use Steer: a running target admits - * the message at its nearest step boundary, while an idle target starts a - * turn. A missing direct child cold-resumes through the ordinary continuation - * lifecycle. The caller signal owns the operation only until inbox acceptance. + * sender's direct parent. A missing direct child cold-resumes through the + * ordinary continuation lifecycle. * @param sender - exact live Agent authorizing and originating the message. * @param targetId - durable direct-parent or direct-child session id. * @param content - model-authored content to deliver. * @param options - caller cancellation before acceptance. * @returns the accepted message's inbox id. - * @throws when adjacency, availability, or admission rejects delivery. */ async sendMessage( sender: Agent, @@ -592,7 +208,7 @@ export class SubagentContinuationManager { 'UNAUTHORIZED', ) } - this.assertAdmitting(sender) + this.activations.assertAdmitting(sender) const senderActivation = this.activations.get(sender.id) if (senderActivation !== undefined && senderActivation.handle.agent === sender @@ -616,10 +232,10 @@ export class SubagentContinuationManager { * Queue one human-authored prompt as a distinct direct-child turn. * @param parent - exact live direct parent authorizing delivery. * @param childId - durable direct-child session id. - * @param content - human-authored content to deliver. - * @param source - durable host-protocol provenance. + * @param content - model-visible prompt blocks. + * @param source - durable attribution for the human prompt. * @param signal - caller cancellation before inbox acceptance. - * @returns the accepted message's inbox id. + * @returns the accepted durable message id. */ async queuePrompt( parent: Agent, @@ -635,10 +251,10 @@ export class SubagentContinuationManager { * Steer one host-authored prompt to a direct continuable child. * @param parent - exact live direct parent authorizing delivery. * @param childId - durable direct-child session id. - * @param content - host-authored content to deliver. - * @param source - durable host-protocol provenance. + * @param content - model-visible prompt blocks. + * @param source - durable attribution for the host prompt. * @param signal - caller cancellation before inbox acceptance. - * @returns the accepted message's inbox id. + * @returns the accepted durable message id. */ async steerPrompt( parent: Agent, @@ -657,10 +273,8 @@ export class SubagentContinuationManager { content: ContentBlock[], options: ChildDeliveryOptions, ): Promise { - this.assertAdmitting(parent) - // Same hold as `startContinuable`: an idle continuation-managed parent - // must not settle underneath a cold resume it is authorizing. - const releaseHold = this.holdOwnership(parent, childId) + this.activations.assertAdmitting(parent) + const releaseHold = this.activations.holdOwnership(parent, childId) try { return await this.deliverFollowup(parent, childId, content, options) } catch (error: unknown) { @@ -677,37 +291,27 @@ export class SubagentContinuationManager { options: ChildDeliveryOptions, ): Promise { while (true) { - const live = await this.locks.run(childId, async () => { + const live = await this.activations.locks.run(childId, async () => { const activation = this.activations.get(childId) if (activation === undefined) return this.coldResume(parent, childId, content, options) - // A delivery that arrives after the disposal transaction began must not - // reach a handle being torn down; wait for release, then cold-resume. - const disposal = activation.disposal - /* v8 ignore next 3 -- the send-versus-dispose cutoff: reaching this arm needs a - * delivery to observe the transaction inside the same critical section that opened it, - * which no test can schedule deterministically. The behavior is covered end-to-end by - * "cold-resumes a delivery that lost the race with final disposal". */ + const disposal = activation.inbox.closing + /* v8 ignore next 3 -- the send-versus-dispose cutoff needs a delivery to + * observe the transaction inside the same critical section that opened it. */ if (disposal !== undefined) { return disposal.then(() => undefined, () => undefined) } - // Text-only delivery stays await-free, so the disposal-cutoff check - // above and the submit share one critical window. The image path - // awaits a capability read, so it re-checks the cutoff afterwards; a - // disposal that began during the read is waited out and retried like - // one observed on entry. if (contentHasImage(content)) { await this.assertImageCapable(activation.handle.agent, options.signal) - if (activation.disposal !== undefined) { - await Promise.allSettled([activation.disposal]) + if (activation.inbox.closing !== undefined) { + await Promise.allSettled([activation.inbox.closing]) return undefined } } return this.submitAdmitted(activation, content, options, parent) }) - /* v8 ignore start -- only the lost-cutoff arm above returns undefined, so only that - * race reaches the retry below, which then cold-resumes a new Activation. */ + /* v8 ignore start -- only a delivery that lost the disposal cutoff retries. */ if (live !== undefined) return live - this.assertAdmitting(parent) + this.activations.assertAdmitting(parent) options.signal.throwIfAborted() /* v8 ignore stop */ } @@ -715,65 +319,13 @@ export class SubagentContinuationManager { /** * Interrupt one live continuable child's current turn. Admission is - * synchronous and the effect is asynchronous: this authorizes the caller, - * requests `Agent.cancel(cause, { keepInbox: true })` on the target, and - * returns without waiting for the target to observe the signal or reach - * quiescence. The Activation, its handle, accepted unclaimed inbox work, and - * already-published descendants are untouched; work already claimed into the - * interrupted turn is not requeued. Once the interrupted driver is idle, a - * waking send resumes the parked queue. - * - * An absent target is an accepted no-op, which uniformly covers natural - * completion races, repeated requests, one-shot ids, and unknown ids without - * consulting the durable catalog. A target whose disposal transaction is - * already open is likewise an accepted no-op after authorization. + * synchronous and the cancellation effect is asynchronous. An absent or + * already-closing target is an accepted no-op after authority checks. * @param targetSessionId - the durable child session id to interrupt. * @param authority - the human parent address or exact live ancestor Agent. - * @throws {SubagentError} `UNAUTHORIZED` when the presented authority does - * not own the live target: a stale or self-targeting ancestor caller, a - * parent address that is not the live target's durable direct parent, or - * an ancestor outside the target's recorded live lineage. */ interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void { - if (authority.kind === 'ancestor') { - const caller = authority.agent - // A stale caller is rejected even when the target is absent, so a - // replaced same-id Agent can never probe this manager's state. - if (this.ctx.agents.get(caller.id) !== caller) { - throw new SubagentError( - `interrupting "${targetSessionId}" requires the exact live ancestor agent`, - 'UNAUTHORIZED', - ) - } - if (caller.id === targetSessionId) { - throw new SubagentError( - `agent "${caller.id}" cannot interrupt itself`, - 'UNAUTHORIZED', - ) - } - } - const activation = this.activations.get(targetSessionId) - if (activation === undefined) return - if (authority.kind === 'user') { - if (activation.handle.agent.session.header.parentSession !== authority.parentSessionId) { - throw new SubagentError( - `subagent "${targetSessionId}" belongs to another parent session`, - 'UNAUTHORIZED', - ) - } - } else if (!activation.ancestry.has(authority.agent)) { - throw new SubagentError( - `subagent "${targetSessionId}" is not a live descendant of agent "${authority.agent.id}"`, - 'UNAUTHORIZED', - ) - } - // Disposal already stopped the target with a whole-Activation teardown; - // a second cancel would be a redundant signal on a closing handle. - if (activation.disposal !== undefined) return - activation.handle.agent.cancel( - authority.kind === 'user' ? { kind: 'user' } : { kind: 'parent' }, - { keepInbox: true }, - ) + this.activations.interrupt(targetSessionId, authority) } /** Deliver one resident continuable child's message to its live direct parent. */ @@ -784,7 +336,7 @@ export class SubagentContinuationManager { ): MessageId { /* v8 ignore next 6 -- only synchronous re-entrant teardown can open this * transaction between exact-agent authorization and this no-await span. */ - if (activation.disposal !== undefined) { + if (activation.inbox.closing !== undefined) { throw new SubagentError( `subagent "${sender.id}" activation is being disposed; the message was not delivered`, 'ACTIVATION_CLOSING', @@ -797,40 +349,18 @@ export class SubagentContinuationManager { 'PARENT_UNAVAILABLE', ) } - const message = agentMessage(sender, content) - this.sendWaking(parent, message, () => { this.sendAgentMessage(parent, message) }) + const message = createAgentMessage(sender, content) + this.sendAgentMessage(parent, message) return message.id } - /** - * Perform one waking send to a parent, accounted against that parent's own - * Activation when it has one. Registering the id before the send is what - * keeps a continuation-managed parent from being judged quiescent in the - * window between a waking send and the microtask that admits it. - * @param parent - the exact live parent receiving the waking message. - * @param message - the message whose id is accounted. - * @param send - the synchronous waking send to perform. - */ - private sendWaking( - parent: Agent, - message: ReturnType, - send: () => void, - ): void { - const parentActivation = this.activations.get(parent.id) - if (parentActivation !== undefined && parentActivation.handle.agent === parent) { - this.admitWaking(parentActivation, message.id, send) - } else { - send() - } - } - /** Send one Agent message while translating only the target's own rejection. */ private sendAgentMessage( parent: Agent, message: ReturnType, ): void { try { - parent.steer(message) + this.activations.sendWaking(parent, message, 'steer') } catch (error: unknown) { throw new SubagentError( 'direct parent is not live; the message was not delivered', @@ -840,229 +370,31 @@ export class SubagentContinuationManager { } } - /** - * Close admission, await every already-admitted materialization through - * publication or rollback, then dispose the stable live Activation forest - * child-first. Sibling branches drain independently: one failure is recorded - * but never prevents the remaining handles from being attempted, and the - * aggregate rejects only after every branch settles. - * @returns once materialization is quiescent and every live Activation released its handle. - * @throws an aggregate error when any branch failed to release. - */ + /** Close manager-wide admission and release every live Activation. */ async drain(): Promise { - // Close admission synchronously before the first await. Materializations - // already past that cutoff remain tracked until their handle is installed - // or rollback completes, producing a stable forest for the later snapshot. - this.draining = true - await Promise.all([...this.materializations].map(materialization => materialization.settled)) - // Snapshot roots after closing admission: a root is an Activation no live - // Activation owns, so disposing roots recurses child-first into the forest. - const owned = new Set() - for (const activation of this.activations.values()) { - for (const child of activation.ownedChildren) owned.add(child) - } - const roots = [...this.activations.values()].filter(activation => !owned.has(activation.childId)) - await this.disposeRoots(roots, 'activation(s)') + await this.activations.drain() } /** * Stop only the continuable descendants of exact live host-owned parents. - * Admission stays closed for those parent trees until each exact parent - * leaves the Agent registry; unrelated trees and manager-wide admission stay - * live. * @param parents - exact live roots whose continuable descendants must stop. - * @returns once every retained descendant Activation released its handle. - * @throws an aggregate error after all scoped branches settle when any failed. */ async drainDescendants(parents: readonly Agent[]): Promise { - const roots = new Set(parents.filter(parent => this.ctx.agents.get(parent.id) === parent)) - if (roots.size === 0) return - - // Publish the scoped admission cutoff before the first await. Merge with an - // earlier call for the same exact root so a converging drain cannot forget - // descendants whose release is already in flight. - for (const root of roots) { - this.closingMembers(root).add(root) - } - - const targets: Activation[] = [] - for (const activation of this.activations.values()) { - const lineage = this.liveLineage(activation.handle.agent) - // Strict descendants only: a continuable Agent may itself be a - // host-owned root, and its host remains responsible for that root handle. - const owners = [...roots].filter(root => activation.handle.agent !== root - && activation.ancestry.has(root)) - if (owners.length === 0) continue - targets.push(activation) - for (const owner of owners) { - const members = this.closingMembers(owner) - members.add(activation.handle.agent) - for (const agent of lineage) members.add(agent) - } - } - const materializations = [...this.materializations].filter((materialization) => { - const owners = [...roots].filter(root => materialization.lineage.includes(root)) - for (const owner of owners) { - const members = this.closingMembers(owner) - for (const agent of materialization.lineage) members.add(agent) - } - return owners.length > 0 - }) - - const ownedTargets = new Set() - for (const activation of targets) { - for (const child of activation.ownedChildren) ownedTargets.add(child) - } - const targetRoots = targets.filter(activation => !ownedTargets.has(activation.childId)) - - // Open every selected transaction before the materialization barrier. - // Disposal propagates cancellation top-down in the same synchronous span; - // handle release remains child-first. - for (const activation of targets) { - const disposal = this.dispose(activation) - void disposal.catch(() => undefined) - } - - await Promise.all(materializations.map(materialization => materialization.settled)) - await this.disposeRoots(targetRoots, 'scoped activation(s)') + await this.activations.drainDescendants(parents) } /** - * Release selected resident direct children of one exact live parent without - * closing admission for the parent's other continuable children. Owned - * descendants are released recursively through the same lifecycle. + * Release selected resident direct children of one exact live parent. * @param parent - exact live direct parent authorizing the selected release. * @param childIds - durable direct-child ids to release when resident. - * @returns once every selected Activation released its handle. - * @throws {SubagentError} `UNAUTHORIZED` when a resident target is not the - * parent's direct continuable child or the parent identity is stale. */ async drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise { - if (this.ctx.agents.get(parent.id) !== parent) { - throw new SubagentError('selected child teardown requires the exact live parent agent', 'UNAUTHORIZED') - } - const targets: Activation[] = [] - for (const childId of new Set(childIds)) { - const activation = this.activations.get(childId) - if (activation === undefined) continue - if (activation.parentSession !== parent.id || !activation.ancestry.has(parent)) { - throw new SubagentError( - `subagent "${childId}" is not a direct child of agent "${parent.id}"`, - 'UNAUTHORIZED', - ) - } - targets.push(activation) - } - - // Open every transaction before the first await so cancellation propagates - // across the selected roots in one synchronous span. - for (const activation of targets) { - const disposal = this.dispose(activation) - void disposal.catch(() => undefined) - } - await this.disposeRoots(targets, 'selected activation(s)') - } - - /** Dispose independent roots and report every branch failure after all settle. */ - private async disposeRoots( - roots: readonly Activation[], - failureSubject: 'activation(s)' | 'scoped activation(s)' | 'selected activation(s)', - ): Promise { - const failures = await Promise.all(roots.map(async (activation) => { - try { - await this.dispose(activation) - return undefined - } catch (error: unknown) { - return error - } - })) - const reasons = failures.filter(failure => failure !== undefined) - if (reasons.length > 0) { - throw new SubagentError( - `continuable subagent teardown failed for ${reasons.length} ${failureSubject}: ` - + reasons.map(reason => errorChain(reason)).join('; '), - 'ACTIVATION_TEARDOWN_FAILED', - ) - } - } - - /** Return the retained member set for one exact scoped-teardown root. */ - private closingMembers(root: Agent): Set { - const existing = this.closingScopes.get(root) - if (existing !== undefined) return existing - const members = new Set() - this.closingScopes.set(root, members) - return members + await this.activations.drainChildren(parent, childIds) } /** - * Return the exact currently resolvable ancestry from `agent` upward. The - * first element is always the supplied identity, even when it is already - * stale; each ancestor after it must be the registry's current exact entry. - */ - private liveLineage(agent: Agent): Agent[] { - const lineage = [agent] - const seen = new Set([agent.id]) - let parentSession = agent.session.header.parentSession - while (parentSession !== undefined) { - const parent = this.ctx.agents.get(parentSession) - if (parent === undefined || seen.has(parent.id)) break - lineage.push(parent) - seen.add(parent.id) - parentSession = parent.session.header.parentSession - } - return lineage - } - - /** - * The teardown that closed continuable admission for this agent's lineage. - * `'manager'` is the whole manager draining; an Agent is the exact scoped root - * whose forest is closing. - * @param agent - the agent whose lineage is tested. - * @returns the closing teardown, or `undefined` while admission is open. - */ - private closingTeardownFor(agent: Agent): Agent | 'manager' | undefined { - if (this.draining) return 'manager' - const lineage = this.liveLineage(agent) - for (const [root, members] of this.closingScopes) { - if (members.has(agent) || lineage.includes(root)) return root - } - return undefined - } - - /** Reject new admission once the manager or this exact parent tree began draining. */ - private assertAdmitting(agent: Agent): void { - const closing = this.closingTeardownFor(agent) - if (closing === undefined) return - throw new SubagentError( - closing === 'manager' - ? 'continuable subagents are draining; the operation was not admitted' - : `continuable subagents below parent "${closing.id}" are draining; the operation was not admitted`, - 'DRAINING', - ) - } - - /** - * Derive residency from Agent quiescence and the owned-child set. `running` - * covers an active admission, an open turn, or accepted waking inbox work. - * - * `Agent.status` alone is insufficient: it stays `idle` between an accepted - * waking send and the microtask that admits it, so a synchronous inbox - * observer would see `settled` while a turn is already queued. `accepted` - * holds the ids this manager admitted but has not yet seen drained. - */ - private stateOf(activation: Activation): ActivationState { - if (activation.handle.agent.status === 'running' || activation.accepted.size > 0) return 'running' - if (activation.ownedChildren.size > 0) return 'waiting' - return 'settled' - } - - /** - * Cold-resume a persisted child: retain and authorize its prepared Session, fold the - * generic descriptor, create the Activation through `ctx.agents.resume()`, - * and submit the waiting turn. This never dispatches through a subagent - * provider — the persisted Session already holds the initial prefix and the - * descriptor is the whole reconstruction input. + * Cold-resume a persisted child and submit the waiting turn. The descriptor + * supplies every reconstruction input; no subagent provider is dispatched. */ private async coldResume( parent: Agent, @@ -1081,13 +413,8 @@ export class SubagentContinuationManager { throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error }) } using source = observation - this.assertAdmitting(parent) - // Authorize the persisted header before folding: only the durable child's - // exact live direct parent may continue it. - this.authorizeLineage(parent, childId, source.header.parentSession) - // Fold only the child's own suffix: a fork seed replays the parent's log, - // which may carry an ANCESTOR's descriptor when the parent is itself a - // continuable child. + this.activations.assertAdmitting(parent) + this.activations.authorizeLineage(parent, childId, source.header.parentSession) const descriptor = foldSubagentDescriptor( source.events.slice(source.inheritedEventCount), ) @@ -1099,7 +426,7 @@ export class SubagentContinuationManager { } let activation: Activation try { - activation = await this.materialize({ + activation = await this.activations.materialize({ childId, provider: descriptor.provider, parent, @@ -1121,14 +448,7 @@ export class SubagentContinuationManager { return await this.submitMaterialized(activation, content, options, parent) } - /** - * Submit to a freshly materialized Activation or roll it back completely. - * @param activation - the just-published Activation to admit or release. - * @param content - the initial or resumed message content. - * @param options - durable source, scheduling, and pre-acceptance cancellation. - * @param parent - the live direct parent authorizing admission. - * @returns the accepted inbox message id. - */ + /** Submit to a freshly materialized Activation or roll it back completely. */ private async submitMaterialized( activation: Activation, content: ContentBlock[], @@ -1137,11 +457,8 @@ export class SubagentContinuationManager { ): Promise { try { if (contentHasImage(content)) { - // The capability read awaits with the activation already published, so - // the disposal cutoff is re-checked before the submit; a drain that - // began during the read turns into a clean closing rejection. await this.assertImageCapable(activation.handle.agent, options.signal) - if (activation.disposal !== undefined) { + if (activation.inbox.closing !== undefined) { throw new SubagentError(`subagent "${activation.childId}" is closing`, 'ACTIVATION_CLOSING') } } @@ -1149,23 +466,31 @@ export class SubagentContinuationManager { } catch (error: unknown) { /* v8 ignore next -- rollback disposal failures must not mask the * pre-acceptance signal, drain, or lifecycle failure. */ - await this.dispose(activation).catch(() => undefined) + await this.activations.dispose(activation).catch(() => undefined) throw error } } - /** - * Refuse image content addressed to a child whose model accepts text only. - * Callers guard with `contentHasImage`, so text-only delivery never awaits. - * The check runs inside the per-child delivery lock, before the message - * exists, so a rejection leaves no partial user message. When the child's - * route is not fixed by its options (a request-waterfall listener owns it) - * or no LLM registry is composed, delivery proceeds and the LLM layer's - * text-only projection replaces each image with its stable placeholder. - * @param agent - the live or freshly materialized child agent. - * @param signal - caller cancellation bounding the model-info read. - * @throws {SubagentError} `MODEL_DOES_NOT_SUPPORT_IMAGES` when the child's resolved model declines image input. - */ + /** Build and submit one message across the final synchronous admission cutoff. */ + private submitAdmitted( + activation: Activation, + content: ContentBlock[], + options: ChildDeliveryOptions, + parent: Agent, + ): MessageId { + const message = options.source === undefined + ? createAgentMessage(parent, content) + : createUserMessage({ content, source: options.source }) + return this.activations.submitAdmitted( + activation, + message, + options.delivery, + parent, + options.signal, + ) + } + + /** Refuse image content for a child whose fixed model accepts text only. */ private async assertImageCapable( agent: Agent, signal: AbortSignal, @@ -1173,8 +498,7 @@ export class SubagentContinuationManager { const { provider, model } = agent.options if (provider === undefined || model === undefined) return const llm = this.ctx.get('llm') - /* v8 ignore next -- a deployment without the LLM registry serves no model - * to refuse against; delivery then defers to the text-only projection. */ + /* v8 ignore next -- without an LLM registry, delivery defers to projection. */ if (llm === undefined) return const info = await llm.resolveModelInfo(provider, model, signal) if (info.inputModalities !== undefined && !info.inputModalities.includes('image')) { @@ -1185,518 +509,6 @@ export class SubagentContinuationManager { } } - /** - * Create or resume the child Agent through the private activation-owner - * scope, install the handle in a fresh Activation, and register ownership on - * a continuation-managed parent. Rejection leaves no Activation, no handle, - * and no ownership membership. - */ - private materialize(inputs: MaterializeInputs): Promise { - this.assertAdmitting(inputs.parent) - const settled = Promise.withResolvers() - const lineage = this.liveLineage(inputs.parent) - const materialization: Materialization = { - lineage, - settled: settled.promise, - } - this.materializations.add(materialization) - return this.materializeTracked(inputs, lineage).finally(() => { - this.materializations.delete(materialization) - settled.resolve() - }) - } - - /** - * Perform one tracked materialization. The caller keeps the drain barrier - * registered until this either returns a resident Activation or finishes - * rollback. - */ - private async materializeTracked( - inputs: MaterializeInputs, - parentLineage: readonly Agent[], - ): Promise { - const { childId, provider, parent, create } = inputs - // No id pre-check here: the child lock serializes each durable child, both - // callers reach this only after confirming no Activation exists, and - // `AgentRegistry.enter()` is the authoritative collision boundary for an id - // some other owner holds — a duplicate would reject there with rollback. - inputs.signal.throwIfAborted() - const setup = (childCtx: Context): void => { - const child = childCtx.agent as Agent - // Only fresh creation appends the descriptor and delegated policy after - // the inherited marker; a cold resume replays those persisted events. - if (create !== undefined) { - child.session.append('subagent/descriptor', create.descriptor) - appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies) - } - applyChildComposition(childCtx, parent, inputs.composition) - } - const observer = this.host.observeActivation(provider, childId, parent) - // Agent creation owns rollback before handle transfer. A rejection leaves - // no resident Activation and therefore publishes no lifecycle edge. - const handle: AgentHandle = create === undefined - ? await this.ownerCtx.agents.resume({ - resumeSessionId: childId, - agentOptions: inputs.agentOptions, - signal: inputs.signal, - setup, - }) - : await this.ownerCtx.agents.create({ - sessionId: childId, - meta: create.meta, - ...(create.seed === undefined ? {} : { seed: create.seed }), - inheritedEventCount: create.inheritedEventCount, - agentOptions: inputs.agentOptions, - signal: inputs.signal, - setup, - }) - - const activation: Activation = { - childId, - // The durable lineage, not merely the caller: creation stamps this same - // agent into the child's header, and cold resume authorized it against - // the persisted header before materializing. - parentSession: parent.id, - provider, - handle, - ancestry: new WeakSet([handle.agent, ...parentLineage]), - ownedChildren: new Set(), - observer, - disposal: undefined, - accepted: new Set(), - announced: false, - poke: Promise.withResolvers(), - } - // After transfer, any failure must dispose the created handle, remove the - // Activation, and roll back parent ownership before rejecting. - this.activations.set(childId, activation) - try { - inputs.signal.throwIfAborted() - this.assertAdmitting(parent) - this.acquireOwnership(parent, childId) - // Every accepted id leaves the inbox exactly once, through dequeue or - // discard. Clearing it there is what lets `stateOf()` distinguish a truly - // quiet Agent from one whose accepted turn has not been admitted yet. - // Registered through the child's own scoped context, so scope filtering - // already restricts both listeners to this exact agent. - handle.agent.ctx.on('agent/inbox/claimed', ({ message }) => { - /* v8 ignore next -- a claim of an id this manager never admitted needs - * another sender on the same child, which no current path allows. */ - if (activation.accepted.delete(message.id)) this.wake(activation) - }) - handle.agent.ctx.on('agent/inbox/discarded', ({ message }) => { - if (activation.accepted.delete(message.id)) this.wake(activation) - }) - // Agent creation committed setup at its publication boundary; - // revocations from here on are immediate live revocation. - // Publish the start edge before any turn can run, so observers see this - // epoch before its first request. - observer.start(handle.agent) - } catch (error: unknown) { - // Listener exceptions are contained by the lifecycle emitter; a start - // publication throw therefore leaves no residency edge to pair. - /* v8 ignore next -- rollback failure must not mask the admission failure - * that prevented this operation from returning an accepted message id. */ - await this.rollbackUnpublished(activation).catch(() => undefined) - throw error - } - this.watchSettlement(activation) - return activation - } - - /** - * Release an Activation whose start edge was not published. The memoized - * transaction remains in the live map until handle disposal settles, so a - * concurrent drain or delivery observes the same closing boundary. - */ - private rollbackUnpublished(activation: Activation): Promise { - return (activation.disposal ??= (async () => { - try { - await activation.handle.dispose() - } finally { - this.activations.delete(activation.childId) - this.releaseOwnership(activation.childId) - } - })()) - } - - /** - * Register the child in a continuation-managed parent's owned set before the - * child can run, so that parent cannot settle while the child is live. A - * top-level or other non-continuation Agent has no Activation and stays - * outside the waiting graph. - */ - private acquireOwnership(parent: Agent, childId: SessionId): void { - const parentActivation = this.activations.get(parent.id) - if (parentActivation === undefined) return - if (parentActivation.disposal !== undefined) { - throw new SubagentError( - `subagent parent "${parent.id}" is being disposed; the child was not established`, - 'ACTIVATION_CLOSING', - ) - } - parentActivation.ownedChildren.add(childId) - } - - /** Remove one child from its live owner's set and let that owner re-check settlement. */ - private releaseOwnership(childId: SessionId): void { - for (const candidate of this.activations.values()) { - if (candidate.ownedChildren.delete(childId)) this.wake(candidate) - } - } - - /** Let a settlement watcher re-observe quiescence after ownership or inbox changes. */ - private wake(activation: Activation): void { - activation.poke.resolve() - activation.poke = Promise.withResolvers() - } - - /** - * Submit one message as the child's next FIFO turn and return its accepted - * inbox id. Acceptance is the operation's success boundary; the manager owns - * the Activation independently afterwards. - */ - private submit( - activation: Activation, - content: ContentBlock[], - options: ChildDeliveryOptions, - parent: Agent, - ): MessageId { - // Parent-originated delivery keeps the parent live through ownership, so - // establish it before the message can enter the child's inbox. - this.acquireOwnership(parent, activation.childId) - const message = options.source === undefined - ? agentMessage(parent, content) - : createUserMessage({ content, source: options.source }) - const accepted = this.admitWaking(activation, message.id, () => { - if (options.delivery === 'steer') activation.handle.agent.steer(message) - else activation.handle.agent.followup(message) - }) - // Past this point the caller has an id for this child, so its eventual - // settlement is something the parent is owed an account of. - activation.announced = true - return accepted - } - - /** - * Account one waking send across a resident Activation's settlement window. - * @param activation - Activation receiving waking inbox work. - * @param messageId - stable identity of the message about to be sent. - * @param send - synchronous send that publishes one enqueue occurrence. - * @returns the accepted message id. - */ - private admitWaking( - activation: Activation, - messageId: MessageId, - send: () => void, - ): MessageId { - // Waking Agent sends publish inbox events synchronously, so observers must - // see this Activation as busy before the call begins. - activation.accepted.add(messageId) - try { - send() - } catch (error: unknown) { - activation.accepted.delete(messageId) - throw error - } - // Accepted waking work keeps this Activation live until whenIdle() observes - // the complete waking suffix. - this.wake(activation) - return messageId - } - - /** - * Cross the final admission cutoff and submit without yielding. Signal abort, - * manager drain, or Activation disposal that wins before this synchronous - * span rejects without inbox acceptance. - */ - private submitAdmitted( - activation: Activation, - content: ContentBlock[], - options: ChildDeliveryOptions, - parent: Agent, - ): MessageId { - options.signal.throwIfAborted() - this.assertAdmitting(parent) - /* v8 ignore next 6 -- only a synchronous re-entrant disposer can change - * this field between the caller's live check and this no-await boundary. */ - if (disposalOf(activation) !== undefined) { - throw new SubagentError( - `subagent "${activation.childId}" activation is being disposed; the message was not accepted`, - 'ACTIVATION_CLOSING', - ) - } - this.authorizeLineage( - parent, - activation.childId, - activation.handle.agent.session.header.parentSession, - ) - return this.submit(activation, content, options, parent) - } - - /** - * Authorize one operation against the durable direct-parent lineage. Other - * agents, ancestors, teams, workflows, and hosts remain rejected until an - * explicit authority protocol has a production consumer. - */ - private authorizeLineage( - parent: Agent, - childId: SessionId, - parentSession: SessionId | undefined, - ): void { - if (this.ctx.agents.get(parent.id) !== parent) { - throw new SubagentError( - `subagent "${childId}" delivery requires the exact live parent agent`, - 'UNAUTHORIZED', - ) - } - if (parentSession !== parent.id) { - throw new SubagentError(`subagent "${childId}" belongs to another parent session`, 'UNAUTHORIZED') - } - } - - /** - * Follow one Activation to settlement: wait for Agent quiescence, then for - * every owned child to complete disposal, and dispose the handle once both - * hold. A `next-turn` delivered while `waiting` wakes the same Agent and - * returns it to `running`, so this re-observes rather than settling early. - */ - private watchSettlement(activation: Activation): void { - void (async () => { - while (disposalOf(activation) === undefined) { - const poked = activation.poke.promise - await Promise.race([activation.handle.agent.whenIdle(), poked]) - if (disposalOf(activation) !== undefined) return - // Re-check settlement INSIDE the child lock and begin disposal in the - // same critical section, so a concurrent delivery either wins admission - // before the transaction opens or waits for release and cold-resumes. - // Deciding outside the lock would let a delivery observe a not-yet - // resident handle that this watcher is already about to tear down. - const settling = await this.locks.run(activation.childId, () => { - if (disposalOf(activation) !== undefined || this.stateOf(activation) !== 'settled') { - return Promise.resolve({ settling: false }) - } - // `dispose()` assigns its memoized transaction synchronously, so - // admission is closed before this critical section releases. - return Promise.resolve({ settling: true, done: this.dispose(activation) }) - }) - if (!settling.settling) { - // Still running, or waiting on descendants: re-observe after the next - // accepted message or ownership release. - if (activation.handle.agent.status !== 'running') await poked - continue - } - try { - await settling.done - } catch (error: unknown) { - this.ctx.logger.warn( - `subagent "${activation.childId}" activation teardown failed: ${errorChain(error)}`, - ) - } - return - } - })() - } - - /** - * Stop one Activation immediately, then release it child-first. The memoized - * transaction is installed before cancellation or recursive callbacks, so - * admission and reentrant teardown converge on the same owner. - * - * The final session flush is best effort and never prevents handle disposal - * or ownership release, because retaining a child would permanently pin its - * ancestors in `waiting`. - * @param activation - the residency epoch to stop and release. - * @returns the one disposal transaction owned by this Activation. - */ - private dispose(activation: Activation): Promise { - const existing = activation.disposal - if (existing !== undefined) return existing - const completion = Promise.withResolvers() - // Presence is the admission cutoff. Assign it before the async helper starts - // because that helper cancels Agents and may synchronously re-enter callers. - activation.disposal = completion.promise - void this.finishDisposal(activation).then(completion.resolve, completion.reject) - return completion.promise - } - - /** - * Propagate stop synchronously, then finish the child-first release. - * @param activation - the Activation whose disposal transaction is installed. - * @returns once the handle and ownership edge are released. - */ - private async finishDisposal(activation: Activation): Promise { - this.wake(activation) - const { childId } = activation - // Stop top-down before the first await. Slow descendant cleanup may delay - // release, but it cannot let this ancestor continue model or tool work. - activation.handle.agent.cancel({ kind: 'parent' }) - const idle = activation.handle.agent.whenIdle() - const children = [...activation.ownedChildren] - .map(child => this.activations.get(child)) - .filter((child): child is Activation => child !== undefined) - const childDisposals = children.map(child => this.dispose(child)) - - const failures: SubagentError[] = [] - try { - // Release remains child-first even though cancellation propagated - // top-down: every owned child completes before this handle is removed. - const childFailures = await Promise.all(childDisposals.map(async (disposal) => { - try { - await disposal - return undefined - } catch (error: unknown) { - return error - } - })) - const reasons = childFailures.filter(reason => reason !== undefined) - if (reasons.length > 0) { - failures.push(new SubagentError( - `subagent "${childId}" child teardown failed: ${reasons.map(reason => errorChain(reason)).join('; ')}`, - 'ACTIVATION_TEARDOWN_FAILED', - )) - } - // Quiesce before the flush: a turn still running would keep - // appending events the flush cannot cover. - await idle - await this.flushFinalState(activation) - // Capture the child-dependent edge data while the child is still live: - // handle disposal unregisters it, and consumers read its log and scope. - activation.observer.capture(activation.handle.agent) - } catch (error: unknown) { - failures.push(new SubagentError( - `subagent "${childId}" activation teardown failed: ${errorChain(error)}`, - 'ACTIVATION_TEARDOWN_FAILED', - { cause: error }, - )) - } - try { - await activation.handle.dispose() - } catch (error: unknown) { - failures.push(new SubagentError( - `subagent "${childId}" activation handle disposal failed: ${errorChain(error)}`, - 'ACTIVATION_TEARDOWN_FAILED', - { cause: error }, - )) - } - - let failure: SubagentError | undefined - if (failures.length === 1) { - failure = failures[0] - } else if (failures.length > 1) { - failure = new SubagentError( - `subagent "${childId}" activation teardown failed at ${failures.length} boundaries: ` - + failures.map(item => errorChain(item)).join('; '), - 'ACTIVATION_TEARDOWN_FAILED', - { cause: new AggregateError(failures) }, - ) - } - // Only now is the Activation gone: keeping the entry until disposal settles - // makes a racing delivery wait for release rather than cold-resume into the - // still-registered agent. - this.activations.delete(childId) - // BEFORE releasing ownership, while the parent still counts this child and - // therefore cannot be judged settled. Delivering after the release would - // race a parent watcher that resumes one microtask later, finds itself - // childless and quiet, and disposes an Agent whose `cancel()` clears the - // inbox this notice is sitting in. - this.notifySettlement(activation, activation.observer.terminal(failure)) - // Release ownership even on failure: a retained failed child would pin its - // ancestors in `waiting` forever. - this.releaseOwnership(childId) - // Emit once the disposal outcome is known, so a rejecting scoped cleanup - // cannot be reported as a successful epoch. - activation.observer.settle(failure) - if (failure !== undefined) throw failure - } - - /** - * Tell the durable direct parent that this child produced everything it is - * going to. Unconditional for every child the caller received an id for: it - * does not consider whether the child reported, because the cases that most - * need it — a token ceiling, a model failure, cancellation, teardown — are - * exactly the ones where the child never got to choose. A materialization - * rolled back before its first acceptance stays silent, since the caller was - * told that child was not established. A parent that is no longer live is not - * an error; the child's own Session remains the durable record either way. - * A parent whose own lineage is already closing receives the notice without a - * wake, because teardown is not a reason to start a turn. - * - * Never blocks disposal. A delivery failure is logged and dropped, because - * retaining a child to retry a notice would pin its whole ancestry in - * `waiting` forever. - * @param activation - the settling Activation, still owned by its parent. - * @param terminal - how this epoch ended, as the terminal edge will report it. - */ - private notifySettlement(activation: Activation, terminal: ActivationTerminal): void { - if (!activation.announced) return - try { - const parent = this.ctx.agents.get(activation.parentSession) - if (parent === undefined) return - const summary = settlementSummary(activation.childId, terminal.stopReason) - const message = createUserMessage({ - content: [ - { type: 'text' as const, text: summary }, - ...terminal.output === undefined - ? [{ type: 'text' as const, text: 'It left no closing message.' }] - : [{ type: 'text' as const, text: 'Its closing message:' }, ...terminal.output], - ], - source: { - kind: 'subagent-settled' as const, - form: 'notice' as const, - summary: boundContextSummary(summary), - senderSessionId: activation.childId, - }, - }) - // A parent whose own teardown already began must not be woken. Waking is - // not a queue operation: `followup()` on a quiescent Agent starts a turn, - // and `cancel()` does not arm against a later one, so a notice arriving - // during teardown would spend a model request on an Agent its host is - // about to dispose — once per tree layer, since each layer's own notice - // then wakes the layer above it. Injecting delivers to a parent still - // reading its inbox and records the account in the log either way; it - // does NOT survive that parent's own disposal, whose `keepInbox: false` - // cancel durably clears whatever it never claimed. - if (this.closingTeardownFor(parent) !== undefined) { - parent.inject(message) - return - } - // An idle parent has nothing else to look at, so it gets one ordinary - // turn. A busy parent is steered instead of woken: `Inbox.claim()` takes - // the whole next-step batch at one boundary, so several children settling - // together cost one step rather than one turn each. Steering rather than - // injecting closes the window where a driver retires between this status - // read and the send, which would strand the notice unclaimed. - this.sendWaking(parent, message, () => { - if (parent.status === 'idle') parent.followup(message) - else parent.steer(message) - }) - } catch (error: unknown) { - this.ctx.logger.warn( - `subagent "${activation.childId}" settlement notice was not delivered to its parent: ` - + errorChain(error), - ) - } - } - - /** - * Request a best-effort final session flush after the child is quiescent. - * Listener failure is logged because flush participation cannot identify a - * particular persistence backend, and teardown must still release ownership. - * @param activation - the Activation whose final events should be flushed. - */ - private async flushFinalState(activation: Activation): Promise { - const child = activation.handle.agent - try { - await child.ctx.sessions.flush(child.session) - } catch (error: unknown) { - this.ctx.logger.warn( - `subagent "${activation.childId}" best-effort final session flush failed; ` - + `the persisted state may be unavailable or stale on resume: ${errorChain(error)}`, - ) - } - } - /** Resolve the persistence service continuable children require, or fail loud. */ private requirePersistence(): SessionPersistence { const persistence = this.ctx.get('sessionPersistence') @@ -1720,8 +532,6 @@ export class SubagentContinuationManager { } return query } - } -export type { SubagentDescriptorData } export default SubagentContinuationManager diff --git a/packages/subagent/subagent/src/control-types.ts b/packages/subagent/subagent/src/control-types.ts index aaf69de0f8..0325da892f 100644 --- a/packages/subagent/subagent/src/control-types.ts +++ b/packages/subagent/subagent/src/control-types.ts @@ -102,6 +102,8 @@ export interface SubagentPromptRequest { readonly childSessionId: SessionId /** Required discriminator retained from the browser control address. */ readonly mode: 'continuable' + /** Whether this message queues a later turn or targets the nearest step. */ + readonly delivery: 'queue' | 'steer' /** * Browser prompt parts delivered as the child's user message. The Host * admits and persists image parts before delivery, so the wire never diff --git a/packages/subagent/subagent/src/control.ts b/packages/subagent/subagent/src/control.ts index 41893ae93c..25fe4f475b 100644 --- a/packages/subagent/subagent/src/control.ts +++ b/packages/subagent/subagent/src/control.ts @@ -21,6 +21,7 @@ const CONTROL_ID_SCHEMAS = { parentSessionId: SESSION_ID_SCHEMA, childSessionId: SESSION_ID_SCHEMA, mode: z.literal('continuable'), + delivery: z.enum(['queue', 'steer']), }), 'subagent.interrupt': z.object({ parentSessionId: SESSION_ID_SCHEMA, diff --git a/packages/subagent/subagent/src/inbox.ts b/packages/subagent/subagent/src/inbox.ts new file mode 100644 index 0000000000..8800e3ce2b --- /dev/null +++ b/packages/subagent/subagent/src/inbox.ts @@ -0,0 +1,70 @@ +/** + * Activation-local admission around one continuable subagent's Agent inbox. + * + * @module @deepseek-ai/dsh-subagent/inbox + */ + +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { UserMessage } from '@deepseek-ai/dsh-session' +import type { SubagentPromptRequest } from './control-types.ts' +import { SubagentError } from './error.ts' + +/** One Agent inbox destination, as the wire request selects it. */ +export type SubagentDelivery = SubagentPromptRequest['delivery'] + +/** Delegate Queue and Steer to one live Agent until its Activation starts closing. */ +export class SubagentInbox { + private closingPromise: Promise | undefined + + /** + * Wrap one live continuable Agent. + * @param agent - the Agent whose inbox receives accepted deliveries. + */ + constructor(private readonly agent: Agent) {} + + /** + * Read the Activation's close transaction. + * @returns the memoized transaction, or `undefined` while delivery remains open. + */ + get closing(): Promise | undefined { + return this.closingPromise + } + + /** + * Read whether the underlying Agent still has accepted work to claim. + * @returns whether either Agent inbox destination is non-empty. + */ + get hasPending(): boolean { + return this.agent.inbox.hasPending + } + + /** + * Submit through the Agent only while its Activation remains resident. + * @param message - the accepted input to submit. + * @param delivery - whether to queue a distinct turn or steer the nearest step. + */ + deliver(message: UserMessage, delivery: SubagentDelivery): void { + if (this.closingPromise !== undefined) { + throw new SubagentError( + `subagent "${this.agent.id}" activation is being disposed; the message was not accepted`, + 'ACTIVATION_CLOSING', + ) + } + if (delivery === 'steer') this.agent.steer(message) + else this.agent.followup(message) + } + + /** + * Close delivery synchronously and share one asynchronous release. + * @param release - the one release operation to start after closing admission. + * @returns the memoized release transaction. + */ + close(release: () => Promise): Promise { + const existing = this.closingPromise + if (existing !== undefined) return existing + const completion = Promise.withResolvers() + this.closingPromise = completion.promise + void release().then(completion.resolve, completion.reject) + return completion.promise + } +} diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts index 96f989bb50..88977cdcae 100644 --- a/packages/subagent/subagent/src/index.ts +++ b/packages/subagent/subagent/src/index.ts @@ -52,12 +52,16 @@ import type { import type { ContinuableCreateRequest, ContinuableCreateSpec, + ContinuableStart, + ContinuableStartSpec, ResolvedSubagentStartRequest, SubagentCapabilities, + SubagentInterruptAuthority, SubagentProvider, SubagentRun, SubagentRunEndInfo, SubagentRunInfo, + SubagentSendMessageOptions, SubagentStartRequest, } from './types.ts' import { SubagentError } from './error.ts' @@ -65,17 +69,12 @@ import { assertSubagentMaxDepth } from './depth.ts' import { createActivationObserver, createLifecycleEmitter, observeRun } from './lifecycle.ts' import type { ActivationObserver, LifecycleEmitter } from './lifecycle.ts' import SubagentContinuationManager from './continuation.ts' -import type { - ContinuableStart, - ContinuableStartSpec, - SubagentInterruptAuthority, - SubagentSendMessageOptions, -} from './continuation.ts' +import type { SubagentDelivery } from './inbox.ts' import { listChildren as listSubagentChildren, listDescendants as listSubagentDescendants } from './list-children.ts' import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts' import { snapshotSubagentDescriptor } from './descriptor.ts' import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts' -import { deliverSubagentPrompt, type HostPromptDeliveryMode } from './internal.ts' +import { deliverSubagentPrompt } from './internal.ts' export * from './out-of-process.ts' export { AssistantOutputFold, finalAssistantOutput } from './assistant-output.ts' @@ -83,11 +82,15 @@ export { SubagentRunId } from './types.ts' export type { ContinuableCreateRequest, ContinuableCreateSpec, + ContinuableStart, + ContinuableStartSpec, ResolvedSubagentStartRequest, SubagentCapabilities, + SubagentInterruptAuthority, SubagentProvider, SubagentResult, SubagentRun, + SubagentSendMessageOptions, SubagentStartRequest, SubagentStopReason, SubagentStopReasonMap, @@ -119,14 +122,7 @@ export { SubagentDepthError, } from './child-agent.ts' export type { ChildComposition, DelegatedPolicyOverrides } from './child-agent.ts' -export type { - AgentMessageSource, - ContinuableStart, - ContinuableStartSpec, - SubagentInterruptAuthority, - SubagentSendMessageOptions, - SubagentSettledMessageSource, -} from './continuation.ts' +export type { AgentMessageSource, SubagentSettledMessageSource } from './continuation-messages.ts' export type * from './control-types.ts' export type { SubagentDescendantListEntry } from './list-children.ts' export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts' @@ -271,7 +267,7 @@ export class SubagentRuntime extends TypertRemoteService { content: ContentBlock[], source: MessageSource, signal: AbortSignal, - delivery: HostPromptDeliveryMode, + delivery: SubagentDelivery, ): Promise { return delivery === 'steer' ? this.requireContinuations().steerPrompt(parent, childId, content, source, signal) @@ -397,11 +393,12 @@ export class SubagentRuntime extends TypertRemoteService { * Deliver one browser-authored message to a continuable child through the * exact live direct parent, retaining the caller-minted request identity and * validated browser zone on the accepted message. Success identifies the - * message the child's FIFO inbox accepted; later execution is independent of - * this call. + * message the child's inbox accepted; later execution is independent of this + * call. Queue delivery targets a later turn; steer delivery targets the + * nearest step and retains the Agent loop's best-effort fallback semantics. * Image parts are admitted and persisted through the attachment store * before delivery, and the child's model must accept image input. - * @param request - durable address, minted identity, content, and optional browser zone. + * @param request - durable address, delivery, minted identity, content, and optional browser zone. * @param signal - carrier cancellation, owning the call until inbox acceptance. * @returns the accepted message's inbox identity. * @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`, @@ -411,7 +408,7 @@ export class SubagentRuntime extends TypertRemoteService { */ @Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise { - const { parentSessionId, childSessionId, clientTimeZone } = request + const { parentSessionId, childSessionId, clientTimeZone, delivery } = request validateControlRequest('subagent.prompt', request) const canonicalTimeZone = clientTimeZone === undefined ? undefined @@ -454,7 +451,7 @@ export class SubagentRuntime extends TypertRemoteService { content, source, signal, - 'queue', + delivery, ), } } catch (error: unknown) { diff --git a/packages/subagent/subagent/src/internal.ts b/packages/subagent/subagent/src/internal.ts index 51bca12607..642cf98943 100644 --- a/packages/subagent/subagent/src/internal.ts +++ b/packages/subagent/subagent/src/internal.ts @@ -9,6 +9,7 @@ import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-ll import type { SessionId } from '@deepseek-ai/dsh-session' import type { ToolDefinition } from '@deepseek-ai/dsh-tools' import type SubagentRuntime from './index.ts' +import type { SubagentDelivery } from './inbox.ts' /** Process-stable identity carried only by the standard adjacent-Agent messaging tool. */ export const adjacentAgentSendMessageTool = Symbol.for('dsh.subagent.adjacentAgentSendMessageTool') @@ -40,9 +41,6 @@ export function isAdjacentAgentSendMessageTool(definition: ToolDefinition | unde */ export const deliverSubagentPrompt = Symbol.for('dsh.subagent.deliverPrompt') -/** Scheduling mode for one host-only direct-child prompt. */ -export type HostPromptDeliveryMode = 'queue' | 'steer' - /** Runtime face required by the host-only prompt adapters. */ export interface HostPromptDeliverer { [deliverSubagentPrompt]( @@ -51,7 +49,7 @@ export interface HostPromptDeliverer { content: ContentBlock[], source: MessageSource, signal: AbortSignal, - delivery: HostPromptDeliveryMode, + delivery: SubagentDelivery, ): Promise } diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts index de8ff6d6b9..1b9ce56c3f 100644 --- a/packages/subagent/subagent/src/types.ts +++ b/packages/subagent/subagent/src/types.ts @@ -11,7 +11,7 @@ import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent' import type { Branded } from '@deepseek-ai/dsh-brand' -import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm' import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session' import type { ObjectJsonSchema, ToolRestriction } from '@deepseek-ai/dsh-tools' import type { SubagentDescriptorData } from './descriptor.ts' @@ -28,6 +28,50 @@ export function SubagentRunId(id: string): SubagentRunId { return id as SubagentRunId } +/** What a caller asks for when starting a continuable background child. */ +export interface ContinuableStartSpec { + /** The `ctx.subagents` provider whose continuable-creation capability establishes the child. */ + readonly provider: string + /** The initial delegation's short `description`, persisted as the child's creation label. */ + readonly label: string + /** + * Optional caller-reserved child identity. Omission preserves the manager's + * UUID allocation; supplying one lets a durable parent record provisioning + * before child materialization without a second identity handshake. + */ + readonly childId?: SessionId + /** + * The delegation request. The manager reserves the stable child id, resolves + * the durable descriptor, and composes the child itself. + */ + readonly request: Omit + /** Caller cancellation, owning the operation only until inbox acceptance. */ + readonly signal: AbortSignal +} + +/** Identities returned once a continuable child accepted its initial prompt. */ +export interface ContinuableStart { + /** The durable child session id, stable across activations. */ + readonly childId: SessionId + /** The accepted initial prompt's inbox message id. */ + readonly messageId: MessageId +} + +/** + * Authority under which one interrupt request is admitted. `user` carries the + * durable direct-parent address a human client presented; `ancestor` carries + * the exact live Agent object whose recorded lineage must contain the caller. + */ +export type SubagentInterruptAuthority = + | { readonly kind: 'user'; readonly parentSessionId: SessionId } + | { readonly kind: 'ancestor'; readonly agent: Agent } + +/** Options for one model-authored message between adjacent Agents. */ +export interface SubagentSendMessageOptions { + /** Caller cancellation, owning the operation only until inbox acceptance. */ + readonly signal: AbortSignal +} + /** * Observe-only identifying detail for a published subagent run, carried by * `subagent/start`. One-shot runs and continuable Activation epochs share this diff --git a/packages/subagent/subagent/tests/continuation-internals.ts b/packages/subagent/subagent/tests/continuation-internals.ts new file mode 100644 index 0000000000..ba45872701 --- /dev/null +++ b/packages/subagent/subagent/tests/continuation-internals.ts @@ -0,0 +1,30 @@ +/** Package-private continuation owners used to place deterministic lifecycle races. */ + +import type { Context } from '@deepseek-ai/cordis' +import type { SessionId } from '@deepseek-ai/dsh-session' +import type { Activation, ContinuableActivationRegistry } from '../src/continuation-activation.ts' +import type SubagentContinuationManager from '../src/continuation.ts' + +/** Return the service's bound continuation manager. */ +export function continuationManager(ctx: Context): SubagentContinuationManager { + const manager = (ctx.subagents as unknown as { + continuations?: SubagentContinuationManager + }).continuations + if (manager === undefined) throw new Error('expected a bound continuation manager') + return manager +} + +/** Return the manager's sole process-local Activation owner. */ +export function continuationActivations(ctx: Context): ContinuableActivationRegistry { + return (continuationManager(ctx) as unknown as { + activations: ContinuableActivationRegistry + }).activations +} + +/** Remove only the registry entry, leaving its Agent live for collision coverage. */ +export function dropContinuationActivation(ctx: Context, childId: SessionId): void { + const registry = continuationActivations(ctx) as unknown as { + resident: Map + } + registry.resident.delete(childId) +} diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts index 68072264e3..8e082debe4 100644 --- a/packages/subagent/subagent/tests/continuation.spec.ts +++ b/packages/subagent/subagent/tests/continuation.spec.ts @@ -22,9 +22,15 @@ import SubagentRuntime, { SUBAGENT_DESCRIPTOR_VERSION, } from '../src/index.ts' import type { SubagentRunEndInfo, SubagentRunInfo } from '../src/index.ts' +import type { SubagentPromptRequestId } from '../src/control-types.ts' import * as SubagentInvariant from '../src/invariant.ts' import { TestSessionQuery } from './test-session-query.ts' import { loadStoredSession } from './persistence-helpers.ts' +import { + continuationActivations, + continuationManager, + dropContinuationActivation, +} from './continuation-internals.ts' type Script = ConstructorParameters[0] @@ -125,6 +131,11 @@ function hasUserText(events: readonly SessionEvent[], text: string): boolean { && event.data.content.some(block => block.type === 'text' && block.text === text)) } +function hasAssistantText(events: readonly SessionEvent[], text: string): boolean { + return events.some(event => event.type === 'assistant/message' + && event.data.message.content.some(block => block.type === 'text' && block.text === text)) +} + /** Caller-supplied user message texts in log order (runtime-context snapshots excluded). */ function userTexts(events: readonly SessionEvent[]): string[] { return events.flatMap(event => event.type === 'user/message' && event.data.source.kind !== 'plugin' @@ -142,19 +153,24 @@ function queuePrompt( content: ContentBlock[], signal: AbortSignal = testSignal, ) { - const manager = (ctx.subagents as unknown as { - continuations?: { - queuePrompt( - parent: Agent, - childId: SessionId, - content: ContentBlock[], - source: { kind: 'user' }, - signal: AbortSignal, - ): Promise - } - }).continuations - if (manager === undefined) throw new Error('expected a bound continuation manager') - return manager.queuePrompt(parent, childId, content, { kind: 'user' }, signal) + return continuationManager(ctx).queuePrompt(parent, childId, content, { kind: 'user' }, signal) +} + +function humanPrompt( + ctx: Context, + parent: Agent, + childId: SessionId, + text: string, + delivery: 'queue' | 'steer', +) { + return ctx.subagents.prompt({ + requestId: `request-${text}` as SubagentPromptRequestId, + parentSessionId: parent.id, + childSessionId: childId, + mode: 'continuable', + delivery, + content: message(text), + }, testSignal) } /** @@ -162,11 +178,7 @@ function queuePrompt( * adding the irreversible operation to the public service contract. */ function drainManager(ctx: Context): Promise { - const manager = (ctx.subagents as unknown as { - continuations?: { drain(): Promise } - }).continuations - if (manager === undefined) throw new Error('expected a bound continuation manager') - return manager.drain() + return continuationManager(ctx).drain() } /** Wait until a child's Activation is gone, i.e. its handle finished disposal. */ @@ -176,6 +188,46 @@ async function waitNoActivation(ctx: Context, childId: SessionId): Promise }, { timeout: 5_000 }) } +/** Wait until the settlement watcher has checked the child's current idle state. */ +async function passSettlementCheck(ctx: Context, childId: SessionId): Promise { + const manager = childLocks(ctx) + const release = Promise.withResolvers() + const entered = Promise.withResolvers() + const barrier = manager.locks.run(childId, async () => { + entered.resolve(undefined) + await release.promise + }) + await entered.promise + release.resolve(undefined) + await barrier + await manager.locks.run(childId, () => Promise.resolve()) +} + +/** The Activation registry's package-private lock, which orders every child decision. */ +function childLocks(ctx: Context) { + return continuationActivations(ctx) +} + +/** + * Occupy one child's lock so a settlement watcher that already observed + * quiescence waits behind the caller, which is the window where later Agent + * activity or Inbox changes race disposal. + * @returns the release callback and the held lock's completion. + */ +async function holdChildLock( + ctx: Context, + childId: SessionId, +): Promise<{ release: () => void; held: Promise }> { + const entered = Promise.withResolvers() + const release = Promise.withResolvers() + const held = childLocks(ctx).locks.run(childId, async () => { + entered.resolve(undefined) + await release.promise + }) + await entered.promise + return { release: () => { release.resolve(undefined) }, held } +} + /** * Keep the top-level test parent out of a scripted model corpus. Every child * settlement wakes its parent, so a suite that scripts only child responses @@ -917,6 +969,46 @@ describe('direct-child Queue residency routing', () => { }) }) +describe('continuable human steering delivery', () => { + it('places resident steering in nextStep with its durable identity and source', async () => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([ + { chunks: textResponse('first'), gate: release.promise }, + { chunks: textResponse('steered') }, + ]) + const { ctx, parent } = await setupWith(adapter) + parkParent(ctx, parent) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + + const receipt = await humanPrompt(ctx, parent, started.childId, 'resident steer', 'steer') + expect(child.inbox.nextStep).toContainEqual(expect.objectContaining({ + id: receipt.messageId, + content: message('resident steer'), + source: { kind: 'user', rpcId: 'request-resident steer' }, + })) + + release.resolve(undefined) + await waitNoActivation(ctx, started.childId) + }) + + it('cold-resumes steering into nextStep instead of inventing another queue', async () => { + const { ctx, parent } = await setup([textResponse('first'), textResponse('steered')]) + parkParent(ctx, parent) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await waitNoActivation(ctx, started.childId) + + const receipt = await humanPrompt(ctx, parent, started.childId, 'cold steer', 'steer') + await waitNoActivation(ctx, started.childId) + const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId) + expect(loaded.events.some(event => event.type === 'agent/inbox/spliced' + && event.data.target === 'next-step' + && event.data.inserted.some(message => message.id === receipt.messageId))).toBe(true) + expect(hasUserText(loaded.events, 'cold steer')).toBe(true) + }) +}) + describe('continuable child ownership', () => { it('keeps a parent Activation waiting until its child completes disposal', async () => { const releaseGrandchild = Promise.withResolvers() @@ -956,6 +1048,187 @@ describe('continuable child ownership', () => { }) describe('continuable durability and teardown', () => { + it('rechecks direct Agent inbox work accepted during the final flush', async () => { + const releaseFirstTurn = Promise.withResolvers() + const adapter = new GatedAdapter([ + { chunks: textResponse('first answer'), gate: releaseFirstTurn.promise }, + { chunks: textResponse('late answer') }, + ]) + const { ctx, parent } = await setupWith(adapter) + parkParent(ctx, parent) + const flushing = Promise.withResolvers() + const releaseFlush = Promise.withResolvers() + let childFlushes = 0 + ctx.on('session/flush', async (session) => { + if (session.header.parentSession === undefined) return + childFlushes++ + if (childFlushes !== 1) return + flushing.resolve(undefined) + await releaseFlush.promise + }) + + const started = await ctx.subagents.startContinuable(startSpec(parent)) + const child = ctx.agents.get(started.childId)! + const cancelSpy = vi.spyOn(child, 'cancel') + releaseFirstTurn.resolve(undefined) + await flushing.promise + expect(cancelSpy).not.toHaveBeenCalled() + child.followup(createUserMessage({ content: message('accepted during flush'), source: { kind: 'user' } })) + await vi.waitFor(() => { + expect(adapter.requests).toHaveLength(2) + expect(hasAssistantText(child.session.snapshotEvents(), 'late answer')).toBe(true) + }) + await child.whenIdle() + expect(cancelSpy).not.toHaveBeenCalled() + releaseFlush.resolve(undefined) + await waitNoActivation(ctx, started.childId) + expect(childFlushes).toBe(2) + const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId) + expect(hasUserText(loaded.events, 'accepted during flush')).toBe(true) + expect(hasAssistantText(loaded.events, 'late answer')).toBe(true) + }) + + it('retries after Session-only work completes during the final flush', async () => { + const releaseFirstTurn = Promise.withResolvers() + const adapter = new GatedAdapter([ + { chunks: textResponse('answer'), gate: releaseFirstTurn.promise }, + ]) + const { ctx, parent } = await setupWith(adapter) + parkParent(ctx, parent) + const flushing = Promise.withResolvers() + const releaseFlush = Promise.withResolvers() + let childFlushes = 0 + ctx.on('session/flush', async (session) => { + if (session.header.parentSession === undefined) return + childFlushes++ + if (childFlushes !== 1) return + flushing.resolve(undefined) + await releaseFlush.promise + }) + + const started = await ctx.subagents.startContinuable(startSpec(parent)) + const child = ctx.agents.get(started.childId)! + releaseFirstTurn.resolve(undefined) + await flushing.promise + child.session.append('user/message', createUserMessage({ + content: message('detached result'), + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + releaseFlush.resolve(undefined) + + await waitNoActivation(ctx, started.childId) + expect(childFlushes).toBe(2) + const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId) + expect(hasUserText(loaded.events, 'detached result')).toBe(true) + }) + + it('keeps a child acquired during the final flush before settling', async () => { + const releaseFirstTurn = Promise.withResolvers() + const releaseGrandchild = Promise.withResolvers() + const adapter = new GatedAdapter([ + { chunks: textResponse('child answer'), gate: releaseFirstTurn.promise }, + { chunks: textResponse('grandchild answer'), gate: releaseGrandchild.promise }, + ]) + const { ctx, parent } = await setupWith(adapter) + parkParent(ctx, parent) + const flushing = Promise.withResolvers() + const releaseFlush = Promise.withResolvers() + let heldFinalFlush = false + ctx.on('session/flush', async (session) => { + if (session.header.parentSession !== parent.id || heldFinalFlush) return + heldFinalFlush = true + flushing.resolve(undefined) + await releaseFlush.promise + }) + + const started = await ctx.subagents.startContinuable(startSpec(parent)) + const child = ctx.agents.get(started.childId)! + releaseFirstTurn.resolve(undefined) + await flushing.promise + const grandchild = await ctx.subagents.startContinuable(startSpec(child)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) }) + + releaseFlush.resolve(undefined) + await passSettlementCheck(ctx, started.childId) + expect(ctx.agents.get(started.childId)).toBe(child) + + releaseGrandchild.resolve(undefined) + await waitNoActivation(ctx, grandchild.childId) + await waitNoActivation(ctx, started.childId) + }) + + it('lets explicit disposal win while the natural final flush is pending', async () => { + const releaseFirstTurn = Promise.withResolvers() + const adapter = new GatedAdapter([ + { chunks: textResponse('answer'), gate: releaseFirstTurn.promise }, + ]) + const { ctx, parent } = await setupWith(adapter) + parkParent(ctx, parent) + const flushing = Promise.withResolvers() + const releaseFlush = Promise.withResolvers() + let heldFinalFlush = false + ctx.on('session/flush', async (session) => { + if (session.header.parentSession !== parent.id || heldFinalFlush) return + heldFinalFlush = true + flushing.resolve(undefined) + await releaseFlush.promise + }) + + const started = await ctx.subagents.startContinuable(startSpec(parent)) + releaseFirstTurn.resolve(undefined) + await flushing.promise + const drained = drainManager(ctx) + await drained + + releaseFlush.resolve(undefined) + await passSettlementCheck(ctx, started.childId) + expect(ctx.agents.get(started.childId)).toBeUndefined() + }) + + it('rechecks maintenance that claims the Agent during the final flush', async () => { + const releaseFirstTurn = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('answer'), gate: releaseFirstTurn.promise }]) + const { ctx, parent } = await setupWith(adapter) + parkParent(ctx, parent) + const flushing = Promise.withResolvers() + const releaseFlush = Promise.withResolvers() + let heldFinalFlush = false + ctx.on('session/flush', async (session) => { + if (session.header.parentSession === undefined || heldFinalFlush) return + heldFinalFlush = true + flushing.resolve(undefined) + await releaseFlush.promise + }) + + const started = await ctx.subagents.startContinuable(startSpec(parent)) + const child = ctx.agents.get(started.childId)! + const cancelSpy = vi.spyOn(child, 'cancel') + releaseFirstTurn.resolve(undefined) + await flushing.promise + expect(cancelSpy).not.toHaveBeenCalled() + const releaseMaintenance = Promise.withResolvers() + let maintenanceSignal: AbortSignal | undefined + const maintenance = child.runMaintenance(async (signal) => { + maintenanceSignal = signal + await releaseMaintenance.promise + }) + const runMaintenance = child.runMaintenance.bind(child) + const settlementClaimAttempted = Promise.withResolvers() + vi.spyOn(child, 'runMaintenance').mockImplementation((task) => { + settlementClaimAttempted.resolve(undefined) + return runMaintenance(task) + }) + + releaseFlush.resolve(undefined) + await settlementClaimAttempted.promise + expect(maintenanceSignal?.aborted).toBe(false) + expect(ctx.agents.get(started.childId)).toBe(child) + + releaseMaintenance.resolve(undefined) + await maintenance + await waitNoActivation(ctx, started.childId) + }) + it('settles despite the persistence backend being disposed mid-run', async () => { const releaseResponse = Promise.withResolvers() const adapter = new GatedAdapter([ @@ -1008,10 +1281,7 @@ describe('continuable durability and teardown', () => { const started = await ctx.subagents.startContinuable(startSpec(parent)) await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map Promise } }> } - }).continuations - const activation = manager.activations.get(started.childId)! + const activation = continuationActivations(ctx).get(started.childId)! const realDispose = activation.handle.dispose.bind(activation.handle) activation.handle.dispose = async () => { await realDispose() @@ -1198,10 +1468,7 @@ describe('continuable durability and teardown', () => { const { ctx, parent } = await setupWith(adapter) const target = await ctx.subagents.startContinuable(startSpec(parent)) await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map Promise } }> } - }).continuations - const activation = manager.activations.get(target.childId)! + const activation = continuationActivations(ctx).get(target.childId)! const realDispose = activation.handle.dispose.bind(activation.handle) activation.handle.dispose = async () => { await realDispose() @@ -1279,10 +1546,7 @@ describe('continuable durability and teardown', () => { it('awaits and rolls back an admitted materialization below a scoped root', async () => { const { ctx, parent } = await setup([]) - const manager = (ctx.subagents as unknown as { - continuations: { ownerCtx: Context } - }).continuations - const agents = manager.ownerCtx.agents + const agents = continuationActivations(ctx).ownerCtx.agents const create = agents.create.bind(agents) const published = Promise.withResolvers() const releaseMaterialization = Promise.withResolvers() @@ -1330,10 +1594,7 @@ describe('continuable durability and teardown', () => { const { ctx, parent } = await setupWith(adapter) const started = await ctx.subagents.startContinuable(startSpec(parent)) await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map Promise } }> } - }).continuations - const activation = manager.activations.get(started.childId)! + const activation = continuationActivations(ctx).get(started.childId)! const realDispose = activation.handle.dispose.bind(activation.handle) activation.handle.dispose = async () => { await realDispose() @@ -1456,10 +1717,7 @@ describe('continuable review regressions', () => { const started = await ctx.subagents.startContinuable(startSpec(originalParent.agent)) await waitNoActivation(ctx, started.childId) - const manager = (ctx.subagents as unknown as { - continuations: { ownerCtx: Context } - }).continuations - const ownerAgents = manager.ownerCtx.agents + const ownerAgents = continuationActivations(ctx).ownerCtx.agents const originalResume = ownerAgents.resume.bind(ownerAgents) const resumed = Promise.withResolvers() const releaseResume = Promise.withResolvers() @@ -1496,19 +1754,13 @@ describe('continuable review regressions', () => { await replacement.dispose() }) - it('clears the accepted reservation when Agent.followup throws', async () => { + it('accepts a later delivery after Agent.followup throws', async () => { const hold = Promise.withResolvers() const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: hold.promise }]) const { ctx, parent } = await setupWith(adapter) const started = await ctx.subagents.startContinuable(startSpec(parent)) await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) const child = ctx.agents.get(started.childId)! - const manager = (ctx.subagents as unknown as { - continuations: { - activations: Map }> - } - }).continuations - const activation = manager.activations.get(started.childId)! const realFollowup = child.followup.bind(child) child.followup = () => { throw new Error('synthetic inbox failure') @@ -1516,9 +1768,10 @@ describe('continuable review regressions', () => { await expect(queuePrompt(ctx, parent, started.childId, message('throws'))) .rejects.toThrow(/synthetic inbox failure/) - expect(activation.accepted.size).toBe(0) child.followup = realFollowup + const accepted = await queuePrompt(ctx, parent, started.childId, message('accepted later')) + expect(child.inbox.nextTurn.some(candidate => candidate.id === accepted)).toBe(true) const drained = drainManager(ctx) hold.resolve(undefined) await drained @@ -1652,11 +1905,8 @@ describe('continuable review regressions', () => { ctx.on('subagent/end', (info) => { ends.push(info) }) const started = await ctx.subagents.startContinuable(startSpec(parent)) - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map Promise } }> } - }).continuations const activation = await vi.waitFor(() => { - const found = manager.activations.get(started.childId) + const found = continuationActivations(ctx).get(started.childId) expect(found).toBeDefined() return found! }) @@ -1680,12 +1930,7 @@ describe('continuable review regressions', () => { ctx.on('subagent/end', info => void ends.push(info)) const started = await ctx.subagents.startContinuable(startSpec(parent)) - const manager = (ctx.subagents as unknown as { - continuations: { - activations: Map void } }> - } - }).continuations - const activation = manager.activations.get(started.childId)! + const activation = continuationActivations(ctx).get(started.childId)! activation.observer.capture = () => { throw new Error('capture failed') } const drained = drainManager(ctx) @@ -1695,20 +1940,30 @@ describe('continuable review regressions', () => { expect(ends[0]!.stopReason).toBe('error') }) + it('releases a naturally settled Activation when terminal capture fails', async () => { + const hold = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('answer'), gate: hold.promise }]) + const { ctx, parent } = await setupWith(adapter) + const ends: SubagentRunEndInfo[] = [] + ctx.on('subagent/end', info => void ends.push(info)) + + const started = await ctx.subagents.startContinuable(startSpec(parent)) + continuationActivations(ctx).get(started.childId)!.observer.capture = () => { + throw new Error('capture failed') + } + + hold.resolve(undefined) + await waitNoActivation(ctx, started.childId) + await vi.waitFor(() => { expect(ends).toHaveLength(1) }) + expect(ends[0]!.stopReason).toBe('error') + }) + it('preserves independent pre-disposal and handle-disposal failures', async () => { const hold = Promise.withResolvers() const adapter = new GatedAdapter([{ chunks: textResponse('answer'), gate: hold.promise }]) const { ctx, parent } = await setupWith(adapter) const started = await ctx.subagents.startContinuable(startSpec(parent)) - const manager = (ctx.subagents as unknown as { - continuations: { - activations: Map Promise } - observer: { capture: (child: Agent) => void } - }> - } - }).continuations - const activation = manager.activations.get(started.childId)! + const activation = continuationActivations(ctx).get(started.childId)! const realDispose = activation.handle.dispose.bind(activation.handle) activation.observer.capture = () => { throw new Error('capture failed') } activation.handle.dispose = async () => { @@ -1771,6 +2026,138 @@ describe('continuable review regressions', () => { expect(hasUserText(loaded.events, 'discarded')).toBe(false) }) + it('settles after removing the last message from an idle parked Inbox', async () => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: release.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + const messageId = await queuePrompt(ctx, parent, started.childId, message('queued')) + ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id }) + release.resolve(undefined) + await child.whenIdle() + await passSettlementCheck(ctx, started.childId) + expect(child.inbox.remove(messageId)).toBe(true) + await waitNoActivation(ctx, started.childId) + }) + + it('keeps a maintenance task that claimed the idle phase after whenIdle resolved', async () => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: release.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + // Held while the child still runs, so the watcher observes idle and then + // waits here with its settlement decision already outstanding. + const lock = await holdChildLock(ctx, started.childId) + release.resolve(undefined) + await child.whenIdle() + const finishMaintenance = Promise.withResolvers() + let maintenanceSignal: AbortSignal | undefined + const maintenance = child.runMaintenance(async (signal) => { + maintenanceSignal = signal + await finishMaintenance.promise + }) + lock.release() + await lock.held + await passSettlementCheck(ctx, started.childId) + expect(maintenanceSignal?.aborted).toBe(false) + expect(ctx.agents.get(started.childId) !== undefined).toBe(true) + finishMaintenance.resolve(undefined) + await maintenance + await waitNoActivation(ctx, started.childId) + }) + + it('settles when maintenance finishes after losing the idle phase', async () => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: release.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + const lock = await holdChildLock(ctx, started.childId) + release.resolve(undefined) + await child.whenIdle() + const finishMaintenance = Promise.withResolvers() + const maintenance = child.runMaintenance(async () => { await finishMaintenance.promise }) + lock.release() + // Let the queued settlement check observe maintenance, then finish it + // before that check's caller receives the false result. + queueMicrotask(() => { + queueMicrotask(() => { finishMaintenance.resolve(undefined) }) + }) + await lock.held + await maintenance + await waitNoActivation(ctx, started.childId) + }) + + it.each([ + { label: 'plugin', source: { kind: 'plugin' as const, plugin: 'tool-jobs' } }, + { label: 'non-plugin', source: { kind: 'team-message', teamId: 't-1' } as never }, + ])('keeps an idle child resident while its Inbox holds $label injected context', async ({ source }) => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: release.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + const lock = await holdChildLock(ctx, started.childId) + release.resolve(undefined) + await child.whenIdle() + const context = createUserMessage({ content: message('parked context'), source }) + child.inject(context) + expect(child.inbox.nextStep).toHaveLength(1) + lock.release() + await lock.held + await passSettlementCheck(ctx, started.childId) + expect(ctx.agents.get(started.childId) !== undefined).toBe(true) + expect(child.inbox.remove(context.id)).toBe(true) + await waitNoActivation(ctx, started.childId) + }) + + it('keeps an idle child resident while plugin-sourced steering stays unclaimed', async () => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: release.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + // A cordis-host-runner failure report: `steer()` from a plugin still wakes + // a driver, so residency must survive until that turn claims the message. + const steered = createUserMessage({ + content: message('Cordis Host handler failed'), + source: { kind: 'plugin', plugin: 'cordis-host-runner' }, + }) + child.steer(steered) + ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id }) + release.resolve(undefined) + await child.whenIdle() + await passSettlementCheck(ctx, started.childId) + expect(ctx.agents.get(started.childId) !== undefined).toBe(true) + expect(child.inbox.remove(steered.id)).toBe(true) + await waitNoActivation(ctx, started.childId) + }) + + it('keeps an idle child resident while an interrupted turn leaves human steering parked', async () => { + const release = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: release.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const child = ctx.agents.get(started.childId)! + await humanPrompt(ctx, parent, started.childId, 'steered', 'steer') + ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id }) + release.resolve(undefined) + await child.whenIdle() + const parked = child.inbox.nextStep[0]! + await passSettlementCheck(ctx, started.childId) + expect(ctx.agents.get(started.childId) !== undefined).toBe(true) + expect(child.inbox.remove(parked.id)).toBe(true) + await waitNoActivation(ctx, started.childId) + }) + it('settles after a delivery discarded inside its own admission window', async () => { const releaseFirst = Promise.withResolvers() const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: releaseFirst.promise }]) @@ -1779,8 +2166,8 @@ describe('continuable review regressions', () => { await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) const child = ctx.agents.get(started.childId)! - // Cancel from the synchronous enqueue observer: the discard fires after the - // id is recorded but before `queuePrompt()` returns. + // Cancel from the synchronous enqueue observer, before `queuePrompt()` + // returns from Agent.followup(). const off = child.ctx.on('agent/inbox/inserted', ({ message }) => { if (message.content.some(block => block.type === 'text' && block.text === 'doomed')) { child.cancel({ kind: 'user' }) @@ -1790,29 +2177,21 @@ describe('continuable review regressions', () => { off() releaseFirst.resolve(undefined) - // Retaining the discarded id would pin residency at `running` forever, so - // reaching no-Activation without an explicit drain is the assertion. + // The discarded delivery leaves no phantom activity that pins residency. await waitNoActivation(ctx, started.childId) const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId) expect(hasUserText(loaded.events, 'doomed')).toBe(false) }) - it('releases older ids discarded during a later admission window', async () => { + it('settles after a later delivery discards older queued work', async () => { const releaseFirst = Promise.withResolvers() const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: releaseFirst.promise }]) const { ctx, parent } = await setupWith(adapter) const started = await ctx.subagents.startContinuable(startSpec(parent)) await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) const child = ctx.agents.get(started.childId)! - const manager = (ctx.subagents as unknown as { - continuations: { - activations: Map }> - } - }).continuations - const activation = manager.activations.get(started.childId)! await queuePrompt(ctx, parent, started.childId, message('queued')) - expect(activation.accepted.size).toBe(1) const off = child.ctx.on('agent/inbox/inserted', ({ message }) => { if (message.content.some(block => block.type === 'text' && block.text === 'doomed')) { child.cancel({ kind: 'user' }) @@ -1821,9 +2200,11 @@ describe('continuable review regressions', () => { await queuePrompt(ctx, parent, started.childId, message('doomed')) off() - expect(activation.accepted.size).toBe(0) releaseFirst.resolve(undefined) await waitNoActivation(ctx, started.childId) + const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId) + expect(hasUserText(loaded.events, 'queued')).toBe(false) + expect(hasUserText(loaded.events, 'doomed')).toBe(false) }) it('reports a prompt a pre-step rejection discarded as refusal', async () => { @@ -2250,11 +2631,8 @@ describe('continuable settlement delivery', () => { it('withholds an outcome the harness could not durably release', async () => { const { ctx, parent } = await setup([textResponse('the answer'), textResponse('parent ack')]) const started = await ctx.subagents.startContinuable(startSpec(parent)) - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map } }> } - }).continuations const activation = await vi.waitFor(() => { - const live = manager.activations.get(started.childId) + const live = continuationActivations(ctx).get(started.childId) expect(live).toBeDefined() return live! }) @@ -2342,11 +2720,8 @@ describe('continuable settlement delivery', () => { const second = await ctx.subagents.startContinuable(startSpec(middle)) await vi.waitFor(() => { expect(middle.status).toBe('idle') }) - // `Agent.status` folds maintenance into `idle`, and a waking send behind it - // only arms a deferred wake. The first child's release moves the middle - // Activation's settlement watcher onto its quiescence race; the second one - // then arrives at exactly the point where an unaccounted delivery would be - // judged quiet, settled, and cancelled — clearing the inbox it sits in. + // `whenIdle()` follows maintenance and the deferred wake it releases, so + // neither settlement notice can be mistaken for completed idle work. const maintaining = Promise.withResolvers() const maintenance = middle.runMaintenance(async () => { await maintaining.promise }) releaseFirst.resolve(undefined) @@ -2380,13 +2755,10 @@ describe('continuable settlement delivery', () => { const inner = await ctx.subagents.startContinuable(startSpec(middle)) await vi.waitFor(() => { expect(middle.status).toBe('idle') }) - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map }> } - }).continuations let ownedAtDelivery: SessionId[] | undefined ctx.on('agent/inbox/inserted', ({ agent, message }) => { if (agent !== middle || message.source.kind !== 'subagent-settled') return - ownedAtDelivery = [...manager.activations.get(middle.id)!.ownedChildren] + ownedAtDelivery = [...continuationActivations(ctx).get(middle.id)!.ownedChildren] }) releaseChild.resolve(undefined) @@ -2633,10 +3005,7 @@ describe('continuable errors', () => { }) // Drop the Activation without disposing the Agent, leaving the id live but // unmanaged. Materialization must not adopt it. - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map } - }).continuations - manager.activations.delete(started.childId) + dropContinuationActivation(ctx, started.childId) await expect(queuePrompt(ctx, parent, started.childId, message('hello'))) .rejects.toThrow(SubagentError) @@ -2696,10 +3065,7 @@ describe('continuable errors', () => { await vi.waitFor(() => { expect(ctx.agents.get(grandchild.childId)).toBeDefined() }) // Make the grandchild's own handle disposal reject: scope teardown failure // propagates, unlike a contained `agent/disposed` listener throw. - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map Promise } }> } - }).continuations - const branch = manager.activations.get(grandchild.childId)! + const branch = continuationActivations(ctx).get(grandchild.childId)! const realDispose = branch.handle.dispose.bind(branch.handle) branch.handle.dispose = async () => { await realDispose() @@ -2730,11 +3096,8 @@ describe('continuable errors', () => { }) // The would-be parent's disposal is already open at the entry hold, so the // establishment rejects before any grandchild resource exists. - const manager = (ctx.subagents as unknown as { - continuations: { activations: Map | undefined }> } - }).continuations const before = new Set(ctx.agents.list().map(agent => agent.id)) - manager.activations.get(outer.childId)!.disposal = Promise.resolve() + void continuationActivations(ctx).get(outer.childId)!.inbox.close(() => Promise.resolve()) await expect(ctx.subagents.startContinuable(startSpec(child))) .rejects.toMatchObject({ code: 'ACTIVATION_CLOSING' }) @@ -2757,13 +3120,8 @@ describe('continuable errors', () => { expect(found).toBeDefined() return found! }) - const manager = (ctx.subagents as unknown as { - continuations: { - activations: Map | undefined }> - ownerCtx: Context - } - }).continuations - const ownerAgents = manager.ownerCtx.agents + const activations = continuationActivations(ctx) + const ownerAgents = activations.ownerCtx.agents const before = new Set(ctx.agents.list().map(agent => agent.id)) // Open the would-be parent's disposal only once the grandchild's Agent is // being created: the entry hold has already passed, so the post-transfer @@ -2771,7 +3129,7 @@ describe('continuable errors', () => { // Activation and no live Agent left behind. const originalCreate = ownerAgents.create.bind(ownerAgents) const createSpy = vi.spyOn(ownerAgents, 'create').mockImplementation((options) => { - manager.activations.get(outer.childId)!.disposal = Promise.resolve() + void activations.get(outer.childId)!.inbox.close(() => Promise.resolve()) createSpy.mockRestore() return originalCreate(options) }) @@ -2901,7 +3259,7 @@ describe('continuable errors', () => { }) describe('SubagentRuntime.interrupt', () => { - it('aborts the current turn durably, parks accepted follow-ups, and resumes them only on a waking send', async () => { + it('aborts the current turn durably, parks accepted follow-ups, and settles after direct Agent followup', async () => { const releaseFirst = Promise.withResolvers() const adapter = new GatedAdapter([ { chunks: textResponse('first'), gate: releaseFirst.promise }, @@ -2924,6 +3282,7 @@ describe('SubagentRuntime.interrupt', () => { // Cancellation is cooperative: the held model call observes it on release. releaseFirst.resolve(undefined) await child.whenIdle() + await passSettlementCheck(ctx, started.childId) // Parked, not resumed: no second model request follows the abort, the // accepted follow-ups stay pending, and the same Activation stays resident. expect(adapter.requests).toHaveLength(1) @@ -2931,9 +3290,9 @@ describe('SubagentRuntime.interrupt', () => { expect(child.status).toBe('idle') expect(ctx.agents.get(started.childId)).toBe(child) - // Only an explicit waking send restores the driver; the parked items then - // run before it in the existing FIFO order. - await queuePrompt(ctx, parent, started.childId, message('waking D')) + // A host can wake a resident child through Agent directly; the parked items + // still run before the new message in the existing FIFO order. + child.followup(createUserMessage({ content: message('waking D'), source: { kind: 'user' } })) await waitNoActivation(ctx, started.childId) const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId) expect(userTexts(loaded.events)).toEqual(['child task', 'parked B', 'parked C', 'waking D']) diff --git a/packages/subagent/subagent/tests/control.spec.ts b/packages/subagent/subagent/tests/control.spec.ts index 22db177cc3..54f6a8a7f6 100644 --- a/packages/subagent/subagent/tests/control.spec.ts +++ b/packages/subagent/subagent/tests/control.spec.ts @@ -43,12 +43,13 @@ function childRow(id: SessionId, activity: 'running' | 'inactive'): SubagentList return { kind: 'child', id, mode: 'continuable', label: 'worker', activity, hasChildren: false } } -function promptRequest(clientTimeZone?: string) { +function promptRequest(clientTimeZone?: string, delivery: 'queue' | 'steer' = 'queue') { return { requestId: REQUEST_ID, parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const, + delivery, content: [{ type: 'text' as const, text: 'continue' }], ...clientTimeZone === undefined ? {} : { clientTimeZone }, } @@ -165,6 +166,15 @@ describe('subagent prompt Remote', () => { expect(delivery).not.toHaveBeenCalled() }) + it('rejects an unknown delivery before admission', async () => { + const { subagents } = await bench({ [PARENT]: { status: 'idle' } }) + const delivery = promptDelivery(subagents) + + await expect(subagents.prompt({ ...promptRequest(), delivery: 'later' as 'queue' }, signal)) + .rejects.toMatchObject({ code: 'gateway/bad-request' }) + expect(delivery).not.toHaveBeenCalled() + }) + it('admits ordered image parts into durable references before delivery', async () => { const { ctx, subagents } = await bench({ [PARENT]: { status: 'idle' } }) const saveImages = vi.fn(async (inputs: readonly { mediaType: string }[]) => @@ -258,6 +268,15 @@ describe('subagent prompt Remote', () => { ) }) + it('passes steer delivery through the same admission operation', async () => { + const { subagents } = await bench({ [PARENT]: { status: 'running' } }) + const delivery = promptDelivery(subagents).mockResolvedValue('m-steer' as MessageId) + + await expect(subagents.prompt(promptRequest(undefined, 'steer'), signal)) + .resolves.toEqual({ messageId: 'm-steer' }) + expect(delivery.mock.calls[0]?.[5]).toBe('steer') + }) + it('omits the zone from the durable source when the browser reported none', async () => { const { subagents } = await bench({ [PARENT]: { status: 'idle' } }) const delivery = promptDelivery(subagents).mockResolvedValue('m-2' as MessageId) diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts index c6f57a151d..c8b526920d 100644 --- a/packages/subagent/subagent/tests/list-children.spec.ts +++ b/packages/subagent/subagent/tests/list-children.spec.ts @@ -35,9 +35,11 @@ import { seedStoredSession } from './persistence-helpers.ts' type Script = ConstructorParameters[0] const roots: string[] = [] +const persistenceDisposers: Array<() => Promise> = [] const projCacheRoots: string[] = [] -afterEach(() => { +afterEach(async () => { + await Promise.all(persistenceDisposers.splice(0).map(dispose => dispose())) for (const root of projCacheRoots.splice(0)) rmSync(root, { recursive: true, force: true }) for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) }) @@ -51,7 +53,8 @@ async function setup( await mountAgentLoopTestDependencies(ctx) const root = mkdtempSync(join(tmpdir(), 'dsh-subagent-list-')) roots.push(root) - await ctx.plugin(JsonlSessionPersistence, { root }) + const persistence = await ctx.plugin(JsonlSessionPersistence, { root }) + persistenceDisposers.push(() => persistence.dispose()) await ctx.plugin(AgentLoop, { agents: [] }) if (options.sessionProjections !== false) await ctx.plugin(SessionProjectionRegistry) if (options.projectionCache === true) { diff --git a/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts b/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts index 7baaddb57a..e19461a3ff 100644 --- a/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts +++ b/packages/test-support/session-snapshot/tests/fixtures/subagent-durability-failure.ts @@ -1,5 +1,6 @@ import type { Context } from '@deepseek-ai/cordis' import { SessionId } from '@deepseek-ai/dsh-session' +import type { SubagentPromptRequestId } from '@deepseek-ai/dsh-subagent' export const name = 'subagent-durability-failure' export const inject = ['agents', 'sessionPersistence', 'subagents'] @@ -12,6 +13,9 @@ export const inject = ['agents', 'sessionPersistence', 'subagents'] * * - `PLACEHOLDER_CHILD_ID` in a scripted `send_message` is remapped to the real * child so both follow-ups queue onto the same live inbox in FIFO order. + * - Under `DSH_SNAPSHOT_HUMAN_STEER`, a browser-authored prompt steers the + * continuable child before its first step, recording the shared next-step + * inbox path without adding a model tool. * - The unknown-id `send_message` (`UNKNOWN_CHILD_ID`) resolves through a * persistence stat fenced behind both accepted follow-ups, so the transcript * records the same order on every runner. @@ -34,6 +38,7 @@ export function apply(ctx: Context): void { const parentTurnClosed = Promise.withResolvers() let parentClosed = false const publishedFailure = process.env.DSH_SUBAGENT_PUBLISHED_FAILURE === '1' + const humanSteer = process.env.DSH_SNAPSHOT_HUMAN_STEER === '1' const persistence = ctx.sessionPersistence const stat = persistence.stat.bind(persistence) const agents = ctx.agents @@ -87,6 +92,14 @@ export function apply(ctx: Context): void { let realChildId: string | undefined const subagents = ctx.subagents as unknown as { sendMessage: (authority: unknown, childId: SessionId, content: unknown, options: unknown) => Promise + prompt: (request: { + requestId: SubagentPromptRequestId + parentSessionId: SessionId + childSessionId: SessionId + mode: 'continuable' + delivery: 'steer' + content: readonly [{ readonly type: 'text'; readonly text: string }] + }, signal: AbortSignal) => Promise } const deliver = subagents.sendMessage.bind(subagents) subagents.sendMessage = (authority, childId, content, options) => { @@ -106,9 +119,21 @@ export function apply(ctx: Context): void { accepted += 1 if (accepted >= 3) followupsAccepted.resolve(undefined) }) + let steering = false ctx.on('agent/pre-step', async ({ agent }, next) => { if (agent.session.header.parentSession === undefined) return next() await followupsAccepted.promise + if (humanSteer && !steering) { + steering = true + await subagents.prompt({ + requestId: 'snapshot-human-steer' as SubagentPromptRequestId, + parentSessionId: agent.session.header.parentSession, + childSessionId: SessionId(agent.session.header.id), + mode: 'continuable', + delivery: 'steer', + content: [{ type: 'text', text: 'Human priority: keep the requested exact reply.' }], + }, new AbortController().signal) + } // The published-failure variant's child never reaches a step (its follow-up // throws), and its parent turn awaits that child, so only the continuable // scenario takes the settlement fence. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 079629c6da..6ed6074160 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -581,6 +581,12 @@ importers: '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../packages/llm/llm + '@deepseek-ai/dsh-llm-replay': + specifier: workspace:^ + version: link:../packages/test-support/llm-replay + '@deepseek-ai/dsh-sdk-client': + specifier: workspace:^ + version: link:../packages/sdk/client '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../packages/core/session @@ -605,12 +611,21 @@ importers: '@deepseek-ai/dsh-session-turn-outline': specifier: workspace:^ version: link:../packages/session/session-turn-outline + '@deepseek-ai/dsh-subagent': + specifier: workspace:^ + version: link:../packages/subagent/subagent '@deepseek-ai/dsh-token-meter': specifier: workspace:^ version: link:../packages/llm/token-meter + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../packages/core/tools '@deepseek-ai/dsh-typert-protocol': specifier: workspace:^ version: link:../packages/typert/protocol + playwright: + specifier: ^1.49.0 + version: 1.61.1 native/landlock-run: devDependencies: @@ -931,6 +946,9 @@ importers: '@deepseek-ai/dsh-util-time': specifier: workspace:^ version: link:../../util/time + '@deepseek-ai/dsh-util-values': + specifier: workspace:^ + version: link:../../util/values '@deepseek-ai/dsh-util-workspace-path': specifier: workspace:^ version: link:../../util/workspace-path diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts index 8f0d2e51cd..02ffac7aba 100644 --- a/scripts/ci-workflow.spec.ts +++ b/scripts/ci-workflow.spec.ts @@ -211,6 +211,16 @@ describe('CI workflow', () => { expect(aggregate.needs).toContain('node-24-bench') expect(node24Bench.name).toBe('node 24 / benchmarks') expect(node24Bench.env).toBeUndefined() + expect(node24Bench.steps).toContainEqual({ + name: 'Install benchmark browser and hosted dependencies', + run: 'pnpm --filter @deepseek-ai/dsh-benchmarks exec playwright install --with-deps chromium', + }) + expect(JSON.stringify(node24Bench.steps)).not.toContain('DSH_CI_FAILOVER_LINUX') + expect(node24Bench.steps).toContainEqual({ + name: 'Run performance benchmarks', + env: { DSH_GATE_VERBOSE: '1' }, + run: 'pnpm run check:ci:bench', + }) expect(aggregate.needs).not.toContain('windows-coverage') expect(aggregate.needs).toContain('windows-native-tests') expect(aggregate.needs).not.toContain('windows-observational') @@ -374,6 +384,36 @@ describe('CI workflow', () => { } }) + it('redirects the Node compile cache to the data-volume runner temp before the first pnpm call', () => { + const prWorkflow = loadWorkflow('.github/workflows/ci.yml') + const masterWorkflow = loadWorkflow('.github/workflows/ci-master.yml') + const redirectLanes = [ + [prWorkflow, 'node-24'], + [prWorkflow, 'node-24-coverage'], + [prWorkflow, 'node-24-consumers'], + [masterWorkflow, 'serial-linux-selfhosted'], + ] as const + for (const [workflow, jobKey] of redirectLanes) { + const job = workflowJob(workflow, jobKey) + if (!Array.isArray(job.steps)) throw new TypeError(`${jobKey} must define steps`) + const redirectStepIndex = job.steps.findIndex((step): step is Record & { run: string } => ( + isRecord(step) && typeof step.run === 'string' + && step.run.includes('NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache') + && step.run.includes('"$GITHUB_ENV"') + )) + // Removing this injection would send every pnpm call in the lane (setup, + // store-path probe, install, and the gate) back to the root partition's + // /tmp; rationale in + // .agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md. + expect(redirectStepIndex, `${jobKey} must inject NODE_COMPILE_CACHE into GITHUB_ENV`).toBeGreaterThan(-1) + const pnpmSetupIndex = job.steps.findIndex((step): step is Record & { uses: string } => ( + isRecord(step) && typeof step.uses === 'string' && step.uses.includes('pnpm/action-setup') + )) + expect(pnpmSetupIndex, `${jobKey} must run pnpm/action-setup`).toBeGreaterThan(-1) + expect(redirectStepIndex, `${jobKey} must redirect before pnpm/action-setup runs pnpm`).toBeLessThan(pnpmSetupIndex) + } + }) + it('keeps supported LSP source under native Windows coverage', () => { const config = readFileSync(resolve(root, 'vitest.config.ts'), 'utf8') diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 591cfd3497..f929c88512 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1349,22 +1349,22 @@ { "doc": "docs/subsystems/subagent.md", "symbol": "AgentMessageSource", - "source": "packages/subagent/subagent/src/continuation.ts" + "source": "packages/subagent/subagent/src/continuation-messages.ts" }, { "doc": "docs/subsystems/subagent.md", "symbol": "SubagentSettledMessageSource", - "source": "packages/subagent/subagent/src/continuation.ts" + "source": "packages/subagent/subagent/src/continuation-messages.ts" }, { "doc": "docs/subsystems/subagent.md", "symbol": "SubagentSendMessageOptions", - "source": "packages/subagent/subagent/src/continuation.ts" + "source": "packages/subagent/subagent/src/types.ts" }, { "doc": "docs/subsystems/subagent.md", "symbol": "SubagentInterruptAuthority", - "source": "packages/subagent/subagent/src/continuation.ts" + "source": "packages/subagent/subagent/src/types.ts" }, { "doc": "docs/subsystems/subagent.md", @@ -1374,7 +1374,7 @@ { "doc": "docs/subsystems/subagent.md", "symbol": "ContinuableStart", - "source": "packages/subagent/subagent/src/continuation.ts" + "source": "packages/subagent/subagent/src/types.ts" }, { "doc": "docs/subsystems/subagent.md", diff --git a/snapshots/sdk/sdk.snapshot.ts b/snapshots/sdk/sdk.snapshot.ts index f0a13d8591..dbdbd6396c 100644 --- a/snapshots/sdk/sdk.snapshot.ts +++ b/snapshots/sdk/sdk.snapshot.ts @@ -127,6 +127,9 @@ const SDK_ASSERTIONS: Readonly> = { expectedFinalResponse: 'CODE_ONE+CODE_TWO', expectedTools: { run_code: ['code', 'description'] }, }, + 'subagent-continuable': { + environment: { DSH_SNAPSHOT_HUMAN_STEER: '1' }, + }, 'subagent-dsh-sdk-diagnostic': { environment: { DSH_TEST_CHILD_PATCH: dshSdkDiagnosticChildPatch }, }, diff --git a/snapshots/sdk/subagent-continuable/session.1.v2.jsonl b/snapshots/sdk/subagent-continuable/session.1.v2.jsonl index 4212579c43..1f29833edc 100644 --- a/snapshots/sdk/subagent-continuable/session.1.v2.jsonl +++ b/snapshots/sdk/subagent-continuable/session.1.v2.jsonl @@ -8,18 +8,20 @@ {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly SECOND_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:15}}"}]}} {"type":"agent/inbox/spliced","data":{"target":"next-step","start":1,"inserted":[{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly THIRD_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:16}}"}]}} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":2,"inserted":[{"content":[{"type":"text","text":"Human priority: keep the requested exact reply."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:17}}"}]}} {"type":"step/start","data":{"turn":1,"step":1}} {"type":"user/message","data":{"content":[{"type":"text","text":"Reply with exactly the word CHILD_OK and nothing else."},{"type":"text","text":"Your parent agent id is \"{{session:1}}\". Before you finish, send your result to that agent with send_message({ agent_id: \"{{session:1}}\", message: \"\" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn."}],"source":{"kind":"user"},"role":"user","id":"{{message:14}}"},"surfaceOp":"append"} -{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:delegation","text":"You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}]},"role":"user","id":"{{message:17}}"},"surfaceOp":"append"} -{"type":"session/title","data":{"title":"Reply with exactly the word","messageSeqs":[10],"source":{"kind":"fallback"}}} +{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:delegation","text":"You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}]},"role":"user","id":"{{message:18}}"},"surfaceOp":"append"} +{"type":"session/title","data":{"title":"Reply with exactly the word","messageSeqs":[11],"source":{"kind":"fallback"}}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:18}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788269696690,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788269696690,"index":0,"dt":[],"texts":["CHILD_OK"]},{"type":"chunk","time":1788269696691,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CHILD_OK"}}},{"type":"chunk","time":1788269696691,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788269696691,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:19}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788505934036,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788505934036,"index":0,"dt":[],"texts":["CHILD_OK"]},{"type":"chunk","time":1788505934036,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CHILD_OK"}}},{"type":"chunk","time":1788505934036,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788505934036,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} -{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":2,"inserted":[]}} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":3,"inserted":[]}} {"type":"step/start","data":{"turn":1,"step":2}} {"type":"user/message","data":{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly SECOND_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:15}}"},"surfaceOp":"append"} {"type":"user/message","data":{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly THIRD_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:16}}"},"surfaceOp":"append"} -{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"SECOND_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:19}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788269696707,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788269696707,"index":0,"dt":[],"texts":["SECOND_OK"]},{"type":"chunk","time":1788269696707,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"SECOND_OK"}}},{"type":"chunk","time":1788269696707,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788269696707,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Human priority: keep the requested exact reply."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:17}}"},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"SECOND_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:20}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788505934049,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788505934049,"index":0,"dt":[],"texts":["SECOND_OK"]},{"type":"chunk","time":1788505934049,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"SECOND_OK"}}},{"type":"chunk","time":1788505934049,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788505934049,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":2}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/sdk/subagent-continuable/session.1.v3.jsonl b/snapshots/sdk/subagent-continuable/session.1.v3.jsonl index c644315244..62f7d55213 100644 --- a/snapshots/sdk/subagent-continuable/session.1.v3.jsonl +++ b/snapshots/sdk/subagent-continuable/session.1.v3.jsonl @@ -8,18 +8,20 @@ {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly SECOND_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:15}}"}]}} {"type":"agent/inbox/spliced","data":{"target":"next-step","start":1,"inserted":[{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly THIRD_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:16}}"}]}} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":2,"inserted":[{"content":[{"type":"text","text":"Human priority: keep the requested exact reply."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:17}}"}]}} {"type":"step/start","data":{"turn":1,"step":1}} {"type":"user/message","data":{"content":[{"type":"text","text":"Reply with exactly the word CHILD_OK and nothing else."},{"type":"text","text":"Your parent agent id is \"{{session:1}}\". Before you finish, send your result to that agent with send_message({ agent_id: \"{{session:1}}\", message: \"\" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn."}],"source":{"kind":"user"},"role":"user","id":"{{message:14}}"},"surfaceOp":"append"} -{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:delegation","text":"You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}]},"role":"user","id":"{{message:17}}"},"surfaceOp":"append"} -{"type":"session/title","data":{"title":"Reply with exactly the word","messageSeqs":[10],"source":{"kind":"fallback"}}} +{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:delegation","text":"You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}]},"role":"user","id":"{{message:18}}"},"surfaceOp":"append"} +{"type":"session/title","data":{"title":"Reply with exactly the word","messageSeqs":[11],"source":{"kind":"fallback"}}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:18}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788269696690,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788269696690,"index":0,"dt":[],"texts":["CHILD_OK"]},{"type":"chunk","time":1788269696691,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CHILD_OK"}}},{"type":"chunk","time":1788269696691,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788269696691,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:19}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788767254264,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788767254264,"index":0,"dt":[],"texts":["CHILD_OK"]},{"type":"chunk","time":1788767254264,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CHILD_OK"}}},{"type":"chunk","time":1788767254264,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788767254264,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} -{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":2,"inserted":[]}} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":3,"inserted":[]}} {"type":"step/start","data":{"turn":1,"step":2}} {"type":"user/message","data":{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly SECOND_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:15}}"},"surfaceOp":"append"} {"type":"user/message","data":{"content":[{"type":"text","text":"Agent {{session:1}} sent a message: "},{"type":"text","text":"Now reply with exactly THIRD_OK."}],"source":{"kind":"agent-message","form":"relay","senderSessionId":"{{session:1}}"},"role":"user","id":"{{message:16}}"},"surfaceOp":"append"} -{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"SECOND_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:19}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788269696707,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788269696707,"index":0,"dt":[],"texts":["SECOND_OK"]},{"type":"chunk","time":1788269696707,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"SECOND_OK"}}},{"type":"chunk","time":1788269696707,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788269696707,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Human priority: keep the requested exact reply."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:17}}"},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"SECOND_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:20}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788767254280,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788767254280,"index":0,"dt":[],"texts":["SECOND_OK"]},{"type":"chunk","time":1788767254280,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"SECOND_OK"}}},{"type":"chunk","time":1788767254280,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788767254280,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":2}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/web/subagent-interrupt/offline-composer.expected.md b/snapshots/web/subagent-interrupt/offline-composer.expected.md index 7c00b9e2c8..b34acde2d7 100644 --- a/snapshots/web/subagent-interrupt/offline-composer.expected.md +++ b/snapshots/web/subagent-interrupt/offline-composer.expected.md @@ -24,6 +24,15 @@ - text: Context injection @deepseek-ai/dsh-system-prompt - paragraph: partial - status: Deep diving... +- list: + - listitem: + - text: Keep working until I stop you again. + - button "Edit queued message": + - img + - button "Remove queued message": + - img + - button "Steer queued message": + - img - textbox "Parent session offline; sending is unavailable but you can still stop the run" [disabled] - button "Commands" [disabled]: - img diff --git a/vitest.bench.config.ts b/vitest.bench.config.ts index 81a4652718..5e355d85d6 100644 --- a/vitest.bench.config.ts +++ b/vitest.bench.config.ts @@ -3,8 +3,9 @@ import { defineConfig } from 'vitest/config' import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts' /** - * CI performance gate. Vitest orchestrates compiled plain-Node workers under - * `.dsh-build/benchmarks/`; timed product work never runs through its source transform. + * CI performance gate. Node CPU cases use compiled plain-Node workers under + * `benchmarks/.dsh-build/`; browser cases drive built Client artifacts through + * the shared shipped-composition Web scaffold. * Files run one at a time so a measurement never shares the CPU with another * benchmark. */