diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md index 668aa91b4d..81b7a1f151 100644 --- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md @@ -861,6 +861,33 @@ 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. +### Default adoption and retirement qualification + +The [context-delivery guide](../../guides/context-delivery.md#qualify-default-adoption-and-retirement) +turns this comparison into an operator plan. Documentation may ship first; +future broader default adoption needs both a declared DeepSeek model and a declared +strong model to support the claimed effectiveness and complete-cost scope. +The reference's existing Codex-scoped default remains current behavior, not proof +that these model comparisons have passed. +Record exact model/provider/version/effort and fixed task, source, host, tools, +feedback, evaluator, budget and stops. Include actual final input/output, +cached/uncached tokens, requests, detail/recovery reads, wall/IO/setup costs and +human attention, alongside task-native outcomes, constraint misses, wrong +actions and once-only recovery. Unknown cost is not zero; preserve repeated-run +variation, failures and negative cases. Historical-best optimization keeps that +native ranking, with final-retention facts separate. A Codex-scoped adapter +cannot qualify a DeepSeek host. + +Keep this sequence in C1/C2/C9: explanation → both-model comparison → supported +profile's reversible adoption/release → scoped default → named old-path +retirement. Mixed or regressed results retain opt-in or explicit limitations. +Retirement requires actual caller replacement, historical decoding/readback, +supported-version and rollback coverage; full snapshots, digest checks, +authority/identity/stops and recovery remain. Do not preserve two permanent +semantic owners or delete a still-supported reader based on new-path existence. +This is a qualification plan, not new experiment authority, a claim of shipped +benefit, or a gate on other independent authorized work. + The [packaged source comparison](ledger/controller-executor-unified-contract-v0/2026-10-29-packaged-source-comparison.md) pins mainline quota and the C1 candidate through real File/SQLite CLI delivery, file deltas, capture refusal/recovery and once-only settlement. Source fidelity 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 89e87e0578..0d7fbd089d 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 @@ -645,6 +645,23 @@ C1 的主要对照是**同一单会话产品路径中的原 quota packet 与融 传输复用掩盖语义退步。Controller/executor 分离是之后独立的对照,不能用来解释或 抵消 C1 回归。 +### 默认采用与退役资格 + +[上下文交付指南](../../guides/context-delivery.zh-CN.md#默认化与退役的验收) 把此比较落实为 +操作方案。文档可先交付;未来扩大默认采用范围需要明确版本的 DeepSeek 与强模型分别支持 +所声明的效果和完整成本范围。reference 已有的 Codex 范围默认仍是当前行为,不证明 +这些模型对照已通过。记录精确 model/provider/version/effort,固定 task、source、host、 +tools、反馈、evaluator、预算与停止条件。除原生任务成果、约束遗漏、错误动作和 +一次性恢复外,计入实际最终 input/output、cached/uncached tokens、请求、详情/恢复 +补读、墙钟/IO/搭建成本与人工注意力。未知成本不记零,保留重复波动、失败与负例。 +历史最佳优化保持原生排名,终态保留事实另列。仅 Codex adapter 不资格化 DeepSeek 宿主。 + +顺序留在 C1/C2/C9:解释 → 双模型比较 → 受支持 profile 的可回退采用/发布 → 范围化 +默认 → 点名旧路径退役。结果混合或退步时保留 opt-in 或明确限制。退役须核实际 caller +替换、历史解码/readback、支持版本与回退覆盖;完整快照、摘要校验、权限/身份/停止 +和恢复继续保留。不长期保留两个同义决策 owner,也不因新路径存在就删除仍受支持的 +reader。这是资格方案,不授予新实验权限,不宣称已交付收益,也不阻塞其他独立获授权工作。 + [打包来源对照](ledger/controller-executor-unified-contract-v0/2026-10-29-packaged-source-comparison.zh-CN.md) 固定 mainline quota 与 C1 候选版本,经真实 File/SQLite CLI 验证交付、文件差分、 capture 拒绝/恢复及一次结算。本负载来源保真改善,冷态和观察器累计输出字节增加。 diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md index 1c56fc7d01..2fd8bb86f1 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md @@ -218,6 +218,19 @@ larger cold/output bytes and an open standalone numeric hash boundary. Preserve that counterevidence and the original outcome/full-cost gate; a working saved-file delta or once-only receipt does not establish long-horizon benefit. +The [context-delivery guide](../../guides/context-delivery.md) explains current +behavior and a minimum two-model comparison. Deliver documentation first; +within C1/C2/C9, qualify a declared DeepSeek model and a declared strong model +against the original quota path under matched conditions and complete costs. +Then qualify reversible adoption and release of a supported profile before a +broader default recommendation. The reference's existing Codex-scoped default +remains current behavior, not proof of model benefit. Mixed or regressed model results retain scoped opt-in +or explicit limitations. Retire only named replaced producers/consumers after +actual migration, historical-reader compatibility and rollback evidence; keep +full snapshots, integrity, authority, identity, stops and recovery. A guide, +Codex-only adapter or shorter output does not pass the model/default gate. +This sequence neither blocks independent authorized work nor starts experiments. + 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 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 b6ef303a57..2d8be1c6c4 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md @@ -167,6 +167,15 @@ C1 的[消费链切换表](controller-executor-unified-contract-v0.zh-CN.md#c1- 以及尚开放的独立数值 hash 边界。保留这些反证和原成果/完整成本门;文件差分或一次 结算回执可用,不证明长程收益。 +[上下文交付指南](../../guides/context-delivery.zh-CN.md) 解释当前行为和最小双模型对照。 +文档先交付;在 C1/C2/C9 内,用明确版本的 DeepSeek 与强模型,分别对照原 quota 路径, +固定可比条件并计入完整成本。随后验收受支持 profile 的可回退采用与发布,再决定默认 +范围扩展建议;reference 已有的 Codex 范围默认仍是当前行为,不证明模型收益。 +结果混合或某模型退步时,保留范围化 opt-in 或明确限制。退役须点名已替换的 +producer/consumer,以实际迁移、历史 reader 兼容和回退证据为依据;保留完整快照、 +完整性、权限、身份、停止与恢复。指南、仅 Codex adapter 或更短输出不通过模型/默认 +门。此顺序不阻塞独立获授权工作,也不启动实验。 + 把该 RFC 的 C1–C9 任务/删除表放在既有工作流内:先验收统一单会话输入,再做角色绑定 与共享生命周期、replan/结果编写、executor 交流、benchmark 复用、打包 App readback 及退役。App heartbeat 流程和实际 benchmark 消费者分别验收;managed Codex 可以作为 diff --git a/docs/guides/README.md b/docs/guides/README.md index 9cb4bba49d..b8afd04f32 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -6,6 +6,8 @@ Guides are task-oriented paths for people starting or operating LoopX. - [Installing LoopX](installing-loopx.md) - [Newcomer command path](newcomer-command-path.md) - [Codex App 自动续跑体验指南](codex-app-autonomous-goal-experience.md) +- [Understand, use and evaluate context delivery](context-delivery.md) +- [理解、使用和验收上下文交付](context-delivery.zh-CN.md) - [Minimal custom runtime example](minimal-custom-runtime-example.md) - [Minimal custom runtime example (中文)](minimal-custom-runtime-example.zh-CN.md) - [Custom Agent runner integration](custom-agent-runner-integration.md) diff --git a/docs/guides/context-delivery.md b/docs/guides/context-delivery.md new file mode 100644 index 0000000000..b7fc90c7ec --- /dev/null +++ b/docs/guides/context-delivery.md @@ -0,0 +1,292 @@ +# Understand, use and evaluate context delivery + +[中文](context-delivery.zh-CN.md) + +Context delivery gives an Agent the requirements for its current work and a +verifiable route to the evidence behind them. **Progressive reading** determines +which material a decision needs; **differential delivery** represents changes +between exact versions. They share a pipeline, but answer different questions. + +The native Codex path defaults on for supported POSIX Codex App/SSH and declared +benchmark heartbeat callers when no machine preference is saved. Saved or explicit +off disables it; ordinary CLI, other hosts and unsupported platforms inherit full +delivery. + +A saved setting is not proof that a host is ready, +that a particular response used a delta, or that the model understood it. The +complete C1 caller migration and long-horizon cost/outcome qualification remain +open. Broad default adoption and old-path retirement need the evidence below. + +- To understand a work session, start with [the example](#one-task-four-situations). +- To operate it, see [enable, verify and roll back](#enable-verify-and-roll-back). +- To change the implementation or its defaults, see + [qualification and retirement](#qualify-default-adoption-and-retirement). + +The [required-work-context reference](../reference/required-work-context.md) +owns current semantics; the [controller/executor RFC](../architecture/rfcs/controller-executor-unified-contract-v0.md) +owns proposed convergence. This guide explains those owners rather than defining +another protocol. + +## Follow the information, not just the prompt + +```mermaid +flowchart TD + A[Current authority and sources] --> B[Immutable capture] + B --> C[Required view and detail references] + C --> D[Full or exact delta] + D --> E[Agent reads necessary facts] + E --> F[Work and verification] + F --> G[Existing writeback and settlement] + E -->|Needed evidence| B +``` + +1. Existing Goal, Todo, acceptance, preference and capability owners supply facts. + A pending read or unavailable source stays visible; presentation cannot turn + it into a successful read or execution permission. +2. Capture binds the source version and work identity. Current native delivery + keeps an original `projection.json` and a required model view, + `required-context.json`. Supporting provenance and review explanations can + remain in the original capture with exact detail references. +3. The TypeScript owner composes the required view, then encodes it. Known + acceptance requirements and current review/check states remain available; + supporting explanations are read when the decision depends on them. Exact + repeated rows may point to their complete occurrence in the same view. + Unknown or unsupported shapes retain their full obligations. +4. The codec compares compatible versions. Native Codex uses a verified saved + file within its session/epoch as the baseline. The final native output also + accounts for reference and complete-read framing when choosing full versus + delta. A full response can therefore be the cheaper valid choice. +5. The Agent obtains the facts required by its next action and does the work. + Admission, fresh authority checks, validation and once-only effects remain + with their existing owners. Reading a capture does not perform those actions. + +The shared implementation starts at +[`prepareProgressiveContextDelivery`](../../loopx/control_plane/quota/progressive_context.ts), +uses the [exact codec](../../loopx/control_plane/quota/context_delivery.ts), and +leaves native files, locking and lifecycle IO to the +[Codex adapter](../../loopx/control_plane/turn_driver/codex_context.py). +One shared preparation call does not prove that every final caller has migrated. + +### Keep three meanings of reuse separate + +| Mechanism | What it reuses | What it does not prove | +| --- | --- | --- | +| Same-response reference | One complete exact value in this current view | That a hidden or older value was read | +| Saved-file delta | Verified immutable file versions with compatible identity | Model retention, comprehension or fresh permission | +| Provider prompt cache | Provider-specific processing/billing reuse of input | Source correctness, task success or LoopX net savings | + +Semantic summarization is another operation: it can change wording or meaning. +The exact codec is not a semantic summary. A controller-authored brief remains +a separate proposed workflow with its own retained-requirement and outcome +tests. Neither shorter wording nor a provider cache hit validates that proposal. + +Explicit confirmed-input clients also have a retained-input contract. Do not +replace that contract with native Codex's saved-file assumption, or require +native Codex to read an old full packet merely to establish a file baseline. + +## One task, four situations + +Consider a synthetic task: **add a UTF-8 export, preserve the existing format, +and never overwrite an existing destination**. The checks and evidence below +are illustrative; they are not a benchmark result. + +| Situation | What the Agent sees or retrieves | What must still happen | +| --- | --- | --- | +| Cold start | A current capture reference and navigation to the full task, Goal intent, applicable requirements, authority and stops | Read the necessary facts and required sources before work; inspect supporting implementation/evidence as needed | +| Warm continuation | A full or delta view of the new version; unchanged facts remain binding through the compatible capture | Read the new test result and any necessary inherited facts; validate the actual export rather than equating a smaller input with success | +| Constraint changes | The current source revision now also requires a distinct output naming rule | Reconcile the changed requirement before the affected write; an old permission or successful test does not cover the new requirement | +| Compaction or lost baseline | Recovery references remain available, while a later work Turn starts a new baseline epoch | Recover missing necessary facts from the same current capture and continue with the original work/effect identity; do not repeat admission or an already committed export merely because context was lost | + +“Full” describes an available complete saved view, not an obligation to drain +every field before making any decision. Read the applicable Goal intent, +requirements, authority, stops and verification obligations first. Expand +supporting evidence when the decision needs it. A broader replan or whole-Goal +acceptance needs a correspondingly broader reading scope. + +The native saved-file basis can inherit unchanged fields, including controls. +An omission from a delta is not evidence that a constraint disappeared, or that +the model has retained it. Retrieve necessary current facts when uncertain. +Default-off and signed-envelope callers retain their own read contracts; the +progressive native example does not relax them. + +### Read and recover the right object + +Use the path, digest and command returned by the current response. A native +response's `recovery` identifies its complete current required view; +`context_details` can identify the original capture containing deferred evidence. +Do not substitute one file's hash for another's. + +- Use known JSON Pointers directly; repeat `--select` for related fields. +- For an unknown pointer, list the nearest known parent with `--list`; use + `--list-depth 2` when it avoids another discovery round. To list the root, + omit `--select` rather than using `/`, which denotes an empty-name property. +- Follow the returned byte cursor for an unfinished selected range. EOF applies + to that selection, not to unread fields elsewhere in the capture. +- Size both reader pages and the host tool's combined output budget. Valid JSON, + a saved log or an EOF flag does not account for bytes the host truncated. + Recover the missing range from the same capture with a smaller batch. +- A missing baseline, unsupported delta or invalid binding recovers the current + full capture. Do not fetch an old packet just to seed a new baseline. + +Compaction does not cancel an admitted Turn. A working brief helps recover its +identity and progress; it grants no new authority or retention proof. Keep a +known accepted operation and its receipt distinct from unresolved delivery. +Fresh authority is still required when the action's owner requires it, but +transport recovery alone does not justify another guard or quota spend. + +## Enable, verify and roll back + +The current native continuity adapter supports POSIX Codex App heartbeat, Codex +App SSH Goal and the explicitly declared Codex benchmark heartbeat worker. +Declarations select an adapter; they do not authenticate a host. Unsupported, +missing or contradictory explicit-on declarations are errors. Other resolved +hosts keep full delivery when inheriting this Codex-scoped preference. + +In the App, use **Settings → This machine → Capabilities → Differential context +→ Codex**. The existing revision-locked preview/apply/readback transaction owns +the setting. It does not initialize the current native session or prove that +its lifecycle hooks are installed. Read-only settings views cannot save it. + +For CLI operators, the same `context_delivery` machine namespace is documented +under [Machine default](../reference/required-work-context.md#machine-default). +There is no separate Goal configuration to duplicate: + +- **Explicit `--context-delivery on` or `off`:** overrides the inherited machine + choice for that invocation. +- **No explicit choice:** uses the saved machine preference when present. +- **No machine preference:** supported native Codex callers default on; other + callers keep full delivery. +- **Worker `LOOPX_CONTEXT_DELIVERY=off`:** overrides inheritance; environment on + alone does not enable native delivery. +- **Turn the App switch off:** saves off through the same transaction; it does + not reverse task effects or rewrite old captures. + +After enabling, inspect an actual supported invocation: its target binding, +full/delta mode, current recovery reference and supported lifecycle context must +agree. Full mode is valid at cold start, after loss, or when complete delivery +costs less. Saving on and observing full do not by themselves indicate failure +or success of delta reuse. + +Machine consumers that parse raw `should_run` or settlement facts must continue +to request raw output on their internal calls. A native presentation envelope +is not the raw authority response; a missing `should_run` is not a denial. +Do not change an experiment's frozen mode, source or clock by changing machine +settings. Trials retain their explicit configuration and original authority. + +### Troubleshoot without changing task history + +| Observation | Check next | +| --- | --- | +| On is rejected | Actual host declaration, supported scenario and POSIX requirement; do not guess a different host identity | +| Every response is full | Session/epoch continuity, file availability and the codec's reason; full may be the expected cheaper representation | +| A selector is missing | List the current parent and use the correct capture/digest; recover necessary facts without another admission | +| A source changed during an exact read | Follow the current task/source freshness contract; a historical capture is not fresh authority | +| A reply disappeared after an effect | Reconcile the original operation and receipt before retrying the effect | +| A new setting saved but no native reuse appears | Host/session setup and actual invocation readback; the saved preference is only one prerequisite | + +Captures and journals may contain private tasks and evidence. Native storage +uses a private runtime directory and per-session journals, with restrictive +permissions and unsafe-path rejection. Do not attach raw captures, local paths +or journals to a public issue. Share a permitted redacted reproducer. Turning +off presentation is not a retention-policy change or a request to delete logs. + +## Qualify default adoption and retirement + +The [RFC's single-session comparison](../architecture/rfcs/controller-executor-unified-contract-v0.md#9-validation-and-acceptance) +remains first: original quota packet versus the fused contract in the same +product path. Optional controller/executor separation is a later comparison. +Do not explain away a single-session regression with a two-session result. + +Future broader default adoption requires **both a declared DeepSeek model and a strong +model** to pass comparable effectiveness and complete-cost evaluation. Run each +model's comparison within its own fixed conditions; do not pool them to hide a +regression. This guide supplies a plan, not new experimental authority or a +claim that either model family has passed. +These criteria govern extending the current scoped default; that shipped default +does not itself prove either model comparison has passed. + +### A minimum discriminating study + +1. Reuse the [benchmark-toolkit](../../loopx/capabilities/benchmark_toolkit/README.md) board, + source/integrity contracts and already qualified evidence. Before execution, + declare exact model/provider/version/reasoning settings, source and host, + tasks/inputs, tools, evaluator/feedback, budget and stops. Declare repetition, + acceptance criteria and the available billing basis; do not invent missing + prices, versions, sample sizes or thresholds. +2. First qualify engineering semantics: cold input, warm continuation, a changed + constraint, and compaction/interrupted recovery. Include a small task and + repeated history; verify source fidelity, required facts, invalid references, + authority boundaries and once-only effects before comparing model benefits. +3. For each model, compare the original-quota/current control with the composed + path under the same single-session workload. Report the actual final model + input, detail reads and recovery, not only the middle serializer. Reuse lawful + progressive-only or delta-only controls when contribution needs separation; + add only the minimum authorized ablation, not new production switches or an + automatic large matrix. +4. Measure the table below and retain failures, variation and negative cases. + Freeze promotion criteria before running; collect subsequent accepted work + that proves adoption of changed constraints or feedback. + +Keep the minimum comparison visible as four cells, each covering the same +declared cold/warm/changed-constraint/recovery scenarios: + +| Declared model | Control | Treatment | +| --- | --- | --- | +| DeepSeek, exact provider/version/settings recorded | Pinned original quota path | Pinned composed path, same host and conditions | +| Strong model, exact provider/version/settings recorded | Pinned original quota path | Pinned composed path, same host and conditions | + +Read existing board rows before selecting cases. Reuse eligible runs; a missing +cell stays unqualified. Preregister each treatment's baseline run binding and +the repetition/order policy, then let the authorized runner execute unchanged +task inputs and evaluator. Each cell returns its source/host binding, actual +final inputs and recovery reads, native outcomes, full costs and integrity +status. Keep failed or censored attempts in the record. The board represents +run eligibility; it does not itself prove a causal comparison or authorize a run. + +The native adapter above is Codex-scoped. It does **not** establish a DeepSeek +host's support. A DeepSeek comparison needs an authorized, qualified host that +exercises the same semantic pipeline; unsupported coverage remains a gap, not +a license to substitute Codex results or change a running study. + +| Effectiveness | Complete applicable cost | +| --- | --- | +| Independent task acceptance/success or task-native metric | Actual input/output and cached/uncached tokens, including known compaction/request coverage | +| Constraint omissions, wrong actions, evidence use | Model/tool requests, detail reads, retries and recovery | +| Recovery, duplicate-effect prevention and usable delivered artifacts | Wall time, applicable tail latency, snapshot/hash/IO and setup/maintenance | +| Actual subsequent adoption of revisions | Human decisions, navigation, intervention and attention | + +Use the task's native ranking. For optimization tasks ranked by historical best, +do not replace it with the final source's score; final artifact/retention facts +remain separate where applicable. Unknown costs are not zero. Time between +evaluation completion and feedback collection can overlap independent +validation; measure that overlap before calling it idle delay. Fewer calls or +smaller bytes can coexist with worse accepted outcomes. + +The existing [packaged-source comparison](../architecture/rfcs/ledger/controller-executor-unified-contract-v0/2026-10-29-packaged-source-comparison.md) +provides real CLI/source/recovery evidence and also records larger cold/output +bytes. Reuse that qualified scope, not a claim of model savings. Cold start, +small tasks, lost baselines and one model regressing are required countercases +to a broad default recommendation. + +### Release and deletion are separate decisions + +| Stage | Exit evidence and owner | +| --- | --- | +| Explain current behavior | Guide/reference agree with real callers; documentation owner preserves the proposal/implementation boundary | +| Evaluate both models | Benchmark owner records fixed conditions, accepted outcomes, costs, uncertainty and unsupported coverage | +| Adopt a supported profile | Runtime/host owner qualifies the real packaged journey and reversible configuration; maintainer decides release scope | +| Recommend a broader default | Both model results support that declared scope; mixed/regressed results retain scoped opt-in or explicit limitations | +| Retire an old path | Caller owner proves replacement, historical-reader compatibility, supported-version/rollback coverage and no remaining live consumer | + +Retirement must name an actual producer, consumer and replacement. Removing a +duplicate decision algorithm after caller migration differs from deleting a +historical decoder. Keep complete snapshots, digest checks, authority/identity/ +stop validation and required recovery. Explicit retained-input clients and +native file-baseline clients are distinct compatibility obligations. Do not +leave two permanent semantic owners, or delete a still-supported reader merely +because the new path exists. + +The [roadmap](../architecture/rfcs/loopx-overall-roadmap-v0.md#unified-contract-and-controllerexecutor-delivery) +and RFC retain the owners and remaining C1/C2/C9 work. Documentation can ship +before model experiments; neither a merged guide nor a smaller packet completes +those runtime, adoption or benefit requirements. diff --git a/docs/guides/context-delivery.zh-CN.md b/docs/guides/context-delivery.zh-CN.md new file mode 100644 index 0000000000..7982e5c7bf --- /dev/null +++ b/docs/guides/context-delivery.zh-CN.md @@ -0,0 +1,228 @@ +# 理解、使用和验收上下文交付 + +[English](context-delivery.md) + +上下文交付让 Agent 获得当前工作的要求,以及通向其证据的可核验入口。**渐进阅读**决定 +本次判断需要哪些材料;**差分交付**表达精确版本之间发生了什么变化。二者共用管线, +但回答不同的问题。 + +未保存机器偏好时,受支持的 POSIX Codex App/SSH 和已声明的 benchmark 心跳入口 +默认开启原生路径。保存 off 或显式关闭可禁用;普通 CLI、其他宿主与不支持的平台 +继承完整交付。 + +保存开关不证明宿主已就绪、某次输入用了 delta,或模型已理解材料。完整 C1 消费链迁移和 +长程成果/成本资格仍未完成;广泛默认化和旧路径退役须取得下文证据。 + +- 理解一次工作,从[四种场景](#一项任务四种场景)开始。 +- 实际使用,看[开启、验证和回退](#开启验证和回退)。 +- 修改实现或默认行为,看[默认化与退役的验收](#默认化与退役的验收)。 + +[Required work context](../reference/required-work-context.md) 定义当前语义; +[Controller/executor RFC](../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) +拥有未来收敛设计。本指南解释既有 owner,不另立一套协议。 + +## 沿信息链理解,而不只看 prompt + +```mermaid +flowchart TD + A[当前权威与来源] --> B[不可变 capture] + B --> C[必要视图与详情引用] + C --> D[全量或精确差分] + D --> E[Agent 读取必要事实] + E --> F[实际工作与验证] + F --> G[既有写回与结算] + E -->|需要证据| B +``` + +1. 既有 Goal、Todo、acceptance、偏好与 capability owner 提供事实。待完成读取和来源 + 不可用继续可见;展示不能把它们变成已读或执行许可。 +2. Capture 绑定来源版本和工作身份。当前原生交付保留原始 `projection.json`,以及 + 面向模型的必要视图 `required-context.json`。来源历史与评审解释可保存在原 capture, + 通过精确详情引用到达。 +3. TypeScript owner 先组成必要视图,再编码。已知验收要求与当前评审/检查状态保持 + 可达;判断依赖解释时再展开。完全相同的重复行可引用同一视图中完整的那一份。 + 未知或不支持的形状保留完整义务。 +4. Codec 比较兼容版本。原生 Codex 以同一 session/epoch 中校验过的保存文件为基线; + 最终输出还计入引用与完整读取的封装成本,再选择 full 或 delta。因此 full 也可能 + 是更便宜的合法结果。 +5. Agent 取得下一动作所需事实,执行并验证。准入、新鲜权限检查、验收和一次性效果 + 仍归既有 owner;读 capture 不执行这些操作。 + +共享实现由 +[`prepareProgressiveContextDelivery`](../../loopx/control_plane/quota/progressive_context.ts) +开始,使用[精确 codec](../../loopx/control_plane/quota/context_delivery.ts),文件、锁和原生 +生命周期 IO 留给 [Codex adapter](../../loopx/control_plane/turn_driver/codex_context.py)。 +一次共享准备调用,不证明所有最终消费者已经迁移。 + +### 三种复用分别看 + +| 机制 | 复用什么 | 不证明什么 | +| --- | --- | --- | +| 同响应引用 | 当前视图内一份完整、精确的值 | 隐藏或旧版本的值已经被读过 | +| 保存文件差分 | 身份兼容、经过校验的不可变文件版本 | 模型保留、理解或新鲜权限 | +| Provider prompt cache | Provider 自己的输入处理/计费复用 | 来源正确、任务成功或 LoopX 净收益 | + +语义摘要是另一种操作,会改变措辞,可能改变含义。精确 codec 不做语义摘要。 +Controller 编写 brief 仍是单独提议的工作流,须验收保留要求与实际成果;更短的文字或 +provider cache 命中都不能替它通过。 + +显式确认完整输入的客户端另有 retained-input 契约。不能把它换成原生 Codex 的文件 +假设,也不能要求原生 Codex 为建立文件基线先把旧完整包读进模型。 + +## 一项任务,四种场景 + +用一个合成任务贯穿:**增加 UTF-8 导出,保留原有格式,绝不覆盖已有目标文件**。 +下列检查和证据是说明例子,不是 benchmark 结果。 + +| 场景 | Agent 看到或取得什么 | 仍须完成什么 | +| --- | --- | --- | +| 冷启动 | 当前 capture 引用,以及完整任务、Goal 意图、适用要求、权限与停止条件的入口 | 工作前读必要事实与必读来源,按需检查实现/支持证据 | +| 暖态继续 | 新版本的 full 或 delta;未变化事实仍经兼容 capture 保持约束力 | 读新测试结果及所需继承事实;验收实际导出,不能把输入变短当成功 | +| 约束变化 | 当前来源 revision 新增输出命名规则 | 在受影响写入前对齐新要求;旧许可或旧测试不覆盖新要求 | +| 压缩或基线丢失 | 恢复引用仍在,后续工作 Turn 使用新基线 epoch | 从本轮同源 capture 补缺失必要事实,沿原工作/effect 身份继续;不能因丢上下文重复准入或已提交的导出 | + +Full 表示完整保存视图可用,不要求判断任何问题前先遍历所有字段。先读适用的 Goal +意图、要求、权限、停止与验证义务,判断需要时展开支持证据。广域重规划或整体验收 +相应扩大阅读范围。 + +原生文件基线可继承未变化字段,包括控制字段。Delta 没列出某条约束,不表示它已 +消失,也不证明模型保留了它。不确定时取得必要当前事实。Default-off 与签名 envelope +调用方继续遵守各自读取契约;这个渐进原生例子不放宽它们。 + +### 读对对象,再恢复 + +使用当前响应返回的路径、摘要与命令。原生响应的 `recovery` 指向当前完整必要视图; +`context_details` 则可指向包含延后证据的原始 capture。不能交换两份文件的 hash。 + +- 已知 JSON Pointer 直接选择,相关字段用重复 `--select` 批量读取。 +- 未知 pointer 先对最近的已知父节点 `--list`;必要时用 `--list-depth 2` 减少发现往返。 + 列出根节点时省略 `--select`,不要写表示空名称属性的 `/`。 +- 未完成的选择沿返回的字节 cursor 继续。EOF 只覆盖该选择,不代表读了其他字段。 +- 同时控制 reader 页与宿主工具的合计输出预算。合法 JSON、落盘日志和 EOF 都不能 + 补上被宿主截掉的字节;缩小批次,从同一 capture 补缺失范围。 +- 基线缺失、不支持的 delta 或绑定无效时,恢复当前完整 capture;不要先取旧包给 + 新基线垫底。 + +压缩不取消已准入的 Turn。Working brief 帮助找回原身份和进度,不提供新权限或模型 +保留证明。已接受操作及其回执,与尚未解决的投递分开;动作 owner 要求新鲜权限时 +仍须取得,但单纯传输恢复不构成再次 guard 或扣额的理由。 + +## 开启、验证和回退 + +当前原生连续性 adapter 支持 POSIX 下的 Codex App heartbeat、Codex App SSH Goal, +以及显式声明的 Codex benchmark heartbeat worker。声明选择 adapter,不认证宿主。 +显式 on 的声明缺失、矛盾或不支持会报错;其他已解析宿主继承这个 Codex 范围偏好时 +保持完整交付。 + +App 中使用 **Settings → This machine → Capabilities → Differential context → Codex**。 +已有的 revision 锁定 preview/apply/readback 事务拥有这项设置;它不初始化当前原生 +session,也不证明生命周期 hook 已安装。只读设置页不能保存。 + +CLI 使用同一个 `context_delivery` 机器 namespace,详见 +[机器级默认](../reference/required-work-context.md#机器级默认),无需再建 Goal 配置。 + +- **显式 `--context-delivery on` 或 `off`**:覆盖该次调用继承的机器选择。 +- **没有显式选择**:已保存机器偏好时使用该偏好。 +- **没有机器偏好**:受支持原生 Codex 调用方默认开启;其他调用方保持完整交付。 +- **Worker 显式 `LOOPX_CONTEXT_DELIVERY=off`**:覆盖继承;环境变量 on 本身不开启原生交付。 +- **关闭 App 开关**:经同一事务保存 off,不撤销任务效果或改写历史 capture。 + +开启后核对一次真实受支持调用:target 绑定、full/delta 模式、当前恢复引用与宿主 +生命周期上下文应一致。冷启动、丢失后或完整交付更便宜时,full 完全合法;保存 on +与看到 full 本身,都不能判断差分是否正确复用。 + +解析原始 `should_run` 或结算事实的机器消费者,其内部调用仍须请求 raw 输出。原生 +展示封装不是原始权威响应;封装中缺少 `should_run` 不表示拒绝准入。不能通过改机器 +设置改变某个实验冻结的模式、来源或时钟;trial 保留原显式配置与权限。 + +### 排障不改写任务历史 + +| 观察 | 下一检查 | +| --- | --- | +| On 被拒绝 | 实际宿主声明、支持场景与 POSIX 要求,不猜一个不同宿主身份 | +| 每次都是 full | Session/epoch 连续性、文件是否可读及 codec 原因;full 可能就是更便宜的预期形式 | +| Selector 不存在 | 列当前父节点,使用正确 capture/digest,补必要事实而不再次准入 | +| 精确读取时来源变化 | 遵守当前任务/来源新鲜度契约;历史 capture 不是新鲜权限 | +| 效果发生后回复丢失 | 先对齐原 operation 和回执,再决定是否重试效果 | +| 设置已保存却未见原生复用 | 核宿主/session 准备与实际调用;保存偏好只是一个前提 | + +Capture/journal 可包含私有任务与证据。原生存储使用私有 runtime 目录和分 session +journal,限制权限并拒绝不安全路径。不要把原始 capture、本机路径或 journal 附到 +公开 issue,使用获准的脱敏复现。关闭展示不改变保留政策,也不是删除日志的请求。 + +## 默认化与退役的验收 + +先保留 [RFC 的单会话对照](../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md#9-验证与验收): +同一产品路径中的原 quota packet 与融合契约。可选 controller/executor 分离是之后 +的独立比较,不能用双会话结果解释或抵消单会话回归。 + +未来扩大默认采用范围必须同时有**明确版本的 DeepSeek 模型与强模型**的可比效果、完整成本 +证据。每个模型内部固定条件分别比较,不能合并结果掩盖某一个模型退步。本指南提供 +方案,不授予新实验权限,也不宣称任何一个模型系列已经通过。 +这些标准约束现有范围化默认的扩展;已交付的默认行为本身不证明双模型对照通过。 + +### 最小判别研究 + +1. 复用 [benchmark-toolkit](../../loopx/capabilities/benchmark_toolkit/README.md) 的 board、来源/ + integrity 契约和已有合格证据。执行前声明 model/provider/version/推理配置、source + 与宿主、任务/输入、工具、evaluator/反馈、预算与停止条件;同时冻结重复策略、 + 验收标准和可获得的计费口径。不编造缺失价格、版本、样本量或数值阈值。 +2. 先验收工程语义:冷态、暖态、关键约束变化、压缩/中断恢复,并纳入小任务和重复 + 历史,验证来源保真、必要事实、无效引用、权限边界和一次性效果,再比较模型收益。 +3. 每个模型用同一单会话负载,对照原 quota/现行控制与组合路径。记录真实最终模型 + 输入、详情补读与恢复,不只测中间 serializer。需要拆贡献时复用合法的 progressive + 或 delta 单因素对照;只补最小获授权消融,不为试验添加生产开关或默认启大矩阵。 +4. 按下表测量,保留失败、波动与负结果;执行前冻结晋级标准,并用后续验收工作证明 + 模型实际采用变化要求或反馈。 + +最小比较保留四格,每格覆盖同一组已声明的冷态/暖态/约束变化/恢复场景: + +| 已声明模型 | 控制 | 处理 | +| --- | --- | --- | +| DeepSeek,记录精确 provider/version/配置 | 固定版本的原 quota 路径 | 固定版本的组合路径,同宿主、同条件 | +| 强模型,记录精确 provider/version/配置 | 固定版本的原 quota 路径 | 固定版本的组合路径,同宿主、同条件 | + +选案例前先读现有 board,复用合格 run;缺失一格就保持未合格。预登记各处理组的基线 +run 绑定及重复/顺序策略,再由获授权 runner 执行不变的任务输入与 evaluator。 +每格返回 source/host 绑定、实际最终输入与恢复补读、原生任务成果、完整成本及 +integrity 状态,保留失败或截尾尝试。Board 表达 run 资格,本身不证明因果比较,也不 +授权启动。 + +上述原生 adapter 范围是 Codex,**不证明 DeepSeek 宿主已支持**。DeepSeek 对照需要 +获授权且已资格化、能经过同一语义管线的宿主。不支持保持缺口,不能替换成 Codex +结果或修改在跑研究。 + +| 效果 | 完整适用成本 | +| --- | --- | +| 独立任务验收/成功率或原生任务指标 | 实际 input/output、cached/uncached tokens,披露压缩/请求覆盖 | +| 约束遗漏、错误动作和证据采用 | 模型/工具请求、详情补读、重试与恢复 | +| 恢复、避免重复效果、可用交付物 | 墙钟、适用尾延迟、快照/hash/IO、搭建与维护 | +| 后续工作实际采用修订 | 人工决策、导航、介入与注意力 | + +按原任务排名规则:以历史最佳排名的优化任务,不能拿终点源码分数替换它;适用的 +终态产物/保留事实另列。未知成本不记零。评测完成至收集反馈之间可能仍在独立验证, +须测量重叠后再判断空等;更少调用或字节可以与更差的验收成果同时发生。 + +已有[打包来源对照](../architecture/rfcs/ledger/controller-executor-unified-contract-v0/2026-10-29-packaged-source-comparison.zh-CN.md) +提供真实 CLI、来源和恢复证据,也保留了更大的冷态/累计输出。复用它已验的范围, +不转写成模型节费。冷启动、小任务、丢基线和某个模型退步,都是广泛默认建议的必要 +反例场景。 + +### 发布与删除分开决定 + +| 阶段 | 退出证据与 owner | +| --- | --- | +| 讲清当前行为 | 指南/reference 与真实 caller 一致,文档 owner 保留提案/实现区别 | +| 双模型比较 | Benchmark owner 记录固定条件、验收成果、成本、不确定性与不支持范围 | +| 采用受支持 profile | Runtime/host owner 验实际打包旅程与可回退配置,维护者决定发布范围 | +| 建议扩大默认 | 两模型证据支持该声明范围;混合/退步时保留范围化 opt-in 或明确限制 | +| 退役旧路径 | Caller owner 核替代、历史读取兼容、支持版本/回退覆盖及不再有活跃消费者 | + +退役须点名实际 producer、consumer 与替代项。调用方迁移后删除重复判断算法,与删除 +历史 decoder 是两件事。完整快照、摘要校验、权限/身份/停止验证和必要恢复应保留。 +显式 retained-input 客户端与原生文件基线客户端是不同兼容义务。既不长期保留两套 +同义决策 owner,也不因新路径存在就抢先删除仍受支持的 reader。 + +[Roadmap](../architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md#统一契约与-controllerexecutor-交付) +与 RFC 继续拥有 C1/C2/C9 的负责人和未闭工作。文档可以先于模型实验交付;指南合并 +或 packet 变小,都不结清运行时、实际采用与收益要求。 diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index aea9943c75..7f3f62f898 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -1,5 +1,9 @@ # Required work context +For a task example, supported setup, recovery and evaluation plan, start with the +[context-delivery guide](../guides/context-delivery.md). This reference remains +the owner of current delivery semantics. + 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 @@ -651,6 +655,9 @@ all-Goal adoption, actual solver costs or outcome benefit. ## 中文 +任务示例、受支持设置、恢复与验收方案见[上下文交付指南](../guides/context-delivery.zh-CN.md)。 +当前交付语义仍由本 reference 定义。 + 本页规定当前交付行为。[统一契约提案](../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md) 拟让所有入口复用 full/delta/detail/recovery 流程。controller 编写的工作说明必须 保留完整原始要求与可访问证据;实验性模型 token 目标不允许截断,也不替代来源读取义务。