From 8cf14a80fe269df2df88956b846880434d470dc0 Mon Sep 17 00:00:00 2001 From: jinmingtao Date: Fri, 20 Nov 2026 18:50:08 +0800 Subject: [PATCH 1/3] test(worker): cover durable deliverable notification --- test/project-runtime.test.ts | 210 +++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) diff --git a/test/project-runtime.test.ts b/test/project-runtime.test.ts index 851a28f..299c284 100644 --- a/test/project-runtime.test.ts +++ b/test/project-runtime.test.ts @@ -34,6 +34,216 @@ class ProjectCodexFake extends CodexFake { } } +async function nativeWorkerAction(f: Awaited>, taskId: string, action: ProjectAction) { + const task = f.loop.store.task(taskId); + assert.ok(task.threadId && f.codex.projectHandler); + const snapshot = f.codex.snapshot(task.threadId); + assert.ok(snapshot.turnId); + return f.codex.projectHandler({ threadId: task.threadId, turnId: snapshot.turnId, + connectionEpoch: 'fake-epoch', callId: action.action === 'status' ? 'status' : action.requestId, action }); +} + +function deliverResult(requestId = 'delivery-attempt-1', resultId = 'result-v1'): ProjectAction { + return { action: 'deliver_result', requestId, resultId, text: 'Verified deliverable. Independent review remains pending.', + deliveryReferences: ['https://github.com/example/app/pull/42', 'docs/verification.md'] }; +} + +for (const grouped of [false, true]) for (const running of [false, true]) { + test(`Worker deliverable reaches its coordinator once with grouped=${grouped} running=${running} and no owner request`, async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('deliverable', 'Produce the agreed deliverable.'); + if (grouped) await f.openGroup(worker.id); + if (!running) await f.idleCoordinator(); + const coordinator = f.coordinator(), groups = f.feishu.groups.size; + const starts = f.codex.starts.length, steers = f.codex.steers.length; + const receipt = await nativeWorkerAction(f, worker.id, deliverResult()); + assert.deepEqual(await nativeWorkerAction(f, worker.id, deliverResult()), receipt); + await f.loop.tick(); + assert.equal(f.events(coordinator.id, 'worker_result').length, 0); + assert.equal(f.codex.starts.length, starts); assert.equal(f.codex.steers.length, steers); + f.codex.complete(worker.threadId!, 'Task group final with a different wording.'); + await f.loop.tick(); await f.loop.tick(); + const events = f.events(coordinator.id, 'worker_result'); + assert.equal(events.length, 1); assert.equal(events[0]?.status, 'delivered'); + assert.match(events[0]!.message.text, /Verified deliverable/); + assert.match(events[0]!.message.text, /result-v1/); + assert.match(JSON.stringify(events[0]), /docs\/verification\.md/); + assert.ok(events[0]?.provenance.kind === 'agent'); + assert.equal(events[0].provenance.taskId, worker.id); + assert.equal(f.codex.starts.length, starts + (running ? 0 : 1)); + assert.equal(f.codex.steers.length, steers + (running ? 1 : 0)); + assert.equal(f.feishu.groups.size, groups); + assert.equal(f.loop.closeout.completed(worker.id), false); + assert.equal(f.loop.store.meta(`task-summary:${worker.id}`), 'Task group final with a different wording.'); + assert.equal(f.loop.store.outputs(worker.id).filter(output => output.text.includes('Task group final')).length, 1); + const group = f.loop.store.task(worker.id).chatId; + assert.equal(group !== null, grouped); + if (group) assert.equal(f.feishu.sent.filter(output => output.chatId === group && output.text.includes('Task group final')).length, 1); + await f.restart(); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(coordinator.id, 'worker_result').length, 1); + assert.equal(f.codex.starts.length, starts + (running ? 0 : 1)); + assert.equal(f.codex.steers.length, steers + (running ? 1 : 0)); + }); +} + +test('Worker delivery survives a restart before successful completion and a lost coordinator delivery response', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('durable-delivery', 'Produce evidence.'); await f.idleCoordinator(); + const action = deliverResult(); + const receipt = await nativeWorkerAction(f, worker.id, action); + await f.restart(); + assert.deepEqual(await nativeWorkerAction(f, worker.id, action), receipt); + const starts = f.codex.starts.length; + f.codex.complete(worker.threadId!, null); + f.codex.loseInputAck = true; + await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); + assert.equal(f.codex.starts.length, starts + 1); + await f.restart(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result')[0]?.status, 'delivered'); + assert.equal(f.codex.starts.length, starts + 1); +}); + +test('Worker result identity deduplicates across turns while separate results with the same prose remain distinct', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('stable-result-id', 'Deliver once.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + await f.loop.projectAction(f.coordinator().id, { action: 'send', requestId: 'follow-up', taskId: worker.id, text: 'Review the delivered evidence.' }); + await f.loop.tick(); + await nativeWorkerAction(f, worker.id, deliverResult('new-attempt-same-result')); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); + await f.loop.projectAction(f.coordinator().id, { action: 'send', requestId: 'second-result', taskId: worker.id, text: 'Produce the second deliverable.' }); + await f.loop.tick(); + await nativeWorkerAction(f, worker.id, deliverResult('new-attempt-new-result', 'result-v2')); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 2); +}); + +test('Worker delivery requires active trusted ingress and rejects changed retry content', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('trusted-delivery', 'Deliver evidence.'); + await assert.rejects(f.loop.projectAction(worker.id, deliverResult()), /active|identity|context/i); + await assert.rejects(nativeWorkerAction(f, f.coordinator().id, deliverResult()), /worker/i); + assert.ok(worker.threadId && f.codex.projectHandler); + const snapshot = f.codex.snapshot(worker.threadId); assert.ok(snapshot.turnId); + await assert.rejects(f.codex.projectHandler({ threadId: worker.threadId, turnId: snapshot.turnId, callId: 'stale', + connectionEpoch: 'stale-epoch', action: deliverResult() }), /active/i); + await nativeWorkerAction(f, worker.id, deliverResult()); + await assert.rejects(nativeWorkerAction(f, worker.id, { ...deliverResult(), text: 'Changed operation content.' }), /different|conflict/i); + await assert.rejects(nativeWorkerAction(f, worker.id, { ...deliverResult('changed-result'), text: 'Changed result content.' }), /different|conflict/i); + f.codex.complete(worker.threadId, 'Ordinary final.'); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); +}); + +for (const terminal of ['failed', 'interrupted'] as const) { + test(`Worker ${terminal} execution cannot publish or later reactivate a declared delivery`, async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch(`delivery-${terminal}`, 'Deliver evidence.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + const snapshot = f.codex.snapshot(worker.threadId!); + snapshot.status = terminal; snapshot.error = terminal; + await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + assert.ok(f.events(f.coordinator().id, 'execution_status').length > 0); + f.codex.complete(worker.threadId!, 'Later ordinary final.'); + await f.loop.tick(); await f.restart(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + }); +} + +test('operator pause invalidates a pending Worker delivery even when the turn finishes before resume', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('paused-delivery', 'Deliver evidence.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + await f.loop.control(worker.id, 'pause'); + f.codex.complete(worker.threadId!, 'Final after pause.'); + await f.loop.control(worker.id, 'resume'); await f.loop.tick(); await f.restart(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); +}); + +for (const kind of ['question', 'approval', 'permissions'] as const) { + test(`native ${kind} preserves its request and prevents a pending Worker delivery`, async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch(`native-delivery-${kind}`, 'Deliver evidence.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + const snapshot = f.codex.snapshot(worker.threadId!); assert.ok(snapshot.turnId); + const request: PendingRequest = { id: `delivery-${kind}`, kind, threadId: worker.threadId!, turnId: snapshot.turnId, + connectionEpoch: 'fake-epoch', prompt: `Native ${kind} still needs an answer.`, method: `native/${kind}`, payload: {}, isBlocking: true }; + snapshot.requests = [request]; await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + assert.deepEqual(f.loop.store.task(worker.id).requests, [request]); + assert.equal(f.codex.approvals.length, 0); assert.equal(f.codex.replies.length, 0); + if (kind === 'question') assert.equal(f.events(f.coordinator().id, 'question').length, 1); + else assert.equal(f.feishu.approvals.at(-1)?.request.id, request.id); + f.codex.complete(worker.threadId!, 'This final does not replace the native answer.'); await f.loop.tick(); await f.restart(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + assert.equal(f.codex.approvals.length, 0); assert.equal(f.codex.replies.length, 0); + }); +} + +for (const origin of ['owner', 'coordinator'] as const) { + test(`${origin} steering invalidates the old delivery and permits a fresh declaration after handling input`, async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch(`delivery-steering-${origin}`, 'Deliver evidence.'); + const opened = origin === 'owner' ? await f.openGroup(worker.id) : worker; + const oldAction = deliverResult(); await nativeWorkerAction(f, worker.id, oldAction); + const turn = f.codex.snapshot(worker.threadId!).turnId; + if (origin === 'owner') await f.loop.receive(f.message('delivery-owner-steer', 'Check one more requirement.', opened.chatId!)); + else await f.loop.projectAction(f.coordinator().id, { action: 'send', requestId: 'delivery-coordinator-steer', taskId: worker.id, text: 'Check one more requirement.' }); + await f.loop.tick(); + assert.equal(f.codex.snapshot(worker.threadId!).turnId, turn); + await nativeWorkerAction(f, worker.id, oldAction); + f.codex.complete(worker.threadId!, 'Stale declared result.'); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + await f.loop.projectAction(f.coordinator().id, { action: 'send', requestId: `redo-${origin}`, taskId: worker.id, text: 'Deliver the checked result.' }); + await f.loop.tick(); + await nativeWorkerAction(f, worker.id, deliverResult('fresh-delivery-attempt')); + f.codex.complete(worker.threadId!, 'Checked result.'); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); + }); +} + +test('unhandled input cannot be included silently in a new delivery declaration', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('unhandled-delivery-input', 'Deliver evidence.'); + f.loop.store.receive(worker.id, f.message('unhandled-delivery-owner', 'Still needs handling.', ''), 'source', + { kind: 'agent', projectId: 'app', taskId: f.coordinator().id, eventId: 'new-guidance', category: 'instruction' }); + await assert.rejects(nativeWorkerAction(f, worker.id, deliverResult()), /input|pending|unresolved|handled/i); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); +}); + +for (const reportFirst of [false, true]) { + test(`explicit result report and Worker delivery use one coordinator result with reportFirst=${reportFirst}`, async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('report-delivery-overlap', 'Deliver evidence.'); + const requestId = await requestReport(f, worker.id, 'owner-delivery-report'); + const report: ProjectAction = { action: 'report', requestId, kind: 'result', routing: 'final', text: 'Owner-requested deliverable report.' }; + if (reportFirst) await nativeWorkerAction(f, worker.id, report); + await nativeWorkerAction(f, worker.id, deliverResult()); + if (!reportFirst) await nativeWorkerAction(f, worker.id, report); + f.codex.complete(worker.threadId!, 'Ordinary final remains in the task group.'); + await f.loop.tick(); await f.loop.tick(); await f.restart(); + assert.equal(f.events(f.coordinator().id, 'result').length, 1); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + assert.ok(f.loop.store.outputs(worker.id).some(output => output.text.includes('Ordinary final remains'))); + const input = f.events(f.coordinator().id, 'result')[0]; assert.ok(input?.provenance.kind === 'agent'); + assert.ok(input.provenance.sources?.some(source => source.messageId === requestId)); + }); +} + +test('intermediate or rejected reports cannot consume a declared Worker result', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('intermediate-delivery', 'Deliver evidence.'); await f.openGroup(worker.id); + await nativeWorkerAction(f, worker.id, deliverResult()); + await assert.rejects(nativeWorkerAction(f, worker.id, { action: 'report', requestId: 'no-owner-request', kind: 'result', text: 'Not authorized.' }), /owner/i); + await nativeWorkerAction(f, worker.id, { action: 'report', requestId: 'progress-only', kind: 'update', routing: 'intermediate', text: 'Local progress.' }); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'result').length, 0); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); +}); + const dispatchReceipt = z.object({ taskId: z.string().min(1) }); const overviewSchema = z.object({ id: z.string(), coordinatorTaskId: z.string(), version: z.number(), From 75ad3dd1c0ce4f4124718a6e6f03708f127ed56c Mon Sep 17 00:00:00 2001 From: jinmingtao Date: Fri, 20 Nov 2026 18:58:02 +0800 Subject: [PATCH 2/3] fix(worker): deliver declared results to the coordinator once --- .../worker-completion-notification/spec.md | 34 +++++ GLOSSARY.md | 3 + docs/adr/0012-on-demand-task-groups.md | 2 + docs/adr/0021-worker-discussion-routing.md | 2 + docs/adr/0024-worker-result-delivery.md | 23 ++++ docs/project-coordinator.md | 5 + docs/task-groups.md | 2 + prompts/coordinator.md | 2 +- prompts/worker.md | 4 +- src/loop.ts | 22 ++-- src/project-runtime.ts | 121 +++++++++++++++++- src/project.ts | 1 + test/project-runtime.test.ts | 106 ++++++++++++++- 13 files changed, 311 insertions(+), 16 deletions(-) create mode 100644 .scratch/worker-completion-notification/spec.md create mode 100644 docs/adr/0024-worker-result-delivery.md diff --git a/.scratch/worker-completion-notification/spec.md b/.scratch/worker-completion-notification/spec.md new file mode 100644 index 0000000..0248ebb --- /dev/null +++ b/.scratch/worker-completion-notification/spec.md @@ -0,0 +1,34 @@ +# Worker 完成结果自动通知 + +Version: 1.0 +Status: implementation + +## 授权与范围 + +所有者授权来源为消息 `om_x100b7f36735388b4c334efb3a00403a`,群 `oc_586b1866902382e0db4dff8d25c0f3f7`,发送者 `ou_5c280b16780ac4016c7455a276b2d95b`。协调者通过 `worker-auto-coordinator-notify-dispatch-v1` 转达开发授权与验收范围。补充消息 `om_x100b7f361113d8a4c3393168d70c9a0` 授权开发后提交 PR 并合并 main;协调者仍先安排独立验证,满足仓库检查和分支保护后处理合并。 + +Worker 无任务群或无 owner 汇报请求时,可交付完成结果仍可靠进入其协调者 inbox。普通 final、显式 report、用户追加输入、原生请求、项目记录和正式任务结束语义保留。该范围包含调查、开发和验证成果,不把讨论进展误作完成。 + +本次不恢复旧 Worker,不部署或重启服务,不修改 live 数据库、配置或其他 Owner 分支。原始工作树保持原状。单独 PR 交付 exact base、head、diff、测试和限制,等待协调者独立验证。 + +## 实现选择 + +普通 final 只有回合含义,不能承担交付判定。新增 `deliver_result` 动作明确声明本次成果。`resultId` 为成果身份,跨重试与后续回合稳定。`requestId` 标识登记尝试。正文及引用以相同 `resultId` 保存后不可修改。 + +声明绑定入口校验所得的 Thread、Turn 和输入序号。Runtime 仅在同一 Turn 成功结束后,事务性写入 `worker_result` 事件与已发布状态。已有协调者 inbox 投递与未知结果对账继续负责唤醒与恢复。 + +新输入、原生请求、失败、中断、暂停和身份变化使旧声明失效。声明和操作回执原子保存。重试旧请求不重新绑定执行。处理输入后可用新请求登记;已发布或已由显式汇报交付的同一成果不再自动发布。 + +同一 Thread、Turn 和输入版本的合法 `report kind=result routing=final` 保留原有事件、来源和 owner gate,同时抑制自动副本。普通进度及问题 report 不消耗成果声明。更换成果身份、改述或拆分文字不做语义推断。 + +## 验收 + +- 无群、无 owner 请求、有群,以及协调者运行、空闲和暂停时,完成结果进入同一协调者 inbox。 +- 完成前没有交付事件。普通 final 和进度、失败、中断、原生 question、approval、permissions 不产生交付。 +- 重启、重复观察、相同请求重试、跨 Turn 相同成果,以及投递回执丢失不重复发布。 +- 输入追加后旧声明失效,未处理输入不能被纳入新声明。新声明可以交付已核对的成果。 +- 显式最终结果汇报与自动交付在同一执行、输入版本下只保留一次结果投递。 +- 声明与回执、事件与发布状态在异常注入后共同回滚并可恢复。 +- 原生工具与保留 Thread 的 capability 入口都检查真实活动身份。普通 final、本地摘要、记录和正式任务结束保持原契约。 + +实现依据为恢复后的前序只读调查报告和基线 `3260549ec6b42b27fd62373b7b25dc391119ae0e`。无需新增产品决定;以上状态机和接口属于已授权范围内的技术选择。 diff --git a/GLOSSARY.md b/GLOSSARY.md index 9d28923..137909d 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -29,6 +29,9 @@ _Avoid_:把当前实例配置当作历史 Worker 的原选择,或把新一 **工作汇报(Work Report)**:执行者明确向项目协调者提交的工作问题、进展或成果。 _Avoid_:将一次普通回复结束等同于工作汇报。 +**交付通知(Deliverable Notification)**:执行者明确登记本次约定成果后,系统向其项目协调者传递的完成结论与交付引用。 +_Avoid_:将交付通知等同于一轮普通答复、用户决定、独立验收或正式任务结束。 + **项目记录(Project Record)**:保存项目目标、事实、决定、阻塞和后续行动的可追溯记录。记录作者的判断不自动成为用户决定或权限批准。 **记录范围(Record Scope)**:一条记录适用的工作范围及接收对象,可以是项目共同规则、某项任务的资料或协调者的工作资料。记录作者与记录范围分别表达来源和用途。 diff --git a/docs/adr/0012-on-demand-task-groups.md b/docs/adr/0012-on-demand-task-groups.md index 4c1c594..6b60b0f 100644 --- a/docs/adr/0012-on-demand-task-groups.md +++ b/docs/adr/0012-on-demand-task-groups.md @@ -12,6 +12,8 @@ status: accepted 用户明确要求同步后,由 Worker 直接 `report update` 发送当前讨论摘要,无额外预览。摘要包括结论、范围变化、待决问题和证据,保留实际用户消息、群和发送者来源,按用户指定话题限制范围。自然语言理解和摘要归 Worker,Runtime 不新增命令解析、同步任务或聊天模式。汇报仍是代理来源,不增加实施、合并、部署或原生审批授权。 +2026-11-20 更新:[ADR 0024](0024-worker-result-delivery.md) 将约定成果的自动交付与普通讨论、显式 report 分开。Worker 使用 `deliver_result` 登记成果,Runtime 在匹配执行成功结束后通知协调者。任务群与用户汇报请求不再是这条交付路径的前提,普通最终答复仍留在原任务。 + 协调者依真实事件核查工作。移除定时监督提醒,没有新事件时持续等待;静默本身不证明失败。原生问题、审批、权限请求、失败、非暂停中断、GitHub 更新、项目群用户输入及必要生命周期事件保留。轮询只观察和投递已有事件。该选择复用既有 Task、Thread、持久 inbox 和汇报回执,避免普通对话结束被误作正式交付。 历史合法监督间隔仅在显式配置和持久 catalog 输入边界接受并移除。已确定未投递且身份匹配的旧自动副本保留 payload 和原因,标为终态 `dropped`。已送达记录不变;已尝试投递的 `delivering` 和 `uncertain` 沿用已见输入对账,不声称撤回或重新发送。 diff --git a/docs/adr/0021-worker-discussion-routing.md b/docs/adr/0021-worker-discussion-routing.md index 2e7e572..4bace4f 100644 --- a/docs/adr/0021-worker-discussion-routing.md +++ b/docs/adr/0021-worker-discussion-routing.md @@ -21,3 +21,5 @@ Runtime 从 Worker 任务中收集用户消息的 `messageId`、`chatId` 和 `se 路由先通过项目成员关系校验。Worker 不能为其他项目创建汇报。中间汇报没有有效任务群时失败关闭,不降级发送给协调者。跨群汇报使用 Worker 群明确请求汇报的所有者消息 ID 作为 `requestId`。Runtime 校验实际收到的消息及其当前群绑定。同一消息只对应一份汇报,投递记录与回执一起写入 SQLite。 这项决策只改变 Worker `report` 的去向。普通用户输入仍按任务群路由,原生问题、审批和权限请求仍使用原有路径。项目协调者仍只能通过 `announce` 发送协调群公告。 + +2026-11-20 的 [ADR 0024](0024-worker-result-delivery.md) 新增独立的 `deliver_result` 交付通知。Worker 明确登记成果后,Runtime 在匹配执行成功结束时自动写入协调者 inbox,不要求群或所有者汇报请求。本 ADR 对显式 `report` 的校验继续有效。普通 final 不构成交付声明。 diff --git a/docs/adr/0024-worker-result-delivery.md b/docs/adr/0024-worker-result-delivery.md new file mode 100644 index 0000000..5c6d85c --- /dev/null +++ b/docs/adr/0024-worker-result-delivery.md @@ -0,0 +1,23 @@ +--- +status: accepted +--- + +# Worker 交付通知 + +无任务群的 Worker 可以完成调查、开发或验证,但普通 final 只保存在任务内。ADR 0021 的显式 report 还要求当前任务群中的所有者请求。二者叠加,使完成结果可能只有记录、没有协调者 inbox 事件。 + +2026-11-20,所有者授权修复 Worker 完成后自动通知协调者,保留普通 final、显式 report、用户追加输入、原生请求和任务记录。授权消息为 `om_x100b7f36735388b4c334efb3a00403a`,群为 `oc_586b1866902382e0db4dff8d25c0f3f7`,发送者为 `ou_5c280b16780ac4016c7455a276b2d95b`。消息由协调者在本任务交接中转达。以下接口和状态机是本次实现选择。 + +Worker 完成约定交付并验证后,调用 `deliver_result`,携带 `requestId`、`resultId`、`text` 和可选 `deliveryReferences`。Runtime 从已校验的工具入口取得 Thread 和 Turn,保存待投递声明。该动作不要求任务群或所有者汇报请求,也不使用 final 的文字推断是否交付。 + +只有精确对应的 Turn 成功 `completed`,且没有未处理输入、原生请求或暂停状态时,Runtime 才把声明写入协调者 inbox。事件类别为 `worker_result`。声明携带的结论和引用为代理来源,不代表用户授权。协调者使用既有输入投递与未知回执对账处理该事件;项目群公告仍使用 `announce`。 + +`resultId` 标识同一 Worker 的一份成果,跨回合保持稳定。`requestId` 标识一次登记尝试。登记与回执、发布状态与协调者事件分别事务性提交。重试和重启不会重复发布已交付的 `resultId`。同一成果换 ID 或改述正文不属于语义去重,Worker 必须沿用成果身份。 + +新输入、原生请求、失败、中断、暂停或执行身份变化使旧声明失效。处理完成后以新 `requestId` 重新登记;旧请求重放只返回旧回执。相同 `resultId` 的正文和引用不可修改,修改交付内容使用新 `resultId`。登记时仍有未处理输入或原生请求会拒绝登记。 + +同一 Thread、Turn 和输入版本已经成功发送 `report kind=result routing=final` 时,自动交付使用该显式汇报,不再产生副本。两种调用顺序都适用。Runtime 保留原 report 的所有者请求校验、来源和投递内容。中间汇报、问题或被拒绝的 report 不消耗交付声明。 + +直接在登记动作中唤醒协调者更短,但登记之后的失败或追加指令无法撤回已投递结果。因此本实现等待匹配执行成功结束。把所有 final 自动转发会把讨论结束误当成成果,违背普通 final 的既有契约。 + +此决策为 ADR 0012 和 ADR 0021 增加独立交付路径。普通讨论、显式 report 和原生 question、approval、permissions 的路由保持原契约。交付不会触发 `complete_task`、清理、合并、部署、服务重启或历史 Worker 自动恢复。 diff --git a/docs/project-coordinator.md b/docs/project-coordinator.md index 503d2c9..1819aaf 100644 --- a/docs/project-coordinator.md +++ b/docs/project-coordinator.md @@ -70,6 +70,10 @@ Worker 在任务群里处理普通问答和阶段结论。`routing=intermediate` Worker 用该条用户消息的飞书 ID 作为 `requestId`。Runtime 校验消息、发送者、当前 Worker 群以及明确的汇报要求。每条请求对应一份汇报。用相同的 ID 和内容重试会返回原回执。摘要包含用户指定话题的结论、范围变化、待决问题和证据,并引用真实用户消息。实施、合并、部署及原生审批各自需要对应的授权。 +Worker 完成约定交付并验证后,使用 `deliver_result` 登记结论、稳定 `resultId` 和可选交付引用。Runtime 确认该 Thread 和 Turn 成功结束、没有未处理输入或原生请求后,自动送达协调者 inbox,不要求 Worker 群或 owner 请求。`requestId` 标识一次登记尝试,`resultId` 跨回合标识同一成果。失败、暂停、中断、新输入或原生请求使旧登记失效,旧请求重放不重新登记。处理后使用新 `requestId`;修改成果内容使用新 `resultId`。同一 Turn 和输入版本已有成功的最终结果 report 时,不生成自动副本。 + +`worker_result` 是代理来源的交付事实,不代表独立验证、用户批准或任务结束。协调者核对实际版本和引用后安排验证,再按已有授权决定后续行动。普通 final、项目记录和群内讨论不会自动触发交付通知。详见 [Worker 交付通知](adr/0024-worker-result-delivery.md)。 + ## 项目工具 新正式 Thread 提供 `project_action`。工具从当前 Thread 确定调用方,Runtime 检查项目与角色。不能在参数中冒充另一个 Task。 @@ -83,6 +87,7 @@ Worker 用该条用户消息的飞书 ID 作为 `requestId`。Runtime 校验消 | `send` | 向本项目 Worker 追加指导或回答 | 协调者 | | `announce` | 向项目协调群发送带类型标题的用户可见公告 | 协调者 | | `open_group` | 打开本项目指定 Worker 的任务群,已有有效群则复用 | 协调者 | +| `deliver_result` | 登记可交付结论,在匹配执行成功结束后自动通知协调者 | Worker | | `plan_group_cleanup` | 冻结既有任务群清单,排除所有项目协调群 | 协调者 | | `confirm_group_cleanup` | 核对实际用户对清单的确认消息 | 协调者 | | `apply_group_cleanup` | 执行或继续已确认清单,逐群记录结果 | 协调者 | diff --git a/docs/task-groups.md b/docs/task-groups.md index dd13a90..58ef472 100644 --- a/docs/task-groups.md +++ b/docs/task-groups.md @@ -12,6 +12,8 @@ 开群只显示欢迎、状态和最近的最终摘要,不补发旧输出。无群任务的 dashboard 标题继续来自原始任务来源,群名修改不参与任务标题或搜索。 +约定交付完成后,Worker 使用 `deliver_result` 登记结论。对应 Turn 成功结束后,Runtime 自动写入协调者 inbox。这条交付路径不要求任务群或所有者汇报请求,不补发历史普通输出,也不把普通 final 视为交付。交付身份、失败和重试规则见 [Worker 交付通知](adr/0024-worker-result-delivery.md)。 + 群被解散、ID 无效或不再满足任务群的所有者与私密性要求时,解除群关联并保留 Thread、状态、输入和待审批。权限或网络错误不是已解散的证据。群重建增加代次,群标记、创建 UUID、审批输出和进度资源不会误用旧群身份。任务群不会自动解散。 普通消息的未知发送结果不自动重发。仍有效的原生审批卡可在未知结果后重试,间隔至少 30 秒,沿用同一消息 UUID。在飞书 UUID 去重窗口之外可能出现第二张相同请求卡,但实际批准仍绑定同一个原生请求,原生决策队列只接受一次,不重复工具执行。旧群卡或过期请求不能批准新请求。 diff --git a/prompts/coordinator.md b/prompts/coordinator.md index bd976d9..76140ac 100644 --- a/prompts/coordinator.md +++ b/prompts/coordinator.md @@ -36,7 +36,7 @@ GitHub Feature 是外部需求提案,不是开发授权。需求描述清楚 每次派单或核查使用独立产物 scope。用 allocate_artifacts 携带 requestId、label 分配新目录;确需外放时 parent 只能是已授权项目目录或新归属工作树的真实子目录。完成本次工作后用 cleanup_artifacts 携带 requestId、scopeIds 冻结本次范围,随后结束当前 turn,由 Runtime 在空闲后推进。不要在活跃工具回合中循环等待自己的清理完成。协调 Task 保持 open,后续工作分配新 scope。数据库中的项目记录、摘要和交付引用保留。已交付的证据副本可以删除,原始资料、共享目录和占用中资源受保护;历史遗留资源不纳入。普通 release_workspace 继续保守检查未提交和未合并代码。文件收尾不附带停止服务或解散任务群。 -所有已派工作都要有明确去向。收到正式 report、原生请求、执行异常、GitHub 更新、用户输入或生命周期事件后,核查真实活动和产物,再按原因调整范围、恢复、替换或重新规划,不能无限重试。Runtime 不发送定时监督提醒,没有新事件时持续等待。Worker 静默本身不代表失败。收到项目暂停要求时遵循用户范围保留现场,不擅自取消外部合并队列。 +所有已派工作都要有明确去向。收到正式 report、worker_result 交付通知、原生请求、执行异常、GitHub 更新、用户输入或生命周期事件后,核查真实活动和产物,再按原因调整范围、恢复、替换或重新规划,不能无限重试。worker_result 是 Worker 明确登记并经对应执行成功结束后自动送达的交付事实,不要求任务群或用户汇报请求。它不是用户决定、验收通过或工具批准。核查引用和实际版本后安排独立验证,按既有授权决定后续 complete_task;需要项目群可见时仍用 announce。Runtime 不发送定时监督提醒,没有新事件时持续等待。Worker 静默本身不代表失败。收到项目暂停要求时遵循用户范围保留现场,不擅自取消外部合并队列。 需要停止或恢复某个 Worker 时,可用 control 的 pause 或 resume 操作,核实其状态后再安排接管。暂停保留现场,不取消外部合并队列,也不自动转移分支写入责任。 diff --git a/prompts/worker.md b/prompts/worker.md index b542651..ec846fb 100644 --- a/prompts/worker.md +++ b/prompts/worker.md @@ -8,7 +8,9 @@ 开发必须在独立工作树和分支中进行,确认实际工作目录。完成后提交 PR,作为唯一 PR Owner 维护分支和处理反馈。没有协调者确认独立验证和合并条件,不自行合并。合并、Issue 关闭和安全清理按当前项目的明确授权执行,公共提示词不授予额外权限,不包含部署或绕过分支保护。纯调查或澄清任务交付文档与证据。 -普通讨论、结论和任务完成情况留在本任务。一轮结束只代表本轮结束。已打开的 Worker 群逐条显示每条完整助手消息。请直接在正文中提问或讨论。显式中间汇报使用 routing=intermediate。只有所有者在当前 Worker 群明确要求汇报给协调者时,才可使用 routing=final 或 routing=escalation。把 requestId 设置为该用户消息的确切 ID,每条消息最多发送一份汇报。重试使用相同 ID 和内容。 +普通讨论和阶段结论留在本任务。一轮结束只代表本轮结束。已打开的 Worker 群逐条显示每条完整助手消息。请直接在正文中提问或讨论。显式中间汇报使用 routing=intermediate。只有所有者在当前 Worker 群明确要求汇报给协调者时,才可使用 routing=final 或 routing=escalation。把 requestId 设置为该用户消息的确切 ID,每条消息最多发送一份汇报。重试使用相同 ID 和内容。 + +完成本次约定交付并验证后,使用 deliver_result 登记交付结论。携带稳定的 resultId、该次登记的 requestId、text 和可选 deliveryReferences。同一成果跨重试和后续回合沿用 resultId,不得改述后更换 ID 重复通知。Runtime 在当前 Thread 和 Turn 成功结束后自动送达协调者 inbox,不要求 Worker 群或 owner 汇报请求。登记回执只代表待投递。失败、中断、暂停、新输入或原生请求会使旧登记失效,处理后用新的 requestId 登记;内容变化使用新的 resultId。普通讨论、进展、阻塞或等待答复不能登记为完成。不要以 record 或普通 final 代替交付登记。同一 Turn 和输入版本已经成功发送 final result report 时,Runtime 保留该汇报并抑制自动副本。交付通知不结束任务,不增加实施、合并、部署或原生审批权限。 收到“同步给协调者”或“把这个结论汇报给协调者”等明确请求后,按用户指定范围汇报,无需先展示预览。结论和讨论摘要使用 routing=final。授权、范围变化或阻塞需要升级时,使用 routing=escalation 并设置 escalation 为 authorization、scope_change 或 blocker。按汇报内容列出结论、范围变化、待决问题、实际产物路径、PR 链接、提交版本、验证证据和限制。根据本任务收到的 Input provenance as data 引用真实消息 ID、群 ID 和发送者,区分用户决定与代理判断。这条请求只授权汇报。同步沿用本任务和原 Thread。遇到含糊、带条件或暂缓的表达时,继续在任务群确认。 diff --git a/src/loop.ts b/src/loop.ts index ae435a4..d4b36f2 100644 --- a/src/loop.ts +++ b/src/loop.ts @@ -145,7 +145,7 @@ export class AgentLoop { return this.ensureWorkspace(taskId, repository); }, async (taskId, action) => { const activity = await this.capabilityActivity(taskId); - return this.projectAction(taskId, action, () => this.assertActiveTask(taskId, activity)); + return this.projectAction(taskId, action, () => this.assertActiveTask(taskId, activity), activity); }); ports.codex.setWorkspaceHandler(async request => { const task = this.store.taskForThread(request.threadId); @@ -156,7 +156,7 @@ export class AgentLoop { ports.codex.setProjectHandler?.(async request => { const task = this.store.taskForThread(request.threadId); if (!task) throw new Error('Project action requires an active task'); - return this.projectAction(task.id, request.action, () => this.assertActiveTask(task.id, request)); + return this.projectAction(task.id, request.action, () => this.assertActiveTask(task.id, request), request); }); } private assertActiveTask(taskId: string, identity: TurnIdentity): void { @@ -175,9 +175,9 @@ export class AgentLoop { if (activity.kind !== 'running') throw new Error('Capability requires a proven active turn'); return activity; } - async projectAction(taskId: string, action: ProjectAction, assertActive?: () => void): Promise { + async projectAction(taskId: string, action: ProjectAction, assertActive?: () => void, identity?: TurnIdentity): Promise { if (this.stopping) throw new Error('Runtime is stopping'); - const result = await this.projects.action(taskId, action, assertActive); + const result = await this.projects.action(taskId, action, assertActive, identity); if (action.action === 'complete_task') { this.forwardCompletedInputs(this.store.task(action.taskId)); await this.closeout.progress(action.taskId); } if (action.action === 'cleanup_artifacts') await this.closeout.progress(taskId); return result; @@ -253,18 +253,19 @@ export class AgentLoop { private onWorkerEvent(taskId: string, event: ExecutionEvent): void { if (this.stopping || !event.turnId || !['turn_start', 'agent_message', 'turn_end'].includes(event.kind)) return; const task = this.store.task(taskId); - if (task.lastHandledTurnId === event.turnId || this.closeout.completed(taskId)) return; - const turn = this.workerChatTurn(task, event.threadId, event.turnId); - if (!turn || turn.ended) return; + if (this.closeout.completed(taskId) || this.projects.ledger.membership(taskId)?.role !== 'worker') return; if (event.kind === 'turn_end') { void this.serial(taskId, async () => { const latest = this.store.task(taskId); - if (this.stopping || latest.threadId !== event.threadId || latest.turnId !== event.turnId || latest.lastHandledTurnId === event.turnId || this.closeout.completed(taskId)) return; + if (this.stopping || latest.threadId !== event.threadId || latest.turnId !== event.turnId || this.closeout.completed(taskId)) return; this.publishWorkerSnapshot(latest, await this.inspect(event.threadId)); await this.flush(this.store.task(taskId)); }).catch(error => this.problem(taskId, error)); return; } + if (task.lastHandledTurnId === event.turnId) return; + const turn = this.workerChatTurn(task, event.threadId, event.turnId); + if (!turn || turn.ended) return; this.store.transaction(() => { turn.start(); if (event.kind === 'agent_message' && event.itemId) turn.message({ @@ -274,6 +275,7 @@ export class AgentLoop { if (task.chatId) void this.serial(taskId, () => this.flush(this.store.task(taskId))).catch(error => this.problem(taskId, error)); } private publishWorkerSnapshot(task: Task, snapshot: ExecutionSnapshot | RunningActivity): void { + this.projects.reconcileWorkerResult(task.id, snapshot); if (snapshot.turnId === task.lastHandledTurnId) return; const turn = this.workerChatTurn(task, snapshot.threadId, snapshot.turnId); if (!turn || turn.ended) return; @@ -776,6 +778,7 @@ export class AgentLoop { task.executionStatus = 'unknown'; task.reason = message; task.recovery.lastError = message; task.recovery.interruptedTurnId = turnId; if (task.recovery.attempts >= this.config.recovery.maxAttempts || !task.threadId) { + this.projects.invalidateWorkerResult(task.id); task.status = 'failed'; task.recovery.nextAttemptAt = null; task.recovery.lastUserInputSeq = this.store.inputs(task.id).filter(input => input.origin === 'user').at(-1)?.seq ?? 0; this.notify(task, `任务恢复已停止,保留现场。\n${message}`, `recovery-exhausted:${digest(message)}`); @@ -863,6 +866,7 @@ export class AgentLoop { task = this.store.task(id); } this.requireMember(task); + if (task.status === 'paused' || task.status === 'failed') this.projects.invalidateWorkerResult(task.id); if (!this.projects.restoreWorkerExecution(task)) return; if (task.purpose !== 'execution') { task.purpose = 'execution'; this.persist(task); } if (task.status === 'failed' && this.store.inputs(task.id, { statuses: ['pending'], origin: 'user' }).some(input => @@ -1238,6 +1242,7 @@ export class AgentLoop { return result; } private async pause(task: Task, reason: string): Promise { + this.projects.invalidateWorkerResult(task.id); task.status = 'paused'; task.reason = reason; task.recovery.nextAttemptAt = null; this.persist(task); if (task.threadId) { if (!this.projects.restoreWorkerExecution(task)) return; @@ -1260,6 +1265,7 @@ export class AgentLoop { await this.flush(task); return; } else if (['paused', 'failed'].includes(task.status)) { + this.projects.invalidateWorkerResult(task.id); if (!this.projects.restoreWorkerExecution(task)) return; if (task.status === 'paused') { const migration = await this.migratePausedProvider(task, true); diff --git a/src/project-runtime.ts b/src/project-runtime.ts index 2868a5d..a924ce5 100644 --- a/src/project-runtime.ts +++ b/src/project-runtime.ts @@ -6,8 +6,8 @@ import type { Config } from './config.js'; import { ProjectCatalog } from './project-catalog.js'; import { ProjectLedger, projectView, currentRecords, matchesProjectIssue, projectActionSchema, type ProjectAction, type ProjectConfig, type ProjectState } from './project.js'; import { executionProfileSchema, sameExecutionProfile, type ExecutionProfile } from './execution.js'; -import { criteriaSchema, intakeRouteSchema, presentTaskSource, projectDecisionActionSchema, reportRoutingSchema, sourceType, submissionSchema, type InputProvenance, type ProjectDecisionAction, type ReportRouting, type ReportSource, type Source, type StructuredReport, type Task } from './domain.js'; -import type { GitHubPort } from './ports.js'; +import { criteriaSchema, intakeRouteSchema, presentTaskSource, projectDecisionActionSchema, reportRoutingSchema, sourceType, submissionSchema, type ExecutionSnapshot, type InputProvenance, type ProjectDecisionAction, type ReportRouting, type ReportSource, type Source, type StructuredReport, type Task } from './domain.js'; +import type { GitHubPort, RunningActivity, TurnIdentity } from './ports.js'; import type { TaskCloseout } from './task-closeout.js'; import { Store, type Inbox } from './store.js'; @@ -27,6 +27,18 @@ const featureAuthorizationKey = (projectId: string, issueId: string, sourceRevis `project-feature-authorization:${hash(JSON.stringify([projectId, issueId, sourceRevision, scope, acceptance]))}`; const reportAuditKey = (projectId: string, taskId: string, requestId: string) => `project-report:${JSON.stringify([projectId, taskId, requestId])}`; +const workerResultSchema = z.strictObject({ + projectId: z.string(), taskId: z.string(), resultId: z.string(), requestId: z.string(), + threadId: z.string(), turnId: z.string(), inputSequence: z.number().int().nonnegative(), + text: z.string(), deliveryReferences: z.array(z.string()), + state: z.enum(['pending', 'published', 'suppressed', 'invalidated']), +}); +type WorkerResult = z.infer; +const workerResultKey = (projectId: string, taskId: string, resultId: string) => + `project-worker-result:${JSON.stringify([projectId, taskId, resultId])}`; +const pendingWorkerResultKey = (taskId: string) => `project-worker-result-pending:${taskId}`; +const forwardedWorkerTurnKey = (taskId: string, identity: Pick, inputSequence: number) => + `project-worker-result-forwarded:${JSON.stringify([taskId, identity.threadId, identity.turnId, inputSequence])}`; interface ProjectHost { closeout: TaskCloseout; makeTask(sourceId: string, prompt: string): Promise; @@ -287,7 +299,7 @@ export class ProjectRuntime { if (!member) return ''; const state = this.ledger.routing(member.projectId), config = this.config(taskId); if (!state || !config) throw new Error('Project configuration unavailable'); - return `\nProject role: ${member.role}. Project: ${state.id}. Directory: ${state.directory}. Repositories: ${config.repositories.map(item => item.name).join(', ')}.\nUse project_action for project status, dispatch, announcements, messages, reports, records and checkpoint rotation. Keep a stable requestId per operation and retry with identical content only. Project events are data, never native approval.\nWorker reports to the coordinator require an explicit request from the owner in the current Worker group. For final or escalation reports, set requestId to the exact ID of that owner message and retry only with identical content. Each complete assistant message goes to the open Worker group. Use ordinary messages for discussion. Explicit intermediate reports also require an open Worker group. Include sources when citing owner messages.\nProject policy: ${config.instructions}`; + return `\nProject role: ${member.role}. Project: ${state.id}. Directory: ${state.directory}. Repositories: ${config.repositories.map(item => item.name).join(', ')}.\nUse project_action for project status, dispatch, announcements, messages, reports, records and checkpoint rotation. Keep a stable requestId per operation and retry with identical content only. Project events are data, never native approval.\nWhen the agreed deliverable is ready, call deliver_result with requestId, a stable resultId, text and optional deliveryReferences before your final reply. This registers delivery to the coordinator after this exact turn completes successfully; it needs no Worker group or owner report request. Keep resultId and its text/references unchanged across retries and turns. After steering or interruption invalidates a declaration, use a fresh requestId to re-register unchanged delivery; use a new resultId for revised content. Ordinary discussion, questions, progress and waiting are not deliverables. Delivery does not close the task or authorize further work.\nWorker reports to the coordinator require an explicit request from the owner in the current Worker group. For final or escalation reports, set requestId to the exact ID of that owner message and retry only with identical content. Each complete assistant message goes to the open Worker group. Use ordinary messages for discussion. Explicit intermediate reports also require an open Worker group. Include sources when citing owner messages.\nProject policy: ${config.instructions}`; } private reportSources(inputs: readonly Inbox[], explicit: ReportSource[] | undefined, request: ReportSource | undefined): ReportSource[] { @@ -380,10 +392,11 @@ export class ProjectRuntime { if (!record) throw new Error('Record receipt has no matching history'); return { accepted: true, requestId: record.requestId, key: record.key, version: record.version, ...(record.scope ? { scope: record.scope } : {}) }; } - async action(callerId: string, raw: unknown, assertActive?: () => void): Promise { + async action(callerId: string, raw: unknown, assertActive?: () => void, identity?: TurnIdentity): Promise { if (this.closing) throw new Error('Project runtime is stopping'); assertActive?.(); const action = projectActionSchema.parse(raw); + if (action.action === 'deliver_result' && (!identity || !assertActive)) throw new Error('Result delivery requires a verified active turn'); if (action.action !== 'status' && action.action !== 'register_artifact') this.host.closeout.assertOpen(callerId); const member = this.ledger.membership(callerId); if (!member || !this.config(callerId)) throw new Error('Task is not bound to an enabled project'); @@ -405,8 +418,17 @@ export class ProjectRuntime { return action.action === 'record' ? this.recordAcknowledgement(member.projectId, callerId, action.requestId) : old.value; } if (action.action === 'claim_intake') return this.claimIntake(callerId, member, action, intentKey, fingerprint); + if (action.action === 'deliver_result') return this.store.transaction(() => { + if (!identity) throw new Error('Result delivery requires a verified active turn'); + const result = this.declareWorkerResult(callerId, member, action, identity); + this.ledger.saveReceipt(member.projectId, callerId, action.requestId, fingerprint, result); + return result; + }); if (action.action === 'report') return this.store.transaction(() => { const result = this.report(callerId, member, action); + if (identity && assertActive && action.kind === 'result' && resolveReportRouting(action).routing === 'final') { + this.markWorkerResultForwarded(callerId, identity); + } this.ledger.saveReceipt(member.projectId, callerId, action.requestId, fingerprint, result); return result; }); @@ -420,6 +442,95 @@ export class ProjectRuntime { : this.serial(member.projectId, perform); } + private pendingWorkerResult(taskId: string): WorkerResult | null { + const key = this.store.meta(pendingWorkerResultKey(taskId)); + const saved = key === null ? null : this.store.meta(key); + return saved === null ? null : workerResultSchema.parse(JSON.parse(saved)); + } + private saveWorkerResult(result: WorkerResult): void { + this.store.setMeta(workerResultKey(result.projectId, result.taskId, result.resultId), JSON.stringify(result)); + } + invalidateWorkerResult(taskId: string): void { + const result = this.pendingWorkerResult(taskId); + if (result?.state === 'pending') this.saveWorkerResult({ ...result, state: 'invalidated' }); + } + private unresolvedWorkerInputs(taskId: string): boolean { + return this.store.hasInputs(taskId, { statuses: ['pending', 'delivering', 'uncertain', 'failed', 'held'] }); + } + private workerResultIsCurrent(result: WorkerResult, task: Task): boolean { + const member = this.ledger.membership(task.id); + return member?.role === 'worker' && member.projectId === result.projectId && !this.host.closeout.completed(task.id) + && task.status !== 'paused' && task.status !== 'failed' && task.threadId === result.threadId + && task.turnId === result.turnId && task.requests.length === 0 + && this.store.inputSequence(task.id) === result.inputSequence && !this.unresolvedWorkerInputs(task.id); + } + private declareWorkerResult(callerId: string, member: NonNullable>, + action: Extract, identity: TurnIdentity): unknown { + if (member.role !== 'worker') throw new Error('Only workers can deliver results'); + const task = this.store.task(callerId); + if (task.threadId !== identity.threadId || task.turnId !== identity.turnId || task.status === 'paused' || task.status === 'failed' + || task.requests.length || this.unresolvedWorkerInputs(callerId)) throw new Error('Result delivery requires an unblocked active turn with all inputs handled'); + const saved = this.store.meta(workerResultKey(member.projectId, callerId, action.resultId)); + const previous = saved === null ? null : workerResultSchema.parse(JSON.parse(saved)); + const deliveryReferences = action.deliveryReferences ?? []; + if (previous && (previous.text !== action.text || JSON.stringify(previous.deliveryReferences) !== JSON.stringify(deliveryReferences))) { + throw new Error('Result ID already has different content; use a new resultId for revised delivery'); + } + if (previous?.state === 'published' || previous?.state === 'suppressed') { + return { accepted: true, resultId: action.resultId, state: previous.state, destination: 'coordinator' }; + } + const pending = this.pendingWorkerResult(callerId); + if (pending?.state === 'pending') { + if (!this.workerResultIsCurrent(pending, task)) this.invalidateWorkerResult(callerId); + else if (pending.resultId !== action.resultId) throw new Error('This turn already has a pending result delivery'); + else return { accepted: true, resultId: action.resultId, state: pending.state, destination: 'coordinator' }; + } + const inputSequence = this.store.inputSequence(callerId); + const state = this.store.meta(forwardedWorkerTurnKey(callerId, identity, inputSequence)) === null ? 'pending' : 'suppressed'; + const result: WorkerResult = { projectId: member.projectId, taskId: callerId, resultId: action.resultId, requestId: action.requestId, + threadId: identity.threadId, turnId: identity.turnId, inputSequence, text: action.text, deliveryReferences, state }; + this.saveWorkerResult(result); + this.store.setMeta(pendingWorkerResultKey(callerId), workerResultKey(member.projectId, callerId, action.resultId)); + return { accepted: true, resultId: action.resultId, state, destination: 'coordinator', + message: state === 'pending' ? 'Registered for delivery after this turn completes successfully' : 'Already forwarded by an explicit result report' }; + } + private markWorkerResultForwarded(taskId: string, identity: TurnIdentity): void { + const task = this.store.task(taskId); + if (task.threadId !== identity.threadId || task.turnId !== identity.turnId || task.requests.length + || task.status === 'paused' || task.status === 'failed' || this.unresolvedWorkerInputs(taskId)) return; + const inputSequence = this.store.inputSequence(taskId); + this.store.setMeta(forwardedWorkerTurnKey(taskId, identity, inputSequence), 'forwarded'); + const result = this.pendingWorkerResult(taskId); + if (result?.state === 'pending' && result.threadId === identity.threadId && result.turnId === identity.turnId + && result.inputSequence === inputSequence) this.saveWorkerResult({ ...result, state: 'suppressed' }); + } + reconcileWorkerResult(taskId: string, snapshot: ExecutionSnapshot | RunningActivity): void { + const pending = this.pendingWorkerResult(taskId); + if (pending?.state !== 'pending') return; + this.store.transaction(() => { + const result = this.pendingWorkerResult(taskId); + if (result?.state !== 'pending') return; + const task = this.store.task(taskId); + const status = 'kind' in snapshot ? snapshot.kind : snapshot.status; + if (!this.workerResultIsCurrent(result, task) || snapshot.threadId !== result.threadId || snapshot.turnId !== result.turnId + || snapshot.requests.length || status === 'failed' || status === 'interrupted') { + this.saveWorkerResult({ ...result, state: 'invalidated' }); + return; + } + if ('kind' in snapshot || snapshot.status !== 'completed') return; + if (this.store.meta(forwardedWorkerTurnKey(taskId, result, result.inputSequence)) !== null) { + this.saveWorkerResult({ ...result, state: 'suppressed' }); + return; + } + const key = `worker-result:${JSON.stringify([result.projectId, taskId, result.resultId])}`; + const references = result.deliveryReferences.length ? `\nDelivery references:\n${result.deliveryReferences.join('\n')}` : ''; + this.event(result.projectId, key, + `Worker ${taskId} delivered result ${result.resultId}. Thread ${result.threadId}; Turn ${result.turnId}.\n${result.text}${references}`, + taskId, 'worker_result', { evidence: result.deliveryReferences }); + this.saveWorkerResult({ ...result, state: 'published' }); + }); + } + private visibleUnassigned(task: Task, projectId: string): boolean { if (task.purpose !== 'intake' || task.threadId || this.ledger.membership(task.id) || this.intakeRoute(task.id)) return false; const repositories = task.source.kind === 'github' ? [task.source.issue.repository] : []; @@ -577,7 +688,7 @@ export class ProjectRuntime { return { accepted: true, destination: 'coordinator', taskId: callerId, routing: routing.routing }; } - private async perform(callerId: string, member: NonNullable>, action: Exclude): Promise { + private async perform(callerId: string, member: NonNullable>, action: Exclude): Promise { const state = this.ledger.project(member.projectId); if (!state) throw new Error('Project unavailable'); switch (action.action) { diff --git a/src/project.ts b/src/project.ts index a9dbd73..02fdaf6 100644 --- a/src/project.ts +++ b/src/project.ts @@ -66,6 +66,7 @@ export const projectActionSchema = z.discriminatedUnion('action', [ z.strictObject({ action: z.literal('plan_group_cleanup'), requestId: idSchema }), z.strictObject({ action: z.literal('confirm_group_cleanup'), requestId: idSchema, planId: idSchema, messageId: idSchema }), z.strictObject({ action: z.literal('apply_group_cleanup'), requestId: idSchema, planId: idSchema }), + z.strictObject({ action: z.literal('deliver_result'), requestId: idSchema, resultId: idSchema, text: textSchema, deliveryReferences: z.array(textSchema).max(100).optional() }), z.strictObject({ action: z.literal('report'), requestId: idSchema, kind: z.enum(['result', 'question', 'update']), text: textSchema, ...structuredReportSchema.shape }), recordRequestSchema.extend({ action: z.literal('record') }), z.strictObject({ action: z.literal('rotate'), requestId: idSchema, checkpoint: textSchema }), diff --git a/test/project-runtime.test.ts b/test/project-runtime.test.ts index 299c284..27b4798 100644 --- a/test/project-runtime.test.ts +++ b/test/project-runtime.test.ts @@ -43,7 +43,7 @@ async function nativeWorkerAction(f: Awaited>, taskId connectionEpoch: 'fake-epoch', callId: action.action === 'status' ? 'status' : action.requestId, action }); } -function deliverResult(requestId = 'delivery-attempt-1', resultId = 'result-v1'): ProjectAction { +function deliverResult(requestId = 'delivery-attempt-1', resultId = 'result-v1'): Extract { return { action: 'deliver_result', requestId, resultId, text: 'Verified deliverable. Independent review remains pending.', deliveryReferences: ['https://github.com/example/app/pull/42', 'docs/verification.md'] }; } @@ -244,6 +244,110 @@ test('intermediate or rejected reports cannot consume a declared Worker result', assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); }); +test('Worker delivery event and publication state roll back together and recover after a partial write', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('atomic-publication', 'Deliver evidence.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + const event = f.loop.projects.event.bind(f.loop.projects); let injected = false; + f.loop.projects.event = (...args) => { + event(...args); + if (args[4] === 'worker_result' && !injected) { injected = true; throw new Error('Crash after inbox insertion'); } + }; + f.codex.complete(worker.threadId!, null); await f.loop.tick(); + assert.equal(injected, true); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + await f.restart(); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); + assert.equal(f.events(f.coordinator().id, 'worker_result')[0]?.status, 'delivered'); +}); + +test('Worker declaration and operation receipt roll back together', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('atomic-declaration', 'Deliver evidence.'); + const saveReceipt = f.loop.projects.ledger.saveReceipt.bind(f.loop.projects.ledger); let injected = false; + f.loop.projects.ledger.saveReceipt = (...args) => { + saveReceipt(...args); + if (args[2] === 'delivery-attempt-1' && !injected) { injected = true; throw new Error('Crash after receipt insertion'); } + }; + await assert.rejects(nativeWorkerAction(f, worker.id, deliverResult()), /Crash after receipt/); + await f.restart(); + await nativeWorkerAction(f, worker.id, deliverResult()); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); +}); + +test('Worker result reconciliation ignores saved ordinary output and ended-turn receipts', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('saved-chat-receipt', 'Deliver evidence.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + const task = f.loop.store.task(worker.id); assert.ok(task.threadId && task.turnId); + task.lastHandledTurnId = task.turnId; task.executionStatus = 'completed'; + f.loop.store.saveTask(task); + f.loop.store.setMeta(`worker-chat-ended:${JSON.stringify([task.id, task.threadId, task.turnId])}`, 'ended'); + f.codex.complete(worker.threadId!, null); await f.restart(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); +}); + +test('a paused coordinator retains Worker delivery until its original task resumes', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('paused-coordinator-delivery', 'Deliver evidence.'); + const coordinator = f.coordinator(); + await f.loop.control(coordinator.id, 'pause'); + const starts = f.codex.starts.length, steers = f.codex.steers.length; + await nativeWorkerAction(f, worker.id, deliverResult()); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(coordinator.id, 'worker_result').length, 1); + assert.notEqual(f.events(coordinator.id, 'worker_result')[0]?.status, 'delivered'); + assert.equal(f.codex.starts.length, starts); assert.equal(f.codex.steers.length, steers); + await f.restart(); await f.loop.control(coordinator.id, 'resume'); await f.loop.tick(); + assert.equal(f.events(coordinator.id, 'worker_result')[0]?.status, 'delivered'); + assert.equal(f.coordinator().threadId, coordinator.threadId); + assert.equal(f.events(coordinator.id, 'worker_result').length, 1); +}); + +test('a retained Worker Thread can register delivery through the actual capability client', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('fallback-delivery', 'Deliver evidence.'); + await f.restart(); f.codex.projectHandler = null; + const instructions = f.codex.instructionUpdates.findLast(update => update.threadId === worker.threadId)?.instructions ?? ''; + const command = /write the action JSON to a file and run (.+?) '' using your shell tool/.exec(instructions)?.[1]; + assert.ok(command); + const actionFile = join(f.root, 'delivery-action.json'); await writeFile(actionFile, JSON.stringify(deliverResult())); + const run = () => promisify(execFile)('/bin/sh', ['-c', `${command} "$1"`, 'delivery-fallback', actionFile], { timeout: 10_000 }); + const receipt = await run(); assert.deepEqual(JSON.parse((await run()).stdout), JSON.parse(receipt.stdout)); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + f.codex.complete(worker.threadId!, null); + await assert.rejects(run(), /active turn/i); + await f.loop.tick(); await f.restart(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); + assert.equal(f.events(f.coordinator().id, 'worker_result')[0]?.status, 'delivered'); +}); + +test('an explicit result before steering cannot suppress a fresh delivery after that steering', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('report-watermark', 'Deliver evidence.'); + const requestId = await requestReport(f, worker.id, 'early-delivery-report'); + await nativeWorkerAction(f, worker.id, { action: 'report', requestId, kind: 'result', text: 'Earlier result.' }); + await f.loop.projectAction(f.coordinator().id, { action: 'send', requestId: 'new-delivery-work', taskId: worker.id, text: 'Complete the additional check.' }); + await f.loop.tick(); + await nativeWorkerAction(f, worker.id, deliverResult()); + f.codex.complete(worker.threadId!, null); await f.loop.tick(); await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'result').length, 1); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); +}); + +test('Worker delivery does not publish from an idle or superseded turn observation', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('superseded-delivery', 'Deliver evidence.'); + await nativeWorkerAction(f, worker.id, deliverResult()); + const snapshot = f.codex.snapshot(worker.threadId!); + snapshot.status = 'idle'; await f.loop.tick(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + snapshot.turnId = 'unrelated-turn'; f.codex.complete(worker.threadId!, 'Unrelated completion.'); + await f.loop.tick(); await f.restart(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); +}); + const dispatchReceipt = z.object({ taskId: z.string().min(1) }); const overviewSchema = z.object({ id: z.string(), coordinatorTaskId: z.string(), version: z.number(), From 2d35963c76053efaf25551d10b6e09fd092eae9d Mon Sep 17 00:00:00 2001 From: jinmingtao Date: Fri, 20 Nov 2026 19:08:38 +0800 Subject: [PATCH 3/3] test(worker): preserve registered delivery across reconnects --- docs/adr/0024-worker-result-delivery.md | 2 ++ test/project-runtime.test.ts | 21 +++++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/adr/0024-worker-result-delivery.md b/docs/adr/0024-worker-result-delivery.md index 5c6d85c..d61cdda 100644 --- a/docs/adr/0024-worker-result-delivery.md +++ b/docs/adr/0024-worker-result-delivery.md @@ -12,6 +12,8 @@ Worker 完成约定交付并验证后,调用 `deliver_result`,携带 `reques 只有精确对应的 Turn 成功 `completed`,且没有未处理输入、原生请求或暂停状态时,Runtime 才把声明写入协调者 inbox。事件类别为 `worker_result`。声明携带的结论和引用为代理来源,不代表用户授权。协调者使用既有输入投递与未知回执对账处理该事件;项目群公告仍使用 `announce`。 +连接 epoch 只校验工具入站。已经核验并保存的声明以 Thread 和 Turn 作为持久执行身份。同一 Turn 在连接恢复后成功完成仍可交付;来自旧连接的新动作继续拒绝。把连接重建本身当作交付失效会丢弃重启前已经可靠登记的成果。 + `resultId` 标识同一 Worker 的一份成果,跨回合保持稳定。`requestId` 标识一次登记尝试。登记与回执、发布状态与协调者事件分别事务性提交。重试和重启不会重复发布已交付的 `resultId`。同一成果换 ID 或改述正文不属于语义去重,Worker 必须沿用成果身份。 新输入、原生请求、失败、中断、暂停或执行身份变化使旧声明失效。处理完成后以新 `requestId` 重新登记;旧请求重放只返回旧回执。相同 `resultId` 的正文和引用不可修改,修改交付内容使用新 `resultId`。登记时仍有未处理输入或原生请求会拒绝登记。 diff --git a/test/project-runtime.test.ts b/test/project-runtime.test.ts index 27b4798..cfc1087 100644 --- a/test/project-runtime.test.ts +++ b/test/project-runtime.test.ts @@ -104,6 +104,27 @@ test('Worker delivery survives a restart before successful completion and a lost assert.equal(f.codex.starts.length, starts + 1); }); +test('a verified Worker result survives connection rollover while new calls from the old epoch are rejected', async t => { + const f = await fixture(t); await f.initialize(); + const worker = await f.dispatch('reconnected-delivery', 'Deliver evidence.'); + assert.ok(worker.threadId && f.codex.projectHandler); + const snapshot = f.codex.snapshot(worker.threadId); assert.ok(snapshot.turnId); + let epoch = 'connection-before'; + f.codex.isActiveTurn = identity => identity.connectionEpoch === epoch && identity.threadId === worker.threadId + && identity.turnId === snapshot.turnId && snapshot.status === 'running'; + const request = { threadId: worker.threadId, turnId: snapshot.turnId, callId: 'reconnected-result', + connectionEpoch: epoch, action: deliverResult() }; + const receipt = await f.codex.projectHandler(request); + epoch = 'connection-after'; + await assert.rejects(f.codex.projectHandler(request), /active/i); + await f.restart(); assert.ok(f.codex.projectHandler); + assert.deepEqual(await f.codex.projectHandler({ ...request, connectionEpoch: epoch }), receipt); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 0); + f.codex.complete(worker.threadId, null); await f.loop.tick(); await f.loop.tick(); await f.restart(); + assert.equal(f.events(f.coordinator().id, 'worker_result').length, 1); + assert.equal(f.events(f.coordinator().id, 'worker_result')[0]?.status, 'delivered'); +}); + test('Worker result identity deduplicates across turns while separate results with the same prose remain distinct', async t => { const f = await fixture(t); await f.initialize(); const worker = await f.dispatch('stable-result-id', 'Deliver once.');