From 040d73871b34807b1a92bab221e9709dce846e3a Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Sun, 30 Aug 2026 20:44:34 +0800 Subject: [PATCH 1/8] feat(agent-team): unify messages on steer --- .../feature/2026-08-05-agent-teams.i18n.yaml | 4 +- .../feature/2026-08-05-agent-teams.md | 6 +- .../feature/2026-08-05-agent-teams.zh.md | 6 +- ...26-08-30-team-send-message-steer.i18n.yaml | 6 + .../2026-08-30-team-send-message-steer.md | 41 ++++ .../2026-08-30-team-send-message-steer.zh.md | 41 ++++ .../headless/tests/fixtures/team-llm.mjs | 6 + .../headless/tests/headless.expected.e2e.ts | 55 +++++ docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 2 +- docs/config-catalog.zh.md | 2 +- docs/persistence-catalog.i18n.yaml | 4 +- docs/persistence-catalog.md | 8 +- docs/persistence-catalog.zh.md | 8 +- docs/subsystems/agent-team.i18n.yaml | 4 +- docs/subsystems/agent-team.md | 7 +- docs/subsystems/agent-team.zh.md | 7 +- docs/tool-catalog.i18n.yaml | 4 +- docs/tool-catalog.md | 32 +-- docs/tool-catalog.zh.md | 30 +-- packages/experimental/README.i18n.yaml | 4 +- packages/experimental/README.md | 2 +- packages/experimental/README.zh.md | 2 +- .../experimental/agent-team/README.i18n.yaml | 4 +- packages/experimental/agent-team/README.md | 4 +- packages/experimental/agent-team/README.zh.md | 4 +- packages/experimental/agent-team/src/index.ts | 2 +- .../experimental/agent-team/src/mailbox.ts | 23 +-- .../experimental/agent-team/src/projection.ts | 1 - packages/experimental/agent-team/src/types.ts | 2 - .../agent-team/tests/persistence.spec.ts | 31 +-- .../tests/projection-events.spec.ts | 1 - .../agent-team/tests/team.spec.ts | 188 +++++++++++------- .../tool-agent-team/README.i18n.yaml | 4 +- .../experimental/tool-agent-team/README.md | 16 +- .../experimental/tool-agent-team/README.zh.md | 18 +- .../experimental/tool-agent-team/src/index.ts | 43 ++-- .../tool-agent-team/tests/tool-team.spec.ts | 12 +- .../extensions/tool-cordis/src/api-catalog.ts | 4 +- packages/subagent/subagent/README.i18n.yaml | 4 +- packages/subagent/subagent/README.md | 2 +- packages/subagent/subagent/README.zh.md | 2 +- .../subagent/subagent/src/continuation.ts | 23 ++- packages/subagent/subagent/src/index.ts | 15 +- packages/subagent/subagent/src/internal.ts | 45 ++++- .../subagent/subagent/tests/control.spec.ts | 5 +- scripts/gen-tool-catalog.ts | 2 +- 47 files changed, 451 insertions(+), 289 deletions(-) create mode 100644 .agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.i18n.yaml create mode 100644 .agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.md create mode 100644 .agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.zh.md diff --git a/.agents/notes/implemented/feature/2026-08-05-agent-teams.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-agent-teams.i18n.yaml index 8ed90b9b2c..e308dfc2f4 100644 --- a/.agents/notes/implemented/feature/2026-08-05-agent-teams.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-05-agent-teams.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-05-agent-teams.md -2026-08-05-agent-teams.md: fbcd8485a972323bc0f8ffb6a5cb7cca9a50044e -2026-08-05-agent-teams.zh.md: 0a1a8a81c47abfca275f5fc3c60b8d514cdddd30 +2026-08-05-agent-teams.md: df84b2710d597330e9fdf6f8f83edb1441f100ec +2026-08-05-agent-teams.zh.md: f1ef275610f6307578288d483eb561ee8d3c7531 diff --git a/.agents/notes/implemented/feature/2026-08-05-agent-teams.md b/.agents/notes/implemented/feature/2026-08-05-agent-teams.md index fbcd8485a9..df84b2710d 100644 --- a/.agents/notes/implemented/feature/2026-08-05-agent-teams.md +++ b/.agents/notes/implemented/feature/2026-08-05-agent-teams.md @@ -32,7 +32,7 @@ Fresh children have no inherited conversation. Fork children capture the Lead's Peer communication is a Lead-log mailbox. `team/message/queued` is appended and flushed before delivery. The target message carries the stable message id and sender identity in both durable source metadata and a short model-visible prefix. A target receipt is acknowledged with `team/message/delivered` only after its pending inbox item or recorded user message is flushed. Immediate admission is serialized per target in queued-log order, recovery retries queued-minus-delivered in the same order, and delivery folds live or persisted target inbox/history state before cold resume. Every current-version Team payload is runtime-validated before entering replay state. The Team runtime tracks dispatch and asynchronous acknowledgement work from synchronous admission until settlement; disposal closes admission and awaits both before removing the service. Current waiters wake only after the owning Team event flush succeeds. -Quiet `send_message` injects, flushes, and acknowledges immediately for a live target without waking it; an inactive target remains queued until another event materializes that teammate. Waking `followup_task` becomes the target's next FIFO turn and may cold-resume it. Success means the message is already durable even when immediate delivery is deferred. The mechanism provides process-local retry and target-Session de-duplication, not a cross-process exactly-once claim. +`send_message` always attempts Steer delivery. A running target receives the message at the nearest step boundary, an idle target starts a turn, and an inactive teammate cold-resumes. Success means the message is already durable even when temporary delivery failure leaves it queued. The mechanism provides process-local retry and target-Session de-duplication, not a cross-process exactly-once claim. The [Team Steer messaging decision](../simplification/2026-08-30-team-send-message-steer.md) owns the single-tool scheduling rationale. Shared tasks are complete snapshots with Team-local ids and monotonic revisions. Every mutation carries `expectedRevision`. Any member creates, reads, or claims a ready unowned task; the owner or Lead edits and transitions it, while only the Lead assigns another member. Numeric task ids remain within the safe-integer allocation range, and exhaustion fails without reusing an id. Dependencies must name non-deleted tasks and form a complete DAG. Deleted tasks are retained tombstones. `writeScopes` are normalized path prefixes that produce overlap diagnostics but never block claim or authorize a write. @@ -48,7 +48,7 @@ Worktree isolation is not a harness runtime behavior. A deployment or prompt may **Extend direct-child subagent tools with peer ids.** Rejected because parent/child authority and Team peer membership are different domains. Adding peer access to the continuation seam would weaken its exact-parent authorization and still leave roster and tasks without a persistence owner. -**Store mail in each target Session before delivery.** Rejected because an inactive target is intentionally not materialized for quiet mail. The always-live Lead Session is the transaction home; target recording is the acknowledgement and de-duplication boundary. +**Store mail in each target Session before Lead-log enqueue.** Rejected because target materialization and acceptance can fail after the Team has committed the send. The always-live Lead Session is the transaction home; target recording is the acknowledgement and de-duplication boundary. **Treat task ownership or write scopes as locks.** Rejected because external writers bypass them, crashed owners remain durable, and path-prefix overlap cannot prove semantic independence. False mutual exclusion is more dangerous than an explicit warning. @@ -68,6 +68,6 @@ Package tests cover identity, name and authority checks, provider selection, res The Lead Session grows with whole task/member snapshots and mailbox acknowledgements. This favors independently inspectable recovery over compact deltas; configured task and pending-mail bounds cap active state, while deleted and delivered history remains append-only until broader Session retention applies. -An active roster member can be non-resident, so `inactive` is not failure and a wakeup can incur cold-resume latency. A quiet message for an inactive target can remain pending indefinitely until the target is otherwise materialized. A failed member permanently consumes its name and member slot, making provisioning failures visible instead of silently recycling identity. +An active roster member can be non-resident, so `inactive` is not failure and a send can incur cold-resume latency. Temporary inspection, resume, or inbox-admission failure can leave a durable message queued for recovery. A failed member permanently consumes its name and member slot, making provisioning failures visible instead of silently recycling identity. Coordination reduces likely checkout conflicts but cannot eliminate writes outside filesystem compare-and-set tools. The final diff and tests remain the Lead's integration boundary. diff --git a/.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md b/.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md index 0a1a8a81c4..f1ef275610 100644 --- a/.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md +++ b/.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md @@ -32,7 +32,7 @@ fresh child 不继承对话。fork child 只捕获一次 Lead 已完成 turn 前 Peer 通讯使用 Lead 日志 mailbox。投递前先追加并 flush `team/message/queued`。target message 会在持久 source metadata 与短模型可见前缀中同时携带稳定 message id 和 sender identity。只有 pending inbox 条目或已记录用户消息完成 flush,Lead 日志才写入 `team/message/delivered` acknowledgement。即时准入按 target 和 queued 日志顺序串行化,恢复按同一顺序重试 queued-minus-delivered,并在冷恢复前折叠 live 或 persisted target 的 inbox/历史状态。每个当前版本 Team payload 都会经过运行时验证后才进入 replay state。Team runtime 从同步准入到 settlement 全程跟踪 dispatch 与异步 acknowledgement 工作;dispose 会关闭准入,并在移除服务前等待两者。当前 waiter 只在所属 Team event flush 成功后被唤醒。 -对于 live target,quiet `send_message` 会立即注入、flush 并确认,但不会唤醒它;inactive target 会保持 queued,直到其他事件 materialize 该 teammate。waking `followup_task` 成为 target 的下一个 FIFO turn,并可冷恢复。即使即时投递被推迟,成功也表示消息已经持久化。该机制提供进程内重试与 target Session 去重,不宣称跨进程 exactly-once。 +`send_message` 始终尝试 Steer 投递。running target 在最近的步骤边界收到消息,idle target 启动一个轮次,inactive teammate 则冷恢复。即使临时投递失败让消息保持 queued,成功也表示消息已经持久化。该机制提供进程内重试与 target Session 去重,不宣称跨进程 exactly-once。[Team Steer 消息决策](../simplification/2026-08-30-team-send-message-steer.zh.md)负责单工具调度的理由。 共享 task 是带 Team-local id 与单调 revision 的完整快照。每次变更都携带 `expectedRevision`。任意 member 可以创建、读取或 claim ready 且无 owner 的任务;Owner 或 Lead 可以编辑和转换;只有 Lead 可以分配给另一个 member。数字 task id 保持在安全整数分配范围内;该范围耗尽时会失败,不会复用 id。依赖必须指向未删除任务,并形成完整 DAG。删除任务保留为 tombstone。`writeScopes` 是规范化路径前缀,只产生重叠诊断,绝不会阻止 claim 或授予写权限。 @@ -48,7 +48,7 @@ Worktree isolation 不是 harness runtime 行为。deployment 或 prompt 可以 **用 peer id 扩展 direct-child subagent tool。** 拒绝,因为 parent/child 权限与 Team peer membership 是不同领域。向 continuation seam 增加 peer access 会削弱 exact-parent authorization,仍无法为 roster 与 task 提供持久 owner。 -**投递前把 mail 存入每个 target Session。** 拒绝,因为 quiet mail 不会 materialize inactive target。始终 live 的 Lead Session 是事务 owner;target recording 是 acknowledgement 与去重边界。 +**在 Lead 日志入队前把 mail 存入每个 target Session。** 拒绝,因为 Team 提交发送之后,target materialization 与准入仍可能失败。始终 live 的 Lead Session 是事务 owner;target recording 是 acknowledgement 与去重边界。 **把 task ownership 或 write scope 当作锁。** 拒绝,因为外部 writer 会绕过它们,崩溃 owner 会持久保留,而路径前缀重叠不能证明语义独立。虚假的互斥保证比明确 warning 更危险。 @@ -68,6 +68,6 @@ Package test 以逐文件 100% coverage 覆盖身份、名字与权限检查、p Lead Session 会随着完整 task/member 快照与 mailbox acknowledgement 增长。该设计用可独立检查的恢复能力换取更紧凑的 delta;配置的 task 与 pending-mail 限额限制 active state,而 deleted 与 delivered 历史会保持 append-only,直到更广泛的 Session retention 生效。 -active roster member 可以不驻留,因此 `inactive` 不表示失败,wakeup 可能产生 cold-resume 延迟。发往 inactive target 的 quiet message 可能无限等待,直到 target 因其他原因 materialize。failed member 会永久占用名字与 member slot,使 provisioning failure 保持可见而不是静默回收身份。 +active roster member 可以不驻留,因此 `inactive` 不表示失败,send 可能产生 cold-resume 延迟。临时 inspection、resume 或 inbox 准入失败可能留下持久 queued 消息等待恢复。failed member 会永久占用名字与 member slot,使 provisioning failure 保持可见而不是静默回收身份。 协调可以降低 checkout 冲突概率,但无法消除文件系统 CAS 工具之外的写入。最终 diff 与测试仍是 Lead 的集成边界。 diff --git a/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.i18n.yaml new file mode 100644 index 0000000000..66a26247ec --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.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-08-30-team-send-message-steer.md +2026-08-30-team-send-message-steer.md: 9eb38ec96f51d074510bd918fc46bac9a61027d0 +2026-08-30-team-send-message-steer.zh.md: 44ed792a1c1a4e149c3309a538dfbe6418612b16 diff --git a/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.md b/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.md new file mode 100644 index 0000000000..9eb38ec96f --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.md @@ -0,0 +1,41 @@ +# Agent Note: Team messaging uses one Steer send_message operation + +Status: implemented + +English | [中文](2026-08-30-team-send-message-steer.zh.md) + +## Problem + +Agent Teams exposed two model operations for one durable mailbox: quiet `send_message` injected into a live target without waking it, while `followup_task` queued a distinct waking turn and cold-resumed an inactive teammate. Models had to choose a scheduling policy instead of stating whom to message, and quiet messages could accumulate for an inactive teammate until unrelated work resumed it. + +The ordinary continuable-Agent controls already use one direction-neutral `send_message` with fixed Steer scheduling. Retaining separate Team names and delivery modes made equivalent model communication depend on whether the target happened to be a direct child or a Team peer. + +## Decision + +Every Team member receives one `send_message({ target, message })` tool. The Team tool set contains nine operations; `followup_task` and model-selectable quiet delivery are absent. The durable `TeamMessageSnapshot` stores sender, target, content, and message identity without a scheduling field. + +Every accepted Team message uses Steer. A running target receives it at the nearest step boundary, an idle target starts a turn, and an inactive teammate cold-resumes through the continuation lifecycle. A successful Team send remains durable before delivery starts. `accepted` means the target inbox accepted the message; `queued` means a temporary inspection, resume, or inbox-admission failure left it in the Team mailbox for recovery. Neither result means the target completed the requested work. + +The Lead receives the Team-attributed user message through `Agent.steer()`. A teammate receives it through a symbol-keyed host-only continuation adapter that authorizes the exact Lead-to-direct-child edge, preserves the original `TeamMessageSource`, and performs resident or cold-resume Steer admission. Sibling and teammate-to-Lead messages therefore retain the real sender; the Team runtime never calls public adjacent-Agent `sendMessage()` while impersonating the Lead. + +The Lead Session remains the mailbox transaction owner. It flushes `team/message/queued` before dispatch, serializes immediate admissions per target in Lead-log order, and records `team/message/delivered` only after the target Session durably contains the same Team message id. Recovery retries queued-minus-delivered records in order, and target-side source folding prevents duplicate acceptance across the crash window between inbox insertion and acknowledgement. + +## Alternatives considered + +**Keep quiet `send_message` and waking `followup_task`.** This preserves caller control over turn scheduling but makes the model choose an implementation policy, permits unread durable mail on inactive targets, and diverges from adjacent-Agent messaging. + +**Keep `followup_task` as an alias for Steer.** Two names for identical behavior would preserve the tool-selection failure without adding an observable capability. + +**Route siblings through public adjacent-Agent `sendMessage()`.** That operation authorizes only exact direct-parent or direct-child model senders and derives its own `AgentMessageSource`. Calling it with the Lead would misattribute sibling mail; widening it to Team membership would weaken its adjacency rule. + +**Drop the Team mailbox and deliver directly.** Direct delivery loses durable enqueue-before-admission, recovery after temporary failure, stable message ids, and target-side de-duplication. + +## Testing + +Package tests pin running, idle, inactive, Lead, sibling, and recovery delivery; target-local ordering; sender attribution; inbox/history de-duplication; temporary failure returning `queued`; and the nine-tool schema. The keyless Agent Teams profile snapshot drives a running implementer, steers a researcher message into its next step, and verifies that both teammates still complete their assigned tasks before the Lead aggregates the result. + +## Consequences + +Models have one Team communication choice and cannot park quiet information intentionally. A message may extend the target's current turn, so prompts and tests require teammates to integrate new messages without abandoning work already in progress. + +The host-only Steer adapter becomes part of the internal continuation integration used by Team delivery. Human browser prompts keep the separate Queue adapter and remain distinct turns. The broader [Agent Teams decision](../feature/2026-08-05-agent-teams.md) retains mailbox, roster, task, and shared-checkout ownership; the [adjacent-Agent messaging decision](../architecture/2026-08-27-adjacent-agent-steer-messaging.md) retains the public direct-edge authorization and model-message source. diff --git a/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.zh.md b/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.zh.md new file mode 100644 index 0000000000..44ed792a1c --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.zh.md @@ -0,0 +1,41 @@ +# Agent Note: Team 消息使用单一 Steer send_message 操作 + +Status: implemented + +[English](2026-08-30-team-send-message-steer.md) | 中文 + +## 问题 + +Agent Teams 为一个持久 mailbox 公开了两个模型操作:quiet `send_message` 注入 live target 而不唤醒它,`followup_task` 则排入一个独立 waking turn 并冷恢复 inactive teammate。模型必须选择调度策略,而不是只说明消息目标;quiet 消息可能为 inactive teammate 持续累积,直到无关工作恢复它。 + +普通 continuable-Agent 控件已经使用一个方向无关、固定 Steer 调度的 `send_message`。保留独立的 Team 名称与投递模式,会让等价的模型通信因为 target 恰好是 direct child 还是 Team peer 而采用不同语义。 + +## 决策 + +每个 Team member 都会获得一个 `send_message({ target, message })` 工具。Team 工具集包含九个操作;不存在 `followup_task` 与模型可选的 quiet 投递。持久 `TeamMessageSnapshot` 存储 sender、target、content 与 message identity,不存储调度字段。 + +每条已接受的 Team 消息都使用 Steer。running target 在最近的步骤边界收到消息,idle target 启动一个轮次,inactive teammate 则通过 continuation lifecycle 冷恢复。每次成功的 Team send 都会在开始投递前完成持久化。`accepted` 表示 target inbox 已接受消息;`queued` 表示临时 inspection、resume 或 inbox 准入失败让消息留在 Team mailbox 等待恢复。两种结果都不表示 target 已完成所请求的工作。 + +Lead 通过 `Agent.steer()` 接收携带 Team 归因的用户消息。teammate 通过 symbol-keyed host-only continuation adapter 接收消息;该 adapter 会授权精确的 Lead-to-direct-child edge、保留原始 `TeamMessageSource`,并执行 resident 或 cold-resume Steer 准入。因此 sibling 与 teammate-to-Lead 消息保留真实 sender;Team 运行时绝不会伪装成 Lead 调用公开的相邻 Agent `sendMessage()`。 + +Lead Session 继续作为 mailbox transaction owner。它在 dispatch 前 flush `team/message/queued`,按 Lead 日志顺序为每个 target 串行化即时准入,并且只有 target Session 持久包含相同 Team message id 后才记录 `team/message/delivered`。恢复按顺序重试 queued-minus-delivered 记录;target 侧 source 折叠会防止 inbox insertion 与 acknowledgement 之间的 crash window 导致重复准入。 + +## 考虑过的替代方案 + +**保留 quiet `send_message` 与 waking `followup_task`。** 这会保留调用方对 turn 调度的控制,但要求模型选择实现策略、允许 inactive target 存在未读持久 mail,并与相邻 Agent 消息语义分叉。 + +**保留 `followup_task` 作为 Steer 别名。** 两个名字表达同一行为只会保留工具选择错误,不会增加可观察能力。 + +**通过公开的相邻 Agent `sendMessage()` 路由 sibling。** 该操作只授权精确的 direct-parent 或 direct-child 模型 sender,并派生自己的 `AgentMessageSource`。以 Lead 身份调用会错误归因 sibling mail;把它扩展到 Team membership 则会削弱相邻关系规则。 + +**删除 Team mailbox 并直接投递。** 直接投递会失去准入前持久入队、临时失败后的恢复、稳定 message id 与 target 侧去重。 + +## 测试 + +包测试固定 running、idle、inactive、Lead、sibling 与 recovery 投递,target-local ordering、sender attribution、inbox/history 去重、临时失败返回 `queued`,以及九工具 schema。无密钥 Agent Teams profile snapshot 驱动 running implementer,把 researcher 消息 Steer 到其下一步骤,并验证两个 teammate 都继续完成各自任务,之后 Lead 才汇总结果。 + +## 后果 + +模型只有一种 Team 通信选择,不能有意停放 quiet information。一条消息可能扩展 target 的当前 turn,因此提示词与测试要求 teammate 整合新消息,同时不放弃已经进行的工作。 + +host-only Steer adapter 成为 Team 投递使用的内部 continuation 集成。人类浏览器 prompt 保留独立 Queue adapter,并继续形成不同 turn。更广泛的 [Agent Teams 决策](../feature/2026-08-05-agent-teams.zh.md)继续负责 mailbox、roster、task 与共享 checkout;[相邻 Agent 消息决策](../architecture/2026-08-27-adjacent-agent-steer-messaging.zh.md)继续负责公开 direct-edge authorization 与 model-message source。 diff --git a/apps/cli/tests/profiles/headless/tests/fixtures/team-llm.mjs b/apps/cli/tests/profiles/headless/tests/fixtures/team-llm.mjs index 57f0fe3dd2..0e31795018 100644 --- a/apps/cli/tests/profiles/headless/tests/fixtures/team-llm.mjs +++ b/apps/cli/tests/profiles/headless/tests/fixtures/team-llm.mjs @@ -88,6 +88,9 @@ function implementer(messages) { const names = calls(messages) const last = latestAssistantCalls(messages) const text = latestToolText(messages) + const userText = messages.flatMap(message => message.role === 'user' + ? message.content.filter(block => block.type === 'text').map(block => block.text) + : []).join('\n') if (!names.includes('team_task_create')) { if (last.includes('team_task_get') && text.includes('"subject":"Research"')) { return toolChunks([{ name: 'team_task_create', args: { @@ -116,6 +119,9 @@ function implementer(messages) { } return toolChunks([{ name: 'team_task_get', args: { task_id: 'task-1' } }]) } + if (!userText.includes('Research complete: use the deterministic finding.')) { + return toolChunks([{ name: 'wait_agent', args: { timeout_ms: 10000 } }]) + } if (!names.includes('send_message')) { return toolChunks([ { name: 'team_task_update', args: { task_id: 'task-2', expected_revision: 2, action: 'complete' } }, diff --git a/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts index b87618c6ad..0df4046f60 100644 --- a/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts +++ b/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts @@ -558,6 +558,49 @@ describe('headless stream-json snapshots', () => { const tasks = rows.filter(row => row.type === 'team/task') .map(row => ((row.data as JsonObject).task as JsonObject)) const latestTasks = Object.values(Object.fromEntries(tasks.map(task => [String(task.subject), task]))) + const implementer = logs.find(log => typeof log.header.parentSession === 'string' + && parseJsonl(log.content).some((row) => { + if (row.type !== 'user/message') return false + const content: unknown = (row.data as JsonObject).content + return Array.isArray(content) && content.some((block: unknown) => ( + typeof block === 'object' && block !== null && !Array.isArray(block) + && (block as JsonObject).type === 'text' + && typeof (block as JsonObject).text === 'string' + && ((block as JsonObject).text as string).includes('IMPLEMENTER_MARK') + )) + })) + if (implementer === undefined) throw new Error('Agent Teams snapshot did not persist the implementer') + const implementerRows = parseJsonl(implementer.content) + const steeredInboxIndex = implementerRows.findIndex((row) => { + if (row.type !== 'agent/inbox/spliced') return false + const data = row.data as JsonObject + const inserted: unknown = data.inserted + return data.target === 'next-step' && Array.isArray(inserted) + && inserted.some((message: unknown) => { + if (typeof message !== 'object' || message === null || Array.isArray(message)) return false + const source = (message as JsonObject).source + return typeof source === 'object' && source !== null && !Array.isArray(source) + && (source as JsonObject).kind === 'team-message' + }) + }) + const steeredMessageIndex = implementerRows.findIndex((row) => { + if (row.type !== 'user/message') return false + const source = (row.data as JsonObject).source + return typeof source === 'object' && source !== null && !Array.isArray(source) + && (source as JsonObject).kind === 'team-message' + }) + const openTurnStart = implementerRows.findLastIndex((row, index) => ( + index < steeredMessageIndex && row.type === 'turn/start' + )) + const openTurnEnd = implementerRows.findLastIndex((row, index) => ( + index < steeredMessageIndex && row.type === 'turn/end' + )) + const completionAfterSteer = implementerRows.some((row, index) => { + if (index <= steeredMessageIndex || row.type !== 'tool/call') return false + const data = row.data as JsonObject + if (data.name !== 'team_task_update' || typeof data.arguments !== 'string') return false + return (JSON.parse(data.arguments) as JsonObject).action === 'complete' + }) projection = { sessions: logs.length, memberEdges: members.length, @@ -573,6 +616,12 @@ describe('headless stream-json snapshots', () => { && (row.data as JsonObject).name === 'wait_agent'), checkedRoster: rows.some(row => row.type === 'tool/call' && (row.data as JsonObject).name === 'list_agents'), + steerEvidence: { + nextStepInbox: steeredInboxIndex >= 0, + messageEntered: steeredMessageIndex > steeredInboxIndex, + enteredOpenTurn: openTurnStart > openTurnEnd, + completedAfterMessage: completionAfterSteer, + }, } }, }) @@ -592,6 +641,12 @@ describe('headless stream-json snapshots', () => { "memberEdges": 4, "queuedMessages": 2, "sessions": 3, + "steerEvidence": { + "completedAfterMessage": true, + "enteredOpenTurn": true, + "messageEntered": true, + "nextStepInbox": true, + }, "tasks": [ { "revision": 3, diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 3989c90eb9..a5fb188f37 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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/config-catalog.md -config-catalog.md: 85aead7a93bd8dff0da4eb4f0e6b6b348d9616b9 -config-catalog.zh.md: f91ebc6c46989cbf98d2a773f6f2873539ad6351 +config-catalog.md: 9da02ad73092ec491d1dcfdfb1a9c053908dfd20 +config-catalog.zh.md: 47d2deebbf24124bde15c0a6eae2b86151a02b16 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 85aead7a93..9da02ad730 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -535,7 +535,7 @@ export interface Config { } ``` -Source: [`packages/experimental/agent-team/src/types.ts:131`](../packages/experimental/agent-team/src/types.ts) +Source: [`packages/experimental/agent-team/src/types.ts:130`](../packages/experimental/agent-team/src/types.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index f91ebc6c46..47d2deebbf 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -537,7 +537,7 @@ export interface Config { } ``` -来源:[`packages/experimental/agent-team/src/types.ts:125`](../packages/experimental/agent-team/src/types.ts) +来源:[`packages/experimental/agent-team/src/types.ts:124`](../packages/experimental/agent-team/src/types.ts) diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index c5520d4dd2..99ed2f2849 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.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/persistence-catalog.md -persistence-catalog.md: fd5b3a4a377069fb7b1fbc37b78d11ec037073a4 -persistence-catalog.zh.md: 9d8fc88a44da1620e2de9aa066b9d6c6204b29b1 +persistence-catalog.md: a3aa16ce1a0fd5daa55935e4d409a72d2d0a4601 +persistence-catalog.zh.md: e2a17d7e4ff29e706a44706b3db6c44c2500ac99 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index fd5b3a4a37..a3aa16ce1a 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -781,7 +781,7 @@ Source: [`packages/subagent/tool-subagent/src/model-selection-state.ts:17`](../p Types: [TeamId](subsystems/agent-team.md) · [TeamMemberSnapshot](subsystems/agent-team.md) -Source: [`packages/experimental/agent-team/src/types.ts:223`](../packages/experimental/agent-team/src/types.ts) +Source: [`packages/experimental/agent-team/src/types.ts:221`](../packages/experimental/agent-team/src/types.ts) @@ -799,7 +799,7 @@ Source: [`packages/experimental/agent-team/src/types.ts:223`](../packages/experi Types: [TeamId](subsystems/agent-team.md) · [TeamMessageId](subsystems/agent-team.md) -Source: [`packages/experimental/agent-team/src/types.ts:229`](../packages/experimental/agent-team/src/types.ts) +Source: [`packages/experimental/agent-team/src/types.ts:227`](../packages/experimental/agent-team/src/types.ts) @@ -812,7 +812,7 @@ Source: [`packages/experimental/agent-team/src/types.ts:229`](../packages/experi Types: [TeamId](subsystems/agent-team.md) · [TeamMessageSnapshot](subsystems/agent-team.md) -Source: [`packages/experimental/agent-team/src/types.ts:227`](../packages/experimental/agent-team/src/types.ts) +Source: [`packages/experimental/agent-team/src/types.ts:225`](../packages/experimental/agent-team/src/types.ts) @@ -825,7 +825,7 @@ Source: [`packages/experimental/agent-team/src/types.ts:227`](../packages/experi Types: [TeamId](subsystems/agent-team.md) · [TeamTaskSnapshot](subsystems/agent-team.md) -Source: [`packages/experimental/agent-team/src/types.ts:225`](../packages/experimental/agent-team/src/types.ts) +Source: [`packages/experimental/agent-team/src/types.ts:223`](../packages/experimental/agent-team/src/types.ts) ### `todo/*` diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index 9d8fc88a44..e2a17d7e4f 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -783,7 +783,7 @@ export type SessionEvent = { 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamMemberSnapshot](subsystems/agent-team.zh.md) -来源:[`packages/experimental/agent-team/src/types.ts:206`](../packages/experimental/agent-team/src/types.ts) +来源:[`packages/experimental/agent-team/src/types.ts:204`](../packages/experimental/agent-team/src/types.ts) @@ -801,7 +801,7 @@ export type SessionEvent = { 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamMessageId](subsystems/agent-team.zh.md) -来源:[`packages/experimental/agent-team/src/types.ts:212`](../packages/experimental/agent-team/src/types.ts) +来源:[`packages/experimental/agent-team/src/types.ts:210`](../packages/experimental/agent-team/src/types.ts) @@ -814,7 +814,7 @@ export type SessionEvent = { 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamMessageSnapshot](subsystems/agent-team.zh.md) -来源:[`packages/experimental/agent-team/src/types.ts:210`](../packages/experimental/agent-team/src/types.ts) +来源:[`packages/experimental/agent-team/src/types.ts:208`](../packages/experimental/agent-team/src/types.ts) @@ -827,7 +827,7 @@ export type SessionEvent = { 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamTaskSnapshot](subsystems/agent-team.zh.md) -来源:[`packages/experimental/agent-team/src/types.ts:208`](../packages/experimental/agent-team/src/types.ts) +来源:[`packages/experimental/agent-team/src/types.ts:206`](../packages/experimental/agent-team/src/types.ts) ### `todo/*` diff --git a/docs/subsystems/agent-team.i18n.yaml b/docs/subsystems/agent-team.i18n.yaml index 37a3cbfb1c..8e3d2f6a95 100644 --- a/docs/subsystems/agent-team.i18n.yaml +++ b/docs/subsystems/agent-team.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/agent-team.md -agent-team.md: e3a746734b067bb7ef8f083c5c9af9cb3707dcf7 -agent-team.zh.md: 1f885a73861c091b50d27d15080ebc09f6d382ec +agent-team.md: 201123ea94499ff20cae25d68b1f7a826439d143 +agent-team.zh.md: d6973ae6899c1d884dc51bd71afbd36a41895527 diff --git a/docs/subsystems/agent-team.md b/docs/subsystems/agent-team.md index e3a746734b..201123ea94 100644 --- a/docs/subsystems/agent-team.md +++ b/docs/subsystems/agent-team.md @@ -2,7 +2,7 @@ English | [中文](agent-team.zh.md) -Types shared by the experimental implicit-root Team domain, model tools, and host adapters. The [Agent Teams Agent Note](../../.agents/notes/implemented/feature/2026-08-05-agent-teams.md) owns identity, mailbox, task, and shared-checkout decisions; this page records the literal durable forms from [`packages/experimental/agent-team/src/types.ts`](../../packages/experimental/agent-team/src/types.ts). +Types shared by the experimental implicit-root Team domain, model tools, and host adapters. The [Agent Teams Agent Note](../../.agents/notes/implemented/feature/2026-08-05-agent-teams.md) owns identity, mailbox, task, and shared-checkout decisions; the [Team Steer messaging Agent Note](../../.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.md) owns message scheduling; this page records the literal durable forms from [`packages/experimental/agent-team/src/types.ts`](../../packages/experimental/agent-team/src/types.ts). ## Identity and roster @@ -34,11 +34,12 @@ interface TeamMessageSnapshot { readonly senderId: SessionId readonly senderName: string readonly targetId: SessionId - readonly delivery: 'quiet' | 'wakeup' readonly content: ContentBlock[] } ``` +Every message attempts Steer delivery. A running target receives it at the nearest step boundary, an idle target starts a turn, and an inactive teammate cold-resumes. Scheduling is not stored in the durable record because callers cannot select another mode. + The target Session keeps message identity and sender attribution on both the pending inbox item and the eventual user message. Folding that source across inbox and history is the target-side de-duplication key; the model-visible framing repeats the id and sender. ```ts type-equiv @@ -116,7 +117,7 @@ async spawnTeammate(caller: Agent, request: SpawnTeammateRequest): Promise diff --git a/docs/subsystems/agent-team.zh.md b/docs/subsystems/agent-team.zh.md index 1f885a7386..d6973ae689 100644 --- a/docs/subsystems/agent-team.zh.md +++ b/docs/subsystems/agent-team.zh.md @@ -2,7 +2,7 @@ [English](agent-team.md) | 中文 -实验性隐式 Root Team 领域、模型工具与宿主适配器共享的类型。[Agent Teams Agent Note](../../.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md)负责身份、mailbox、task 与共享 checkout 决策;本页记录 [`packages/experimental/agent-team/src/types.ts`](../../packages/experimental/agent-team/src/types.ts) 中的字面持久形式。 +实验性隐式 Root Team 领域、模型工具与宿主适配器共享的类型。[Agent Teams Agent Note](../../.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md)负责身份、mailbox、task 与共享 checkout 决策;[Team Steer 消息 Agent Note](../../.agents/notes/implemented/simplification/2026-08-30-team-send-message-steer.zh.md)负责消息调度;本页记录 [`packages/experimental/agent-team/src/types.ts`](../../packages/experimental/agent-team/src/types.ts) 中的字面持久形式。 ## 身份与 roster @@ -34,11 +34,12 @@ interface TeamMessageSnapshot { readonly senderId: SessionId readonly senderName: string readonly targetId: SessionId - readonly delivery: 'quiet' | 'wakeup' readonly content: ContentBlock[] } ``` +每条消息都会尝试 Steer 投递。running target 在最近的步骤边界收到消息,idle target 启动一个轮次,inactive teammate 则冷恢复。调用方不能选择其他模式,因此持久记录不存储调度方式。 + target Session 会在 pending inbox 条目和最终用户消息上保留消息身份与发送者归因。跨 inbox 与历史折叠该 source 构成 target 侧去重键;模型可见的 framing 会重复 id 和发送者。 ```ts type-equiv @@ -116,7 +117,7 @@ async spawnTeammate(caller: Agent, request: SpawnTeammateRequest): Promise diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml index afcff35539..a70f3d6e35 100644 --- a/docs/tool-catalog.i18n.yaml +++ b/docs/tool-catalog.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/tool-catalog.md -tool-catalog.md: f71c5dea97ca92fd816c45c6fbd816ee05309d63 -tool-catalog.zh.md: 3286da7015cfa793820f6107a96af1fc73472ddb +tool-catalog.md: 416585106de28296a3105fafbbe6e4edc0d0f16b +tool-catalog.zh.md: 89d2e467863c09b78805fd9db8ec785ad7936a9d diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index f71c5dea97..416585106d 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -36,7 +36,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-subagent` | `list_subagent_models`, `subagent` | `ctx.tools`, `ctx.subagents`, `ctx.systemPrompt`, `ctx.llm for model discovery and selected-route validation` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered delegation name is the load-time `toolName` config (default `subagent`); the default schema above has model selection off, while the discovery schema is shown as the fixed companion available in an enabled Session. Web presets sample the Plugins preference for each new top-level Session and preserve that decision for its child Sessions; `subagent_fork` remains fixed-route. Each instance independently controls whether it reads model-selection settings and its background behavior through `modelSelectionSettings`, `backgroundMode`, and `enableRunInBackground`. | | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`, `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries). | | `@deepseek-ai/dsh-tool-jobs` | `job_kill`, `job_list`, `job_output` | `ctx.tools`, `ctx.jobs`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-job controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' `ctx.jobs.start()`. | -| `@deepseek-ai/dsh-experimental-tool-agent-team` | `followup_task`, `interrupt_agent`, `list_agents`, `send_message`, `spawn_teammate`, `team_task_create`, `team_task_get`, `team_task_list`, `team_task_update`, `wait_agent` | `ctx.tools`, `ctx.systemPrompt`, `ctx.agentTeams`, `an exact live Team member Agent` | `tool/call`, `team/member`, `team/message/queued`, `team/message/delivered`, `team/task`, `tool/result` | - | All ten tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names. | +| `@deepseek-ai/dsh-experimental-tool-agent-team` | `interrupt_agent`, `list_agents`, `send_message`, `spawn_teammate`, `team_task_create`, `team_task_get`, `team_task_list`, `team_task_update`, `wait_agent` | `ctx.tools`, `ctx.systemPrompt`, `ctx.agentTeams`, `an exact live Team member Agent` | `tool/call`, `team/member`, `team/message/queued`, `team/message/delivered`, `team/task`, `tool/result` | - | All nine tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task. | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflowEngine`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - | | `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. | @@ -1742,32 +1742,6 @@ The kind-agnostic background-job controller: background bash commands, PTY sends ## `@deepseek-ai/dsh-experimental-tool-agent-team` -### `followup_task` - -Send a durable follow-up task to another Team member and start a turn when needed. - -```json -{ - "type": "object", - "properties": { - "target": { - "type": "string", - "description": "Team member name, or lead." - }, - "message": { - "type": "string", - "description": "Self-contained message for the target." - } - }, - "required": [ - "target", - "message" - ] -} -``` - -Source: [`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) - ### `interrupt_agent` Interrupt one teammate's current turn while preserving its pending inbox. Team Lead only. @@ -1804,7 +1778,7 @@ Source: [`packages/experimental/tool-agent-team/src/index.ts`](../packages/exper ### `send_message` -Send durable information to another Team member without starting an idle member. +Send one durable message to another Team member. A running target receives it at the nearest step boundary; an idle target starts a turn; an inactive teammate cold-resumes. ```json { @@ -2052,7 +2026,7 @@ Wait for the next teammate status, mailbox, or shared-task change after this cal Source: [`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) -All ten tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names. +All nine tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names. diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md index 3286da7015..89d2e46786 100644 --- a/docs/tool-catalog.zh.md +++ b/docs/tool-catalog.zh.md @@ -40,7 +40,7 @@ | `@deepseek-ai/dsh-tool-subagent` | `list_subagent_models`、`subagent` | `ctx.tools`、`ctx.subagents`、`ctx.systemPrompt`、`用于模型发现和所选路由校验的 ctx.llm` | `tool/call`、`tool/result`、`child session events through the chosen provider` | `subagent`、`subagent_fork` | 注册的委派工具名称取决于加载时 `toolName` 配置(默认为 `subagent`);上述默认 schema 关闭模型选择,而发现 schema 则展示为已启用 Session 中可用的固定配套工具。Web preset 会在每个新顶层 Session 创建时读取插件页偏好,并为其子 Session 保留该决定;`subagent_fork` 始终使用固定路由。每个实例通过 `modelSelectionSettings`、`backgroundMode` 与 `enableRunInBackground` 独立控制是否读取模型选择设置及其后台行为。 | | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`child session events through ctx.subagents` | - | 这些是控制可继续后台 subagent 的全局命名工具:绑定提供方的 `tool-subagent` 实例注册不同的委派工具;本包注册一次 `send_message` 和 `interrupt_agent`,另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供,其目录行使用 sessionProjections 和实时 Agent 注册表。 | | `@deepseek-ai/dsh-tool-jobs` | `job_kill`、`job_list`、`job_output` | `ctx.tools`、`ctx.jobs`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制器:后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器,从而启用生产方的 `ctx.jobs.start()`。 | -| `@deepseek-ai/dsh-experimental-tool-agent-team` | `followup_task`、`interrupt_agent`、`list_agents`、`send_message`、`spawn_teammate`、`team_task_create`、`team_task_get`、`team_task_list`、`team_task_update`、`wait_agent` | `ctx.tools`、`ctx.systemPrompt`、`ctx.agentTeams`、`an exact live Team member Agent` | `tool/call`、`team/member`、`team/message/queued`、`team/message/delivered`、`team/task`、`tool/result` | - | 这 10 个工具限定于隐式 Team Lead 与持久 teammate 作用域。随产品发布的 dsh-base bundle 默认禁用该包;文档中的 Agent Teams profile patch 会启用它,并禁用旧 continuable child 的同名控制工具。 | +| `@deepseek-ai/dsh-experimental-tool-agent-team` | `interrupt_agent`、`list_agents`、`send_message`、`spawn_teammate`、`team_task_create`、`team_task_get`、`team_task_list`、`team_task_update`、`wait_agent` | `ctx.tools`、`ctx.systemPrompt`、`ctx.agentTeams`、`an exact live Team member Agent` | `tool/call`、`team/member`、`team/message/queued`、`team/message/delivered`、`team/task`、`tool/result` | - | 这 9 个工具限定于隐式 Team Lead 与持久 teammate 作用域。随产品发布的 dsh-base bundle 默认禁用该包;文档中的 Agent Teams profile patch 会启用它,并禁用旧 continuable child 的同名控制工具。 | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态;UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项,因此本目录明确选择 `true`,对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具,但描述会要求只能有 1 个活动任务。 | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflowEngine`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - | | `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后,使模型可见 schema 在更换后端时保持稳定。 | @@ -1748,32 +1748,6 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后, ## `@deepseek-ai/dsh-experimental-tool-agent-team` -### `followup_task` - -向另一名 Team member 发送持久 follow-up task,并在需要时启动一个 turn。 - -```json -{ - "type": "object", - "properties": { - "target": { - "type": "string", - "description": "Team member name, or lead." - }, - "message": { - "type": "string", - "description": "Self-contained message for the target." - } - }, - "required": [ - "target", - "message" - ] -} -``` - -来源:[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) - ### `interrupt_agent` 中断一名 teammate 的当前 turn,同时保留其待处理 inbox。仅 Team Lead 可用。 @@ -1810,7 +1784,7 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后, ### `send_message` -向另一名 Team member 发送持久信息,但不启动 idle member。 +向另一名 Team member 发送一条持久消息。running target 会在最近的步骤边界收到消息;idle target 会启动一个 turn;inactive teammate 会冷恢复。 ```json { diff --git a/packages/experimental/README.i18n.yaml b/packages/experimental/README.i18n.yaml index a6d751aaa7..2a253523ab 100644 --- a/packages/experimental/README.i18n.yaml +++ b/packages/experimental/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/experimental/README.md -README.md: 689739bc532ddde4c41c3fb550d098add0501f70 -README.zh.md: 18499a28849dd3f4671ef266f24818cdc30f15e8 +README.md: 1a5f60c84327f47d9edea7d6bccb87d710a766f7 +README.zh.md: b97fd66854bcf8ad435348ddcba605f44eeffe52 diff --git a/packages/experimental/README.md b/packages/experimental/README.md index 689739bc53..1a5f60c843 100644 --- a/packages/experimental/README.md +++ b/packages/experimental/README.md @@ -30,7 +30,7 @@ The experimental group contains prototype capabilities that are not part of any | [`client-ui-agent-team`](client-ui-agent-team/README.md) | Team roster, task board, and teammate navigation for Web | — | | [`code-runtime-python`](code-runtime-python/README.md) | CPython subprocess backend for the code-execution seam | `ctx.codeRuntime` | | [`inspector`](inspector/README.md) | Cross-realm CDP hub for Host debugging, Client Runtime inspection, network capture, and Cordis trees | `ctx.inspector` | -| [`tool-agent-team`](tool-agent-team/README.md) | Ten tools that let the model create, message, and coordinate teammates | registers scoped tools on `ctx.tools` | +| [`tool-agent-team`](tool-agent-team/README.md) | Nine tools that let the model create, message, and coordinate teammates | registers scoped tools on `ctx.tools` | | [`webworker-packer`](webworker-packer/README.md) | Builds the gzip-compressed VFS image consumed by the browser worker preview | library and CLI — no ctx key | | [`webworker-runtime`](webworker-runtime/README.md) | Runs the harness plugin tree inside a dedicated browser worker | library and worker entry — no ctx key | diff --git a/packages/experimental/README.zh.md b/packages/experimental/README.zh.md index 18499a2884..b97fd66854 100644 --- a/packages/experimental/README.zh.md +++ b/packages/experimental/README.zh.md @@ -30,7 +30,7 @@ kind: "package-group" | [`client-ui-agent-team`](client-ui-agent-team/README.zh.md) | Web Team roster、任务板与 teammate 导航 | — | | [`code-runtime-python`](code-runtime-python/README.zh.md) | 代码执行 seam 的 CPython 子进程后端 | `ctx.codeRuntime` | | [`inspector`](inspector/README.zh.md) | 用于 Host 调试、Client Runtime 检查、网络采集与 Cordis 树的跨 realm CDP hub | `ctx.inspector` | -| [`tool-agent-team`](tool-agent-team/README.zh.md) | 让模型创建、发消息与协调 teammate 的十个工具 | 按作用域注册工具到 `ctx.tools` | +| [`tool-agent-team`](tool-agent-team/README.zh.md) | 让模型创建、发消息与协调 teammate 的九个工具 | 按作用域注册工具到 `ctx.tools` | | [`webworker-packer`](webworker-packer/README.zh.md) | 构建浏览器 worker 预览所消费的 gzip 压缩 VFS 镜像 | 库与 CLI,不使用 ctx key | | [`webworker-runtime`](webworker-runtime/README.zh.md) | 在专用浏览器 worker 中运行 harness 插件树 | 库与 worker 入口,不使用 ctx key | diff --git a/packages/experimental/agent-team/README.i18n.yaml b/packages/experimental/agent-team/README.i18n.yaml index f4ee635c11..5dda62d955 100644 --- a/packages/experimental/agent-team/README.i18n.yaml +++ b/packages/experimental/agent-team/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/experimental/agent-team/README.md -README.md: 0316834f566112b708f513b46cd0e5e3ab503061 -README.zh.md: 0aae14bccc06c57a9e1698f302cadd6b293baca8 +README.md: 1f9f7e98fdd2d8c32c6da2d514ff763367d6eb65 +README.zh.md: d6b57d35b6305c94fad966e3c9b3e20f6a3e81f5 diff --git a/packages/experimental/agent-team/README.md b/packages/experimental/agent-team/README.md index 0316834f56..1f9f7e98fd 100644 --- a/packages/experimental/agent-team/README.md +++ b/packages/experimental/agent-team/README.md @@ -68,7 +68,7 @@ Only the Lead can create teammates or interrupt them. Any member can send a message to any other member or to the Lead. A live member receives it immediately; an offline member's messages queue and arrive when it resumes. Messages are never lost and never delivered twice. -Two delivery modes cover the two common intents: a quiet message delivers information without starting an idle teammate (use it for updates that can wait), and a follow-up makes the message the recipient's next turn (use it to hand over work). The sender always sees the outcome — delivered now, or queued. A queued message is already safely stored, so it must not be resent. +Every message uses Steer: a running target receives it at the nearest step boundary, an idle target starts a turn, and an inactive teammate cold-resumes. The sender always sees the outcome — accepted by the target inbox, or retained as queued when delivery is temporarily unavailable. A queued message is already safely stored, so it must not be resent. ### Shared task board @@ -131,6 +131,8 @@ Every ordinary runtime root is the implicit Lead of a Team whose `TeamId` equals `sendMessage()` validates peer membership, appends `team/message/queued`, and flushes before attempting delivery. The target message begins with `Team message from :` and keeps the same id and sender in `TeamMessageSource`. A target receipt is acknowledged with `team/message/delivered` only after the target Session durably holds the message identity in its pending inbox or recorded history. Immediate admissions are serialized per target in durable queue order; recovery dispatches queued-minus-delivered records in the same order. Delivery folds both live and persisted target inbox/history state before retrying, so a crash between inbox acceptance and model claim does not duplicate the message. The guarantee is process-local retry plus target-Session de-duplication, not cross-process exactly-once delivery. +Lead delivery calls `Agent.steer()` directly. Teammate delivery uses the continuation owner's host-only Steer path, which preserves the Team sender source while authorizing the Lead-to-child edge and cold-resuming inactive targets. Sibling messages never impersonate the Lead through the public adjacent-Agent messaging operation. + ### Shared task board Tasks are complete versioned snapshots; every mutation carries `expectedRevision`, and a stale caller receives `TEAM_TASK_STALE_REVISION` instead of overwriting a newer value. Numeric `task-` ids require a safe-integer suffix, and id-space exhaustion reports `TEAM_TASK_LIMIT` instead of reusing the final id. Deleted tasks remain tombstones for replay and id stability but do not consume `maxTasks` or appear in `listTasks()`. `writeScopes` are normalized workspace-relative prefixes; views warn on overlap with in-progress tasks but never block claim or authorize writes. diff --git a/packages/experimental/agent-team/README.zh.md b/packages/experimental/agent-team/README.zh.md index 0aae14bccc..d6b57d35b6 100644 --- a/packages/experimental/agent-team/README.zh.md +++ b/packages/experimental/agent-team/README.zh.md @@ -68,7 +68,7 @@ roster 显示每个成员的职责(`lead` 或 `teammate`)与当前状态:` 任何成员都可以向任何其他成员或 Lead 发送消息。live 成员会立即收到;离线成员的消息会排队,并在其恢复后到达。消息不会丢失,也绝不会重复投递。 -两种投递模式覆盖两种常见意图:quiet 消息在不让 idle teammate 启动的情况下传达信息(用于可以等待的更新),follow-up 让消息成为接收方的下一个轮次(用于移交工作)。发送方始终能看到结果——已送达,或正在排队。排队的消息已经安全存储,因此绝不能重发。 +每条消息都使用 Steer:running target 在最近的步骤边界收到消息,idle target 启动一个轮次,inactive teammate 则冷恢复。发送方始终能看到结果——target inbox 已接受,或在投递暂时不可用时保留为 queued。排队的消息已经安全存储,因此绝不能重发。 ### 共享任务板 @@ -131,6 +131,8 @@ Lead 可以停止 teammate 的当前轮次,而不会删除其排队的消息 `sendMessage()` 校验 peer 成员关系,追加 `team/message/queued` 并在尝试投递前 flush。目标消息以 `Team message from :` 开头,并在 `TeamMessageSource` 中保留同一 id 与发送者。只有目标 Session 在 pending inbox 或已记录历史中持久持有消息身份后,才会以 `team/message/delivered` 确认投递。即时准入按目标与持久队列顺序串行化;恢复按同一顺序重新投递 queued-minus-delivered 记录。重试前会同时折叠 live 与持久目标 inbox/历史状态,因此 inbox 已接受但模型尚未 claim 时发生崩溃不会复制消息。该保证是进程内重试加 target Session 去重,而不是跨进程 exactly-once 投递。 +投递给 Lead 时直接调用 `Agent.steer()`。投递给 teammate 时使用 continuation owner 的 host-only Steer 路径;该路径会保留 Team 发送者 source,同时授权 Lead-to-child edge 并冷恢复 inactive target。sibling 消息绝不会通过公开的相邻 Agent 消息操作伪装成 Lead。 + ### 共享任务板 任务是完整版本化快照;每次变更都携带 `expectedRevision`,陈旧调用方会收到 `TEAM_TASK_STALE_REVISION`,而不会覆盖更新的值。数字 `task-` id 的后缀必须是安全整数,id 空间耗尽时报告 `TEAM_TASK_LIMIT`,而不是复用最后一个 id。已删除任务作为 tombstone 保留以供回放与维持 id 稳定,但不占用 `maxTasks`,也不出现在 `listTasks()` 中。`writeScopes` 是规范化后的 workspace 相对前缀;视图会对与 in-progress 任务的重叠发出警告,但绝不阻止 claim 或授予写权限。 diff --git a/packages/experimental/agent-team/src/index.ts b/packages/experimental/agent-team/src/index.ts index de0487e93b..6fa0500eeb 100644 --- a/packages/experimental/agent-team/src/index.ts +++ b/packages/experimental/agent-team/src/index.ts @@ -157,7 +157,7 @@ export class TeamService extends TypertRemoteService { /** * Queue one durable peer message, then attempt immediate delivery. * @param caller - exact live sending Team member. - * @param request - target name, content, scheduling mode, and pre-queue cancellation. + * @param request - target name, content, and pre-queue cancellation. * @returns durable message identity and immediate-delivery observation. */ async sendMessage(caller: Agent, request: SendTeamMessageRequest): Promise { diff --git a/packages/experimental/agent-team/src/mailbox.ts b/packages/experimental/agent-team/src/mailbox.ts index 11f969edf8..59d3b5b6e1 100644 --- a/packages/experimental/agent-team/src/mailbox.ts +++ b/packages/experimental/agent-team/src/mailbox.ts @@ -8,7 +8,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' -import { queueHostSubagentPrompt } from '@deepseek-ai/dsh-subagent/internal' +import { steerHostSubagentPrompt } from '@deepseek-ai/dsh-subagent/internal' import { errorMessage, TeamError } from './error.ts' import type { TeamJournal } from './journal.ts' import type { TeamRuntimeLifecycle } from './lifecycle.ts' @@ -49,7 +49,7 @@ export class TeamMailbox { /** * Queue one durable peer message, then attempt immediate delivery. * @param caller - exact live sending Team member. - * @param request - target name, content, scheduling mode, and pre-queue cancellation. + * @param request - target name, content, and pre-queue cancellation. * @returns durable message identity and immediate-delivery observation. */ async send(caller: Agent, request: SendTeamMessageRequest): Promise { @@ -93,8 +93,6 @@ export class TeamMailbox { && (membership.role === 'lead' || message.targetId === agent.id)) for (const message of messages) { signal.throwIfAborted() - if (membership.role === 'lead' && message.delivery === 'quiet' - && message.targetId !== membership.root.id && this.ctx.agents.get(message.targetId) === undefined) continue await this.tryDispatch(membership.root, message, signal) } } @@ -134,7 +132,6 @@ export class TeamMailbox { senderId: caller.id, senderName: membership.name, targetId: target.id, - delivery: request.delivery, content, } if (Buffer.byteLength(JSON.stringify(this.deliveryContent(queued)), 'utf8') > this.maxMessageBytes) { @@ -191,8 +188,7 @@ export class TeamMailbox { ): Promise { const active = this.activeDispatches.get(message.targetId) const live = message.targetId === root.id ? root : this.ctx.agents.get(message.targetId) - if (active !== undefined && live !== undefined && message.delivery === 'quiet' - && this.messagePrecedes(root, message.id, active.id)) { + if (active !== undefined && live !== undefined && this.messagePrecedes(root, message.id, active.id)) { return await this.dispatchOnce(root, message, signal) } return await this.serializeDispatch(message, () => this.dispatchOnce(root, message, signal)) @@ -242,18 +238,9 @@ export class TeamMailbox { const content = this.deliveryContent(message) if (message.targetId === root.id) { const input = createUserMessage({ content, source }) - if (message.delivery === 'wakeup') { - root.followup(input) - return await this.checkpointDelivered(root, root.session, message.id) - } - root.inject(input) + root.steer(input) return await this.checkpointDelivered(root, root.session, message.id) } - if (message.delivery === 'quiet') { - if (target === undefined) return false - target.inject(createUserMessage({ content, source })) - return await this.checkpointDelivered(root, target.session, message.id) - } if (target === undefined) { const recorded = await this.persistedTargetRecorded(message.targetId, message.id, signal) if (recorded === undefined) return false @@ -262,7 +249,7 @@ export class TeamMailbox { return true } } - await queueHostSubagentPrompt(this.ctx.subagents, root, message.targetId, content, source, signal) + await steerHostSubagentPrompt(this.ctx.subagents, root, message.targetId, content, source, signal) return target === undefined ? true : await this.checkpointDelivered(root, target.session, message.id) diff --git a/packages/experimental/agent-team/src/projection.ts b/packages/experimental/agent-team/src/projection.ts index df68fa518c..2d60102197 100644 --- a/packages/experimental/agent-team/src/projection.ts +++ b/packages/experimental/agent-team/src/projection.ts @@ -90,7 +90,6 @@ const teamMessageSnapshotSchema = z.object({ senderId: sessionIdSchema, senderName: z.string(), targetId: sessionIdSchema, - delivery: z.enum(['quiet', 'wakeup']), content: z.array(contentBlockSchema), }).strict() as z.ZodType diff --git a/packages/experimental/agent-team/src/types.ts b/packages/experimental/agent-team/src/types.ts index 8d5b2a8d62..5818a6bc5f 100644 --- a/packages/experimental/agent-team/src/types.ts +++ b/packages/experimental/agent-team/src/types.ts @@ -108,7 +108,6 @@ export interface TeamMessageSnapshot { readonly senderId: SessionId readonly senderName: string readonly targetId: SessionId - readonly delivery: 'quiet' | 'wakeup' readonly content: ContentBlock[] } @@ -160,7 +159,6 @@ export interface SpawnTeammateResult { export interface SendTeamMessageRequest { readonly target: string readonly content: ContentBlock[] - readonly delivery: 'quiet' | 'wakeup' readonly signal: AbortSignal } diff --git a/packages/experimental/agent-team/tests/persistence.spec.ts b/packages/experimental/agent-team/tests/persistence.spec.ts index 9c85709e2e..fbacd0fca6 100644 --- a/packages/experimental/agent-team/tests/persistence.spec.ts +++ b/packages/experimental/agent-team/tests/persistence.spec.ts @@ -209,7 +209,6 @@ for (const backend of backends) { const receipt = await second.ctx.agentTeams.sendMessage(activeHandle.agent, { target: 'recoverable', content: [{ type: 'text', text: 'resume after reconciliation' }], - delivery: 'wakeup', signal: SIGNAL, }) expect(receipt.status).toBe('accepted') @@ -265,7 +264,7 @@ for (const backend of backends) { await second.dispose() }) - it('replays queued-minus-delivered mail in FIFO order without waking for quiet mail', { + it('retries queued mail through cold-resume Steer after restart', { timeout: PERSISTENCE_TEST_TIMEOUT_MS, }, async () => { const storageRoot = mkdtempSync(join(tmpdir(), `dsh-team-mail-${backend.name.toLowerCase()}-`)) @@ -283,14 +282,15 @@ for (const backend of backends) { signal: SIGNAL, }) await vi.waitFor(() => { expect(first.ctx.agents.get(started.member.id)).toBeUndefined() }, { timeout: 5_000 }) - const quiet = await first.ctx.agentTeams.sendMessage(firstLead, { + vi.spyOn(first.ctx.sessionPersistence, 'inspect') + .mockRejectedValueOnce(new Error('temporary target inspection failure')) + const queued = await first.ctx.agentTeams.sendMessage(firstLead, { target: 'mail-worker', - content: [{ type: 'text', text: 'durable quiet context' }], - delivery: 'quiet', + content: [{ type: 'text', text: 'durable retry context' }], signal: SIGNAL, }) - expect(quiet.status).toBe('queued') - expect(durable(firstLead).pendingMessages.map(message => message.id)).toEqual([quiet.messageId]) + expect(queued.status).toBe('queued') + expect(durable(firstLead).pendingMessages.map(message => message.id)).toEqual([queued.messageId]) await first.dispose() const second = await stack(backend, storageRoot, [textResponse('resumed teammate answer')]) @@ -298,19 +298,6 @@ for (const backend of backends) { resumeSessionId: rootId, agentOptions: { provider: 'mock', model: 'mock' }, }) - await vi.waitFor(() => { - expect(durable(rootHandle.agent).pendingMessages.map(message => message.id)) - .toEqual([quiet.messageId]) - }) - expect(second.ctx.agents.get(started.member.id)).toBeUndefined() - - const waking = await second.ctx.agentTeams.sendMessage(rootHandle.agent, { - target: 'mail-worker', - content: [{ type: 'text', text: 'resume after restart' }], - delivery: 'wakeup', - signal: SIGNAL, - }) - expect(waking.status).toBe('accepted') await vi.waitFor(() => { expect(second.ctx.agents.get(started.member.id)).toBeUndefined() }, { timeout: 5_000 }) await vi.waitFor(() => { expect(durable(rootHandle.agent).pendingMessages).toEqual([]) }) @@ -319,7 +306,7 @@ for (const backend of backends) { && event.data.source.kind === 'team-message' ? [event.data.source.messageId] : []) - expect(peerIds).toEqual([quiet.messageId, waking.messageId]) + expect(peerIds).toEqual([queued.messageId]) await rootHandle.dispose() await second.dispose() @@ -373,7 +360,6 @@ for (const backend of backends) { senderId: rootId, senderName: 'lead', targetId: started.member.id, - delivery: 'wakeup', content: [{ type: 'text', text: 'already recorded before acknowledgement' }], } firstLead.session.append('team/message/queued', { @@ -426,7 +412,6 @@ for (const backend of backends) { senderId: rootId, senderName: 'lead', targetId: childId, - delivery: 'wakeup', content: [{ type: 'text', text: 'already durable in target inbox' }], } root.session.append('team/member', { diff --git a/packages/experimental/agent-team/tests/projection-events.spec.ts b/packages/experimental/agent-team/tests/projection-events.spec.ts index 3cd6b6103c..b4d1952050 100644 --- a/packages/experimental/agent-team/tests/projection-events.spec.ts +++ b/packages/experimental/agent-team/tests/projection-events.spec.ts @@ -71,7 +71,6 @@ function message(overrides: Partial = {}): TeamMessageSnaps senderId: ROOT, senderName: 'lead', targetId: CHILD, - delivery: 'quiet', content: [{ type: 'text', text: 'hello' }], ...overrides, } diff --git a/packages/experimental/agent-team/tests/team.spec.ts b/packages/experimental/agent-team/tests/team.spec.ts index 291fd6b59d..3acae897fd 100644 --- a/packages/experimental/agent-team/tests/team.spec.ts +++ b/packages/experimental/agent-team/tests/team.spec.ts @@ -11,7 +11,7 @@ import { SessionId, type Session } from '@deepseek-ai/dsh-session' import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl' import SubagentService from '@deepseek-ai/dsh-subagent' -import { queueSubagentPrompt, type HostPromptQueue } from '@deepseek-ai/dsh-subagent/internal' +import { deliverSubagentPrompt, type HostPromptDeliverer } from '@deepseek-ai/dsh-subagent/internal' import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork-in-process' import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process' import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' @@ -331,7 +331,7 @@ describe('Team identity and provisioning', () => { diagnostics: ['string provider failure'], }) await expect(first.ctx.agentTeams.sendMessage(first.lead, { - target: 'string-failure', content: content('cannot deliver'), delivery: 'quiet', signal: SIGNAL, + target: 'string-failure', content: content('cannot deliver'), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_MEMBER_NOT_FOUND' }) const second = await setup([]) @@ -578,7 +578,7 @@ describe('Team shared task DAG', () => { }) it('enforces CAS, ownership, dependencies, transitions, and write-scope warnings', async () => { - const { ctx, lead } = await setup(['hang', 'hang']) + const { ctx, lead } = await setup(['hang', 'hang', textResponse('beta integrated update')]) const firstMember = await spawn(ctx, lead, 'alpha') const alpha = await waitRunning(ctx, firstMember.member.id) const secondMember = await spawn(ctx, lead, 'beta') @@ -922,15 +922,14 @@ describe('Team Remote API', () => { }) describe('Team mailbox and waiting', () => { - it('injects a quiet message addressed to the Lead and checkpoints its receipt', async () => { - const { ctx, lead } = await setup([]) + it('steers a message addressed to the Lead and checkpoints its receipt', async () => { + const { ctx, lead } = await setup(['hang']) const message: TeamMessageSnapshot = { - id: TeamMessageId('quiet-lead-message'), + id: TeamMessageId('steer-lead-message'), senderId: SessionId('team-worker'), senderName: 'worker', targetId: lead.id, - delivery: 'quiet', - content: content('quiet report'), + content: content('progress report'), } lead.session.append('team/message/queued', { version: 1, @@ -939,12 +938,15 @@ describe('Team mailbox and waiting', () => { }) await expect(teamInternals(ctx).mailbox.tryDispatch(lead, message, SIGNAL)).resolves.toBe(true) - expect(lead.inbox.nextStep.some(input => input.source.kind === 'team-message' - && input.source.messageId === message.id)).toBe(true) + expect(lead.session.snapshotEvents().some(event => event.type === 'agent/inbox/spliced' + && event.data.inserted.some(input => input.source.kind === 'team-message' + && input.source.messageId === message.id))).toBe(true) expect(durable(lead).pendingMessages).toEqual([]) + lead.cancel({ kind: 'parent' }) + await lead.whenIdle() }) - it('acknowledges waking messages persisted by a busy Lead before model claim', async () => { + it('acknowledges steered messages persisted by a busy Lead before model claim', async () => { const { ctx, lead, teamFiber } = await setup(['hang', 'hang'], { maxPendingMessagesPerMember: 1 }) const started = await spawn(ctx, lead, 'lead-reporter') const reporter = await waitRunning(ctx, started.member.id) @@ -952,10 +954,10 @@ describe('Team mailbox and waiting', () => { await waitRunning(ctx, lead.id) const first = await ctx.agentTeams.sendMessage(reporter, { - target: 'lead', content: content('first wakeup report'), delivery: 'wakeup', signal: SIGNAL, + target: 'lead', content: content('first progress report'), signal: SIGNAL, }) const second = await ctx.agentTeams.sendMessage(reporter, { - target: 'lead', content: content('second wakeup report'), delivery: 'wakeup', signal: SIGNAL, + target: 'lead', content: content('second progress report'), signal: SIGNAL, }) expect([first.status, second.status]).toEqual(['accepted', 'accepted']) expect(lead.status).toBe('running') @@ -1000,8 +1002,7 @@ describe('Team mailbox and waiting', () => { const target = await waitRunning(ctx, started.member.id) const immediate = await ctx.agentTeams.sendMessage(lead, { target: 'pending-target', - content: content('live quiet receipt'), - delivery: 'quiet', + content: content('live steer receipt'), signal: SIGNAL, }) expect(immediate.status).toBe('accepted') @@ -1014,7 +1015,6 @@ describe('Team mailbox and waiting', () => { senderId: lead.id, senderName: 'lead', targetId: target.id, - delivery: 'quiet', content: content('durable pending receipt'), } lead.session.append('team/message/queued', { @@ -1082,7 +1082,7 @@ describe('Team mailbox and waiting', () => { await waitNoAgent(ctx, target.id) }) - it('acknowledges waking messages accepted by a busy target inbox', async () => { + it('acknowledges steered messages accepted by a busy target inbox', async () => { const { ctx, lead } = await setup(['hang'], { maxPendingMessagesPerMember: 1 }) const started = await spawn(ctx, lead, 'busy-target') const target = await waitRunning(ctx, started.member.id) @@ -1094,24 +1094,24 @@ describe('Team mailbox and waiting', () => { }) const first = await ctx.agentTeams.sendMessage(lead, { - target: 'busy-target', content: content('first waking message'), delivery: 'wakeup', signal: SIGNAL, + target: 'busy-target', content: content('first steered message'), signal: SIGNAL, }) expect(first.status).toBe('accepted') expect(flushed).toEqual([lead.id, target.id, lead.id]) expect(durable(lead).pendingMessages).toEqual([]) - expect(target.inbox.nextTurn.some(message => message.source.kind === 'team-message' + expect(target.inbox.nextStep.some(message => message.source.kind === 'team-message' && message.source.messageId === first.messageId)).toBe(true) flushed.length = 0 const second = await ctx.agentTeams.sendMessage(lead, { - target: 'busy-target', content: content('second waking message'), delivery: 'wakeup', signal: SIGNAL, + target: 'busy-target', content: content('second steered message'), signal: SIGNAL, }) expect(second.status).toBe('accepted') expect(flushed).toEqual([lead.id, target.id, lead.id]) expect(durable(lead).pendingMessages).toEqual([]) - expect(target.inbox.nextTurn.filter(message => message.source.kind === 'team-message' + expect(target.inbox.nextStep.filter(message => message.source.kind === 'team-message' && (message.source.messageId === first.messageId || message.source.messageId === second.messageId))) .toHaveLength(2) @@ -1120,19 +1120,19 @@ describe('Team mailbox and waiting', () => { await waitNoAgent(ctx, target.id) }) - it('serializes concurrent waking delivery admission for one target', async () => { + it('serializes concurrent Steer delivery admission for one target', async () => { const { ctx, lead } = await setup([textResponse('target initial')]) const target = await spawn(ctx, lead, 'ordered-target') await waitNoAgent(ctx, target.member.id) const entered = Promise.withResolvers() const release = Promise.withResolvers() const admitted: string[] = [] - vi.spyOn(ctx.subagents as unknown as HostPromptQueue, queueSubagentPrompt) + vi.spyOn(ctx.subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) .mockImplementation(async (_parent, _childId, blocks) => { const last = blocks.at(-1) const text = last?.type === 'text' ? last.text : '' admitted.push(text) - if (text === 'first waking') { + if (text === 'first steer') { entered.resolve(undefined) await release.promise } @@ -1140,15 +1140,15 @@ describe('Team mailbox and waiting', () => { }) const first = ctx.agentTeams.sendMessage(lead, { - target: 'ordered-target', content: content('first waking'), delivery: 'wakeup', signal: SIGNAL, + target: 'ordered-target', content: content('first steer'), signal: SIGNAL, }) await entered.promise let secondSettled = false const second = ctx.agentTeams.sendMessage(lead, { - target: 'ordered-target', content: content('second waking'), delivery: 'wakeup', signal: SIGNAL, + target: 'ordered-target', content: content('second steer'), signal: SIGNAL, }).finally(() => { secondSettled = true }) await new Promise((resolve) => { setTimeout(resolve, 0) }) - expect(admitted).toEqual(['first waking']) + expect(admitted).toEqual(['first steer']) expect(secondSettled).toBe(false) release.resolve(undefined) @@ -1156,7 +1156,63 @@ describe('Team mailbox and waiting', () => { { status: 'accepted' }, { status: 'accepted' }, ]) - expect(admitted).toEqual(['first waking', 'second waking']) + expect(admitted).toEqual(['first steer', 'second steer']) + }) + + it('admits an earlier durable message ahead of a later in-flight resume', async () => { + const { ctx, lead } = await setup(['hang']) + const started = await spawn(ctx, lead, 'reordered-target') + const target = await waitRunning(ctx, started.member.id) + const earlier: TeamMessageSnapshot = { + id: TeamMessageId('earlier-message'), + senderId: lead.id, + senderName: 'lead', + targetId: target.id, + content: content('earlier steer'), + } + const later: TeamMessageSnapshot = { + ...earlier, + id: TeamMessageId('later-message'), + content: content('later steer'), + } + for (const message of [earlier, later]) { + lead.session.append('team/message/queued', { + version: 1, + teamId: TeamId(lead.id), + message, + }) + } + + const laterEntered = Promise.withResolvers() + const releaseLater = Promise.withResolvers() + const admitted: string[] = [] + vi.spyOn(ctx.subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) + .mockImplementation(async (_parent, _childId, blocks, source) => { + const last = blocks.at(-1) + const text = last?.type === 'text' ? last.text : '' + if (text === 'later steer') { + laterEntered.resolve(undefined) + await releaseLater.promise + } + const input = createUserMessage({ content: blocks, source }) + target.inject(input) + admitted.push(text) + return input.id + }) + + const laterDispatch = teamInternals(ctx).mailbox.tryDispatch(lead, later, SIGNAL) + await laterEntered.promise + await expect(teamInternals(ctx).mailbox.tryDispatch(lead, earlier, SIGNAL)).resolves.toBe(true) + expect(admitted).toEqual(['earlier steer']) + + releaseLater.resolve(undefined) + await expect(laterDispatch).resolves.toBe(true) + expect(admitted).toEqual(['earlier steer', 'later steer']) + expect(durable(lead).pendingMessages).toEqual([]) + + ctx.agentTeams.interrupt(lead, 'reordered-target') + target.cancel({ kind: 'parent' }) + await waitNoAgent(ctx, target.id) }) it('deduplicates live target history and contains inspection and delivery failures', async () => { @@ -1169,7 +1225,6 @@ describe('Team mailbox and waiting', () => { senderId: lead.id, senderName: 'lead', targetId: live.id, - delivery: 'wakeup', content: content('already in live history'), } lead.session.append('team/message/queued', { @@ -1245,15 +1300,15 @@ describe('Team mailbox and waiting', () => { await waitNoAgent(ctx, inactiveStarted.member.id) const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect').mockRejectedValueOnce(new Error('inspect unavailable')) const uncertain = await ctx.agentTeams.sendMessage(lead, { - target: 'inactive-target', content: content('inspection failure'), delivery: 'wakeup', signal: SIGNAL, + target: 'inactive-target', content: content('inspection failure'), signal: SIGNAL, }) expect(uncertain.status).toBe('queued') inspect.mockRestore() - vi.spyOn(ctx.subagents as unknown as HostPromptQueue, queueSubagentPrompt) + vi.spyOn(ctx.subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) .mockRejectedValueOnce(new Error('delivery unavailable')) const failed = await ctx.agentTeams.sendMessage(lead, { - target: 'inactive-target', content: content('delivery failure'), delivery: 'wakeup', signal: SIGNAL, + target: 'inactive-target', content: content('delivery failure'), signal: SIGNAL, }) expect(failed.status).toBe('queued') expect(warnings.some(warning => warning.includes('inspect unavailable'))).toBe(true) @@ -1263,44 +1318,33 @@ describe('Team mailbox and waiting', () => { await waitNoAgent(ctx, live.id) }) - it('keeps quiet mail dormant, wakes on follow-up, preserves FIFO, and de-duplicates delivery', async () => { - const { ctx, lead } = await setup(['hang', textResponse('beta first'), textResponse('beta resumed')]) + it('cold-resumes an inactive sibling with sender attribution', async () => { + const { ctx, lead } = await setup(['hang', 'hang']) const alphaStarted = await spawn(ctx, lead, 'alpha') const alpha = await waitRunning(ctx, alphaStarted.member.id) const betaStarted = await spawn(ctx, lead, 'beta') - await waitNoAgent(ctx, betaStarted.member.id) + const beta = await waitRunning(ctx, betaStarted.member.id) + ctx.agentTeams.interrupt(lead, 'beta') + await waitNoAgent(ctx, beta.id) - const quiet = await ctx.agentTeams.sendMessage(alpha, { - target: 'beta', content: content('quiet info'), delivery: 'quiet', signal: SIGNAL, + const first = await ctx.agentTeams.sendMessage(alpha, { + target: 'beta', content: content('first update'), signal: SIGNAL, }) - expect(quiet.status).toBe('queued') - expect(ctx.agents.get(betaStarted.member.id)).toBeUndefined() - const waking = await ctx.agentTeams.sendMessage(alpha, { - target: 'beta', content: content('do another turn'), delivery: 'wakeup', signal: SIGNAL, - }) - expect(waking.status).toBe('accepted') + expect(first.status).toBe('accepted') await waitNoAgent(ctx, betaStarted.member.id) - await vi.waitFor(() => { expect(durable(lead).pendingMessages).toEqual([]) }) - const stored = await ctx.sessionPersistence.inspect(betaStarted.member.id) - const peerMessages = stored.events.filter(event => event.type === 'user/message' - && event.data.source.kind === 'team-message') - expect(peerMessages.map((event) => { - if (event.type !== 'user/message') return undefined - const block = event.data.content.at(-1) - return block?.type === 'text' ? block.text : undefined - })).toEqual(['quiet info', 'do another turn']) - expect(peerMessages.map(event => event.type === 'user/message' - ? event.data.content[0]?.type === 'text' && event.data.content[0].text - : undefined)).toEqual([ - expect.stringMatching(/^Team message .* from alpha:$/u), + const peerMessages = stored.events.flatMap(event => event.type === 'user/message' + && event.data.source.kind === 'team-message' ? [event.data] : []) + expect(peerMessages.map(message => message.content.at(-1))).toEqual([ + { type: 'text', text: 'first update' }, + ]) + expect(peerMessages.map(message => message.content[0]?.type === 'text' && message.content[0].text)).toEqual([ expect.stringMatching(/^Team message .* from alpha:$/u), ]) - expect(peerMessages.map(event => event.type === 'user/message' && event.data.source.kind === 'team-message' - ? [event.data.source.messageId, event.data.source.senderName] + expect(peerMessages.map(message => message.source.kind === 'team-message' + ? [message.source.messageId, message.source.senderName] : undefined)).toEqual([ - [quiet.messageId, 'alpha'], - [waking.messageId, 'alpha'], + [first.messageId, 'alpha'], ]) ctx.agentTeams.interrupt(lead, 'alpha') @@ -1315,25 +1359,26 @@ describe('Team mailbox and waiting', () => { const target = await spawn(ctx, lead, 'target') await waitNoAgent(ctx, target.member.id) await expect(ctx.agentTeams.sendMessage(lead, { - target: 'target', content: content('x'.repeat(300)), delivery: 'quiet', signal: SIGNAL, + target: 'target', content: content('x'.repeat(300)), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_MESSAGE_TOO_LARGE' }) + vi.spyOn(ctx.sessionPersistence, 'inspect').mockRejectedValueOnce(new Error('temporary inspection failure')) const queued = await ctx.agentTeams.sendMessage(lead, { - target: 'target', content: content('one'), delivery: 'quiet', signal: SIGNAL, + target: 'target', content: content('one'), signal: SIGNAL, }) expect(queued.status).toBe('queued') await expect(ctx.agentTeams.sendMessage(lead, { - target: 'target', content: content('two'), delivery: 'quiet', signal: SIGNAL, + target: 'target', content: content('two'), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_MAILBOX_FULL' }) await expect(ctx.agentTeams.sendMessage(lead, { - target: 'lead', content: content('self'), delivery: 'quiet', signal: SIGNAL, + target: 'lead', content: content('self'), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_SELF_MESSAGE' }) await expect(ctx.agentTeams.sendMessage(lead, { - target: 'missing', content: content('unknown target'), delivery: 'quiet', signal: SIGNAL, + target: 'missing', content: content('unknown target'), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_MEMBER_NOT_FOUND' }) const controller = new AbortController() controller.abort(new TeamError('cancelled before queue', 'TEST_CANCELLED')) await expect(ctx.agentTeams.sendMessage(lead, { - target: 'target', content: content('cancelled'), delivery: 'quiet', signal: controller.signal, + target: 'target', content: content('cancelled'), signal: controller.signal, })).rejects.toMatchObject({ code: 'TEST_CANCELLED' }) }) @@ -1342,12 +1387,12 @@ describe('Team mailbox and waiting', () => { const started = await spawn(ctx, lead, 'worker') const worker = await waitRunning(ctx, started.member.id) const followup = await ctx.agentTeams.sendMessage(lead, { - target: 'worker', content: content('retained follow-up'), delivery: 'wakeup', signal: SIGNAL, + target: 'worker', content: content('retained follow-up'), signal: SIGNAL, }) expect(followup.status).toBe('accepted') expect(ctx.agentTeams.interrupt(lead, 'worker')).toEqual({ previousStatus: 'running' }) await vi.waitFor(() => { expect(worker.status).toBe('idle') }) - expect(worker.inbox.nextTurn.some(message => message.source.kind === 'team-message' + expect(worker.inbox.nextStep.some(message => message.source.kind === 'team-message' && message.source.messageId === followup.messageId)).toBe(true) worker.cancel({ kind: 'parent' }) await waitNoAgent(ctx, worker.id) @@ -1558,7 +1603,7 @@ describe('Team mailbox and waiting', () => { const entered = Promise.withResolvers() const aborted = Promise.withResolvers() const release = Promise.withResolvers() - vi.spyOn(ctx.subagents as unknown as HostPromptQueue, queueSubagentPrompt) + vi.spyOn(ctx.subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) .mockImplementation(async (_parent, _childId, _content, _source, signal) => { entered.resolve(undefined) return await new Promise((_resolve, reject) => { @@ -1575,7 +1620,6 @@ describe('Team mailbox and waiting', () => { const sending = ctx.agentTeams.sendMessage(lead, { target: 'mailbox-worker', content: content('resume during disposal'), - delivery: 'wakeup', signal: SIGNAL, }) await entered.promise @@ -1600,7 +1644,6 @@ describe('Team mailbox and waiting', () => { senderId: SessionId('sender'), senderName: 'sender', targetId: lead.id, - delivery: 'wakeup', content: content('acknowledge before disposal'), } lead.session.append('team/message/queued', { @@ -1679,14 +1722,13 @@ describe('Team mailbox and waiting', () => { signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_DISPOSED' }) await expect(ctx.agentTeams.sendMessage(lead, { - target: 'nobody', content: content('must reject'), delivery: 'quiet', signal: SIGNAL, + target: 'nobody', content: content('must reject'), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_DISPOSED' }) await expect(internal.mailbox.tryDispatch(lead, { id: TeamMessageId('post-disposal-message'), senderId: lead.id, senderName: 'lead', targetId: lead.id, - delivery: 'quiet', content: content('must not dispatch'), }, SIGNAL)).resolves.toBe(false) }) diff --git a/packages/experimental/tool-agent-team/README.i18n.yaml b/packages/experimental/tool-agent-team/README.i18n.yaml index df245ca2ed..6eea81aad6 100644 --- a/packages/experimental/tool-agent-team/README.i18n.yaml +++ b/packages/experimental/tool-agent-team/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/experimental/tool-agent-team/README.md -README.md: b8474117d429d6f03562479834bb13daad3307b9 -README.zh.md: ca4dd17e0ccafef4112655f80543d539c9a11a4b +README.md: 4f8d589189540c40560c9abd4e4db999c3d18542 +README.zh.md: 15a87f5640e7115d09792f138f1cc36f20d9eab0 diff --git a/packages/experimental/tool-agent-team/README.md b/packages/experimental/tool-agent-team/README.md index b8474117d4..4f8d589189 100644 --- a/packages/experimental/tool-agent-team/README.md +++ b/packages/experimental/tool-agent-team/README.md @@ -1,5 +1,5 @@ --- -description: "Ten tools that let the model create, message, and coordinate teammates, for compositions mounting the experimental Team plugins." +description: "Nine tools that let the model create, message, and coordinate teammates, for compositions mounting the experimental Team plugins." kind: "package-reference" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-experimental-tool-agent-team` gives the model a team toolset on top of the team domain package: create named teammates, send them messages or follow-up work, see who is available, wait for progress, interrupt a stuck teammate, and manage a shared task board — ten tools in total. A short policy section in every member's prompt teaches the model when to form a team (only when you ask for one) and how to coordinate on a shared workspace. Mounting it replaces legacy subagent controls with the same tool names, so a composition that wants both must disable the legacy definitions. It is experimental: excluded from official releases, carries no stability promise, and creates teammates only when you explicitly ask for a team. +`dsh-experimental-tool-agent-team` gives the model a team toolset on top of the team domain package: create named teammates, steer messages to them, see who is available, wait for progress, interrupt a stuck teammate, and manage a shared task board — nine tools in total. A short policy section in every member's prompt teaches the model when to form a team (only when you ask for one) and how to coordinate on a shared workspace. Mounting it replaces legacy subagent controls with the same tool names, so a composition that wants both must disable the legacy definitions. It is experimental: excluded from official releases, carries no stability promise, and creates teammates only when you explicitly ask for a team. ## Table of Contents @@ -25,7 +25,7 @@ English | [中文](README.zh.md) ## Use this package -Add this package on top of `@deepseek-ai/dsh-experimental-agent-team` when the model should run a team through tools. Once mounted, every team member — the Lead and each teammate — gets the same ten tools plus a policy paragraph that states its own role and name. +Add this package on top of `@deepseek-ai/dsh-experimental-agent-team` when the model should run a team through tools. Once mounted, every team member — the Lead and each teammate — gets the same nine tools plus a policy paragraph that states its own role and name. ### When to choose it @@ -54,10 +54,10 @@ Try it by asking the Lead model: "create a teammate named reviewer to check the ### What the model can do -The ten tools group into four capabilities: +The nine tools group into four capabilities: - **Create a teammate** — `spawn_teammate` takes a name, a description, and the initial task; only the Lead can call it. -- **Send messages** — `send_message` delivers information without waking an idle teammate; `followup_task` makes the message the recipient's next turn and wakes it when needed. +- **Send messages** — `send_message` steers a running member at its nearest step boundary, starts an idle member, and cold-resumes an inactive teammate. - **See and wait** — `list_agents` shows the roster with live status; `wait_agent` waits for the next team change; `interrupt_agent` stops a teammate's current turn (Lead only). - **Manage the task board** — `team_task_create`, `team_task_list`, `team_task_get`, and `team_task_update` add, browse, read, and update shared tasks. @@ -91,12 +91,12 @@ The [Agent Teams Agent Note](../../../.agents/notes/implemented/feature/2026-08- | File | Role | |---|---| -| [`src/index.ts`](src/index.ts) | Plugin entry: config, the fixed policy text, and the ten scoped tool registrations | +| [`src/index.ts`](src/index.ts) | Plugin entry: config, the fixed policy text, and the nine scoped tool registrations | | — | No runtime invariant companion is published; the Team service owns durable and authorization relations. | ### Policy and tools -One `team:policy` section on the member scope teaches each member its role and the coordination rules; the fixed text and the ten tool registrations are declared in [`src/index.ts`](src/index.ts). The ten tool schemas appear only in Team member scopes, so non-Team subagents keep the default catalog. Scoped registrations with the same names as the legacy global continuable-subagent controls shadow those globals for team members only. +One `team:policy` section on the member scope teaches each member its role and the coordination rules; the fixed text and the nine tool registrations are declared in [`src/index.ts`](src/index.ts). The nine tool schemas appear only in Team member scopes, so non-Team subagents keep the default catalog. Scoped registrations with the same names as the legacy global continuable-subagent controls shadow those globals for team members only. ### Scoped registration and teardown @@ -125,7 +125,7 @@ Read these pages when the package-level contract is not enough. They move from t #### What the model sees -One stable policy section states the exact Team role/name/id, the explicit-delegation requirement, shared-cwd behavior, filesystem stale-version recovery, Bash/formatter/codegen risk, task and write-scope coordination, quiet versus waking delivery, the no-retry mailbox rule, and the Lead's duty to wait before answering. The ten Team schemas from `spawn_teammate` through `team_task_update` appear only in Team member scopes. +One stable policy section states the exact Team role/name/id, the explicit-delegation requirement, shared-cwd behavior, filesystem stale-version recovery, Bash/formatter/codegen risk, task and write-scope coordination, Steer delivery, the no-retry mailbox rule, and the Lead's duty to wait before answering. The nine Team schemas from `spawn_teammate` through `team_task_update` appear only in Team member scopes. #### Token effect diff --git a/packages/experimental/tool-agent-team/README.zh.md b/packages/experimental/tool-agent-team/README.zh.md index ca4dd17e0c..15a87f5640 100644 --- a/packages/experimental/tool-agent-team/README.zh.md +++ b/packages/experimental/tool-agent-team/README.zh.md @@ -1,5 +1,5 @@ --- -description: "十个让模型创建、发消息与协调 teammate 的工具,供组合实验性 Team 插件的部署方阅读。" +description: "九个让模型创建、发消息与协调 teammate 的工具,供组合实验性 Team 插件的部署方阅读。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-experimental-tool-agent-team` 在团队领域包之上给模型一套团队工具:创建具名 teammate、给它们发消息或后续任务、查看谁在线、等待进展、中断卡住的 teammate,以及管理共享任务板——共十个工具。每个成员的提示词中都有一段简短策略,教模型何时组建团队(只有你要求时)以及如何在共享工作区协作。挂载它会用同名的团队工具取代旧版 subagent 控件,因此想同时使用两者的组合必须禁用旧定义。它是实验性的:不进入正式发布、不承诺稳定性,并且只有你明确要求组建团队时才会创建 teammate。 +`dsh-experimental-tool-agent-team` 在团队领域包之上给模型一套团队工具:创建具名 teammate、向它们 Steer 消息、查看谁在线、等待进展、中断卡住的 teammate,以及管理共享任务板——共九个工具。每个成员的提示词中都有一段简短策略,教模型何时组建团队(只有你要求时)以及如何在共享工作区协作。挂载它会用同名的团队工具取代旧版 subagent 控件,因此想同时使用两者的组合必须禁用旧定义。它是实验性的:不进入正式发布、不承诺稳定性,并且只有你明确要求组建团队时才会创建 teammate。 ## 目录 @@ -25,7 +25,7 @@ kind: "package-reference" ## 使用本包 -当模型应该通过工具运行一支团队时,在 `@deepseek-ai/dsh-experimental-agent-team` 之上挂载本包。挂载后,每个团队成员——Lead 与每个 teammate——都会获得相同的十个工具,外加一段说明自身角色与名字的策略段落。 +当模型应该通过工具运行一支团队时,在 `@deepseek-ai/dsh-experimental-agent-team` 之上挂载本包。挂载后,每个团队成员——Lead 与每个 teammate——都会获得相同的九个工具,外加一段说明自身角色与名字的策略段落。 ### 何时选择 @@ -54,10 +54,10 @@ kind: "package-reference" ### 模型能做什么 -十个工具分为四类能力: +九个工具分为四类能力: - **创建 teammate**——`spawn_teammate` 接收名字、描述与初始任务;只有 Lead 可以调用它。 -- **发送消息**——`send_message` 在不唤醒 idle teammate 的情况下传达信息;`followup_task` 让消息成为接收方的下一个轮次,并在需要时唤醒它。 +- **发送消息**——`send_message` 在最近的步骤边界 Steer running member、启动 idle member,并冷恢复 inactive teammate。 - **查看与等待**——`list_agents` 显示带实时状态的 roster;`wait_agent` 等待下一次团队变化;`interrupt_agent` 停止 teammate 的当前轮次(仅限 Lead)。 - **管理任务板**——`team_task_create`、`team_task_list`、`team_task_get` 与 `team_task_update` 添加、浏览、读取与更新共享任务。 @@ -91,12 +91,12 @@ kind: "package-reference" | 文件 | 职责 | |---|---| -| [`src/index.ts`](src/index.ts) | 插件入口:配置、固定策略文本与十个 scoped 工具注册 | -| — | 不发布运行时不变式伴生入口;委托只能通过 `ctx.agentTeams` 观察。 | +| [`src/index.ts`](src/index.ts) | 插件入口:配置、固定策略文本与九个 scoped 工具注册 | +| — | 不发布运行时不变式伴生入口;Team 服务拥有持久化与授权关系。 | ### 策略与工具 -member scope 上的一个 `team:policy` 段落教每个成员自己的角色与协作规则;固定文本与十个工具注册都声明在 [`src/index.ts`](src/index.ts)。十个工具 schema 只出现在 Team member scope 中,因此非 Team subagent 保持默认目录。与旧全局 continuable-subagent 控件同名的 scoped 注册只会为团队成员覆盖这些全局控件。 +member scope 上的一个 `team:policy` 段落教每个成员自己的角色与协作规则;固定文本与九个工具注册都声明在 [`src/index.ts`](src/index.ts)。九个工具 schema 只出现在 Team member scope 中,因此非 Team subagent 保持默认目录。与旧全局 continuable-subagent 控件同名的 scoped 注册只会为团队成员覆盖这些全局控件。 ### 按作用域注册与拆除 @@ -125,7 +125,7 @@ member scope 上的一个 `team:policy` 段落教每个成员自己的角色与 #### 模型看到什么 -一段稳定策略会说明确切 Team role/name/id、显式 delegation 要求、共享 cwd 行为、文件 stale-version 恢复、Bash/formatter/codegen 风险、task/write-scope 协调、quiet 与 waking 投递区别、mailbox 不重试规则,以及 Lead 必须在回答前等待。`spawn_teammate` 到 `team_task_update` 的十个 Team schema 只出现在 Team member scope。 +一段稳定策略会说明确切 Team role/name/id、显式 delegation 要求、共享 cwd 行为、文件 stale-version 恢复、Bash/formatter/codegen 风险、task/write-scope 协调、Steer 投递、mailbox 不重试规则,以及 Lead 必须在回答前等待。`spawn_teammate` 到 `team_task_update` 的九个 Team schema 只出现在 Team member scope。 #### Token 影响 diff --git a/packages/experimental/tool-agent-team/src/index.ts b/packages/experimental/tool-agent-team/src/index.ts index ee60a1aea1..824c042f23 100644 --- a/packages/experimental/tool-agent-team/src/index.ts +++ b/packages/experimental/tool-agent-team/src/index.ts @@ -34,10 +34,10 @@ The Team Lead and all teammates share the same working directory and filesystem. Prefer read/edit/write for file changes. If a file operation returns FS_STALE_VERSION, read the current file, rebase your intended change onto the new content, and retry. Bash, formatters, code generators, and scripts are not fully protected by the filesystem version guard; coordinate them explicitly and have the Lead review the final diff and run tests. -Use send_message for quiet information that must not start an idle teammate. Use followup_task when the target should run another turn. A delivered peer item starts with its stable message id and sender name. A successful send is already durable even when its result says queued; do not resend it. Shared-task workflow is list, get, claim with the current revision, perform the work, then complete. Task readiness never starts an owner. Before wait_agent, use list_agents and make sure another required member is running or provisioning; use followup_task first when the required member is inactive. wait_agent observes only changes after that call starts, never wakes a member, and returns noProgress immediately when no other member can produce a change. Re-list after wakeup or timeout. The Lead must wait for required teammates before giving the final answer.` +send_message steers a running target at its nearest step boundary, starts an idle target, and cold-resumes an inactive teammate. A delivered peer item starts with its stable message id and sender name. A successful send is already durable even when its result says queued; do not resend it. Shared-task workflow is list, get, claim with the current revision, perform the work, then complete. Task readiness never starts an owner. Before wait_agent, use list_agents and make sure another required member is running or provisioning; use send_message first when the required member is inactive. wait_agent observes only changes after that call starts, never wakes a member, and returns noProgress immediately when no other member can produce a change. Re-list after wakeup or timeout. The Lead must wait for required teammates before giving the final answer.` const ACTIVE_WAIT_STATUSES: ReadonlySet = new Set(['running', 'provisioning']) -const NO_ACTIVE_PEER_MESSAGE = 'No other Team member is running or provisioning. wait_agent cannot make progress or wake inactive teammates. Re-list with list_agents and team_task_list, then use followup_task to wake each required inactive teammate before waiting again.' +const NO_ACTIVE_PEER_MESSAGE = 'No other Team member is running or provisioning. wait_agent cannot make progress or wake inactive teammates. Re-list with list_agents and team_task_list, then use send_message to wake each required inactive teammate before waiting again.' /** * One roster row, matching `TeamMemberView`. The Lead pseudo-row omits the @@ -198,29 +198,22 @@ function install(agent: Agent, ctx: Context, config: Required): () => vo }, }))) - const messageTool = (toolName: 'send_message' | 'followup_task', delivery: 'quiet' | 'wakeup'): void => { - register(scoped.tools.register(defineTool({ - name: toolName, - description: delivery === 'quiet' - ? 'Send durable information to another Team member without starting an idle member.' - : 'Send a durable follow-up task to another Team member and start a turn when needed.', - parameters: { - target: { type: 'string', required: true, description: 'Team member name, or lead.' }, - message: { type: 'string', required: true, description: 'Self-contained message for the target.' }, - }, - output: jsonOutput(SEND_VALUE_SCHEMA), - execute(args, exec) { - return ctx.agentTeams.sendMessage(callingAgent(exec.agent, toolName), { - target: args.target, - content: [{ type: 'text', text: args.message }], - delivery, - signal: exec.signal, - }) - }, - }))) - } - messageTool('send_message', 'quiet') - messageTool('followup_task', 'wakeup') + register(scoped.tools.register(defineTool({ + name: 'send_message', + description: 'Send one durable message to another Team member. A running target receives it at the nearest step boundary; an idle target starts a turn; an inactive teammate cold-resumes.', + parameters: { + target: { type: 'string', required: true, description: 'Team member name, or lead.' }, + message: { type: 'string', required: true, description: 'Self-contained message for the target.' }, + }, + output: jsonOutput(SEND_VALUE_SCHEMA), + execute(args, exec) { + return ctx.agentTeams.sendMessage(callingAgent(exec.agent, 'send_message'), { + target: args.target, + content: [{ type: 'text', text: args.message }], + signal: exec.signal, + }) + }, + }))) register(scoped.tools.register(defineTool({ name: 'list_agents', diff --git a/packages/experimental/tool-agent-team/tests/tool-team.spec.ts b/packages/experimental/tool-agent-team/tests/tool-team.spec.ts index 353586a37f..199a635b7a 100644 --- a/packages/experimental/tool-agent-team/tests/tool-team.spec.ts +++ b/packages/experimental/tool-agent-team/tests/tool-team.spec.ts @@ -26,7 +26,6 @@ const SIGNAL = new AbortController().signal const TOOL_NAMES = [ 'spawn_teammate', 'send_message', - 'followup_task', 'list_agents', 'wait_agent', 'interrupt_agent', @@ -179,7 +178,7 @@ describe('dsh-tool-team', () => { timedOut: false, noProgress: { reason: 'no-active-peer', - message: 'No other Team member is running or provisioning. wait_agent cannot make progress or wake inactive teammates. Re-list with list_agents and team_task_list, then use followup_task to wake each required inactive teammate before waiting again.', + message: 'No other Team member is running or provisioning. wait_agent cannot make progress or wake inactive teammates. Re-list with list_agents and team_task_list, then use send_message to wake each required inactive teammate before waiting again.', }, }) for (const timeout_ms of [9_999, 3_600_001, Number.MAX_SAFE_INTEGER + 1]) { @@ -221,12 +220,12 @@ describe('dsh-tool-team', () => { // Every Team result reaches the model as compact JSON: indentation would // spend tokens on every roster, task, and receipt without adding meaning. expect(text(roster)).toBe(JSON.stringify(JSON.parse(text(roster)))) - const peer = await execute(ctx, child, 'send_message', { target: 'lead', message: 'quiet report' }) + const peer = await execute(ctx, child, 'send_message', { target: 'lead', message: 'progress report' }) expect(peer.isError).toBe(false) expect(JSON.parse(text(peer))).toMatchObject({ status: 'accepted' }) - const waking = await execute(ctx, child, 'followup_task', { target: 'lead', message: 'review the report' }) - expect(waking.isError).toBe(false) - expect(JSON.parse(text(waking))).toMatchObject({ status: 'accepted' }) + const followup = await execute(ctx, child, 'send_message', { target: 'lead', message: 'review the report' }) + expect(followup.isError).toBe(false) + expect(JSON.parse(text(followup))).toMatchObject({ status: 'accepted' }) await lead.whenIdle() const created = await execute(ctx, lead, 'team_task_create', { @@ -425,7 +424,6 @@ describe('dsh-tool-team', () => { await ctx.agentTeams.sendMessage(lead, { target: 'cold-worker', content: [{ type: 'text', text: 'resume with Team scope' }], - delivery: 'wakeup', signal: SIGNAL, }) const resumed = await waitRunning(ctx, childId) diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 7c6091b1e4..0716f61e2d 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -370,7 +370,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ { signature: 'async sendMessage(caller: Agent, request: SendTeamMessageRequest): Promise', description: 'Queue one durable peer message, then attempt immediate delivery.', - parameters: [{ name: 'caller', description: 'exact live sending Team member.' }, { name: 'request', description: 'target name, content, scheduling mode, and pre-queue cancellation.' }], + parameters: [{ name: 'caller', description: 'exact live sending Team member.' }, { name: 'request', description: 'target name, content, and pre-queue cancellation.' }], returns: 'durable message identity and immediate-delivery observation.', }, { @@ -4780,7 +4780,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SendTeamMessageRequest', - declaration: 'export interface SendTeamMessageRequest {\n readonly target: string;\n readonly content: ContentBlock[];\n readonly delivery: \'quiet\' | \'wakeup\';\n readonly signal: AbortSignal;\n}', + declaration: 'export interface SendTeamMessageRequest {\n readonly target: string;\n readonly content: ContentBlock[];\n readonly signal: AbortSignal;\n}', }, { name: 'SendTeamMessageResult', diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml index 0d24bbc1ef..d01088076b 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: 257a76a4ef84583d3337f697bc8024d72219c4d6 -README.zh.md: 135086b982df38089cdef0acf85535d35354a9d7 +README.md: 6712af94000d82878d8f7cea6194eeb0d2f92421 +README.zh.md: ee0cc8861c174939cc767ba6791c1c19c1d2bc8c diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md index 257a76a4ef..6712af9400 100644 --- a/packages/subagent/subagent/README.md +++ b/packages/subagent/subagent/README.md @@ -77,7 +77,7 @@ This section explains how the service is built and where the observable behavior |---|---| | [`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 adapter for browser and Team message protocols | +| [`src/internal.ts`](src/internal.ts) | Host-only Queue and Steer adapters for browser and Team message protocols | | [`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 | diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md index 135086b982..ee0cc8861c 100644 --- a/packages/subagent/subagent/README.zh.md +++ b/packages/subagent/subagent/README.zh.md @@ -77,7 +77,7 @@ 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 适配器 | +| [`src/internal.ts`](src/internal.ts) | 供浏览器与 Team 消息协议使用的 host-only Queue 与 Steer 适配器 | | [`src/types.ts`](src/types.ts) | 公开的请求、结果与提供方约定 | | [`src/descriptor.ts`](src/descriptor.ts) | 版本化的 `subagent/descriptor` 会话事件词汇 | | [`src/child-agent.ts`](src/child-agent.ts) | 子级组装、委派策略、深度辅助函数 | diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts index 0ccf961407..08c55fbf63 100644 --- a/packages/subagent/subagent/src/continuation.ts +++ b/packages/subagent/subagent/src/continuation.ts @@ -133,7 +133,7 @@ export interface SubagentSendMessageOptions { /** Inputs shared by model steering and the human Queue adapter. */ type ChildDeliveryOptions = - | { readonly delivery: 'steer'; readonly signal: AbortSignal } + | { readonly delivery: 'steer'; readonly source?: MessageSource; readonly signal: AbortSignal } | { readonly delivery: 'queue'; readonly source: MessageSource; readonly signal: AbortSignal } /** @@ -567,6 +567,25 @@ export class SubagentContinuationManager { return this.deliverToChild(parent, childId, content, { source, signal, delivery: 'queue' }) } + /** + * 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 signal - caller cancellation before inbox acceptance. + * @returns the accepted message's inbox id. + */ + async steerPrompt( + parent: Agent, + childId: SessionId, + content: ContentBlock[], + source: MessageSource, + signal: AbortSignal, + ): Promise { + return this.deliverToChild(parent, childId, content, { source, signal, delivery: 'steer' }) + } + /** Route one parent-originated delivery through residency and cold resume. */ private async deliverToChild( parent: Agent, @@ -1262,7 +1281,7 @@ export class SubagentContinuationManager { // 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.delivery === 'steer' + const message = options.source === undefined ? agentMessage(parent, content) : createUserMessage({ content, source: options.source }) const accepted = this.admitWaking(activation, message.id, () => { diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts index 28e50930cd..8eb29021ad 100644 --- a/packages/subagent/subagent/src/index.ts +++ b/packages/subagent/subagent/src/index.ts @@ -75,7 +75,7 @@ import { listChildren as listSubagentChildren, listDescendants as listSubagentDe import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts' import { snapshotSubagentDescriptor } from './descriptor.ts' import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts' -import { queueSubagentPrompt } from './internal.ts' +import { deliverSubagentPrompt, type HostPromptDeliveryMode } from './internal.ts' export * from './out-of-process.ts' export { AssistantOutputFold, finalAssistantOutput } from './assistant-output.ts' @@ -255,7 +255,7 @@ export class SubagentRuntime extends TypertRemoteService { } /** - * Queue one host-protocol message as a distinct direct-child turn. + * Deliver one host-protocol message to a direct continuable child. * Symbol-keyed so host adapters can preserve their own provenance without * widening the public Service Definition or impersonating an Agent sender. * @param parent - exact live direct parent authorizing delivery. @@ -263,16 +263,20 @@ export class SubagentRuntime extends TypertRemoteService { * @param content - host-authored content to deliver. * @param source - durable host-protocol provenance. * @param signal - caller cancellation before inbox acceptance. + * @param delivery - Queue as a distinct turn or Steer at the nearest step. * @returns the accepted message's inbox id. */ - private [queueSubagentPrompt]( + private [deliverSubagentPrompt]( parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal, + delivery: HostPromptDeliveryMode, ): Promise { - return this.requireContinuations().queuePrompt(parent, childId, content, source, signal) + return delivery === 'steer' + ? this.requireContinuations().steerPrompt(parent, childId, content, source, signal) + : this.requireContinuations().queuePrompt(parent, childId, content, source, signal) } /** @@ -445,12 +449,13 @@ export class SubagentRuntime extends TypertRemoteService { content = await admitPromptContent(attachments, request.content) } return { - messageId: await this[queueSubagentPrompt]( + messageId: await this[deliverSubagentPrompt]( parent, childSessionId, content, source, signal, + 'queue', ), } } catch (error: unknown) { diff --git a/packages/subagent/subagent/src/internal.ts b/packages/subagent/subagent/src/internal.ts index 47a3bda127..51bca12607 100644 --- a/packages/subagent/subagent/src/internal.ts +++ b/packages/subagent/subagent/src/internal.ts @@ -34,20 +34,24 @@ export function isAdjacentAgentSendMessageTool(definition: ToolDefinition | unde } /** - * Process-stable symbol-keyed Queue delivery shared by the bundled runtime + * Process-stable symbol-keyed host delivery shared by the bundled runtime * entry and this unbundled internal subpath. * @internal */ -export const queueSubagentPrompt = Symbol.for('dsh.subagent.queuePrompt') +export const deliverSubagentPrompt = Symbol.for('dsh.subagent.deliverPrompt') -/** Runtime face required by the host-only Queue adapter. */ -export interface HostPromptQueue { - [queueSubagentPrompt]( +/** 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]( parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal, + delivery: HostPromptDeliveryMode, ): Promise } @@ -69,11 +73,40 @@ export function queueHostSubagentPrompt( source: MessageSource, signal: AbortSignal, ): Promise { - return (runtime as unknown as HostPromptQueue)[queueSubagentPrompt]( + return (runtime as unknown as HostPromptDeliverer)[deliverSubagentPrompt]( parent, childId, content, source, signal, + 'queue', + ) +} + +/** + * Steer one host-protocol message without exposing another Service operation. + * @param runtime - subagent runtime owning continuation residency. + * @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 signal - caller cancellation before inbox acceptance. + * @returns the accepted message's inbox id. + */ +export function steerHostSubagentPrompt( + runtime: SubagentRuntime, + parent: Agent, + childId: SessionId, + content: ContentBlock[], + source: MessageSource, + signal: AbortSignal, +): Promise { + return (runtime as unknown as HostPromptDeliverer)[deliverSubagentPrompt]( + parent, + childId, + content, + source, + signal, + 'steer', ) } diff --git a/packages/subagent/subagent/tests/control.spec.ts b/packages/subagent/subagent/tests/control.spec.ts index 1acfb9a3bd..733564032b 100644 --- a/packages/subagent/subagent/tests/control.spec.ts +++ b/packages/subagent/subagent/tests/control.spec.ts @@ -13,7 +13,7 @@ import SubagentRuntime, { type SubagentListEntry, type SubagentPromptRequestId, } from '@deepseek-ai/dsh-subagent' -import { queueSubagentPrompt, type HostPromptQueue } from '@deepseek-ai/dsh-subagent/internal' +import { deliverSubagentPrompt, type HostPromptDeliverer } from '@deepseek-ai/dsh-subagent/internal' const PARENT = SessionId('parent') const CHILD = SessionId('child') @@ -36,7 +36,7 @@ async function bench(live?: Record) { /** Spy on the private human-Queue adapter without widening the public service. */ function promptDelivery(subagents: SubagentRuntime) { - return vi.spyOn(subagents as unknown as HostPromptQueue, queueSubagentPrompt) + return vi.spyOn(subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) } function childRow(id: SessionId, activity: 'running' | 'inactive'): SubagentListEntry { @@ -254,6 +254,7 @@ describe('subagent prompt Remote', () => { [{ type: 'text', text: 'continue' }], { kind: 'user', rpcId: REQUEST_ID, clientTimeZone: 'Asia/Shanghai' }, signal, + 'queue', ) }) diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 0f3cdc5d38..972eadc1b8 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -543,7 +543,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ }, scope: ctx => catalogChildScopes.get(ctx) as Agent, note: - 'All ten tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names.', + 'All nine tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names.', }, { pkg: '@deepseek-ai/dsh-tool-todo', From 1149d47e9a06f002b081801fc52d782cb6398ea9 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Sun, 30 Aug 2026 20:51:43 +0800 Subject: [PATCH 2/8] test(tools): update team catalog expectation --- packages/core/tools/tests/gen-tool-catalog.spec.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index 66e1929039..0630cfaa8e 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -28,7 +28,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { expect(names).toEqual([ 'ask_user_question', 'bash', 'bash', 'cordis_define', 'cordis_inspect_list', 'cordis_inspect_query', 'cordis_inspect_self', 'cordis_run', 'cordis_stop', - 'cordis_undefine', 'create_goal', 'edit', 'exit_plan_mode', 'followup_task', 'get_goal', 'glob', 'grep', + 'cordis_undefine', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'interrupt_agent', 'interrupt_agent', 'job_kill', 'job_list', 'job_output', 'list_agents', 'list_agents', 'list_subagent_models', 'lsp', 'pwsh', 'pwsh', 'ralph', 'read', 'read_image', 'run_code', 'schedule_create', 'schedule_delete', From 070b46e1ef2b5b43f04f4b1bdf79d4dc52a2cde3 Mon Sep 17 00:00:00 2001 From: Turtle Date: Wed, 2 Sep 2026 15:06:25 +0800 Subject: [PATCH 3/8] fix(issue-management): restore Project date fields --- .github/issue-management/config.json | 2 +- .github/issue-management/policy.mjs | 39 ++++++++--------- .github/issue-management/policy.test.mjs | 55 +++++++++++------------- 3 files changed, 43 insertions(+), 53 deletions(-) diff --git a/.github/issue-management/config.json b/.github/issue-management/config.json index 85fd4086bd..a935fb5ef8 100644 --- a/.github/issue-management/config.json +++ b/.github/issue-management/config.json @@ -5,7 +5,7 @@ "projectTitle": "DSH Issue Management", "lifecycleActor": "dsh-issue-management", "priorityField": "Priority", - "startDateField": "Start date", + "startDateField": "Start Date", "projectTimeZone": "Asia/Shanghai", "allowUnassignedOwner": true, "statuses": [ diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs index 8b4cde7aab..ef5583894f 100644 --- a/.github/issue-management/policy.mjs +++ b/.github/issue-management/policy.mjs @@ -484,13 +484,7 @@ async function projectContext(number, includeStatusActor = false, includeStartDa title fields(first: 50) { nodes { - ... on ProjectV2Field { - id - name - dataType - isIssueField - issueField { ... on IssueFieldDate { id } } - } + ... on ProjectV2Field { id name dataType isIssueField } ... on ProjectV2SingleSelectField { id name dataType options { id name } } } } @@ -518,9 +512,7 @@ async function projectContext(number, includeStatusActor = false, includeStartDa } startDateValue: fieldValueByName(name: $startDateField) @include(if: $includeStartDate) { - ... on ProjectV2ItemIssueFieldValue { - issueFieldValue { ... on IssueFieldDateValue { value } } - } + ... on ProjectV2ItemFieldDateValue { date } } } } @@ -552,8 +544,8 @@ async function projectContext(number, includeStatusActor = false, includeStartDa if (startDateField && startDateField.dataType !== 'DATE') { throw new Error(`Project ${config.startDateField} 字段必须为 Date`) } - if (startDateField && (!startDateField.isIssueField || !startDateField.issueField?.id)) { - throw new Error(`Project ${config.startDateField} 字段必须为 Issue Date 字段`) + if (startDateField?.isIssueField) { + throw new Error(`Project ${config.startDateField} 字段必须为 Project Date 字段`) } const item = issue.projectItems.nodes.find((candidate) => candidate.project.id === project.id) const latestStatusEvent = issue.timelineItems?.nodes @@ -593,24 +585,27 @@ async function ensureProjectItem(number, includeStartDate = false) { } /** - * Initialize one Issue's organization Start date when it is empty. + * Initialize one Issue's Project Start Date when it is empty. * @param {number} number Same-repository Issue number. * @param {string} date Date in YYYY-MM-DD form. - * @returns {Promise} Resolves after the conditional Issue-field update. + * @returns {Promise} Resolves after the conditional Project update. */ export async function initializeIssueStartDate(number, date) { const context = await ensureProjectItem(number, true) - if (context.item.startDateValue?.issueFieldValue?.value) return + if (context.item.startDateValue?.date) return await graphql( - `mutation($issueId: ID!, $fieldId: ID!, $date: String!) { - updateIssueFieldValue(input: { - issueId: $issueId, - issueField: {fieldId: $fieldId, dateValue: $date} - }) { issue { id } } + `mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $date: Date!) { + updateProjectV2ItemFieldValue(input: { + projectId: $projectId, + itemId: $itemId, + fieldId: $fieldId, + value: {date: $date} + }) { projectV2Item { id } } }`, { - issueId: context.issue.id, - fieldId: context.startDateField.issueField.id, + projectId: context.project.id, + itemId: context.item.id, + fieldId: context.startDateField.id, date, }, ) diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs index 3fc1071ada..252654ce57 100644 --- a/.github/issue-management/policy.test.mjs +++ b/.github/issue-management/policy.test.mjs @@ -21,8 +21,7 @@ const projectGraphqlData = ({ startDate = null, startDateField = true, startDateType = 'DATE', - startDateIsIssueField = true, - startDateIssueField = true, + startDateIsIssueField = false, } = {}) => ({ organization: { projectV2: { @@ -34,11 +33,10 @@ const projectGraphqlData = ({ ...(startDateField ? [ { - id: 'start-date-project-field-id', - name: 'Start date', + id: 'start-date-field-id', + name: 'Start Date', dataType: startDateType, isIssueField: startDateIsIssueField, - issueField: startDateIssueField ? { id: 'start-date-issue-field-id' } : null, }, ] : []), @@ -56,8 +54,7 @@ const projectGraphqlData = ({ id: 'item-id', project: { id: 'project-id' }, fieldValueByName: { name: 'Inbox', optionId: 'inbox-option-id' }, - startDateValue: - startDate === null ? null : { issueFieldValue: { value: startDate } }, + startDateValue: startDate === null ? null : { date: startDate }, }, ] : [], @@ -269,27 +266,29 @@ test('initializes every referenced Issue only for a PR opened event', async () = assert.equal(writes.length, 3) }) -test('writes an empty Issue Start date with the configured field', async (t) => { +test('writes an empty Project Start Date with the configured field', async (t) => { const requests = mockGraphql(t, (request) => { if (request.query.includes('query(')) return projectGraphqlData() - return { updateIssueFieldValue: { issue: { id: 'issue-id' } } } + return { updateProjectV2ItemFieldValue: { projectV2Item: { id: 'item-id' } } } }) await initializeIssueStartDate(42, '2026-08-28') assert.equal(requests.length, 2) assert.match(requests[0].query, /isIssueField/) - assert.match(requests[0].query, /ProjectV2ItemIssueFieldValue/) - assert.match(requests[1].query, /updateIssueFieldValue/) - assert.match(requests[1].query, /issueField: \{fieldId: \$fieldId, dateValue: \$date\}/) + assert.doesNotMatch(requests[0].query, /issueField\s*\{/) + assert.match(requests[0].query, /ProjectV2ItemFieldDateValue/) + assert.match(requests[1].query, /updateProjectV2ItemFieldValue/) + assert.match(requests[1].query, /value: \{date: \$date\}/) assert.deepEqual(requests[1].variables, { - issueId: 'issue-id', - fieldId: 'start-date-issue-field-id', + projectId: 'project-id', + itemId: 'item-id', + fieldId: 'start-date-field-id', date: '2026-08-28', }) }) -test('preserves an existing Issue Start date', async (t) => { +test('preserves an existing Project Start Date', async (t) => { const requests = mockGraphql(t, () => projectGraphqlData({ startDate: '2026-08-01' })) await initializeIssueStartDate(42, '2026-08-28') @@ -297,13 +296,13 @@ test('preserves an existing Issue Start date', async (t) => { assert.equal(requests.length, 1) }) -test('adds a referenced Issue to the Project before setting Start date', async (t) => { +test('adds a referenced Issue to the Project before setting Start Date', async (t) => { const requests = mockGraphql(t, (request) => { if (request.query.includes('query(')) return projectGraphqlData({ projectItem: false }) if (request.query.includes('addProjectV2ItemById')) { return { addProjectV2ItemById: { item: { id: 'new-item-id' } } } } - return { updateIssueFieldValue: { issue: { id: 'issue-id' } } } + return { updateProjectV2ItemFieldValue: { projectV2Item: { id: 'new-item-id' } } } }) await initializeIssueStartDate(42, '2026-08-28') @@ -311,30 +310,26 @@ test('adds a referenced Issue to the Project before setting Start date', async ( assert.equal(requests.length, 3) assert.deepEqual(requests[1].variables, { projectId: 'project-id', contentId: 'issue-id' }) assert.deepEqual(requests[2].variables, { - issueId: 'issue-id', - fieldId: 'start-date-issue-field-id', + projectId: 'project-id', + itemId: 'new-item-id', + fieldId: 'start-date-field-id', date: '2026-08-28', }) }) -test('rejects a missing, non-Date, or Project-local Start date field', async (t) => { +test('rejects a missing, non-Date, or Issue-level Start Date field', async (t) => { let response = projectGraphqlData({ startDateField: false }) const requests = mockGraphql(t, () => response) - await assert.rejects(initializeIssueStartDate(42, '2026-08-28'), /Project 缺少 Start date 字段/) + await assert.rejects(initializeIssueStartDate(42, '2026-08-28'), /Project 缺少 Start Date 字段/) response = projectGraphqlData({ startDateType: 'TEXT' }) - await assert.rejects(initializeIssueStartDate(42, '2026-08-28'), /Start date 字段必须为 Date/) - response = projectGraphqlData({ startDateIsIssueField: false }) + await assert.rejects(initializeIssueStartDate(42, '2026-08-28'), /Start Date 字段必须为 Date/) + response = projectGraphqlData({ startDateIsIssueField: true }) await assert.rejects( initializeIssueStartDate(42, '2026-08-28'), - /Start date 字段必须为 Issue Date 字段/, + /Start Date 字段必须为 Project Date 字段/, ) - response = projectGraphqlData({ startDateIssueField: false }) - await assert.rejects( - initializeIssueStartDate(42, '2026-08-28'), - /Start date 字段必须为 Issue Date 字段/, - ) - assert.equal(requests.length, 4) + assert.equal(requests.length, 3) }) test('does not treat pull request references as Issue associations', () => { From fcd109d29a4a7d298b1f2eeda2463c20b1cc09ac Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:07:58 +0800 Subject: [PATCH 4/8] feat(storage): version read compatibility and backup-and-skip salvage for per-record units MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A DomainSpec may declare compatibleVersions: older domain versions whose stored records the current record schemas still accept. The json backend's per-record reads admit documents stamped with a declared version (writes always stamp the current one), and the legacy whole-unit bootstrap migrates only a file whose stored version is in the accepted set — previously it migrated any version and stamped the records current, turning a discardable stale cache into invalid-record failures that refused the whole domain at open and permanently poisoned the new tree on first boot. A DomainSpec may also declare invalidRecords: 'backup-and-skip' for domains whose records are disposable derived data: a stored record failing its zod schema is moved aside through the new optional KvUnit.backupRecord (.json.bak. under the json backend), logged with its cause, and skipped, instead of rejecting the open. The default stays fail-loud, and so do backends without backupRecord. --- packages/storage/storage-domain/src/index.ts | 23 +++++- packages/storage/storage-domain/src/spec.ts | 34 ++++++++ .../storage-domain/tests/domain.spec.ts | 41 ++++++++++ packages/storage/storage-json/src/format.ts | 18 +++-- .../storage-json/src/per-record-unit.ts | 75 +++++++++++++----- .../storage-json/tests/json-backend.spec.ts | 78 ++++++++++++++++++- packages/storage/storage/src/backend.ts | 23 ++++++ 7 files changed, 259 insertions(+), 33 deletions(-) diff --git a/packages/storage/storage-domain/src/index.ts b/packages/storage/storage-domain/src/index.ts index d2c16a3d69..7e0be5e151 100644 --- a/packages/storage/storage-domain/src/index.ts +++ b/packages/storage/storage-domain/src/index.ts @@ -88,7 +88,10 @@ export class DomainFacility { * (`facet-unsupported`); open the unit projected from the spec (backend * `version-mismatch`/`malformed-medium` pass through); load and validate * every stored record against the spec's zod schemas (`invalid-record` - * with the offending table and key); construct the domain. + * with the offending table and key — unless the spec declares + * `invalidRecords: 'backup-and-skip'` and the unit can move documents aside, in + * which case the failing record is backed up, logged, and skipped); + * construct the domain. * * Lifecycle: the CALLER owns the returned handle and closes it via * `Domain.close()` (typically as its own `ctx.effect` disposer) — the @@ -118,7 +121,23 @@ export class DomainFacility { for (const [table, tableSpec] of Object.entries(spec.tables)) { const records = new Map() for (const [key, raw] of Object.entries(snapshot.tables[table] ?? {})) { - records.set(key, parseRecord(spec.name, table, key, () => tableSpec.valueSchema.parse(raw))) + let parsed: unknown + try { + parsed = parseRecord(spec.name, table, key, () => tableSpec.valueSchema.parse(raw)) + } catch (error) { + // Backup-and-skip policy (disposable derived data): move the record's + // document aside, log the concrete failure, and open without the + // record. Backends that cannot move a document keep the loud path. + if (spec.invalidRecords !== 'backup-and-skip' || unit.backupRecord === undefined) throw error + const moved = await unit.backupRecord(table, key) + // parseRecord always wraps the zod failure as the cause. + this.ctx.logger.error( + `domain '${spec.name}': stored record '${key}' in table '${table}' failed schema validation; ` + + `moved to '${moved}' and treated as absent. Cause: ${String((error as DomainError).cause)}`, + ) + continue + } + records.set(key, parsed) } tables.set(table, records) } diff --git a/packages/storage/storage-domain/src/spec.ts b/packages/storage/storage-domain/src/spec.ts index 74348918aa..f9267bcba5 100644 --- a/packages/storage/storage-domain/src/spec.ts +++ b/packages/storage/storage-domain/src/spec.ts @@ -45,6 +45,26 @@ export interface DomainSpec { * (a stale record document is discarded, never migrated). */ readonly layout?: 'single' | 'per-record' + /** + * Older domain versions whose stored records the current record schemas + * also accept (the declaring owner vouches for that, typically by + * declaring the fields older records lack as optional). `per-record` backends + * read documents stamped with a listed version instead of discarding them, + * and accept a legacy whole-unit file so stamped for the one-time + * bootstrap; writes always stamp {@link version}. + */ + readonly compatibleVersions?: readonly number[] + /** + * What `open` does with a stored table record that fails its zod schema. + * Absent (the default), the whole open rejects with `invalid-record` — + * right for authoritative data. `'backup-and-skip'` is for domains whose + * records are disposable derived data: the backend moves the record's + * document aside (`KvUnit.backupRecord`), the failure is logged with + * its cause, and the open continues with the record absent. A backend + * without `backupRecord` (no per-record document to move) falls back + * to the rejecting default. The global slot always rejects. + */ + readonly invalidRecords?: 'backup-and-skip' /** Optional global singleton slot. */ readonly global?: DomainGlobalSpec /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */ @@ -91,6 +111,13 @@ export function defineDomain(spec: S): S { if (!Number.isInteger(spec.version) || spec.version < 0) { throw new Error(`domain '${spec.name}' version must be a non-negative integer, got ${spec.version}`) } + for (const compat of spec.compatibleVersions ?? []) { + if (!Number.isInteger(compat) || compat < 0 || compat >= spec.version) { + throw new Error( + `domain '${spec.name}' compatibleVersions entries must be non-negative integers below version ${spec.version}, got ${compat}`, + ) + } + } if (spec.layout !== undefined) { // Runtime boundary: the union type is compile-time only — a spec built // from config could carry any value, and a bad one must fail loud here. @@ -99,6 +126,12 @@ export function defineDomain(spec: S): S { throw new Error(`domain '${spec.name}' layout must be 'single' or 'per-record', got ${layout}`) } } + if (spec.invalidRecords !== undefined) { + const policy: string = spec.invalidRecords + if (policy !== 'backup-and-skip') { + throw new Error(`domain '${spec.name}' invalidRecords must be 'backup-and-skip' when present, got ${policy}`) + } + } for (const table of Object.keys(spec.tables)) { if (!UNIT_NAME_RE.test(table)) { throw new Error(`domain '${spec.name}' table name '${table}' must match ${UNIT_NAME_RE}`) @@ -125,5 +158,6 @@ export function descriptorOf(spec: DomainSpec): KvUnitDescriptor { tables: Object.keys(spec.tables), hasGlobal: spec.global !== undefined, ...spec.layout === undefined ? {} : { layout: spec.layout }, + ...spec.compatibleVersions === undefined ? {} : { compatibleVersions: spec.compatibleVersions }, } } diff --git a/packages/storage/storage-domain/tests/domain.spec.ts b/packages/storage/storage-domain/tests/domain.spec.ts index 3b3c8fa679..b21ec0faf8 100644 --- a/packages/storage/storage-domain/tests/domain.spec.ts +++ b/packages/storage/storage-domain/tests/domain.spec.ts @@ -58,6 +58,25 @@ describe('defineDomain', () => { })).toThrow(/must not accept null/) }) + it('validates compatibleVersions entries and projects them onto the descriptor', () => { + expect(() => defineDomain({ name: 'ok', version: 2, compatibleVersions: [1.5], tables: {} })) + .toThrow(/compatibleVersions/) + expect(() => defineDomain({ name: 'ok', version: 2, compatibleVersions: [2], tables: {} })) + .toThrow(/below version/) + expect(() => defineDomain({ name: 'ok', version: 2, compatibleVersions: [-1], tables: {} })) + .toThrow(/compatibleVersions/) + expect(descriptorOf(defineDomain({ name: 'ok', version: 2, compatibleVersions: [0, 1], tables: {} }))) + .toMatchObject({ compatibleVersions: [0, 1] }) + // An undeclared set is absent from the descriptor. + expect(descriptorOf(spec)).not.toHaveProperty('compatibleVersions') + }) + + it('rejects an unknown invalidRecords policy', () => { + expect(() => defineDomain({ + name: 'ok', version: 1, invalidRecords: 'zap' as 'backup-and-skip', tables: {}, + })).toThrow(/invalidRecords/) + }) + it('rejects an invalid layout and projects the declared one onto the descriptor', () => { // A spec built from config can carry any value; the union type is // compile-time only, so the runtime boundary check must reject it. @@ -139,6 +158,28 @@ describe('DomainFacility.open', () => { }) }) + it('keeps the rejecting default under backup-and-skip when the backend cannot move documents', async () => { + // The memory backend has no backupRecord, so the declared policy cannot + // apply and the open falls back to failing loud. + const salvageSpec = defineDomain({ + name: 'salvage', + version: 1, + invalidRecords: 'backup-and-skip', + tables: { items: domainTable(itemSchema) }, + }) + const pool = new MemoryMediaPool() + { + const { facility } = await harness({ pool }) + await (await facility.open(salvageSpec)).table('items').put('bad', { label: 'x', count: 2 }) + } + pool.media.get('salvage')!.tables.get('items')!.set('bad', { label: 'x', count: 'NaN' }) + const { facility } = await harness({ pool }) + await expect(facility.open(salvageSpec)).rejects.toMatchObject({ + code: 'invalid-record', + detail: { table: 'items', key: 'bad' }, + }) + }) + it('rejects a stored global that fails its schema with the global marker', async () => { const pool = new MemoryMediaPool() pool.versions.set('demo', 1) diff --git a/packages/storage/storage-json/src/format.ts b/packages/storage/storage-json/src/format.ts index 045485eaba..22cbe8f703 100644 --- a/packages/storage/storage-json/src/format.ts +++ b/packages/storage/storage-json/src/format.ts @@ -100,16 +100,18 @@ export function serializeRecord(version: number, value: unknown): string { /** * Parse one per-record document, validating its version stamp. A document - * that is malformed or stamped with a different version is FOREIGN and reads - * as absent — the per-record contract: one bad or stale record file must not - * brick the whole unit, and a version bump discards stale records instead of - * migrating them (the whole-unit format rejects instead, because there is - * exactly one document). + * that is malformed or stamped with an unaccepted version is FOREIGN and + * reads as absent — the per-record contract: one bad or stale record file + * must not brick the whole unit, and a version bump discards stale records + * instead of migrating them (the whole-unit format rejects instead, because + * there is exactly one document). * @param text - Raw per-record document content. - * @param version - Expected unit version; a mismatch discards the document. + * @param versions - Accepted unit versions (the current one plus the + * descriptor's compatibleVersions); any other stamp discards the + * document. * @returns the record value, or `undefined` for a foreign document. */ -export function parseRecord(text: string, version: number): unknown { +export function parseRecord(text: string, versions: readonly number[]): unknown { let document: unknown try { document = JSON.parse(text) @@ -118,6 +120,6 @@ export function parseRecord(text: string, version: number): unknown { } if (typeof document !== 'object' || document === null) return undefined const { version: stamped, record } = document as Record - if (stamped !== version) return undefined + if (typeof stamped !== 'number' || !versions.includes(stamped)) return undefined return record } diff --git a/packages/storage/storage-json/src/per-record-unit.ts b/packages/storage/storage-json/src/per-record-unit.ts index b75f9f9452..346c7a0d6a 100644 --- a/packages/storage/storage-json/src/per-record-unit.ts +++ b/packages/storage/storage-json/src/per-record-unit.ts @@ -10,20 +10,23 @@ * memory unchanged. * * Per-record contract: a record document that is malformed or stamped with a - * different version reads as an absent record — one bad or stale file never - * bricks the whole unit, and a version bump discards stale records instead - * of migrating them. Record keys become path segments, so they must be - * path-safe (`[a-zA-Z0-9_-]+`); an unsafe key rejects at write. + * version outside the accepted set (the descriptor's current version plus + * its `compatibleVersions`) reads as an absent record — one bad or stale + * file never bricks the whole unit, and a version bump discards stale + * records instead of migrating them. Record keys become path segments, so + * they must be path-safe (`[a-zA-Z0-9_-]+`); an unsafe key rejects at write. * * Legacy bootstrap: when the new tree has no document path, a legacy * whole-unit file `/.json` (the pre-per-record layout) seeds - * per-record documents. Any new document path, including one whose contents - * are unreadable or stale, suppresses the bootstrap for the whole unit. The + * per-record documents, provided its stored unit version is in the accepted + * set — a legacy file stamped with any other version is left alone and reads + * as the empty unit. Any new document path, including one whose contents are + * unreadable or stale, suppresses the bootstrap for the whole unit. The * legacy file is never changed or deleted. * @module @deepseek-ai/dsh-storage-json/src/per-record-unit */ -import { mkdir, readFile, readdir, rm } from 'node:fs/promises' +import { mkdir, readFile, readdir, rename, rm } from 'node:fs/promises' import { dirname, join } from 'node:path' import type { Dirent } from 'node:fs' import { StorageError } from '@deepseek-ai/dsh-storage' @@ -64,6 +67,7 @@ export async function openPerRecordUnit( * @returns the authoritative state reconstructed from the tree. */ async function loadPerRecordState(descriptor: KvUnitDescriptor, dir: string): Promise { + const versions = acceptedStamps(descriptor) const state: UnitState = { version: descriptor.version, global: null, @@ -83,11 +87,11 @@ async function loadPerRecordState(descriptor: KvUnitDescriptor, dir: string): Pr if (entry.isDirectory()) { const records = state.tables.get(entry.name) if (records !== undefined) { - return loadTableRecords(records, descriptor.version, join(dir, entry.name)) + return loadTableRecords(records, versions, join(dir, entry.name)) } } if (entry.name === 'global.json' && descriptor.hasGlobal) { - const global = await readRecord(join(dir, entry.name), descriptor.version) + const global = await readRecord(join(dir, entry.name), versions) if (global !== undefined) state.global = global return true } @@ -97,12 +101,21 @@ async function loadPerRecordState(descriptor: KvUnitDescriptor, dir: string): Pr return state } +/** The version stamps this unit reads as its own: current plus declared compatible versions. */ +function acceptedStamps(descriptor: KvUnitDescriptor): readonly number[] { + return [descriptor.version, ...descriptor.compatibleVersions ?? []] +} + /** * Bootstrap an empty per-record tree from a legacy whole-unit file * (`/.json`, the pre-per-record layout). Every declared-table * record is copied into a current-version document, while the legacy file is * retained unchanged. A missing, foreign (another unit's name), malformed, - * or non-unit legacy file is left alone; other read failures propagate. + * or non-unit legacy file is left alone, and so is one whose stored unit + * version is outside the accepted set — migrating records the owner never + * vouched for would stamp them with the current version and turn a + * discardable stale cache into schema failures at the domain layer. Other + * read failures propagate. * @param descriptor - Static identity and shape of the unit. * @param dir - The per-record unit directory (`/`). * @param state - The empty tree state; bootstrapped records are added. @@ -116,16 +129,18 @@ async function bootstrapLegacyUnit(descriptor: KvUnitDescriptor, dir: string, st if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error return } - // The legacy document is runtime data: only `unit.name` and the tables map - // shape are checked here — the record values are migrated as-is and the - // domain layer's schemas judge them. - let document: { unit?: { name?: unknown }; tables?: unknown } + // The legacy document is runtime data: only `unit.name`, `unit.version`, + // and the tables map shape are checked here — the record values are + // migrated as-is and the domain layer's schemas judge them. + let document: { unit?: { name?: unknown; version?: unknown }; tables?: unknown } try { - document = JSON.parse(text) as { unit?: { name?: unknown }; tables?: unknown } + document = JSON.parse(text) as { unit?: { name?: unknown; version?: unknown }; tables?: unknown } } catch { return // Malformed legacy file: not ours to interpret or delete. } if (document.unit?.name !== descriptor.name) return + const stamped = document.unit.version + if (typeof stamped !== 'number' || !acceptedStamps(descriptor).includes(stamped)) return const tables = document.tables if (typeof tables !== 'object' || tables === null) return const recordsByTable = tables as Record> @@ -146,14 +161,14 @@ async function bootstrapLegacyUnit(descriptor: KvUnitDescriptor, dir: string, st * @returns whether the directory contains any `.json` document path, * independently of key safety, readability, or stored version. */ -async function loadTableRecords(records: Map, version: number, dir: string): Promise { +async function loadTableRecords(records: Map, versions: readonly number[], dir: string): Promise { const files = await readdir(dir, { withFileTypes: true }) const hasDocuments = files.some(file => file.name.endsWith('.json')) const loaded = await Promise.all(files.map(async (file) => { if (!file.name.endsWith('.json')) return const key = file.name.slice(0, -'.json'.length) if (!SAFE_KEY_RE.test(key)) return - const record = await readRecord(join(dir, file.name), version) + const record = await readRecord(join(dir, file.name), versions) if (record !== undefined) return [key, record] as const })) for (const record of loaded) { @@ -163,9 +178,9 @@ async function loadTableRecords(records: Map, version: number, } /** Read one record document; a foreign (unreadable or stale) one reads as absent. */ -async function readRecord(path: string, version: number): Promise { +async function readRecord(path: string, versions: readonly number[]): Promise { try { - return parseRecord(await readFile(path, 'utf8'), version) + return parseRecord(await readFile(path, 'utf8'), versions) } catch { return undefined } @@ -213,6 +228,22 @@ export class PerRecordJsonUnit implements KvUnit { await this.tracked(rm(join(this.tableDir(table), `${key}.json`), { force: true })) } + /** + * Move one record's document aside as `.json.bak.`. The + * moved file no longer ends in `.json`, so every later read ignores it; the + * bytes stay on disk for inspection. A same-minute backup of the same + * key overwrites the previous backup (the newer bytes are the ones worth + * keeping). + */ + async backupRecord(table: string, key: string): Promise { + this.assertOpen() + assertSafeKey(this.descriptor.name, key) + const path = join(this.tableDir(table), `${key}.json`) + const moved = `${path}.bak.${backupStamp(new Date())}` + await this.tracked(rename(path, moved)) + return moved + } + /** Durably replace the global singleton. Only valid when declared. */ async setGlobal(value: unknown): Promise { this.assertOpen() @@ -267,6 +298,12 @@ export class PerRecordJsonUnit implements KvUnit { } } +/** Local-time `YYYYMMDDHHmm` suffix for backed-up documents. */ +function backupStamp(now: Date): string { + const pad = (value: number): string => String(value).padStart(2, '0') + return `${String(now.getFullYear())}${pad(now.getMonth() + 1)}${pad(now.getDate())}${pad(now.getHours())}${pad(now.getMinutes())}` +} + /** Reject a record key that would be unsafe as a path segment. */ function assertSafeKey(unit: string, key: string): void { if (!SAFE_KEY_RE.test(key)) { diff --git a/packages/storage/storage-json/tests/json-backend.spec.ts b/packages/storage/storage-json/tests/json-backend.spec.ts index bafbf92ef4..57ad9d7633 100644 --- a/packages/storage/storage-json/tests/json-backend.spec.ts +++ b/packages/storage/storage-json/tests/json-backend.spec.ts @@ -329,10 +329,10 @@ describe('per-record layout', () => { it('bootstraps an empty per-record tree from a legacy whole-unit file and preserves it', async () => { const root = await freshRoot() - // A legacy single-layout file for the same unit (any older version); - // the extra table is not declared and must be skipped. + // A legacy single-layout file for the same unit, stamped with the current + // version; the extra table is not declared and must be skipped. const legacy = JSON.stringify({ - unit: { name: 'recs', version: 3 }, + unit: { name: 'recs', version: 2 }, global: null, tables: { t: { old1: { v: 1 }, old2: { v: 2 } }, undeclared: { k: { v: 0 } } }, }) @@ -347,6 +347,75 @@ describe('per-record layout', () => { await backend.close() }) + it('bootstraps from a legacy file only when its stored version is accepted', async () => { + // Version 3 is neither current (2) nor declared compat: the legacy file + // is left alone and the unit reads empty — migrating unvouched records + // would stamp them current and surface as schema failures at the domain + // layer instead of a discardable stale cache. + const root = await freshRoot() + const legacy = JSON.stringify({ + unit: { name: 'recs', version: 3 }, + global: null, + tables: { t: { old: { v: 1 } } }, + }) + await writeFile(join(root, 'recs.json'), legacy, 'utf8') + const backend = new JsonStorageBackend(root) + const unit = await backend.kv.open(descriptor) + expect(await unit.loadAll()).toEqual({ tables: { t: {} }, global: null }) + await expect(readFile(join(root, 'recs.json'), 'utf8')).resolves.toBe(legacy) + await unit.close() + await backend.close() + + // The same file bootstraps once version 3 is declared read-compatible… + const root2 = await freshRoot() + await writeFile(join(root2, 'recs.json'), legacy, 'utf8') + const backend2 = new JsonStorageBackend(root2) + const compat = { ...descriptor, version: 4, compatibleVersions: [3] } + const unit2 = await backend2.kv.open(compat) + expect(await unit2.loadAll()).toEqual({ tables: { t: { old: { v: 1 } } }, global: null }) + // …and the migrated documents are stamped with the CURRENT version. + expect(JSON.parse(await readFile(join(root2, 'recs', 't', 'old.json'), 'utf8'))) + .toEqual({ version: 4, record: { v: 1 } }) + await unit2.close() + await backend2.close() + }) + + it('backupRecord moves the document aside; reads see it absent and a write recreates it', async () => { + const root = await freshRoot() + const backend = new JsonStorageBackend(root) + const unit = await backend.kv.open(descriptor) + await unit.putRecord('t', 'k', { v: 1 }) + const moved = await unit.backupRecord!('t', 'k') + expect(moved).toMatch(/k\.json\.bak\.\d{12}$/) + expect(JSON.parse(await readFile(moved, 'utf8'))).toEqual({ version: 2, record: { v: 1 } }) + await expect(readFile(recordPath(root, 'k'), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' }) + // The moved file no longer ends in .json, so it reads as absent… + expect(await unit.loadAll()).toEqual({ tables: { t: {} }, global: null }) + // …and the key is free for a fresh write. + await unit.putRecord('t', 'k', { v: 2 }) + expect(await unit.loadAll()).toEqual({ tables: { t: { k: { v: 2 } } }, global: null }) + await expect(unit.backupRecord!('t', 'a/b')).rejects.toThrow(/not path-safe/) + await unit.close() + await expect(unit.backupRecord!('t', 'k')).rejects.toMatchObject({ code: 'closed' }) + await backend.close() + }) + + it('reads per-record documents stamped with a declared compat version and stamps writes current', async () => { + const root = await freshRoot() + const backend = new JsonStorageBackend(root) + const compat = { ...descriptor, compatibleVersions: [1] } + await mkdir(join(root, 'recs', 't'), { recursive: true }) + await writeFile(recordPath(root, 'oldrec'), JSON.stringify({ version: 1, record: { v: 'old' } }), 'utf8') + await writeFile(recordPath(root, 'ancient'), JSON.stringify({ version: 0, record: { v: 'no' } }), 'utf8') + const unit = await backend.kv.open(compat) + // Version 1 is declared compat and served; version 0 is not and discards. + expect(await unit.loadAll()).toEqual({ tables: { t: { oldrec: { v: 'old' } } }, global: null }) + await unit.putRecord('t', 'oldrec', { v: 'new' }) + expect(JSON.parse(await readFile(recordPath(root, 'oldrec'), 'utf8'))) + .toEqual({ version: 2, record: { v: 'new' } }) + await backend.close() + }) + it('ignores the legacy whole-unit file when any new document path exists', async () => { const root = await freshRoot() const legacy = JSON.stringify({ @@ -400,7 +469,8 @@ describe('per-record layout', () => { await backend4.close() const root5 = await freshRoot() - await writeFile(join(root5, 'recs.json'), JSON.stringify({ unit: { name: 'recs' }, tables: 'not an object' }), 'utf8') + // A current-version stamp so the shapeless `tables` is what stops the bootstrap. + await writeFile(join(root5, 'recs.json'), JSON.stringify({ unit: { name: 'recs', version: 2 }, tables: 'not an object' }), 'utf8') const backend5 = new JsonStorageBackend(root5) const unit5 = await backend5.kv.open(descriptor) expect(await unit5.loadAll()).toEqual({ tables: { t: {} }, global: null }) diff --git a/packages/storage/storage/src/backend.ts b/packages/storage/storage/src/backend.ts index 9cba748655..4a8e0ac2d8 100644 --- a/packages/storage/storage/src/backend.ts +++ b/packages/storage/storage/src/backend.ts @@ -61,6 +61,16 @@ export interface KvUnitDescriptor { * foreign documents. */ readonly layout?: 'single' | 'per-record' + /** + * Older unit versions whose stored records are also readable under the + * declaring owner's current record schemas (the owner vouches for that — + * typically by declaring the fields old records lack as optional). Reads of + * a `per-record` unit accept documents stamped with any listed version, and + * the legacy whole-unit bootstrap accepts a legacy file stamped with one; + * writes always stamp {@link version}. `single`-layout reads stay + * exact-version. + */ + readonly compatibleVersions?: readonly number[] } /** @@ -99,6 +109,19 @@ export interface KvUnit { */ deleteRecord(table: string, key: string): Promise + /** + * Move one record's stored document out of the unit's readable set, + * preserving its bytes for inspection instead of deleting them. Backends + * whose medium has no per-record document to move (the `single` layout, a + * row store) omit this member, and the caller falls back to its + * reject-loud path. Absent after the move: a later {@link loadAll} reads + * the key as missing and a later {@link putRecord} recreates it fresh. + * @param table - Declared table name. + * @param key - Record key. + * @returns the medium location the document was moved to (diagnostics). + */ + backupRecord?(table: string, key: string): Promise + /** * Write the global singleton durably. Only valid when the descriptor * declared `hasGlobal`. From 49df707c865f4ad22c26dd56c810c8c0bb0af393 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:08:41 +0800 Subject: [PATCH 5/8] fix(session-projection-cache): keep upgraded caches readable and boots safe across domain versions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The session_projcache domain declares compatibleVersions: [3, 4] and invalidRecords: 'backup-and-skip'. The two lineage identity fields become optional — records admitted from older versions predate them, and the single reader (identityMatches) interprets absence as the unseeded lineage: exact for unseeded sessions, while a seeded caller fails the match and refolds cold, so the lineage binding keeps its protection. Upgraded homes therefore boot and serve their cached listing titles immediately, including homes whose new tree already holds current-stamped documents without lineage fields, and a record failing validation anyway is backed up and skipped instead of refusing the plugin tree. tests/fixtures/ archives the real on-disk media of every shipped generation (v3 whole-unit file, v4 and v5 per-record documents, and the lineage-less current-stamped shape); fixtures.spec.ts proves each recovers through the real storage stack, rewrites to the current format on the next live write, and that a hopeless record is salvaged without costing the boot. --- .../session-projection-cache/src/index.ts | 12 +- .../session-projection-cache/src/spec.ts | 29 ++- .../tests/cache.spec.ts | 58 +++++ .../tests/fixtures.spec.ts | 240 ++++++++++++++++++ .../tests/fixtures/v3-single-unit.json | 136 ++++++++++ .../tests/fixtures/v4-session-doc.json | 212 ++++++++++++++++ .../tests/fixtures/v5-lineageless-doc.json | 128 ++++++++++ .../tests/fixtures/v5-session-doc.json | 220 ++++++++++++++++ 8 files changed, 1029 insertions(+), 6 deletions(-) create mode 100644 packages/session/session-projection-cache/tests/fixtures.spec.ts create mode 100644 packages/session/session-projection-cache/tests/fixtures/v3-single-unit.json create mode 100644 packages/session/session-projection-cache/tests/fixtures/v4-session-doc.json create mode 100644 packages/session/session-projection-cache/tests/fixtures/v5-lineageless-doc.json create mode 100644 packages/session/session-projection-cache/tests/fixtures/v5-session-doc.json diff --git a/packages/session/session-projection-cache/src/index.ts b/packages/session/session-projection-cache/src/index.ts index 35bf5d9eed..22828a103c 100644 --- a/packages/session/session-projection-cache/src/index.ts +++ b/packages/session/session-projection-cache/src/index.ts @@ -367,12 +367,18 @@ function identityOf( } } -/** Whether a stored record's bound identity names the caller's lifecycle. */ +/** + * Whether a stored record's bound identity names the caller's lifecycle. + * Absent lineage fields (records admitted via `compatibleVersions` predate + * them) read as the unseeded lineage: exact for an unseeded caller, and a + * seeded caller's expectation then fails the match, discarding the record to + * a cold rebuild. + */ function identityMatches(stored: CheckpointIdentity, expected: CheckpointIdentity): boolean { return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd - && stored.isSeeded === expected.isSeeded - && stored.inheritedEventCount === expected.inheritedEventCount + && (stored.isSeeded ?? false) === expected.isSeeded + && (stored.inheritedEventCount ?? 0) === expected.inheritedEventCount } export default SessionProjectionCache diff --git a/packages/session/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts index 35351917a5..d368764244 100644 --- a/packages/session/session-projection-cache/src/spec.ts +++ b/packages/session/session-projection-cache/src/spec.ts @@ -38,12 +38,19 @@ export const checkpointRow = z.object({ * old record pass every watermark check and seed state folded from an * unrelated log. Reads validate this against the live header (listing) or * the stored header (cold read) before accepting any record. + * + * The lineage fields are optional because records admitted through + * `compatibleVersions` predate them. The reader (`identityMatches`) + * interprets their absence as the unseeded lineage — exact for an unseeded + * session, while a seeded expectation fails the match and the record is + * discarded to a cold rebuild. Current-version writes always store both + * fields. */ export const checkpointIdentity = z.object({ createdAt: z.number().int().nonnegative(), cwd: z.string().optional(), - isSeeded: z.boolean(), - inheritedEventCount: z.number().int().nonnegative().transform(SessionLogOffset), + isSeeded: z.boolean().optional(), + inheritedEventCount: z.number().int().nonnegative().transform(SessionLogOffset).optional(), }) /** The identity fields a record is bound to, inferred from {@link checkpointIdentity}. */ @@ -68,11 +75,27 @@ export type CheckpointRecord = z.infer * bumps per session: after a bump, a stale session document is discarded on * open (cache semantics — a stale or unreadable cache costs a longer tail * replay, never a wrong value) while the rest of the domain stays usable, - * instead of rejecting the whole medium. + * instead of rejecting the whole medium. The `compatibleVersions` entries + * are declared because those records differ from the current version only + * by the absent optional lineage fields, so upgraded homes keep serving + * their cached listing projections instead of dropping every title until + * each session is reopened; the per-record version map lives in the + * read-compat Agent Note + * (.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md). + * The per-row `ver` guard and the identity match still discard anything the + * current fold semantics cannot vouch for. + * + * `invalidRecords: 'backup-and-skip'`: a stored record that fails the schema + * anyway is disposable derived data, so it must never cost the boot — the + * domain layer moves the document aside as `.json.bak.`, logs + * the concrete validation failure, and serves the session as uncached (a + * cold read rebuilds and rewrites it). */ export const projectionCacheDomainSpec = defineDomain({ name: 'session_projcache', version: 5, + compatibleVersions: [3, 4], + invalidRecords: 'backup-and-skip', layout: 'per-record', tables: { sessions: domainTable(checkpointRecord) }, }) diff --git a/packages/session/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts index bfdca18567..4a5ce73d28 100644 --- a/packages/session/session-projection-cache/tests/cache.spec.ts +++ b/packages/session/session-projection-cache/tests/cache.spec.ts @@ -42,9 +42,11 @@ declare module '@deepseek-ai/dsh-session-projection/types' { 'cache-test/marks2': Map 'cache-test/count': number 'cache-test/secret': string + 'cache-test/marks3': MarksState } interface SessionProjectionMap { 'cache-test/marks': { marks: string[] } + 'cache-test/marks3': { marks: string[] } } } @@ -71,6 +73,18 @@ const marksUnit = (stateVersion = 1) => ({ stateVersion, }) satisfies ProjectionDefinition<'cache-test/marks', MarksState> +const marks3Unit = { + key: 'cache-test/marks3', + stateSchema: z.object({ marks: z.array(z.string()) }).nullable(), + init: () => null, + apply: state => state, + wire: { + viewSchema: z.object({ marks: z.array(z.string()) }), + view: state => state ?? { marks: [] }, + }, + stateVersion: 1, +} satisfies ProjectionDefinition<'cache-test/marks3', MarksState> + const secretUnit = { key: 'cache-test/secret', stateSchema: z.string(), @@ -376,6 +390,26 @@ describe('SessionProjectionCache listing read', () => { .toBeUndefined() }) + it('carries ONE cut across multiple served rows: the lowest watermark wins', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-')) + roots.push(root) + // Equal watermarks: whichever row is visited second cannot lower the cut, + // so the one-cut fold sees both a lowering and a non-lowering row in + // every iteration order. + await seedRecord(root, 'multi-row', { + 'cache-test/marks': { ver: 1, seq: SessionSeq(4), val: { marks: ['a'] } }, + 'cache-test/marks3': { ver: 1, seq: SessionSeq(4), val: { marks: ['b'] } }, + }) + const { ctx, cache } = await harness({ root }) + ctx.sessionProjections.register(marks3Unit) + const block = cache.cachedSnapshot(headerOf(SessionId('multi-row')), SessionLogOffset(0)) + expect(block?.values).toEqual({ + 'cache-test/marks': { marks: ['a'] }, + 'cache-test/marks3': { marks: ['b'] }, + }) + expect(block?.asOfSeq).toBe(4) + }) + it('returns undefined when the stored record is version-mismatched', async () => { const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-')) roots.push(root) @@ -394,6 +428,30 @@ describe('SessionProjectionCache listing read', () => { .toBeUndefined() }) + it('serves a pre-lineage record (accepted old version) to an unseeded caller only', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-')) + roots.push(root) + // A document stamped with an accepted older version whose identity + // predates the lineage fields: absent lineage reads as unseeded. + const path = recordPath(root, SessionId('pre-lineage')) + await mkdir(dirname(path), { recursive: true }) + await writeFile(path, JSON.stringify({ + version: 4, + record: { + identity: { createdAt: 0 }, + rows: { 'cache-test/marks': { ver: 1, seq: 4, val: { marks: ['kept'] } } }, + }, + })) + const { cache } = await harness({ root }) + const id = SessionId('pre-lineage') + // Unseeded caller: the absent lineage is exactly its identity — served. + expect(cache.cachedSnapshot(headerOf(id), SessionLogOffset(0))) + .toEqual({ asOfSeq: 4, values: { 'cache-test/marks': { marks: ['kept'] } } }) + // Seeded caller: the lineage-less record cannot vouch for the cut — refused. + expect(cache.cachedSnapshot({ ...headerOf(id), isSeeded: true }, SessionLogOffset(2))) + .toBeUndefined() + }) + it('returns undefined when every stored row is version-mismatched', async () => { const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-')) roots.push(root) diff --git a/packages/session/session-projection-cache/tests/fixtures.spec.ts b/packages/session/session-projection-cache/tests/fixtures.spec.ts new file mode 100644 index 0000000000..a85bcef5c6 --- /dev/null +++ b/packages/session/session-projection-cache/tests/fixtures.spec.ts @@ -0,0 +1,240 @@ +/** + * Cross-version recovery over archived on-disk artifacts. `fixtures/` holds + * real `session_projcache` media produced by released builds through their + * web apps (see scripts/releasefix): the v3 whole-unit file, a v4 per-record + * document, a current v5 document, and the v5-stamped lineage-less document + * that the formerly unguarded legacy bootstrap wrote over v3 records. Each + * must recover through the real storage stack — the domain opens and the + * listing read serves the archived title — and a record that fails schema + * validation anyway is backed up and skipped instead of failing the boot. + */ + +import { afterEach, describe, expect, it, vi } from 'vitest' +import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { Context } from '@deepseek-ai/cordis' +import { z } from 'zod' +import SessionStore, { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session' +import type { SessionHeader } from '@deepseek-ai/dsh-session' +import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' +import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection' +import Storage from '@deepseek-ai/dsh-storage' +import { + apply as storageJsonApply, Config as storageJsonConfig, inject as storageJsonInject, name as storageJsonName, +} from '@deepseek-ai/dsh-storage-json' +import { + apply as storageDomainApply, Config as storageDomainConfig, inject as storageDomainInject, name as storageDomainName, +} from '@deepseek-ai/dsh-storage-domain' +import SessionProjectionCache from '../src/index.ts' +import { projectionCacheDomainSpec } from '../src/spec.ts' + +// Declarations must match the shipped title unit's exactly (the repo-wide +// compile face sees both). +declare module '@deepseek-ai/dsh-session-projection/types' { + interface SessionProjectionStateMap { + title: string | null + } + interface SessionProjectionMap { + title: string | null + } +} + +declare module '@deepseek-ai/dsh-session/types' { + interface SessionEventMap { + 'fixtures-test/set-title': { title: string } + } + + interface OutOfBandSessionEventMap { + 'fixtures-test/set-title': true + } +} + +// Mirrors the shipped title unit's storage face: stateVersion 1, bare-string +// state (the fixture rows carry exactly this shape in every archived +// version), folding a test event so the rewrite path has fresh data. +const titleUnit = { + key: 'title', + stateSchema: z.string().nullable(), + init: () => null, + apply: (state, event) => (event.type === 'fixtures-test/set-title' ? event.data.title : state), + wire: { viewSchema: z.string().nullable(), view: state => state }, + stateVersion: 1, +} satisfies ProjectionDefinition<'title', string | null> + +const FIXTURES = fileURLToPath(new URL('./fixtures/', import.meta.url)) + +/** One archived per-record document (`{version, record}`). */ +interface FixtureDoc { + version: number + record: { + identity: { createdAt: number; cwd?: string } + rows: Record + } +} + +async function fixtureJson(name: string): Promise { + return JSON.parse(await readFile(join(FIXTURES, name), 'utf8')) as T +} + +/** Header for the session a fixture record is bound to (identity witness). */ +function headerFor(id: SessionId, identity: FixtureDoc['record']['identity']): SessionHeader { + return { + version: 0, + id, + createdAt: identity.createdAt, + isSeeded: false, + ...identity.cwd === undefined ? {} : { cwd: identity.cwd }, + } +} + +const contexts: Context[] = [] +const roots: string[] = [] + +async function harness(root: string) { + roots.push(root) + const ctx = new Context() + contexts.push(ctx) + await ctx.plugin(Storage) + await ctx.plugin({ name: storageJsonName, inject: storageJsonInject, apply: storageJsonApply, Config: storageJsonConfig }, { root }) + await ctx.plugin({ name: storageDomainName, inject: storageDomainInject, apply: storageDomainApply, Config: storageDomainConfig }, { backend: 'json' }) + await ctx.plugin(SessionStore) + await ctx.plugin(SessionProjectionRegistry) + ctx.sessionProjections.register(titleUnit) + await ctx.plugin(SessionProjectionCache, { writeEveryEvents: 100, writeIntervalMs: 60_000 }) + return { ctx, cache: ctx.sessionProjectionCache } +} + +/** Lay one per-record fixture document into a fresh backend root. */ +async function placeDoc(root: string, id: string, name: string): Promise { + const path = join(root, projectionCacheDomainSpec.name, 'sessions', `${id}.json`) + await mkdir(dirname(path), { recursive: true }) + await cp(join(FIXTURES, name), path) + return fixtureJson(name) +} + +/** + * Drive a live write over a recovered session id and assert the archived + * document is replaced by a current-version one: v5 stamp, lineage present, + * and the freshly folded title — the write path never keeps the old format. + */ +async function assertRewrite(ctx: Context, root: string, id: SessionId): Promise { + const session = ctx.sessions.create(id) + session.append('fixtures-test/set-title', { title: '重写标题' }) + session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + const path = join(root, projectionCacheDomainSpec.name, 'sessions', `${id}.json`) + await vi.waitFor(async () => { + const doc = JSON.parse(await readFile(path, 'utf8')) as FixtureDoc + expect(doc.version).toBe(projectionCacheDomainSpec.version) + expect(doc.record.identity).toMatchObject({ isSeeded: false, inheritedEventCount: 0 }) + expect(doc.record.rows['title']?.val).toBe('重写标题') + }, { timeout: 5_000 }) +} + +afterEach(async () => { + await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose())) + await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }))) +}) + +describe('archived version recovery', () => { + it('recovers the v3 whole-unit archive through the legacy bootstrap', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-fx-')) + await cp(join(FIXTURES, 'v3-single-unit.json'), join(root, `${projectionCacheDomainSpec.name}.json`)) + type SingleUnit = { + unit: { version: number } + tables: { sessions: Record } + } + const archive = await fixtureJson('v3-single-unit.json') + expect(archive.unit.version).toBe(3) // the fixture IS the old format + const [sid, record] = Object.entries(archive.tables.sessions)[0]! + + const { ctx, cache } = await harness(root) + const snapshot = cache.cachedSnapshot(headerFor(SessionId(sid), record.identity), SessionLogOffset(0), ['title']) + expect(snapshot?.values.title).toBe(record.rows['title']!.val) + + // The one-time bootstrap materialized a current-version document. + const migrated = JSON.parse( + await readFile(join(root, projectionCacheDomainSpec.name, 'sessions', `${sid}.json`), 'utf8'), + ) as { version: number } + expect(migrated.version).toBe(projectionCacheDomainSpec.version) + + await assertRewrite(ctx, root, SessionId(sid)) + }) + + for (const [fixture, storedVersion] of [ + ['v4-session-doc.json', 4], + ['v5-session-doc.json', 5], + ['v5-lineageless-doc.json', 5], + ] as const) { + it(`serves the archived title from ${fixture}, then rewrites it current`, async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-fx-')) + const id = SessionId('fixture-session') + const doc = await placeDoc(root, id, fixture) + expect(doc.version).toBe(storedVersion) + + const { ctx, cache } = await harness(root) + const snapshot = cache.cachedSnapshot(headerFor(id, doc.record.identity), SessionLogOffset(0), ['title']) + expect(snapshot?.values.title).toBe(doc.record.rows['title']!.val) + + await assertRewrite(ctx, root, id) + }) + } + + it('refuses a lineage-less archive for a seeded caller (identity mismatch, cold rebuild)', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-fx-')) + const id = SessionId('fixture-seeded') + const doc = await placeDoc(root, id, 'v5-lineageless-doc.json') + + const { cache } = await harness(root) + const seeded = { ...headerFor(id, doc.record.identity), isSeeded: true } + expect(cache.cachedSnapshot(seeded, SessionLogOffset(2), ['title'])).toBeUndefined() + }) + + it('backs up and skips a record that fails schema validation instead of failing the boot', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-projcache-fx-')) + roots.push(root) + const sessionsDir = join(root, projectionCacheDomainSpec.name, 'sessions') + await mkdir(sessionsDir, { recursive: true }) + // Current-version stamp, hopeless record content: no compat rung can save it. + await writeFile(join(sessionsDir, 'broken.json'), JSON.stringify({ + version: projectionCacheDomainSpec.version, + record: { identity: { createdAt: 'not-a-number' }, rows: 'not-an-object' }, + })) + const good = await placeDoc(root, SessionId('survivor'), 'v5-session-doc.json') + + const ctx = new Context() + contexts.push(ctx) + await ctx.plugin(Storage) + await ctx.plugin({ name: storageJsonName, inject: storageJsonInject, apply: storageJsonApply, Config: storageJsonConfig }, { root }) + await ctx.plugin({ name: storageDomainName, inject: storageDomainInject, apply: storageDomainApply, Config: storageDomainConfig }, { backend: 'json' }) + await ctx.plugin(SessionStore) + await ctx.plugin(SessionProjectionRegistry) + ctx.sessionProjections.register(titleUnit) + const error = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {}) + // The boot survives the broken record — this line rejecting IS the fixed bug. + await ctx.plugin(SessionProjectionCache, { writeEveryEvents: 100, writeIntervalMs: 60_000 }) + + // Concrete console diagnostics: which record, where it went, and why. + expect(error).toHaveBeenCalledWith(expect.stringContaining("record 'broken'")) + expect(error).toHaveBeenCalledWith(expect.stringContaining('.json.bak.')) + + // The document was moved aside as .json.bak., bytes intact. + const entries = await readdir(sessionsDir) + expect(entries).not.toContain('broken.json') + const backup = entries.find(name => /^broken\.json\.bak\.\d{12}$/.test(name)) + expect(backup).toBeDefined() + expect(JSON.parse(await readFile(join(sessionsDir, backup!), 'utf8'))) + .toMatchObject({ record: { rows: 'not-an-object' } }) + + // The broken record reads as absent; its neighbors still serve. + const cache = ctx.sessionProjectionCache + expect(cache.cachedSnapshot(headerFor(SessionId('broken'), { createdAt: 0 }), SessionLogOffset(0))) + .toBeUndefined() + expect(cache.cachedSnapshot( + headerFor(SessionId('survivor'), good.record.identity), + SessionLogOffset(0), + ['title'], + )?.values.title).toBe(good.record.rows['title']!.val) + }) +}) diff --git a/packages/session/session-projection-cache/tests/fixtures/v3-single-unit.json b/packages/session/session-projection-cache/tests/fixtures/v3-single-unit.json new file mode 100644 index 0000000000..4b36243611 --- /dev/null +++ b/packages/session/session-projection-cache/tests/fixtures/v3-single-unit.json @@ -0,0 +1,136 @@ +{ + "unit": { + "name": "session_projcache", + "version": 3 + }, + "global": null, + "tables": { + "sessions": { + "session-1374fa81-15da-44ca-be12-b4c6fe8076a3": { + "identity": { + "createdAt": 1788286864454, + "cwd": "/tmp" + }, + "rows": { + "sessionStats": { + "ver": 1, + "seq": 54, + "val": { + "turns": 2, + "steps": 2, + "llmMs": 2169, + "toolMs": 0, + "ttftMs": 1872, + "ttftSteps": 2, + "decodeMs": 297, + "decodeTokens": 20, + "lastTurn": 2, + "openStep": null, + "pendingCalls": {} + } + }, + "title": { + "ver": 1, + "seq": 54, + "val": "验收标题-rc2" + }, + "goal": { + "ver": 4, + "seq": 54, + "val": null + }, + "tokenUsage": { + "ver": 1, + "seq": 54, + "val": { + "totals": { + "uncachedInputTokens": 6083, + "outputTokens": 20, + "cacheReadTokens": 9728, + "cacheWriteTokens": 0 + }, + "last": { + "turn": 2, + "step": 1, + "buckets": { + "uncachedInputTokens": 112, + "outputTokens": 4, + "cacheReadTokens": 7808, + "cacheWriteTokens": 0 + } + } + } + }, + "contextPressure": { + "ver": 4, + "seq": 54, + "val": { + "surfaceTokens": 178, + "contextWindow": 1000000, + "pressureTokens": 7920, + "sampledSurfaceTokens": 168 + } + }, + "contextBreakdown": { + "ver": 2, + "seq": 54, + "val": { + "systemTokens": 1620, + "toolsTokens": 6475, + "messageTokens": 178 + } + }, + "subagentTiming": { + "ver": 2, + "seq": 54, + "val": { + "descriptorSeen": false, + "settledMs": 0 + } + }, + "subagent": { + "ver": 2, + "seq": 54, + "val": {} + }, + "permissions": { + "ver": 1, + "seq": 54, + "val": { + "preset": "workspace-write", + "sandbox": "workspace-write", + "approval": "ask" + } + }, + "sessionListMetadata": { + "ver": 1, + "seq": 54, + "val": { + "blank": false, + "lastPromptAt": 1788286867410 + } + }, + "imageLimits": { + "ver": 1, + "seq": 54, + "val": null + }, + "todos": { + "ver": 2, + "seq": 54, + "val": null + }, + "plan": { + "ver": 2, + "seq": 54, + "val": { + "active": false, + "wanted": null, + "running": null + } + } + } + } + } + } +} diff --git a/packages/session/session-projection-cache/tests/fixtures/v4-session-doc.json b/packages/session/session-projection-cache/tests/fixtures/v4-session-doc.json new file mode 100644 index 0000000000..56d6868405 --- /dev/null +++ b/packages/session/session-projection-cache/tests/fixtures/v4-session-doc.json @@ -0,0 +1,212 @@ +{ + "version": 4, + "record": { + "identity": { + "createdAt": 1788286912530, + "cwd": "/tmp" + }, + "rows": { + "title": { + "ver": 1, + "seq": 68, + "val": "验收标题-alpha3" + }, + "titleInput": { + "ver": 3, + "seq": 68, + "val": { + "first": { + "seq": 7, + "text": "请只回复一个词:pong" + }, + "count": 2, + "lastSeq": 58 + } + }, + "llmRetry": { + "ver": 1, + "seq": 68, + "val": {} + }, + "sandboxMode": { + "ver": 1, + "seq": 68, + "val": "workspace-write" + }, + "goal": { + "ver": 6, + "seq": 68, + "val": { + "current": null, + "seenGoalIds": [], + "failure": null + } + }, + "tokenUsage": { + "ver": 2, + "seq": 68, + "val": { + "totals": { + "uncachedInputTokens": 8192, + "outputTokens": 35, + "cacheReadTokens": 8064, + "cacheWriteTokens": 0 + }, + "last": { + "turn": 2, + "step": 1, + "buckets": { + "uncachedInputTokens": 86, + "outputTokens": 4, + "cacheReadTokens": 8064, + "cacheWriteTokens": 0 + } + } + } + }, + "contextPressure": { + "ver": 4, + "seq": 68, + "val": { + "surfaceTokens": 193, + "contextWindow": 1000000, + "pressureTokens": 8150, + "sampledSurfaceTokens": 183 + } + }, + "contextBreakdown": { + "ver": 2, + "seq": 68, + "val": { + "systemTokens": 1760, + "toolsTokens": 6579, + "messageTokens": 193 + } + }, + "turnBoundary": { + "ver": 2, + "seq": 68, + "val": { + "openTurnStartSeq": null, + "lastStepStartSeq": 57, + "lastStepBoundary": { + "kind": "end", + "seq": 67 + }, + "lastTurn": 2 + } + }, + "sessionStats": { + "ver": 1, + "seq": 68, + "val": { + "turns": 2, + "steps": 2, + "llmMs": 3486, + "toolMs": 0, + "ttftMs": 3199, + "ttftSteps": 2, + "decodeMs": 287, + "decodeTokens": 35, + "lastTurn": 2, + "openStep": null, + "pendingCalls": {} + } + }, + "turnOutline": { + "ver": 2, + "seq": 68, + "val": { + "turns": [ + { + "turn": 1, + "seq": 4, + "prompt": "请只回复一个词:pong", + "response": "pong" + }, + { + "turn": 2, + "seq": 55, + "prompt": "请只回复一个词:pong2", + "response": "pong2" + } + ], + "draft": "" + } + }, + "agentPreset": { + "ver": 1, + "seq": 68, + "val": "standard" + }, + "subagentTiming": { + "ver": 2, + "seq": 68, + "val": { + "descriptorSeen": false, + "settledMs": 0 + } + }, + "subagent": { + "ver": 2, + "seq": 68, + "val": {} + }, + "permissions": { + "ver": 2, + "seq": 68, + "val": { + "preset": "workspace-write", + "sandbox": "workspace-write", + "approval": "ask", + "seeded": false + } + }, + "modelSelection": { + "ver": 2, + "seq": 68, + "val": { + "lastUsed": { + "provider": "deepseek-official", + "model": "deepseek-v4-flash", + "reasoningEffort": "high" + }, + "pending": null + } + }, + "sessionListMetadata": { + "ver": 1, + "seq": 68, + "val": { + "blank": false, + "lastPromptAt": 1788286917834 + } + }, + "imageLimits": { + "ver": 1, + "seq": 68, + "val": null + }, + "todos": { + "ver": 2, + "seq": 68, + "val": null + }, + "plan": { + "ver": 3, + "seq": 68, + "val": { + "active": false, + "wanted": null, + "running": null, + "activeAtLastHeader": false + } + }, + "subagentModelSelectionPolicy": { + "ver": 1, + "seq": 68, + "val": null + } + } + } +} diff --git a/packages/session/session-projection-cache/tests/fixtures/v5-lineageless-doc.json b/packages/session/session-projection-cache/tests/fixtures/v5-lineageless-doc.json new file mode 100644 index 0000000000..f887e980e2 --- /dev/null +++ b/packages/session/session-projection-cache/tests/fixtures/v5-lineageless-doc.json @@ -0,0 +1,128 @@ +{ + "version": 5, + "record": { + "identity": { + "createdAt": 1788286864454, + "cwd": "/tmp" + }, + "rows": { + "sessionStats": { + "ver": 1, + "seq": 54, + "val": { + "turns": 2, + "steps": 2, + "llmMs": 2169, + "toolMs": 0, + "ttftMs": 1872, + "ttftSteps": 2, + "decodeMs": 297, + "decodeTokens": 20, + "lastTurn": 2, + "openStep": null, + "pendingCalls": {} + } + }, + "title": { + "ver": 1, + "seq": 54, + "val": "\u9a8c\u6536\u6807\u9898-rc2" + }, + "goal": { + "ver": 4, + "seq": 54, + "val": null + }, + "tokenUsage": { + "ver": 1, + "seq": 54, + "val": { + "totals": { + "uncachedInputTokens": 6083, + "outputTokens": 20, + "cacheReadTokens": 9728, + "cacheWriteTokens": 0 + }, + "last": { + "turn": 2, + "step": 1, + "buckets": { + "uncachedInputTokens": 112, + "outputTokens": 4, + "cacheReadTokens": 7808, + "cacheWriteTokens": 0 + } + } + } + }, + "contextPressure": { + "ver": 4, + "seq": 54, + "val": { + "surfaceTokens": 178, + "contextWindow": 1000000, + "pressureTokens": 7920, + "sampledSurfaceTokens": 168 + } + }, + "contextBreakdown": { + "ver": 2, + "seq": 54, + "val": { + "systemTokens": 1620, + "toolsTokens": 6475, + "messageTokens": 178 + } + }, + "subagentTiming": { + "ver": 2, + "seq": 54, + "val": { + "descriptorSeen": false, + "settledMs": 0 + } + }, + "subagent": { + "ver": 2, + "seq": 54, + "val": {} + }, + "permissions": { + "ver": 1, + "seq": 54, + "val": { + "preset": "workspace-write", + "sandbox": "workspace-write", + "approval": "ask" + } + }, + "sessionListMetadata": { + "ver": 1, + "seq": 54, + "val": { + "blank": false, + "lastPromptAt": 1788286867410 + } + }, + "imageLimits": { + "ver": 1, + "seq": 54, + "val": null + }, + "todos": { + "ver": 2, + "seq": 54, + "val": null + }, + "plan": { + "ver": 2, + "seq": 54, + "val": { + "active": false, + "wanted": null, + "running": null + } + } + } + } +} diff --git a/packages/session/session-projection-cache/tests/fixtures/v5-session-doc.json b/packages/session/session-projection-cache/tests/fixtures/v5-session-doc.json new file mode 100644 index 0000000000..9b822870a8 --- /dev/null +++ b/packages/session/session-projection-cache/tests/fixtures/v5-session-doc.json @@ -0,0 +1,220 @@ +{ + "version": 5, + "record": { + "identity": { + "createdAt": 1788286864454, + "cwd": "/tmp", + "isSeeded": false, + "inheritedEventCount": 0 + }, + "rows": { + "title": { + "ver": 1, + "seq": 71, + "val": "验收标题-rc2" + }, + "titleInput": { + "ver": 3, + "seq": 71, + "val": { + "first": { + "seq": 7, + "text": "请只回复一个词:pong" + }, + "count": 3, + "lastSeq": 60 + } + }, + "llmRetry": { + "ver": 1, + "seq": 71, + "val": {} + }, + "sandboxMode": { + "ver": 1, + "seq": 71, + "val": "workspace-write" + }, + "goal": { + "ver": 6, + "seq": 71, + "val": { + "current": null, + "seenGoalIds": [], + "failure": null + } + }, + "tokenUsage": { + "ver": 2, + "seq": 71, + "val": { + "totals": { + "uncachedInputTokens": 14219, + "outputTokens": 24, + "cacheReadTokens": 9728, + "cacheWriteTokens": 0 + }, + "last": { + "turn": 3, + "step": 1, + "buckets": { + "uncachedInputTokens": 8136, + "outputTokens": 4, + "cacheReadTokens": 0, + "cacheWriteTokens": 0 + } + } + } + }, + "contextPressure": { + "ver": 4, + "seq": 71, + "val": { + "surfaceTokens": 200, + "contextWindow": 1000000, + "pressureTokens": 8136, + "sampledSurfaceTokens": 190 + } + }, + "contextBreakdown": { + "ver": 2, + "seq": 71, + "val": { + "systemTokens": 1729, + "toolsTokens": 6611, + "messageTokens": 200 + } + }, + "sessionStats": { + "ver": 1, + "seq": 71, + "val": { + "turns": 3, + "steps": 3, + "llmMs": 4368, + "toolMs": 0, + "ttftMs": 4030, + "ttftSteps": 3, + "decodeMs": 338, + "decodeTokens": 24, + "lastTurn": 3, + "openStep": null, + "pendingCalls": {} + } + }, + "agentPreset": { + "ver": 1, + "seq": 71, + "val": "standard" + }, + "subagentTiming": { + "ver": 2, + "seq": 71, + "val": { + "descriptorSeen": false, + "settledMs": 0 + } + }, + "subagent": { + "ver": 2, + "seq": 71, + "val": {} + }, + "turnBoundary": { + "ver": 2, + "seq": 71, + "val": { + "openTurnStartSeq": null, + "lastStepStartSeq": 59, + "lastStepBoundary": { + "kind": "end", + "seq": 70 + }, + "lastTurn": 3 + } + }, + "turnOutline": { + "ver": 2, + "seq": 71, + "val": { + "turns": [ + { + "turn": 1, + "seq": 4, + "prompt": "请只回复一个词:pong", + "response": "pong" + }, + { + "turn": 2, + "seq": 40, + "prompt": "请只回复一个词:pong2", + "response": "pong2" + }, + { + "turn": 3, + "seq": 57, + "prompt": "请只回复一个词:pong3", + "response": "pong3" + } + ], + "draft": "" + } + }, + "permissions": { + "ver": 2, + "seq": 71, + "val": { + "preset": "workspace-write", + "sandbox": "workspace-write", + "approval": "ask", + "seeded": true + } + }, + "modelSelection": { + "ver": 2, + "seq": 71, + "val": { + "lastUsed": { + "provider": "deepseek-official", + "model": "deepseek-v4-flash", + "reasoningEffort": "high" + }, + "pending": null + } + }, + "sessionListMetadata": { + "ver": 1, + "seq": 71, + "val": { + "blank": false, + "lastPromptAt": 1788287660106 + } + }, + "imageLimits": { + "ver": 1, + "seq": 71, + "val": null + }, + "todos": { + "ver": 2, + "seq": 71, + "val": null + }, + "plan": { + "ver": 3, + "seq": 71, + "val": { + "active": false, + "wanted": null, + "running": null, + "activeAtLastHeader": false + } + }, + "subagentModelSelectionPolicy": { + "ver": 1, + "seq": 71, + "val": null + } + } + } +} From bef26396e5a16b129b8f0f28b354b0ec3095b045 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:09:16 +0800 Subject: [PATCH 6/8] docs(session-projection-cache): cross-version read-compat note and schema-change fixture rule The proposed Agent Note records the three shipped on-disk generations of session_projcache, the read-compat and backup-and-skip decisions, the upgrade matrix, and the rejected alternatives. The package README documents the upgrade guarantees and requires every future schema or domain-version change to land with archived fixtures and tests proving its upgrade story. The storage subsystem page and the generated cordis catalog pick up the new DomainSpec fields. --- ...jcache-cross-version-read-compat.i18n.yaml | 6 ++ ...-02-projcache-cross-version-read-compat.md | 69 +++++++++++++++++++ ...-projcache-cross-version-read-compat.zh.md | 69 +++++++++++++++++++ docs/subsystems/storage.i18n.yaml | 4 +- docs/subsystems/storage.md | 25 ++++++- docs/subsystems/storage.zh.md | 25 ++++++- .../extensions/tool-cordis/src/api-catalog.ts | 8 +-- .../session-projection-cache/README.i18n.yaml | 4 +- .../session-projection-cache/README.md | 3 + .../session-projection-cache/README.zh.md | 3 + 10 files changed, 206 insertions(+), 10 deletions(-) create mode 100644 .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml create mode 100644 .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md create mode 100644 .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md diff --git a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml new file mode 100644 index 0000000000..412b47ab8f --- /dev/null +++ b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md +2026-09-02-projcache-cross-version-read-compat.md: 9bd0cd9049ed9c9d4180f54d55f10f9b0f555dfc +2026-09-02-projcache-cross-version-read-compat.zh.md: 4682c5fe4732b21649214ee98f25d478c9bfcb18 diff --git a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md new file mode 100644 index 0000000000..9bd0cd9049 --- /dev/null +++ b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md @@ -0,0 +1,69 @@ +# Agent Note: Projection-cache cross-version read compatibility (session_projcache v3/v4/v5) + +Status: proposed + +English | [中文](2026-09-02-projcache-cross-version-read-compat.zh.md) + +## Problem + +The `session_projcache` storage domain evolved through three on-disk generations across published releases. An upgraded DSH_HOME failed in two ways: + +- **A v3 single-file home bricked startup after the upgrade**: the per-record layout's legacy bootstrap migrated the old whole-unit file without checking its `unit.version`, stamping the old records with the current version into the new tree; the domain layer's per-record zod validation at open then hit the missing now-required fields → `invalid-record` → the whole domain refused to open → the plugin tree failed to load. And because the bootstrap writes before validation runs, **the first boot permanently wrote the bad documents into the new tree** ("poisoning") — every later boot saw a non-empty tree, never took the legacy path again, and the home stayed unusable. +- **A v4 per-record home lost its listing titles after the upgrade**: v4 documents were silently discarded by the version-stamp check (the per-record contract), and SessionList is a zero-I/O cache-only read, so a miss served the row without projections; titles only returned as each session was individually reopened. + +The cache domain's own contract is "a stale or unreadable cache costs a longer tail replay, never a wrong value, never a refused load" — the hard failure and the wholesale discard each broke the first half of that contract or the product expectation. + +## The three on-disk generations + +| domain version | shipped in | layout | on-disk form | identity fields | row fields | +|---|---|---|---|---|---| +| 3 | 0.1.1-rc.2 | single | one file `storages/session_projcache.json` (`{unit:{name,version}, global, tables}`) | `createdAt`, `cwd?` | `ver`, `seq`, `val` | +| 4 | 0.1.2-alpha.3 | per-record | one file per session `storages/session_projcache/sessions/.json` (`{version, record}`) | `createdAt`, `cwd?` | same | +| 5 | 0.1.2-alpha.4 | per-record | same as v4 | + `isSeeded` (required → optional in this change), `inheritedEventCount` (same) | same (`seq` numbers mean the same as v4; only type brands were added) | + +The only substantive v4→v5 difference is the two new lineage identity fields; the `ver/seq/val` row shape is identical across all three generations, and `seq` numbering did not change ([the 2026-08-31 seq/offset brands note](../../implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md) pins the on-disk numbers as unchanged). v3→v4 was a layout migration with identical record content. + +One derived shape also exists: a v3 home that ran the v5 build once (the poisoned state) — its new tree holds documents **stamped 5 whose content is a v3 record** (no lineage fields). + +## Proposal + +Declared read compatibility — reads tolerate vouched-for older versions, writes always stamp the current one: + +1. **`DomainSpec.compatibleVersions` (new, optional)**: the domain owner declares "records stored under these older versions are also readable under the current record schemas" (typically by declaring the fields old records lack as optional). `defineDomain` validates each entry as a non-negative integer below the current version; `descriptorOf` projects the set onto the backend `KvUnitDescriptor`. +2. **json backend per-record reads** accept version stamps in "current ∪ compatibleVersions"; anything outside the set is still discarded as foreign. **The write path always stamps the current version** (the first checkpoint after reading an old record naturally advances it). The `single` layout stays exact-version. +3. **Legacy-bootstrap version gate (the actual bug fix)**: the old whole-unit file's `unit.version` must fall inside the accepted set to be migrated; otherwise the file is left alone and the unit reads empty — stamping records the owner never vouched for turns a discardable stale cache into hard schema failures at the domain layer. +4. **The projcache domain declares `version: 5, compatibleVersions: [3, 4]`**, and the two lineage fields become `.optional()`. The single reader of stored identities, `identityMatches`, normalizes absence to the unseeded lineage (`?? false` / `?? 0`): exact for unforked sessions, while a forked session's expectation is seeded → natural mismatch → discard and cold rebuild, so the lineage binding loses none of its protection. +5. **The poisoned state self-heals**: documents stamped 5 without lineage fields parse under the optional schema (their content is the real pre-upgrade cache data), so the home boots again and titles serve immediately. +6. **Schema-validation backstop: `invalidRecords: 'backup-and-skip'` (declared by this domain only)**. A stored record that still fails to parse beyond read compatibility no longer refuses the whole domain: the domain layer calls the backend's `KvUnit.backupRecord` (json per-record implementation = rename the document to `.json.bak.`, bytes kept, never read again), prints the concrete failure with `logger.error` (domain, table, key, destination, zod cause), and continues the open with the record absent; the next cold read rebuilds and rewrites that session's cache. **The policy is an explicit per-domain declaration and the default stays fail-loud** — other domains still refuse the whole load on invalid stored data, and a backend without `backupRecord` (single layout, row stores) also falls back to fail-loud. Naming history: quarantine → backup-and-skip (user ruling: the word must carry both "back up" and "skip", sharing its root with the `.bak` suffix; skip-backup was rejected because the CLI `--skip-X` convention reads it as "do not back up"). + +### Upgrade matrix + +| home shape | behavior after the fix | +|---|---| +| v3 single-file (not poisoned) | bootstrap migrates (3 ∈ accepted set) → titles serve immediately | +| v3 + poisoned new tree | new-tree documents read directly (optional tolerance) → boot restored, titles serve immediately | +| v4 per-record | documents read directly (4 ∈ accepted set) → titles serve immediately | +| v5 healthy | unaffected | +| old records of forked (seeded) sessions | identity mismatch → discarded, cold rebuild when the session opens (safe side) | + +## Alternatives considered + +- **Discard-and-rebuild only** (bootstrap gate + bump to v6): fixes the boot, but every SessionList title is lost after the upgrade until each session is reopened — fails the upgrade-and-go product requirement. +- **Schema `.default()` fills**: behaviorally equivalent to optional + reader normalization, but bakes the "absent = unseeded" interpretation into the durable schema's output type; ruled for optional — the schema honestly describes every accepted on-disk shape and the interpretation lives at the consumer (user ruling, 2026-09-02). +- **Roll the domain version back 5→4**: the smallest diff (three lines), but breaks version monotonicity, depends on the "bootstrap skips no versions" bug itself, and drops every poisoned and healthy v5 home's cache. + +## Risks + +- A deployment routing this domain to the sqlite backend gets none of the tolerance: sqlite implements neither `compatibleVersions` nor `backupRecord`, so behavior degrades to the old strict-version semantics (a whole-unit version mismatch still refuses with `version-mismatch`; nothing loosens, nothing serves wrong values). Shipped compositions route this domain to json, so this stays a deployment-configuration risk only. +- The optional lineage fields widen what a current-version document may omit: a v5-stamped record stripped of its lineage decodes as unseeded. The identity match still refuses it for seeded callers, and the per-row `ver` guard still screens every value, so the residual exposure is an unseeded caller reading an unseeded-shaped record — the same trust extended to genuine pre-lineage records. +- `backupRecord` overwrites a same-minute backup of the same key (the newer bytes win); distinct minutes and distinct keys never collide. + +## Acceptance criteria + +- `storage-json` unit tests: compat-stamped reads / out-of-set discards / writes stamping current; legacy bootstrap migrating only accepted versions (including the migrated-documents-stamp-current assertion); `backupRecord` move / absent read / rewrite / closed guard. +- `storage-domain` unit tests: `compatibleVersions` / `invalidRecords` declaration validation; backup-and-skip falling back to fail-loud when the backend has no `backupRecord`. +- `session-projection-cache` unit tests: records without lineage fields serve unseeded sessions verbatim and are discarded for seeded ones. +- **Archived-fixture recovery tests** (`tests/fixtures.spec.ts` + `tests/fixtures/`): four media archives produced by the real released builds — `v3-single-unit.json` (the 0.1.1-rc.2 whole-unit file), `v4-session-doc.json` (0.1.2-alpha.3), `v5-session-doc.json` (current), `v5-lineageless-doc.json` (the unguarded bootstrap's poisoned shape, synthesized from the v3 record) — each opened through the real storage stack, asserting the listing serves the archived title and that a live write rewrites the document to the current version (v5 stamp + lineage fields + fresh value); plus the backup-and-skip behavior for a schema-failing record (boot survives, `.bak` lands, log is concrete, neighbor records unharmed). +- End-to-end acceptance: `scripts/releasefix/` (real old release artifacts building the v3 / v4 / poisoned homes; the SessionList RPC asserts titles restored verbatim). + +Future bump procedure: when a new version's shape can tolerate old records through "optional fields + reader normalization", add the old version to `compatibleVersions`; otherwise bump normally (discard and rebuild) and remove the no-longer-compatible versions from the set. Either way, the package README requires the bump to land with archived fixtures and tests proving the chosen disposition. diff --git a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md new file mode 100644 index 0000000000..4682c5fe47 --- /dev/null +++ b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md @@ -0,0 +1,69 @@ +# Agent Note: 投影缓存跨版本读兼容(session_projcache v3/v4/v5) + +Status: proposed + +[English](2026-09-02-projcache-cross-version-read-compat.md) | 中文 + +## 问题 + +`session_projcache` 存储域在已发布版本间演进了三代磁盘结构。升级后的 DSH_HOME 出现两类故障: + +- **v3 单文件 home 升级后启动硬失败**:per-record 布局的 legacy bootstrap 迁移旧单文件时不检查其 `unit.version`,把旧记录原样打上当前版本戳写入新树;domain 层开域时逐条 zod 校验,旧记录缺新增必填字段 → `invalid-record` → 整个域拒开 → 插件树加载失败。且 bootstrap 先写盘后校验,**首次启动即把坏文档永久写入新树**("投毒")——此后每次启动新树非空、连 legacy 路径都不再走,home 持续不可用。 +- **v4 per-record home 升级后列表丢标题**:v4 文档被版本戳检查静默丢弃(per-record 契约),SessionList 是零 I/O 纯缓存读,miss 后整行不带投影;标题要等每个会话被逐个重新打开后才恢复。 + +缓存域自身的契约是"过期或不可读的缓存只付出更长的尾部重放,绝不给出错值、绝不拒载"——硬失败与整体丢弃都违背该契约的前半句或产品预期。 + +## 三代磁盘结构差异 + +| domain version | 携带发布 | 布局 | 磁盘形态 | identity 字段 | 行字段 | +|---|---|---|---|---|---| +| 3 | 0.1.1-rc.2 | single | 单文件 `storages/session_projcache.json`(`{unit:{name,version}, global, tables}`) | `createdAt`, `cwd?` | `ver`, `seq`, `val` | +| 4 | 0.1.2-alpha.3 | per-record | 每会话一份 `storages/session_projcache/sessions/.json`(`{version, record}`) | `createdAt`, `cwd?` | 同上 | +| 5 | 0.1.2-alpha.4 | per-record | 同 v4 | + `isSeeded`(必填→本次改 optional)、`inheritedEventCount`(同) | 同上(`seq` 数值语义与 v4 相同,仅类型加 brand) | + +v4→v5 的唯一实质差异是 identity 新增两个 lineage 字段;行内 `ver/seq/val` 三代一致,`seq` 的数值含义未变([2026-08-31 seq/offset brands note](../../implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.zh.md) 明确 on-disk 数值不变)。v3→v4 是布局迁移,记录内容结构一致。 + +另有一种衍生形态:跑过一次 v5 版本的 v3 home(投毒态)——新树里存在**版本戳为 5 但内容是 v3 记录**(缺 lineage 字段)的文档。 + +## 提案 + +声明式读兼容——读容忍 owner 背书过的旧版本,写恒戳当前版本: + +1. **`DomainSpec.compatibleVersions`(新增,可选)**:域 owner 声明"这些旧版本的存量记录在当前记录 schema 下也可读"(典型手段:新增字段标 optional)。`defineDomain` 校验各项为小于当前 version 的非负整数;`descriptorOf` 透传到后端 `KvUnitDescriptor`。 +2. **json 后端 per-record 读**:接受"当前版本 ∪ compatibleVersions"内的版本戳,集合外照旧视为 foreign 丢弃;**写路径永远戳当前版本**(读到旧记录后的下一次 checkpoint 自然把它推进到当前版本)。single 布局维持 exact-version 不变。 +3. **legacy bootstrap 版本把关(bug 修复本体)**:旧单文件的 `unit.version` 必须落在接受集合内才迁移,否则视为空 unit 留在原地——为 owner 未背书的记录打当前版本戳,会把"可丢弃的过期缓存"变成 domain 层的 schema 硬失败。 +4. **projcache 域声明 `version: 5, compatibleVersions: [3, 4]`**;两个 lineage 字段改为 `.optional()`。唯一消费 stored identity 的读点 `identityMatches` 把缺失归一化为 unseeded lineage(`?? false` / `?? 0`):对非 fork 会话这是精确值;fork 会话的 expected 是 seeded → 天然 mismatch → 丢弃冷读重建,lineage 绑定的防护不放松。 +5. **投毒态自愈**:v5 戳缺 lineage 字段的文档被 optional schema 直接接受(内容本就是升级前的真实缓存数据),home 恢复可启动且标题立即可服务。 +6. **schema 校验兜底:`invalidRecords: 'backup-and-skip'`(仅本域声明)**。读兼容之外仍然解析失败的存量记录不再让整个域拒开:domain 层调用后端的 `KvUnit.backupRecord`(json per-record 实现=把文档改名为 `.json.bak.`,字节留档、不再被读取),用 `logger.error` 打印具体失败信息(域名、表、键、移动去向、zod 失败原因),随后当该记录不存在继续启动;下一次冷读会重建并重写该会话的缓存。**该策略是域级显式声明,缺省仍为 fail-loud**——其他业务域的存量数据校验失败照旧整域拒载;后端没有 `backupRecord` 能力(single 布局、行存储)时也回退 fail-loud。命名沿革:quarantine → backup-and-skip(用户裁决:词要同时含"备份"与"跳过"两义,且与 `.bak` 后缀同源;skip-backup 因 CLI `--skip-X` 惯例存在"不备份"反读而弃用)。 + +### 升级矩阵 + +| home 形态 | 修复后行为 | +|---|---| +| v3 单文件(未投毒) | bootstrap 迁移(3 ∈ 接受集)→ 标题立即可服务 | +| v3 + 投毒新树 | 新树文档直接读入(optional 容忍)→ 启动恢复、标题立即可服务 | +| v4 per-record | 文档直接读入(4 ∈ 接受集)→ 标题立即可服务 | +| v5 正常 | 不受影响 | +| fork(seeded)会话的旧记录 | identity mismatch → 丢弃,打开会话时冷读重建(安全侧) | + +## 备选方案 + +- **只丢弃重建**(bootstrap 把关 + bump v6):启动可修,但升级后 SessionList 标题全丢、要逐会话打开才恢复——不满足升级即用的产品要求。 +- **schema `.default()` 填缺省**:行为与 optional+读点归一化等价,但把"缺失=unseeded"的解释固化进 durable schema 的输出类型;拍板为 optional——schema 如实描述介质上所有被接受的形态,解释权在消费点(2026-09-02 用户裁决)。 +- **域版本回退 5→4**:改动最小(三行),但破坏版本单调性、依赖"bootstrap 不查版本"这个 bug 本身、且投毒态与正常 v5 home 的缓存全被丢弃。 + +## 风险 + +- 部署方若把本域路由到 sqlite 后端,得不到任何容忍能力:sqlite 既未实现 `compatibleVersions` 也没有 `backupRecord`,行为退化为原有的严格版本语义(整 unit 版本不匹配仍 `version-mismatch` 拒开;不放松、不出错值)。shipped 组合固定路由 json,此风险仅存在于部署配置层面。 +- optional lineage 字段放宽了当前版本文档可缺省的范围:被剥离 lineage 的 v5 戳记录会解码为 unseeded。身份比对仍会对 seeded 调用方拒收,逐行 `ver` 守卫仍筛查每个值,残余暴露面只是 unseeded 调用方读到 unseeded 形态的记录——与真实 pre-lineage 记录享有的信任完全相同。 +- `backupRecord` 对同一键的同一分钟内重复备份会覆盖前一份(新字节胜出);不同分钟、不同键永不冲突。 + +## 验收标准 + +- `storage-json` 单测:compat 版本戳读入/集合外丢弃/写恒当前版本;legacy bootstrap 仅在版本被接受时迁移(含迁移后文档戳当前版本断言);`backupRecord` 移档/读缺席/重写/封闭守卫。 +- `storage-domain` 单测:`compatibleVersions`/`invalidRecords` 声明校验;后端无 `backupRecord` 时 backup-and-skip 回退 fail-loud。 +- `session-projection-cache` 单测:缺 lineage 字段的记录对 unseeded 会话按原值服务、对 seeded 会话丢弃。 +- **归档 fixtures 独立恢复测试**(`tests/fixtures.spec.ts` + `tests/fixtures/`):真实发布物产出的四份介质存档——`v3-single-unit.json`(0.1.1-rc.2 整域单文件)、`v4-session-doc.json`(0.1.2-alpha.3)、`v5-session-doc.json`(当前版)、`v5-lineageless-doc.json`(无守卫 bootstrap 的投毒形态,由 v3 记录合成)——逐一走真实存储栈开域,断言列表读出归档标题、且 live 写把文档重写为当前版本(v5 戳 + lineage 字段 + 新值);外加 schema 失败记录的 backup-and-skip 行为(启动不失败、`.bak` 落盘、日志具体、邻居记录不受累)。 +- 端到端验收:`scripts/releasefix/`(真实老版本发布包构造 v3/v4/投毒三态 home,SessionList RPC 断言标题原样恢复)。 + +未来 bump 流程:新版本结构若可用"optional 字段 + 读点归一化"容忍旧记录,就把旧版本加入 `compatibleVersions`;否则正常 bump(丢弃重建),并把不再兼容的版本从集合中移除。无论哪条路,包 README 都要求 bump 随附归档 fixture 和论证所选处置方式的测试。 diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml index 1e9a7e221c..d234297a9d 100644 --- a/docs/subsystems/storage.i18n.yaml +++ b/docs/subsystems/storage.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/storage.md -storage.md: 1e4141e6ef1c6f8e1c2593e21e788b626d6b1ed7 -storage.zh.md: f0433c600674741c3de0ce3e99430297839ce124 +storage.md: e52f6d8869ee3092a5be99f0bd2873b410b45ed9 +storage.zh.md: f752862af9f10cfb32f39f2a1aa7801c922f841e diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md index 1e4141e6ef..e52f6d8869 100644 --- a/docs/subsystems/storage.md +++ b/docs/subsystems/storage.md @@ -65,6 +65,26 @@ interface DomainSpec { * (a stale record document is discarded, never migrated). */ readonly layout?: 'single' | 'per-record' + /** + * Older domain versions whose stored records the current record schemas + * also accept (the declaring owner vouches for that, typically by + * declaring the fields older records lack as optional). `per-record` backends + * read documents stamped with a listed version instead of discarding them, + * and accept a legacy whole-unit file so stamped for the one-time + * bootstrap; writes always stamp {@link version}. + */ + readonly compatibleVersions?: readonly number[] + /** + * What `open` does with a stored table record that fails its zod schema. + * Absent (the default), the whole open rejects with `invalid-record` — + * right for authoritative data. `'backup-and-skip'` is for domains whose + * records are disposable derived data: the backend moves the record's + * document aside (`KvUnit.backupRecord`), the failure is logged with + * its cause, and the open continues with the record absent. A backend + * without `backupRecord` (no per-record document to move) falls back + * to the rejecting default. The global slot always rejects. + */ + readonly invalidRecords?: 'backup-and-skip' /** Optional global singleton slot. */ readonly global?: DomainGlobalSpec /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */ @@ -180,7 +200,10 @@ The mounted domain facility. Opens declared domains over routed backends; one fa * (`facet-unsupported`); open the unit projected from the spec (backend * `version-mismatch`/`malformed-medium` pass through); load and validate * every stored record against the spec's zod schemas (`invalid-record` - * with the offending table and key); construct the domain. + * with the offending table and key — unless the spec declares + * `invalidRecords: 'backup-and-skip'` and the unit can move documents aside, in + * which case the failing record is backed up, logged, and skipped); + * construct the domain. * * Lifecycle: the CALLER owns the returned handle and closes it via * `Domain.close()` (typically as its own `ctx.effect` disposer) — the diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md index f0433c6006..f752862af9 100644 --- a/docs/subsystems/storage.zh.md +++ b/docs/subsystems/storage.zh.md @@ -65,6 +65,26 @@ interface DomainSpec { * (a stale record document is discarded, never migrated). */ readonly layout?: 'single' | 'per-record' + /** + * Older domain versions whose stored records the current record schemas + * also accept (the declaring owner vouches for that, typically by + * declaring the fields older records lack as optional). `per-record` backends + * read documents stamped with a listed version instead of discarding them, + * and accept a legacy whole-unit file so stamped for the one-time + * bootstrap; writes always stamp {@link version}. + */ + readonly compatibleVersions?: readonly number[] + /** + * What `open` does with a stored table record that fails its zod schema. + * Absent (the default), the whole open rejects with `invalid-record` — + * right for authoritative data. `'backup-and-skip'` is for domains whose + * records are disposable derived data: the backend moves the record's + * document aside (`KvUnit.backupRecord`), the failure is logged with + * its cause, and the open continues with the record absent. A backend + * without `backupRecord` (no per-record document to move) falls back + * to the rejecting default. The global slot always rejects. + */ + readonly invalidRecords?: 'backup-and-skip' /** Optional global singleton slot. */ readonly global?: DomainGlobalSpec /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */ @@ -180,7 +200,10 @@ The mounted domain facility. Opens declared domains over routed backends; one fa * (`facet-unsupported`); open the unit projected from the spec (backend * `version-mismatch`/`malformed-medium` pass through); load and validate * every stored record against the spec's zod schemas (`invalid-record` - * with the offending table and key); construct the domain. + * with the offending table and key — unless the spec declares + * `invalidRecords: 'backup-and-skip'` and the unit can move documents aside, in + * which case the failing record is backed up, logged, and skipped); + * construct the domain. * * Lifecycle: the CALLER owns the returned handle and closes it via * `Domain.close()` (typically as its own `ctx.effect` disposer) — the diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 55761bf933..3c81eb2b3b 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -2151,7 +2151,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ methods: [ { signature: 'async open(spec: S): Promise>', - description: 'Open one declared domain. Steps, each failing the whole call: reject a name that is already open (`already-open`); resolve the backend route (`backend-not-found` passes through from the hub); require its `kv` facet (`facet-unsupported`); open the unit projected from the spec (backend `version-mismatch`/`malformed-medium` pass through); load and validate every stored record against the spec\'s zod schemas (`invalid-record` with the offending table and key); construct the domain.\n\nLifecycle: the CALLER owns the returned handle and closes it via `Domain.close()` (typically as its own `ctx.effect` disposer) — the facility does not tie the domain to any consumer fiber. Domains still open when the facility unmounts are closed by the plugin disposer.', + description: 'Open one declared domain. Steps, each failing the whole call: reject a name that is already open (`already-open`); resolve the backend route (`backend-not-found` passes through from the hub); require its `kv` facet (`facet-unsupported`); open the unit projected from the spec (backend `version-mismatch`/`malformed-medium` pass through); load and validate every stored record against the spec\'s zod schemas (`invalid-record` with the offending table and key — unless the spec declares `invalidRecords: \'backup-and-skip\'` and the unit can move documents aside, in which case the failing record is backed up, logged, and skipped); construct the domain.\n\nLifecycle: the CALLER owns the returned handle and closes it via `Domain.close()` (typically as its own `ctx.effect` disposer) — the facility does not tie the domain to any consumer fiber. Domains still open when the facility unmounts are closed by the plugin disposer.', parameters: [{ name: 'spec', description: 'The domain declaration, typically from `defineDomain`.' }], returns: 'the opened domain handle, typed by the spec.', }, @@ -3956,7 +3956,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'DomainSpec', - declaration: 'export interface DomainSpec {\n readonly name: string;\n readonly version: number;\n readonly layout?: \'single\' | \'per-record\';\n readonly global?: DomainGlobalSpec;\n readonly tables: Record;\n}', + declaration: 'export interface DomainSpec {\n readonly name: string;\n readonly version: number;\n readonly layout?: \'single\' | \'per-record\';\n readonly compatibleVersions?: readonly number[];\n readonly invalidRecords?: \'backup-and-skip\';\n readonly global?: DomainGlobalSpec;\n readonly tables: Record;\n}', }, { name: 'DomainTableSpec', @@ -4264,11 +4264,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'KvUnit', - declaration: 'export interface KvUnit {\n loadAll(): Promise<{\n tables: Record>;\n global: unknown;\n }>;\n putRecord(table: string, key: string, value: unknown): Promise;\n deleteRecord(table: string, key: string): Promise;\n setGlobal(value: unknown): Promise;\n close(): Promise;\n}', + declaration: 'export interface KvUnit {\n loadAll(): Promise<{\n tables: Record>;\n global: unknown;\n }>;\n putRecord(table: string, key: string, value: unknown): Promise;\n deleteRecord(table: string, key: string): Promise;\n backupRecord?(table: string, key: string): Promise;\n setGlobal(value: unknown): Promise;\n close(): Promise;\n}', }, { name: 'KvUnitDescriptor', - declaration: 'export interface KvUnitDescriptor {\n readonly name: string;\n readonly version: number;\n readonly tables: readonly string[];\n readonly hasGlobal: boolean;\n readonly layout?: \'single\' | \'per-record\';\n}', + declaration: 'export interface KvUnitDescriptor {\n readonly name: string;\n readonly version: number;\n readonly tables: readonly string[];\n readonly hasGlobal: boolean;\n readonly layout?: \'single\' | \'per-record\';\n readonly compatibleVersions?: readonly number[];\n}', }, { name: 'LlmAdapter', diff --git a/packages/session/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml index e4fe8490a2..4dd1489d4e 100644 --- a/packages/session/session-projection-cache/README.i18n.yaml +++ b/packages/session/session-projection-cache/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/session/session-projection-cache/README.md -README.md: 51b9d86724af96304cf09a5c7c1b61b7394d336a -README.zh.md: bb84b67bdde678884fd4f2be1b14b2161da8c2a0 +README.md: 9fd9766d75ab3f9a460b2802ac59810839f21ae4 +README.zh.md: 98725d9ce76ab44821adf3d43e3807932cf6b675 diff --git a/packages/session/session-projection-cache/README.md b/packages/session/session-projection-cache/README.md index 51b9d86724..9fd9766d75 100644 --- a/packages/session/session-projection-cache/README.md +++ b/packages/session/session-projection-cache/README.md @@ -64,6 +64,8 @@ Three mandatory points always write: session creation persists the seed-derived The log leads and the cache follows: a live checkpoint flushes the session's buffered events durably before the cache row lands, so a crash can leave the cache behind the log but never ahead of it. Reads and writes share the storage domain's coherent in-memory state; the per-unit write chain mutates memory only after durability. Each version-stamped record must match the live unit schema and complete lifecycle identity (`createdAt`, `cwd`, `isSeeded`, and `inheritedEventCount`), so a row initialized under one fork cut cannot seed another. The JSON backend stores each record at `/session_projcache/sessions/.json` in an owner-only directory tree. +Upgrades never cost the boot or the listing: records stamped with a version in the spec's `compatibleVersions` stay readable (their absent lineage fields decode as the unseeded lineage — exact for unseeded sessions, while a seeded caller fails the identity match and refolds cold), and a stored record that still fails schema validation is moved aside as `.json.bak.` under the domain's `invalidRecords: 'backup-and-skip'` policy, logged with its cause, and rebuilt by the next checkpoint. + ----- @@ -126,6 +128,7 @@ These limits define where the cache needs operational care. They are current pac - **No eviction or retention surface** — records accumulate per session; pruning stored checkpoints is out-of-band maintenance, same stance as session persistence itself. - **Interval throttle is per-session coarse** — the timer arms at the first dirty event after a clean write; a steady sub-threshold trickle writes once per interval, not a sliding window. - **No cache-side cold refold** — the cache serves and refreshes its rows but never reads the session log (it does not depend on the persistence layer); a consumer that needs a guaranteed cold snapshot refolds from the log itself. +- **Every schema or domain-version change must prove its upgrade story** — a change to the stored record schema or the domain version lands in the same PR with an archived fixture of the previously shipped on-disk format under `tests/fixtures/` and test cases in `tests/fixtures.spec.ts` proving the chosen disposition: read-compat recovery (`compatibleVersions`), current-version rewrite, or backup-and-skip salvage. A bump whose old records are simply discarded still proves that the discard neither fails the boot nor poisons the tree. ### Dev Note diff --git a/packages/session/session-projection-cache/README.zh.md b/packages/session/session-projection-cache/README.zh.md index bb84b67bdd..98725d9ce7 100644 --- a/packages/session/session-projection-cache/README.zh.md +++ b/packages/session/session-projection-cache/README.zh.md @@ -64,6 +64,8 @@ kind: "package-reference" 日志领先,缓存跟随:实时检查点先把会话的缓冲事件持久化,然后才保存缓存记录。因此崩溃可能让缓存落后于日志,但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态;逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与完整生命周期身份(`createdAt`、`cwd`、`isSeeded` 和 `inheritedEventCount`),因此在一个 fork 切点下初始化的行不能播种另一个切点。JSON 后端把每条记录存于仅所有者可访问的 `/session_projcache/sessions/.json` 目录树中。 +升级绝不拖垮启动或列表:版本戳落在 spec `compatibleVersions` 集合内的记录保持可读(缺失的 lineage 字段解码为 unseeded lineage——对非 fork 会话精确无误,seeded 调用方则通不过身份比对、回落冷折叠),而仍然通不过 schema 校验的存量记录会按域的 `invalidRecords: 'backup-and-skip'` 策略移出为 `.json.bak.<时间戳>`、连同原因写入日志,并由下一次检查点重建。 + ----- @@ -126,6 +128,7 @@ kind: "package-reference" - **无淘汰或保留接口**——记录按会话持续累积;清理已存储检查点属于带外维护,与会话持久化采用相同策略。 - **间隔节流采用按会话的粗粒度控制**——一次无脏数据的写入完成后,计时器在首个脏事件到达时启动;持续但低于条数阈值的事件流每间隔写入一次,而非滑动窗口。 - **缓存侧不做冷重折叠**——缓存只服务并刷新自己的记录,从不读取会话日志,因为它不依赖持久化层;需要保证冷快照的消费方自行从日志重新折叠。 +- **每次 schema 或域版本变更都必须论证升级路径**——改动存储记录 schema 或域版本时,同一 PR 必须在 `tests/fixtures/` 下归档此前已发布的磁盘格式样本,并在 `tests/fixtures.spec.ts` 中用测试论证所选的处置方式:读兼容恢复(`compatibleVersions`)、当前版本重写,或 backup-and-skip 抢救。即便选择直接丢弃旧记录的 bump,也要证明丢弃既不炸启动、也不污染缓存树。 ### 开发备注 From db2dd2f840a3a82f3a5d4f1193aa5a7a61c12f51 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:42:35 +0800 Subject: [PATCH 7/8] docs(session-projection-cache): land the read-compat note as implemented and state fixture provenance in place Review follow-ups: the Agent Note triplet moves to implemented/ rewritten as shipped state (Decision/Consequences/Testing, present tense), cross-linked both ways with the 2026-07-28 storage recovery proposal whose projcache reset/destroy path it supersedes (that proposal stays live for authoritative and whole-medium damage). The fixtures spec header and the note state the fixture provenance as recorded facts of the released builds instead of citing local tooling, and the spec JSDoc points at the note's final home. --- ...projcache-cross-version-read-compat.i18n.yaml | 6 ++++++ ...-09-02-projcache-cross-version-read-compat.md | 16 ++++++++-------- ...-02-projcache-cross-version-read-compat.zh.md | 16 ++++++++-------- ...ge-root-and-derived-medium-recovery.i18n.yaml | 4 ++-- ...8-storage-root-and-derived-medium-recovery.md | 2 +- ...torage-root-and-derived-medium-recovery.zh.md | 2 +- ...projcache-cross-version-read-compat.i18n.yaml | 6 ------ .../session/session-projection-cache/src/spec.ts | 2 +- .../tests/fixtures.spec.ts | 16 +++++++++------- 9 files changed, 36 insertions(+), 34 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml rename .agents/notes/{proposed => implemented}/architecture/2026-09-02-projcache-cross-version-read-compat.md (88%) rename .agents/notes/{proposed => implemented}/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md (87%) delete mode 100644 .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml diff --git a/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml new file mode 100644 index 0000000000..78edca4d40 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md +2026-09-02-projcache-cross-version-read-compat.md: 64b52ba482e5850e1d0c3d473ca87ba7822af67f +2026-09-02-projcache-cross-version-read-compat.zh.md: c8adad9fd2b7184418a4da44e8b2e5d1f31feed7 diff --git a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md b/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md similarity index 88% rename from .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md rename to .agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md index 9bd0cd9049..64b52ba482 100644 --- a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md +++ b/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md @@ -1,6 +1,6 @@ # Agent Note: Projection-cache cross-version read compatibility (session_projcache v3/v4/v5) -Status: proposed +Status: implemented English | [中文](2026-09-02-projcache-cross-version-read-compat.zh.md) @@ -19,13 +19,13 @@ The cache domain's own contract is "a stale or unreadable cache costs a longer t |---|---|---|---|---|---| | 3 | 0.1.1-rc.2 | single | one file `storages/session_projcache.json` (`{unit:{name,version}, global, tables}`) | `createdAt`, `cwd?` | `ver`, `seq`, `val` | | 4 | 0.1.2-alpha.3 | per-record | one file per session `storages/session_projcache/sessions/.json` (`{version, record}`) | `createdAt`, `cwd?` | same | -| 5 | 0.1.2-alpha.4 | per-record | same as v4 | + `isSeeded` (required → optional in this change), `inheritedEventCount` (same) | same (`seq` numbers mean the same as v4; only type brands were added) | +| 5 | 0.1.2-alpha.4 | per-record | same as v4 | + `isSeeded` (shipped required; now optional), `inheritedEventCount` (same) | same (`seq` numbers mean the same as v4; only type brands were added) | -The only substantive v4→v5 difference is the two new lineage identity fields; the `ver/seq/val` row shape is identical across all three generations, and `seq` numbering did not change ([the 2026-08-31 seq/offset brands note](../../implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.md) pins the on-disk numbers as unchanged). v3→v4 was a layout migration with identical record content. +The only substantive v4→v5 difference is the two new lineage identity fields; the `ver/seq/val` row shape is identical across all three generations, and `seq` numbering did not change ([the 2026-08-31 seq/offset brands note](2026-08-31-session-sequence-and-log-offset-brands.md) pins the on-disk numbers as unchanged). v3→v4 was a layout migration with identical record content. One derived shape also exists: a v3 home that ran the v5 build once (the poisoned state) — its new tree holds documents **stamped 5 whose content is a v3 record** (no lineage fields). -## Proposal +## Decision Declared read compatibility — reads tolerate vouched-for older versions, writes always stamp the current one: @@ -34,7 +34,7 @@ Declared read compatibility — reads tolerate vouched-for older versions, write 3. **Legacy-bootstrap version gate (the actual bug fix)**: the old whole-unit file's `unit.version` must fall inside the accepted set to be migrated; otherwise the file is left alone and the unit reads empty — stamping records the owner never vouched for turns a discardable stale cache into hard schema failures at the domain layer. 4. **The projcache domain declares `version: 5, compatibleVersions: [3, 4]`**, and the two lineage fields become `.optional()`. The single reader of stored identities, `identityMatches`, normalizes absence to the unseeded lineage (`?? false` / `?? 0`): exact for unforked sessions, while a forked session's expectation is seeded → natural mismatch → discard and cold rebuild, so the lineage binding loses none of its protection. 5. **The poisoned state self-heals**: documents stamped 5 without lineage fields parse under the optional schema (their content is the real pre-upgrade cache data), so the home boots again and titles serve immediately. -6. **Schema-validation backstop: `invalidRecords: 'backup-and-skip'` (declared by this domain only)**. A stored record that still fails to parse beyond read compatibility no longer refuses the whole domain: the domain layer calls the backend's `KvUnit.backupRecord` (json per-record implementation = rename the document to `.json.bak.`, bytes kept, never read again), prints the concrete failure with `logger.error` (domain, table, key, destination, zod cause), and continues the open with the record absent; the next cold read rebuilds and rewrites that session's cache. **The policy is an explicit per-domain declaration and the default stays fail-loud** — other domains still refuse the whole load on invalid stored data, and a backend without `backupRecord` (single layout, row stores) also falls back to fail-loud. Naming history: quarantine → backup-and-skip (user ruling: the word must carry both "back up" and "skip", sharing its root with the `.bak` suffix; skip-backup was rejected because the CLI `--skip-X` convention reads it as "do not back up"). +6. **Schema-validation backstop: `invalidRecords: 'backup-and-skip'` (declared by this domain only)**. A stored record that still fails to parse beyond read compatibility no longer refuses the whole domain: the domain layer calls the backend's `KvUnit.backupRecord` (json per-record implementation = rename the document to `.json.bak.`, bytes kept, never read again), prints the concrete failure with `logger.error` (domain, table, key, destination, zod cause), and continues the open with the record absent; the next cold read rebuilds and rewrites that session's cache. **The policy is an explicit per-domain declaration and the default stays fail-loud** — other domains still refuse the whole load on invalid stored data, and a backend without `backupRecord` (single layout, row stores) also falls back to fail-loud. Naming history: quarantine → backup-and-skip (user ruling: the word must carry both "back up" and "skip", sharing its root with the `.bak` suffix; skip-backup was rejected because the CLI `--skip-X` convention reads it as "do not back up"). For this domain it supersedes the reset/destroy recovery path of the [2026-07-28 storage recovery proposal](../../proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md), which stays live for authoritative and whole-medium damage. ### Upgrade matrix @@ -52,18 +52,18 @@ Declared read compatibility — reads tolerate vouched-for older versions, write - **Schema `.default()` fills**: behaviorally equivalent to optional + reader normalization, but bakes the "absent = unseeded" interpretation into the durable schema's output type; ruled for optional — the schema honestly describes every accepted on-disk shape and the interpretation lives at the consumer (user ruling, 2026-09-02). - **Roll the domain version back 5→4**: the smallest diff (three lines), but breaks version monotonicity, depends on the "bootstrap skips no versions" bug itself, and drops every poisoned and healthy v5 home's cache. -## Risks +## Consequences - A deployment routing this domain to the sqlite backend gets none of the tolerance: sqlite implements neither `compatibleVersions` nor `backupRecord`, so behavior degrades to the old strict-version semantics (a whole-unit version mismatch still refuses with `version-mismatch`; nothing loosens, nothing serves wrong values). Shipped compositions route this domain to json, so this stays a deployment-configuration risk only. - The optional lineage fields widen what a current-version document may omit: a v5-stamped record stripped of its lineage decodes as unseeded. The identity match still refuses it for seeded callers, and the per-row `ver` guard still screens every value, so the residual exposure is an unseeded caller reading an unseeded-shaped record — the same trust extended to genuine pre-lineage records. - `backupRecord` overwrites a same-minute backup of the same key (the newer bytes win); distinct minutes and distinct keys never collide. -## Acceptance criteria +## Testing - `storage-json` unit tests: compat-stamped reads / out-of-set discards / writes stamping current; legacy bootstrap migrating only accepted versions (including the migrated-documents-stamp-current assertion); `backupRecord` move / absent read / rewrite / closed guard. - `storage-domain` unit tests: `compatibleVersions` / `invalidRecords` declaration validation; backup-and-skip falling back to fail-loud when the backend has no `backupRecord`. - `session-projection-cache` unit tests: records without lineage fields serve unseeded sessions verbatim and are discarded for seeded ones. - **Archived-fixture recovery tests** (`tests/fixtures.spec.ts` + `tests/fixtures/`): four media archives produced by the real released builds — `v3-single-unit.json` (the 0.1.1-rc.2 whole-unit file), `v4-session-doc.json` (0.1.2-alpha.3), `v5-session-doc.json` (current), `v5-lineageless-doc.json` (the unguarded bootstrap's poisoned shape, synthesized from the v3 record) — each opened through the real storage stack, asserting the listing serves the archived title and that a live write rewrites the document to the current version (v5 stamp + lineage fields + fresh value); plus the backup-and-skip behavior for a schema-failing record (boot survives, `.bak` lands, log is concrete, neighbor records unharmed). -- End-to-end acceptance: `scripts/releasefix/` (real old release artifacts building the v3 / v4 / poisoned homes; the SessionList RPC asserts titles restored verbatim). +- End-to-end acceptance, executed against the real release artifacts: the published 0.1.1-rc.2 and 0.1.2-alpha.3 npm builds seeded homes through their own web apps (model turns plus a rename RPC), the published 0.1.2-alpha.4 build reproduced both failures (including the poisoned tree), and the fixed build served every home shape — pristine v3, poisoned v3, v4, and fresh — with the SessionList RPC returning the recorded titles verbatim. Future bump procedure: when a new version's shape can tolerate old records through "optional fields + reader normalization", add the old version to `compatibleVersions`; otherwise bump normally (discard and rebuild) and remove the no-longer-compatible versions from the set. Either way, the package README requires the bump to land with archived fixtures and tests proving the chosen disposition. diff --git a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md b/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md similarity index 87% rename from .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md rename to .agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md index 4682c5fe47..c8adad9fd2 100644 --- a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md @@ -1,6 +1,6 @@ # Agent Note: 投影缓存跨版本读兼容(session_projcache v3/v4/v5) -Status: proposed +Status: implemented [English](2026-09-02-projcache-cross-version-read-compat.md) | 中文 @@ -19,13 +19,13 @@ Status: proposed |---|---|---|---|---|---| | 3 | 0.1.1-rc.2 | single | 单文件 `storages/session_projcache.json`(`{unit:{name,version}, global, tables}`) | `createdAt`, `cwd?` | `ver`, `seq`, `val` | | 4 | 0.1.2-alpha.3 | per-record | 每会话一份 `storages/session_projcache/sessions/.json`(`{version, record}`) | `createdAt`, `cwd?` | 同上 | -| 5 | 0.1.2-alpha.4 | per-record | 同 v4 | + `isSeeded`(必填→本次改 optional)、`inheritedEventCount`(同) | 同上(`seq` 数值语义与 v4 相同,仅类型加 brand) | +| 5 | 0.1.2-alpha.4 | per-record | 同 v4 | + `isSeeded`(v5 首发必填;现为 optional)、`inheritedEventCount`(同前) | 同上(`seq` 数值语义与 v4 相同,仅类型加 brand) | -v4→v5 的唯一实质差异是 identity 新增两个 lineage 字段;行内 `ver/seq/val` 三代一致,`seq` 的数值含义未变([2026-08-31 seq/offset brands note](../../implemented/architecture/2026-08-31-session-sequence-and-log-offset-brands.zh.md) 明确 on-disk 数值不变)。v3→v4 是布局迁移,记录内容结构一致。 +v4→v5 的唯一实质差异是 identity 新增两个 lineage 字段;行内 `ver/seq/val` 三代一致,`seq` 的数值含义未变([2026-08-31 seq/offset brands note](2026-08-31-session-sequence-and-log-offset-brands.zh.md) 明确 on-disk 数值不变)。v3→v4 是布局迁移,记录内容结构一致。 另有一种衍生形态:跑过一次 v5 版本的 v3 home(投毒态)——新树里存在**版本戳为 5 但内容是 v3 记录**(缺 lineage 字段)的文档。 -## 提案 +## 决策 声明式读兼容——读容忍 owner 背书过的旧版本,写恒戳当前版本: @@ -34,7 +34,7 @@ v4→v5 的唯一实质差异是 identity 新增两个 lineage 字段;行内 ` 3. **legacy bootstrap 版本把关(bug 修复本体)**:旧单文件的 `unit.version` 必须落在接受集合内才迁移,否则视为空 unit 留在原地——为 owner 未背书的记录打当前版本戳,会把"可丢弃的过期缓存"变成 domain 层的 schema 硬失败。 4. **projcache 域声明 `version: 5, compatibleVersions: [3, 4]`**;两个 lineage 字段改为 `.optional()`。唯一消费 stored identity 的读点 `identityMatches` 把缺失归一化为 unseeded lineage(`?? false` / `?? 0`):对非 fork 会话这是精确值;fork 会话的 expected 是 seeded → 天然 mismatch → 丢弃冷读重建,lineage 绑定的防护不放松。 5. **投毒态自愈**:v5 戳缺 lineage 字段的文档被 optional schema 直接接受(内容本就是升级前的真实缓存数据),home 恢复可启动且标题立即可服务。 -6. **schema 校验兜底:`invalidRecords: 'backup-and-skip'`(仅本域声明)**。读兼容之外仍然解析失败的存量记录不再让整个域拒开:domain 层调用后端的 `KvUnit.backupRecord`(json per-record 实现=把文档改名为 `.json.bak.`,字节留档、不再被读取),用 `logger.error` 打印具体失败信息(域名、表、键、移动去向、zod 失败原因),随后当该记录不存在继续启动;下一次冷读会重建并重写该会话的缓存。**该策略是域级显式声明,缺省仍为 fail-loud**——其他业务域的存量数据校验失败照旧整域拒载;后端没有 `backupRecord` 能力(single 布局、行存储)时也回退 fail-loud。命名沿革:quarantine → backup-and-skip(用户裁决:词要同时含"备份"与"跳过"两义,且与 `.bak` 后缀同源;skip-backup 因 CLI `--skip-X` 惯例存在"不备份"反读而弃用)。 +6. **schema 校验兜底:`invalidRecords: 'backup-and-skip'`(仅本域声明)**。读兼容之外仍然解析失败的存量记录不再让整个域拒开:domain 层调用后端的 `KvUnit.backupRecord`(json per-record 实现=把文档改名为 `.json.bak.`,字节留档、不再被读取),用 `logger.error` 打印具体失败信息(域名、表、键、移动去向、zod 失败原因),随后当该记录不存在继续启动;下一次冷读会重建并重写该会话的缓存。**该策略是域级显式声明,缺省仍为 fail-loud**——其他业务域的存量数据校验失败照旧整域拒载;后端没有 `backupRecord` 能力(single 布局、行存储)时也回退 fail-loud。命名沿革:quarantine → backup-and-skip(用户裁决:词要同时含"备份"与"跳过"两义,且与 `.bak` 后缀同源;skip-backup 因 CLI `--skip-X` 惯例存在"不备份"反读而弃用)。对本域而言,该策略取代了 [2026-07-28 存储恢复提案](../../proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md)中 reset/destroy 的恢复途径;该提案对权威介质与整介质损坏仍然有效。 ### 升级矩阵 @@ -52,18 +52,18 @@ v4→v5 的唯一实质差异是 identity 新增两个 lineage 字段;行内 ` - **schema `.default()` 填缺省**:行为与 optional+读点归一化等价,但把"缺失=unseeded"的解释固化进 durable schema 的输出类型;拍板为 optional——schema 如实描述介质上所有被接受的形态,解释权在消费点(2026-09-02 用户裁决)。 - **域版本回退 5→4**:改动最小(三行),但破坏版本单调性、依赖"bootstrap 不查版本"这个 bug 本身、且投毒态与正常 v5 home 的缓存全被丢弃。 -## 风险 +## 影响 - 部署方若把本域路由到 sqlite 后端,得不到任何容忍能力:sqlite 既未实现 `compatibleVersions` 也没有 `backupRecord`,行为退化为原有的严格版本语义(整 unit 版本不匹配仍 `version-mismatch` 拒开;不放松、不出错值)。shipped 组合固定路由 json,此风险仅存在于部署配置层面。 - optional lineage 字段放宽了当前版本文档可缺省的范围:被剥离 lineage 的 v5 戳记录会解码为 unseeded。身份比对仍会对 seeded 调用方拒收,逐行 `ver` 守卫仍筛查每个值,残余暴露面只是 unseeded 调用方读到 unseeded 形态的记录——与真实 pre-lineage 记录享有的信任完全相同。 - `backupRecord` 对同一键的同一分钟内重复备份会覆盖前一份(新字节胜出);不同分钟、不同键永不冲突。 -## 验收标准 +## 测试 - `storage-json` 单测:compat 版本戳读入/集合外丢弃/写恒当前版本;legacy bootstrap 仅在版本被接受时迁移(含迁移后文档戳当前版本断言);`backupRecord` 移档/读缺席/重写/封闭守卫。 - `storage-domain` 单测:`compatibleVersions`/`invalidRecords` 声明校验;后端无 `backupRecord` 时 backup-and-skip 回退 fail-loud。 - `session-projection-cache` 单测:缺 lineage 字段的记录对 unseeded 会话按原值服务、对 seeded 会话丢弃。 - **归档 fixtures 独立恢复测试**(`tests/fixtures.spec.ts` + `tests/fixtures/`):真实发布物产出的四份介质存档——`v3-single-unit.json`(0.1.1-rc.2 整域单文件)、`v4-session-doc.json`(0.1.2-alpha.3)、`v5-session-doc.json`(当前版)、`v5-lineageless-doc.json`(无守卫 bootstrap 的投毒形态,由 v3 记录合成)——逐一走真实存储栈开域,断言列表读出归档标题、且 live 写把文档重写为当前版本(v5 戳 + lineage 字段 + 新值);外加 schema 失败记录的 backup-and-skip 行为(启动不失败、`.bak` 落盘、日志具体、邻居记录不受累)。 -- 端到端验收:`scripts/releasefix/`(真实老版本发布包构造 v3/v4/投毒三态 home,SessionList RPC 断言标题原样恢复)。 +- 端到端验收,以真实发布物执行:已发布的 0.1.1-rc.2 与 0.1.2-alpha.3 npm 包经各自 web app 造数(真实模型对话 + rename RPC),已发布的 0.1.2-alpha.4 包复现两类故障(含投毒树),修复后构建对纯净 v3、投毒 v3、v4、全新四种 home 形态经 SessionList RPC 原样返回记录在案的标题。 未来 bump 流程:新版本结构若可用"optional 字段 + 读点归一化"容忍旧记录,就把旧版本加入 `compatibleVersions`;否则正常 bump(丢弃重建),并把不再兼容的版本从集合中移除。无论哪条路,包 README 都要求 bump 随附归档 fixture 和论证所选处置方式的测试。 diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml index ea0fe4b44b..96ea4961d6 100644 --- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml +++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md -2026-07-28-storage-root-and-derived-medium-recovery.md: 1505be1c58d5cf829327b2919113bb2e42798ce7 -2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 1bab5ab663df1419cc826c3d6acb59bd8bff7de0 +2026-07-28-storage-root-and-derived-medium-recovery.md: 68a6792c38a8fe097558de3d5a857ab4ea0d3533 +2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 0c712b3b928f4b3df44e706b154c3a90a784403c diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md index 1505be1c58..68a6792c38 100644 --- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md +++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md @@ -10,7 +10,7 @@ The persisted projection cache ([note](2026-07-27-session-projection-and-command **Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session/session-persistence-jsonl/src/index.ts). -**Recovery behavior.** Inside a healthy medium the cache is fully self-healing by design: a `stateVersion`-mismatched row is discarded and refolded, a log shrunk below a row's watermark is detected by the anchored restore floor and answered with one full re-read, and every background write is fail-soft. But at the *medium* level there is no recovery at all: a truncated, hand-edited, or version-bumped `session_projcache.json` fails `openJsonUnit` with `malformed-medium`/`version-mismatch` (packages/storage/storage-json/src/format.ts), a schema-drifted record fails domain open with `invalid-record` (packages/storage/storage-domain/src/index.ts), the rejection propagates through `SessionProjectionCache[Service.init]`, and under the CLI's fail-loud boot the assembly refuses to start. A file whose entire content is rebuildable from session logs can brick boot. This contradicts the cache package's own stated stance ("a stale or unreadable cache costs a longer tail replay, never a wrong value") and the cache domain spec's JSDoc ("version bumps discard the whole medium"), which describes an aspiration, not the implementation. Partially superseded for the projection cache: [the per-session cache files note](../../implemented/architecture/2026-08-19-projection-cache-per-session-files.md) removed the global `session_projcache` domain, so the cache half of this proposal (recovery on that domain) no longer applies; the `workspace.json` half remains current. The same fail-loud path is *correct* for `workspace.json` — workspace records are authoritative, not derivable — so the missing concept is a per-domain declaration of authority, not a global behavior change. +**Recovery behavior.** Inside a healthy medium the cache is fully self-healing by design: a `stateVersion`-mismatched row is discarded and refolded, a log shrunk below a row's watermark is detected by the anchored restore floor and answered with one full re-read, and every background write is fail-soft. But at the *medium* level there is no recovery at all: a truncated, hand-edited, or version-bumped `session_projcache.json` fails `openJsonUnit` with `malformed-medium`/`version-mismatch` (packages/storage/storage-json/src/format.ts), a schema-drifted record fails domain open with `invalid-record` (packages/storage/storage-domain/src/index.ts), the rejection propagates through `SessionProjectionCache[Service.init]`, and under the CLI's fail-loud boot the assembly refuses to start. A file whose entire content is rebuildable from session logs can brick boot. This contradicts the cache package's own stated stance ("a stale or unreadable cache costs a longer tail replay, never a wrong value") and the cache domain spec's JSDoc ("version bumps discard the whole medium"), which describes an aspiration, not the implementation. Partially superseded for the projection cache: [the per-session cache files note](../../implemented/architecture/2026-08-19-projection-cache-per-session-files.md) removed the global `session_projcache` domain, so the cache half of this proposal (recovery on that domain) no longer applies; the `workspace.json` half remains current. The `invalid-record` class for the per-record projection cache is now also superseded: the shipped domain declares `invalidRecords: 'backup-and-skip'` ([cross-version read-compat note](../../implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md)), which backs the failing record up and skips it at open, so the reset/destroy proposal below stays relevant only for whole-medium damage on authoritative or single-document media. The same fail-loud path is *correct* for `workspace.json` — workspace records are authoritative, not derivable — so the missing concept is a per-domain declaration of authority, not a global behavior change. ## Proposal diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md index 1bab5ab663..0c712b3b92 100644 --- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md +++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md @@ -10,7 +10,7 @@ Status: proposed **文件到底存在哪(根错位已收口,resolve-once 残余仍开放)。** 共享 base 将会话存储默认为全局 harness home(`$DSH_HOME/sessions`,默认 `~/.dsh/sessions`),而出厂 Web overlay 曾给 json 后端相对根 `./.storages`:`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动,会话相同,工作区注册表和投影缓存却各是一份,而缓存存在的意义恰恰是跨会话冷列表,凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除:overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`(`apps/cli/config/web.cordis.yml`)。残余隐患:`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上(packages/storage/storage-json/src/index.ts);出厂 overlay 的根已是绝对路径不受影响,但任何相对根(裸 Loader 启动、测试)仍会被后续 cwd 变化劈开,JSONL 会话后端用「构造时 resolve 一次」防住的正是它("later process.cwd() changes cannot split one backend across roots",packages/session/session-persistence-jsonl/src/index.ts)。 -**恢复行为。** 在健康介质内部,缓存按设计完全自愈:`stateVersion` 不匹配的行被丢弃重折,日志缩短到行水位以下由带锚的 restore floor 检出并以一次全量重读回答,每次后台写都是 fail-soft。但在*介质*层面完全没有恢复:被截断、被手改或版本被 bump 的 `session_projcache.json` 会让 `openJsonUnit` 以 `malformed-medium`/`version-mismatch` 失败(packages/storage/storage-json/src/format.ts),schema 漂移的记录让域 open 以 `invalid-record` 失败(packages/storage/storage-domain/src/index.ts),拒绝一路穿过 `SessionProjectionCache[Service.init]`,在 CLI 的 fail-loud 启动下整个组装拒绝启动。一个内容完全可从会话日志重建的文件能把启动搞死。这与缓存包自己声明的立场("a stale or unreadable cache costs a longer tail replay, never a wrong value")和缓存域 spec 的 JSDoc("version bumps discard the whole medium")相矛盾——后者描述的是愿望而非实现。投影缓存半边已被[每会话缓存文件 note](../../implemented/architecture/2026-08-19-projection-cache-per-session-files.zh.md) 部分取代:全局 `session_projcache` domain 已移除,本提案的缓存恢复半边不再适用;`workspace.json` 半边仍然有效。同一条 fail-loud 路径对 `workspace.json` 却是*正确*的——工作区记录是权威数据,不可派生——所以缺的概念是按域声明权威性,而不是全局改行为。 +**恢复行为。** 在健康介质内部,缓存按设计完全自愈:`stateVersion` 不匹配的行被丢弃重折,日志缩短到行水位以下由带锚的 restore floor 检出并以一次全量重读回答,每次后台写都是 fail-soft。但在*介质*层面完全没有恢复:被截断、被手改或版本被 bump 的 `session_projcache.json` 会让 `openJsonUnit` 以 `malformed-medium`/`version-mismatch` 失败(packages/storage/storage-json/src/format.ts),schema 漂移的记录让域 open 以 `invalid-record` 失败(packages/storage/storage-domain/src/index.ts),拒绝一路穿过 `SessionProjectionCache[Service.init]`,在 CLI 的 fail-loud 启动下整个组装拒绝启动。一个内容完全可从会话日志重建的文件能把启动搞死。这与缓存包自己声明的立场("a stale or unreadable cache costs a longer tail replay, never a wrong value")和缓存域 spec 的 JSDoc("version bumps discard the whole medium")相矛盾——后者描述的是愿望而非实现。投影缓存半边已被[每会话缓存文件 note](../../implemented/architecture/2026-08-19-projection-cache-per-session-files.zh.md) 部分取代:全局 `session_projcache` domain 已移除,本提案的缓存恢复半边不再适用;`workspace.json` 半边仍然有效。per-record 投影缓存的 `invalid-record` 一类如今也已被取代:已发布的域声明了 `invalidRecords: 'backup-and-skip'`([跨版本读兼容 note](../../implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md)),open 时把失败记录备份后跳过,因此下文 reset/destroy 提案仅对权威介质或单文档介质的整介质损坏仍然相关。同一条 fail-loud 路径对 `workspace.json` 却是*正确*的——工作区记录是权威数据,不可派生——所以缺的概念是按域声明权威性,而不是全局改行为。 ## 提案 diff --git a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml b/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml deleted file mode 100644 index 412b47ab8f..0000000000 --- a/.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each -# side as of the last confirmed-consistent state. Both languages carry equal authority; -# after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md -2026-09-02-projcache-cross-version-read-compat.md: 9bd0cd9049ed9c9d4180f54d55f10f9b0f555dfc -2026-09-02-projcache-cross-version-read-compat.zh.md: 4682c5fe4732b21649214ee98f25d478c9bfcb18 diff --git a/packages/session/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts index d368764244..1830853f6c 100644 --- a/packages/session/session-projection-cache/src/spec.ts +++ b/packages/session/session-projection-cache/src/spec.ts @@ -81,7 +81,7 @@ export type CheckpointRecord = z.infer * their cached listing projections instead of dropping every title until * each session is reopened; the per-record version map lives in the * read-compat Agent Note - * (.agents/notes/proposed/architecture/2026-09-02-projcache-cross-version-read-compat.md). + * (.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md). * The per-row `ver` guard and the identity match still discard anything the * current fold semantics cannot vouch for. * diff --git a/packages/session/session-projection-cache/tests/fixtures.spec.ts b/packages/session/session-projection-cache/tests/fixtures.spec.ts index a85bcef5c6..e2486b7a9d 100644 --- a/packages/session/session-projection-cache/tests/fixtures.spec.ts +++ b/packages/session/session-projection-cache/tests/fixtures.spec.ts @@ -1,12 +1,14 @@ /** * Cross-version recovery over archived on-disk artifacts. `fixtures/` holds - * real `session_projcache` media produced by released builds through their - * web apps (see scripts/releasefix): the v3 whole-unit file, a v4 per-record - * document, a current v5 document, and the v5-stamped lineage-less document - * that the formerly unguarded legacy bootstrap wrote over v3 records. Each - * must recover through the real storage stack — the domain opens and the - * listing read serves the archived title — and a record that fails schema - * validation anyway is backed up and skipped instead of failing the boot. + * real `session_projcache` media, each produced by driving the named release + * through its own web app (session created over RPC, real model turns, a + * rename): the v3 whole-unit file (published 0.1.1-rc.2), a v4 per-record + * document (published 0.1.2-alpha.3), a current v5 document, and the + * v5-stamped lineage-less document reproducing byte-for-byte what the + * formerly unguarded legacy bootstrap wrote over v3 records. Each must + * recover through the real storage stack — the domain opens and the listing + * read serves the archived title — and a record that fails schema validation + * anyway is backed up and skipped instead of failing the boot. */ import { afterEach, describe, expect, it, vi } from 'vitest' From eeddd457cd6080fd046f581f70abd5eafb38c744 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 2 Sep 2026 17:14:44 +0800 Subject: [PATCH 8/8] fix(agent-team): preserve mailbox order on cold resume --- docs/persistence-catalog.i18n.yaml | 4 +- docs/persistence-catalog.md | 8 +- docs/persistence-catalog.zh.md | 8 +- .../experimental/agent-team/src/mailbox.ts | 51 ++++---- .../experimental/agent-team/src/projection.ts | 12 +- .../experimental/agent-team/src/roster.ts | 6 +- .../experimental/agent-team/src/task-board.ts | 4 +- packages/experimental/agent-team/src/types.ts | 8 +- .../agent-team/tests/invariant.spec.ts | 6 +- .../agent-team/tests/persistence.spec.ts | 18 +-- .../tests/projection-events.spec.ts | 86 ++++++------- .../agent-team/tests/team.spec.ts | 114 ++++++++---------- .../subagent/subagent/src/continuation.ts | 10 +- 13 files changed, 167 insertions(+), 168 deletions(-) diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index 84d0af864b..b6e2f8ac7f 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.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/persistence-catalog.md -persistence-catalog.md: 5b8ae5748c997b829ce715534bee4390c0aac1f5 -persistence-catalog.zh.md: 9a5d1b40201a26d20839902f109d8c1ab8eb5301 +persistence-catalog.md: 1c0c6919987c691b82c4639aff0f779c95dca83c +persistence-catalog.zh.md: 4cc8ba5b7fc76708a80285013ebcbb03fe3e8e4a diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 5b8ae5748c..1c0c691998 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -776,7 +776,7 @@ Source: [`packages/subagent/tool-subagent/src/model-selection-state.ts:17`](../p ```ts persistence-catalog /** Whole teammate lifecycle value, stored only in the Team Lead Session. */ -'team/member': { version: 1; teamId: TeamId; member: TeamMemberSnapshot } +'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot } ``` Types: [TeamId](subsystems/agent-team.md) · [TeamMemberSnapshot](subsystems/agent-team.md) @@ -790,7 +790,7 @@ Source: [`packages/experimental/agent-team/src/types.ts:221`](../packages/experi ```ts persistence-catalog /** Durable acknowledgement that the target Session recorded the message. */ 'team/message/delivered': { - version: 1 + version: 2 teamId: TeamId messageId: TeamMessageId targetId: SessionId @@ -807,7 +807,7 @@ Source: [`packages/experimental/agent-team/src/types.ts:227`](../packages/experi ```ts persistence-catalog /** Durable mailbox enqueue, stored before delivery is attempted. */ -'team/message/queued': { version: 1; teamId: TeamId; message: TeamMessageSnapshot } +'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot } ``` Types: [TeamId](subsystems/agent-team.md) · [TeamMessageSnapshot](subsystems/agent-team.md) @@ -820,7 +820,7 @@ Source: [`packages/experimental/agent-team/src/types.ts:225`](../packages/experi ```ts persistence-catalog /** Whole shared-task value, stored only in the Team Lead Session. */ -'team/task': { version: 1; teamId: TeamId; task: TeamTaskSnapshot } +'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot } ``` Types: [TeamId](subsystems/agent-team.md) · [TeamTaskSnapshot](subsystems/agent-team.md) diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index 9a5d1b4020..4cc8ba5b7f 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -778,7 +778,7 @@ export type SessionEvent = { ```ts persistence-catalog /** Whole teammate lifecycle value, stored only in the Team Lead Session. */ -'team/member': { version: 1; teamId: TeamId; member: TeamMemberSnapshot } +'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot } ``` 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamMemberSnapshot](subsystems/agent-team.zh.md) @@ -792,7 +792,7 @@ export type SessionEvent = { ```ts persistence-catalog /** Durable acknowledgement that the target Session recorded the message. */ 'team/message/delivered': { - version: 1 + version: 2 teamId: TeamId messageId: TeamMessageId targetId: SessionId @@ -809,7 +809,7 @@ export type SessionEvent = { ```ts persistence-catalog /** Durable mailbox enqueue, stored before delivery is attempted. */ -'team/message/queued': { version: 1; teamId: TeamId; message: TeamMessageSnapshot } +'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot } ``` 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamMessageSnapshot](subsystems/agent-team.zh.md) @@ -822,7 +822,7 @@ export type SessionEvent = { ```ts persistence-catalog /** Whole shared-task value, stored only in the Team Lead Session. */ -'team/task': { version: 1; teamId: TeamId; task: TeamTaskSnapshot } +'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot } ``` 类型:[TeamId](subsystems/agent-team.zh.md) · [TeamTaskSnapshot](subsystems/agent-team.zh.md) diff --git a/packages/experimental/agent-team/src/mailbox.ts b/packages/experimental/agent-team/src/mailbox.ts index 8af111cd76..acd842308a 100644 --- a/packages/experimental/agent-team/src/mailbox.ts +++ b/packages/experimental/agent-team/src/mailbox.ts @@ -26,7 +26,6 @@ import type { /** Owns every process-local state transition for the durable Team mailbox. */ export class TeamMailbox { private readonly dispatchTails = new Map>() - private readonly activeDispatches = new Map() private readonly inFlightMessages = new Set() private readonly inFlightDispatches = new Set>() @@ -139,7 +138,7 @@ export class TeamMailbox { throw new TeamError(`team message exceeds ${this.maxMessageBytes} bytes`, 'TEAM_MESSAGE_TOO_LARGE') } await this.journal.appendAndFlush(root, 'team/message/queued', { - version: 1, + version: 2, teamId: TeamId(root.id), message: queued, }) @@ -187,12 +186,7 @@ export class TeamMailbox { message: TeamMessageSnapshot, signal: AbortSignal, ): Promise { - const active = this.activeDispatches.get(message.targetId) - const live = message.targetId === root.id ? root : this.ctx.agents.get(message.targetId) - if (active !== undefined && live !== undefined && this.messagePrecedes(root, message.id, active.id)) { - return await this.dispatchOnce(root, message, signal) - } - return await this.serializeDispatch(message, () => this.dispatchOnce(root, message, signal)) + return await this.serializeDispatch(message, () => this.dispatchThrough(root, message, signal)) } /** Serialize delivery admission for one durable target in queued order. */ @@ -202,16 +196,8 @@ export class TeamMailbox { ): Promise { const targetId = message.targetId const prior = this.dispatchTails.get(targetId) ?? Promise.resolve() - const dispatch = async (): Promise => { - this.activeDispatches.set(targetId, message) - try { - return await operation() - } finally { - this.activeDispatches.delete(targetId) - } - } /* v8 ignore next -- dispatch tails absorb rejection, so the recovery callback is a fail-safe backstop. */ - const run = prior.then(dispatch, dispatch) + const run = prior.then(operation, operation) /* v8 ignore next -- dispatchOnce contains delivery failures and serializeDispatch itself does not throw. */ const tail = run.then(() => undefined, () => undefined) this.dispatchTails.set(targetId, tail) @@ -222,6 +208,29 @@ export class TeamMailbox { } } + /** Deliver every pending target message through `message` in durable queue order. */ + private async dispatchThrough( + root: Agent, + message: TeamMessageSnapshot, + signal: AbortSignal, + ): Promise { + const state = this.journal.state(root) + const pending = state.messages.filter(candidate => + candidate.targetId === message.targetId && !state.delivered.includes(candidate.id)) + const requested = pending.findIndex(candidate => candidate.id === message.id) + if (requested < 0) return state.delivered.includes(message.id) + for (const candidate of pending.slice(0, requested + 1)) { + const ownsInFlight = !this.inFlightMessages.has(candidate.id) + if (ownsInFlight) this.inFlightMessages.add(candidate.id) + try { + if (!await this.dispatchOnce(root, candidate, signal)) return false + } finally { + if (ownsInFlight) this.inFlightMessages.delete(candidate.id) + } + } + return true + } + /** Attempt one queued delivery after target-local ordering admits it. */ private async dispatchOnce(root: Agent, message: TeamMessageSnapshot, signal: AbortSignal): Promise { try { @@ -260,12 +269,6 @@ export class TeamMailbox { } } - /** Whether `left` was durably queued before `right` in one Lead log. */ - private messagePrecedes(root: Agent, left: TeamMessageId, right: TeamMessageId): boolean { - const ids = this.journal.state(root).messages.map(message => message.id) - return ids.indexOf(left) < ids.indexOf(right) - } - /** Flush one live target receipt before the Lead records its delivered edge. */ private async checkpointDelivered( root: Agent, @@ -286,7 +289,7 @@ export class TeamMailbox { const queued = state.messages.find(message => message.id === messageId) if (queued === undefined || queued.targetId !== targetId) return await this.journal.appendAndFlush(root, 'team/message/delivered', { - version: 1, + version: 2, teamId: TeamId(root.id), messageId, targetId, diff --git a/packages/experimental/agent-team/src/projection.ts b/packages/experimental/agent-team/src/projection.ts index 2d60102197..85fdfd0e0d 100644 --- a/packages/experimental/agent-team/src/projection.ts +++ b/packages/experimental/agent-team/src/projection.ts @@ -99,25 +99,25 @@ const teamEventSelectorSchema = z.object({ }).loose() const teamMemberEventSchema = z.object({ - version: z.literal(1), + version: z.literal(2), teamId: teamIdSchema, member: teamMemberSnapshotSchema, }).strict() as z.ZodType const teamTaskEventSchema = z.object({ - version: z.literal(1), + version: z.literal(2), teamId: teamIdSchema, task: teamTaskSnapshotSchema, }).strict() as z.ZodType const teamMessageQueuedEventSchema = z.object({ - version: z.literal(1), + version: z.literal(2), teamId: teamIdSchema, message: teamMessageSnapshotSchema, }).strict() as z.ZodType const teamMessageDeliveredEventSchema = z.object({ - version: z.literal(1), + version: z.literal(2), teamId: teamIdSchema, messageId: teamMessageIdSchema, targetId: sessionIdSchema, @@ -224,7 +224,7 @@ function applyProjectionEvent(state: TeamProjectionState, event: SessionEvent): try { const selector = parsePersisted(event.type, teamEventSelectorSchema, event.data) if (selector.teamId !== state.id) return - if (selector.version !== 1) { + if (selector.version !== 2) { throw new Error(`unsupported Agent Teams event version ${String(selector.version)}`) } applyCurrentTeamEvent(state, parseCurrentTeamEvent(event)) @@ -306,7 +306,7 @@ function applyCurrentTeamEvent(state: TeamState, event: TeamSessionEvent): void /** Host-only Team projection selected by the projected Session identity. */ export const teamProjectionDefinition = { key: 'agentTeam', - stateVersion: 2, + stateVersion: 3, stateSchema: teamProjectionEntrySchema, init: header => emptyTeamState(header.id), apply: (state, event) => { diff --git a/packages/experimental/agent-team/src/roster.ts b/packages/experimental/agent-team/src/roster.ts index 7ff934b150..3d0ca8372e 100644 --- a/packages/experimental/agent-team/src/roster.ts +++ b/packages/experimental/agent-team/src/roster.ts @@ -274,7 +274,7 @@ export class TeamRoster { if (state.members.length >= this.maxMembers) { throw new TeamError(`Team member limit ${this.maxMembers} reached`, 'TEAM_MEMBER_LIMIT') } - await this.journal.appendAndFlush(root, 'team/member', { version: 1, teamId: TeamId(root.id), member }) + await this.journal.appendAndFlush(root, 'team/member', { version: 2, teamId: TeamId(root.id), member }) }) let started: ContinuableStart @@ -424,7 +424,7 @@ export class TeamRoster { ...phase === 'failed' ? { error: failure } : {}, } await this.journal.appendAndFlush(root, 'team/member', { - version: 1, + version: 2, teamId: TeamId(root.id), member: settled, }) @@ -472,7 +472,7 @@ export class TeamRoster { } if (current.phase !== 'provisioning') return current.phase await this.journal.appendAndFlush(root, 'team/member', { - version: 1, + version: 2, teamId: TeamId(root.id), member: terminal, }) diff --git a/packages/experimental/agent-team/src/task-board.ts b/packages/experimental/agent-team/src/task-board.ts index 5dd235f940..cc7064ceb6 100644 --- a/packages/experimental/agent-team/src/task-board.ts +++ b/packages/experimental/agent-team/src/task-board.ts @@ -67,7 +67,7 @@ export class TeamTaskBoard { writeScopes: this.writeScopes(request.writeScopes ?? []), } this.assertTaskGraph(state, task) - await this.journal.appendAndFlush(root, 'team/task', { version: 1, teamId: TeamId(root.id), task }) + await this.journal.appendAndFlush(root, 'team/task', { version: 2, teamId: TeamId(root.id), task }) return this.taskView(root, state, task) }) } @@ -209,7 +209,7 @@ export class TeamTaskBoard { revision: current.revision + 1, } this.assertTaskGraph(state, task) - await this.journal.appendAndFlush(root, 'team/task', { version: 1, teamId: TeamId(root.id), task }) + await this.journal.appendAndFlush(root, 'team/task', { version: 2, teamId: TeamId(root.id), task }) return this.taskView(root, state, task) }) } diff --git a/packages/experimental/agent-team/src/types.ts b/packages/experimental/agent-team/src/types.ts index 5818a6bc5f..f7b8ca414f 100644 --- a/packages/experimental/agent-team/src/types.ts +++ b/packages/experimental/agent-team/src/types.ts @@ -218,14 +218,14 @@ export interface TeamWaitResult { declare module '@deepseek-ai/dsh-session/types' { interface SessionEventMap { /** Whole teammate lifecycle value, stored only in the Team Lead Session. */ - 'team/member': { version: 1; teamId: TeamId; member: TeamMemberSnapshot } + 'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot } /** Whole shared-task value, stored only in the Team Lead Session. */ - 'team/task': { version: 1; teamId: TeamId; task: TeamTaskSnapshot } + 'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot } /** Durable mailbox enqueue, stored before delivery is attempted. */ - 'team/message/queued': { version: 1; teamId: TeamId; message: TeamMessageSnapshot } + 'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot } /** Durable acknowledgement that the target Session recorded the message. */ 'team/message/delivered': { - version: 1 + version: 2 teamId: TeamId messageId: TeamMessageId targetId: SessionId diff --git a/packages/experimental/agent-team/tests/invariant.spec.ts b/packages/experimental/agent-team/tests/invariant.spec.ts index 04d99d75a5..5dd8dba256 100644 --- a/packages/experimental/agent-team/tests/invariant.spec.ts +++ b/packages/experimental/agent-team/tests/invariant.spec.ts @@ -30,13 +30,13 @@ describe('Agent Teams stream invariant', () => { phase: 'provisioning' as const, } expect(() => { - session.append('team/member', { version: 1, teamId: TeamId(session.id), member }) + session.append('team/member', { version: 2, teamId: TeamId(session.id), member }) }).not.toThrow() const invalid = ctx.sessions.create(SessionId('team-invariant-invalid')) expect(() => { invalid.append('team/member', { - version: 1, + version: 2, teamId: TeamId(invalid.id), member: { ...member, phase: 'active' }, }) @@ -53,7 +53,7 @@ describe('Agent Teams stream invariant', () => { expect(() => { session.append('team/task', { - version: 1, + version: 2, teamId: TeamId(session.id), task: { id: TeamTaskId('task-1'), diff --git a/packages/experimental/agent-team/tests/persistence.spec.ts b/packages/experimental/agent-team/tests/persistence.spec.ts index 12f3e1b9f3..0f550c591c 100644 --- a/packages/experimental/agent-team/tests/persistence.spec.ts +++ b/packages/experimental/agent-team/tests/persistence.spec.ts @@ -178,12 +178,12 @@ for (const backend of backends) { await Promise.resolve() activeRoot.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(activeRoot.id), member: provisioning(childId, 'recoverable'), }) failedRoot.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(failedRoot.id), member: provisioning(SessionId(`${backend.name}-missing`), 'missing'), }) @@ -248,7 +248,7 @@ for (const backend of backends) { await Promise.resolve() await Promise.resolve() root.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(root.id), member: provisioning(childId, 'pending-worker'), }) @@ -295,8 +295,8 @@ for (const backend of backends) { signal: SIGNAL, }) await vi.waitFor(() => { expect(first.ctx.agents.get(started.member.id)).toBeUndefined() }, { timeout: 5_000 }) - vi.spyOn(first.ctx.sessionPersistence, 'inspect') - .mockRejectedValueOnce(new Error('temporary target inspection failure')) + vi.spyOn(first.ctx.sessionPersistence, 'open') + .mockRejectedValueOnce(new Error('temporary target read failure')) const queued = await first.ctx.agentTeams.sendMessage(firstLead, { target: 'mail-worker', content: [{ type: 'text', text: 'durable retry context' }], @@ -376,7 +376,7 @@ for (const backend of backends) { content: [{ type: 'text', text: 'already recorded before acknowledgement' }], } firstLead.session.append('team/message/queued', { - version: 1, + version: 2, teamId: TeamId(rootId), message: queued, }) @@ -428,17 +428,17 @@ for (const backend of backends) { content: [{ type: 'text', text: 'already durable in target inbox' }], } root.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(root.id), member: provisioned, }) root.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(root.id), member: active, }) root.session.append('team/message/queued', { - version: 1, + version: 2, teamId: TeamId(root.id), message: queued, }) diff --git a/packages/experimental/agent-team/tests/projection-events.spec.ts b/packages/experimental/agent-team/tests/projection-events.spec.ts index d78b160ff0..97187e4eb6 100644 --- a/packages/experimental/agent-team/tests/projection-events.spec.ts +++ b/packages/experimental/agent-team/tests/projection-events.spec.ts @@ -79,15 +79,15 @@ function message(overrides: Partial = {}): TeamMessageSnaps describe('Agent Teams projection events', () => { it('projects current-team records independently from inherited records', () => { const records: SessionEvent[] = [ - event('team/member', { version: 1, teamId: TeamId('ancestor'), member: member() }, SessionSeq(0)), - event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(1)), + event('team/member', { version: 2, teamId: TeamId('ancestor'), member: member() }, SessionSeq(0)), + event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(1)), event('team/member', { - version: 1, + version: 2, teamId: TEAM, member: member({ phase: 'active' }), }, SessionSeq(2)), - event('team/task', { version: 1, teamId: TEAM, task: task({ id: TeamTaskId('task-7') }) }, SessionSeq(3)), - event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, SessionSeq(4)), + event('team/task', { version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-7') }) }, SessionSeq(3)), + event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(4)), ] const projected = project(ROOT, records) const state = teamState(projected) @@ -103,53 +103,53 @@ describe('Agent Teams projection events', () => { }) it('enforces teammate identity and lifecycle', () => { - const base = event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(0)) + const base = event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0)) expect(() => projectTeam(ROOT, [event('team/member', { - version: 1, + version: 2, teamId: TEAM, member: member({ phase: 'active' }), }, SessionSeq(0))])).toThrow(/must begin provisioning/) expect(() => projectTeam(ROOT, [base, event('team/member', { - version: 1, + version: 2, teamId: TEAM, member: member({ name: 'renamed', phase: 'active' }), }, SessionSeq(1))])).toThrow(/immutable identity/) expect(() => projectTeam(ROOT, [base, event('team/member', { - version: 1, + version: 2, teamId: TEAM, member: member({ phase: 'active' }), }, SessionSeq(1)), event('team/member', { - version: 1, + version: 2, teamId: TEAM, member: member({ phase: 'failed' }), }, SessionSeq(2))])).toThrow(/invalid active -> failed/) const duplicateName = member({ id: SessionId('child-b') }) expect(() => projectTeam(ROOT, [base, event('team/member', { - version: 1, + version: 2, teamId: TEAM, member: duplicateName, }, SessionSeq(1))])).toThrow(/name .* reused/) }) it('enforces task revision continuity', () => { - const first = event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0)) + const first = event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0)) expect(() => projectTeam(ROOT, [event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ revision: 2 }), }, SessionSeq(0))])).toThrow(/begin at revision 1/) expect(() => projectTeam(ROOT, [first, event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ revision: 3 }), }, SessionSeq(1))])).toThrow(/revision is not contiguous/) }) it('rejects every invalid persisted task dependency relation', () => { - const first = event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0)) + const first = event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0)) const second = event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-2'), @@ -159,7 +159,7 @@ describe('Agent Teams projection events', () => { const invalid: Array<{ records: SessionEvent[]; message: RegExp }> = [ { records: [event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ blockedBy: [TeamTaskId('missing')] }), }, SessionSeq(0))], @@ -167,7 +167,7 @@ describe('Agent Teams projection events', () => { }, { records: [event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ blockedBy: [TeamTaskId('task-1')] }), }, SessionSeq(0))], @@ -182,7 +182,7 @@ describe('Agent Teams projection events', () => { }, { records: [first, second, event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ revision: 2, blockedBy: [TeamTaskId('task-2')] }), }, SessionSeq(2))], @@ -190,7 +190,7 @@ describe('Agent Teams projection events', () => { }, { records: [first, second, event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ revision: 2, status: 'deleted' }), }, SessionSeq(2))], @@ -205,7 +205,7 @@ describe('Agent Teams projection events', () => { it('leaves numeric allocation unchanged for a branded nonstandard task id', () => { const state = projectTeam(ROOT, [event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ id: TeamTaskId('external-task') }), }, SessionSeq(0))]) @@ -214,16 +214,16 @@ describe('Agent Teams projection events', () => { it('rejects a persisted numeric task id outside the safe integer range', () => { expect(() => projectTeam(ROOT, [event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-9007199254740992') }), }, SessionSeq(0))])).toThrow(/persisted Agent Teams team\/task payload is invalid/) }) it('enforces mailbox queue and acknowledgement relations', () => { - const queued = event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, SessionSeq(0)) + const queued = event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(0)) const delivered = event('team/message/delivered', { - version: 1, + version: 2, teamId: TEAM, messageId: TeamMessageId('message-1'), targetId: CHILD, @@ -241,42 +241,42 @@ describe('Agent Teams projection events', () => { it('validates every current-version persisted payload before projecting it', () => { const malformed = [ { - ...event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(0)), - data: { version: 1, teamId: TEAM, member: { ...member(), name: 42 } }, + ...event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0)), + data: { version: 2, teamId: TEAM, member: { ...member(), name: 42 } }, }, { - ...event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0)), - data: { version: 1, teamId: TEAM, task: { ...task(), blockedBy: [42] } }, + ...event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0)), + data: { version: 2, teamId: TEAM, task: { ...task(), blockedBy: [42] } }, }, { - ...event('team/message/queued', { version: 1, teamId: TEAM, message: message() }, SessionSeq(0)), + ...event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(0)), data: { - version: 1, + version: 2, teamId: TEAM, message: { ...message(), content: [{ type: 'text', text: 42 }] }, }, }, { ...event('team/message/delivered', { - version: 1, + version: 2, teamId: TEAM, messageId: TeamMessageId('message-1'), targetId: CHILD, }, SessionSeq(0)), data: { - version: 1, + version: 2, teamId: TEAM, messageId: TeamMessageId('message-1'), targetId: 42, }, }, { - ...event('team/member', { version: 1, teamId: TEAM, member: member() }, SessionSeq(0)), - data: { version: 1, teamId: TEAM, member: member(), unexpected: true }, + ...event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0)), + data: { version: 2, teamId: TEAM, member: member(), unexpected: true }, }, { - ...event('team/task', { version: 1, teamId: TEAM, task: task() }, SessionSeq(0)), - data: { version: 1, teamId: 42, task: task() }, + ...event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0)), + data: { version: 2, teamId: 42, task: task() }, }, ] as unknown as SessionEvent[] @@ -289,7 +289,7 @@ describe('Agent Teams projection events', () => { it('retains merge-extensible content blocks while rejecting malformed core variants', () => { const extension = { type: 'plugin/custom', payload: { value: 1 } } as never const state = projectTeam(ROOT, [event('team/message/queued', { - version: 1, + version: 2, teamId: TEAM, message: message({ content: [extension] }), }, SessionSeq(0))]) @@ -298,23 +298,23 @@ describe('Agent Teams projection events', () => { it('records unsupported event versions without applying them', () => { const invalid = event('team/task', { - version: 2 as 1, + version: 1 as 2, teamId: TEAM, task: task(), }, SessionSeq(0)) const later = event('team/task', { - version: 1, + version: 2, teamId: TEAM, task: task(), }, SessionSeq(1)) const state = project(ROOT, [invalid, later]) - expect(state.failure).toMatch(/unsupported Agent Teams event version 2/) + expect(state.failure).toMatch(/unsupported Agent Teams event version 1/) expect(isEmptyState(state)).toBe(true) }) it('isolates unsupported inherited Team records from the current Team', () => { const inherited = event('team/task', { - version: 2 as 1, + version: 1 as 2, teamId: TeamId('ancestor'), task: task(), }, SessionSeq(0)) @@ -326,12 +326,12 @@ describe('Agent Teams projection events', () => { it('ignores malformed current-version records inherited from another Team', () => { const inherited = { ...event('team/task', { - version: 1, + version: 2, teamId: TeamId('ancestor'), task: task(), }, SessionSeq(0)), data: { - version: 1, + version: 2, teamId: TeamId('ancestor'), task: { ...task(), subject: 42 }, }, diff --git a/packages/experimental/agent-team/tests/team.spec.ts b/packages/experimental/agent-team/tests/team.spec.ts index 1a11e8c06c..4f099a0916 100644 --- a/packages/experimental/agent-team/tests/team.spec.ts +++ b/packages/experimental/agent-team/tests/team.spec.ts @@ -193,7 +193,7 @@ describe('Team identity and provisioning', () => { phase: 'provisioning' as const, } lead.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(lead.id), member: provisioning, }) @@ -354,7 +354,7 @@ describe('Team identity and provisioning', () => { const provisioning = durable(second.lead).members[0] if (provisioning === undefined) throw new Error('missing provisioning edge') second.lead.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(second.lead.id), member: { ...provisioning, phase: 'active' }, }) @@ -555,7 +555,7 @@ describe('Team shared task DAG', () => { const { ctx, lead } = await setup([]) const id = TeamTaskId(`task-${Number.MAX_SAFE_INTEGER}`) lead.session.append('team/task', { - version: 1, + version: 2, teamId: TeamId(lead.id), task: { id, @@ -948,7 +948,7 @@ describe('Team mailbox and waiting', () => { content: content('progress report'), } lead.session.append('team/message/queued', { - version: 1, + version: 2, teamId: TeamId(lead.id), message, }) @@ -1034,7 +1034,7 @@ describe('Team mailbox and waiting', () => { content: content('durable pending receipt'), } lead.session.append('team/message/queued', { - version: 1, + version: 2, teamId: TeamId(lead.id), message, }) @@ -1070,7 +1070,7 @@ describe('Team mailbox and waiting', () => { content: content('canceled before checkpoint'), } lead.session.append('team/message/queued', { - version: 1, + version: 2, teamId: TeamId(lead.id), message: disappearing, }) @@ -1137,14 +1137,14 @@ describe('Team mailbox and waiting', () => { }) it('serializes concurrent Steer delivery admission for one target', async () => { - const { ctx, lead } = await setup([textResponse('target initial')]) - const target = await spawn(ctx, lead, 'ordered-target') - await waitNoAgent(ctx, target.member.id) + const { ctx, lead } = await setup(['hang']) + const started = await spawn(ctx, lead, 'ordered-target') + const target = await waitRunning(ctx, started.member.id) const entered = Promise.withResolvers() const release = Promise.withResolvers() const admitted: string[] = [] vi.spyOn(ctx.subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) - .mockImplementation(async (_parent, _childId, blocks) => { + .mockImplementation(async (_parent, _childId, blocks, source) => { const last = blocks.at(-1) const text = last?.type === 'text' ? last.text : '' admitted.push(text) @@ -1152,7 +1152,9 @@ describe('Team mailbox and waiting', () => { entered.resolve(undefined) await release.promise } - return createUserMessage({ content: blocks, source: { kind: 'user' } }).id + const input = createUserMessage({ content: blocks, source }) + target.inject(input) + return input.id }) const first = ctx.agentTeams.sendMessage(lead, { @@ -1163,7 +1165,7 @@ describe('Team mailbox and waiting', () => { const second = ctx.agentTeams.sendMessage(lead, { target: 'ordered-target', content: content('second steer'), signal: SIGNAL, }).finally(() => { secondSettled = true }) - await new Promise((resolve) => { setTimeout(resolve, 0) }) + await vi.waitFor(() => { expect(durable(lead).pendingMessages).toHaveLength(2) }) expect(admitted).toEqual(['first steer']) expect(secondSettled).toBe(false) @@ -1173,58 +1175,43 @@ describe('Team mailbox and waiting', () => { { status: 'accepted' }, ]) expect(admitted).toEqual(['first steer', 'second steer']) + + ctx.agentTeams.interrupt(lead, 'ordered-target') + target.cancel({ kind: 'parent' }) + await waitNoAgent(ctx, target.id) }) - it('admits an earlier durable message ahead of a later in-flight resume', async () => { - const { ctx, lead } = await setup(['hang']) + it('delivers persisted mail before the later message that cold-resumes its target', async () => { + const { ctx, lead } = await setup([textResponse('target initial'), 'hang', 'hang']) const started = await spawn(ctx, lead, 'reordered-target') - const target = await waitRunning(ctx, started.member.id) + await waitNoAgent(ctx, started.member.id) const earlier: TeamMessageSnapshot = { id: TeamMessageId('earlier-message'), senderId: lead.id, senderName: 'lead', - targetId: target.id, + targetId: started.member.id, content: content('earlier steer'), } - const later: TeamMessageSnapshot = { - ...earlier, - id: TeamMessageId('later-message'), - content: content('later steer'), - } - for (const message of [earlier, later]) { - lead.session.append('team/message/queued', { - version: 1, - teamId: TeamId(lead.id), - message, - }) - } + lead.session.append('team/message/queued', { + version: 2, + teamId: TeamId(lead.id), + message: earlier, + }) + await ctx.sessions.flush(lead.session) - const laterEntered = Promise.withResolvers() - const releaseLater = Promise.withResolvers() - const admitted: string[] = [] - vi.spyOn(ctx.subagents as unknown as HostPromptDeliverer, deliverSubagentPrompt) - .mockImplementation(async (_parent, _childId, blocks, source) => { - const last = blocks.at(-1) - const text = last?.type === 'text' ? last.text : '' - if (text === 'later steer') { - laterEntered.resolve(undefined) - await releaseLater.promise - } - const input = createUserMessage({ content: blocks, source }) - target.inject(input) - admitted.push(text) - return input.id - }) - - const laterDispatch = teamInternals(ctx).mailbox.tryDispatch(lead, later, SIGNAL) - await laterEntered.promise - await expect(teamInternals(ctx).mailbox.tryDispatch(lead, earlier, SIGNAL)).resolves.toBe(true) - expect(admitted).toEqual(['earlier steer']) - - releaseLater.resolve(undefined) - await expect(laterDispatch).resolves.toBe(true) - expect(admitted).toEqual(['earlier steer', 'later steer']) - expect(durable(lead).pendingMessages).toEqual([]) + const later = await ctx.agentTeams.sendMessage(lead, { + target: 'reordered-target', content: content('later steer'), signal: SIGNAL, + }) + expect(later.status).toBe('accepted') + const target = await waitRunning(ctx, started.member.id) + await vi.waitFor(() => { + const accepted = target.session.snapshotEvents().flatMap(event => event.type === 'agent/inbox/spliced' + ? event.data.inserted.flatMap(message => message.source.kind === 'team-message' + ? [message.source.messageId] + : []) + : []) + expect(accepted).toEqual([earlier.id, later.messageId]) + }) ctx.agentTeams.interrupt(lead, 'reordered-target') target.cancel({ kind: 'parent' }) @@ -1244,7 +1231,7 @@ describe('Team mailbox and waiting', () => { content: content('already in live history'), } lead.session.append('team/message/queued', { - version: 1, teamId: TeamId(lead.id), message, + version: 2, teamId: TeamId(lead.id), message, }) await ctx.sessions.flush(lead.session) live.session.append('user/message', createUserMessage({ @@ -1269,13 +1256,14 @@ describe('Team mailbox and waiting', () => { }), { surfaceOp: 'append' }) await expect(internal.tryDispatch(lead, message, SIGNAL)).resolves.toBe(true) await internal.markDelivered(lead, message.id, live.id) + await expect(internal.tryDispatch(lead, message, SIGNAL)).resolves.toBe(true) const wrongTarget: TeamMessageSnapshot = { ...message, id: TeamMessageId('wrong-target-message'), } lead.session.append('team/message/queued', { - version: 1, teamId: TeamId(lead.id), message: wrongTarget, + version: 2, teamId: TeamId(lead.id), message: wrongTarget, }) await ctx.sessions.flush(lead.session) await internal.markDelivered(lead, wrongTarget.id, SessionId('wrong-target')) @@ -1383,7 +1371,7 @@ describe('Team mailbox and waiting', () => { await expect(ctx.agentTeams.sendMessage(lead, { target: 'target', content: content('x'.repeat(300)), signal: SIGNAL, })).rejects.toMatchObject({ code: 'TEAM_MESSAGE_TOO_LARGE' }) - vi.spyOn(ctx.sessionPersistence, 'inspect').mockRejectedValueOnce(new Error('temporary inspection failure')) + vi.spyOn(ctx.sessionPersistence, 'open').mockRejectedValueOnce(new Error('temporary read failure')) const queued = await ctx.agentTeams.sendMessage(lead, { target: 'target', content: content('one'), signal: SIGNAL, }) @@ -1589,7 +1577,7 @@ describe('Team mailbox and waiting', () => { phase: 'provisioning' as const, } lead.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(lead.id), member, }) @@ -1602,7 +1590,7 @@ describe('Team mailbox and waiting', () => { }) await waitRunning(ctx, childId) lead.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(lead.id), member: { ...member, @@ -1669,7 +1657,7 @@ describe('Team mailbox and waiting', () => { content: content('acknowledge before disposal'), } lead.session.append('team/message/queued', { - version: 1, + version: 2, teamId: TeamId(lead.id), message, }) @@ -1822,7 +1810,7 @@ describe('Team mailbox and waiting', () => { phase: 'provisioning' as const, } first.lead.session.append('team/member', { - version: 1, teamId: TeamId(first.lead.id), member: provisioning, + version: 2, teamId: TeamId(first.lead.id), member: provisioning, }) const reconcileFirst = teamInternals(first.ctx).roster await reconcileFirst.reconcileProvisioning(first.lead, SIGNAL) @@ -1842,7 +1830,7 @@ describe('Team mailbox and waiting', () => { const childId = SessionId('concurrently-settled-child') const member = { ...provisioning, id: childId, name: 'concurrent-child' } second.lead.session.append('team/member', { - version: 1, teamId: TeamId(second.lead.id), member, + version: 2, teamId: TeamId(second.lead.id), member, }) const entered = Promise.withResolvers() const release = Promise.withResolvers() @@ -1855,7 +1843,7 @@ describe('Team mailbox and waiting', () => { const reconciling = reconcileSecond.reconcileProvisioning(second.lead, SIGNAL) await entered.promise second.lead.session.append('team/member', { - version: 1, + version: 2, teamId: TeamId(second.lead.id), member: { ...member, phase: 'failed', error: 'settled elsewhere' }, }) diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts index 6fabb6ea33..f127bc51de 100644 --- a/packages/subagent/subagent/src/continuation.ts +++ b/packages/subagent/subagent/src/continuation.ts @@ -134,7 +134,15 @@ export interface SubagentSendMessageOptions { /** Inputs shared by model steering and the human Queue adapter. */ type ChildDeliveryOptions = - | { readonly delivery: 'steer'; readonly source?: MessageSource; readonly signal: AbortSignal } + | { + readonly delivery: 'steer' + /** + * A provided host source is preserved on the user message; omission attributes + * an adjacent-Agent message to the parent. + */ + readonly source?: MessageSource + readonly signal: AbortSignal + } | { readonly delivery: 'queue'; readonly source: MessageSource; readonly signal: AbortSignal } /**