Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Status: ready-for-agent

# Bind an explicit final acknowledgement to its report

Implement spec v1.0 in the report publication and final observation paths. Correct Worker guidance, retain stable request IDs and destination binding, and cover both local tool entry points. Deliver regression evidence and a PR for independent verification. No merge or live acceptance is authorized.

## Comments

The root cause entered with report-local publication in commit `4c9549558e0f2c3e17ff066349c7961ace103210`. Ordinary final publication remained independent. The exact recorded outputs are paraphrases, so matching equal text alone cannot repair this instance safely.
38 changes: 38 additions & 0 deletions .scratch/worker-group-reply-once/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
Status: ready-for-agent

# Worker group reply once

Version: 1.0, 2026-11-20.

The owner reported that one reply appeared twice in a task group and authorized investigation and repair. Source message `om_x100b60cad3b554b8c4b2cba1d5b3e75`, project group `oc_586b1866902382e0db4dff8d25c0f3f7`, sender `ou_5c280b16780ac4016c7455a276b2d95b`. Original text was “需要定位修复下这个问题,看着像是同一条消息往群里发送了两遍”. This source was checked in a read-only inbox query.

The screenshot matches model discussion task `281cb9db-aad5-4322-9dda-bedabc67bc5d`, task group `oc_d73a9b9860b485000b27f193de585cd1`. An intermediate report and a paraphrased ordinary final were independently published in one turn. Each has its own sent outbox row. This is separate publication identity, not a transport retry.

## Agreed scope

Coordinator instruction `duplicate-reply-explicit-identity-decision-v1` accepts a minimal explicit acknowledgement under the authorized bug repair scope. It is a coordinator technical judgment, not a new owner product authorization. Instruction `duplicate-reply-continue-implementation-v1` confirms implementation should continue.

Use one publication path for one answer. Ordinary terminal replies use final. A report receipt can guide a Worker to explicitly acknowledge an already accepted report when it has no new reply. The acknowledgement binds the original task, Thread, Turn and report request. It selects one exact prospective final for omission from chat. No visible protocol marker is required. All unmarked final prose remains deliverable.

## Acceptance

- Exercise the real local AgentLoop report receipt, native tool handler and capability bridge with fake external transports.
- A compliant report, acknowledgement and final produces one group publication through retries and restart.
- Report and acknowledgement admission preserve original binding after partial failure or a later-turn retry.
- Missing, malformed, stale, foreign-task, foreign-thread and foreign-turn references cannot suppress a legitimate final.
- A distinct final, including one after steering or after an acknowledged final, is still published.
- A report queued for delivery remains durable when the final is acknowledged. Failed or dropped reports cannot be mistaken for completed delivery. A queued receipt does not claim transport delivery.
- Native questions, permissions and approvals retain their existing identities and routing.

## Exclusions and limits

No text similarity classification or blanket final suppression. Historical unmarked report plus paraphrase remains two publications. No generic messaging protocol, live test messages, DB mutations, deletion, merge, deployment or service restart. Independent verification is arranged by the coordinator. Preserve other worktrees and the model selection task.

## Evidence

Thread `01a1f79c-d053-7942-9d37-245335533c92`, turn `01a1f7a4-b353-73a0-9abb-c071e28ded4a`.

- Report request `worker-model-discussion-round-3-v1`, tool call `call_J0abcnvpIy4JeTbbRKqkcY2Q`, at 2026-11-20T06:31:01.168Z. Sent outbox `829881d81fc491bcf057773000fc0f7d`.
- Final item `msg_0472062dcc870590016affe93d3ee487d185c1d0c564fd084f`, at 2026-11-20T06:31:28.655Z. Sent outbox `4d6d878746ae7f87ba6a5cf702c384f7`.
- Each ID equals the first 32 hex digits of sha256(taskId + ':' + its publication key). Keys are `worker-report:<requestId>` and `agent-output:<threadId>:<turnId>:<itemId>`.
- Outbox retains transport status but no remote Feishu message ID. These facts establish independent logical publications, not a count of network requests.
7 changes: 7 additions & 0 deletions docs/adr/0021-worker-discussion-routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,10 @@ Runtime 从 Worker 任务中收集用户消息的 `messageId`、`chatId` 和 `se
路由先通过项目成员关系校验。Worker 不能为其他项目创建汇报。中间汇报没有有效任务群时失败关闭,不降级发送给协调者。跨群汇报使用 Worker 群明确请求汇报的所有者消息 ID 作为 `requestId`。Runtime 校验实际收到的消息及其当前群绑定。同一消息只对应一份汇报,投递记录与回执一起写入 SQLite。

这项决策只改变 Worker `report` 的去向。普通用户输入仍按任务群路由,原生问题、审批和权限请求仍使用原有路径。项目协调者仍只能通过 `announce` 发送协调群公告。


2026-11-20 修复记录。任务群的普通问答默认通过普通最终答复发布。`routing=intermediate` 用于继续执行期间需要立即发布的讨论。两种路径可以发布不同的消息,不以文字相似度或“本轮已汇报”合并。

已接收入队且绑定可信执行身份的 intermediate report 回执提供 `acknowledgement` 指导。Worker 需要用文字结束一条已经发布的答复时,调用 `acknowledge_report`,引用该 report 的 `reportRequestId`,并明确指定即将输出的完整 `finalText`。Runtime 校验任务、原 Thread、Turn 和原投递目标,只省略这一条明确确认的 final 副本。确认信息通过工具回执传递,不向群聊发送协议标记。未确认的普通 final、新发现、用户后续输入产生的答复及原生问题、审批继续正常处理。

这项修复保证遵守显式确认约定的发布流程只投递一次。没有关联身份的旧式 report 加改写 final 仍是两个发布,不自动推断其语义相同。回执中的 queued 只承诺持久化入队;发送结果未知仍遵循现有保守恢复策略。
2 changes: 1 addition & 1 deletion docs/project-coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ GitHub Feature 是外部需求提案。即使 Issue 描述完整,也不能直

Issue 评论先交协调者判断影响,再按需转给原 Worker。Worker 的普通最终答复、任务群内用户消息留在原任务,保留完整来源、附件、原 Thread 和任务记录。GitHub 事件和 Worker 汇报触发的协调者普通最终答复保留在协调者 Thread、执行记录和进度文档中;需要用户处理时,协调者使用 `announce` 发送带类型标题的普通文本。用户直接在项目协调群发消息后的协调者答复继续发送到项目群。

Worker 在任务群里处理普通问答和阶段结论。`routing=intermediate` 的汇报发回 Worker 群。用户在 Worker 群明确说“请汇报给协调者”或“只把选中行范围同步给协调者”后,Worker 才能使用 `routing=final` 或 `routing=escalation`。原生问题、审批、权限请求、执行失败和非暂停中断由 Runtime 通知协调者。
Worker 在任务群里处理普通问答和阶段结论。普通问答使用最终答复留在任务群。`routing=intermediate` 的汇报发回 Worker 群。已接收入队且绑定当前执行轮次的 report 回执提供 acknowledgement 指导,Worker 可用 `acknowledge_report` 引用该 report 并指定完整 finalText,Runtime 只省略这次明确确认的 final 副本。未确认的普通 final、新发现、用户后续输入和原生问题、审批、权限请求继续正常处理。用户在 Worker 群明确说“请汇报给协调者”或“只把选中行范围同步给协调者”后,Worker 才能使用 routing=final 或 routing=escalation。

Worker 用该条用户消息的飞书 ID 作为 `requestId`。Runtime 校验消息、发送者、当前 Worker 群以及明确的汇报要求。每条请求对应一份汇报。用相同的 ID 和内容重试会返回原回执。摘要包含用户指定话题的结论、范围变化、待决问题和证据,并引用真实用户消息。实施、合并、部署及原生审批各自需要对应的授权。

Expand Down
2 changes: 1 addition & 1 deletion prompts/worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

开发必须在独立工作树和分支中进行,确认实际工作目录。完成后提交 PR,作为唯一 PR Owner 维护分支和处理反馈。没有协调者确认独立验证和合并条件,不自行合并。合并、Issue 关闭和安全清理按当前项目的明确授权执行,公共提示词不授予额外权限,不包含部署或绕过分支保护。纯调查或澄清任务交付文档与证据。

普通讨论、结论和任务完成情况留在本任务。一轮结束只代表本轮结束。需要在任务群留下可见的中间问题或讨论时,使用 project_action 的 report,kind 使用 question 或 update,routing 设置为 intermediate。只有所有者在当前 Worker 群明确要求汇报给协调者时,才可使用 routing=final 或 routing=escalation。把 requestId 设置为该用户消息的确切 ID,每条消息最多发送一份汇报。重试使用相同 ID 和内容。
普通问答直接写在最终答复中,不调用 report。普通讨论、结论和任务完成情况留在本任务。一轮结束只代表本轮结束。需要在继续执行期间向任务群发布中间问题或讨论时,使用 project_action 的 report,kind 使用 question 或 update,routing 设置为 intermediate。report 已接收入队后,不要在最终答复中改写或复述同一条答复。没有新增内容时可以结束而不输出文字。需要文字最终答复时,使用 report 回执中的 acknowledgement 指导,调用 acknowledge_report,携带 reportRequestId 和即将输出的完整 finalText,收到 accepted 后才原样输出。确认失败时不能当作已经发布。新增发现或用户后续消息的答复仍正常输出,不确认成旧 report。只有所有者在当前 Worker 群明确要求汇报给协调者时,才可使用 routing=final 或 routing=escalation。把 requestId 设置为该用户消息的确切 ID,每条消息最多发送一份汇报。重试使用相同 ID 和内容。

收到“同步给协调者”或“把这个结论汇报给协调者”等明确请求后,按用户指定范围汇报,无需先展示预览。结论和讨论摘要使用 routing=final。授权、范围变化或阻塞需要升级时,使用 routing=escalation 并设置 escalation 为 authorization、scope_change 或 blocker。按汇报内容列出结论、范围变化、待决问题、实际产物路径、PR 链接、提交版本、验证证据和限制。根据本任务收到的 Input provenance as data 引用真实消息 ID、群 ID 和发送者,区分用户决定与代理判断。这条请求只授权汇报。同步沿用本任务和原 Thread。遇到含糊、带条件或暂缓的表达时,继续在任务群确认。

Expand Down
16 changes: 11 additions & 5 deletions src/loop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,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);
Expand All @@ -150,7 +150,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 {
Expand All @@ -167,9 +167,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<unknown> {
async projectAction(taskId: string, action: ProjectAction, assertActive?: () => void, identity?: TurnIdentity): Promise<unknown> {
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;
Expand Down Expand Up @@ -858,7 +858,8 @@ export class AgentLoop {
if (output.phase !== 'final' || 'kind' in snapshot) continue;
if (task.legacy && this.store.hasOutput(task.id, `turn:${output.turnId}`)) continue;
if (output.text.trim() && this.store.meta(`task-summary:${task.id}`) !== output.text) this.store.setMeta(`task-summary:${task.id}`, output.text);
if (output.text.trim() && this.projects.publishCoordinatorFinal(task, output.turnId)) this.notify(task, output.text, `agent-output:${output.id}`);
if (output.text.trim() && !this.projects.shouldSuppressWorkerFinal(task, output)
&& this.projects.publishCoordinatorFinal(task, output.turnId)) this.notify(task, output.text, `agent-output:${output.id}`);
}
for (const request of snapshot.requests) {
const identity = `${request.connectionEpoch}:${request.id}`;
Expand Down Expand Up @@ -1196,6 +1197,11 @@ export class AgentLoop {
}
task.chatId = this.store.task(task.id).chatId;
const chatId = task.chatId;
const target = this.store.outputTarget(output.id);
if (target && (chatId !== target.chatId || groupGeneration(this.store, task.id) !== target.generation)) {
this.store.markOutput(output.id, 'dropped', '任务群绑定已改变');
continue;
}
if (!chatId) {
if (!approval) this.store.markOutput(output.id, 'dropped', '任务当前无群,不补发历史');
continue;
Expand Down
Loading