From a6470eafdade66c47cf237bb3c9f2336c92229fa Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Thu, 29 Oct 2026 00:06:43 +0800 Subject: [PATCH] docs(context): define candidate delivery by decision stage Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- ...controller-executor-unified-contract-v0.md | 72 ++++++++++++++++++- ...ller-executor-unified-contract-v0.zh-CN.md | 53 +++++++++++++- docs/development/testing-and-quality.md | 31 ++++++++ docs/reference/required-work-context.md | 9 +++ 4 files changed, 161 insertions(+), 4 deletions(-) diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md index 04c6afa8d2..101bccb762 100644 --- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md @@ -5,7 +5,7 @@ - **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 +- **Last normative revision:** 2026-10-28 - **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) @@ -381,6 +381,74 @@ 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. +### Candidate context by decision stage + +Preserve complete candidate context in the canonical capture; deliver it according +to the decision the consumer must make through the same C1/C2 owners. This is a +proposed replacement contract, not permission to skip existing required reads. +The current capability gate assigns selection to the Agent. A `selected_todo` +projection or list order alone does not prove that comparison is finished. Keep +the complete-context repair in [#7557](https://github.com/loopx-project/loopx/pull/7557) +until consumers and recovery obligations are replaced together. + +| Decision stage | Required input before the dependent decision | +| --- | --- | +| Select or reconsider work | Complete discoverable candidate index: identity/revision, original objective, declared Goal contribution, priority, eligibility, ownership, dependencies/blockers, current evidence/uncertainty and exact captured detail reference. Missing facts remain unknown. Read full detail for compared alternatives; if the index cannot establish whether an alternative matters, expand it before choosing. Do not silently keep only a top-K set. | +| Continue admitted work | Full selected task, original and cumulative requirements, applicable global/shared constraints, dependencies, contrary evidence, current authority and stops. A registered continuation contract may defer independent alternatives while exposing new/changed eligibility and evidence that can require reconsideration. An Agent still instructed to select over all runnable candidates remains in the selection stage. | +| Replan or accept the Goal | Expand all affected work and acceptance, including cross-Agent dependencies and contradictory evidence. Unknown scope expands to the complete captured basis. Ownership and earlier local completion do not prove irrelevance. | + +These are consumer obligations, not three packet schemas or new scheduler modes. +The typed owner determines which reads can be deferred under an explicit contract; +the Agent/controller makes the semantic choice. Author-provided purpose or risk +summaries help discovery but cannot prove omitted prose irrelevant. Do not infer +relevance from keywords, claim labels or a model-authored score. Without sufficient +typed facts, comparison can still require all bodies: cold selection has no +promised compression ratio. Default expansion of the current Agent's outcomes is +useful for ordinary work, with other outcomes discoverable; shared requirements, +dependencies, conflicting evidence and unknown relationships override that default. +Outcome scope and candidate selection remain distinct owners. + +Extend the existing immutable reader to batch selected details from the **same +capture**, retaining each requested item's revision, lineage, integrity, coverage +and cursor. Distinct revisions of one Todo stay distinct. Missing, truncated, +unsupported or changed detail holds dependent work and uses that capture's full +recovery; a fresh guard is not a detail reader. One read can deliver several bodies; +verified bodies need not be repeated within a supported retained session. Reading +an index never acknowledges hidden bodies. Delta baselines contain only material +actually delivered to that consumer: newly required detail must supply its text +even if the machine already holds it. Context loss recovers the required model +artifact, widening to the full source when its scope is unknown. Historical captures +keep their original obligations. Read receipts prove coverage, not comprehension, +retention, fresh authority or acceptance. + +The single-session Agent consumes this same pipeline. In the controller/executor +profile, the controller compares alternatives and absorbs Core bookkeeping; +the executor receives the complete selected work and authorized materials through +the existing host channel. It does not become a Core client or receive every +alternative to compensate for an incomplete brief. Reuse capability eligibility, +work-context/read fulfillment, capture/detail and delta owners; add no parallel +candidate store, Python relevance policy or per-item approval round trip. + +Qualify against original quota single-session delivery and the corrected complete +context on matched inputs. Include a decisive constraint at the end of an initially +unexpanded candidate, a useful alternative beyond any display limit, changed peer +evidence, a now-runnable blocker, identical titles with different requirements, +missing metadata, context loss and failed batch reads. Actual choice and subsequent +verified work must honor the constraint; reconstructable JSON or an unchanged +selected ID is insufficient. Count initial input, all detail reads, paging, retries, +recovery, both sessions' calls, latency and human intervention through accepted +outcomes. Keep small-task and cold-selection counterexamples where staging costs +more. Report bytes separately from tokens measured with the actual model tokenizer. + +Delivery stays within C1/C2: qualify the shared same-capture reader and required-read +recovery through an actual caller; replace that caller's stage-specific delivery +and obligations together; then qualify retained delta and matched outcomes/full +cost. Reuse [#7560](https://github.com/loopx-project/loopx/pull/7560)'s outcome-scope +work without treating outcome relations as candidate-selection proof. Diagnostic +counter folding in [#7587](https://github.com/loopx-project/loopx/pull/7587) is a +separate compatible slice, not this replacement. Each slice can have its own PR +and rollback; no generic retrieval framework or two-session rollout is required. + ## 6. Alternatives and design choices | Alternative | Disposition | @@ -782,7 +850,7 @@ 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 | +| **C2 — One context-delivery pipeline; C1** | Context owner + host observers: absorb full/delta/detail/recovery into the canonical contract; replace candidate delivery by decision stage; remove packet-format branches and duplicate context copies | Required detail precedes actual selection/work; normal/replan/resume preserve cross-Agent constraints and exact role/session continuity at measured complete cost; 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 | 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 index 9c98c54223..7d5d5e4725 100644 --- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md @@ -5,7 +5,7 @@ - **交付成熟度：** Proposal；本文不交付新运行时、schema 或默认行为。 - **作者 / 负责人：** LoopX 维护者、控制面与运行时 owner - **创建日期：** 2026-10-27 -- **最近规范性修订：** 2026-10-27 +- **最近规范性修订：** 2026-10-28 - **实现基线：** `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) @@ -294,6 +294,55 @@ session、role、epoch、schema、source capture 下证明已完整送达并保 已取消工作。Executor 任务对话独立消费语义材料，不是 controller Core packet 换名后的 delta。 +### 按决策阶段交付候选上下文 + +Canonical capture 保留完整候选上下文，由同一 C1/C2 owner 按消费者实际要做的决策 +交付。本节提出替换契约，不允许跳过已有必读项。当前 capability gate 将选择交给 +Agent；`selected_todo` 投影或列表顺序本身不能证明比较已经完成。在消费者与恢复义务 +一起替换前，保留 [#7557](https://github.com/loopx-project/loopx/pull/7557) 的完整 +上下文修复。 + +| 决策阶段 | 依赖决策前必须取得的输入 | +| --- | --- | +| 选工作或重新考虑选择 | 完整、可发现的候选索引：身份/版本、原目标、已声明的 Goal 贡献、优先级、资格、归属、依赖/阻塞、当前证据/不确定性和同次捕获详情引用。缺失事实保持未知。比较备选项前读其完整详情；索引不能判明某项是否相关时，先展开再选择。不能静默只保留 top-K。 | +| 继续已准入工作 | 完整当前任务、原始和累计要求、适用的全局/共享约束、依赖、反证、当前权限与停止条件。注册的继续执行契约可延后独立备选项，同时暴露可能触发重新考虑的新资格/资格变化和证据。仍被要求在全部 runnable 候选中选择的 Agent，依然处于选择阶段。 | +| 重规划或验收 Goal | 展开全部受影响工作与验收，包括跨 Agent 依赖和冲突证据。范围未知时展开完整捕获依据；归属和之前的局部完成不能证明无关。 | + +这些是消费者义务，不是三套 packet schema 或新 scheduler mode。Typed owner 按明确 +契约决定哪些读取可延后，Agent/controller 负责语义选择。作者提供的目的或风险摘要 +帮助发现，不能证明省略正文无关。不按关键词、领取标签或模型评分推断相关性。缺少充分 +typed 事实时，比较仍可能需要所有正文；冷态选择不承诺压缩比例。普通工作默认展开当前 +Agent 的 outcomes、让其他成果可发现是有用的；共享要求、依赖、冲突证据和未知关系 +必须突破默认范围。Outcome scope 与候选选择保留各自 owner。 + +扩展既有不可变 reader，从**同次 capture** 批量读取所选详情，保留各请求项的版本、 +来源、完整性、覆盖与游标。同 Todo 不同版本仍分开。详情缺失、截断、不受支持或变化时 +阻止依赖工作，使用该 capture 的完整恢复；fresh guard 不能充当详情 reader。一次 +读取可交付多个正文，受支持的保留会话内无需重复交付已验证正文。读索引不等于确认隐藏 +正文已读。Delta 基线只包含实际交付给该消费者的材料；新成为必需的详情必须提供正文， +不能因为机器已经存有它而省略。上下文丢失恢复必需模型产物，范围未知时扩大到完整来源。 +历史 capture 保留原义务。读取回执证明覆盖，不证明理解、保留、新鲜权限或验收。 + +单会话 Agent 消费同一管线。Controller/executor profile 中，由 controller 比较备选项 +并承担 Core 记账；executor 经既有 host 通道取得完整当前工作与授权材料。它不会成为 +Core 客户端，也不用接收全部备选项来弥补 brief 的缺失。复用 capability 资格、 +work-context/读取履行、capture/detail 与 delta owner，不新增候选存储、Python +相关性规则或逐项审批往返。 + +在相同输入上，与原 quota 单会话和修正后的完整上下文对照。覆盖：初始未展开候选末尾 +的决定性约束、展示上限之外的有价值备选项、peer 证据变化、阻塞项变为可执行、同标题 +不同要求、缺失元数据、上下文丢失及批读失败。实际选择与后续已验证工作必须遵守约束； +可重建 JSON 或 selected ID 不变不足以通过。计入从首轮输入到验收成果的全部详情读取、 +分页、重试、恢复、两个会话的调用、延迟和人工介入；保留分阶段交付更昂贵的小任务与 +冷态选择反例。字节与使用真实模型 tokenizer 测得的 token 分开报告。 + +交付仍归 C1/C2：先由真实 caller 验证共享同 capture reader 与必读恢复，再将该 caller +的阶段交付和义务一起替换，最后验证 retained delta 与可比成果/完整成本。复用 +[#7560](https://github.com/loopx-project/loopx/pull/7560) 的 outcome scope 工作， +不能将 outcome 关系当成候选选择证明。 +[#7587](https://github.com/loopx-project/loopx/pull/7587) 的诊断计数折叠是独立兼容 +切片，不代表本次替换。每个切片可有独立 PR 与回退，不要求通用检索框架或启用双会话。 + ## 6. 备选方案与取舍 | 备选方案 | 结论 | @@ -590,7 +639,7 @@ backoff 继续归当前 scheduler owner。本文不引入模型空轮询或新 | 任务 / 依赖 | 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 | +| **C2 — 一个上下文交付管线；C1** | Context owner + host observer：将 full/delta/detail/recovery 纳入 canonical 契约，按决策阶段替换候选交付，删除 packet 格式分支和重复上下文副本 | 必需详情先于实际选择/工作；正常/replan/resume 保留跨 Agent 约束与精确 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 期间单会话编写仍合格 | diff --git a/docs/development/testing-and-quality.md b/docs/development/testing-and-quality.md index 5559630fbd..4b5ab7220c 100644 --- a/docs/development/testing-and-quality.md +++ b/docs/development/testing-and-quality.md @@ -1287,6 +1287,37 @@ performance criteria, and does not qualify a model by itself. 90,000；原超限失败保留。新增候选丢失/正文缩短的零模型调用负例，原选择、人工门禁、 结算、重复次数、对照及生产硬边界不变；本次预算修正不等于真实模型通过。 +This allowance is not a target architecture. A source-level attribution at +`d4980a0e9aa8acf8b847e2fec73d29454c23690d` reproduces those three output sizes. +Their standalone pretty-JSON capability gates occupy 80,874 / 80,874 / 80,807 +UTF-8 bytes. The fixture deliberately repeats a 28-sentence diagnostic in each +row: runnable text alone is 28,767 bytes, blocked text 19,168, and binding text +19,168. These are synthetic stress costs, not a production-volume estimate. +The fixture's 16 resolution bindings are Todo-shaped text rows; the real +`agents/capability_gate.ts` owner produces capability/owner/blocked-ID bindings. +Its selected Todo is outside the runnable set in the two execution fixtures; +the human-gate fixture has no selected Todo. Preserve this regression fixture +and its historical failures, but do not use selected-ID invariance alone to +qualify actual candidate choice or remove those rows to claim a saving. + +For the proposed [decision-stage delivery](../architecture/rfcs/controller-executor-unified-contract-v0.md#candidate-context-by-decision-stage), +add a separate representative producer-to-consumer comparison: actual eligible +candidates, non-repeated requirements, meaningful alternatives and a decisive +tail constraint. Match source, model/policy and acceptance; count all batch +detail reads and recovery through subsequent verified work. A smaller first +response or a larger regression allowance cannot qualify the replacement. +Current full-context preflight remains in force until the replacement has an +explicit required-read contract; this design does not weaken or rewrite it. + +上述归因复现同一组三个输出：capability gate 单独 pretty-JSON 为 +80,874 / 80,874 / 80,807 UTF-8 字节。Fixture 每行重复 28 句诊断；runnable、 +blocked、binding 正文分别为 28,767、19,168、19,168 字节。16 个 binding 是带正文的 +Todo 形状，与生产 owner 的 capability/owner/blocked-ID binding 不同；两个执行 +fixture 的 selected Todo 不在 runnable 集合，human gate 没有 selected Todo。 +这些是压力成本，不是生产规模估计。保留原 fixture/失败，另用真实 producer、非重复 +要求、有意义备选项及末尾约束验证选择与后续工作；计入全部批读/恢复成本。新必读契约 +合格前，当前完整上下文 preflight 保持生效，不能靠删候选或首屏变小宣称收益。 + Complete registry routes exposed an existing brief heartbeat regression on the unchanged 128-character-root fixture. Commit `fb20c153ba2c2a7376efe68091a76ca470effbde` added those routes: its immediate parent diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index fefe903dd4..4499a715e5 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -11,6 +11,15 @@ 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. +The RFC's [candidate context by decision stage](../architecture/rfcs/controller-executor-unified-contract-v0.md#candidate-context-by-decision-stage) +proposes complete captured alternatives with discoverable decision facts and +same-capture batch detail reads. It does not change current read obligations. +The current capability gate leaves candidate selection to the Agent; a selected +Todo display is not proof that it can ignore alternatives. Existing full-context +captures must still be read completely. A future staged caller must replace its +delivery, required reads and recovery together, including unknown-scope full +fallback; an index read cannot establish delivery of hidden bodies. + 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