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
2 changes: 1 addition & 1 deletion docs/architecture/rfcs/STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ appendix may keep dated history, but no dated log heading may precede it.
| [RFC: Capable Agent Manager and Semantic Work Handoff (v0)](capable-manager-semantic-handoff-v0.md) | Accepted | [Personal Follow-through independent proposal](personal-follow-through-v0.md) | [2 entries](ledger/capable-manager-semantic-handoff-v0/) |
| [RFC: Complete State Recovery and Controlled Reactivation (v0)](complete-state-recovery-v0.md) | Accepted | none | — |
| [RFC: Composable State Machines and Recovery Verification (v0)](composable-state-machines-recovery-verification-v0.md) | Accepted | none | — |
| [RFC: Controller / Executor Sessions and One Governed Work Contract (v0)](controller-executor-unified-contract-v0.md) | Accepted | none | — |
| [RFC: Controller / Executor Sessions and One Governed Work Contract (v0)](controller-executor-unified-contract-v0.md) | Accepted | none | [1 entry](ledger/controller-executor-unified-contract-v0/) |
| [Explicit Todo continuation: Stage A](cross-session-memory-substrate-v0.md) | Accepted | none | — |
| [RFC: LoopX Desktop Execution Frontends v0](desktop-execution-frontends-v0.md) | Accepted | none | — |
| [RFC: External Evidence Research Capability v0](external-evidence-research-capability-v0.md) | Accepted | none | [3 entries](ledger/external-evidence-research-capability-v0/) |
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/rfcs/STATUS.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
| [RFC:强能力 Agent 管家与语义工作交接(v0)](capable-manager-semantic-handoff-v0.zh-CN.md) | 已接受 | [个人事项持续跟进独立提案](personal-follow-through-v0.zh-CN.md) | [2 条](ledger/capable-manager-semantic-handoff-v0/) |
| [RFC:完整状态恢复与受控重新激活(v0)](complete-state-recovery-v0.zh-CN.md) | 已接受 | 无 | — |
| [RFC:可组合状态机与恢复验证(v0)](composable-state-machines-recovery-verification-v0.zh-CN.md) | 已接受 | 无 | — |
| [RFC:Controller / Executor 会话与统一受治理工作契约(v0)](controller-executor-unified-contract-v0.zh-CN.md) | 已接受 | 无 | — |
| [RFC:Controller / Executor 会话与统一受治理工作契约(v0)](controller-executor-unified-contract-v0.zh-CN.md) | 已接受 | 无 | [1 条](ledger/controller-executor-unified-contract-v0/) |
| [显式 Todo 接续:阶段 A](cross-session-memory-substrate-v0.zh-CN.md) | 已接受 | 无 | — |
| [RFC:LoopX 桌面执行前端 v0](desktop-execution-frontends-v0.zh-CN.md) | 已接受 | 无 | — |
| [RFC:外部证据研究能力 v0](external-evidence-research-capability-v0.zh-CN.md) | 已接受 | 无 | [3 条](ledger/external-evidence-research-capability-v0/) |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -752,6 +752,78 @@ owner; adopt its qualified changes and add only the integration coverage missing
at the new composition boundary. Keep C1 open until the replacement works and
the remaining supported readers have explicit cutover/retirement conditions.

### Responsibility convergence and contributor handoff

The [source-backed refactor handoff](ledger/controller-executor-unified-contract-v0/2026-10-27-refactor-handoff.md)
decomposes C3/C4/C7/C8/C9 into concrete simplification candidates. It belongs to
this plan, not another roadmap or evidence of shipped implementation. The pinned
audit separates duplicated decisions, misplaced shared code, existing shared
owners and hypotheses requiring semantic comparison.

Keep three responsibilities clear:

1. **Core semantic owners:** decide legal work/session/effect transitions and
validate original authority and receipts in the existing typed domains.
2. **Shared managed execution:** drive those decisions through session binding,
native invocation, observations and recovery. Reuse existing Turn/effect
owners; this is not another permission engine or scheduler.
3. **Host adapters:** implement native SDK/CLI transport, event translation,
supported resume and resource cleanup. Preserve real host differences rather
than hiding unsupported behavior behind a nominal common interface.

Select work from the overall roadmap, current user outcome, demonstrated
bottlenecks, open delivery and canonical work. Package IDs and table order are
references, not global priority, an Agent's fixed agenda or reserved ownership.
C1/C2 composition/capture/final-input work and these simplifications are options
within that same frontier, not competing permanent Agent mandates. Owners name
code boundaries, not assignments or execution grants; recheck target main,
open PRs and canonical work before claiming one.

| Existing task / package | Simplification result | Start condition |
| --- | --- | --- |
| **C3.1 Managed-operation protocol** | Codex and DSH adopt one operation-session flow; remove duplicated binding/profile checks and handoff/start orchestration, and DSH's dependency on a Codex-owned generic handler | When this duplication is the selected bottleneck: existing single-session behavior and two real callers; retain native differences |
| **C3.2 Session-binding callers** | Reuse shared persistence; eliminate caller-side binding reconstruction and private cross-host imports where a cohesive existing operation can replace them | Pair with C3.1 if a separate change would leave only a rename/facade; role/generation expansion waits for stable C1 |
| **C4.1 Receipt-to-continuation** | Adopt a qualified typed Turn observation/continuation boundary; retire replaced Python receipt reconstruction and decisions | Keep journal recovery distinct from next-work decisions; integrate C1 and existing recovery fixes |
| **C4.2 Outer-worker adoption** | Consume qualified semantic results instead of reconstructing common retry/continuation policy | C4.1; preserve wake ownership, original receipts and opaque-command uncertainty |
| **C4.3 Settlement-adapter convergence** | Reuse settlement primitives; retire a second step/condition interpreter only where obligations coincide | Candidate: compare Host Todo completion and Turn settlement; coordinate active settlement PRs |
| **C7.1 Worker/process adapter cleanup** | Reuse applicable launch/drain/cleanup helpers and remove proven duplicated mechanics | Candidate: match ownership, signal/deadline and control-arm semantics first |
| **C8.1 Operational readback** | App/Chat/CLI consume the same typed work/session facts; retire superseded caller classifications | Candidate: role facts available and duplicate classification demonstrated; retain unknown/coverage and audience boundaries |
| **C9.1 Lease/source-path retirement** | Remove obsolete normal-writer routing/wrappers after caller migration; retain required release, fence-close and original-receipt recovery | Cross-RFC candidate: shared-authority/TS acceptance, not a controller-launch prerequisite |
| **C9.2 Contract-test consolidation** | Shared invariant cases and thin native-adapter tests replace duplicated complete-flow fixtures | Companion to the owning replacement; preserve unique integration and negative cases |

These are nine investigation/delivery packages, **not nine promised PRs**, a
fixed remaining count or mandatory work before C1 lands. Do not select C3.1
merely because it appears first, or prefer visible code deletion over a more
valuable current correctness, contract-delivery or authority-retirement outcome.
If selected, C3.2 may share C3.1's reversible PR. Only actual semantic dependencies
constrain order. Existing-behavior repairs and proven local simplifications can
land before C1; contract-dependent cutovers retain that dependency. Similar-looking
files do not qualify a conditional candidate.

Record why the chosen slice advances the current global outcome, which higher-
value alternatives or in-flight deliveries were considered, and its actual
dependency. Reassess after delivery or new evidence; this inventory neither
exhausts useful work nor obliges an Agent to finish one lane before changing
focus. Priority advice creates no new admission or approval gate.

Each claimed package carries its source owners/callers, target boundary,
specific deleted rules/branches, real-path oracle, dependencies and rollback
in the existing Todo and PR. An audit assigns no peer work and creates no parallel
task store. Complete caller replacement and deletion in the usable slice; keep a
wrapper only for an identified external or recovery contract. Measure total
production changes across languages, semantic owners, complete-transaction
runtime crossings and the next representative rule's change sites. Python LOC
reduction or a new shared class alone does not establish simplification; no
arbitrary net-negative LOC quota replaces correctness or required validation.

Reuse [TypeScript change-locality payoff](typescript-control-plane-migration-v0.md#28-change-locality-as-migration-payoff)
and [smoke consolidation policy](../../development/good-smokes.md). Internal
behavior-preserving replacements need real caller/backend evidence, not new
settings screens. Changed caller-facing operations/readback retain C8's packaged
frontend failure/recovery journey and first-screen evidence. C1/default-adoption
complete-cost and benefit qualification remain unchanged; a bounded refactor is
not full RFC acceptance.

## 12. Open decisions

1. **Exact wire name and field mapping — contract owner, before C1 cutover.**
Expand All @@ -767,3 +839,12 @@ the remaining supported readers have explicit cutover/retirement conditions.
Test same-model controller/executor first to isolate architecture effects;
cheaper controller models and different budgets are separate experiments.
Keep the profile opt-in until full outcome/cost evidence supports a decision.

## Appendix A: Execution ledger

Source audits and subsequent delivery evidence live in
[`ledger/controller-executor-unified-contract-v0/`](ledger/controller-executor-unified-contract-v0/).
The directory is the index. A planning/source-inspection entry does not establish
runtime delivery; live priorities and claims remain in the roadmap and canonical
work. Keep historical entries append-only and refine the current normative plan
here rather than treating a dated audit as a permanent execution queue.
Original file line number Diff line number Diff line change
Expand Up @@ -570,6 +570,62 @@ C1 首个实现片必须把完整字段/条款迁移与真实单会话 producer
Native-resume/context 工作保留原 owner;采用其已验收改动,只补新组合边界缺少的集成
覆盖。替换真正可用且其余受支持 reader 有明确切换/退役条件之前,C1 保持未完成。

### 职责收敛与贡献者交接

[有源码依据的重构交接清单](ledger/controller-executor-unified-contract-v0/2026-10-27-refactor-handoff.zh-CN.md)
把 C3/C4/C7/C8/C9 拆成具体精简候选。它属于本计划,不是另一份 roadmap,也不证明
实现已交付。固定版本核对区分重复决策、归属不当的共享代码、已有共享 owner,以及
需要语义比较才能成立的假设。

保持三个清晰的职责:

1. **Core 语义 owner:** 在既有 typed 领域内裁决合法工作、会话、effect 转移,验证
原权限与回执。
2. **公共受管执行:** 按这些裁决驱动会话绑定、原生调用、观察与恢复。复用既有
Turn/effect owner;不是另一套权限引擎或调度器。
3. **Host adapter:** 实现原生 SDK/CLI transport、事件转换、实际支持的 resume 和资源
清理。保留真实宿主差异,不能用名义统一接口隐藏不支持的行为。

从整体 roadmap、当前用户成果、实际瓶颈、在途交付与 canonical 工作中选择任务。
工作包编号和表格顺序只是引用,不是全局优先级、某个 Agent 的固定议程或预留归属。
C1/C2 组合/capture/最终输入工作与这些精简同属一个候选前沿,不是永久分给不同 Agent
的竞争议程。Owner 指代码边界,不代表任务分配或执行授权;认领前重新核对目标 main、
开放 PR 与 canonical 工作。

| 既有任务 / 工作包 | 精简结果 | 启动条件 |
| --- | --- | --- |
| **C3.1 受管操作协议** | Codex、DSH 采用同一操作会话流程;删除重复 binding/profile 校验、handoff/start 编排,以及 DSH 对 Codex 模块内通用 handler 的依赖 | 此重复被选为当前瓶颈时:现有单会话行为、两个真实调用方,保留原生差异 |
| **C3.2 会话绑定调用方** | 复用共享持久化;以既有完整操作替换调用方重建 binding 和跨 Host 私有导入 | 若独立拆开只剩改名/facade,则与 C3.1 一起交付;role/generation 扩展等待 C1 稳定 |
| **C4.1 回执到继续决策** | 采用已合格 typed Turn 观察/继续边界;退役被替代的 Python 回执重建与决策 | 保留 journal 恢复与下一工作决策的区别;整合 C1 及已有恢复修复 |
| **C4.2 外层 worker 采用** | 消费已合格语义结果,移除自行重建的公共重试/继续策略 | C4.1;保留唤醒归属、原回执和不透明命令的不确定性 |
| **C4.3 结算 adapter 收敛** | 复用 settlement 原语;仅在义务一致时删除第二套步骤/条件解释器 | 候选:比较 Host Todo completion 与 Turn settlement,并对齐在途结算 PR |
| **C7.1 Worker/进程 adapter 精简** | 复用适用 launch/drain/cleanup helper,删除已证实重复的机制 | 候选:先核对归属、信号/截止时间及对照组语义 |
| **C8.1 运行 readback** | App/Chat/CLI 消费同一 typed 工作/会话事实,退役被替代的调用方分类 | 候选:role 事实可用且证实分类重复;保留 unknown/coverage 与受众边界 |
| **C9.1 租约/来源旧路径退役** | 调用方迁移后删除过时正常 writer 路由/wrapper;保留必要 release、fence-close 和原回执恢复 | 跨 RFC 候选:遵循 shared-authority/TS 验收,不作为 controller 启动前置 |
| **C9.2 契约测试合并** | 共用不变量案例,加薄原生 adapter 测试,替换重复完整流程 fixture | 随所属替换交付;保留独有集成与负例 |

这是九个调查/交付工作包,**不是承诺九个 PR**、固定剩余数量,也不是 C1 合入前必须
完成的工作。不能因 C3.1 排在前面就选择它,也不能为了可见删代码而放弃当前更有价值的
正确性、契约交付或 authority 退役成果。若选定 C3.1,C3.2 可以属于同一个可逆 PR。
只有真实语义依赖约束顺序。现有行为修复和已证实局部精简可以先于 C1 交付;依赖契约
的切换仍保留该依赖。不能仅凭文件相似就认定候选具备实施条件。

记录所选切片为何推进当前全局成果、考虑过哪些更高价值替代项或在途交付,以及实际
依赖。交付或新证据出现后重新评估;此盘点不穷尽有价值工作,也不要求 Agent 做完
一条工作线才能换方向。优先级建议不新增准入或批准 gate。

每个已认领工作包在既有 Todo/PR 内携带来源 owner/调用方、目标边界、具体删除的规则/
分支、真实路径 oracle、依赖与回退。审计不替其他 Agent 分配任务,也不建立平行任务库。
可用切片应完成调用方替换和删除;仅对具名外部接口或恢复契约保留 wrapper。记录跨语言
生产代码总变化、语义 owner、完整事务 runtime crossing,以及下一项代表性规则的
修改位置。Python LOC 减少或新增共享类不能单独证明精简;不以任意净减行数配额
替代正确性或必需验证。

复用 [TS 修改局部性收益](typescript-control-plane-migration-v0.zh-CN.md#28-以修改局部性衡量迁移收益)
及 [smoke 合并规则](../../development/good-smokes.md)。内部行为保持替换需要真实调用方/
后端证据,无需新设置页面。改变调用方操作/readback 时,仍需 C8 的打包前端失败/恢复
旅程及首屏证据。C1/默认采用的完整成本与收益资格不变;有界重构不代表完整 RFC 验收。

## 12. 待决事项

1. **精确 wire 名称与字段映射——contract owner,在 C1 cutover 前。** 优先演进一个
Expand All @@ -582,3 +638,11 @@ Native-resume/context 工作保留原 owner;采用其已验收改动,只补
3. **资源分配与默认——product/evaluation owner,在 C7–C8 后。** 先用相同模型的
controller/executor 隔离架构影响;更便宜的 controller 模型与不同预算另行实验。
完整成果/成本证据支持决定前,profile 保持 opt-in。

## Appendix A: Execution ledger / 执行记录

源码核对及后续交付证据位于
[`ledger/controller-executor-unified-contract-v0/`](ledger/controller-executor-unified-contract-v0/)。
目录即索引。规划/源码检查记录不证明 runtime 交付;当前优先级与认领仍在 roadmap 和
canonical 工作中维护。历史记录保持 append-only,当前规范性计划在本文修订,不能把
某日审计当作永久执行队列。
Loading
Loading