Skip to content

Commit b3ce2cf

Browse files
authored
Merge pull request #7416 from loopx-project/codex/controller-unified-contract
docs: unify work contracts and design controller/executor sessions
2 parents 6e03576 + 9d2d022 commit b3ce2cf

22 files changed

Lines changed: 1611 additions & 28 deletions

‎benchmark/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,18 @@ live tasks, hidden evaluation, credentials, raw trajectories, submissions, and
4444
unpublished comparisons remain maintainer-owned. Engineering readiness does not
4545
by itself establish a C2 uplift claim.
4646

47+
The [unified work contract and session-role RFC](../docs/architecture/rfcs/controller-executor-unified-contract-v0.md)
48+
extends this build map with C7: benchmark workers should reuse the same qualified
49+
product profile and governed lifecycle as other entrypoints. Benchmark-family
50+
adapters retain task, environment, verifier and scoring semantics. Proposed
51+
single-/two-session comparisons count both sessions and all recovery costs;
52+
helper delivery neither launches trials nor changes frozen historical arms.
53+
54+
中文:[统一工作契约与会话角色提案](../docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md)
55+
的 C7 延伸本建设图:worker 复用同一已验收产品模式和治理生命周期,benchmark 适配器
56+
保留题目、环境、验证与评分语义。拟议单双会话对照计入双方及全部恢复成本;
57+
交付 helper 不启动实验,也不修改已冻结的历史对照臂。
58+
4759
## Current work
4860

4961
- [Execution observations through ordinary Goal planning](runtime/EXECUTION_OBSERVATIONS.md)

‎docs/architecture/rfcs/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,14 @@ Paired diffs do not certify translation accuracy.
191191
settlement, and typed Effect Program foundations are shipped. Replan
192192
planning/ACK stays domain-local until a second real lifecycle justifies
193193
extraction.
194+
- [Controller / Executor Sessions and One Governed Work Contract v0](controller-executor-unified-contract-v0.md)
195+
([中文版](controller-executor-unified-contract-v0.zh-CN.md))
196+
- **Delivery on `main`:** Design only; no unified schema or dual-session profile is implemented.
197+
- **Current boundary:** Replaces permanent quota/Turn packet views with one
198+
contract including differential context; controller-only model access to
199+
Core, natural-language executor work and runtime-owned identity/recovery.
200+
C1–C9 connect concrete refactors, real host adoption and complete-cost
201+
qualification without changing defaults or launching experiments.
194202
- [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md)
195203
([中文版](typescript-control-plane-migration-v0.zh-CN.md))
196204
- **Delivery on `main`:** Substantially implemented; active migration.

‎docs/architecture/rfcs/STATUS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ appendix may keep dated history, but no dated log heading may precede it.
1818

1919
[中文版](STATUS.zh-CN.md) is the semantic mirror of this file.
2020

21-
## Accepted (46)
21+
## Accepted (47)
2222

2323
| RFC | Header status | Supersedes / closes | Ledger |
2424
| --- | --- | --- | --- |
@@ -31,6 +31,7 @@ appendix may keep dated history, but no dated log heading may precede it.
3131
| [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/) |
3232
| [RFC: Complete State Recovery and Controlled Reactivation (v0)](complete-state-recovery-v0.md) | Accepted | none | — |
3333
| [RFC: Composable State Machines and Recovery Verification (v0)](composable-state-machines-recovery-verification-v0.md) | Accepted | none | — |
34+
| [RFC: Controller / Executor Sessions and One Governed Work Contract (v0)](controller-executor-unified-contract-v0.md) | Accepted | none | — |
3435
| [Explicit Todo continuation: Stage A](cross-session-memory-substrate-v0.md) | Accepted | none | — |
3536
| [RFC: LoopX Desktop Execution Frontends v0](desktop-execution-frontends-v0.md) | Accepted | none | — |
3637
| [RFC: External Evidence Research Capability v0](external-evidence-research-capability-v0.md) | Accepted | none | [3 entries](ledger/external-evidence-research-capability-v0/) |

‎docs/architecture/rfcs/STATUS.zh-CN.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
[English](STATUS.md) 与本文互为语义镜像。
1717

18-
## 已接受 (46)
18+
## 已接受 (47)
1919

2020
| RFC | 头部状态 | 替代 / 关闭 | Ledger |
2121
| --- | --- | --- | --- |
@@ -28,6 +28,7 @@
2828
| [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/) |
2929
| [RFC:完整状态恢复与受控重新激活(v0)](complete-state-recovery-v0.zh-CN.md) | 已接受 | 无 | — |
3030
| [RFC:可组合状态机与恢复验证(v0)](composable-state-machines-recovery-verification-v0.zh-CN.md) | 已接受 | 无 | — |
31+
| [RFC:Controller / Executor 会话与统一受治理工作契约(v0)](controller-executor-unified-contract-v0.zh-CN.md) | 已接受 | 无 | — |
3132
| [显式 Todo 接续:阶段 A](cross-session-memory-substrate-v0.zh-CN.md) | 已接受 | 无 | — |
3233
| [RFC:LoopX 桌面执行前端 v0](desktop-execution-frontends-v0.zh-CN.md) | 已接受 | 无 | — |
3334
| [RFC:外部证据研究能力 v0](external-evidence-research-capability-v0.zh-CN.md) | 已接受 | 无 | [3 条](ledger/external-evidence-research-capability-v0/) |

‎docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
| Status | Accepted |
66
| Supersedes / closes | none |
77
| Date | 2026-08-08 |
8-
| Last normative revision | 2026-10-01 |
8+
| Last normative revision | 2026-10-27 |
99
| Author | LoopX maintainers |
1010
| Scope | Public control-plane docs, packet contracts, refactor direction, test strategy |
1111

@@ -464,8 +464,12 @@ The existing R5 CLI captures full decisions before projection, with a private di
464464

465465
#### Heartbeat and Turn Envelope convergence
466466

467-
Under existing M7.4 and roadmap S2/S3/S6/S8, converge the **execution facts**
468-
used by heartbeat and Turn hosts, while keeping host effect ownership separate.
467+
Under existing M7.4 and roadmap S2/S3/S6/S8, converge heartbeat and Turn
468+
execution into **one governed work contract**, while keeping host effect
469+
ownership explicit. The [controller/executor RFC](controller-executor-unified-contract-v0.md)
470+
owns the complete schema/consumer migration and optional model-session split.
471+
Its target replaces permanent quota/Turn views with one schema, full/delta
472+
delivery and immutable recovery; this does not claim that cutover has shipped.
469473
When an admitted Todo later waits on a timer, PR or capability, the typed
470474
receipt owner preserves its original writeback and settlement route. Reentry
471475
projects only that closeout, including for deferred work and after the wait
@@ -692,7 +696,7 @@ Continue in this order using the existing owners and checkpoints:
692696
| Todo | Observable outcome and decisive acceptance |
693697
|---|---|
694698
| Reconcile execution/context requirements across heartbeat and TurnEnvelope | Same captured authoritative decision preserves actor/Goal/Todo, required full reads, claim/lease, action selection, replan/closure, conditional settlement and scheduler ownership. Inventory omitted/duplicated facts before deleting render branches. Include optional capabilities off, recall-only, ingest-only, stale binding and provider failure; private detail is accessed only through authorized references. |
695-
| Adopt one typed projection in real host renderers | Heartbeat full/thin and Turn host consume the same execution facts and per-Turn capture/detail route. Keep host-specific notification and scheduler transport explicit. Real File/SQLite CLI plus packaged Codex App tests cover reentry, source loss, refusal before required reads, late results, backoff and exactly-once settlement; no second admission from a detail read. Retire the replaced projection only after its last caller moves. |
699+
| Adopt one contract in real host entrypoints | Heartbeat full/thin and Turn host consume the same schema and per-Turn capture/detail route, with no permanent format-specific semantic views. Keep host-specific notification and scheduler transport explicit. Real File/SQLite CLI plus packaged Codex App tests cover reentry, source loss, refusal before required reads, late results, backoff and exactly-once settlement; no second admission from a detail read. Retire the replaced projection only after its last caller moves. |
696700
| Qualify the context shape and migration default | Compare the same normal, replan, wait/recovery and optional-capability workloads against both current full and compact paths. Measure payload/model tokens, detail IO, latency, resource growth, omissions and decision/outcome quality. Keep data loss, duplicate effects, identity and settlement errors as hard constraints. Preserve supported saved prompts/receipts and reversible rollout; change budgets or defaults only with that evidence. |
697701

698702
**Context cost and projection convergence: next implementation slice**
@@ -712,13 +716,17 @@ The next slice stays within the existing three convergence acceptances above:
712716
ordinary `quota should-run` input actually consumed by benchmark case solvers;
713717
operator/control-plane and personal maintenance packets are secondary. The
714718
shared projection delivers complete context on first use and exact changed
715-
subtrees on supported warm turns. Solvers need not switch to TurnEnvelope.
719+
subtrees on supported warm turns. Solvers retain their product entrypoint;
720+
both old packet formats migrate to the single contract.
716721
In-packet deduplication and cold-start reduction complement this work; a
717722
succession of small cleanups must not substitute for qualifying the repeated
718723
input path. A smaller stored capture or import cleanup proves no model saving.
719-
2. **One projection owner, two transport consumers.** Extend the existing typed
720-
interaction/work-context owner for full and delta context; quota and
721-
TurnEnvelope consume it. Preserve original capture, required-source checks,
724+
2. **One contract and one delivery mechanism across hosts.** Extend the existing
725+
typed interaction/work-context owner for full and delta context. Replace
726+
quota and TurnEnvelope output schemas with the unified schema; retain old
727+
decoders only for identified migration readers and historical receipt replay.
728+
Different host wrappers do not create different contract views. Preserve
729+
original capture, required-source checks,
722730
invocation, selection, settlement and detail routes. Python retains source IO;
723731
hosts retain their effects and context-continuity observation. No independent
724732
admission service, diff daemon or Python context-decision owner is needed.
@@ -763,6 +771,11 @@ App consumers, and their full fallback. A standalone diff helper is insufficient
763771
| Turn adoption | Consume the same full/delta context owner while retaining Turn signatures and outer-executor effects. Host-only settlement execution remains distinct from a manual CLI agent's executable settlement obligations. |
764772
| Choice of representation | Emit a delta only when it is smaller after binding/removal metadata. Otherwise emit full context. Do not truncate values or change source selection to meet a byte target. |
765773

774+
The surface-specific bindings below describe the existing delivery/migration
775+
contract. They remain mandatory while those readers are active; C1–C9 of the
776+
controller/executor proposal replaces both emitted formats. Historical captures
777+
keep their original version and may never reuse a new-schema baseline.
778+
766779
**Source and change boundaries.** The shared `context_delivery_v1` presentation
767780
covers whole quota packets, whole Turn envelopes and their common work context.
768781
The surface is part of the existing Goal/Agent/session/epoch/capture binding, so
@@ -1742,6 +1755,14 @@ Example replacements:
17421755

17431756
## Semantic control and execution ownership
17441757

1758+
The optional [controller/executor profile](controller-executor-unified-contract-v0.md)
1759+
separates model responsibilities within these owners: the controller is the sole
1760+
model-facing Core client; the executor exchanges natural-language work and
1761+
artifacts under host-enforced scope. It is not the deterministic Turn Loop
1762+
Controller. One Agent may bind those two roles without creating two competing
1763+
work executors or a second authority. Single-session behavior remains available;
1764+
role binding, result validation and total-cost qualification precede promotion.
1765+
17451766
LoopX's semantic control plane preserves work meaning across Turns, Agents and
17461767
runtimes: intent, ownership, dependencies, authority, evidence and continuation.
17471768
Its execution responsibility covers the typed transactions and settlement

‎docs/architecture/rfcs/agent-loop-effect-interpreter-v0.zh-CN.md‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
| 状态 | 已接受 |
66
| 替代 / 关闭 | 无 |
77
| 日期 | 2026-08-08 |
8-
| 最近规范性修订 | 2026-10-01 |
8+
| 最近规范性修订 | 2026-10-27 |
99
| 作者 | LoopX maintainers |
1010
| 范围 | 公开控制面文档、packet 合同、重构方向、测试策略 |
1111

@@ -323,8 +323,10 @@ R5 短包投影也完整保留已有 CLI 结算计划,包括 effect identity
323323

324324
#### Heartbeat 与 TurnEnvelope 收敛
325325

326-
沿用既有 M7.4 与 roadmap S2/S3/S6/S8,统一 heartbeat 和 Turn host 消费的
327-
**执行事实**,宿主效果的所有权仍分别保留。已准入 Todo 随后等待定时、PR 或能力时,
326+
沿用既有 M7.4 与 roadmap S2/S3/S6/S8,把 heartbeat 和 Turn 执行统一为
327+
**一份受治理工作契约**,显式保留宿主效果所有权。[Controller/executor RFC](controller-executor-unified-contract-v0.zh-CN.md)
328+
拥有完整 schema/消费者迁移和可选模型会话分工:以同一 schema、full/delta 交付及不可变
329+
恢复替代长期 quota/Turn 视图。这不宣称 cutover 已交付。已准入 Todo 随后等待定时、PR 或能力时,
328330
typed receipt owner 保留原回写与结算路径;即使工作已 deferred 或等待已到期,重入也
329331
只投影原收尾,不恢复业务执行、不选择后继、不创建重试时钟。恢复复用原回执中的正向
330332
工作准入和精确结算绑定;工作区修复本身没有业务结果,须先经同轮正常 guard 对精确
@@ -469,7 +471,7 @@ live 模型结果、App 采用或以下三项收敛验收完成。
469471
| Todo | 可观察结果与决定性验收 |
470472
|---|---|
471473
| 核对 heartbeat 与 TurnEnvelope 的执行和上下文要求 | 同一捕获的权威决策保留 actor/Goal/Todo、必读全文、claim/lease、选择、replan/收尾、带条件结算和 scheduler 所有权。删除渲染分支前列明遗漏与重复事实。覆盖可选能力关闭、仅 recall、仅 ingest、绑定失效和 provider 失败;私有详情只经有权限的引用访问。 |
472-
| 在真实宿主 renderer 采用同一 typed 投影 | heartbeat full/thin 与 Turn host 消费同一执行事实及同 Turn 捕获/详情入口;显式保留通知和 scheduler 的宿主传输。真实 File/SQLite CLI 与打包 Codex App 覆盖重入、来源丢失、必读前拒绝、迟到结果、backoff 和一次结算;补读不触发第二次准入。最后调用方迁移后才退役旧投影。 |
474+
| 在真实宿主入口采用统一契约 | heartbeat full/thin 与 Turn host 消费同一 schema 及同 Turn 捕获/详情入口,不长期保留分格式的语义视图;显式保留通知和 scheduler 的宿主传输。真实 File/SQLite CLI 与打包 Codex App 覆盖重入、来源丢失、必读前拒绝、迟到结果、backoff 和一次结算;补读不触发第二次准入。最后调用方迁移后才退役旧投影。 |
473475
| 核验上下文形态及迁移默认 | 将相同的正常、replan、等待/恢复与可选能力负载同时对照当前完整和短包路径,测量载荷/model token、详情 IO、延迟、资源增长、遗漏、决策与结果质量。数据丢失、重复效果、身份和结算错误保持硬约束;保留受支持的已保存 prompt/回执与可逆 rollout,根据证据再改预算或默认。 |
474476

475477
**上下文成本与投影融合:下一实现切片**
@@ -484,12 +486,14 @@ live 模型结果、App 采用或以下三项收敛验收完成。
484486

485487
1. **以完整首包、后续子树增量作为融合目标。** 优先优化 benchmark case 内 solver 实际
486488
消费的普通 `quota should-run` 输入,实验操作者/控制面对话及个人维护包为次要项。
487-
共享投影首次完整交付,支持温态复用时只交付精确变化子树,solver 无需切换 TurnEnvelope。
489+
共享投影首次完整交付,支持温态复用时只交付精确变化子树。Solver 保留产品入口,
490+
两种旧 packet 格式共同迁入统一契约。
488491
包内去重和冷启动缩减作为配套;连续做小清理不能替代重复输入路径的验收。存储 capture
489492
缩小或 import 清理不能证明模型输入节省。
490-
2. **一个投影 owner,两个传输调用方。** 扩展已有 typed interaction/work-context owner,
491-
同时生成完整和增量上下文,由 quota 与 TurnEnvelope 消费。保留原始捕获、required-source
492-
校验、调用、选择、结算与详情入口;Python 保留来源 IO,host 保留效果执行和上下文连续性
493+
2. **跨宿主使用同一契约、同一交付机制。** 扩展已有 typed interaction/work-context owner,
494+
同时生成完整和增量上下文,用统一 schema 替代 quota 与 TurnEnvelope 输出 schema;
495+
旧 decoder 只服务具名迁移 reader 和历史回执 replay。不同宿主外层包装不构成不同契约
496+
视图。保留原始捕获、required-source 校验、调用、选择、结算与详情入口;Python 保留来源 IO,host 保留效果执行和上下文连续性
493497
观察。不新增独立准入服务、diff daemon 或 Python 上下文决策 owner。刻画调用方并在采用后
494498
删除被替代投影。输出释放前的 host 传输 ACK 既不证明模型完整收到了内容,也不证明其仍被
495499
保留。现有 capture/handoff 是接入位置,并非已经实现的连续性契约。
@@ -519,6 +523,10 @@ live 模型结果、App 采用或以下三项收敛验收完成。
519523
| Turn 采用 | 消费同一完整/增量上下文 owner,同时保留 Turn 签名和外层 executor 效果归属。host 独占的结算执行与手动 CLI agent 的可执行结算义务仍有区别。 |
520524
| 表示选择 | 计入绑定和删除元数据后,只有更小才发送 delta,否则发送全量。不为字节目标截断值或改变来源选择。 |
521525

526+
以下按 surface 区分的绑定描述现有交付/迁移契约;对应 reader 活跃时仍必须遵守。
527+
Controller/executor 提案的 C1–C9 替换两种输出格式;历史 capture 保留原版本,
528+
不能借用新 schema 基线。
529+
522530
**来源与变化边界。** 共享的 `context_delivery_v1` 展示覆盖完整 quota packet、
523531
完整 Turn envelope 及其公共 work context。surface 纳入既有 Goal/Agent/session/epoch/
524532
capture 绑定,不同展示不能借用彼此基线。扩展的是展示,不改变准入、持久化或结算 authority。
@@ -1164,6 +1172,12 @@ M7 只有在真实 vertical slice 满足 Product Outcome Contract、旧路径被
11641172

11651173
## 语义控制与执行归属
11661174

1175+
可选的 [controller/executor profile](controller-executor-unified-contract-v0.zh-CN.md)
1176+
在既有 owner 内分配模型职责:controller 是唯一面向 Core 的模型客户端,executor 在
1177+
host 强制范围内交流自然语言工作与产物。它不同于确定性的 Turn Loop Controller。
1178+
同一 Agent 可绑定这两个角色,不增加竞争业务 executor 或第二份权限。单会话仍可用;
1179+
角色绑定、结果验证和完整成本资格先于默认提升。
1180+
11671181
LoopX 的语义控制面跨 Turn、Agent 与 runtime 保持工作含义:intent、ownership、
11681182
dependency、authority、evidence 和 continuation。执行责任覆盖它实际拥有的 typed
11691183
transaction 与 settlement step。Agent/capability 推理提出领域结果,kernel 核验

0 commit comments

Comments
 (0)