diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index c5fd28ec73..ba739fedeb 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -150,14 +150,15 @@ Paired diffs do not certify translation accuracy. transfer, stale-owner races, PostgreSQL authority, successor scheduling and App/Lark delivery need separate qualification; no new runtime or state writer. -- [Monorepo Distribution Split v0](monorepo-distribution-split-v0.md) +- [Monorepo Distribution and Small-Kernel Runtime Composition v0](monorepo-distribution-split-v0.md) ([中文版](monorepo-distribution-split-v0.zh-CN.md)) - **Delivery on `main`:** Proposal only; tracking [#5072](https://github.com/loopx-project/loopx/issues/5072). - - **Current boundary:** Keeps one repository; splits the installed wheel into - `loopx-core`, `loopx-workspace` and `packages/` capability distributions, - regroups `loopx/` top-level modules with compatibility shims, and pins the - top-level module count with an architecture test. No kernel semantics, - licence or schema change; multi-repository split remains a non-goal. + - **Current boundary:** One design for directory ownership, `loopx-core` / + `loopx-workspace` / optional distributions, and minimal/standard runtime + composition over one governance implementation. Preserves import + compatibility and adds demand-loading, activation, context, managed-task + recovery and matched product/benchmark qualification. Original packaging + milestones and decisions remain; no runtime, default, licence or schema change. - [Automatic Execution Admission v0](automatic-execution-admission-v0.md) ([中文版](automatic-execution-admission-v0.zh-CN.md)) diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 6fac57113c..035ecd07c1 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -31,7 +31,7 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Capable Agent Manager and Semantic Work Handoff (v0)](capable-manager-semantic-handoff-v0.md) | Accepted | [Personal Follow-through independent proposal](personal-follow-through-v0.md) | [2 entries](ledger/capable-manager-semantic-handoff-v0/) | | [RFC: Complete State Recovery and Controlled Reactivation (v0)](complete-state-recovery-v0.md) | Accepted | none | — | | [RFC: Composable State Machines and Recovery Verification (v0)](composable-state-machines-recovery-verification-v0.md) | Accepted | none | — | -| [RFC: Controller / Executor Sessions and One Governed Work Contract (v0)](controller-executor-unified-contract-v0.md) | Accepted | none | [3 entries](ledger/controller-executor-unified-contract-v0/) | +| [RFC: Controller / Executor Sessions and One Governed Work Contract (v0)](controller-executor-unified-contract-v0.md) | Accepted | none | [4 entries](ledger/controller-executor-unified-contract-v0/) | | [Explicit Todo continuation: Stage A](cross-session-memory-substrate-v0.md) | Accepted | none | — | | [RFC: LoopX Desktop Execution Frontends v0](desktop-execution-frontends-v0.md) | Accepted | none | — | | [RFC: External Evidence Research Capability v0](external-evidence-research-capability-v0.md) | Accepted | none | [3 entries](ledger/external-evidence-research-capability-v0/) | @@ -56,7 +56,7 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Long-Running Agent Reliability Diagnostics and Governed Delivery v0](long-running-agent-reliability-diagnostics-governed-delivery-v0.md) | Accepted | none | — | | [LoopX Overall Roadmap v0: Product, Collaboration, Technology and Delivery](loopx-overall-roadmap-v0.md) | Accepted | none | [1 entry](ledger/loopx-overall-roadmap-v0/) | | [Manager runtime profile v0](manager-runtime-profile-v0.md) | Accepted | none | — | -| [RFC: Monorepo Distribution Split (v0)](monorepo-distribution-split-v0.md) | Accepted | none | — | +| [RFC: Monorepo Distribution and Small-Kernel Runtime Composition (v0)](monorepo-distribution-split-v0.md) | Accepted | none | — | | [RFC: Obelisk Session Evidence Provider v0](obelisk-session-evidence-provider-v0.md) | Accepted | none | — | | [RFC: Agent Judgment and Optional Independent Assessment — Jev as a Candidate (v0)](optional-semantic-assistance-jev-v0.md) | Accepted | none | — | | [RFC: Post-Outcome Memory Utility Attribution v0](post-outcome-memory-utility-attribution-v0.md) | Accepted | none | — | diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index 51a81ad3e6..a0b1ad1601 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -28,7 +28,7 @@ | [RFC：强能力 Agent 管家与语义工作交接（v0）](capable-manager-semantic-handoff-v0.zh-CN.md) | 已接受 | [个人事项持续跟进独立提案](personal-follow-through-v0.zh-CN.md) | [2 条](ledger/capable-manager-semantic-handoff-v0/) | | [RFC：完整状态恢复与受控重新激活（v0）](complete-state-recovery-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：可组合状态机与恢复验证（v0）](composable-state-machines-recovery-verification-v0.zh-CN.md) | 已接受 | 无 | — | -| [RFC：Controller / Executor 会话与统一受治理工作契约（v0）](controller-executor-unified-contract-v0.zh-CN.md) | 已接受 | 无 | [3 条](ledger/controller-executor-unified-contract-v0/) | +| [RFC：Controller / Executor 会话与统一受治理工作契约（v0）](controller-executor-unified-contract-v0.zh-CN.md) | 已接受 | 无 | [4 条](ledger/controller-executor-unified-contract-v0/) | | [显式 Todo 接续：阶段 A](cross-session-memory-substrate-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：LoopX 桌面执行前端 v0](desktop-execution-frontends-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：外部证据研究能力 v0](external-evidence-research-capability-v0.zh-CN.md) | 已接受 | 无 | [3 条](ledger/external-evidence-research-capability-v0/) | @@ -53,7 +53,7 @@ | [RFC：长程 Agent 可靠性诊断与治理交付 v0](long-running-agent-reliability-diagnostics-governed-delivery-v0.zh-CN.md) | 已接受 | 无 | — | | [LoopX 整体路线总纲 v0：产品、协作、技术与交付](loopx-overall-roadmap-v0.zh-CN.md) | 已接受 | 无 | [1 条](ledger/loopx-overall-roadmap-v0/) | | [Manager runtime profile v0 / 管家运行模式 v0](manager-runtime-profile-v0.zh-CN.md) | 已接受 | 无 | — | -| [RFC：Monorepo 内的发行物拆分（v0）](monorepo-distribution-split-v0.zh-CN.md) | 已接受 | 无 | — | +| [RFC：Monorepo 发行拆分与小内核运行时装配（v0）](monorepo-distribution-split-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：Obelisk Session Evidence Provider v0](obelisk-session-evidence-provider-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：Agent 判断与可选独立评估——以 Jev 为候选方案（v0）](optional-semantic-assistance-jev-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：结果后记忆效用归因 v0](post-outcome-memory-utility-attribution-v0.zh-CN.md) | 已接受 | 无 | — | diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 4491ef8fa3..6a4b46ff83 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -1,11 +1,11 @@ -# RFC: Monorepo Distribution Split (v0) +# RFC: Monorepo Distribution and Small-Kernel Runtime Composition (v0) -- **RFC status:** Accepted, proposal only (open decisions D1–D4 remain unapproved) +- **RFC status:** Accepted, proposal only (open decisions D1–D7 remain unapproved) - **Delivery maturity:** Proposal - **Authors / owners:** LoopX maintainers - **Created:** 2026-09-26 -- **Last normative revision:** 2026-10-22 -- **Implementation baseline:** `2f3d13ae9` +- **Last normative revision:** 2026-10-29 +- **Implementation baseline:** packaging inventory `2f3d13ae9`; runtime composition audit `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` - **Related contracts:** [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md), [Extensions reference](../../reference/extensions.md), [Capability catalog](../../../loopx/capabilities/README.md), [Overall Roadmap v0](loopx-overall-roadmap-v0.md) (S2, S8, S12), [import-boundary tests](../../../tests/architecture/test_control_plane_import_boundaries.py) - **Tracking issue:** [#5072](https://github.com/loopx-project/loopx/issues/5072) - **Supersedes / closes:** none @@ -19,6 +19,12 @@ are not approval. Appendices are non-normative. This RFC ships an English document and a `.zh-CN.md` semantic mirror; a difference between them is a defect. +This is the single design for directory ownership, installable distributions +and runtime composition. Its original filename and tracking issue remain +stable. Merge accepts a design basis; it does not establish runtime delivery, +performance, host qualification or a new default. Historical measurements below +retain their original baselines. + --- ## 1. Decision summary @@ -45,11 +51,23 @@ defect. 7. **Not approved here:** graduating any package to its own repository, changing licences per package, or reducing any schema. +The distribution tiers compose **one governance implementation** into minimal +and standard presets. Minimal must execute and recover a real governed task; +standard adds the product composition around the same kernel. A research +configuration freezes one of these compositions plus declared experimental +changes, without becoming a third governance implementation. + +Smallness is measured separately in installed dependencies, loaded code, +activated services and model-visible context. The package table defines what +can be installed, not what every command must load. Installing standard grants +no service activation or permission. Existing defaults and machine-enforced +work obligations remain until a qualified, explicitly disclosed migration. + ## 2. Problem and motivation A developer who wants a CLI-only or kernel-only LoopX installs the same wheel as someone running the desktop workspace, the Lark manager, and every built-in -capability. On the baseline: +capability. Historical packaging inventory on `2f3d13ae9`: | Fact | Baseline value | | --- | --- | @@ -85,6 +103,27 @@ The owners of these surfaces cannot fix this locally: a capability author cannot decide the kernel's packaging, and the kernel cannot decide which capabilities are optional without a repository-level rule. +Directory and package changes also need an execution contract. A short CLI read +should not initialize a research stack or IM service; an embedded managed task +should not require an interactive App. Smaller installed code alone does not +prevent eager imports, idle polling or excessive context on every model call. +Section 9 therefore qualifies both structural moves and useful task journeys. + +The design must support these observable journeys: + +| Journey | Required outcome | Composition implication | +| --- | --- | --- | +| Bounded managed task | Start without an interactive App, execute, settle and read back the result | Minimal includes one qualified host path and durable authority | +| Long-horizon research | Produce a useful first result, then evidence-backed revisions or new outcomes as work continues | Optional planning, research and memory strategies; progress is more than elapsed time or repeated summaries | +| Two or three cooperating peers | Return evidence to the coordinator, record adoption, recover ownership after interruption | Reuse shared work/lease authority; peer lifetime and result adoption are distinct | +| App or IM request | Pause, correct, resume and receive the accepted result at the original destination | Frontends and delivery providers compose around the same work identity | +| Hardware or external operations | Execute several steps, reconcile uncertain effects, and verify stopping at the relevant boundary | An explicitly activated operation provider owns readback, interlocks and safe retry | +| Reproducible benchmark | Compare qualified product compositions with native controls and complete costs | Freeze experiment inputs; keep native runner, verifier and scoring ownership | + +These are shared product requirements, not a commitment to ship every journey +or every combination at once. Content, office and engineering capabilities +use the same boundaries without becoming mandatory startup dependencies. + ### Invariants - I1. One repository, one PR, one CI run for any cross-package change. @@ -103,6 +142,15 @@ are optional without a repository-level rule. diagnostic. - I6. No public/private boundary rule, schema field, or licence changes as a side effect of a move. +- I7. Unselected optional components do not initialize, register timers/hooks, + use the network or inject model instructions. Missing execution prerequisites + fail before dispatch instead of falling back to ungoverned execution. +- I8. Required context remains complete and fresh; smaller prompts cannot drop + requirements, required reads or stop conditions. Replay reconciles durable + identities and external evidence before retry. +- I9. Performance and outcome claims name the measured composition, baseline, + environment and scope. File-count reduction and faster help do not establish + better task outcomes. ## 3. Scope and non-goals @@ -116,6 +164,8 @@ are optional without a repository-level rule. `CapabilityRegistry` provider boundary. - Optional-extra or bundled delivery of the Node effect runtime for `loopx-core`. +- Minimal/standard composition, demand loading, activation, context boundaries + and matched product/benchmark qualification using the same typed owners. ### Non-goals @@ -125,6 +175,9 @@ are optional without a repository-level rule. - Any change to kernel semantics, TS migration order, or stable protocols. - Removing legacy compatibility facades (`loopx.status`, `loopx.quota`); their retirement stays governed by the migration RFC. +- A new model loop, scheduler, plugin system, memory database, benchmark-native + runner, storage migration, device framework or mandatory daemon. No benchmark + run, device operation or host promotion is authorized by this proposal. ## 4. Current-system contract @@ -148,6 +201,25 @@ Facts audited on `2f3d13ae9`: contract while an extension is a delivery unit. This RFC applies that rule to the kernel wheel itself. +Runtime composition audit on `9cae3b28939f72fa4aadab5cfe49e19bcbdab372`: + +- [entrypoint.py](../../../loopx/entrypoint.py) has a small version path and + selected native scheduler follow-ups. [cli_runtime.py](../../../loopx/cli_runtime.py) + dispatches selected commands and retains a full-parser fallback. + `performance-diagnosis` is registry-optional but outside the selected-command + set: a bounded loading seam, not proof all startup is lazy. +- The [unified controller/executor RFC](controller-executor-unified-contract-v0.md) + owns the governed work contract; [session modes](agent-session-execution-modes-v0.md) + own managed/attached admission; [DSH/Pi selection](harness-selection-dsh-pi-v0.md) + owns host qualification. Composition reuses these contracts. +- [Benchmark toolkit](../../../loopx/capabilities/benchmark_toolkit/README.md) + owns reusable permissions, concurrency and integrity. [Benchmark policy](../../../benchmark/README.md) + keeps native execution/evaluation with the benchmark; no second launcher is restored. +- The [three-layer protocol](../../reference/protocols/multi-agent-three-layer-minimality-v0.md) + uses “kernel” for a broader reusable layer. Here, governance kernel names the + authority boundary and boot closure names a selected entrypoint's required code. + A reusable runner or presentation facility need not enter every boot closure. + ## 5. Proposed architecture ### Ownership and authority @@ -159,11 +231,60 @@ Facts audited on `2f3d13ae9`: | `loopx-capability-` (in `packages/`) | one capability's contract, providers, CLI subcommands, docs | Capability owner from CODEOWNERS | `loopx-core`; optionally other capability packages | | `loopx` (meta) | no code | Release owner | all of the above, pinned to one release train | +This is an installation layout. CLI handlers and host facilities inside +`loopx-core` are not thereby part of every startup dependency closure. Optional +provider distributions keep the existing `packages//` convention; +the capability-package row does not require one capability per provider. + Authority does not move: the kernel remains the only writer of Goal/Todo/claim/ lease/quota/effect state. A capability package may only register providers, capability contracts and CLI subcommands through `CapabilityRegistry`; it never imports kernel-private modules. +### Governance and runtime ownership + +| Boundary | Existing owner and responsibility | Excluded responsibility | +| --- | --- | --- | +| Bootstrap | Entrypoint/CLI routes resolve commands and installed metadata | Goal decisions or provider activation during discovery | +| Governance kernel | Typed Goal, work, quota, runtime and coordination owners: requirements, admission, lease, budget, stop, effect, receipt, settlement and recovery | Model/tool loop, task strategy, UI, transport or scoring | +| Host | Admitted managed/attached provider: model/tools, session lifecycle and observations | A second work ledger or independent permission authority | +| Capability strategy | Nearest outcome owner: planning, context selection, research, recall and review | Overriding mandatory transitions, leases, stop or budget | +| Extension and product surface | Existing lifecycle/registry; frontends and delivery providers consume public-safe projections and submit commands | New plugin machinery or deriving authority from display/private source text | + +Placement introduces no capability or provider id: governance remains in +`control_plane`, generic lifecycle in `extensions`, task behavior in its nearest +capability, and optional distributions in `packages/`. Keep new domain-neutral +rules in the existing typed TypeScript owner; Python may adapt but must not +reimplement state rules. A new capability needs an independently useful +provider-neutral caller contract. A real host/device integration owns its +provider-specific execution and recovery, without creating a generic framework. + +A planner can recommend work or stride; the owning transition decides admission +and obligations. Presets cannot turn a machine-enforced `must_attempt_work` +contract into prose guidance. The kernel is a cohesive set of domains, not one +large file. The adjacent refactor should localize the next change and preserve +characterized behavior. + +### Presets over the distribution tiers + +| Composition | Required content | Explicit optional content | +| --- | --- | --- | +| Minimal | Bootstrap, same governance implementation, one supported authority provider, one qualified execution path, compact status/result readback and recovery | Task capabilities, persistent recall, observers, connectors, workspace UI | +| Standard | Same kernel and compatible ordinary-product composition | Load/activate only the capabilities, hosts, UI/IM services and connectors required by the chosen workflow | +| Research configuration | Pinned minimal or standard composition plus a declared experiment overlay | Only instrumentation or ablations named in the experimental design | + +The `loopx` meta-package retains installation compatibility; installed standard +content is not an activation list. Minimal is an executable composition, not a +flag applied after standard fully initializes. A host-free read-only kernel +library does not qualify that executable preset. Exact contents and the first +supported host/authority combination are D2/D5 decisions. + +Keep composition, managed/attached mode, host provider, one/two model sessions, +storage provider and benchmark arm independent. Minimal does not imply attached, +standard does not require two model sessions, and research does not mean +ungoverned. Publish only tested combinations and preserve existing mode defaults; +changing composition must not silently change a binding's execution owner. + ### Supported host integration decision Separately installed `generic-cli` host transports consume the existing Turn @@ -245,6 +366,81 @@ features. The kernel-caller inventory is the 52 import sites named in Section 2; each one is either retargeted to a registry lookup or documented as a retained core capability (D2). +### Demand loading and context + +1. **Resolve:** read local versioned metadata generated at build/install or + explicit extension registration. Top-level help, command listing and unknown + command rejection must not scan repositories, import every provider or use + the network. Duplicate registrations and stale/incompatible metadata are + reported; precedence is explicit, never import-order dependent. +2. **Load:** import the selected command and its dependency closure. Detailed + command help may load its own parser, but not activate execution services. + Optional imports stay behind their owning route, including fallback paths. +3. **Activate:** validate installed/enabled/ready state and scoped permissions, + then start required services through their existing lifecycle owner. Missing + optional code reports how to install/enable it. Missing required authority + or runtime fails closed. Kernel import/help must not require Node; effectful + commands retain this RFC's typed `node_unavailable` boundary. +4. **Provide context:** render the existing governed work contract for the + selected work and executor. Reuse full-first, differential continuation and + recovery semantics from the unified controller/executor design. Required + reads and source completeness remain binding. + +Context reuse must be invalidated by relevant source/requirement revisions, +session generation changes, compaction or lost acknowledgements. A smaller +packet cannot be treated as proof the executor has the prior context. Recover +through the owning contract when continuity is unknown. Capability instructions +are supplied when applicable; authority is never inferred from prompt text. + +Optional observers consume committed events or bounded projections. Their +latency must not enter admission/settlement transactions unless the existing +contract explicitly requires their receipt. Batch best-effort telemetry only; +do not defer authoritative receipt persistence, weaken fsync/transaction +guarantees or cache stale permission/lease decisions to meet a timing target. + +### Governed lifecycle and external effects + +Use existing Goal/Agent/work/Turn identities, revisions, leases, effect ids and +receipts through the unified work contract. Resolve composition, verify +requirements and authority, admit work, execute through the bound host, validate +and persist evidence, settle once, then deliver/read back through the owning +channel. Each step uses its existing legal transitions and replay rules; +this description adds no competing status enum or transaction coordinator. + +An executor crash, a lost effect acknowledgement and a lost result-delivery +acknowledgement are different recovery cases. An operation provider must expose +whether an effect can be reconciled and retried safely. Unknown external state +holds further dependent effects for readback or intervention; “not observed” +does not mean “not executed.” Device idempotency, physical interlocks and +compensation remain provider responsibilities, not invented kernel guarantees. + +Model cancellation, process termination and confirmed device stop are separate +facts. A stopped model must not produce a “device stopped” claim without device +evidence. Providers needing persistent supervision cannot be unloaded while +effects are unresolved. Result acceptance, transport delivery and the user's +readback must also retain their existing distinct evidence. + +### Product and benchmark execution + +Follow the [long-horizon research program](long-horizon-harness-benchmark-research-program-v0.md): +native/plain controls, passive observation, governed execution and ablations +have explicit identities. A native control receives no LoopX instructions or +hooks. Passive observation must qualify non-interference. Governed arms use +the same qualified composition and transitions as product tasks; an ablation +that changes governance is a named experimental variant, never a product default. + +Freeze product/host versions, resolved composition, model and sampling settings, +skills/tools, initial state, budget, checkpoint/recovery policy, dataset and +verifier versions. Scope memory by run/arm and prohibit cross-arm contamination. +Report controller, executor, compaction, retry, recovery and human-intervention +costs as well as task outcomes. Native runners/verifiers retain task semantics +and scoring. Performance work cannot bypass toolkit permission/integrity checks +or publish raw tasks, trajectories or verifier logs as public product evidence. + +Long-horizon product qualification additionally needs evidence that later work +improves an already useful initial result or changes a decision. Deliberately +weakening the initial result, adding more text or running longer is not progress. + ## 6. Alternatives and design choices | Alternative | Why not chosen now | @@ -253,6 +449,22 @@ retained core capability (D2). | **Keep one wheel, add extras only** | Reduces install weight but leaves the flat namespace and the two packaging conventions in place; contributors still cannot find boundaries. | | **Move everything to `packages/` at once** | Breaks I3 for many callers simultaneously and mixes behavioural risk into a structural change. Per-group moves with I3 compatibility are cheaper to review and to roll back. | | **Bundle Node into `loopx-core` unconditionally** | Solves I5 but makes the kernel wheel platform-specific and large. Kept as option D1 alongside the optional-extra approach. | +| **Separate minimal and standard engines** | Duplicates state transitions and breaks product/benchmark parity. | +| **Make every governance rule a plugin** | Budget, stop, lease and settlement could disappear with a preset. | +| **Use an upstream agent runtime as the LoopX kernel** | Model execution can be a host provider; it does not replace LoopX work authority. | +| **Require one daemon or remote service for every composition** | Adds lifecycle and deployment cost to bounded local use; any optional daemon remains under its existing contract. | + +Pi demonstrates a small agent core with tool/event execution and explicit +context transformation separate from the coding product. DSH demonstrates +shared runtime composition through multiple presets and a self-contained +minimal SDK bundle. At the pinned revision, DSH web minimal and standard use +the same agent-preset package with different plugin lists; minimal includes +persistent shell, image reading and compaction. Its SDK minimal also supplies +working-directory state and persistence with optional configured MCP resources. +These are composition examples, not evidence that DSH has exactly two engines +or that LoopX's headless adapter and DSH plugin correspond to those presets. +Borrow the explicit boundaries, without adopting Cordis, upstream permission +defaults or a new LoopX model loop. Pinned sources are in Appendix C. ## 7. Safety, privacy, and compatibility @@ -269,6 +481,15 @@ retained core capability (D2). - **Fail-closed:** an effectful command without the runtime extra fails with `node_unavailable`; it never proceeds without the TS kernel. +Host availability, installation and capability declarations are observations, +not grants. Preserve Goal/Agent/workspace/delivery scope through provider calls. +No required context or stop/budget rule becomes optional with a preset. +Unmigrated CLI routes retain fallback until parsing, global options, output, +errors and exit codes qualify; incompatible versions fail before dispatch. +Retire the full parser only after every supported command has migrated and +help and diagnostic parity pass. Never run two writers against one binding +to make a mixed-version rollout appear available. + ## 8. Migration and rollback | Step | Gate | Rollback | @@ -280,8 +501,15 @@ retained core capability (D2). | Capability package moves | per capability, kernel-caller inventory resolved | revert one package | | Shim removal | one minor release after the move; deprecation recorded in update notes | not applicable; requires migration by callers | -Rollback requires no data migration at any step because no canonical record -changes. +Before changing an active binding's composition, check compatibility, quiesce +its execution owner and reconcile outstanding effects. Verify the new owner +and resolved composition before resuming; never hot-swap across an active +lease. Rollback uses the same reconciliation and retains durable state. +Any later irreversible data change needs a separate migration/export gate. + +Rollback of these structural/composition changes requires no data migration. +Default changes need explicit owner decisions and release notes; this proposal +changes no current default. ## 9. Validation and acceptance @@ -295,8 +523,33 @@ changes. | No kernel truth duplicated | import-boundary tests + review of `packages/*/src` for kernel-private imports; interim guard: `tests/architecture/test_package_kernel_import_ratchet.py` pins every `loopx.*` import under `packages/*/src`, fails on an unreviewed new edge, and requires a retired edge to lower the pin in the same PR | zero private-kernel violations | Static imports only. The 13 pre-existing edges in Ark, Finance and JEV remain tracked migration debt, separate from MemT's 2 supported public integration imports. A green ratchet does not retire that debt or establish this row; supported public edges need not disappear | | Meta-package parity | `pip install loopx` then existing full smoke | identical to pre-split smoke | — | -Deterministic conformance rows above are required for each milestone; no live -qualification or performance claim is made by this RFC. +The seven structural rows above remain required for their move/package +milestones. Runtime and journey qualification adds the following rows. + +These rows are proposed acceptance criteria, not claims of passing evidence. +Deterministic fixtures cover semantics independently of observed implementation +output. Live, performance and promotion evidence are reported separately. + +| Id / claim | Test or evidence | Required result | Boundary | +| --- | --- | --- | --- | +| V1 / demand loading | Import/process/network tracing for import, help, listing, unknown command and a selected route, under both presets | Only declared dependency closure; no optional activation | Does not prove execution performance | +| V2 / authority parity | Characterization and negative tests for requirements, stale claims, stop, budget, replay and settlement | Identical legal/illegal transitions in both presets, exactly one settlement | No authority bypass in minimal | +| V3 / CLI compatibility | Differential supported-command corpus, including fallback and missing Node/provider cases | Stable parsing, output contract, exit codes and actionable failures | Unmigrated routes are explicitly listed | +| V4 / managed minimal | One real managed task, injected interruption, restart, evidence validation and result readback | Same identity and reconciled effects; no duplicate dispatch of confirmed work or settlement; recovery costs recorded; accepted result reachable | One qualified host is enough initially; mock-only execution is insufficient | +| V5 / context continuity | Initial context, unchanged continuation, source revision, compaction and lost-ACK cases | Complete required context or explicit recovery; stale context rejected | Token reduction measured separately | +| V6 / standard journey | Original App/IM request, correction/pause, resume, completion and return | One execution owner; visible accepted result and costs; no silent destination change | Each frontend/provider qualifies separately | +| V7 / research and peers | Useful initial result followed by evidence-backed improvement; peer result return and adoption after owner recovery | New outcome or justified decision revision with attributable evidence | More time, peers or prose alone cannot pass | +| V8 / benchmark fidelity | Frozen matched runs, native/passive/governed boundaries, memory isolation and full cost ledger | Native semantics intact; C0–C4 evidence follows the research/diagnostics owners | No score or causal benefit is claimed by this RFC | +| V9 / physical effects | Simulator/fault injection, then explicitly authorized provider-specific live qualification | Lost ACK reconciled, duplicate actuation prevented where guaranteed, device stop independently confirmed | No universal exactly-once or emergency-stop guarantee | +| V10 / overhead | Repeated paired cold-process and warm-path measurements on a named environment | Report median/p95, RSS, modules, file I/O, Node startup/IPC, bytes and model tokens; no durability regression | R0 sets numeric budgets; no paid task run required for CLI baselines | + +Candidate local-development targets are import below 50 ms, top-level help below +100 ms and selected command help below 200 ms at p95. They are D6 proposals, +not verified results or portable CI thresholds. Define interpreter startup and +cache conditions, sample count and machine/runtime versions before adopting +them. Measure real status/admission/settlement latency separately on +representative small and large state, including SQLite contention/recovery; +do not apply a CLI-help target to those operations or subtract their required I/O. ## 10. Operational contract @@ -307,16 +560,35 @@ qualification or performance claim is made by this RFC. - Release notes name public import moves and each retained shim’s expiry release. - No new daemon, storage or network surface is introduced. +Readback also names the resolved composition/versions, selected host and +session mode, required versus optional providers and why a component loaded. +Reuse current diagnostics/projections; do not add a status database. Distinguish +missing prerequisites, stale authority and uncertain effects. Record startup +and Turn overhead separately; observer failure does not rewrite committed +results, while required evidence/delivery receipts remain governed by their +owner. Capacity/backpressure and recovery retain existing work/host contracts. + ## 11. Normative delivery plan | Milestone | Shipped behavior | Entry gate | Exit evidence | Rollback | | --- | --- | --- | --- | --- | -| M0 | Budget fixture and test at the current count; RFC index entry | this RFC accepted | budget test green; count pinned | delete test | +| M0 | Budget fixture and test at the current count; RFC index entry | this RFC accepted; remeasure the fixture baseline | budget test green; count pinned | delete test | +| R0 | Characterized `performance-diagnosis` selected route and measured loading seam | Current route/owner/dependency map; D6 measurement decision; independent of package publication | V1/V3 for this route, V10 baseline; unchanged behavior | Revert route extraction | | M1 | `loopx/chat_*` → `loopx/chat/` with I3 compatibility; budget lowered by net reduction | M0 | Section 9 rows 1–2 | revert | | M2 | `loopx/*_goal_mode` → `loopx/hosts/` with I3 compatibility | M0 | rows 1–2 | revert | -| M3 | `loopx-core` + `loopx-workspace` + meta `loopx` published as pre-release; Node as extra or bundle per D1 | M1, M2; D1 decided | rows 3–4, 7 | unpublish pre-release | +| M3 | `loopx-core` + `loopx-workspace` + meta `loopx` published as pre-release; Node as extra or bundle per D1 | M1, M2; D1 decided; selected D2/D5 composition mapped | rows 3–4, 7; repeat qualified R1/R2 journeys against clean split-package install | Unpublish pre-release | +| R1 | Opt-in executable minimal with one real managed Turn, restart and result readback | R0; selected D2 contents and D5 host/authority; may qualify source composition before M3 | V1–V5/V10 for the supported combination; source evidence alone does not qualify split-package installation | Return to previous qualified composition after reconciliation | +| R2 | Standard uses the same kernel and activates one chosen product workflow | R1; existing frontend/session admission; may qualify source composition before M3 | V2/V5/V6/V10 and feature-off parity; repeat cold-install journey at M3 before claiming split-package qualification | Disable opt-in composition, retain state | | M4 | First capability without kernel callers moved to `packages/` | M3; D2 inventory | rows 5–6 | revert package | | M5 | Remaining eligible capabilities moved; public shims from M1/M2 removed after the documented compatibility window | M4 | full smoke identical | not applicable | +| R3 | Matched product-path benchmark and a long-horizon/peer journey | R1 or R2 for the selected surface; frozen design and separate run authorization | V7/V8, complete costs, privacy and existing C0–C4 qualification | Retire experimental overlay, retain bounded evidence | +| R4 | One real external-operation provider with reconciliation and stop readback | D7; named operation owner and explicit operation authorization | V9 plus inherited governance gates | Quiesce/reconcile before disabling | + +M0–M5 retain the original distribution milestones; R0–R4 are their runtime and +journey qualification slices in this same plan. R0 can ship before directory +moves; it does not qualify the kernel. R3/R4 are optional and do not block a +qualified CLI or managed task. No unused provider, field or framework is added +ahead of its real caller. Report the applied/deferred adjacent refactor in each PR. ## 12. Open decisions @@ -328,7 +600,10 @@ qualification or performance claim is made by this RFC. 2. **D2 — Which capabilities remain in core.** Owner: kernel + capability maintainers. Input: the 52 kernel-side import sites. Recommendation: keep only capabilities that the Turn driver, quota or heartbeat prompt require at - runtime; everything else is a package. Deadline: before M4. + runtime; everything else is a package. Resolve accidental eager imports + through the registry rather than treating their existence as proof of core + need. Record exact install/load/activation closures for minimal and standard. + Deadline: selected composition before R1/M3; full inventory before M4. 3. **D3 — Shim lifetime.** Owner: release owner. Options: one minor release (recommended) or two. Deadline: M1. 4. **D4 — Index placement.** Whether this RFC is listed under "Control-Plane @@ -336,6 +611,24 @@ qualification or performance claim is made by this RFC. Integration". Recommendation: kernel section, since the budget test and `loopx-core` boundary are kernel-owned. +5. **D5 — First executable composition.** Owner: runtime/host and authority + maintainers. Choose the exact minimal host/storage combination and standard + mapping under the existing package scheme. Recommend opt-in minimal and + the smallest already qualified managed path, retaining current defaults. + DSH/Pi qualification stays with its selection RFC. Evidence: V4 recovery and + session continuity before R1 exit, package readback before M3. +6. **D6 — Performance budgets.** Owner: performance maintainers. Choose + machine-specific p95 budgets or relative regression limits; recommend the + Section 9 candidate budgets with explicit process/cache/sample conditions. + Evidence: reproducible R0 baseline; derive real Turn budgets independently. +7. **D7 — External operation caller.** Owner: operation-provider maintainer. + Choose one concrete caller or defer physical qualification. Recommend no + device framework before a real caller. Scope, idempotency/readback/stop + contract and operation authorization are required before R4. + +The added recommendations do not close D1–D4 or approve any new default. +Approval needs a reviewed decision, not implementation progress or silence. + --- ## Appendix A: Execution ledger (non-normative) @@ -416,6 +709,9 @@ qualification or performance claim is made by this RFC. | E1 | 148 top-level modules | `2f3d13ae9` | `ls loopx/*.py \| wc -l` | 148 | counts files, not public API | | E2 | 52 kernel-side capability imports | `2f3d13ae9` | `rg -l "loopx\.capabilities\|from \.\.capabilities\|from \.capabilities" loopx/control_plane loopx/cli_commands loopx/*.py` | 52 | static imports only | | E3 | 80 capability → control_plane imports | `2f3d13ae9` | `rg -l control_plane loopx/capabilities` | 80 | includes docs strings; upper bound | +| E4 | Selected CLI loading seam | `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` | Linked entrypoint/CLI in Section 4 | Source-audited | No new timing claim | +| E5 | DSH composition example | Pinned upstream commit | [`minimal.patch.yml`](https://github.com/deepseek-ai/deepseek-harness/blob/f3803c96974ad4a94195fb97e5c637e9c2a3afe3/packages/bundle/web-app/presets/minimal.patch.yml), [`standard.patch.yml`](https://github.com/deepseek-ai/deepseek-harness/blob/f3803c96974ad4a94195fb97e5c637e9c2a3afe3/packages/bundle/web-app/presets/standard.patch.yml), [`sdk-minimal`](https://github.com/deepseek-ai/deepseek-harness/blob/f3803c96974ad4a94195fb97e5c637e9c2a3afe3/packages/bundle/sdk-minimal/README.md) | Source-audited | Shared preset composition and a self-contained SDK bundle; not a LoopX host qualification or permission recommendation | +| E6 | Pi core/context example | Pinned upstream commit | [`agent` core](https://github.com/badlogic/pi-mono/blob/f14813e96510a7cf7562a120e809c6a134af073d/packages/agent/README.md) | Source-audited | Agent/tool/event core with `transformContext`, `convertToLlm`, `prepareRequest` and `finishTurn` seams; no LoopX authority or performance claim | ## Appendix D: Rejected or superseded alternatives diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md index 30f3f828a4..9d64e1d4d2 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -1,11 +1,11 @@ -# RFC：Monorepo 内的发行物拆分（v0） +# RFC：Monorepo 发行拆分与小内核运行时装配（v0） -- **RFC 状态：** 已接受（仅提案；第 12 节 D1–D4 未决，合并不等于批准） +- **RFC 状态：** 已接受（仅提案；第 12 节 D1–D7 未决，合并不等于批准） - **交付成熟度：** Proposal - **作者 / 负责人：** LoopX maintainers - **创建：** 2026-09-26 -- **最近规范性修订：** 2026-10-22 -- **实现基线：** `2f3d13ae9` +- **最近规范性修订：** 2026-10-29 +- **实现基线：** 发行盘点 `2f3d13ae9`；运行时装配审计 `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` - **相关契约：** [TypeScript 控制面迁移 v0](typescript-control-plane-migration-v0.zh-CN.md)、[Extensions 参考](../../reference/extensions.md)、[Capability 目录](../../../loopx/capabilities/README.md)、[总体路线图 v0](loopx-overall-roadmap-v0.zh-CN.md)（S2、S8、S12）、[import 边界测试](../../../tests/architecture/test_control_plane_import_boundaries.py) - **跟踪 issue：** [#5072](https://github.com/loopx-project/loopx/issues/5072) - **替代 / 关闭：** 无 @@ -15,6 +15,10 @@ 第 1–10 节是持久的设计与验收契约；第 11 节是规范性交付计划；第 12 节列出未决决策，建议答案不等于批准；附录为非规范内容。本 RFC 同时提供英文版与 `.zh-CN.md` 语义镜像，两者不一致视为缺陷。 +本文是目录归属、可安装发行物与运行时装配的统一设计，保留原文件名与跟踪 issue。 +合并代表接受设计依据，不代表 runtime 已交付、性能已验证、宿主已合格或默认值已改变。 +以下历史测量保留原有基线。 + --- ## 1. 决策摘要 @@ -27,9 +31,17 @@ 6. **不变：** 内核权威、CLI 兼容基线、extension 生命周期规则、公开/私有边界、全部稳定协议。 7. **本 RFC 不批准：** 任何子包"毕业"到独立仓库、按发行物改许可证、任何 schema 缩减。 +各发行层把**同一份治理实现**装配为 minimal 与 standard 预设。 +Minimal 必须执行并恢复真实的受治理任务；standard 围绕同一内核增加产品装配。 +研究配置冻结其中一种装配与声明过的实验改动，不产生第三套治理实现。 + +“小”分别从安装依赖、加载代码、激活服务、模型可见上下文衡量。 +发行表定义可安装内容，不代表每条命令都必须加载。安装 standard 不授予服务激活或权限。 +现有默认值与机器强制工作义务持续生效，直到合格且明确披露的迁移改变它们。 + ## 2. 问题与动机 -只想要 CLI 或内核的开发者，安装的和运行桌面工作台、Lark 管家、全部内置 capability 的人是同一个 wheel。基线数据： +只想要 CLI 或内核的开发者，安装的和运行桌面工作台、Lark 管家、全部内置 capability 的人是同一个 wheel。`2f3d13ae9` 上的历史发行盘点： | 事实 | 基线值 | | --- | --- | @@ -52,6 +64,24 @@ 这些表面的负责人无法在本地解决：capability 作者不能决定内核的打包方式，内核也不能在没有仓库级规则的情况下决定哪些 capability 是可选的。 +目录与包拆分还需要执行契约。简短 CLI 读取不应初始化研究栈或 IM 服务，嵌入式 managed +任务不应要求交互 App。仅缩小安装代码不能防止提前导入、空闲轮询或每次模型调用的过量上下文。 +因此第 9 节同时验证结构迁移和有用的任务旅程。 + +设计必须支持以下可观察旅程： + +| 旅程 | 必须得到的结果 | 对装配的要求 | +| --- | --- | --- | +| 有界 managed 任务 | 无交互 App 也能启动、执行、结算并回读结果 | Minimal 包含一条合格宿主路径与持久 authority | +| 长程研究 | 先产出有用的首个结果，持续工作后有证据支持的修订或新成果 | 规划、研究、记忆策略按需；进展不能只是时间变长或重复总结 | +| 两三个 peer 协作 | 证据返回协调者，记录采纳，中断后恢复所有权 | 复用工作/租约 authority；peer 生命周期与结果采纳分离 | +| App 或 IM 请求 | 暂停、纠正、继续，并在原目的地收到已验收结果 | 前端与交付 provider 围绕同一工作身份装配 | +| 硬件或外部操作 | 完成多步任务，核对不确定副作用，并在对应边界验证停止 | 显式激活的 operation provider 负责回读、联锁与安全重试 | +| 可复现 benchmark | 用原生对照与完整成本比较合格产品装配 | 冻结实验输入；原生 runner、verifier 与评分保留各自所有权 | + +这些是共享产品要求，不表示一次性交付所有旅程或组合。 +内容、办公与工程能力使用同样的边界，无须成为强制启动依赖。 + ### 不变量 - I1. 任何跨包变更都是一个仓库、一个 PR、一次 CI。 @@ -60,6 +90,11 @@ - I4. 缺失的可选发行物退化为与 extension "off state" 相同的行为：核心命令可用，缺失的 capability 报告为不可用，绝不静默替换。 - I5. 安装仅内核发行物不需要 Node.js；在没有 Node.js 时运行有副作用的命令得到类型化 `node_unavailable` 诊断。 - I6. 任何移动都不附带改变公开/私有边界规则、schema 字段或许可证。 +- I7. 未选择的可选组件不能初始化、注册 timer/hook、联网或注入模型指令。 + 缺少执行前提时须在 dispatch 前失败，不能降级到不受治理的执行。 +- I8. 必需上下文保持完整、新鲜；缩短 prompt 不能删除要求、required reads 或停止条件。 + 重放先核对持久身份与外部证据，再决定重试。 +- I9. 性能与成果声明注明所测装配、基线、环境和范围。文件数减少、help 加速不能证明任务效果改善。 ## 3. 范围与非目标 @@ -70,6 +105,7 @@ - 三层发行物的定义及"哪类代码归哪层"的规则。 - 内置 capability 经现有 `CapabilityRegistry` provider 边界迁入 `packages/`。 - `loopx-core` 以 optional extra 或随包捆绑方式交付 Node effect runtime。 +- 使用同一类型化 owner 的 minimal/standard 装配、按需加载、激活、上下文边界与匹配的产品/benchmark 资格验证。 ### 非目标 @@ -77,6 +113,8 @@ - 按发行物改许可证；除另有许可证 RFC 决定外，所有层保持 Apache-2.0。 - 任何内核语义、TS 迁移顺序或稳定协议的变更。 - 移除旧兼容 facade（`loopx.status`、`loopx.quota`）；其退役仍由迁移 RFC 管辖。 +- 新模型 loop、scheduler、插件体系、记忆数据库、benchmark 原生 runner、存储迁移、设备框架或强制 daemon。 + 本提案不授权 benchmark 运行、设备操作或宿主晋级。 ## 4. 现状契约 @@ -88,6 +126,21 @@ - `packages/*/extension.toml` 与 `loopx.extensions.manifest` 定义 extension 生命周期（readiness、版本、默认关闭、卸载）。这是 capability 包必须采用的契约，本文不重新定义。 - `docs/reference/extensions.md` 已写明：capability 是产品契约，extension 是交付单元。本 RFC 把这条规则应用到内核 wheel 自身。 +`9cae3b28939f72fa4aadab5cfe49e19bcbdab372` 上的运行时装配审计： + +- [entrypoint.py](../../../loopx/entrypoint.py) 有轻量 version 路径与部分原生 scheduler 后续调用。 + [cli_runtime.py](../../../loopx/cli_runtime.py) 按所选命令分发，保留完整 parser fallback。 + `performance-diagnosis` 无须 registry，但尚未进入 selected-command 集合； + 这是有界加载接缝，不代表所有启动都已延迟加载。 +- [Controller/Executor 统一 RFC](controller-executor-unified-contract-v0.zh-CN.md) 负责受治理工作契约； + [Session 模式](agent-session-execution-modes-v0.zh-CN.md) 负责 managed/attached 准入； + [DSH/Pi 选择](harness-selection-dsh-pi-v0.zh-CN.md) 负责宿主资格。装配复用这些契约。 +- [Benchmark toolkit](../../../loopx/capabilities/benchmark_toolkit/README.md) 负责通用权限、并发与完整性。 + [Benchmark 政策](../../../benchmark/README.md) 把原生执行/评估留在 benchmark，不恢复第二个 launcher。 +- [三层协议](../../reference/protocols/multi-agent-three-layer-minimality-v0.md) 的 “kernel” 指更宽的复用层。 + 本文治理内核指 authority 边界，启动依赖闭包指所选入口必需代码。 + 可复用 runner 或展示设施无须进入每个启动闭包。 + ## 5. 提议的架构 ### 归属与权威 @@ -99,8 +152,49 @@ | `loopx-capability-`（位于 `packages/`） | 单个 capability 的契约、provider、CLI 子命令、文档 | CODEOWNERS 中的 capability owner | `loopx-core`；可选依赖其他 capability 包 | | `loopx`（meta） | 无代码 | 发布负责人 | 以上全部，钉在同一发布列车 | +这是安装布局。`loopx-core` 中的 CLI handler 和宿主设施不因此进入每次启动的依赖闭包。 +可选 provider 发行物继续遵守 `packages//` 惯例；capability 包这一行不要求每个 provider +都创建一个 capability。 + 权威不移动：内核仍是 Goal/Todo/claim/lease/quota/effect 状态的唯一写者。capability 包只能通过 `CapabilityRegistry` 注册 provider、capability 契约和 CLI 子命令，绝不 import 内核私有模块。 +### 治理与运行时所有权 + +| 边界 | 现有 owner 与职责 | 不承担的职责 | +| --- | --- | --- | +| Bootstrap | Entrypoint/CLI 路由解析命令与已安装元数据 | Goal 决策、发现阶段激活 provider | +| 治理内核 | 类型化 Goal、work、quota、runtime、coordination owner：要求、准入、租约、预算、停止、effect、receipt、结算与恢复 | Model/tool loop、任务策略、UI、传输或评分 | +| 宿主 | 已准入的 managed/attached provider：模型/工具、Session 生命周期、观测 | 第二份工作账本或独立权限 authority | +| Capability 策略 | 最近的结果型 owner：规划、上下文选择、研究、召回、评审 | 覆盖强制迁移、租约、停止或预算 | +| Extension 与产品界面 | 现有生命周期/registry；前端和交付 provider 消费公开安全投影、提交命令 | 新插件机制，或从展示/私有源文字推导 authority | + +放置不新增 capability 或 provider id：治理留在 `control_plane`，通用生命周期在 `extensions`， +任务行为在最近的 capability，可选发行物在 `packages/`。新的通用领域规则留在既有类型化 +TypeScript owner；Python 可以适配，不能重建状态规则。 +新 capability 需要独立有用、provider-neutral 的调用者契约。 +真实宿主/设备集成负责自己的 provider 专属执行与恢复，不预建通用框架。 + +Planner 可以建议工作或 stride，所属迁移规则决定准入与义务。 +预设不能把机器强制的 `must_attempt_work` 契约变成文字 guidance。 +内核是内聚领域的集合，不是一个大文件。相邻重构应让下一次修改更局部，并保持已刻画的行为。 + +### 发行层之上的预设 + +| 装配 | 必需内容 | 显式可选内容 | +| --- | --- | --- | +| Minimal | Bootstrap、同一治理实现、一个受支持 authority provider、一条合格执行路径、紧凑状态/结果回读与恢复 | 任务能力、持久召回、observer、connector、workspace UI | +| Standard | 同一内核与兼容的普通产品装配 | 仅加载/激活所选工作流需要的 capability、宿主、UI/IM 服务与 connector | +| 研究配置 | 固定版本的 minimal 或 standard 装配及声明过的实验 overlay | 仅实验设计中列出的 instrumentation 或 ablation | + +`loopx` meta-package 保留安装兼容；已安装 standard 内容不等于激活列表。 +Minimal 是可执行装配，不是在 standard 完成全部初始化后加开关。 +不带宿主的只读 kernel library 不构成可执行预设资格。 +精确内容与首个受支持宿主/authority 组合由 D2/D5 决定。 + +装配、managed/attached 模式、宿主 provider、一个/两个模型 Session、存储 provider、benchmark arm +保持独立。Minimal 不意味着 attached，standard 不要求双模型 Session，research 不等于不受治理。 +只发布已测组合，保留现有模式默认值；改变装配不能静默改变 binding 的执行 owner。 + ### 受支持的宿主接入决策 独立安装的 `generic-cli` 宿主 transport 使用已有 Turn wire protocol，不注册 @@ -158,6 +252,60 @@ tests/architecture/top_level_module_budget.json capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一新规则：**`loopx/capabilities/` 下在 `main` 上没有内核调用方的 capability，在接受新特性前必须先迁到 `packages/`。** 内核调用方清单即第 2 节的 52 处 import；每处要么改为 registry 查询，要么被记录为保留的核心 capability（D2）。 +### 按需加载与上下文 + +1. **解析：** 读取 build/install 或显式 extension 注册时生成的本地版本化元数据。 + 顶层 help、命令列表与未知命令拒绝不能扫描仓库、导入所有 provider 或联网。 + 重复注册、过期或不兼容元数据必须可见；优先级显式确定，不能依赖导入顺序。 +2. **加载：** 导入所选命令及其依赖闭包。详细命令 help 可以加载自身 parser，但不能激活执行服务。 + 可选导入留在所属路由之后，fallback 路径也须遵守。 +3. **激活：** 校验 installed/enabled/ready 状态及作用域权限，再经现有生命周期 owner 启动所需服务。 + 可选代码缺失时说明如何安装/启用；必需 authority 或 runtime 缺失时 fail closed。 + Kernel 导入/help 不要求 Node；有副作用命令保留本文的类型化 `node_unavailable` 边界。 +4. **提供上下文：** 为所选工作和 executor 渲染现有受治理工作契约，复用统一 Controller/Executor + 设计的首次完整、后续差量与恢复语义。Required reads 和来源完整性仍有约束力。 + +相关来源/要求版本变化、Session generation 变化、compaction 或 ACK 丢失时，必须使上下文复用失效。 +不能因为 packet 更小，就认为 executor 已掌握前文。连续性未知时走所属契约的恢复路径。 +Capability 指令仅在适用时提供；authority 不能从 prompt 文字推导。 + +可选 observer 消费已提交事件或有界投影。除非现有契约明确要求它的 receipt， +其延迟不能进入准入/结算事务。只批处理尽力而为的 telemetry；不能为满足时间目标而延迟 +authority receipt 持久化、弱化 fsync/事务保证，或缓存过期权限/租约决策。 + +### 受治理生命周期与外部副作用 + +通过统一工作契约使用既有 Goal/Agent/work/Turn 身份、revision、lease、effect id 与 receipt。 +解析装配，校验要求和 authority，准入工作，经绑定宿主执行，验证并持久化证据，结算一次， +再经所属 channel 交付/回读。各步骤使用既有合法迁移与重放规则；这段描述不新增竞争的 status enum +或事务协调者。 + +Executor 崩溃、effect ACK 丢失、结果交付 ACK 丢失是不同恢复情形。 +Operation provider 必须说明某个 effect 能否核对、能否安全重试。 +外部状态未知时，后续依赖操作须等待回读或人工干预；“未观测到”不等于“未执行”。 +设备幂等、物理联锁与补偿归 provider 负责，不能虚构为内核保证。 + +模型取消、进程终止、设备确认停止是不同事实。模型停止不能在缺少设备证据时生成 +“设备已停止”声明。需要持续监督的 provider，在 effect 尚未解决时不能卸载。 +结果验收、传输交付、用户回读也必须保留现有的不同证据。 + +### 产品与 benchmark 执行 + +遵守 [长程研究计划](long-horizon-harness-benchmark-research-program-v0.zh-CN.md)： +native/plain 对照、被动观测、受治理执行与 ablation 具有明确身份。 +原生对照不接受 LoopX 指令或 hook。被动观测须验证无干扰。 +受治理实验臂使用与产品任务相同的合格装配与迁移；改变治理的 ablation 必须作为具名实验变体， +不能成为产品默认行为。 + +冻结产品/宿主版本、解析后的装配、模型与采样设置、skills/tools、初始状态、预算、 +checkpoint/恢复策略、数据集与 verifier 版本。按 run/arm 隔离记忆，禁止跨实验臂污染。 +除了任务结果，还要报告 controller、executor、compaction、retry、recovery 与人工干预成本。 +原生 runner/verifier 保留任务语义与评分。性能工作不能跳过 toolkit 的权限/完整性检查， +也不能把原始任务、trajectory 或 verifier 日志作为公开产品证据发布。 + +长程产品资格还要求证明：后续工作改善了已经有用的初始结果，或改变了决策。 +故意削弱首个结果、增加文字或运行更久都不算进展。 + ## 6. 备选方案与设计选择 | 备选 | 为何现在不选 | @@ -166,6 +314,18 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 | **保持单 wheel，只加 extras** | 能减轻安装重量，但平铺命名空间与两套打包惯例照旧；贡献者仍找不到边界。 | | **一次性全部搬到 `packages/`** | 同时对大量调用方破坏 I3，并把行为风险混入结构性变更。按组迁移并遵守 I3 兼容更易评审、更易回滚。 | | **无条件把 Node 捆进 `loopx-core`** | 解决 I5，但让内核 wheel 变成平台相关且体积大。作为 D1 选项与 optional-extra 方案并列保留。 | +| **Minimal 与 standard 各自一套引擎** | 重复状态迁移，破坏产品/benchmark 一致性。 | +| **全部治理规则插件化** | 预算、停止、租约、结算可能随预设消失。 | +| **以上游 agent runtime 替代 LoopX 内核** | 模型执行可以是宿主 provider，不能替代 LoopX 工作 authority。 | +| **每种装配都强制依赖一个 daemon 或远程服务** | 增加有界本地使用的生命周期与部署成本；可选 daemon 仍遵循其既有契约。 | + +Pi 展示了小型 agent core、工具/事件执行，以及与 coding 产品分离的显式上下文转换。 +DSH 展示了同一 runtime 的多预设装配与自包含的最小 SDK bundle。 +在固定版本中，DSH web minimal 与 standard 使用相同 agent-preset 包、不同 plugin 列表； +minimal 包含持久 shell、图像读取与 compaction。SDK minimal 还提供工作目录状态、持久化， +并按配置提供可选 MCP 资源。这些是装配范例，不能据此声称 DSH 恰好有两套引擎， +或把 LoopX headless adapter 与 DSH plugin 分别当成这两种预设。 +借鉴显式边界，不引入 Cordis、上游权限默认值或新的 LoopX 模型 loop。固定来源见附录 C。 ## 7. 安全、隐私与兼容 @@ -175,6 +335,12 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 - **混合版本：** meta-package 把所有层钉到同一发布列车。混合版本安装不受支持，由 `loopx doctor` 报告。 - **fail-closed：** 没有 runtime extra 时，有副作用的命令以 `node_unavailable` 失败，绝不在没有 TS 内核的情况下继续。 +宿主可用、安装和 capability 声明都是观测，不是授权。Provider 调用保持 Goal/Agent/workspace/delivery +作用域。预设不能把必需上下文或停止/预算规则变为可选。未迁 CLI 路由保留 fallback，直到 +parsing、global options、输出、错误与 exit code 合格；不兼容版本在 dispatch 前拒绝。 +只有全部受支持命令完成迁移、help 与诊断一致性验证通过后，才能退役完整 parser。 +不能让两个 writer 同时写同一 binding 来制造混合版本 rollout 可用的假象。 + ## 8. 迁移与回滚 | 步骤 | 门禁 | 回滚 | @@ -186,7 +352,12 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 | capability 包迁移 | 逐个 capability，内核调用方清单已解决 | revert 单个包 | | 移除 shim | 迁移后一个 minor 版本；弃用记入 update notes | 不适用；需调用方迁移 | -任何步骤都不需要数据迁移，因为没有规范记录改变。 +切换活跃 binding 的装配前，检查兼容、让执行 owner 静止并核对未完成 effect。 +继续前验证新 owner 与解析后的装配；不能跨活跃 lease 热切换。回滚同样先核对并保留持久状态。 +后续不可逆数据变化须另设迁移/导出门槛。 + +这些结构/装配变化的回滚不需要数据迁移。默认值变化须有明确 owner 决策与 release notes； +本提案不改变现有默认值。 ## 9. 验证与验收 @@ -200,7 +371,29 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 | 无内核真相重复 | import 边界测试 + 审查 `packages/*/src` 是否 import 内核私有模块；过渡守卫：`tests/architecture/test_package_kernel_import_ratchet.py` 钉住每一个 `loopx.*` import，未经评审的新边失败，退役的边必须在同一 PR 降低 pin | 零内核私有违规 | 仅静态 import。Ark、Finance、JEV 的 13 条既有边仍作为迁移积压跟踪，与 MemT 的 2 条受支持公开接入边区分。守卫变绿不消除积压，也不满足本行；受支持的公开边不要求消失 | | meta-package 一致性 | `pip install loopx` 后跑现有完整 smoke | 与拆分前 smoke 一致 | — | -以上确定性一致性行是每个里程碑的必需项；本 RFC 不做任何实机 qualification 或性能主张。 +以上七条结构性验收继续约束对应迁移/打包里程碑。运行时与旅程资格增加以下条目。 + +以下是拟定验收条件，不是已通过声明。确定性 fixture 根据语义独立设计，不能从当前实现输出反推期望。 +Live、性能和晋级证据分别记录。 + +| Id / 声明 | 测试或证据 | 必须得到的结果 | 边界 | +| --- | --- | --- | --- | +| V1 / 按需加载 | 两种预设下对 import、help、列表、未知命令、所选路由做导入/进程/网络追踪 | 只加载声明过的依赖闭包；无可选激活 | 不证明执行性能 | +| V2 / authority 一致性 | 对要求、过期 claim、停止、预算、重放、结算做刻画与负例测试 | 两种预设具有相同合法/非法迁移，只结算一次 | Minimal 不得绕过 authority | +| V3 / CLI 兼容 | 受支持命令的差分语料，含 fallback、Node/provider 缺失 | Parsing、输出契约、exit code 稳定，失败可操作 | 明确列出未迁移路由 | +| V4 / managed minimal | 一个真实 managed 任务、注入中断、重启、证据验证与结果回读 | 身份相同，effect 已核对；不重复派发已确认工作或结算；恢复成本有记录，已验收结果可获取 | 初期一个合格宿主即可；纯 mock 执行不够 | +| V5 / 上下文连续性 | 首次上下文、无变化续行、来源修订、compaction、ACK 丢失 | 必需上下文完整或明确恢复；拒绝过期上下文 | 单独测 token 减少 | +| V6 / standard 旅程 | 原始 App/IM 请求、纠正/暂停、继续、完成与返回 | 一个执行 owner；已验收结果和成本可见；目的地不静默改变 | 每个前端/provider 分别合格 | +| V7 / 研究与 peers | 有用首个结果后的证据性改善；owner 恢复后的 peer 结果返回与采纳 | 新成果或有理由的决策修订，并有可归属证据 | 更多时间、peer 或文字本身不能通过 | +| V8 / benchmark 保真 | 固定的匹配实验、native/passive/governed 边界、记忆隔离、完整成本账本 | 原生语义完整；C0–C4 证据遵守研究/诊断 owner | 本 RFC 不声称分数或因果收益 | +| V9 / 物理副作用 | 模拟器/故障注入，再做显式授权的 provider 专属 live 验证 | 核对丢失 ACK；在保证范围内防重复动作；独立确认设备停止 | 不承诺通用 exactly-once 或紧急停止 | +| V10 / 开销 | 指定环境中重复、成对测量冷进程与热路径 | 报告 median/p95、RSS、模块数、文件 I/O、Node 启动/IPC、字节与模型 token；持久性无退化 | R0 确定数字预算；CLI 基线无须付费任务运行 | + +本地开发候选目标为 p95：import 低于 50 ms、顶层 help 低于 100 ms、所选命令 help 低于 200 ms。 +它们是 D6 的建议，不是已验证结果或跨机器 CI 阈值。 +采用前要定义解释器启动、缓存条件、样本数、机器/runtime 版本。 +真实 status/admission/settlement 延迟须在有代表性的小/大状态上单独测量，包含 SQLite 竞争和恢复； +不能把 CLI-help 目标套在这些操作上，也不能减掉其必需 I/O。 ## 10. 运维契约 @@ -209,24 +402,50 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 - 发布说明列出公开 import 的移动及保留 shim 的到期版本。 - 不引入新的守护进程、存储或网络面。 +回读还说明解析后的装配/版本、所选宿主和 Session 模式、必需/可选 provider 与加载原因。 +复用现有诊断/投影，不新增状态库。区分前提缺失、authority 过期和 effect 不确定。 +启动与 Turn 开销分别记录；observer 故障不改写已提交结果，必需证据/交付 receipt 仍由所属 owner +治理。容量、背压、恢复继续遵守既有 work/host 契约。 + ## 11. 规范性交付计划 | 里程碑 | 交付行为 | 进入门禁 | 退出证据 | 回滚 | | --- | --- | --- | --- | --- | -| M0 | 以当前数量加入预算 fixture 与测试；RFC 索引条目 | 本 RFC 被接受 | 预算测试绿；数量钉住 | 删除测试 | +| M0 | 以当前数量加入预算 fixture 与测试；RFC 索引条目 | 本 RFC 被接受；重测 fixture 基线 | 预算测试绿；数量钉住 | 删除测试 | +| R0 | 已刻画的 `performance-diagnosis` selected route 与实测加载接缝 | 现有路由/owner/依赖图；D6 测量决策；不依赖包发布 | 本路由 V1/V3、V10 基线；行为不变 | 撤回路由提取 | | M1 | `loopx/chat_*` → `loopx/chat/` 遵守 I3 兼容；预算按净减少调低 | M0 | 第 9 节第 1–2 行 | revert | | M2 | `loopx/*_goal_mode` → `loopx/hosts/` 遵守 I3 兼容 | M0 | 第 1–2 行 | revert | -| M3 | `loopx-core` + `loopx-workspace` + meta `loopx` 以预发布发布；Node 按 D1 以 extra 或捆绑交付 | M1、M2；D1 已决 | 第 3–4、7 行 | 撤下预发布 | +| M3 | `loopx-core` + `loopx-workspace` + meta `loopx` 以预发布发布；Node 按 D1 以 extra 或捆绑交付 | M1、M2；D1 已决；所选 D2/D5 装配已映射 | 第 3–4、7 行；在干净拆包安装上重验已合格的 R1/R2 旅程 | 撤下预发布 | +| R1 | Opt-in 可执行 minimal，含一个真实 managed Turn、重启与结果回读 | R0；所选 D2 内容和 D5 宿主/authority；可先于 M3 验证源码装配 | 此受支持组合的 V1–V5/V10；源码证据本身不代表拆包安装合格 | 核对后返回旧合格装配 | +| R2 | Standard 使用同一内核，只激活所选产品工作流 | R1；现有前端/Session 准入；可先于 M3 验证源码装配 | V2/V5/V6/V10、关闭一致性；声称拆包资格前，在 M3 重验冷安装旅程 | 关闭 opt-in 装配，保留状态 | | M4 | 第一个无内核调用方的 capability 迁入 `packages/` | M3；D2 清单 | 第 5–6 行 | revert 单包 | | M5 | 其余符合条件的 capability 迁移；M1/M2 的公开 shim 在文档化兼容窗口结束后移除 | M4 | 完整 smoke 一致 | 不适用 | +| R3 | 匹配的产品路径 benchmark 及长程/peer 旅程 | 所选界面的 R1 或 R2；冻结设计与单独运行授权 | V7/V8、完整成本、隐私与既有 C0–C4 资格 | 停用实验 overlay，保留有界证据 | +| R4 | 一个真实外部操作 provider，含核对与停止回读 | D7；具名操作 owner 和显式操作授权 | V9 加继承的治理门槛 | 停用前先静止/核对 | + +M0–M5 保留原发行里程碑；R0–R4 是同一计划中的运行时和旅程资格切片。 +R0 可以先于目录移动交付，但不代表内核合格。R3/R4 可选，不阻塞已合格的 CLI 或 managed 任务。 +真实调用者出现前不增加闲置 provider、字段或框架。每个 PR 记录应用/推迟的相邻重构。 ## 12. 未决决策 1. **D1 — `loopx-core` 的 Node 交付方式。** 负责人：内核 maintainers。选项：(a) `loopx-core[runtime]` extra，文档说明 Node 为前提；(b) 以平台 wheel 捆绑钉住版本的 Node；(c) 两者都做，(a) 为默认。建议：(c)。所需证据：package-smoke lane 的 wheel 体积与平台矩阵。截止：M3 前。 -2. **D2 — 哪些 capability 留在 core。** 负责人：内核 + capability maintainers。输入：52 处内核侧 import。建议：只保留 Turn driver、quota 或 heartbeat prompt 在运行时需要的 capability，其余全部成包。截止：M4 前。 +2. **D2 — 哪些 capability 留在 core。** 负责人：内核 + capability maintainers。输入：52 处内核侧 import。建议：只保留 Turn driver、quota 或 heartbeat prompt 在运行时需要的 capability，其余全部成包。偶然的 eager import 应经 registry 解耦，不能把其存在直接当作 core 必需性的证据。记录 minimal/standard 的精确安装/加载/激活闭包。截止：所选装配在 R1/M3 前，全量盘点在 M4 前。 3. **D3 — shim 存活期。** 负责人：发布负责人。选项：一个 minor 版本（建议）或两个。截止：M1。 4. **D4 — 索引位置。** 本 RFC 列在"控制面内核、状态与迁移"还是"运行时、Capability 与协作集成"。建议：内核章节，因为预算测试与 `loopx-core` 边界由内核负责。 +5. **D5 — 首个可执行装配。** 负责人：runtime/host 与 authority maintainers。 + 在现有发行方案内选择 minimal 的精确宿主/存储组合与 standard 映射。 + 建议 minimal 先 opt-in，选择最小且已合格的 managed 路径，保留当前默认值。 + DSH/Pi 仍按选择 RFC 验证。证据：R1 退出前有 V4 恢复与 Session 连续性，M3 前有包回读。 +6. **D6 — 性能预算。** 负责人：性能 maintainers。选择机器相关 p95 预算或相对回归界限； + 建议第 9 节候选预算加明确进程/缓存/样本条件。证据：可复现 R0 基线；真实 Turn 预算独立推导。 +7. **D7 — 外部操作调用者。** 负责人：operation-provider maintainer。 + 选择具体调用者或推迟物理资格。建议真实调用者出现前不做设备框架。 + R4 前须确定范围、幂等/回读/停止契约和操作授权。 + +新增建议不关闭 D1–D4，也不批准新默认值。批准须有评审决策，不能来自实现进展或沉默。 + --- ## 附录 A：执行台账（非规范） @@ -292,6 +511,9 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 | E1 | 148 个顶层模块 | `2f3d13ae9` | `ls loopx/*.py \| wc -l` | 148 | 统计文件数，非公开 API | | E2 | 52 处内核侧 capability import | `2f3d13ae9` | `rg -l "loopx\.capabilities\|from \.\.capabilities\|from \.capabilities" loopx/control_plane loopx/cli_commands loopx/*.py` | 52 | 仅静态 import | | E3 | 80 处 capability → control_plane import | `2f3d13ae9` | `rg -l control_plane loopx/capabilities` | 80 | 含 docstring；为上界 | +| E4 | 所选 CLI 加载接缝 | `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` | 第 4 节链接的入口/CLI | 源码审计 | 无新性能测量 | +| E5 | DSH 装配范例 | 固定上游 commit | [`minimal.patch.yml`](https://github.com/deepseek-ai/deepseek-harness/blob/f3803c96974ad4a94195fb97e5c637e9c2a3afe3/packages/bundle/web-app/presets/minimal.patch.yml)、[`standard.patch.yml`](https://github.com/deepseek-ai/deepseek-harness/blob/f3803c96974ad4a94195fb97e5c637e9c2a3afe3/packages/bundle/web-app/presets/standard.patch.yml)、[`sdk-minimal`](https://github.com/deepseek-ai/deepseek-harness/blob/f3803c96974ad4a94195fb97e5c637e9c2a3afe3/packages/bundle/sdk-minimal/README.md) | 源码审计 | 共享预设装配与自包含 SDK bundle；不代表 LoopX 宿主资格或权限建议 | +| E6 | Pi core/上下文范例 | 固定上游 commit | [`agent` core](https://github.com/badlogic/pi-mono/blob/f14813e96510a7cf7562a120e809c6a134af073d/packages/agent/README.md) | 源码审计 | Agent/tool/event core，以及 `transformContext`、`convertToLlm`、`prepareRequest`、`finishTurn` 接缝；无 LoopX authority 或性能声明 | ## 附录 D：被拒绝或被取代的备选