Skip to content
Merged
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
73 changes: 73 additions & 0 deletions .scratch/worker-execution-identity-v11/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
Status: ready-for-agent

# Worker execution identity

Version: v1.2

## Problem Statement

Agent Loop currently reads the shared worker execution profile whenever it creates, resumes, or observes a Worker Thread. A configuration reload can therefore change an existing Worker’s model or reasoning effort. Removing a profile can also make a historical Worker inherit a different profile or fail without preserving the original choice.

## Solution

At Worker creation, the coordinator selects one complete model and reasoning-effort pair from the configured Worker allowlist. Agent Loop stores that selection with the Worker task and uses the stored identity for every later turn, observation, pause recovery, and service restart. Configuration changes affect only Workers created after the change. If a historical Worker has no reliable saved original identity, Agent Loop stops before choosing a replacement and reports the ambiguity for coordination.

## User Stories

1. As a project coordinator, I want to select a Worker model and reasoning effort from configured complete pairs, so that each Worker starts with an intentional execution identity.
2. As a project coordinator, I want different Workers to use different allowed pairs, so that the selected capability matches each assignment.
3. As a project coordinator, I want an unavailable pair to be rejected at Worker creation, so that no model and effort combination outside the allowlist can run.
4. As a project coordinator, I want a model and effort to be validated as one pair, so that Agent Loop never crosses a model from one entry with an effort from another entry.
5. As a Worker, I want my selected identity saved with my task, so that later turns use the same model and reasoning effort.
6. As a Worker, I want follow-up messages to use my original identity, so that conversation behavior does not change after configuration reload.
7. As a Worker, I want pause and resume to retain my identity, so that recovery does not silently switch execution capability.
8. As an operator, I want a service restart to restore each Worker’s saved identity, so that restart recovery preserves task behavior.
9. As an operator, I want changing the allowlist to affect only new Workers, so that existing work remains stable.
10. As an operator, I want deleting an allowed pair to leave existing Workers usable with their saved identity, so that configuration cleanup does not rewrite history.
11. As a coordinator, I want the coordinator’s own execution profile to keep using the coordinator configuration, so that Worker selection does not expand or alter coordinator model behavior.
12. As a coordinator, I want historical Workers to use their recorded original identity when reliable provenance exists, so that migration preserves the actual prior choice.
13. As a coordinator, I want an ambiguous historical identity to be surfaced as a blocker, so that the system never guesses from the current instance default.
14. As an operator, I want a failed model call to retain its selected identity, so that retry behavior does not become an unannounced model fallback.
15. As a reviewer, I want the persisted identity to be visible in task state and test fixtures, so that restart and legacy behavior can be audited.

## Implementation Decisions

- Define the Worker execution identity as one validated execution profile containing the backend, model, and reasoning effort. Treat the model and reasoning effort as an inseparable pair.
- Store the Worker allowlist as a single nonempty list of complete execution profiles. Accept the previous single-profile input as a one-entry list at configuration loading. Validate a dispatch selection against an allowlist entry by structural equality, including backend, model, and reasoning effort.
- Extend Worker dispatch input so the coordinator supplies the selected complete profile. Reject a missing or non-allowlisted selection instead of synthesizing a profile from separate model and effort values.
- Persist the selected profile in the task snapshot at the point the task becomes a Worker execution. Keep it across turns, pause, resume, restart, provider migration, and configuration reload.
- Resolve execution for a Worker from its persisted task identity. Resolve execution for a coordinator from the current coordinator role profile. Do not apply Worker snapshots to coordinator tasks.
- Preserve an existing task’s saved identity even when the current allowlist changes or no longer contains that entry. The allowlist constrains creation, not historical execution.
- Inspect durable task state and any reliable existing execution identity before resuming a historical Worker. Use only the complete, valid legacy task-scoped model and effort metadata as a historical original-value source, and persist the source keys. If no reliable original value exists, preserve task, group, Thread, native approvals, operator pause and held inputs, and report one execution-identity blocker before any execution. Never substitute the current Worker profile.
- Keep the dispatch and execution identity validation at the project execution boundary. The loop passes the resulting profile to the Codex port and does not reselect it.
- Base the model feature directly on current main `3260549ec6b42b27fd62373b7b25dc391119ae0e`. Preserve its report, native request, capability, and Worker group message behavior. The cancelled single-config feature is not a dependency.

## Testing Decisions

- Test observable execution behavior. Assert the profile sent to Thread creation, resume, observation, and new turns rather than private maps or helper calls.
- Test dispatch validation for an allowed pair, a crossed pair, a missing selection, and a pair removed from the current allowlist after creation.
- Test task persistence by constructing a Worker, reloading the store, and continuing the Worker with changed configuration. The Codex port must receive the saved profile.
- Test pause and resume, provider restart recovery, and multiple turns with the same saved profile.
- Test historical tasks with reliable saved provenance and tasks without reliable provenance. The first resumes with its recorded identity; the second reports a blocker and never uses the current default.
- Reuse existing project dispatch, project Codex, execution configuration, and runtime recovery fixtures. Add no test that asserts private implementation structure.

## Out of Scope

- Runtime model switching, per-turn reselection, manual Worker profile editing, or automatic model fallback.
- New backend support, dashboard changes, coordinator model selection changes, or a separate verifier role.
- Credential storage, credential redaction, and the cancelled single-config migration.
- Deployment, service restart, live database edits, merge, or changes to unrelated task worktrees.

## Further Notes

- The product decisions in worker execution requirements v1.0 and v1.1 establish creation-time selection, immutable existing Worker identity, and historical preservation. Technical field names and persistence details remain implementation choices.
- The implementation must report the exact main base and resulting PR head. Independent verification is arranged by the coordinator.


## Authorization and sources

The retained v1.0 requirements have SHA256 `f645ade92f2335c37e4b7d1c6ba718876be54cf36b432acf875e8d772775b90d`. Their U1, U2, and U3 source identifiers remain authoritative for the product rules. v1.1 adds the following supplied owner message: `om_x100b60caf31598a4de137711674c7e7`, chat `oc_586b1866902382e0db4dff8d25c0f3f7`, sender `ou_5c280b16780ac4016c7455a276b2d95b`: "历史worker继续沿用原来它本身的模型和推理强度. 先让worker调用to-spec形成文档然后使用poteto-mode进行开发."

The coordinator confirmed the historical fail-closed boundary in task `c9edaf14-f18a-42de-841e-d963e1f520cc`, event `worker-model-historical-fail-closed-v1`: complete legacy keys restore with source; missing, partial, or unreliable provenance preserves task state and emits one blocker without execution or defaults. This is a sourced coordinator instruction within the implementation grant, not a native approval or deployment authorization.

The coordinator relayed owner cancellation of PR63 in event `model-pr63-cancelled-rebase-v1`. Version v1.2 removes that dependency and rebases only the authorized model feature onto main `3260549ec6b42b27fd62373b7b25dc391119ae0e`. Existing environment credential loading remains the main contract. This is a technical base revision; the v1.1 product and implementation authorization remains unchanged. All verification must be refreshed on this base.
5 changes: 4 additions & 1 deletion GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,10 @@ _Avoid_:将接收请求等同于已委派执行。

**执行后端(Execution Backend)**:实际运行执行角色任务的执行层,例如 Codex、dsh 或 Claude Code。执行后端与模型名称是两个概念,角色可以选择后端及其模型参数。

**角色执行配置(Role Execution Configuration)**:为每个执行角色指定执行后端、模型和推理强度的共同配置。所有协调项目使用同一套角色执行配置。
**角色执行配置(Role Execution Configuration)**:为项目协调者指定执行后端、模型和推理强度,并为 Worker 列出允许组合的共同配置。所有协调项目使用同一套角色执行配置。

**Worker 执行身份(Worker Execution Identity)**:同一 Worker 在创建时选定的完整执行后端、模型和推理强度,连同其可追溯来源。后续对话、配置变化、暂停恢复和服务重启保留该身份。
_Avoid_:把当前实例配置当作历史 Worker 的原选择,或把新一轮回复当作重新选择身份。

**工作汇报(Work Report)**:执行者明确向项目协调者提交的工作问题、进展或成果。
_Avoid_:将一次普通回复结束等同于工作汇报。
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@ cp config/example.json config.json

正式任务共用本机 Codex daemon。Agent Loop 通过官方 `daemon version` 发现服务,只在服务未运行时调用 `daemon start`。连接失败会报告错误,断线后重新连接并核对原 Thread。Agent Loop 不停止、重启或更新 daemon,也不回退私有 App Server。

在 `execution.backends` 配置执行后端连接参数,在角色配置中填写 `backend`、`model` 和 `reasoningEffort`。当前提供 Codex 后端,未来可以增加其他执行后端。模型配置属于 Agent Loop 运行时,不修改后端的全局配置;配置文件变化由运行时 watcher 读取,下一次模型调用生效。
在 `execution.backends` 配置执行后端连接参数。`execution.coordinator` 填写一个完整执行配置,`execution.worker` 列出允许的完整 `backend`、`model`、`reasoningEffort` 组合。当前提供 Codex 后端,未来可以增加其他执行后端。模型配置属于 Agent Loop 运行时,不修改后端的全局配置;配置文件变化由运行时 watcher 读取。协调者在下次调用使用新配置;Worker 只在创建时从允许列表选定一次。多轮对话、暂停恢复和服务重启始终沿用任务保存的选择,删除允许项也不改变已有 Worker。旧的单个 Worker 配置仍作为只含一项的允许列表加载。

Agent Loop 不再使用模型选择目录。任务必须先归属到已配置项目;未归属 intake 和历史任务保持等待,不创建执行 Thread。项目协调者和 Worker 直接使用项目目录及统一的角色执行配置。
Agent Loop 不再使用模型选择目录。任务必须先归属到已配置项目;未归属 intake 和历史任务保持等待,不创建执行 Thread。项目协调者和 Worker 直接使用项目目录。协调者从当前配置读取执行参数,Worker 使用自身保存的执行身份。

本地项目可使用 `repositories: []`,不需要 GitHub token。正式会话按角色读取 `prompts/coordinator.md` 或 `prompts/worker.md`,`engineering.promptPath` 不覆盖角色规则。角色指导、委派范围和环境信息通过 `developerInstructions` 与 `additionalContext` 传入正式 Thread;用户消息和 Issue 内容作为请求材料。`engineering.skillPath` 指向已安装的 poteto-mode,其他技能通过现有机制发现。加载与更新方式见[正式会话提示词](docs/prompts/task.md)。

Expand Down
12 changes: 7 additions & 5 deletions config/example.json
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,13 @@
"model": "gpt-6-astra",
"reasoningEffort": "high"
},
"worker": {
"backend": "codex",
"model": "gpt-6.1-sol",
"reasoningEffort": "xhigh"
},
"worker": [
{
"backend": "codex",
"model": "gpt-6.1-sol",
"reasoningEffort": "xhigh"
}
],
"backends": {
"codex": {
"executable": "codex",
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0017-configurable-execution-roles.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Agent Loop 的执行配置由实例统一提供,所有协调项目使用同一

工程归属不再由模型选择。已经明确项目的协调者和 Worker 直接使用项目归属;没有项目归属的 intake 或 legacy Task 保持 pending,不创建执行 Thread,直到协调者完成 `claim_intake` 或 `dispatch`。没有角色的历史 Task 不能回退到通用模型;已有项目成员关系的 Task 保留其 coordinator 或 worker 角色。

运行时监听配置文件。有效变更在当前轮次结束后、下一次创建、恢复或开始调用时生效;正在执行的轮次不被中断。无效变更保留最后一份有效配置并记录诊断,文件修复后自动恢复。任务只保存角色,不把模型或推理强度快照作为运行时来源,因此已有 Task 也会在下一次调用使用新配置。
运行时监听配置文件。有效变更在当前轮次结束后、下一次创建、恢复或开始调用时生效;正在执行的轮次不被中断。无效变更保留最后一份有效配置并记录诊断,文件修复后自动恢复。此处原定所有任务在下次调用使用新配置。Worker 的该规则现由 [ADR 0023](0023-worker-execution-identities.md) 取代:创建时选择完整允许配对,保存身份并在后续调用持续使用。协调者仍按当前角色配置执行。

旧项目级模型字段严格拒绝,要求迁移到统一的 `execution` 配置。配置与角色绑定属于实例级契约,不随单个项目或单个任务重复维护。

Expand Down
13 changes: 13 additions & 0 deletions docs/adr/0023-worker-execution-identities.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
status: accepted
---

# Worker 在创建时固定执行身份

用户要求协调者依据创建时的相关对话,从配置允许的完整模型与推理强度配对中选择一次。Worker 任务的持续上下文跨越多轮、暂停恢复和服务重启,因此把完整执行配置与来源保存在任务中。修改或删除允许项只限制新 Worker;已有身份不可改写。协调者继续使用当前角色配置。

`execution.worker` 使用非空的完整 profile 列表。旧单 profile 作为只含一项的允许列表加载。dispatch 必须显式选择完整 `execution`,保存该选择与来源。按两个独立列表交叉生成配对、逐轮重新选择、运行中修改和静默回退均违反该约定。

旧版 dispatch 曾在同一事务保存 `project-task-model:<taskId>` 与 `project-task-effort:<taskId>`,当时唯一后端为 Codex。只有这两个键提供完整有效值时才恢复旧身份,来源保留键名。缺失或无可靠证据时,Runtime 保留任务、Thread、群、原生审批、operator-paused 状态和 held 输入,向协调者发送一次执行身份阻塞事件并停止该 Worker 的执行。当前角色配置和 Thread 的当前或最近设置都不能证明原选择。

该决策取代 ADR 0017 对 Worker 后续使用热更新配置的规定。它不增加协调者模型选择、执行后端、看板控制、手工改模型或自动模型回退。
10 changes: 6 additions & 4 deletions docs/project-coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Worker 默认不建群;用户需要直接交流时,由协调者打开指定
{
"execution": {
"coordinator": {"backend": "codex", "model": "gpt-6-astra", "reasoningEffort": "high"},
"worker": {"backend": "codex", "model": "gpt-6.1-sol", "reasoningEffort": "xhigh"},
"worker": [{"backend": "codex", "model": "gpt-6.1-sol", "reasoningEffort": "xhigh"}],
"backends": {"codex": {"executable": "codex", "approvalPolicy": "on-request", "sandbox": "workspace-write", "requestTimeoutMs": 120000}}
},
"projects": [
Expand All @@ -42,17 +42,19 @@ Worker 默认不建群;用户需要直接交流时,由协调者打开指定

配置在启动时加载。启用实际配置前,按[本机服务操作](agents/operations.md)执行切换并核对。源码测试不代表正式实例已经启用。

协调者和 Worker 使用实例级 `execution` 配置。配置为每个角色指定执行后端、模型和推理强度,所有协调项目共用同一套值。Agent Loop 不提供 验证角色,独立验证由 pstack 负责。执行配置变化由 watcher 读取,已有任务在下一次调用使用新配置。
协调者和 Worker 使用实例级 `execution` 配置。`execution.coordinator` 指定协调者配置,`execution.worker` 是非空的完整配对允许列表,所有项目共用该配置。旧单配置可加载为只含一项的允许列表。Agent Loop 不提供 验证角色,独立验证由 pstack 负责。执行配置变化由 watcher 读取,协调者在下一次调用使用新配置;Worker 创建后固定使用保存值。

模型名必须能由本机 Codex 解析。Runtime 不按名称猜测模型家族,也不默默更换不可用模型。任务只保存 coordinator 或 worker 角色;恢复和下一次调用按当前配置解析模型与推理强度。既有任务按保存的项目身份恢复。
模型名必须能由本机 Codex 解析。Runtime 不按名称猜测模型家族,也不默默更换不可用模型。Worker 任务在创建或接管 intake 时保存完整 `workerExecution` 身份与派单来源。后续多轮、暂停恢复、provider 迁移和服务重启均沿用保存值。允许列表变化或删除仅限制新 Worker。`status` 的 `workerExecutionProfiles` 与协调者每轮上下文提供当前候选。派单必须显式携带完整 `execution`,即使允许列表只有一项。

历史 Worker 只从完整有效的 `project-task-model:<taskId>` 与 `project-task-effort:<taskId>` 恢复原配对,身份来源保留这两个键。缺失、半项或非法值会生成一次协调者执行身份阻塞事件,保留群、Thread、原生审批、暂停状态及 held 输入。Runtime 不执行该 Worker,也不使用当前默认补值。Thread 当前设置不能证明历史原选择。

## 对话与角色指导

Runtime 为项目建立一个协调 Task 及项目群。协调者使用 `prompts/coordinator.md`,Worker 使用 `prompts/worker.md`。用户在项目群交办或补充材料。CLI submit、answer 和私聊接单已经移除。`status --request-id` 保留为旧 CLI 请求的只读查询。

GitHub 和历史接单记录保留原文、来源和附件,不自动创建执行 Thread、工作区或任务群。项目不明确时保留问题和现场,不回退到无项目执行。

协调者派单携带目标、背景、范围、禁止动作、验收及交付要求。接单请求通过 `dispatch` 的 `intakeTaskId` 原地转为 Worker,保留请求身份、原文、附件和范围回答。项目群直接交办的子任务仍可使用普通 `dispatch`。共享项目入口本身不是隔离工作树。
协调者派单携带目标、背景、范围、禁止动作、验收及交付要求,并根据创建时的相关对话选择一个允许的完整 `execution` 配置。接单请求通过 `dispatch` 的 `intakeTaskId` 原地转为 Worker,保留请求身份、原文、附件和范围回答。项目群直接交办的子任务仍可使用普通 `dispatch`。共享项目入口本身不是隔离工作树。

模糊的新需求先交 Worker 调查和澄清,本轮不实施业务代码。Worker 使用 grill-with-docs 查明已有事实,整理需求文档和待决问题。协调者把问题、证据、选项、影响和建议带回项目群,再将实际用户答复及消息、群和发送者来源交回原 Worker。已解决的问题不重复问。

Expand Down
Loading