diff --git a/benchmark/README.md b/benchmark/README.md index c76b079dbe..855bac62d2 100644 --- a/benchmark/README.md +++ b/benchmark/README.md @@ -44,6 +44,18 @@ live tasks, hidden evaluation, credentials, raw trajectories, submissions, and unpublished comparisons remain maintainer-owned. Engineering readiness does not by itself establish a C2 uplift claim. +The [unified work contract and session-role RFC](../docs/architecture/rfcs/controller-executor-unified-contract-v0.md) +extends this build map with C7: benchmark workers should reuse the same qualified +product profile and governed lifecycle as other entrypoints. Benchmark-family +adapters retain task, environment, verifier and scoring semantics. Proposed +single-/two-session comparisons count both sessions and all recovery costs; +helper delivery neither launches trials nor changes frozen historical arms. + +中文：[统一工作契约与会话角色提案](../docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +的 C7 延伸本建设图：worker 复用同一已验收产品模式和治理生命周期，benchmark 适配器 +保留题目、环境、验证与评分语义。拟议单双会话对照计入双方及全部恢复成本； +交付 helper 不启动实验，也不修改已冻结的历史对照臂。 + ## Current work - [Execution observations through ordinary Goal planning](runtime/EXECUTION_OBSERVATIONS.md) diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index 08168db90f..c5fd28ec73 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -191,6 +191,14 @@ Paired diffs do not certify translation accuracy. settlement, and typed Effect Program foundations are shipped. Replan planning/ACK stays domain-local until a second real lifecycle justifies extraction. +- [Controller / Executor Sessions and One Governed Work Contract v0](controller-executor-unified-contract-v0.md) + ([中文版](controller-executor-unified-contract-v0.zh-CN.md)) + - **Delivery on `main`:** Design only; no unified schema or dual-session profile is implemented. + - **Current boundary:** Replaces permanent quota/Turn packet views with one + contract including differential context; controller-only model access to + Core, natural-language executor work and runtime-owned identity/recovery. + C1–C9 connect concrete refactors, real host adoption and complete-cost + qualification without changing defaults or launching experiments. - [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md) ([中文版](typescript-control-plane-migration-v0.zh-CN.md)) - **Delivery on `main`:** Substantially implemented; active migration. diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 6d2656d887..5cb719de11 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -18,7 +18,7 @@ appendix may keep dated history, but no dated log heading may precede it. [中文版](STATUS.zh-CN.md) is the semantic mirror of this file. -## Accepted (46) +## Accepted (47) | RFC | Header status | Supersedes / closes | Ledger | | --- | --- | --- | --- | @@ -31,6 +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 | — | | [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/) | diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index f8791b87d4..7e7433e6df 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -15,7 +15,7 @@ [English](STATUS.md) 与本文互为语义镜像。 -## 已接受 (46) +## 已接受 (47) | RFC | 头部状态 | 替代 / 关闭 | Ledger | | --- | --- | --- | --- | @@ -28,6 +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) | 已接受 | 无 | — | | [显式 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/) | diff --git a/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md b/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md index b5c08ce3d1..8af6d7260e 100644 --- a/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md +++ b/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md @@ -5,7 +5,7 @@ | Status | Accepted | | Supersedes / closes | none | | Date | 2026-08-08 | -| Last normative revision | 2026-10-01 | +| Last normative revision | 2026-10-27 | | Author | LoopX maintainers | | Scope | Public control-plane docs, packet contracts, refactor direction, test strategy | @@ -464,8 +464,12 @@ The existing R5 CLI captures full decisions before projection, with a private di #### Heartbeat and Turn Envelope convergence -Under existing M7.4 and roadmap S2/S3/S6/S8, converge the **execution facts** -used by heartbeat and Turn hosts, while keeping host effect ownership separate. +Under existing M7.4 and roadmap S2/S3/S6/S8, converge heartbeat and Turn +execution into **one governed work contract**, while keeping host effect +ownership explicit. The [controller/executor RFC](controller-executor-unified-contract-v0.md) +owns the complete schema/consumer migration and optional model-session split. +Its target replaces permanent quota/Turn views with one schema, full/delta +delivery and immutable recovery; this does not claim that cutover has shipped. When an admitted Todo later waits on a timer, PR or capability, the typed receipt owner preserves its original writeback and settlement route. Reentry 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: | Todo | Observable outcome and decisive acceptance | |---|---| | 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. | -| 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. | +| 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. | | 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. | **Context cost and projection convergence: next implementation slice** @@ -712,13 +716,17 @@ The next slice stays within the existing three convergence acceptances above: ordinary `quota should-run` input actually consumed by benchmark case solvers; operator/control-plane and personal maintenance packets are secondary. The shared projection delivers complete context on first use and exact changed - subtrees on supported warm turns. Solvers need not switch to TurnEnvelope. + subtrees on supported warm turns. Solvers retain their product entrypoint; + both old packet formats migrate to the single contract. In-packet deduplication and cold-start reduction complement this work; a succession of small cleanups must not substitute for qualifying the repeated input path. A smaller stored capture or import cleanup proves no model saving. -2. **One projection owner, two transport consumers.** Extend the existing typed - interaction/work-context owner for full and delta context; quota and - TurnEnvelope consume it. Preserve original capture, required-source checks, +2. **One contract and one delivery mechanism across hosts.** Extend the existing + typed interaction/work-context owner for full and delta context. Replace + quota and TurnEnvelope output schemas with the unified schema; retain old + decoders only for identified migration readers and historical receipt replay. + Different host wrappers do not create different contract views. Preserve + original capture, required-source checks, invocation, selection, settlement and detail routes. Python retains source IO; hosts retain their effects and context-continuity observation. No independent 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 | 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. | | 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. | +The surface-specific bindings below describe the existing delivery/migration +contract. They remain mandatory while those readers are active; C1–C9 of the +controller/executor proposal replaces both emitted formats. Historical captures +keep their original version and may never reuse a new-schema baseline. + **Source and change boundaries.** The shared `context_delivery_v1` presentation covers whole quota packets, whole Turn envelopes and their common work context. The surface is part of the existing Goal/Agent/session/epoch/capture binding, so @@ -1742,6 +1755,14 @@ Example replacements: ## Semantic control and execution ownership +The optional [controller/executor profile](controller-executor-unified-contract-v0.md) +separates model responsibilities within these owners: the controller is the sole +model-facing Core client; the executor exchanges natural-language work and +artifacts under host-enforced scope. It is not the deterministic Turn Loop +Controller. One Agent may bind those two roles without creating two competing +work executors or a second authority. Single-session behavior remains available; +role binding, result validation and total-cost qualification precede promotion. + LoopX's semantic control plane preserves work meaning across Turns, Agents and runtimes: intent, ownership, dependencies, authority, evidence and continuation. Its execution responsibility covers the typed transactions and settlement diff --git a/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.zh-CN.md b/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.zh-CN.md index 0bf7b7a00b..228bcb2e3c 100644 --- a/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.zh-CN.md +++ b/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.zh-CN.md @@ -5,7 +5,7 @@ | 状态 | 已接受 | | 替代 / 关闭 | 无 | | 日期 | 2026-08-08 | -| 最近规范性修订 | 2026-10-01 | +| 最近规范性修订 | 2026-10-27 | | 作者 | LoopX maintainers | | 范围 | 公开控制面文档、packet 合同、重构方向、测试策略 | @@ -323,8 +323,10 @@ R5 短包投影也完整保留已有 CLI 结算计划，包括 effect identity #### Heartbeat 与 TurnEnvelope 收敛 -沿用既有 M7.4 与 roadmap S2/S3/S6/S8，统一 heartbeat 和 Turn host 消费的 -**执行事实**，宿主效果的所有权仍分别保留。已准入 Todo 随后等待定时、PR 或能力时， +沿用既有 M7.4 与 roadmap S2/S3/S6/S8，把 heartbeat 和 Turn 执行统一为 +**一份受治理工作契约**，显式保留宿主效果所有权。[Controller/executor RFC](controller-executor-unified-contract-v0.zh-CN.md) +拥有完整 schema/消费者迁移和可选模型会话分工：以同一 schema、full/delta 交付及不可变 +恢复替代长期 quota/Turn 视图。这不宣称 cutover 已交付。已准入 Todo 随后等待定时、PR 或能力时， typed receipt owner 保留原回写与结算路径；即使工作已 deferred 或等待已到期，重入也 只投影原收尾，不恢复业务执行、不选择后继、不创建重试时钟。恢复复用原回执中的正向 工作准入和精确结算绑定；工作区修复本身没有业务结果，须先经同轮正常 guard 对精确 @@ -469,7 +471,7 @@ live 模型结果、App 采用或以下三项收敛验收完成。 | Todo | 可观察结果与决定性验收 | |---|---| | 核对 heartbeat 与 TurnEnvelope 的执行和上下文要求 | 同一捕获的权威决策保留 actor/Goal/Todo、必读全文、claim/lease、选择、replan/收尾、带条件结算和 scheduler 所有权。删除渲染分支前列明遗漏与重复事实。覆盖可选能力关闭、仅 recall、仅 ingest、绑定失效和 provider 失败；私有详情只经有权限的引用访问。 | -| 在真实宿主 renderer 采用同一 typed 投影 | heartbeat full/thin 与 Turn host 消费同一执行事实及同 Turn 捕获/详情入口；显式保留通知和 scheduler 的宿主传输。真实 File/SQLite CLI 与打包 Codex App 覆盖重入、来源丢失、必读前拒绝、迟到结果、backoff 和一次结算；补读不触发第二次准入。最后调用方迁移后才退役旧投影。 | +| 在真实宿主入口采用统一契约 | heartbeat full/thin 与 Turn host 消费同一 schema 及同 Turn 捕获/详情入口，不长期保留分格式的语义视图；显式保留通知和 scheduler 的宿主传输。真实 File/SQLite CLI 与打包 Codex App 覆盖重入、来源丢失、必读前拒绝、迟到结果、backoff 和一次结算；补读不触发第二次准入。最后调用方迁移后才退役旧投影。 | | 核验上下文形态及迁移默认 | 将相同的正常、replan、等待/恢复与可选能力负载同时对照当前完整和短包路径，测量载荷/model token、详情 IO、延迟、资源增长、遗漏、决策与结果质量。数据丢失、重复效果、身份和结算错误保持硬约束；保留受支持的已保存 prompt/回执与可逆 rollout，根据证据再改预算或默认。 | **上下文成本与投影融合：下一实现切片** @@ -484,12 +486,14 @@ live 模型结果、App 采用或以下三项收敛验收完成。 1. **以完整首包、后续子树增量作为融合目标。** 优先优化 benchmark case 内 solver 实际 消费的普通 `quota should-run` 输入，实验操作者/控制面对话及个人维护包为次要项。 - 共享投影首次完整交付，支持温态复用时只交付精确变化子树，solver 无需切换 TurnEnvelope。 + 共享投影首次完整交付，支持温态复用时只交付精确变化子树。Solver 保留产品入口， + 两种旧 packet 格式共同迁入统一契约。 包内去重和冷启动缩减作为配套；连续做小清理不能替代重复输入路径的验收。存储 capture 缩小或 import 清理不能证明模型输入节省。 -2. **一个投影 owner，两个传输调用方。** 扩展已有 typed interaction/work-context owner， - 同时生成完整和增量上下文，由 quota 与 TurnEnvelope 消费。保留原始捕获、required-source - 校验、调用、选择、结算与详情入口；Python 保留来源 IO，host 保留效果执行和上下文连续性 +2. **跨宿主使用同一契约、同一交付机制。** 扩展已有 typed interaction/work-context owner， + 同时生成完整和增量上下文，用统一 schema 替代 quota 与 TurnEnvelope 输出 schema； + 旧 decoder 只服务具名迁移 reader 和历史回执 replay。不同宿主外层包装不构成不同契约 + 视图。保留原始捕获、required-source 校验、调用、选择、结算与详情入口；Python 保留来源 IO，host 保留效果执行和上下文连续性 观察。不新增独立准入服务、diff daemon 或 Python 上下文决策 owner。刻画调用方并在采用后 删除被替代投影。输出释放前的 host 传输 ACK 既不证明模型完整收到了内容，也不证明其仍被 保留。现有 capture/handoff 是接入位置，并非已经实现的连续性契约。 @@ -519,6 +523,10 @@ live 模型结果、App 采用或以下三项收敛验收完成。 | Turn 采用 | 消费同一完整/增量上下文 owner，同时保留 Turn 签名和外层 executor 效果归属。host 独占的结算执行与手动 CLI agent 的可执行结算义务仍有区别。 | | 表示选择 | 计入绑定和删除元数据后，只有更小才发送 delta，否则发送全量。不为字节目标截断值或改变来源选择。 | +以下按 surface 区分的绑定描述现有交付/迁移契约；对应 reader 活跃时仍必须遵守。 +Controller/executor 提案的 C1–C9 替换两种输出格式；历史 capture 保留原版本， +不能借用新 schema 基线。 + **来源与变化边界。** 共享的 `context_delivery_v1` 展示覆盖完整 quota packet、 完整 Turn envelope 及其公共 work context。surface 纳入既有 Goal/Agent/session/epoch/ capture 绑定，不同展示不能借用彼此基线。扩展的是展示，不改变准入、持久化或结算 authority。 @@ -1164,6 +1172,12 @@ M7 只有在真实 vertical slice 满足 Product Outcome Contract、旧路径被 ## 语义控制与执行归属 +可选的 [controller/executor profile](controller-executor-unified-contract-v0.zh-CN.md) +在既有 owner 内分配模型职责：controller 是唯一面向 Core 的模型客户端，executor 在 +host 强制范围内交流自然语言工作与产物。它不同于确定性的 Turn Loop Controller。 +同一 Agent 可绑定这两个角色，不增加竞争业务 executor 或第二份权限。单会话仍可用； +角色绑定、结果验证和完整成本资格先于默认提升。 + LoopX 的语义控制面跨 Turn、Agent 与 runtime 保持工作含义：intent、ownership、 dependency、authority、evidence 和 continuation。执行责任覆盖它实际拥有的 typed transaction 与 settlement step。Agent／capability 推理提出领域结果，kernel 核验 diff --git a/docs/architecture/rfcs/agent-session-execution-modes-v0.md b/docs/architecture/rfcs/agent-session-execution-modes-v0.md index 7b8b3daad4..eae0ae1440 100644 --- a/docs/architecture/rfcs/agent-session-execution-modes-v0.md +++ b/docs/architecture/rfcs/agent-session-execution-modes-v0.md @@ -9,7 +9,7 @@ the session-ownership decision already described for the Desktop frontend. Session-ownership and host-admission decisions require maintainer acceptance. - **Created:** 2026-09-15 -- **Last normative revision:** 2026-09-15 +- **Last normative revision:** 2026-10-27 - **Implementation baseline:** `6c3da75ca` - **Related contracts:** [Desktop execution frontends](desktop-execution-frontends-v0.md), [Single-owner local daemon](single-owner-local-daemon-v0.md), @@ -229,6 +229,22 @@ monitor, or lifecycle truth; conversation text as a receipt; a second scheduler for the same binding; a Goal-wide default binding; and a mode change inferred from a probe, a transport, or a prompt. +### Controller and executor session roles + +The [unified work contract RFC](controller-executor-unified-contract-v0.md) +proposes an optional controller model session plus one business executor under +one logical Agent. This is a role distinction, not a third execution mode or +authority rank. Extend the existing binding owner with explicit role/generation, +separate ordered queues and independent context baselines before admitting both +sessions. Never overwrite the single Agent-scoped native-session slot with two +IDs. The one-active-executor invariant applies to the business work; a controller +role is not permission for a second simultaneous business executor. Its only +Core access is through existing scoped operations, and host enforcement keeps +Core credentials/write tools outside executor access. Role changes, stop, late +results and controller recovery must retain the original request/attempt and +settlement binding. Until that profile qualifies, existing bindings retain their +current behavior; no implicit conversion or host promotion follows. + ### Reusable Agent operations and continuation ownership The existing frontend Goal Chat is the baseline conversational coordinator. The @@ -614,6 +630,7 @@ extending this RFC with a competing rule. | [TypeScript control-plane migration](typescript-control-plane-migration-v0.md) | Which surface owns typed state machines, effects, and settlement rules during migration | Mode transitions that become machine-enforced belong to that typed boundary. Python adapters may bridge the contract but must not fork session-mode authority. | | [Goal Channel collaboration](goal-channel-collaboration-v0.md) | Goal-bound collaboration surfaces, channel delivery, notifications | Owns where collaboration is delivered. This RFC owns which session binding the delivery targets and whether that binding can accept it. | | [LoopX Turn v0](../../reference/protocols/loopx-turn-v0.md) | The bounded governed Turn: decide, execute, validate, write back, spend once | The execution unit used by managed hosts and by attached hosts that return governed results. This RFC does not extend the Turn contract. | +| [Controller/executor and unified contract](controller-executor-unified-contract-v0.md) | Unified Core input, model-role split, natural-language executor exchange and path retirement | This RFC owns role binding, modes and host lifecycle; the new proposal owns cross-path acceptance. The controller model is distinct from the pure disposition function below. | | [Turn loop controller](../../reference/protocols/turn-loop-controller-v0.md) | The pure disposition transition for continued Turns and its budget semantics | Decides whether another Turn is eligible. It does not own a session, start processes, or schedule work. | | [Host mode plan](../../reference/protocols/host-mode-plan-v0.md) | User-facing host-mode selection from intent and advertised capabilities, and the preview command it prints | A different axis: how work advances and through which connector. It is not a mode authority; a selected host must still declare its session mode per this RFC. | | [Session runtime projection](../../reference/protocols/session-runtime-loopx-projection-v0.md) | The read-only projection of an external runtime session into LoopX without copying private traces | Consistent with `attached_host`: the runtime owns transcripts, LoopX owns its own state. This RFC adds no projection fields. | diff --git a/docs/architecture/rfcs/agent-session-execution-modes-v0.zh-CN.md b/docs/architecture/rfcs/agent-session-execution-modes-v0.zh-CN.md index 17c7a274b2..2979461441 100644 --- a/docs/architecture/rfcs/agent-session-execution-modes-v0.zh-CN.md +++ b/docs/architecture/rfcs/agent-session-execution-modes-v0.zh-CN.md @@ -7,7 +7,7 @@ - **作者 / 负责人：** 由维护者指示整理的契约。它把桌面端提案中已有的会话归属决策 抽取并规范化。会话归属与宿主接入决策需要维护者接受。 - **创建日期：** 2026-09-15 -- **最近规范性修订：** 2026-09-15 +- **最近规范性修订：** 2026-10-27 - **实现基线：** `6c3da75ca` - **相关契约：** [桌面执行前端](desktop-execution-frontends-v0.zh-CN.md)、 [单属主本地守护进程](single-owner-local-daemon-v0.md)、 @@ -185,6 +185,17 @@ claim 与完成回执，以及"只有经过验证的回写才推进工作"这一 +### Controller 与 executor 会话角色 + +[统一工作契约 RFC](controller-executor-unified-contract-v0.zh-CN.md) 提议同一逻辑 Agent +可选地使用一个 controller 模型会话和一个业务 executor。这是角色区别，不是第三种执行 +模式或权限等级。同时准入前，先扩展既有 binding owner，显式记录 role/generation、 +独立有序队列与各自上下文基线。不能往单一 Agent 级 native-session 槽位写两个 ID。 +一个活跃 executor 的不变量约束业务工作；controller role 不许可第二个并发业务 executor。 +它通过既有受限操作访问 Core，host 强制把 Core 凭据/写工具排除在 executor 权限之外。 +角色变化、Stop、迟到结果及 controller 恢复须保留原 request/attempt 和结算绑定。 +该 profile 合格前，已有绑定行为不变；不隐式转换或提升 host。 + ### 可复用的 Agent 操作与续跑归属 现有前端 Goal 对话是会话型 coordinator 的基线入口。所有者也可以把 peer @@ -484,6 +495,7 @@ App 自有心跳的模型唤醒抑制仍需要宿主下发前钩子。通用 pro | [TypeScript 控制面迁移](typescript-control-plane-migration-v0.zh-CN.md) | 迁移期间由哪个面拥有类型化状态机、effect 与结算规则 | 成为机器强制的模式转换属于那个类型化边界。Python 适配器可以桥接契约，但不得分叉会话模式权威。 | | [Goal Channel 协作](goal-channel-collaboration-v0.zh-CN.md) | Goal 绑定的协作面、通道投递与通知 | 拥有协作投递到哪里。本 RFC 拥有投递所针对的会话绑定，以及该绑定能否接受它。 | | [LoopX Turn v0](../../reference/protocols/loopx-turn-v0.md) | 有界受治理 Turn：decide、execute、validate、write back、spend once | 托管宿主使用的执行单元，也是返回受治理结果的挂接宿主使用的单元。本 RFC 不扩展 Turn 契约。 | +| [Controller/executor 与统一契约](controller-executor-unified-contract-v0.zh-CN.md) | 统一 Core 输入、模型角色分工、自然语言 executor 交流与路径退役 | 本文拥有角色绑定、mode 和 host 生命周期；新提案拥有跨路径验收。Controller 模型区别于下一行的纯 disposition 函数。 | | [Turn 循环控制器](../../reference/protocols/turn-loop-controller-v0.md) | 继续 Turn 的纯处置转换及其预算语义 | 判断是否还有下一个 Turn 有资格执行。它不拥有会话、不启动进程、不调度工作。 | | [宿主模式规划](../../reference/protocols/host-mode-plan-v0.md) | 依据意图与已声明能力做面向用户的宿主模式选择，以及它打印的预览命令 | 这是另一个轴：工作如何推进、经由哪个连接器。它不是模式权威；被选中的宿主仍须按本 RFC 声明其会话模式。 | | [会话运行时投影](../../reference/protocols/session-runtime-loopx-projection-v0.md) | 把外部运行时会话只读投影进 LoopX，且不复制私有 trace | 与 `attached_host` 一致：运行时拥有 transcript，LoopX 拥有自己的状态。本 RFC 不新增投影字段。 | diff --git a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md index b9cd91d9d9..5683e7c604 100644 --- a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md +++ b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.md @@ -4,7 +4,7 @@ - **Supersedes / closes:** [Personal Follow-through independent proposal](personal-follow-through-v0.md) - **Delivery maturity:** Partial; private runtime profile, team-plan confirmation and Todo materialization shipped; complete M1–M4 remain unqualified. - **Authors / owners:** LoopX maintainers; manager engineering owner -- **Created / last normative revision:** 2026-09-13 / 2026-10-04 +- **Created / last normative revision:** 2026-09-13 / 2026-10-27 - **Implementation baseline:** `7eb4b7bb1661bd5eff63a8725a33169792d5964b` - **Language mirror:** [中文版](capable-manager-semantic-handoff-v0.zh-CN.md) - **Related contracts:** [Effect interpreter](agent-loop-effect-interpreter-v0.md), [Manager continuity](../../reference/protocols/manager-evidence-and-continuity-v0.md), [Goal Vision/Replan](../../reference/protocols/goal-vision-replan-contract-v0.md), [Desktop frontends](desktop-execution-frontends-v0.md), [Shared authority](shared-goal-authority-state-provider-v0.md), [Shared Goal alignment/amendment](shared-goal-alignment-and-governed-amendment-v0.md), [TS migration](typescript-control-plane-migration-v0.md) @@ -187,6 +187,15 @@ For a small local manager action, a current request/Turn and accepted effect rec The durable semantic context consists of a small typed identity/control header plus a versioned human-readable brief and resolvable work/artifact references. The header drives routing and legal transitions. The brief carries open-ended domain meaning; Core does not classify every sentence into a rigid schema. This is dense general-task state, not serialization of the model's hidden thoughts. The same context remains available when a runtime session is replaced. +The [controller/executor proposal](controller-executor-unified-contract-v0.md) +applies this semantic exchange to two session roles within one logical Agent. +Only the controller model consumes the unified Core contract and authors typed +Core operations. The executor receives natural-language work with complete +authorized materials and returns artifacts/evidence, not a specialized Core +packet view. Runtime-owned routing/revision/attempt metadata reuses these request +records; it is not another authority or handoff ledger. This does not restrict +independent peer Agents, which retain their own scoped Core relationships. + Prefer one cohesive replacement to compatibility wrappers that preserve duplicate decisions. Inventory every existing producer/reader, migrate with lossless mappings, switch one writer and delete the replaced rules. Reusing contracts and data is required; reusing every current class, JSON directory and prompt is not. The lead Agent owns task decomposition, investigation, delegation, revision and diff --git a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md index 8a4bfc1384..1c15253fbd 100644 --- a/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md +++ b/docs/architecture/rfcs/capable-manager-semantic-handoff-v0.zh-CN.md @@ -4,7 +4,7 @@ - **替代 / 关闭：** [个人事项持续跟进独立提案](personal-follow-through-v0.zh-CN.md) - **交付成熟度：** Partial；私人运行 profile、团队计划确认与 Todo 物化已交付，完整 M1–M4 未验收。 - **作者 / 责任人：** LoopX 维护者、管家工程负责人 -- **创建 / 最近规范修订：** 2026-09-13 / 2026-10-04 +- **创建 / 最近规范修订：** 2026-09-13 / 2026-10-27 - **实现基线：** `7eb4b7bb1661bd5eff63a8725a33169792d5964b` - **语言镜像：** [English](capable-manager-semantic-handoff-v0.md) - **相关契约：** [Effect interpreter](agent-loop-effect-interpreter-v0.zh-CN.md)、[管家连续性](../../reference/protocols/manager-evidence-and-continuity-v0.md)、[Goal Vision/Replan](../../reference/protocols/goal-vision-replan-contract-v0.md)、[桌面入口](desktop-execution-frontends-v0.zh-CN.md)、[共享权威](shared-goal-authority-state-provider-v0.zh-CN.md)、[共享目标对齐/修订](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md)、[TS 迁移](typescript-control-plane-migration-v0.zh-CN.md) @@ -155,6 +155,13 @@ flowchart LR 持久语义上下文由小型 typed 身份/控制头、版本化可读 brief、可解析工作/工件引用构成。头部用于路由和合法转移，brief 承载开放的领域含义，Core 不把每句话硬分成固定 schema。这是通用工作稠密状态，不是序列化模型隐藏思维；runtime session 换掉后也能续接。 +[Controller/executor 提案](controller-executor-unified-contract-v0.zh-CN.md) 把这种语义交流 +用于同一逻辑 Agent 内的两个 session role。只有 controller 模型消费统一 Core 契约并 +编写 typed Core 操作。Executor 接收自然语言任务和完整授权材料，返回产物/证据， +不消费专用 Core packet 视图。运行时持有的路由/revision/attempt 元数据复用这些请求 +记录，不形成另一套权限或交接账本。独立 peer Agent 仍保留各自受限的 Core 关系， +不受这个同 Agent 内部角色划分限制。 + 优先一次内聚替换，不用兼容包装长期保留两套判断。盘点所有 producer/reader，无损迁移、切换单 writer、删除被替代规则。必须复用有效契约和数据，不必复用每个类、JSON 目录和 prompt。 主 Agent 负责拆解、调查、委派、修订和综合；host 服务执行已准入动作并恢复其回执， diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md new file mode 100644 index 0000000000..4c9b6074ab --- /dev/null +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md @@ -0,0 +1,769 @@ +# RFC: Controller / Executor Sessions and One Governed Work Contract (v0) + +- **RFC status:** Accepted (design acceptance takes effect on merge) +- **Supersedes / closes:** none +- **Delivery maturity:** Proposal; no new runtime, schema or default is shipped by this document. +- **Authors / owners:** LoopX maintainers; control-plane and runtime owners +- **Created:** 2026-10-27 +- **Last normative revision:** 2026-10-27 +- **Implementation baseline:** `fe2b8dcbcb998647edb4bafb51932988bd7fdaa6` +- **Related contracts:** [Effect interpreter](agent-loop-effect-interpreter-v0.md), [Session execution modes](agent-session-execution-modes-v0.md), [Semantic handoff](capable-manager-semantic-handoff-v0.md), [Overall roadmap](loopx-overall-roadmap-v0.md) +- **Language mirror:** [中文版](controller-executor-unified-contract-v0.zh-CN.md) + +## Document map and maintenance contract + +The English and Chinese documents are semantic mirrors; a difference is a defect. + +Section 4 records source facts at the named baseline. Sections 1–3 and 5–11 +define the proposed decision and acceptance; section 12 records unresolved +choices. Before merge this is a review proposal. Merge accepts the design, +not implementation, installation, experiments or default promotion. Historical +evidence belongs in a dated ledger when an implementation first produces it. + +## 1. Decision summary + +1. Converge quota execution packets and TurnEnvelope into **one versioned + governed work contract**: one schema, one semantic producer, one capture, + one delivery/recovery mechanism and one settlement identity. Different hosts + carry that same contract; permanent quota/Turn compatibility views are not + the target. Combine quota packet's decision-necessary information with + TurnEnvelope's delivery efficiency; replace both and qualify the net change + against the original quota-packet path. Existing domain owners still decide + their own facts. +2. In the optional two-session profile, the **controller model session is the + sole model-facing Core client**. It reads the contract, reasons about work, + talks to the executor and submits explicit typed Core operations. Core owns + legal transitions and receipts; the controller is not a second authority. +3. The executor receives a natural-language task conversation, original source + material and ordinary host tools. It returns findings, artifacts, evidence + and questions. It neither consumes a second Core packet view nor authors + quota, Vision, lease or settlement fields. A small machine carrier records + routing and causality outside the task prose. +4. Full-first delivery, exact differential context and automatic full recovery + are capabilities of the single contract. Controller and executor sessions + have independent continuity evidence; one cannot borrow the other's baseline. +5. Unification first qualifies the existing single-session path. Two-session + execution remains opt-in until matched outcome and complete-cost evidence + justifies adoption. This RFC launches no benchmark or privileged operation. + +## 2. Problem and motivation + +A task can enter through App heartbeat, an external worker or `loopx turn`, yet +its context and result obligations are presented differently. Shared decision +facts already exist, but callers still choose packet formats, reconstruct +prompts and adapt model-authored bookkeeping. Adding another controller-specific +packet would multiply these paths. + +For example, an executor asked to repair a failing export needs the original +requirements, the failure, permitted workspace and independent acceptance. It +does not need to learn how to encode a Vision delta or debit a LoopX Turn. +Separating that work may reduce distraction and repeated protocol input, but +an extra controller can also lose constraints, add latency or over-coordinate. +These are hypotheses to test, not benefits established by session separation. + +### Invariants + +- Preserve complete accepted requirements, revisions, authority, unresolved + reads and evidence provenance; a shorter prompt is not permission to omit them. +- Exactly one current control owner and one admitted executor attempt for the + selected work. Dialogue, routing ACKs and model completion are not receipts. +- Notifications do not govern execution. A quiet notification result cannot + cancel admitted work; a message cannot override a genuine stop or budget gate. +- A governed Turn is a bounded work/settlement unit, not a wake, model response + or controller/executor exchange. Do not charge a new Turn for each message. +- Preserve original identity through retry, source correction and closeout; + never settle an old result against a newly selected Todo. + +## 3. Scope and non-goals + +In scope: contract convergence, context delivery, role-specific session binding, +controller/executor communication, shared lifecycle reuse, host adapters, +benchmark adoption, retirement and observable product acceptance. + +Non-goals: a new Goal store, workflow DSL, generic effect executor, permission +engine, scheduler, mandatory two-Agent team, automatic host switching or changes +to benchmark scoring. Peer teams retain existing delegation/acceptance contracts. +This proposal does not move business reasoning into deterministic Core rules. + +## 4. Current-system contract + +| Existing concept | Actual role / source | Consequence for the target | +| --- | --- | --- | +| Quota packet / TurnEnvelope | [`quota.py`](../../../loopx/cli_commands/quota.py) projects a decided payload through separate ordinary/envelope branches; [`turn_envelope.ts`](../../../loopx/control_plane/quota/turn_envelope.ts) supplies bounded sections and action binding | Migrate both sets of obligations into one schema, then retire both old output paths | +| Work context | [`interaction_contract.ts`](../../../loopx/control_plane/work_items/interaction_contract.ts) carries typed execution/context requirements | Extend the existing owner; do not create a controller decision engine | +| Thin heartbeat | [`task_body.py`](../../../loopx/control_plane/heartbeat/task_body.py) renders product entry instructions with format-dependent branches | Keep the bootstrap/host entry; converge its consumed contract | +| `loopx turn` | [`turn.py`](../../../loopx/cli_commands/turn.py), [`executor.py`](../../../loopx/control_plane/turn_driver/executor.py), [`settlement.py`](../../../loopx/control_plane/turn_driver/settlement.py) implement governed invocation and receipt-bound closeout | Reuse the lifecycle; a CLI entry is not another product runtime | +| Managed Codex | [`codex_agent_session.py`](../../../loopx/control_plane/turn_driver/codex_agent_session.py) and [`codex_sessions.py`](../../../loopx/control_plane/turn_driver/codex_sessions.py) implement native session execution/resume | Runtime adapter, not a competing control plane; current Agent-scoped storage lacks the proposed role distinction | +| Executor result | [`codex_cli.py`](../../../loopx/control_plane/turn_driver/codex_cli.py) asks for a schema-constrained result including delivery and Vision/progress fields | Move Core authoring responsibility to the controller in the two-session profile; preserve validation | +| External worker | [`external_scheduler_worker.py`](../../../scripts/external_scheduler_worker.py) owns outer wake/command transport | Preserve that ownership; remove duplicate semantic orchestration where demonstrated | +| Benchmark runner | [`worker.py`](../../../benchmark/runtime/worker.py) uses the product thin body for heartbeat and public Turn CLI for Turn mode; [`sessions.py`](../../../benchmark/runtime/sessions.py) reuses the native session adapter | Evaluation harness around product profiles, not a separate implementation target | +| Turn Loop Controller | [Stable protocol](../../reference/protocols/turn-loop-controller-v0.md) defines a pure disposition function | Keep it deterministic; it is not the proposed controller model session | + +Execution mode (`managed_runtime` / `attached_host`), runtime provider, wake +source, single/two-session organization and evaluation arm are independent +axes. Not every combination is supported. Native/plain benchmark controls may +intentionally have no LoopX Core and must remain uncontaminated controls. + +### C1 source audit: shared owners and the remaining split + +The source already shares more than the output names suggest. `_emit_quota_result` +captures the complete decision **before** `_project_quota_cli_payload` chooses +ordinary CLI compaction or `buildTurnEnvelope`. The latter delegates to the +TypeScript owner; its Python module is a transport adapter. Both quota capture +and Turn journal capture call `write_decision_capture` in +[`decision_capture.py`](../../../loopx/control_plane/turn_driver/decision_capture.py). +Native context delivery and explicit host handoff also reuse that module and +the existing context-delivery owner. C1 must converge the remaining composition +and consumer assumptions, rather than introduce another capture service or +rewrite already shared delta/native-resume logic. + +| Current source / obligation | Present envelope treatment | Required C1 disposition | +| --- | --- | --- | +| `interaction_contract.agent_channel.work_context` and pending required reads | `work_context` plus `required_reads`; identical inline material can be referenced | One complete requirement/evidence source with resolvable references; preserve pending reads and their completion conditions | +| Selected Todo, recommended action, action portfolio and planning horizon | `action`; reference relocation and text compaction occur in `turnActionProjection` | One selected work/action identity; preserve complete actionable clauses and distinguish summaries from executable instructions | +| `interaction_contract.cli_channel.settlement_plan` | Copied into `writeback.settlement_plan`, including original effect identity and conditional steps | Reuse the settlement owner unchanged; neither controller dialogue nor a new capture creates another debit identity | +| User/agent interaction channels, execution policy and task orchestration | Separate `user`, `execution_policy`, `boundary` and orchestration sections | Preserve notification versus execution obligations, authority and stop gates; do not derive them from prose | +| Replan packet, required reads and staged writeback | Dedicated replan projection and deferred writeback | Preserve fact/source access, policy-specific triggers and ordered mutations; no blanket activation of stride behavior | +| Scheduler context and execution ownership | Scheduler projection with caller execution context | Carry the actual host owner and ACK obligations; a common schema does not transfer scheduler authority | +| Complete saved decision, action signature and journal binding | Source hash, projected action hash and captured-decision reference are distinct | Preserve the distinction between semantic integrity, exact transport bytes and receipt identity; no hash substitution | + +This is an owner-and-obligation map, **not an exhaustive field inventory or a +parity result**. Current projections have bounded text, allowlists and relocated +references. Matching their action signatures alone cannot prove preservation of +all source clauses or unknown fields. C1 implementation must enumerate those +fields and callers against its exact base/head; anything unclassified holds +cutover, rather than disappearing into an assumed compatibility view. + +A synthetic probe of the named baseline demonstrates the limit: two long +`recommended_action` strings with identical prefixes but different tails produce +the same action-signature document and both report `matches=true`, while their +`source_decision_hash` values differ. An unregistered top-level source field has +the same distinction. Conversely, a complete registered settlement plan survives +projection, and changing its Turn identity changes the action signature. These +observations reject promoting the existing bounded envelope unchanged into the +complete contract. They do **not** establish a current authority-loss bug: the +recommendation is diagnostic, the unknown field is synthetic, and the complete +source commitment still distinguishes both inputs. No model benefit is measured. + +## 5. Proposed architecture + +### Ownership and one contract + +```text +Core owners <-> unified governed work contract <-> controller session + | + task / findings / artifacts + | + executor session + | + scoped host tools + +Host adapters enforce dispatch, session fences, interruption and transport. +Core owners validate operations and commit existing effect/settlement receipts. +``` + +Use the existing TypeScript interaction/work-context and effect owners. The +composition owner captures their current facts once; it does not reimplement +quota, replan, Todo or lease decisions. Python may collect sources and adapt +native transport. Host-specific execution ownership remains explicit in the +same contract, including delegated scheduler effects and their ACK obligations. + +The schema name and exact field migration require the task C1 inventory below. +The following are required semantic groups, **not additional nested protocols**: + +| Group | Preserved capabilities | +| --- | --- | +| Identity and current decision | Contract version, capture/revision, Goal/Agent/work/Turn binding, selected action, admission, claim/lease, scope, approvals, cancellation and stop conditions | +| Complete work context | Original intent and requirements, unresolved obligations, accepted evidence, current sources/revisions, required-read completion and authorized detail access | +| Context delivery | Full/delta encoding, exact base/target digests, consumer session/role/epoch and immutable capture recovery | +| Operations and closeout | Available typed operations, action binding/integrity, conditional ordering, validation and writeback/debit identity, scheduler and notification ownership | + +There is one semantic instance and one schema across CLI, heartbeat, managed +Turn and evaluation. Full versus delta is an encoding choice for that instance; +pagination is a transport limit. Neither creates a quota schema and a Turn +schema. Native tool wrappers may carry provider-required envelopes without +renaming, omitting or independently deciding contract fields. Human UI read +models remain presentation sinks, not alternate executable contracts. + +The composition boundary is **after current domain decisions and host-operation +binding, before immutable capture and context encoding**. All live writers use +that boundary. They must not first compact a quota packet into an envelope and +then label the result the complete unified contract. Required source material +may use authorized detail references, but those references, revisions and read +obligations must be complete and recoverable from that same semantic capture. + +“One capture” means one immutable semantic observation for an invocation, not +one file for every purpose. Keep the complete canonical instance, encoded +full/delta/page artifacts and the Turn journal's binding distinguishable. Exact +file-byte digests protect transport; canonical hashes protect semantic content; +the existing effect identity protects once-only settlement. None substitutes +for another or grants current authority. Reserve an identity/location before +serialization when recovery references need it; do not require a document to +contain the digest of its own final bytes. Encoding, pagination, native resume +and recovery derive from the saved instance without another guard. A legitimate +new selection or authority check may produce a new capture; it must not rewrite +an earlier observation or silently rebind an outstanding result. + +### Review freshness and recovery + +A complete capture proves what was observed; it does not freeze write-time +validity. Keep semantic content identity, review relevance and settlement +identity distinct. A supporting outcome owned by another agent may still +constrain the shared Goal: owner labels alone cannot remove its acceptance or +requirement-status changes from the review basis. Narrow invalidation requires +an explicit dependency-scoping rule and tests for shared constraints, not a +role-name filter or an allowlist inferred from prose. + +When the same admitted obligation rejects a stale review, its current typed +owner should return the complete current review basis and applicable control +instructions. The consumer reads and reassesses that basis, then retries the +original writeback with its original identities. Do not send it an unbound +write command or require another guard merely to retrieve facts already used +by the writer. A changed basis still rejects; returning context does not accept +a decision or authorize spending. This recovery belongs to the existing +composition/writeback boundary and must survive the C1 writer transition. +It is not a claim that cross-agent invalidation has been narrowed or that the +complete unified contract is delivered. + +### Executor input and output + +Choose **natural-language work exchange with runtime-owned metadata**, rather +than an executor-facing Core view or an untracked chat. The controller explains +the objective, relevant facts, boundaries and acceptance in task-appropriate +prose; it can steer, answer questions and revise a request. The host carries +opaque request/revision, attempt, session/generation, causal sequence and +artifact references using existing request/dispatch records. The model need +not reproduce those identifiers in prose. No new independent message ledger +is introduced. + +Original requirements and authorized evidence are attached or accessible through +host material readers. Core capture and access checks are performed by the +controller/runtime; the executor does not call Core to retrieve them. Preserve +mandatory source reading through the actual material delivery/read mechanism; +controller paraphrase or a routing ACK is insufficient. Required material that +cannot be delivered blocks dependent execution; independent work may continue. +Untrusted source text never acquires instruction or tool authority. + +The executor chooses its local tools and steps within the delegated scope. It +does not ask the controller before every tool use. Tool permission enforcement +belongs to the host/provider, including scoped filesystem/process access: +omitting a Core tool name from the prompt is not isolation. An unrestricted shell +with Core credentials would violate this profile. Unsupported isolation is +reported as unsupported, without silently claiming a qualified two-session mode. + +Outputs preserve the requested deliverable, artifact references, observed +validation, failures and uncertainty. The controller interprets these results, +performs or requests independent verification and submits explicit typed Core +commands. Core never infers completion, permission or replan from substrings in +the executor prose. Host termination is not business completion. A failed +validation can lead to feedback and further work within the same admitted scope; +a material scope/revision change needs a newly qualified dispatch. + +**Length is language-neutral and task-dependent.** Preserve independently +executable meaning before minimizing size. Initial experimental targets are +200–800 model tokens for an ordinary brief, 800–2000 for a complex handoff and +150–600 for a result summary. These are unvalidated starting points, not schema +limits, defaults, pass criteria or truncation rules. Count with the actual model +tokenizer; record language/content mix. Code, mathematics, tables, source material +and full requested deliverables retain their natural format. Measure summaries, +attachments, rereads and all exchanges together; moving text behind a reference +does not remove its cost. Small same-session corrections carry only the change +when continuity is proven, with no minimum length requirement. + +For example, the controller can ask: “Repair the export failure shown in the +attached reproduction; preserve the original ordering requirement and stay in +the assigned workspace. Validate the regression and report remaining gaps.” +The response can explain the change and link the patch and independent test +result. Neither sentence is a substitute for original requirements, a permission +grant or a canonical completion receipt. + +### Sessions, lifecycle and recovery + +Start with one logical work Agent and two explicitly bound native session +roles. Do not create a second Goal/Todo/quota identity merely to split cognition. +Extend the existing session binding owner with role and generation, separate +ordered queues and separate context baselines; do not write two native IDs into +the current single Agent-scoped slot. One controller owns control dialogue; +at most one executor attempt owns the selected work. The controller role is not +another simultaneous business executor. Peer or parallel execution still needs +its existing independent claim/lease/handoff contract. + +1. The existing entrypoint obtains fresh admission or resumes an owed receipt. + It supplies the captured unified contract to the controller. +2. The controller reasons from the Goal, unmet requirements, results and feasible + work; Core validates its chosen operation. Replan policy still controls when + review is required. Fact-first reasoning does not turn a stride-only trigger + into the default policy or require a gratuitous route change. +3. Before dispatch, the host binds work/request revision, attempt, session role, + generation, scope and budget. Record intent before invoking the executor. +4. The executor works and returns observations/artifacts. Readback distinguishes + delivery, execution, result availability, independent validation and accepted + writeback. Dialogue can span several exchanges without multiple quota debits. +5. The controller proposes acceptance or revision; the existing effect owner + validates and settles the original Turn exactly once. A fresh decision then + continues runnable work, waits on the recorded event/time or stops. + +| Failure | Required handling | +| --- | --- | +| Controller crashes after dispatch | Recover the persisted attempt and executor state/result before deciding to resend; do not start a duplicate executor | +| Result/settlement response is lost | Read existing receipts by original idempotency identity; retry only the unresolved effect | +| Executor restarts or context is compacted | Fence the old generation, requalify continuity and deliver complete current material if unknown | +| Cancellation, changed requirements, expired lease or late result | Revalidate current authority/revision before every owned dispatch/write; retain evidence, reject stale acceptance and reconcile admitted effects | +| Stop while a tool is running | Host interrupts within its supported contract; report acknowledgement and actual termination separately. Preserve unknown/in-flight effects; never claim physical rollback from a stop receipt | +| Controller is unavailable | Existing host/Core stop and budget mechanisms remain effective; hold dependent work and recover, without asking the executor to become Core owner | + +### Differential context + +Reuse the existing context-delivery owner and immutable capture mechanism. +Deliver complete context first. Send exact registered-subtree deltas only with +proven complete delivery and retained context in the exact consumer session, +role, epoch, schema and source capture. Preserve deletion, array order, null, +empty values and complete strings. Unknown fields remain fully delivered until +their reuse semantics are registered; send full if delta plus metadata is larger. + +Current authority, admission, cancellation, unresolved-read, settlement and +scheduler facts stay fresh and inline even if unchanged. A warm transport never +relaxes the underlying instructions. Missing/out-of-order deltas, truncation, +compaction, corrupt or unknown baselines select full recovery from the same +capture automatically, without another admission/debit. Execution still checks +current source validity and authority; recovering an old capture cannot revive +cancelled work. The executor's task conversation is a separate consumer of +semantic material, not a relabeled delta of the controller's Core packet. + +## 6. Alternatives and design choices + +| Alternative | Disposition | +| --- | --- | +| Keep quota and TurnEnvelope as permanent compatible views | Reject as the end state: duplicate selection/rendering and field-drift remain; retain only bounded migration decoders | +| Give the executor a compact Core packet view | Reject as the default two-session design: it retains protocol authoring load and two model-facing Core clients | +| Pure natural-language chat with no runtime binding | Reject: stale/duplicate results, cancellation and restart cannot be reliably reconciled | +| Always use two sessions | Reject: controller cost, latency and lossy delegation may exceed the benefit; keep a qualified single-session profile | +| One universal runtime/effect executor | Reject: host, scheduler, transaction and provider permissions differ; share semantics and receipts, not ownership | + +## 7. Safety, privacy and compatibility + +Controller reasoning grants no extra authority. Runtime credentials and Core +write capabilities remain inaccessible to the executor; scoped work artifacts +are delivered under current access rules. Permission revocation and cancellation +are enforced outside model memory. Sensitive source material stays within its +authorized audience and retention boundary, including model-provider selection. + +Existing single-session behavior and optional-capability-off behavior need +parity. Unsupported profiles fail explicitly. Old persisted captures and receipts +retain their original version/signature and replay identity; never rewrite them +to resemble the new schema. Mixed-version live writers are fenced, not merged +by best-effort prose conversion. Schema removal requires the exact field inventory, +lossless mapping and explicit maintainer approval required by the RFC index. + +## 8. Migration and rollback + +### C1 wire-layout recommendation + +The target combines quota packet's decision-necessary information with +TurnEnvelope's efficiency and replaces both. “Complete” means complete necessary +semantics, not every duplicated diagnostic in today's packet permanently inline. +The lossless root-preserving candidate below is an intermediate migration oracle: +it exposes omissions and reference breakage while consumers move. Renaming that +candidate or forwarding all old fields does not satisfy the final design. + +Inventory each field and instruction clause with its owning rule and consumer. +Keep current task, original requirements and revisions, relevant evidence, +authority, required reads, execution/stop conditions and original settlement +obligations available before their dependent decision. Reuse typed ownership to +remove proven duplicate representations and unrelated diagnostic noise. Stable +material can be referenced or differentially delivered only with verified +retention or a resolvable, integrity-bound source and explicit read ordering; +missing context must recover before dependent work. A reference alone does not +prove that the model received its constraints. Unknown fields cannot be silently +classified as optional or dropped by a prose heuristic. + +Within one canonical contract, absorb the useful envelope properties: clear +execution identity and action organization, a single machine-owned binding, +less duplicate instruction text, bounded delivery and reliable detail/recovery. +Full/delta/detail are encodings of that instance, not permanent competing semantic +views. Preserve raw source evidence in its existing owner without emitting a +second executable packet. The final wire layout may change where its mapped +references, consumers and measured benefit justify it; root preservation is not +an immutable product constraint. + +| Source or concern | Candidate mapping and qualification | +| --- | --- | +| Current decision fields during migration | Preserve path/value in the lossless oracle; enumerate all modes and classify necessary semantics, proven duplication and diagnostic-only material before the final mapping. Do not infer optionality from one observed packet. | +| Work context, required reads and settlement | Keep their existing `interaction_contract` paths and owners. Existing root-relative references retain their meaning; any intentional relocation requires explicit reference and reader migration. Never rewrite prose or command strings by pattern. | +| Host-operation binding | Compose from the actual caller execution context. Validate consistency with source authority; reject conflicting bindings rather than choosing whichever representation is convenient. | +| Content and transport integrity | Commit the entire semantic instance independently of the former compact action digest. Preserve exact capture-byte verification and original settlement identity as separate checks; changing a transport encoding does not create a new effect. | +| Historical receipts and readers | Decode the recorded version for outstanding work. A temporary internal adapter may serve an existing effect interpreter, but must not become a second emitted contract or a compact replacement for the model's required input. | + +A synthetic layout probe used real isolated File/SQLite quota captures and the +existing TypeScript context codec. Preserving source paths permitted warm delta +encoding; moving all facts under a new `facts` key while retaining the old +`quota_packet` surface fell back to full with `delta_not_smaller`. Both layouts +reconstructed exactly, and an epoch change required full delivery. Retention was +synthetically asserted; this measures codec behavior, not host observation, +model comprehension or outcome/cost benefit. It rejects **unmapped root relocation +under the existing surface**, not nesting in general. A redesigned nested layout +remains possible if its mapping and consumers justify the migration cost. + +Therefore C1/C2 must explicitly version the context surface and its fresh/reuse +paths with the wire transition. Do not relabel an old surface or inherit its +baseline by Turn identity. The first delivery after transition is full; reuse +requires a verified compatible retained baseline. Qualification includes fields +outside the old action projection, missing baselines, session/epoch changes and +same-capture recovery. This resolves a concrete layout risk; shared writer and +final-consumer replacement remain the next implementation, not another layout +framework or a declaration that C1 is delivered. + +The unfinished implementation candidate [#7430](https://github.com/loopx-project/loopx/pull/7430) +now composes a complete source in the existing TypeScript owner before both +quota and native Turn capture, and passes it to actual Codex stdin. Isolated +File/SQLite CLI tests with a synthetic executable cover source integrity, +failed-attempt recovery and once-only settlement. This advances the two-writer +and final-input replacement; it does not qualify C1 cutover. The candidate +now routes capability reentry through the canonical CLI channel and preserves +original hash-bound review/writeback readers in complete-contract Codex input. +Synthetic File/SQLite execution qualifies those readers for fresh obligation-bound +and prior Todo-bound replans. Native launch now derives its one causal binding +from the recorded settlement identity; an observed semantic replan obligation +cannot replace an existing Todo binding. Source-quota and health refusals still +prevent host launch. Release fixture setup now imports its final source once; +these executable checks do not qualify a real model or installed host. +The structured-host renderer now shares complete-input transport with Codex, +including original hash-bound material readers. Actual isolated File/SQLite +Turn-to-DSH runner paths receive that same captured source; historical request +prompts retain their exact content. Structured DSH still has Todo-scoped +sessions: an obligation-only replan is rejected before dispatch, rather than +inventing a Todo binding. Full-source input deliberately retains inactive +capability configuration and diagnostics; those facts do not activate recall +instructions or reflection result fields. This is a disclosed presentation +change, with activation and historical parity checked separately. +The Markdown quota entrypoints now render the same complete contract rather +than selecting a second subset of facts. Actual File/SQLite CLI captures retain +every field and instruction under both the ordinary and former envelope flag; +JSON types and arbitrary source text survive rendering. External-worker +File/SQLite admission, unresolved-attempt recovery and restart checks pass with +the complete producer output, but an opaque shell wake still does not prove +delivery of that original contract to an executor model. +The real benchmark checkpoint preflight now verifies complete source equality +for File/SQLite, replan/non-replan and context delivery on/off. Its optional +full recovery retains that same source, with one initial admission and no +reader writes. This qualifies transport to the checkpoint's model-input file, +not native session capture or a benchmark/model outcome. A matching outer +source hash alone previously admitted an unsupported version or invalid inner +binding through `replan-view`; the reader now uses the existing complete-contract +validator, while unversioned historical reads retain their decoder. +Successor authoring is now bound to the already-decided Turn before complete +capture, using the same formatting owner as historical staged reads. The complete +contract includes original Turn/Goal binding and the obligation to finish the +creation receipt's original settlement before ending, without executing the +successor. A later modern material read does not append another binding. Actual +File/SQLite App-heartbeat and generic-CLI tests create the successor from this +inline contract, reject premature spend, settle the original identity once and +leave the successor open, without another guard or a staged reader dependency. +This changes complete-input successor guidance; historical unversioned reads +retain their old behavior. Settlement-only, capability-intent, unbound and +mismatched-context inputs retain their authoring unchanged. The checkpoint's +legacy-reader tests alone do not establish this lifecycle result. Remaining +material-reader retirement and other C1 consumers must not restore a second +compact executable fact view merely to satisfy historical assertions. +The complete-contract boundary now rejects unknown, empty or mistyped root +execution actions, using the existing decision/frontier vocabularies both +before capture and on later reads. Valid hashes do not make unknown execution +semantics supported. Optional evidence remains intact, including unfamiliar +versions and action-like field names; historical unversioned action routing is +unchanged. This qualifies the root action boundary, not every required semantic +field. A real File/SQLite native-CLI producer fault is rejected before capture, +dispatch or spend. The preceding candidate reached a later launch refusal; +these probes do not show prior unguarded execution. Selected-work tests now consume the complete interaction context and +use the actual native `turn plan` entrypoint for host input. Real File/SQLite +checks retain full task text, canonical notes, scoped gates, fresh requirement +reads and source-loss recovery without rebinding an App capture to a native +host. The six earlier failures at obsolete root-layout assertions remain +historical failures; their downstream semantic checks now execute. +The six earlier staged-reader failures are retained as historical evidence. +The complete composer now reuses Explore's existing applicability correction +before capture: a proven pure replan without a Todo does not advertise the +Todo-bound result attachment. Evidence, independent graph commands and all +before-work obligations remain; unfamiliar/custom instructions and ambiguous +bindings stay intact. Supported Todo-bound attachment authoring remains fully +inline. This is an applicability correction, not an authority change or a new +compact fact view. Real File/SQLite native host inputs qualify both bindings. +The staged tests now consume the complete CLI input and exercise the historical +material-reader codec against that same immutable capture, including a hostile +PATH, unavailable registry, tampered identity/acceptance and the actual writer. +They compare all successor-binding instructions rather than excluding fields +that the complete input now owns. The attachment refusal fixture supplies a +valid explicit finding status so it reaches the real missing-Todo identity gate. +All 23 staged checks and four native host cases passed; these overlapping scopes +do not establish full consumer retirement or packaged-host qualification. +The native context fixture now binds both CLI spellings to `complete_turn` and +compares reconstructed facts with the original captures. Its four initial +failures came from constructing the restoration oracle with retired surfaces; +a Unix rendezvous check had masked the same mismatch by accepting full fallback. +The corrected checks require the original target and actual delta mode. Ten +cases pass through real Codex exec/app-server/code-mode and worker resume with +isolated SQLite and deterministic loopback inference, including compaction, +process resume, replaced history and an unqualified replay profile. No paid +model or benchmark experiment ran. The current full quota-settlement CLI module +passes 158 checks, including the historical cache-parity case; the earlier +intermittent mismatch is not causally explained or relabeled as a pass. +The File/SQLite context-to-DSH subprocess checks now use the complete capture and +production request builder instead of treating a current CLI response as a legacy +action projection. Normal capability-on/off inputs retain every source fact; +bound replan uses the production capture binder and executes the delivered +original-evidence readers. Altered source facts, schema versions and replan +obligations reject before the runner seam. The explicit historical reference +reader remains covered. Eight focused cases pass with an injected recorder, +not a live DSH model; runtime code is unchanged by this test migration. +The complete-contract boundary now also reuses the existing interaction decoder +for its required version, channel types, notification policy and execution +consistency. Four negative cases previously passed composition despite invalid +semantics; they now reject even when a producer supplies correct integrity +hashes. The original object and unknown optional facts remain intact rather than +being replaced with normalized decoder output. File/SQLite native input checks +reject an unsupported inner version before Codex prompt execution or DSH runner +loading, without spend. The complete-contract/context/DSH/stdio selection passes +352 cases; TypeScript checking and focused lint pass. This qualifies these +interaction semantics, not every required field or packaged-host adoption. +Remaining cache consistency investigation, other old reader expectations, staged instruction parity and +actual optional/external consumers, version admission and packaged host +continuity remain unfinished. Operation-SDK checks without an explicit native +runtime are untested, not qualified. The default writer change remains +unshipped; the PR is Draft for unfinished author work, not merely pending review. No model or cost benefit is +established. Historical effect decoding is temporary; it must not become a +second permanent executable view. + +### C1 caller replacement and cutover unit + +The cutover unit is a supported entrypoint **and its downstream consumers**, +not an output flag. Source inspection at `99921829f2c5` identifies the following +live seams. This supplements the earlier baseline audit; it is a migration +design, not a claim that these paths have changed. + +| Live seam | Concrete replacement and retained owner | +| --- | --- | +| `quota.py::_emit_quota_result` / `_project_quota_cli_payload` | Compose the complete contract before capture; replace the ordinary/envelope execution-format branch. Retain admission, capability hooks, capture IO and host poll receipts with their current owners. A diagnostic status view is not an executable contract. | +| `turn.py` after `build_fresh_turn_decision_owner().resolve()` | Call the same composition owner with the actual scheduler execution context. This entry calls `build_turn_envelope` directly; changing quota CLI emission alone does not migrate Turn. Retain the Turn plan, journal and receipt executor. | +| `heartbeat/task_body.py::render_thin_heartbeat_task_body` | Replace the `captured_envelope` instruction split with one contract-reading instruction. Preserve exact selection/reentry transport, notification independence, required reads and original settlement. The saved bootstrap still resolves current instructions on wake. | +| `turn_driver/codex_cli.py::_prompt` and `host_candidate.py::extract_turn_authority` / `render_prompt` | Replace format-specific model inputs at the actual prompt boundary. Today ordinary Codex receives the envelope, staged replan uses extracted authority, and structured hosts use extracted authority. Shared source bytes or signatures do not prove these final inputs preserve the same obligations. Keep provider result encoding and outer effect ownership. | +| `turn_driver/decision_capture.py` and `cli_commands/quota_capture.py` | Reuse immutable capture, validated readers and full/delta delivery. Fresh delivery and saved-capture recovery must reconstruct the same contract; do not reuse a continuity baseline for a different projection merely because its Turn identity matches. | +| `benchmark/runtime/worker.py`, `benchmark/runtime/sessions.py` and `scripts/external_scheduler_worker.py` | Migrate the product entry they actually invoke. Keep evaluation setup and outer wake ownership; do not add benchmark-only conversion or count a managed-host test as attached-host acceptance. | + +Before replacing any seam, its implementation PR records source path, field or +instruction clause, current readers, target owner, representation, recovery and +retirement condition. Relocation must include reference resolution; an omitted +diagnostic needs evidence that it carries no action, authority, required read or +acceptance obligation. Unknown data cannot silently disappear. Unknown required +execution semantics cannot be made safe merely by forwarding their JSON: the +dependent operation stays unavailable until a compatible consumer understands +them. Do not classify obligations by substring matching. + +Use **one explicit version transition**, not automatic format negotiation per +wake. New admission for a migrated binding requires compatible composition, +delivery and consuming readers. An unsupported consumer receives an actionable +unavailable result before dispatch, without creating a second live writer. +Already admitted work continues its recorded version and original receipts; +retain its historical decoder until that work and the supported recovery window +are reconciled. Rollback likewise separates outstanding work from new admission. +A version transition does not rewrite saved prompts, journals or source hashes +as if they had always used the new contract. + +The first C1 PR must include the two production composition callsites above and +at least one complete producer-to-final-input journey, with an explicit list of +remaining readers. Qualifying that bounded slice does not enable the new writer +for an unqualified host or close C1. The final cutover removes active format +choice only after all supported readers qualify. Temporary decoders have named +callers and removal conditions; they are not user-facing compatibility views. + +For each normal, selection, replan, wait, recovery and capability-off fixture, +check independently authored obligations at **three boundaries**: composed +contract, reconstructed delivery, and final model input plus required material +reads. Include a source change outside the old action signature, a missing +required source, an incompatible consumer and a lost settlement response. +Reconstruction equality alone misses prompt-layer omission; a complete prompt +alone misses stale authority or a duplicate debit. These are integration +requirements, not authorization to run a model or launch an experiment. + +1. Inventory actual producers, readers, writers, saved prompts, captures and + external integrations. Map each old field and prose obligation to its retained + owner/field, authoritative derivation or explicitly approved removal. No + blanket claim of “same facts” suffices. Keep original failure fixtures. +2. Qualify the unified contract in single-session execution through real quota, + thin-heartbeat and Turn entrypoints. Switch one writer per binding; old + readers are explicit version-pinned migration adapters with an identified + caller and removal condition. They do not become permanent product views. +3. Add role-aware sessions, shared lifecycle reuse and the opt-in two-session + profile. Reuse existing same-session/native-resume and effect recovery code. +4. Adopt the shared product profile in benchmark workers and the packaged App + heartbeat journey. Each host proves its own observation, stop and recovery + boundaries. Neither a CLI test nor a model simulation qualifies installed App. +5. Remove old producers, format selectors, duplicate renderers and dual-format + tests after the last supported active reader migrates. Keep only historical + version decoders for supported receipt replay. End-state acceptance requires + one emitted contract and no choice between quota and Turn packet formats. + +Rollback disables new admission for the affected profile, drains or interrupts +its attempts, reconciles receipts and restores the prior qualified profile on +the next admitted work. Do not silently replace native sessions or reinterpret +pending receipts. Before field/decoder removal, demonstrate export, old-version +readback and downgrade behavior; retain the old reader until the supported +retention/upgrade boundary is satisfied. No destructive migration is authorized +by this document alone. + +## 9. Validation and acceptance + +| Claim | Evidence and required result | Boundary | +| --- | --- | --- | +| One complete contract | Field/clause inventory; same captured normal, replan, wait, recovery and capability-off workloads through all active entrypoints; identical reconstructed semantic instance | One serializer unit test is insufficient; malformed/unsupported versions fail explicitly | +| Lossless context delivery | Full/delta/recovery equivalence, missing/late/truncated pages, role/session mismatch and real native compaction/resume | Include all read/recovery costs; no second admission or spend | +| Role isolation and recovery | Controller/executor crash windows, duplicate dispatch, late result, revision change, lease expiry and stop under actual host tools | No executor Core access; no stale result adoption or hidden business executor | +| Semantic adoption | Original requirements → controller decision → actual executor work → independent verification → accepted result and original-audience return | Read receipt, valid JSON or successful replan alone cannot pass | +| Shared production paths | Real CLI and supported File/SQLite paths; real isolated PostgreSQL suite when authority persistence changes; packaged App heartbeat and benchmark worker reuse | No live Goal corruption; unsupported/unrun hosts stay unqualified | +| Outcome and cost benefit | Matched current single-session, unified single-session and unified two-session arms with fixed task/model/policy/budget/evaluator | Report uncertainty, failures and counterexamples; no claim from prompt bytes alone | + +The primary C1 comparison is **original quota packet versus the fused contract +in the same single-session product path**. Keep host, task, original facts, +model/policy, evaluator and available budget matched. Compare cold full input, +ordinary warm continuation, replan, missing baseline and interrupted recovery; +include long/repeated history and capability-off cases. The old envelope may be +a diagnostic reference arm, not a second permanent destination. Compare the new +full encoding and its delta encoding separately so transport reuse cannot hide +a semantic regression. Controller/executor separation is a later independent +comparison and cannot explain away a C1 regression. + +### C1 baseline boundary and reuse inventory + +The baseline is the **original caller-visible quota delivery**, not the raw +internal decision. In `cli_commands/quota.py`, the original emitter captures the +source, optionally applies `replan_cli_view` when a capture exists, then applies +`compact_quota_should_run_cli_payload`. Native context delivery adds its own +full/delta transport afterward. Record the exact revision, host flags, capture +availability and detail options for both arms. Comparing a compact candidate +against the larger internal source would overstate savings; comparing a full +candidate against only a deferred entry would omit baseline follow-up costs. + +The existing paths already contain useful efficiency behavior. C1 should absorb +its qualified semantics into the shared TypeScript composition/context owners, +then retire the old caller-specific producer. Do not call the whole legacy +compactor as a shortcut: exact sharing, omission and deferred reads have different +information and failure consequences. + +| Existing information / transformation | Fusion disposition and decisive check | +| --- | --- | +| Selected work, original requirements, acceptance, evidence, permissions and stops | Available before the dependent decision. Keep distinct revisions and contradictory evidence; neither lane labels nor action signatures establish completeness. | +| Identical acceptance copies, nested vision audits, authoring and optional guidance | Prefer one complete in-contract owner plus an exact reference where smaller. Compare JSON types and every clause; different/missing owners remain distinct. No extra read or new decision authority. Existing projection tests provide characterization, not new-consumer qualification. | +| Bounded Todo lanes, shortened suggestions and omitted boundary/history entries | Treat as deliberate omission, not lossless deduplication. Retain completeness/count facts and same-capture recovery; prove the omitted item cannot change the current decision, or load it before deciding. Never inherit the old display limits as semantic limits. | +| Captured replan review, acceptance detail and writeback readers | Separate decision facts from later authoring format while retaining the original identity and all required meaning. Bound reads to the same capture; count every required stage, error and recovery. A missing/stale reference must not trigger a new guard or authorize work. | +| Full/delta/resume delivery | Reuse the existing continuity owner after composition. Establish exact semantic reconstruction and required material availability before action; charge cold fallback and lost-baseline recovery. | +| Scheduler, admission and settlement identities | One authoritative instance before capture; transport must preserve host ownership, original Turn and once-only effects. Repeated representations do not justify weakening their checks. | + +A fixed-source synthetic replan audit of candidate `895f38fc5` illustrates why +the boundary matters. With stride off and no capture staging, the raw source was +21,461 compact UTF-8 JSON bytes, the original quota CLI projection 20,543, and +the complete candidate 21,738: **+5.82% against CLI**, versus +1.29% against raw +source. With capture staging, entry/review/writeback totaled 21,882 bytes versus +21,821 for the candidate. With `evidence_conditioned_v1`, those staged bytes +totaled 28,558 versus 33,368 for the candidate. These use the existing synthetic +replan fixture and production projection/read functions with a synthetic capture +route; they are not executed model trajectories or an installed-host trial. +Extra acceptance/Explore reads, actual request framing, cache behavior and +outcome differences are unmeasured. The legacy receipt toggle produced identical +data and does not add an independent workload. No net-benefit conclusion follows. + +The next implementation slice should first qualify exact same-contract sharing +through composition, readers and recovery, then assess deferred-detail choices +with the matched workload above. Keep cold and staged totals separate and retain +negative results; do not force a byte target by dropping unique instructions. + +Report the field/clause diff and its decision consequence together with actual +model input, cached/uncached tokens, added reads/round trips, reconstruction, +latency, failures/retries, verification and human intervention. A smaller first +packet with more total reads can be negative. Judge positive only with preserved +required semantics and comparable accepted outcomes at lower complete cost, or +better accepted outcomes at comparable budget. Mixed results remain a tradeoff; +transport-only passes and unmeasured outcomes remain inconclusive. Set numeric +criteria before running matched experiments, using the existing measurement +contract rather than inventing an arbitrary compression threshold. C1 cutover +requires this quota-baseline comparison; a serializer or byte reduction alone +cannot close it. + +Use the [existing measurement model](long-horizon-harness-benchmark-research-program-v0.md#6-measurement-model). +Include both sessions' input/output/cached tokens, tool and material reads, +planning/replan/recovery, wall time, verification, human attention and provider +cost; unknown usage is not zero. Persist causal attribution without duplicating +cost when an artifact is forwarded. Compare accepted outcomes under comparable +budgets, not only replan counts or executor speed. Freeze criteria before any +separately authorized experiment; this RFC specifies no automatic winner. + +## 10. Operational contract + +Existing Goal Chat, settings and work readback must expose the selected profile, +actual controller/executor availability, current work, meaningful progress, +unavailable/error state, scope of Stop and returned artifact. Avoid exposing +internal packet selection as a user task. Reuse shared typed projections and +configuration precedence; do not create an independent controller console or +duplicate provider/model settings. + +Observe captures, request/attempt/role/generation, current revisions, effect +receipts and cost coverage in existing diagnostics. Give operators actionable +recovery without raw private transcripts. Notifications remain separate from +work continuation; event/time waits and backoff use the current scheduler owner. +No model busy-polling loop or new recurring automation follows from this RFC. + +## 11. Normative delivery plan and refactor tasks + +These tasks extend roadmap S2/S4/S6/S7/S11 and the effect interpreter's existing +convergence work, not a new roadmap. Reconcile related active tasks/PRs before +claiming; reuse qualified fixes rather than reimplementing them. Task IDs below +are stable design references, not claims that a canonical Todo is complete. + +| Task / dependency | Owner and concrete replacement | Decisive exit / rollback | +| --- | --- | --- | +| **C1 — Unified contract; first** | Interaction/work-context + quota/Turn owners: inventory fields and instruction clauses, capture one schema, migrate actual ordinary quota/Turn producers and thin renderer | Single-session real-entry parity with necessary information, action binding and once-only settlement, plus the quota-baseline effectiveness/full-cost comparison in §9; retain version-pinned readers until cutover qualifies | +| **C2 — One context-delivery pipeline; C1** | Context owner + host observers: absorb full/delta/detail/recovery into the canonical contract; remove packet-format branches and duplicate context copies | Same-capture recovery and exact role/session continuity through normal/replan/resume; full fallback without a new admission; rollback encoding to full | +| **C3 — Session binding and native lifecycle; C1** | Session/runtime owner: extend existing binding for role/generation; reuse native create/resume/observe/interrupt and ordered queues | Two roles cannot overwrite the Agent native ID, cross-read baselines or race execution; recovery observes existing attempts before retry; disable new role admission to roll back | +| **C4 — Shared governed lifecycle; C1** | Effect/Turn owner + outer worker adapters: converge duplicated prepare/dispatch/observe/validate/writeback/settle orchestration around existing typed operations and receipts | App/Turn/external worker agree on admission, original result and single debit under partial failure; scheduler effects retain their true host owner; switch callers back only after receipt reconciliation | +| **C5 — Replan and result authoring boundary; C1** | Goal/Vision and interaction owners: expose current facts and typed controller operations; remove ordinary executor obligations to manufacture Core writeback fields in the two-session profile | Fact-first decision preserves default/stride policy differences, all evidence and required validation; invalid proposed writes reject; single-session authoring remains qualified during rollout | +| **C6 — Controller/executor exchange; C2–C5** | Manager/request + host owners: reuse versioned semantic requests and result return; replace schema-constrained executor work with natural-language work/material exchange | Complete source delivery, local executor autonomy, enforced Core isolation, corrective exchange and independently accepted outcome; return to qualified single-session profile for new work on rollback | +| **C7 — Benchmark reuse and full-cost attribution; C4/C6** | Benchmark toolkit/execution owner: thin adapters select the same product profiles; consolidate duplicated launch/session settings and track both sessions without changing frozen trials | Native/plain controls unchanged; matched-arm configuration/replay and complete cost coverage; no jobs launched merely by merging helpers | +| **C8 — Product configuration and operational readback; C3/C6** | Existing App/settings/Chat projections: one effective configuration owner, role-aware activity, failure/recovery, Stop and artifact return | Packaged managed and supported attached heartbeat journeys, including unavailable host and late results; installed qualification separate; no new packet-format toggle | +| **C9 — Retire old paths and qualify adoption; C1–C8** | Contract/runtime maintainers: remove superseded producers, format switches, duplicated prompts and tests; update protocols, guides and RFC delivery facts | Caller/field/decoder retirement inventory, historical replay and rollback evidence; App + benchmark acceptance and matched benefit before any default promotion | + +C1's inventory is part of its usable replacement, not a standalone architecture +framework. C3/C4/C5 can proceed independently once C1's contract is stable; +C7 can prepare measurements before C6 but cannot claim two-session outcomes. +Implementation PRs must name the replaced caller, remaining gap, actual tests +and rollback. No full language migration or unrelated manager rewrite is a +prerequisite. No task is complete merely because a new abstraction compiles. + +For C1, the first implementation slice pairs the complete field/clause migration +with a real single-session producer and consumer replacement. Start at the +shared quota emission boundary and trace both attached heartbeat delivery and +the Turn adapter; retain their actual host ownership. Do not build an unused +third serializer while both active writers keep their own semantics. Existing +`test_quota_decision_capture.py` and `test_turn_host_decision_capture.py` provide +capture/recovery coverage to extend, not proof of the proposed schema. Qualify +normal work, selection, replan, wait, unsettled-Turn recovery, unavailable detail +and capability-off behavior through the real entries on isolated fixtures. +Each case must check complete obligations and original settlement identity as +well as reconstructed data. The oracle must include source-different but +projection-equal cases; comparing two outputs of the same projection is circular +evidence for completeness. Native-resume/context work remains with its existing +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. + +## 12. Open decisions + +1. **Exact wire name and field mapping — contract owner, before C1 cutover.** + Prefer evolving one existing registered vocabulary/version over a parallel + protocol family. Section 8 recommends preserving source-root paths; finalize + the version and host-binding mapping after the complete producer/reader/field inventory; + maintainer approval is required for removal, not for preserving old meaning. +2. **First qualified two-session host — runtime owner, before C6 dispatch.** + Choose from actual session control and isolation capabilities. Managed Codex + may be an implementation vehicle; App heartbeat is a required product + qualification. Neither entry is presumed to prove the other or benchmark use. +3. **Resource allocation and default — product/evaluation owners, after C7–C8.** + 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. diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md new file mode 100644 index 0000000000..1a201c51f5 --- /dev/null +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md @@ -0,0 +1,584 @@ +# RFC：Controller / Executor 会话与统一受治理工作契约（v0） + +- **RFC 状态：** Accepted（设计接受在合并后生效） +- **替代 / 关闭：** 无 +- **交付成熟度：** Proposal；本文不交付新运行时、schema 或默认行为。 +- **作者 / 负责人：** LoopX 维护者、控制面与运行时 owner +- **创建日期：** 2026-10-27 +- **最近规范性修订：** 2026-10-27 +- **实现基线：** `fe2b8dcbcb998647edb4bafb51932988bd7fdaa6` +- **相关契约：** [Effect interpreter](agent-loop-effect-interpreter-v0.zh-CN.md)、[会话执行模式](agent-session-execution-modes-v0.zh-CN.md)、[语义交接](capable-manager-semantic-handoff-v0.zh-CN.md)、[整体路线图](loopx-overall-roadmap-v0.zh-CN.md) +- **语言镜像：** [English](controller-executor-unified-contract-v0.md) + +## 文档地图与维护契约 + +英文与中文文档互为语义镜像；两者出现差异即为缺陷。 + +第 4 节记录指定基线的源码事实；第 1–3、5–11 节定义提议的决策与验收；第 12 节记录 +待决事项。合并前本文是待评审提案。合并接受设计，不证明实现、安装、实验或默认提升。 +首次实现产出证据后，历史记录进入独立的日期 ledger。 + +## 1. 决策摘要 + +1. 将 quota 执行 packet 与 TurnEnvelope 融合成**一份版本化的受治理工作契约**： + 同一 schema、语义生产入口、capture、交付/恢复机制和结算身份。不同宿主携带同一契约， + 长期保留 quota/Turn 兼容视图不是目标。吸收 quota packet 的必要信息量优势与 + TurnEnvelope 的交付效率优势，一起替换二者，并相对原 quota packet 路径验收净变化。 + 各 domain owner 仍决定自己拥有的事实。 +2. 在可选的双会话 profile 中，**controller 模型会话是唯一面向 Core 的模型客户端**。 + 它读契约、判断工作、与 executor 沟通并提交显式 typed Core 操作。Core 拥有合法迁移与 + 回执；controller 不是第二个权威。 +3. Executor 接收自然语言任务对话、原始材料和普通宿主工具，返回发现、产物、证据与问题。 + 它不消费第二份 Core packet 视图，不编写 quota、Vision、lease 或 settlement 字段。 + 任务正文之外的小型机器载体负责记录路由与因果关系。 +4. 完整首包、精确差分上下文与自动全量恢复属于统一契约的能力。Controller 与 executor + 分别证明各自上下文连续性，不能借用对方的基线。 +5. 先在现有单会话路径验收契约统一；双会话保持 opt-in，直至可比成果与完整成本证据支持 + 采用。本文不启动 benchmark 或特权操作。 + +## 2. 问题与动机 + +同一任务可从 App heartbeat、external worker 或 `loopx turn` 进入，但上下文和结果 +义务的呈现不同。共享决策事实已经存在，调用方仍分别选择 packet 格式、组织提示，并适配 +模型编写的记账信息。再增加一份 controller 专用 packet 会继续增加分支。 + +例如，修复导出失败的 executor 需要原始要求、失败事实、允许使用的工作区和独立验收， +不需要学习如何编码 Vision delta 或扣除 LoopX Turn。分离这些工作可能减少干扰与重复 +协议输入，但额外 controller 也可能丢约束、增加延迟或过度指挥。这些是待验证假设， +不能从会话拆分直接推出收益。 + +### 不变量 + +- 保留完整已接受要求、revision、权限、未完成必读和证据来源；短提示不能成为遗漏理由。 +- 选定工作只有一个当前控制 owner 和一个已准入 executor attempt。对话、路由 ACK 和 + 模型宣告完成都不是回执。 +- 通知不决定执行。安静通知不能取消已准入工作；消息不能覆盖真实停止或预算 gate。 +- 受治理 Turn 是有界工作/结算单位，不是 wake、模型回复或 controller/executor 往返。 + 不能按每条消息另扣 Turn。 +- 重试、来源修正与收尾保留原身份；不能把旧结果结算到新选中的 Todo。 + +## 3. 范围与非目标 + +范围包括：契约融合、上下文交付、按角色绑定会话、controller/executor 沟通、共享生命周期 +复用、宿主 adapter、benchmark 采用、旧路径退役与可观察的产品验收。 + +非目标：新 Goal store、workflow DSL、通用 effect executor、权限引擎、scheduler、 +强制双 Agent 团队、自动切换宿主或修改 benchmark 评分。Peer 团队沿用现有委派/验收 +契约，不把业务判断移入确定性的 Core 规则。 + +## 4. 当前系统契约 + +| 现有概念 | 实际职责 / 源码 | 对目标设计的含义 | +| --- | --- | --- | +| Quota packet / TurnEnvelope | [`quota.py`](../../../loopx/cli_commands/quota.py) 对已决 payload 分普通/envelope 分支投影；[`turn_envelope.ts`](../../../loopx/control_plane/quota/turn_envelope.ts) 提供有界分节与动作绑定 | 将两者义务迁入同一 schema，再退役两条旧输出路径 | +| Work context | [`interaction_contract.ts`](../../../loopx/control_plane/work_items/interaction_contract.ts) 承载 typed 执行/上下文要求 | 扩展现有 owner，不新建 controller 决策引擎 | +| Thin heartbeat | [`task_body.py`](../../../loopx/control_plane/heartbeat/task_body.py) 按格式分支渲染产品入口指令 | 保留 bootstrap/宿主入口，统一其消费的契约 | +| `loopx turn` | [`turn.py`](../../../loopx/cli_commands/turn.py)、[`executor.py`](../../../loopx/control_plane/turn_driver/executor.py)、[`settlement.py`](../../../loopx/control_plane/turn_driver/settlement.py) 实现受治理调用与回执绑定收尾 | 复用生命周期；CLI 入口不是另一套产品 runtime | +| Managed Codex | [`codex_agent_session.py`](../../../loopx/control_plane/turn_driver/codex_agent_session.py) 与 [`codex_sessions.py`](../../../loopx/control_plane/turn_driver/codex_sessions.py) 实现原生会话执行/续接 | 属于 runtime adapter，不是竞争控制面；当前 Agent 级存储还没有提议中的角色区分 | +| Executor result | [`codex_cli.py`](../../../loopx/control_plane/turn_driver/codex_cli.py) 要求 schema 约束结果，包括 delivery、Vision/progress 字段 | 双会话 profile 把 Core 编写责任交给 controller，保留验证 | +| External worker | [`external_scheduler_worker.py`](../../../scripts/external_scheduler_worker.py) 拥有外层唤醒/命令传输 | 保留该归属；对已经证实重复的语义编排进行合并 | +| Benchmark runner | [`worker.py`](../../../benchmark/runtime/worker.py) 的 heartbeat 使用产品 thin body，Turn mode 使用公开 Turn CLI；[`sessions.py`](../../../benchmark/runtime/sessions.py) 复用原生会话 adapter | 它是产品 profile 外的评估 harness，不是独立实现目标 | +| Turn Loop Controller | [稳定协议](../../reference/protocols/turn-loop-controller-v0.md) 定义纯 disposition 函数 | 保持确定性；它不是本提案的 controller 模型会话 | + +执行模式（`managed_runtime` / `attached_host`）、runtime provider、唤醒来源、单/双会话 +组织与评估组是独立维度；并非所有组合都受支持。Native/plain benchmark 对照可以有意 +不包含 LoopX Core，必须保留其独立性。 + +### C1 源码核对：已有共享 owner 与剩余分叉 + +源码实际共享的部分比输出名称体现的更多。`_emit_quota_result` 在 +`_project_quota_cli_payload` 选择普通 CLI 压缩或 `buildTurnEnvelope` **之前**， +已经捕获完整决策。后者委托 TypeScript owner，Python 模块是传输 adapter。 +Quota capture 与 Turn journal capture 都调用 +[`decision_capture.py`](../../../loopx/control_plane/turn_driver/decision_capture.py) +中的 `write_decision_capture`。原生上下文交付与显式宿主 handoff 也复用该模块和既有 +context-delivery owner。C1 应收敛剩余的组合逻辑与消费者假设，不另建 capture service， +也不重写已经共享的差分与 native-resume 逻辑。 + +| 当前来源 / 义务 | 当前 envelope 处理 | C1 必须保留的归属与语义 | +| --- | --- | --- | +| `interaction_contract.agent_channel.work_context` 与未完成必读 | `work_context` 加 `required_reads`；相同内联材料可改用引用 | 一份完整要求/证据来源与可解析引用；保留未完成必读及其完成条件 | +| 选定 Todo、recommended action、action portfolio 与 planning horizon | `action`；`turnActionProjection` 进行引用迁移与文本压缩 | 一份选定工作/动作身份；保留完整可执行条款，区分摘要与执行指令 | +| `interaction_contract.cli_channel.settlement_plan` | 复制至 `writeback.settlement_plan`，包含原 effect 身份与条件步骤 | 原样复用 settlement owner；controller 对话和新 capture 都不另建扣款身份 | +| User/agent interaction channel、execution policy 与 task orchestration | 分为 `user`、`execution_policy`、`boundary` 与 orchestration 分节 | 保留通知与执行义务的区别、权限和停止 gate；不从正文猜测 | +| Replan packet、必读与分阶段写回 | 专门的 replan 投影与延后写回 | 保留事实/来源访问、policy 特定触发与有序变更；不统一打开 stride 行为 | +| Scheduler context 与执行归属 | 携带调用方执行上下文的 scheduler 投影 | 保留真实宿主 owner 与 ACK 义务；统一 schema 不转移 scheduler 权限 | +| 完整已保存决策、action signature 与 journal 绑定 | 来源 hash、投影动作 hash、captured-decision 引用分别存在 | 区分语义完整性、精确传输字节与回执身份，不互换 hash | + +这份表是 owner 与义务映射，**不是完整字段清单，也不是等价验证结果**。当前投影有文本 +预算、字段白名单和引用迁移；仅比较 action signature，不能证明完整来源条款与未知字段 +都被保留。C1 实现必须按确切 base/head 枚举字段和调用方；未分类项阻止切换，不能以 +假定的兼容视图为由悄悄丢弃。 + +对上述基线的合成探针展示了这一限制：两段前缀相同、尾部不同的长 `recommended_action` +产生相同的 action-signature document，且均返回 `matches=true`，但各自的 +`source_decision_hash` 不同。未注册的顶层来源字段也有相同区别。反之，完整的已注册 +settlement plan 在投影中保留，改变其 Turn 身份会改变 action signature。这些观察 +排除了直接把现有有界 envelope 原样提升成完整契约的路线，**不证明当前发生权限丢失**： +recommendation 属于诊断，未知字段是合成输入，完整来源承诺仍能区分两份输入。 +没有测量模型收益。 + +## 5. 提议架构 + +### 归属与统一契约 + +```text +Core owners <-> unified governed work contract <-> controller session + | + task / findings / artifacts + | + executor session + | + scoped host tools + +Host adapter 执行 dispatch、session fence、中断与传输。 +Core owner 校验操作，提交既有 effect/settlement 回执。 +``` + +复用 TypeScript interaction/work-context 与 effect owner。组合 owner 一次捕获它们的 +当前事实，不重写 quota、replan、Todo 或 lease 决策。Python 可以收集来源、适配原生 +传输。宿主特定执行归属在同一契约中显式表达，包括委托给宿主的 scheduler effect 和 +相应 ACK 义务。 + +Schema 名称与逐字段迁移需完成下文 C1 盘点。以下是必须覆盖的语义组，**不是再加几层 +嵌套协议**： + +| 语义组 | 保留能力 | +| --- | --- | +| 身份与当前决策 | 契约版本、capture/revision、Goal/Agent/work/Turn 绑定、选定动作、准入、claim/lease、范围、批准、取消与停止条件 | +| 完整工作上下文 | 原始意图与要求、未满足义务、已接受证据、当前来源/revision、必读完成状态与授权详情访问 | +| 上下文交付 | Full/delta 编码、精确 base/target digest、消费 session/role/epoch 与不可变 capture 恢复 | +| 操作与收尾 | 可用 typed 操作、动作绑定/完整性、条件顺序、验证及 writeback/debit 身份、scheduler 与通知归属 | + +CLI、heartbeat、managed Turn 与评估使用一个语义实例、一个 schema。Full/delta 是该 +实例的编码选择，分页是传输限制，都不形成 quota schema 和 Turn schema。原生工具 +可以带 provider 必需的外层包装，但不能改名、遗漏或另行决定契约字段。人类 UI read +model 继续作为展示 sink，不成为另一份可执行契约。 + +组合边界位于**当前 domain 决策与宿主操作绑定之后、不可变 capture 与上下文编码之前**。 +所有活跃 writer 使用该边界，不能先把 quota packet 压成 envelope，再把结果改称完整 +统一契约。必需来源材料可以使用经授权的详情引用，但引用、revision 和必读义务必须完整， +并能从同一次语义 capture 恢复。 + +“一份 capture”指一次调用的一份不可变语义观察，不是所有用途只存一个文件。完整规范 +实例、编码后的 full/delta/page 产物和 Turn journal 的绑定应保持可区分。精确文件字节 +digest 保护传输，canonical hash 保护语义内容，既有 effect 身份保护只结算一次；三者 +不能互相替代，也不授予当前权限。恢复引用需要身份/位置时，在序列化前预留；不要要求 +文档包含自身最终字节的 digest。编码、分页、native resume 与恢复都从已保存实例派生， +不再执行 guard。合法的新选择或权限复核可以产生新 capture，但不能改写旧观察，或把 +未结算结果悄悄绑定到新观察。 + +### 评审新鲜度与恢复 + +完整 capture 证明当时观察到了什么，不会冻结写回时的有效性。语义内容身份、评审 +相关性和结算身份应分别保留。由其他 Agent 持有的 supporting outcome 仍可能约束 +共享 Goal；不能仅凭 owner 标签，从评审依据中排除其验收或要求状态变化。缩小失效 +范围需要明确的依赖范围规则及共享约束测试，不能依靠角色名过滤或从文案推断白名单。 + +同一已准入 obligation 拒绝过期评审时，当前 typed owner 应返回完整的当前评审依据和 +适用控制指令。消费者先阅读并重新判断，再以原身份重试原写回。不要返回丢失绑定的 +通用写命令，也不要为了获取 writer 已使用的事实而要求再次 guard。依据再次变化仍 +应拒绝；返回上下文不等于接受决策或授权扣额。这一恢复归现有组合/写回边界，应在 +C1 writer 切换中保留；不代表已缩小跨 Agent 失效范围或交付完整统一契约。 + +### Executor 输入与输出 + +采用**自然语言工作交流，加运行时持有的元数据**，不提供 executor 专用 Core 视图，也 +不退化为无记录聊天。Controller 用适合任务的正文说明目标、相关事实、边界和验收，可 +steer、回答问题或修订请求。Host 通过既有 request/dispatch 记录携带 opaque request/ +revision、attempt、session/generation、因果序列与产物引用；模型不必在正文复述这些 +标识。不增加独立消息账本。 + +原始要求和授权证据以附件或宿主材料 reader 提供。Core capture 与访问校验由 controller/ +runtime 完成，executor 不通过调用 Core 取材料。必读要求由实际材料交付/读取机制保留， +controller 转述或路由 ACK 不能替代。必需材料不能交付时，阻止依赖它的工作；独立工作 +可以继续。不可信来源正文不能获得指令或工具权限。 + +Executor 在委派范围内自主选择工具和步骤，不必每次调用工具都询问 controller。工具 +权限由宿主/provider 强制，包括文件与进程访问范围；仅从提示中移除 Core 工具名不构成 +隔离。能访问 Core 凭据的无限制 shell 会违反这个 profile。不支持所需隔离的宿主应明确 +显示不支持，不能静默声称双会话已经合格。 + +输出保留用户要求的交付物、产物引用、实测验证、失败与不确定性。Controller 理解结果、 +执行或请求独立验证，再提交显式 typed Core 命令。Core 不从 executor 散文中的子串推断 +完成、权限或 replan。宿主进程退出不等于业务完成。验证失败可在同一已准入范围内反馈 +并继续工作；实质性的范围/revision 变化需要重新核验 dispatch。 + +**长度要求与语言无关，并随任务变化。** 先保留可独立执行的完整含义，再优化大小。实验 +起点可采用：普通任务正文 200–800 model tokens，复杂交接 800–2000，结果摘要 +150–600。这些是未经验证的起点，不是 schema 上限、默认值、通过条件或截断规则。 +使用实际模型 tokenizer 计量，并记录语言/内容构成。代码、数学、表格、来源材料和完整 +交付物保留自然格式；摘要、附件、补读和所有往返合计成本，引用不会消除材料成本。 +同会话的小修正在连续性有据可查时只传变化，没有最低长度要求。 + +例如，controller 可以说：“修复附件复现中的导出失败；保留原始排序要求，在分配的 +工作区操作。验证回归，说明剩余缺口。”结果可以解释修改并引用 patch 与独立测试。 +这两段自然语言均不替代原始要求、权限授予或 canonical 完成回执。 + +### 会话、生命周期与恢复 + +首版使用一个逻辑工作 Agent 和两个显式绑定的原生 session role。不能只为认知分工再建 +一个 Goal/Todo/quota 身份。扩展既有 session binding owner，加入 role/generation、 +独立有序队列及上下文基线；不能把两个 native ID 写进当前单一 Agent 级槽位。 +一个 controller 拥有控制对话，选定工作最多由一个 executor attempt 执行。Controller +role 不是第二个并发业务 executor。Peer 或并行执行仍需既有独立 claim/lease/handoff +契约。 + +1. 既有入口取得新鲜准入或恢复应结回执，把捕获的统一契约交给 controller。 +2. Controller 围绕 Goal、未满足要求、已有结果和可行工作判断，Core 验证其选定操作。 + Replan policy 继续决定何时必须 review；先看事实不意味着把 stride 独有触发条件变成 + 默认 policy，也不强迫无意义换路。 +3. Dispatch 前，host 绑定 work/request revision、attempt、session role、generation、 + 范围与预算；调用 executor 前记录 intent。 +4. Executor 工作并返回观察/产物。Readback 区分投递、执行、结果可用、独立验证与已接受 + 写回。多次交流不产生多次 quota 扣除。 +5. Controller 提议接受或修改；既有 effect owner 校验并对原 Turn 结算一次。后续新鲜 + 决策继续可执行工作、按记录的事件/时间等待或停止。 + +| 故障 | 必需处理 | +| --- | --- | +| Controller 在 dispatch 后崩溃 | 先恢复已持久化 attempt 与 executor 状态/结果，再决定是否重发；不能启动重复 executor | +| 结果/结算响应丢失 | 以原幂等身份读既有回执，仅重试未解决的 effect | +| Executor 重启或上下文被压缩 | 围栏旧 generation，重新核验连续性；未知时完整交付当前材料 | +| 取消、需求变化、lease 到期或结果迟到 | 每次拥有的 dispatch/write 前重验当前权限/revision；保留证据，拒绝过时接受并核对已准入 effect | +| 工具执行中 Stop | Host 在受支持范围内中断；分别报告 ACK 与真实退出。保留未知/执行中 effect；停止回执不能证明物理回滚 | +| Controller 不可用 | 既有 host/Core 停止与预算机制仍有效；暂停依赖工作并恢复，不能让 executor 临时成为 Core owner | + +### 差分上下文 + +复用现有 context-delivery owner 与不可变 capture 机制。先完整交付，只有在精确消费 +session、role、epoch、schema、source capture 下证明已完整送达并保留上下文，才能 +发送注册子树的精确 delta。保留删除、数组顺序、null、空值和完整字符串。未知字段在 +注册复用语义前每次完整发送；delta 加元数据更大时发送 full。 + +当前权限、准入、取消、未完成必读、结算与 scheduler 事实即使未变也新鲜内联交付，温态 +传输不能减弱正文义务。缺失/乱序 delta、截断、压缩、损坏或未知基线自动从同次 capture +全量恢复，不重新准入/扣额。执行仍检查来源有效性与当前权限；恢复旧 capture 不能复活 +已取消工作。Executor 任务对话独立消费语义材料，不是 controller Core packet 换名后的 +delta。 + +## 6. 备选方案与取舍 + +| 备选方案 | 结论 | +| --- | --- | +| Quota 与 TurnEnvelope 长期保留兼容视图 | 拒绝作为终态：仍有重复选择/渲染与字段漂移；仅保留有界迁移 decoder | +| 给 executor 一份紧凑 Core packet 视图 | 不作为双会话默认设计：仍有协议编写负担和两个面向 Core 的模型客户端 | +| 没有运行时绑定的纯自然语言聊天 | 拒绝：无法可靠核对过时/重复结果、取消与重启 | +| 始终使用双会话 | 拒绝：controller 成本、延迟和交接损失可能超过收益；保留合格单会话 profile | +| 一个万能 runtime/effect executor | 拒绝：host、scheduler、事务与 provider 权限不同；共享语义与回执，不共享执行所有权 | + +## 7. 安全、隐私与兼容性 + +Controller 判断不授予额外权限。运行时凭据与 Core 写能力对 executor 不可访问；按 +当前访问规则交付范围内工作材料。撤权和取消在模型记忆之外强制执行。敏感材料保留原有 +受众、保留期限及模型 provider 选择边界。 + +现有单会话与可选能力关闭路径需要行为等价。不支持的 profile 显式失败。旧持久化 +capture/回执保留原版本/签名与 replay 身份，不能改写成新 schema。混合版本 live writer +通过围栏处理，不靠尽力而为的散文转换合并。Schema 删除须满足 RFC 索引规定的逐字段 +盘点、无损映射和显式维护者批准。 + +## 8. 迁移与回退 + +### C1 wire 布局建议 + +目标是吸收 quota packet 的必要信息量优势与 TurnEnvelope 的效率优势，一起替换 +二者。“完整”指必要语义完整，不表示今天 packet 中所有重复诊断都永久内联。下述 +保留根路径的无损候选只是迁移对照，用于在消费者迁移时发现遗漏与引用断裂；给它改名 +或转发全部旧字段，均不能满足最终设计。 + +逐字段、逐条指令盘点所属规则与实际消费者。在依赖它的决策之前，必须具备当前任务、 +原需求及修订、相关证据、权限、必读、执行/停止条件和原结算义务。通过 typed owner +识别并消除已证实的重复表达与无关诊断噪声。稳定材料只有在保留证据已验证，或来源 +可解析且绑定完整性、读取顺序明确时，才可引用或差分交付；缺失上下文须先恢复再执行 +依赖工作。引用本身不证明模型收到了约束。不能凭正文启发式把未知字段当成可选或静默删除。 + +在同一规范契约内吸收 envelope 的有效特性：清晰的执行身份与动作组织、单一机器 +binding、减少重复指令、有界交付与可靠详情/恢复。Full/delta/detail 是同一实例的 +编码，不是永久并存的不同语义视图。原始来源证据保留在既有 owner，不再输出第二份 +可执行 packet。最终布局可在引用映射、消费者迁移与实测收益成立时调整；保留根路径 +不是不可更改的产品约束。 + +| 来源或关注点 | 候选映射与资格要求 | +| --- | --- | +| 迁移中的当前 decision 字段 | 无损对照保留路径和值；最终映射前枚举各模式，区分必要语义、已证实重复与纯诊断材料，不能凭某次 packet 推断可选性。 | +| Work context、必读与结算 | 保留既有 `interaction_contract` 路径与 owner。现有根相对引用保持含义；有意搬迁须显式迁移引用与 reader，不能按模式改写正文或命令字符串。 | +| Host-operation binding | 从真实调用方 execution context 组合，验证与源权限一致；binding 冲突时拒绝，不能选择方便的表示。 | +| 内容与传输完整性 | 对整个语义实例作完整性承诺，独立于原紧凑 action digest。精确 capture 字节校验和原结算身份仍分别检查；更换传输编码不创建新 effect。 | +| 历史回执与 reader | 未结工作按记录版本解码。临时内部 adapter 可以服务既有效果解释器，但不能成为第二份输出契约，也不能用紧凑副本替代模型必需输入。 | + +一个合成布局探针使用真实隔离 File/SQLite quota capture 和既有 TypeScript context +codec。保留源路径时可使用 warm delta；将全部事实搬至新 `facts` key、同时沿用旧 +`quota_packet` surface 时，以 `delta_not_smaller` 回退 full。两种布局均精确重建， +epoch 变化均要求 full。Retention 为合成声明；这衡量 codec 行为，不证明宿主观察、 +模型理解或成果/成本收益。它排除的是**沿用旧 surface 却未映射的根路径搬迁**，不是 +一般性的嵌套布局。若映射与消费者收益足以抵偿迁移成本，仍可设计嵌套布局。 + +因此 C1/C2 须随 wire 迁移显式版本化 context surface 及其 fresh/reuse 路径，不能 +改名冒用旧 surface 或凭 Turn 身份继承基线。迁移后的首次交付使用 full；只有验证了 +兼容的 retained baseline 才可复用。资格覆盖旧 action 投影之外的字段、基线缺失、 +session/epoch 变化和同 capture 恢复。这里消除了具体布局风险；下一步仍是共享 writer +与最终消费者替换，不能再建设一个布局框架，也不能据此宣布 C1 交付。 + +尚未完成的实现候选 [#7430](https://github.com/loopx-project/loopx/pull/7430) 已在既有 +TypeScript owner 中、quota 与原生 Turn 捕获之前组合完整来源，并传入实际 Codex +stdin。隔离 File/SQLite 的真实 CLI 加合成可执行程序覆盖来源完整性、失败 attempt +恢复与一次结算。这推进了两个 writer 和最终输入替换，尚未取得 C1 切换资格。 +候选现已通过规范 CLI channel 路由能力重入，并在完整契约的 Codex 输入中保留原始 +hash 绑定的 review/writeback reader。合成 File/SQLite 执行验证了新 obligation 绑定 +和原 Todo 绑定 replan 的材料读取。原生启动现只从已记录的结算身份取得唯一因果 +绑定，观察到的语义 replan obligation 不得替换原 Todo 绑定。源 quota 与健康拒绝 +仍阻止宿主启动。Release fixture 现只导入一次最终来源；这些可执行检查不代表真实 +模型或已安装宿主验收。结构化宿主 renderer 现与 Codex 共享完整输入传输及原 hash +绑定的材料读取器。实际隔离 File/SQLite Turn→DSH runner 接收同一捕获来源；历史 +请求 prompt 正文保持精确一致。结构化 DSH 仍使用 Todo 范围的 session：只有 +obligation 的 replan 在派发前被拒绝，不伪造 Todo 绑定。完整来源有意保留未激活能力的 +配置和诊断事实；这些事实不会激活 recall 指令或 reflection 结果字段。这是已披露的 +展示变化，激活边界与历史等价分开验证。 +Markdown quota 入口现渲染同一份完整契约，不再另外挑选事实子集。真实 File/SQLite +CLI 捕获验证普通入口与原 envelope flag 均保留全部字段和指令，JSON 类型与任意 +来源正文经过渲染后不丢失。外部 worker 的 File/SQLite 准入、未决 attempt 恢复和 +重启检查已通过完整 producer 输出；但不透明 shell wake 仍不能证明该原始契约已 +交付 executor 模型。 +真实 benchmark checkpoint preflight 已验证 File/SQLite、replan/非 replan 及 +context delivery 开关组合下的完整来源相等；可选 full recovery 保留同一来源，初始 +准入只有一次，reader 不写状态。这只证明契约传到 checkpoint 的模型输入文件， +不代表原生 session 捕获或 benchmark/模型成果。此前只要外层 source hash 相符， +`replan-view` 就会接受不支持的版本或无效的内部绑定；现在复用既有完整契约 validator， +未版本化的历史读取保留原解码器。 +successor 写入指引现已在完整 capture 前绑定到已决定的 Turn，复用历史 staged +读取的同一格式化 owner。完整契约包含原 Turn/Goal 绑定，以及结束前完成创建回执 +所返原结算、不得执行 successor 的义务；后续现代材料读取不再追加第二次绑定。 +真实 File/SQLite 的 App heartbeat 和 generic CLI 测试从该内联契约创建 successor， +拒绝过早 spend，原身份只结算一次并保持 successor open，不依赖再次 guard 或 +staged reader。这改变了完整输入的 successor 指引；未版本化历史读取保持原行为。 +仅结算、capability intent、未绑定和 context 不匹配的输入保留原写入指引。 +checkpoint 的旧 reader 测试本身不能证明这条生命周期。剩余材料 reader 退役及 +其他 C1 消费者不能为满足历史断言而恢复第二份精简可执行事实视图。 +完整契约边界现复用既有 decision/frontier 词表，在 capture 前与后续读取时拒绝未知、 +空值或类型错误的根执行 action；hash 合法不能证明消费者理解未知执行语义。可选证据 +仍完整保留，包括陌生版本和形似 action 的字段名；未版本化历史 action 路由不变。 +这只验证根 action 边界，不代表所有必需语义字段均已验收。真实 File/SQLite 原生 CLI +的 producer 故障在 capture、派发与 spend 前被拒绝；前一候选会到达更晚的启动拒绝， +这些探针不证明此前存在无保护执行。Selected-work 测试现读取 +完整 interaction context，并通过真实原生 `turn plan` 入口验证宿主输入。真实 +File/SQLite 检查保留完整任务正文、规范 note、作用域 gate、需求新鲜读取及来源丢失 +恢复，不把 App capture 换绑到原生宿主。此前六项旧根布局断言失败仍作为历史失败 +保留；它们后续的语义检查现在已实际执行。 +此前六项 staged-reader 失败作为历史证据保留。完整 composer 现于 capture 前 +复用 Explore 既有可用性修正：已证明没有 Todo 的 pure replan 不再展示必须绑定 +Todo 的结果附件写法。证据、独立图命令与全部工作前义务保留；陌生/自定义指令及 +歧义绑定保持原文。有 Todo 的可用附件写法仍完整内联。这是可用性修正，不改变 +权限，也不新增精简事实视图。真实 File/SQLite 原生宿主输入覆盖两种绑定。 +Staged 测试现消费完整 CLI 输入，并对同一不可变 capture 运行历史材料 reader +codec，覆盖恶意 PATH、不可用 registry、身份/验收篡改及实际 writer。测试比较 +全部 successor 绑定指令，不再排除完整输入已拥有的字段。附件拒绝 fixture 提供 +合法、显式的 finding status，确保实际到达缺少 Todo 的身份门。23 项 staged +检查与四项原生宿主用例通过；这些相互重叠的范围不能证明全部消费者退役或打包 +宿主资格。 +原生 context fixture 现将两种 CLI 写法都绑定到 `complete_turn`，并将重建后的 +全部事实与原始 capture 比较。首次四项失败源于恢复 oracle 仍使用旧 surface； +Unix rendezvous 检查此前只比较内容，允许 full 回退掩盖同一错配。修正后要求 +原 target 和实际 delta 模式。十项用例通过真实 Codex exec/app-server/code-mode +及 worker resume，使用隔离 SQLite 与确定性本地回环响应，覆盖压缩、进程恢复、 +历史文件替换和未合格 replay profile。未调用付费模型或启动 benchmark 实验。 +当前完整 quota-settlement CLI 模块 158 项通过，包含历史 cache parity 用例； +此前间歇性错配的原因尚未证明，不能改写为历史通过。 +File/SQLite context→DSH 子进程检查现使用完整 capture 和生产 request builder， +不再把当前 CLI 响应当作旧 action projection。普通 capability 开/关输入保留全部 +来源事实；已绑定 replan 使用生产 capture binder，并执行实际交付的原证据 reader。 +来源事实、schema 版本或 replan 义务被修改时，在 runner 接缝前拒绝；显式历史引用 +reader 覆盖仍保留。八项聚焦用例通过，使用注入的记录 runner，未调用真实 DSH 模型； +本次测试迁移没有修改 runtime 代码。 +完整契约边界现进一步复用既有 interaction decoder，校验必需版本、channel 类型、 +通知策略和执行一致性。四种非法语义原先能通过组合；现在即使 producer 提供正确 +完整性哈希也会拒绝。保留原对象及未知可选事实，不用 decoder 规范化输出替换原文。 +File/SQLite 原生输入检查确认不支持的内层版本在 Codex prompt 执行或 DSH runner +加载前拒绝，且不扣额。完整契约/context/DSH/stdio 集合 352 项通过，TypeScript +检查及聚焦 lint 通过。这只证明上述交互语义，不代表所有必需字段或打包宿主已验收。 +剩余 cache 一致性调查、其他旧 reader 断言、分阶段指令等价和实际 optional/external +消费者、版本准入及打包宿主连续性仍未完成。缺少显式原生 runtime 的 operation SDK +检查属于未测，不能算资格。默认 writer 变更尚未交付；PR 因作者实现未完而保持 +Draft，不是仅等待评审。尚无模型或成本收益证据。历史 effect 解码只是临时迁移， +不得成为第二份永久可执行视图。 + +### C1 消费链替换与切换单元 + +切换单元是一个受支持入口**及其下游消费者**，不是一个输出开关。对 +`99921829f2c5` 的源码核对确认以下活跃接缝。这补充前述基线审计；它是迁移设计， +不表示这些路径已经改变。 + +| 活跃接缝 | 具体替换与保留的 owner | +| --- | --- | +| `quota.py::_emit_quota_result` / `_project_quota_cli_payload` | 在 capture 前组合完整契约，替换 ordinary/envelope 执行格式分支。准入、capability hook、capture IO 与 host poll 回执保留原 owner。诊断 status 视图不是可执行契约。 | +| `turn.py` 的 `build_fresh_turn_decision_owner().resolve()` 之后 | 携带实际 scheduler execution context 调用同一组合 owner。此入口直接调用 `build_turn_envelope`；仅修改 quota CLI emission 不会迁移 Turn。保留 Turn plan、journal 和回执执行器。 | +| `heartbeat/task_body.py::render_thin_heartbeat_task_body` | 用统一契约读取指令替换 `captured_envelope` 指令分支，保留精确 selection/reentry transport、通知独立性、必读与原结算身份。保存的 bootstrap 仍在唤醒时解析当前指令。 | +| `turn_driver/codex_cli.py::_prompt` 与 `host_candidate.py::extract_turn_authority` / `render_prompt` | 在实际 prompt 边界替换格式特定输入。当前普通 Codex 接收 envelope，分阶段 replan 使用提取的 authority，结构化 host 也使用提取的 authority。共享源字节或签名不能证明这些最终输入保留相同义务。保留 provider 结果编码与外层 effect 归属。 | +| `turn_driver/decision_capture.py` 与 `cli_commands/quota_capture.py` | 复用不可变 capture、校验读取器和 full/delta 交付。首次交付和保存后恢复必须重建同一契约；不能仅因 Turn 身份相同，就把某投影的 continuity baseline 用于另一投影。 | +| `benchmark/runtime/worker.py`、`benchmark/runtime/sessions.py` 与 `scripts/external_scheduler_worker.py` | 迁移它们实际调用的产品入口。保留评估配置与外层唤醒归属，不新增 benchmark 专用转换，也不把 managed-host 测试算作 attached-host 验收。 | + +替换任一接缝前，实现 PR 记录源路径、字段或指令条款、当前 reader、目标 owner、表示、 +恢复与退役条件。字段搬迁须包含引用解析；删除诊断须证明其中不含动作、权限、必读或 +验收义务。未知数据不得静默消失；未知的必需执行语义也不能靠转发 JSON 就变安全， +相关操作须保持不可用，直到兼容消费者能够理解。不能用子串匹配分类义务。 + +使用**一次明确的版本迁移**，不在每次唤醒自动协商格式。已迁移 binding 的新准入要求 +组合、交付和消费 reader 兼容。不支持的消费者在 dispatch 前收到可操作的不可用结果， +不能因此创建第二个活跃 writer。已准入工作继续使用记录的版本和原回执；在这些工作及 +受支持恢复窗口核清前保留历史 decoder。回退同样区分未结工作与新准入。版本迁移不能 +把保存的 prompt、journal 或源 hash 改写成仿佛一直使用新契约。 + +C1 首个 PR 必须覆盖上述两个生产组合调用点，并交付至少一条从生产端到最终输入的 +完整旅程，同时明确剩余 reader。这个有界切片通过资格，不代表可向未验收 host 开启 +新 writer，也不关闭 C1。最终切换须在全部受支持 reader 验收后删除活跃格式选择。 +临时 decoder 有具名 caller 与退出条件，不是面向用户的兼容视图。 + +对 normal、selection、replan、wait、recovery 和 capability-off 的每个 fixture， +在**三个边界**核对独立编写的义务：组合契约、重建交付、最终模型输入及必需材料读取。 +包含旧 action signature 未覆盖的源变化、必需来源缺失、不兼容消费者和结算响应丢失。 +仅重建相等会漏掉 prompt 层丢义务；仅 prompt 完整会漏掉过期权限或重复扣额。 +这些是集成要求，不授权运行模型或启动实验。 + +1. 盘点实际 producer、reader、writer、已保存 prompt、capture 和外部集成。把每个旧 + 字段与正文义务映射到保留的 owner/字段、权威派生或明确批准的删除。“事实相同”的 + 总括声明不够；保留原失败 fixture。 +2. 通过真实 quota、thin-heartbeat、Turn 入口验收统一契约的单会话执行。每个 binding + 只切一个 writer；旧 reader 是绑定版本的显式迁移 adapter，列出真实调用方与删除 + 条件，不能成为长期产品视图。 +3. 加入按角色区分的 session、共享生命周期复用及 opt-in 双会话 profile，复用既有 + same-session/native-resume 和 effect recovery 代码。 +4. Benchmark worker 与打包 App heartbeat 采用同一产品 profile。各 host 分别证明 + 观察、停止和恢复；CLI 测试或模型模拟不能证明已安装 App 合格。 +5. 最后一个受支持活跃 reader 迁移后，删除旧 producer、格式选择开关、重复 renderer + 与双格式测试。只为受支持历史回执 replay 保留版本 decoder。终态验收要求只发出一份 + 契约，不再选择 quota 或 Turn packet 格式。 + +回退先关闭受影响 profile 的新准入，drain/中断 attempt，核对回执，再在下次准入工作 +恢复先前合格 profile。不能静默替换 native session 或重解释 pending 回执。删除字段/ +decoder 前证明 export、旧版本 readback 与降级行为；满足受支持保留/升级边界前保留旧 +reader。本文不单独授权破坏性迁移。 + +## 9. 验证与验收 + +| 主张 | 证据与必需结果 | 边界 | +| --- | --- | --- | +| 一份完整契约 | 字段/条款盘点；同次捕获的正常、replan、wait、recovery、能力关闭负载经过全部活跃入口；重建语义实例相同 | 单 serializer 单测不足；畸形/不支持版本显式失败 | +| 无损上下文交付 | Full/delta/recovery 等价；缺页、迟到、截断、role/session 不符与真实原生压缩/续接 | 合计所有读取/恢复成本，不重新准入/扣额 | +| 角色隔离与恢复 | 实际 host tools 下的 controller/executor 崩溃窗口、重复 dispatch、迟到结果、revision 变化、lease 到期、Stop | Executor 不能访问 Core，不能采用过时结果或隐藏第二个业务 executor | +| 语义采用 | 原始要求 → controller 判断 → executor 实际工作 → 独立验证 → 接受结果并回原受众 | 读回执、合法 JSON 或 replan 成功不能单独通过 | +| 共享生产路径 | 真实 CLI 与受支持 File/SQLite；涉及 authority 持久化变更时跑真实隔离 PostgreSQL；打包 App heartbeat 与 benchmark worker 复用 | 不破坏 live Goal；未支持/未运行 host 仍未合格 | +| 成果与成本收益 | 当前单会话、统一契约单会话、统一契约双会话三组，固定 task/model/policy/budget/evaluator | 报告不确定性、失败与反例，不从 prompt bytes 单独宣称收益 | + +C1 的主要对照是**同一单会话产品路径中的原 quota packet 与融合后新契约**。 +匹配 host、任务、原始事实、模型/policy、evaluator 和可用预算，覆盖冷启动全量、普通 +暖续接、replan、缺失基线与中断恢复，并包含长/重复历史和 capability-off。旧 envelope +可以作为诊断参考组，不成为永久第二目标。新契约 full 与 delta 编码分别比较，避免 +传输复用掩盖语义退步。Controller/executor 分离是之后独立的对照，不能用来解释或 +抵消 C1 回归。 + +### C1 基线边界与复用盘点 + +基线是**原路径中调用者实际收到的 quota 交付**，不是内部原始 decision。 +`cli_commands/quota.py` 的原 emitter 先捕获 source；有 capture 时按条件应用 +`replan_cli_view`，再应用 `compact_quota_should_run_cli_payload`，随后原生上下文 +交付还有 full/delta 传输。两组须记录精确版本、host flags、capture 是否可用及 detail +选项。用更大的内部 source 对比紧凑候选会夸大节省；只用延后读取的首包对比完整候选， +则会漏算基线的后续成本。 + +现有路径已包含值得复用的效率行为。C1 应把已合格的语义吸收到共享 TypeScript +composition/context owner，再退役旧的 caller-specific producer。不能直接套用整个旧 +compactor：精确共享、省略和延后读取的信息与失败后果各不相同。 + +| 现有信息／变换 | 融合处理与决定性检查 | +| --- | --- | +| 已选工作、原始要求、验收、证据、权限及停止条件 | 依赖它们的决策前可用。保留不同 revision 和矛盾证据；lane 标签或 action signature 均不能证明完整性。 | +| 相同验收副本、嵌套 vision audit、authoring 和可选指导 | 在更小时优先使用契约内一份完整 owner 加精确引用。比较 JSON 类型及每条义务；不同或缺失 owner 时分别保留。不增加补读或决策权。已有 projection 测试只提供特征验证，不代表新消费者已合格。 | +| 有限 Todo lanes、缩短的建议、省略的边界／历史项 | 视为主动省略，而非无损去重。保留完整性／计数事实和同 capture 恢复；证明被省略项不影响当前决策，或先加载再决策。旧显示上限不能自动变成语义上限。 | +| 捕获后的 replan review、验收详情和 writeback reader | 区分决策事实与后续 authoring 格式，同时保留原身份和全部必要含义。读取绑定同一 capture；计入每个必需阶段、错误和恢复。引用缺失／过期不能重新 guard 或授权工作。 | +| Full/delta/resume 交付 | 在 composition 后复用既有 continuity owner。行动前验证精确语义重建与必要材料可用；计入冷回退及丢失基线的恢复。 | +| Scheduler、准入与结算身份 | Capture 前只有一份权威实例；传输保留真实 host owner、原 Turn 与一次性 effects。重复表示不构成削弱检查的理由。 | + +候选 `895f38fc5` 的固定 source 合成 replan 审计说明了边界的影响。关闭 stride 且不做 +capture 分阶段时，原始 source 为 21,461 个紧凑 UTF-8 JSON 字节，原 quota CLI +projection 为 20,543，完整候选为 21,738：**相对 CLI 增加 5.82%**，相对原始 source +则是 1.29%。启用 capture 分阶段后，entry/review/writeback 合计 21,882 字节，候选 +为 21,821。启用 `evidence_conditioned_v1` 时，分阶段合计 28,558，候选为 33,368。 +这里使用既有合成 replan fixture、生产 projection/read 函数与合成 capture 路由； +不是实际模型轨迹或安装宿主实验。追加的验收／Explore 读取、实际请求包装、缓存行为 +及成果差异均未测。切换 legacy receipt 得到相同数据，不增加独立 workload。这些数字 +不支持净收益结论。 + +下一实施切片应先在 composition、reader 和 recovery 中验证同契约精确共享，再用上述 +可比负载评估延后详情的取舍。冷启动与分阶段总量分别保留，保留负结果，不能靠删除独有 +指令达到字节目标。 + +同时报告字段/条款 diff 及其决策后果、实际模型输入、cached/uncached tokens、追加 +读取/往返、重建、延迟、失败/重试、验证与人工介入。首包更小但总补读更多，可能是负向。 +只有必要语义保留且同等验收成果的完整成本降低，或可比预算下验收成果改善，才判正向。 +效果混合则报告取舍；只有传输通过或成果未测时结论仍不确定。按既有测量合同在可比实验 +前确定数值标准，不凭空规定压缩比例。C1 切换须完成这个 quota 基线对照，不能仅凭 +serializer 或字节减少结清。 + +使用[既有测量模型](long-horizon-harness-benchmark-research-program-v0.md#6-measurement-model)。 +计入两个会话的输入/输出/cached tokens、工具及材料读取、planning/replan/recovery、 +墙钟时间、验证、人工注意力和 provider 成本；未知用量不是零。持久化因果归因，转发 +产物时不重复计算成本。比较可比预算下的已接受成果，不能只看 replan 次数或 executor +速度。另行授权实验前冻结标准，本文不预设胜出方案。 + +## 10. 运行契约 + +既有 Goal Chat、settings 与工作 readback 应呈现选定 profile、controller/executor +真实可用性、当前工作、有意义进展、不可用/错误、Stop 范围及返回产物。不要把内部 packet +选择变成用户任务。复用共享 typed 投影与配置优先级，不建独立 controller console 或 +重复 provider/model 设置。 + +既有诊断记录 capture、request/attempt/role/generation、当前 revision、effect 回执 +和成本覆盖；提供可操作恢复，不暴露私有原始对话。通知与工作延续分离；事件/时间等待及 +backoff 继续归当前 scheduler owner。本文不引入模型空轮询或新的 recurring automation。 + +## 11. 规范性交付计划与重构任务 + +这些任务扩展整体路线图 S2/S4/S6/S7/S11 和 effect interpreter 既有融合工作，不另立 +路线图。认领前对齐相关活跃任务/PR，复用已合格修复，不重复实现。下列 task ID 是稳定 +设计引用，不代表 canonical Todo 已完成。 + +| 任务 / 依赖 | Owner 与实际替换内容 | 决定性退出 / 回退 | +| --- | --- | --- | +| **C1 — 统一契约；首先** | Interaction/work-context + quota/Turn owner：盘点字段与指令条款，捕获同一 schema，迁移真实普通 quota/Turn producer 与 thin renderer | 单会话真实入口保留必要信息、动作绑定和一次结算，并完成第 9 节相对 quota 基线的效果/完整成本对照；cutover 合格前保留绑定版本的 reader | +| **C2 — 一个上下文交付管线；C1** | Context owner + host observer：将 full/delta/detail/recovery 纳入 canonical 契约，删除 packet 格式分支和重复上下文副本 | 正常/replan/resume 中同 capture 恢复及精确 role/session 连续性；full 回退不重新准入；编码可回退 full | +| **C3 — 会话绑定与原生生命周期；C1** | Session/runtime owner：扩展 role/generation，复用 native create/resume/observe/interrupt 和有序队列 | 两角色不覆盖 Agent native ID、不借用基线、不竞态执行；重试前观察既有 attempt；关闭新角色准入即可开始回退 | +| **C4 — 共享受治理生命周期；C1** | Effect/Turn owner + 外层 worker adapter：围绕既有 typed 操作与回执合并重复 prepare/dispatch/observe/validate/writeback/settle 编排 | App/Turn/external worker 在部分失败下对准入、原结果与一次扣额一致；scheduler effect 保留真实 host owner；核对回执后才切回旧调用方 | +| **C5 — Replan 与结果编写边界；C1** | Goal/Vision 与 interaction owner：提供当前事实和 typed controller 操作，移除双会话 profile 中普通 executor 编造 Core 写回字段的义务 | 先看事实保留 default/stride policy 区别、全部证据与必要验证；非法写回拒绝；rollout 期间单会话编写仍合格 | +| **C6 — Controller/executor 交流；C2–C5** | Manager/request + host owner：复用版本化语义请求与结果返回，用自然语言工作/材料交流替换 executor 的 schema 约束任务 | 完整来源交付、executor 局部自主、强制 Core 隔离、纠偏往返与独立验收结果；回退后新工作使用合格单会话 profile | +| **C7 — Benchmark 复用与完整成本归因；C4/C6** | Benchmark toolkit/execution owner：薄 adapter 选择相同产品 profile；合并重复 launch/session 配置，跟踪两个会话，不改冻结 trial | Native/plain 对照不变，可比组配置/replay 与完整成本覆盖；合并 helper 不启动 job | +| **C8 — 产品配置与运行 readback；C3/C6** | 既有 App/settings/Chat 投影：同一 effective configuration owner，按角色展示 activity、失败/恢复、Stop 和产物返回 | 打包 managed 及受支持 attached heartbeat 流程，包括 host 不可用和结果迟到；安装资格另验；不新增 packet 格式开关 | +| **C9 — 旧路径退役与采用资格；C1–C8** | Contract/runtime 维护者：删除被替代 producer、格式开关、重复提示/测试，更新 protocol、guide 和 RFC 交付事实 | 调用方/字段/decoder 退役清单、历史 replay 与回退证据；App + benchmark 验收及可比收益成立后再决定默认提升 | + +C1 盘点是可用替换的一部分，不单独建设架构框架。C1 契约稳定后，C3/C4/C5 可以独立 +推进；C7 可以提前准备测量，但不能提前宣称双会话成果。实现 PR 列明替换的调用方、剩余 +缺口、实际测试与回退。完整语言迁移或无关 manager 重写不是前置条件；新抽象能编译 +不能算任务完成。 + +C1 首个实现片必须把完整字段/条款迁移与真实单会话 producer、consumer 替换一起交付。 +从共享 quota emission 边界开始，同时追踪 attached heartbeat 交付与 Turn adapter， +保留各自真实宿主归属。不能新增无人使用的第三个 serializer，而两个活跃 writer 继续 +各自拥有语义。既有 `test_quota_decision_capture.py` 与 +`test_turn_host_decision_capture.py` 提供可扩展的 capture/恢复覆盖，不证明新 schema。 +通过隔离 fixture 上的真实入口验收普通工作、选择、replan、等待、未结算 Turn 恢复、 +详情不可用与 capability-off 行为。每例除重建数据外，还须验证完整义务和原结算身份。 +独立 oracle 必须包含来源不同而投影相同的情况；比较同一投影的两份输出不能证明完整性。 +Native-resume/context 工作保留原 owner；采用其已验收改动，只补新组合边界缺少的集成 +覆盖。替换真正可用且其余受支持 reader 有明确切换/退役条件之前，C1 保持未完成。 + +## 12. 待决事项 + +1. **精确 wire 名称与字段映射——contract owner，在 C1 cutover 前。** 优先演进一个 + 现有注册 vocabulary/version，不另起协议族。第 8 节建议保留源根路径；完成 + producer/reader/字段盘点后确定版本与 host-binding 映射； + 字段删除需要维护者批准，保留原含义不因此新增批准要求。 +2. **首个合格双会话 host——runtime owner，在 C6 dispatch 前。** 根据实际会话控制与 + 隔离能力选择。Managed Codex 可以是实现载体，App heartbeat 是必要产品验收；两者 + 不能互相替代，也不能据此证明 benchmark 使用。 +3. **资源分配与默认——product/evaluation owner，在 C7–C8 后。** 先用相同模型的 + controller/executor 隔离架构影响；更便宜的 controller 模型与不同预算另行实验。 + 完整成果/成本证据支持决定前，profile 保持 opt-in。 diff --git a/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.md b/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.md index 368abb17a3..2fa6af4d2d 100644 --- a/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.md +++ b/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.md @@ -15,8 +15,9 @@ Sections 1–3 and 5–11 define the proposed experiment and integration boundaries; section 4 records source observations, not live qualification. Section 12 lists -decisions needed before execution. Appendix A records provenance. Keep the -Chinese mirror synchronized. Merge accepts a design basis, not a runtime +decisions needed before execution. Appendix A records provenance. The Chinese +file is a semantic mirror; keep both language versions synchronized. Merge +accepts a design basis, not a runtime default, benchmark result, spending commitment or upstream implementation promise. Future measured checkpoints belong in the existing [RFC ledger](ledger/README.md). diff --git a/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.zh-CN.md b/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.zh-CN.md index f0b9bf0a14..b4511f985b 100644 --- a/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.zh-CN.md +++ b/docs/architecture/rfcs/layerfs-engineering-exploration-evaluation-v0.zh-CN.md @@ -14,7 +14,8 @@ ## 文档地图与维护契约 第 1–3、5–11 节规定拟议实验与集成边界；第 4 节记录源码观察，不代表真实运行资格。 -第 12 节列出执行前待定事项。附录 A 保存来源。中英文保持语义同步。 +第 12 节列出执行前待定事项。附录 A 保存来源。中文文件是英文文件的语义镜像， +两种语言版本必须同步维护。 合并接受的是设计基础，不是运行时默认值、benchmark 结果、支出承诺或上游实施承诺。 后续实测 checkpoint 使用现有 [RFC ledger](ledger/README.zh-CN.md)。 diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md index 7cc8feb9d4..ad2456f24c 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md @@ -3,8 +3,9 @@ - Status: Accepted - Supersedes / closes: none - Scope baseline: architecture audit at 2026-09-16, `0aa6179de`; RFC inventory - updated through 2026-10-11 against `5c62c5c03`; steward reproduction baseline is - preserved separately in Section 8. + updated through 2026-10-11 against `5c62c5c03`; controller/contract refinement + uses `08e290fb5` on 2026-10-27. Steward reproduction baseline is preserved + separately in Section 8. - Ownership: overall product outcomes, cross-domain dependencies, priorities and portfolio acceptance here; concrete rules in domain RFCs/stable protocols; execution state in canonical Todos. - Language: [中文版](loopx-overall-roadmap-v0.zh-CN.md) is the semantic mirror. @@ -178,6 +179,31 @@ Its packaged source/recovery and comprehension checks qualify that reading slice; independent scientific calibration, installed adoption and 2.0 release acceptance remain open. Proposed experiments are advice, not execution authority. +### Unified contract and controller/executor delivery + +The [controller/executor RFC](controller-executor-unified-contract-v0.md) +refines S2/S4/S6/S7/S11: one governed work schema replaces quota/Turn packet +format choices and incorporates full-first differential context. The optional +controller model alone talks to Core; the executor receives natural-language +work and materials, while existing host/Core owners retain identity, permissions, +recovery and settlement. Session roles, execution modes, wake sources and +benchmark arms remain separate axes. This is design direction, not shipped +behavior or evidence of lower cost. + +C1's [caller cutover map](controller-executor-unified-contract-v0.md#c1-caller-replacement-and-cutover-unit) +includes quota emission, the direct Turn producer and the final native/structured +host prompts. A common capture does not unify those consumers. Qualification +checks source obligations through composition, reconstruction and actual final +input; new-admission cutover stays separate from historical receipt replay. + +Use that RFC’s C1–C9 task/deletion map within the existing work streams: first +qualify unified single-session inputs, then role binding and shared lifecycle, +replan/result authoring, executor exchange, benchmark reuse, packaged App +readback and retirement. Qualify both the App heartbeat journey and the actual +benchmark consumer; managed Codex can carry an implementation but proves neither +by itself. Reuse active context/recovery work. No new Goal, scheduler, parallel +roadmap, benchmark launch or default promotion follows from these task entries. + ### Current priorities after research and acceptance integration This checkpoint is pinned to main `5550e91bab` (2026-10-23). It reconciles @@ -464,6 +490,7 @@ subsystem was not performed. Section 8 records the focused audit. | [Complete State Recovery and Controlled Reactivation v0](complete-state-recovery-v0.md) | S2/S10 | Accepted design; backup create and configuration-only isolated recovery exist, complete-state verify/reactivation do not | M1: readable inert audit in Settings/Capability Center with owner/next action and no live authority; M3: recover one packaged local File/SQLite Goal, continue unfinished work, and record recovered/lost work, human cost, holds, owner reuse, and zero protected duplicate operations | | [Composable State Machines and Recovery Verification v0](composable-state-machines-recovery-verification-v0.md) | S2/S3/S10 | Design only; local conformance is reusable evidence | P1: one typed boundary, then ownership/writeback/settlement fault sequences and conditional progress; production entrypoint and real-backend evidence | | [Agent Loop Effect Interpreter](agent-loop-effect-interpreter-v0.md) | S2 | Accepted; core implemented, adoption continues | P0: reuse effect/recovery, cover R1 partial commits; retain domain-local replan ACK | +| [Controller / Executor and Unified Work Contract](controller-executor-unified-contract-v0.md) | S2/S4/S6/S7/S11 | Design only; schema cutover and dual-session behavior unimplemented | P1: C1–C9 converge one contract, exact differential context, role binding, shared lifecycle and benchmark/App adoption; require independent outcomes and complete costs before default promotion | | [TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | S2 | Accepted; whole-transaction migration active | P0/P1: R1–R4 hot transactions first; T0–T4 caller/deletion/cost evidence; no full rewrite prerequisite | | [Semantic Vocabulary Convergence and Commit-Time Drift Checks (v0)](semantic-vocabulary-convergence-v0.md) | S2 | Accepted; registry/inventory/drift and subsequent typed slices exist | P1: converge by semantic role and active producer/consumer; no name-based enum merging; review schema changes separately | | [LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.md) | S2/S3/S7 | Accepted; stores, local transactions and service-admission foundations exist | P1→P2: R5 local D1–D3, R6 authenticated hosts; real backend/soak/recovery before promotion | diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md index e4a9694f3e..00f0b9c1f7 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md @@ -3,7 +3,8 @@ - 状态：已接受 - 替代 / 关闭：无 - 范围基线：架构审计使用 2026-09-16 的 `0aa6179de`；RFC inventory 依据 - `5c62c5c03` 更新至 2026-10-11；管家故障复现基线单独保留在第 8 节。 + `5c62c5c03` 更新至 2026-10-11；controller/契约修订使用 2026-10-27 的 + `08e290fb5`。管家故障复现基线单独保留在第 8 节。 - 责任：总纲拥有产品目标、跨领域依赖、优先级和组合验收；领域 RFC/稳定协议拥有具体规则；运行 Todo 拥有执行状态。 - 语言：[English](loopx-overall-roadmap-v0.md) 与本文互为语义镜像。 @@ -136,6 +137,25 @@ assessment 中有证据绑定的研究综合分析接入指标 → 汇报 → 建议实验，并在输出被拒绝时保留已观测成本。打包来源／恢复与理解检查只验证这一阅读切片；独立科学校准、安装采用和 2.0 发布验收仍未完成。提出的实验属于建议，不授予执行权限。 +### 统一契约与 controller/executor 交付 + +[Controller/executor RFC](controller-executor-unified-contract-v0.zh-CN.md) 细化 +S2/S4/S6/S7/S11：用一份受治理工作 schema 替代 quota/Turn packet 格式选择，并纳入 +完整首包与差分上下文。可选 controller 模型独自对接 Core，executor 接收自然语言工作 +和材料；身份、权限、恢复、结算仍归既有 host/Core owner。Session role、执行模式、 +唤醒来源和 benchmark 评估组保持正交。这是设计方向，不是已交付行为或成本收益证据。 + +C1 的[消费链切换表](controller-executor-unified-contract-v0.zh-CN.md#c1-消费链替换与切换单元) +覆盖 quota emission、直接生产契约的 Turn 入口和最终 native/structured host prompt。 +共享 capture 不表示这些消费者已统一。资格检查须追踪来源义务经过组合、重建到实际 +最终输入；新准入切换与历史回执重放分别处理。 + +把该 RFC 的 C1–C9 任务/删除表放在既有工作流内：先验收统一单会话输入，再做角色绑定 +与共享生命周期、replan/结果编写、executor 交流、benchmark 复用、打包 App readback +及退役。App heartbeat 流程和实际 benchmark 消费者分别验收；managed Codex 可以作为 +实现载体，但不能单独证明二者。复用活跃的上下文/恢复工作。这些任务项不创建新 Goal、 +scheduler 或并行路线图，不启动 benchmark，不提升默认。 + ### 研究与验收集成后的当前优先级 本检查点固定在 main `5550e91bab`（2026-10-23），核对公共源码交付，不公布私有实验 @@ -350,6 +370,7 @@ Muse 设计页在浏览器超时，其文章通过网页检索读取。本次调 | [完整状态恢复与受控重新激活 v0](complete-state-recovery-v0.zh-CN.md) | S2/S10 | 已接受设计；备份创建与仅配置的隔离恢复已存在，完整状态验证／重新激活尚不存在 | M1：在 Settings/Capability Center 提供可读 inert audit，显示 owner／next action 且无 live authority；M3：恢复一个 packaged local 文件／SQLite Goal、继续未完成工作，并记录找回／丢失工作、人工成本、hold、owner 复用及零受保护重复 operation | | [可组合状态机与恢复验证 v0](composable-state-machines-recovery-verification-v0.zh-CN.md) | S2/S3/S10 | 仅设计；复用局部 conformance 证据 | P1：一条 typed 边界，再验 ownership/writeback/settlement 故障序列与有条件推进；真实入口及后端证据 | | [Agent Loop Effect Interpreter](agent-loop-effect-interpreter-v0.zh-CN.md) | S2 | Accepted；核心已实现，继续采用 | P0：复用 effect/recovery，先补 R1 部分提交反例，保持 replan ACK domain-local | +| [Controller / Executor 与统一工作契约](controller-executor-unified-contract-v0.zh-CN.md) | S2/S4/S6/S7/S11 | 仅设计；schema cutover 与双会话未实现 | P1：C1–C9 收敛统一契约、精确差分、角色绑定、共享生命周期与 benchmark/App 采用；独立成果和完整成本先于默认提升 | | [TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.zh-CN.md) | S2 | Accepted；整笔事务迁移中 | P0/P1：R1–R4 热事务优先；T0–T4 caller/删除/成本证据；不是百 Agent 前全量重写 | | [Semantic Vocabulary Convergence and Commit-Time Drift Checks (v0)](semantic-vocabulary-convergence-v0.zh-CN.md) | S2 | 已接受；registry/inventory/drift 与后续 typed 切片存在 | P1：按语义角色收敛 vocabulary；盘点真实 producer/consumer；不凭枚举同名合并，schema 改动单独审阅 | | [LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.zh-CN.md) | S2/S3/S7 | 已接受；store、局部事务和 service admission 基础已存在 | P1→P2：R5 本地 D1–D3；R6 认证跨 host；真实 backend/soak/恢复资格后才晋升 | diff --git a/docs/heartbeat-automation-prompt.md b/docs/heartbeat-automation-prompt.md index 4a832f0448..77f2b180ec 100644 --- a/docs/heartbeat-automation-prompt.md +++ b/docs/heartbeat-automation-prompt.md @@ -6,6 +6,16 @@ advances one LoopX goal without hiding compute policy inside the timer. The timer only wakes the executor. LoopX decides whether that wakeup should spend delivery compute. +The [unified-contract RFC](architecture/rfcs/controller-executor-unified-contract-v0.md) +keeps Codex App heartbeat as a required product qualification path. Its proposed +controller session would consume one canonical contract and delegate ordinary +work to an executor. That profile is not enabled by this template: continue to +use the installed runtime's fresh contract and existing scheduler/stop rules. + +中文：[统一契约提案](architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +将 Codex App heartbeat 列为必验产品路径。拟议 controller 消费统一契约后向 executor +交付业务任务；本模板不启用该模式，仍以已安装运行时的最新契约和调度/停止规则执行。 + ## Two Prompt Layers Keep the Codex App visible goal text and the heartbeat automation task body as diff --git a/docs/reference/protocols/README.md b/docs/reference/protocols/README.md index 526aeedc8f..60c59cd8d3 100644 --- a/docs/reference/protocols/README.md +++ b/docs/reference/protocols/README.md @@ -5,6 +5,15 @@ files remain flat in this migration to preserve established links; this index groups them by responsibility so callers can find the right contract without scanning a chronological list. +The [unified work contract and controller/executor RFC](../../architecture/rfcs/controller-executor-unified-contract-v0.md) +defines the proposed convergence of quota, Turn and host consumers. It is a +design target, not an additional shipped protocol or a replacement wire format +that callers can select today. Current versioned contracts below remain valid +until their documented migration is qualified. + +中文：[统一工作契约与 controller/executor 提案](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +规定 quota、Turn 与 Host 消费者的收敛方向；当前尚未交付新协议，现有版本契约在迁移验收前继续有效。 + ## Control Plane And State - [`active_state_structured_projection_v0`](active-state-structured-projection-v0.md): Active state structured projection v0 diff --git a/docs/reference/protocols/loopx-turn-v0.md b/docs/reference/protocols/loopx-turn-v0.md index 4bff3eb2cd..df61718ff8 100644 --- a/docs/reference/protocols/loopx-turn-v0.md +++ b/docs/reference/protocols/loopx-turn-v0.md @@ -22,6 +22,17 @@ The protocol is host-neutral. A Codex CLI adapter is the first target, but the driver lifecycle must not depend on Codex-specific session files, transcript formats, or benchmark task schemas. +The [controller/executor RFC](../../architecture/rfcs/controller-executor-unified-contract-v0.md) +proposes reusing this governed lifecycle across managed, attached heartbeat and +external-worker paths. A Turn remains the admitted work/settlement unit, not one +model message or timer wake. Splitting native session roles does not create a +second business executor, quota identity or independent control plane. + +中文：[controller/executor 提案](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +拟让托管、附着 heartbeat 与外部 worker 复用这套生命周期。Turn 仍是获准工作及其 +结算单元，不等于一条模型消息或一次唤醒；拆分会话角色不增加业务执行者或 quota 身份。 +上述跨入口收敛仍待实现与真实路径验收。 + ### Execution deadline defaults `turn run-once` now has no default single-turn wall-time limit (previously diff --git a/docs/reference/protocols/turn-envelope-v0.md b/docs/reference/protocols/turn-envelope-v0.md index 908fa52640..cf2fdc28ec 100644 --- a/docs/reference/protocols/turn-envelope-v0.md +++ b/docs/reference/protocols/turn-envelope-v0.md @@ -5,6 +5,28 @@ computed `quota should-run` decision. It gives an agent the next action and its safety contract without replaying every diagnostic lane in the full quota payload. +This page describes the current versioned representation. The +[unified-contract RFC](../../architecture/rfcs/controller-executor-unified-contract-v0.md) +proposes replacing the live quota/envelope format choice with one complete +contract, including differential delivery. Historical captures retain their +original schema and signature; the proposal does not introduce a new CLI switch. +The proposed composition point precedes capture and encoding. Today's action +signature compares its registered projection; equality alone does not establish +complete source-clause preservation or qualify the unified contract. +The RFC's [C1 caller replacement](../../architecture/rfcs/controller-executor-unified-contract-v0.md#c1-caller-replacement-and-cutover-unit) +also covers the direct Turn producer and final host prompts. Quota CLI output +parity alone does not qualify those consumers. Historical v0 decoding remains +separate from switching new admissions to a future unified version. + +中文：本页记录当前版本。[统一契约提案](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +的终态是一份包含差分交付能力的完整契约，取消线上 quota/envelope 格式选择； +历史捕获保留原 schema 与签名。本次文档更新不新增 CLI 开关。 +提议的组合点位于 capture 与编码之前。当前 action signature 比较其注册投影； +仅签名相等不能证明完整来源条款得到保留，也不能验收统一契约。 +RFC 的 [C1 消费链替换](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md#c1-消费链替换与切换单元) +还覆盖直接生产契约的 Turn 入口和最终 host prompt；仅 quota CLI 输出等价不能验收 +这些消费者。历史 v0 解码与新准入切换到未来统一版本分别处理。 + Preview it explicitly: ```bash diff --git a/docs/reference/protocols/turn-loop-controller-v0.md b/docs/reference/protocols/turn-loop-controller-v0.md index 26669c80c9..0e2ba156e4 100644 --- a/docs/reference/protocols/turn-loop-controller-v0.md +++ b/docs/reference/protocols/turn-loop-controller-v0.md @@ -21,6 +21,15 @@ or product default of three Turns. The budget applies to continued `validated_progress` on the same Todo, not a chain of completed Todos and not fine-grained planning mode. +The proposed [controller model session](../../architecture/rfcs/controller-executor-unified-contract-v0.md) +is a separate role: it reasons about work and exchanges tasks/results with an +executor. This deterministic transition owner continues to validate disposition +inputs; the model session neither replaces it nor acquires scheduler authority. + +中文：[controller 模型会话提案](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +中的 controller 负责工作判断与任务/结果交互；本页的纯状态转移 owner 继续验证 +接续输入。模型会话不替代该 owner，也不因此取得 scheduler 权限。 + ## Inputs | Input | Shape | Notes | diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index 1e56a486f3..acc2f30ed4 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -1,5 +1,16 @@ # Required work context +This page specifies current delivery behavior. The +[unified-contract RFC](../architecture/rfcs/controller-executor-unified-contract-v0.md) +proposes one full/delta/detail/recovery pipeline across entrypoints. Its +controller-authored brief must retain complete original requirements and +reachable evidence; experimental model-token targets never permit truncation +or replace source-consumption obligations. +The proposed shared composition boundary preserves source revisions and pending +read obligations before capture. Recovering delivery from that immutable capture +does not refresh authority; a legitimate new selection/authority check remains +distinct from retrying transport. + Ordinary Heartbeat/quota delivers the full effective selected Todo, enabled canonical acceptance and Agent-scoped User obligations at `interaction_contract.agent_channel.work_context`. These are current work @@ -333,6 +344,12 @@ all-Goal adoption, actual solver costs or outcome benefit. ## 中文 +本页规定当前交付行为。[统一契约提案](../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +拟让所有入口复用 full/delta/detail/recovery 流程。controller 编写的工作说明必须 +保留完整原始要求与可访问证据；实验性模型 token 目标不允许截断，也不替代来源读取义务。 +提议的共享组合边界在 capture 前保留来源 revision 与未完成必读义务。从该不可变 capture +恢复交付不刷新权限；合法的新选择/权限检查与传输重试仍是不同操作。 + 普通 Heartbeat/quota 默认在 `agent_channel.work_context` 返回完整选定 Todo、 启用的验收与当前 Agent 相关的 User Todo，附带来源和修订，不需要开启 TurnEnvelope。 Goal Markdown 复用原 writer 对生成区域的严格归属规则：所有已识别 Todo 区域均有