From 3cae288a7bb3d7a0e43a6349d6f7c6a839455806 Mon Sep 17 00:00:00 2001 From: "lusendong.6789" Date: Thu, 29 Oct 2026 22:05:23 +0800 Subject: [PATCH 1/3] docs(rfc): define small kernel runtime composition Signed-off-by: lusendong.6789 Co-authored-by: TRAE CLI --- docs/architecture/rfcs/README.md | 9 + docs/architecture/rfcs/STATUS.md | 5 +- docs/architecture/rfcs/STATUS.zh-CN.md | 5 +- .../small-kernel-runtime-composition-v0.md | 390 ++++++++++++++++++ ...all-kernel-runtime-composition-v0.zh-CN.md | 310 ++++++++++++++ 5 files changed, 715 insertions(+), 4 deletions(-) create mode 100644 docs/architecture/rfcs/small-kernel-runtime-composition-v0.md create mode 100644 docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index c5fd28ec73..dabfa3e944 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -159,6 +159,15 @@ Paired diffs do not certify translation accuracy. top-level module count with an architecture test. No kernel semantics, licence or schema change; multi-repository split remains a non-goal. +- [Small Kernel and Runtime Composition v0](small-kernel-runtime-composition-v0.md) + ([中文版](small-kernel-runtime-composition-v0.zh-CN.md)) + - **Delivery on `main`:** Proposal only; no runtime or default change. + - **Current boundary:** One governance implementation, minimal/standard + composition and frozen research configurations. Defines demand loading, + activation and context boundaries, product/benchmark parity, and staged + managed-task, product-journey and external-operation qualification under + the existing distribution and controller/executor contracts. + - [Automatic Execution Admission v0](automatic-execution-admission-v0.md) ([中文版](automatic-execution-admission-v0.zh-CN.md)) - **Delivery on `main`:** M1 policy, managed Turn admission and M3 diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 6fac57113c..e953bbb5ff 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -18,7 +18,7 @@ appendix may keep dated history, but no dated log heading may precede it. [中文版](STATUS.zh-CN.md) is the semantic mirror of this file. -## Accepted (47) +## Accepted (48) | RFC | Header status | Supersedes / closes | Ledger | | --- | --- | --- | --- | @@ -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/) | @@ -68,6 +68,7 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Shared Goal Alignment and Governed Amendment Protocol (v0)](shared-goal-alignment-and-governed-amendment-v0.md) | Accepted | none | [2 entries](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC: LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.md) | Accepted | none | [24 entries](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | Accepted | none | — | +| [RFC: Small Kernel and Runtime Composition (v0)](small-kernel-runtime-composition-v0.md) | Accepted | none | — | | [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [18 entries](ledger/typescript-control-plane-migration-v0/) | ## Superseded (1) diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index 51a81ad3e6..db75be9956 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -15,7 +15,7 @@ [English](STATUS.md) 与本文互为语义镜像。 -## 已接受 (47) +## 已接受 (48) | RFC | 头部状态 | 替代 / 关闭 | Ledger | | --- | --- | --- | --- | @@ -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/) | @@ -65,6 +65,7 @@ | [RFC：共享 Goal 对齐与受治理 Amendment 协议（v0）](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md) | 已接受 | 无 | [2 条](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC：LoopX 共享控制面权威与可插拔状态 Provider（v0）](shared-goal-authority-state-provider-v0.zh-CN.md) | 已接受 | 无 | [24 条](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | 已接受 | none | — | +| [RFC：小内核与运行时装配（v0）](small-kernel-runtime-composition-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [18 条](ledger/typescript-control-plane-migration-v0/) | ## 已被替代 (1) diff --git a/docs/architecture/rfcs/small-kernel-runtime-composition-v0.md b/docs/architecture/rfcs/small-kernel-runtime-composition-v0.md new file mode 100644 index 0000000000..df51db33ff --- /dev/null +++ b/docs/architecture/rfcs/small-kernel-runtime-composition-v0.md @@ -0,0 +1,390 @@ +# RFC: Small Kernel and Runtime Composition (v0) + +- **RFC status:** Accepted, design acceptance takes effect on merge +- **Supersedes / closes:** none +- **Delivery maturity:** Proposal +- **Authors / owners:** LoopX maintainers +- **Created:** 2026-10-29 +- **Last normative revision:** 2026-10-29 +- **Implementation baseline:** `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` +- **Related contracts:** [Distribution split](monorepo-distribution-split-v0.md), [Unified controller/executor contract](controller-executor-unified-contract-v0.md), [Session execution modes](agent-session-execution-modes-v0.md), [Overall roadmap](loopx-overall-roadmap-v0.md), [Extensions](../../reference/extensions.md) +- **Language mirror:** [中文版](small-kernel-runtime-composition-v0.zh-CN.md) + +## Document map and maintenance contract + +Sections 1–11 define the design and acceptance contract; section 4 records the +named implementation baseline. Section 12 records unresolved decisions, whose +recommendations are not approval. The appendix contains source evidence. +English and Chinese are semantic mirrors. Merge accepts a design basis; it +does not establish implementation, performance, host qualification or a new +default. Dated delivery evidence belongs in the [RFC ledger](ledger/README.md). + +## 1. Decision summary + +LoopX should have one small governance kernel, composed into **minimal** and +**standard** presets. A research configuration freezes a composition and its +experimental changes; it does not create a third governance implementation. + +The kernel owns durable work admission and settlement: Goal requirements, +work identity, claims/leases, budget, stop rules, effect identity, receipts and +recovery. Hosts own model/tool execution. Capabilities supply task strategies +and domain behavior. Frontends display and submit through these same owners. + +Smallness has four independent meanings: installed dependencies, loaded code, +activated services, and model-visible context. Installing standard must not +make every command load or start every capability. Minimal must still perform +a real governed Turn and recover it after interruption. + +This RFC refines runtime composition under the existing distribution split +and unified work contract. It neither renames their packages nor adds another +plugin system, session protocol or roadmap. Existing defaults, mandatory work +obligations and authority remain in force until a qualified migration changes +them explicitly. No benchmark, device operation or host promotion is approved +by accepting this design. + +## 2. Problem and motivation + +A short CLI read should not initialize a research stack or an IM service. An +embedded managed task should not need an App session. A standard product user +still needs understandable progress, intervention, recovery and delivery back +to the original request. A benchmark needs to measure that same implementation +without importing unrelated product services or changing the native evaluator. + +Package splitting alone cannot meet these needs: an installed dependency can +still be eagerly imported, an unused service can still poll, and a small +binary can still send excessive context on every model call. Conversely, a +loader alone cannot provide LoopX's durable governance semantics. + +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. Each state transition and effect has one authority; presets cannot fork it. +- I2. Omitting an optional component causes no initialization, timer, network + call, hook or model instruction from that component. +- I3. A missing execution prerequisite fails with actionable context before + dispatch; it never falls back to an ungoverned execution path. +- I4. Required context remains complete and fresh; smaller prompts do not + authorize dropping requirements, required reads or stop conditions. +- I5. Replay reconciles durable identity and external evidence before retry; + completion, settlement and result delivery remain distinguishable. +- I6. Performance and outcome claims name the measured composition, baseline, + environment and scope. Faster help is not evidence of better task outcomes. + +## 3. Scope and non-goals + +In scope: runtime ownership, explicit composition, demand loading, context +boundaries, benchmark fidelity and staged qualification for product journeys. + +Non-goals: a new model loop, capability catalog, scheduler, memory database, +benchmark-native runner, storage migration, device abstraction framework or +microservice split. This proposal adds no CLI flag, package or persisted schema. +It removes no stored field. Actual configuration syntax is an implementation +decision under the existing extension and distribution contracts. + +## 4. Current-system contract + +On the named baseline, [entrypoint.py](../../../loopx/entrypoint.py) has a small +version route and selected native scheduler follow-ups; +[cli_runtime.py](../../../loopx/cli_runtime.py) dispatches selected commands and +retains the full-parser path for other commands. `performance-diagnosis` is +registry-optional but is not in the selected-command set. This supplies a +bounded first loading seam; it is not evidence that all startup is already lazy. + +Typed domain authority is being consolidated under +[control_plane](../../../loopx/control_plane/) according to the +[TypeScript migration](typescript-control-plane-migration-v0.md). Python still +owns adapters and some existing paths. New composition work must use the +existing owner and characterize legacy behavior before moving it; it must not +silently recreate rules in a second language. + +The distribution RFC owns `loopx-core`, `loopx-workspace` and optional packages. +The [three-layer protocol](../../reference/protocols/multi-agent-three-layer-minimality-v0.md) +uses “kernel” for a broader reusable layer including runner/presentation +facilities. Here, **governance kernel** means the authority boundary, while +**boot closure** means code required by a selected entrypoint. A reusable +facility can remain in that broader layer without belonging to every boot closure. + +The unified controller/executor RFC owns the governed work contract. Session +modes own `managed_runtime` versus `attached_host`. The +[DSH/Pi selection RFC](harness-selection-dsh-pi-v0.md) owns host qualification; +a bounded headless adapter and a session-owning runtime have different duties. +[Benchmark toolkit](../../../loopx/capabilities/benchmark_toolkit/README.md) +owns reusable permission, concurrency and integrity support, while +[benchmark policy](../../../benchmark/README.md) keeps native execution and +evaluation with the benchmark. This RFC does not restore a second launcher. + +## 5. Proposed architecture + +### 5.1 Ownership and placement + +| Boundary | Owner and responsibility | Excluded responsibility | +| --- | --- | --- | +| Bootstrap | Existing entrypoint/CLI route; resolve command and installed composition metadata | Goal decisions, provider activation during discovery | +| Governance kernel | Existing typed Goal, work, quota, runtime and coordination owners; admission, transition, effect, settlement and recovery rules | LLM/tool loop, task strategy, UI, transport, benchmark scoring | +| Host execution | Admitted managed or attached host provider; model calls, tools, session lifecycle and execution observations | A second work ledger or independent permission authority | +| Capability strategy | Nearest outcome capability; planning, context selection, research, recall, review | Overriding required transitions, leases, stop or budget | +| Extension lifecycle | Existing manifest, registry, compatibility and activation machinery | Another generic plugin/container framework | +| Product surface | Workspace, CLI, IM or delivery provider consumes public-safe projections and submits commands | Inferring canonical state from private source files or display text | + +Placement rationale: no new capability id or provider id is introduced here. +Core governance belongs to `control_plane`; loading/lifecycle mechanics belong +to existing entrypoints and `extensions`; benchmark support stays with +`benchmark_toolkit`. A later optional host/device integration uses an existing +outcome owner when sufficient, with its independently distributed provider in +`packages//`. A new capability requires a real provider-neutral +caller contract, not merely an installable bundle. + +Governance is a logical boundary, not a request to move every rule into one +file. Keep cohesive typed domains. A planner may recommend work or a stride; +only the owning transition decides admission and obligations. Replacing a +strategy must not turn a machine-enforced `must_attempt_work` rule into prose +guidance. Changing such a default requires its own disclosed contract change. + +### 5.2 Presets and independent axes + +| Composition | Required content | Explicit optional content | +| --- | --- | --- | +| Minimal | Bootstrap, existing 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 | The same kernel and compatible product composition for ordinary use | Activate capabilities, host integration, UI/IM services and external connectors only for the chosen workflow | +| Research configuration | A pinned minimal or standard composition plus a declared experiment overlay | Instrumentation or ablations explicitly named in the experimental design | + +Minimal is a supported end-to-end composition, not a disabling flag on a +fully initialized standard runtime. A kernel library may be used for read-only +embedding without a host, but that does not qualify the executable minimal preset. +Standard is a convenience composition; installation alone grants no activation +or permission. Existing installation behavior remains until the distribution +RFC's migration gates are met. + +Keep these axes independent: composition; managed/attached mode; host provider; +one/two model sessions; storage provider; benchmark arm. In particular, minimal +does not mean “attached,” standard does not require two model sessions, and +research does not mean “ungoverned.” Publish only tested combinations. Preserve +the session-mode RFC's defaults and explicit mode admission; do not silently +change a binding's execution owner when changing composition. + +### 5.3 Resolve, load, activate, provide 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 the distribution 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. + +### 5.4 Durable 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. + +### 5.5 Benchmark uses the product implementation + +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 | Decision and trade-off | +| --- | --- | +| Only split packages or add lazy imports | Useful first slices; insufficient to define activation, authority and context boundaries | +| Separate minimal and standard engines | Rejected: duplicates transitions and invalidates product/benchmark parity | +| Make every rule a plugin | Rejected: budget, stop, lease and settlement could disappear with a preset | +| Adopt an upstream agent runtime as the LoopX kernel | Rejected: upstream model execution can be a provider, but does not replace LoopX work authority | +| One mandatory daemon or remote service | Not required: adds lifecycle and deployment cost to bounded local use; any daemon remains under its existing RFC | + +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 A. + +## 7. Safety, privacy, and compatibility + +No existing permission or mandatory gate becomes optional through composition. +Host availability, extension installation and runtime capability declarations +are observations, not grants. Keep Goal, Agent, workspace and delivery scopes +through every provider call; resolve secrets through the existing provider +boundary. Public projections exclude private source content and local artifacts. + +No schema/field removal is proposed. Preserve known readers/writers and external +imports for their documented compatibility windows. Unmigrated CLI routes keep +the existing fallback until command parity qualifies their replacement. Reject +unsupported version/provider combinations before dispatch; never run two writers +against one binding to make mixed-version rollout appear available. + +## 8. Migration and rollback + +First characterize CLI parsing, output, errors, required reads and effect +behavior. Move one cohesive route and update active callers; remove an internal +bridge only after its real callers migrate. Do not migrate storage or weaken +durability as a side effect of loading work. + +Introduce executable minimal as opt-in with an explicit resolved composition +readback. Before switching an active binding, check compatibility, quiesce its +owner and reconcile outstanding effects. Validate the new owner/readback before +resuming; never hot-swap across an active lease. Roll back to the previous +qualified composition after the same reconciliation. Keep durable state intact. +Any later irreversible data change needs a separate migration/export gate. + +Standard adoption requires the product journey gates below. Retire the full +parser fallback only after all supported commands have migrated and global +options, help, errors and exit codes preserve compatibility. Default changes +require release notes and an explicit owner decision; this RFC makes none. + +## 9. Validation and acceptance + +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 | +| --- | --- | --- | --- | +| A1 / 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 | +| A2 / 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 | +| A3 / 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 | +| A4 / managed minimal | One real managed task, injected interruption, restart, evidence validation and result readback | Same identity, reconciled effect, no duplicate work or charge; accepted result reachable | One qualified host is enough initially; mock-only execution is insufficient | +| A5 / 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 | +| A6 / 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 | +| A7 / 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 | +| A8 / 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 | +| A9 / 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 | +| A10 / 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 | M0 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 D3 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 + +Readback should explain the resolved composition and versions, selected host +and session mode, required versus optional providers, activation/readiness and +the reason a component was loaded. Reuse current diagnostics/projection owners; +do not introduce another status database. Missing prerequisites, incompatible +metadata, stale authority and uncertain effects must remain distinguishable. + +Record startup and Turn overhead separately. Optional observer failure is +visible without rewriting committed execution results; mandatory delivery or +evidence receipt failure remains governed by its owner. Capacity limits and +backpressure belong to the existing work/host/provider contracts. Operator +recovery reconciles persisted receipts and provider readback before resuming. + +## 11. Normative delivery plan + +These slices fit the existing roadmap's runtime, distribution and product +streams; they do not establish a parallel program or require a repository-wide +rewrite before a local performance improvement can ship. + +| Milestone | Shipped behavior | Entry gate | Exit evidence | Rollback | +| --- | --- | --- | --- | --- | +| M0 / one loading seam | Selected `performance-diagnosis` route and measured loading boundary | Current-route characterization; owner/dependency map; D3 measurement decision | A1/A3 for this route, A10 baseline, no unrelated imports or behavior change | Revert route extraction | +| M1 / executable minimal | One qualified managed governed task with durable restart/result readback | D1 composition contents and D2 host/provider choice; existing authority contracts | A1–A5 and A10 for this supported combination | Explicit return to previous qualified composition | +| M2 / standard journey | Standard resolves the same kernel and activates only a chosen product workflow | M1; existing session/frontend admission | A2/A5/A6/A10 including cold install and feature-off parity | Disable the opt-in composition and retain state | +| M3 / research qualification | Matched product-path experiment and one long-horizon/peer journey | M1 or M2 for the selected surface; frozen design and separate run authorization | A7/A8, complete cost and privacy review, existing C0–C4 gates | Retire experimental overlay; retain bounded evidence | +| M4 / external operation provider | One real caller with provider-specific effect reconciliation and stop evidence | D4; named device/operation owner and explicit operation authorization | A9 plus inherited governance gates | Quiesce/reconcile provider before disabling | + +M0 does not qualify the kernel. M3 and M4 are optional qualification branches; +they need not block a qualified CLI or managed task. No unused provider, +configuration field, framework or generic test matrix is added ahead of its +first real caller. Each PR records the bounded refactor considered, applied +or deferred and its compatibility evidence. + +## 12. Open decisions + +| Id / owner | Options and recommendation | Evidence needed / decision point | +| --- | --- | --- | +| D1 / distribution and runtime maintainers | Map presets to the accepted distribution scheme; recommend opt-in minimal and standard as the eventual compatibility composition, without choosing a new default now | Exact installed/load/activation closures and upgrade/readback contract before M1 packaging | +| D2 / host and authority maintainers | Select the first managed host and supported storage combination from existing providers; recommend the smallest already qualifying path, with DSH/Pi judged by the existing selection RFC | A4 host/session continuity and authority recovery evidence before M1 exit; no universal host claim | +| D3 / performance maintainers | Adopt machine-specific p95 budgets or relative regression limits; recommend the candidate budgets plus explicit measurement conditions | Reproducible baseline before M0 exit; real Turn budget derived independently | +| D4 / operation-provider owner | Choose one concrete external-operation caller, or defer physical qualification; recommend no generic device framework before a caller exists | Scope, idempotency/readback/stop contract and authorization before M4 | + +Approval must be recorded through the corresponding reviewed decision; a +recommendation, implementation progress or silence cannot close a decision. + +## Appendix A: Source evidence (non-normative) + +| Evidence | Pinned source | Supported claim and limit | +| --- | --- | --- | +| E1 / LoopX | Implementation baseline above; linked entrypoint, CLI and owning contracts in section 4 | Existing seams and ownership only; no new performance measurement | +| E2 / DSH | [`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) | Shared preset composition and a self-contained SDK bundle; not a LoopX host qualification or permission recommendation | +| E3 / Pi | [`agent` core](https://github.com/badlogic/pi-mono/blob/f14813e96510a7cf7562a120e809c6a134af073d/packages/agent/README.md) | Agent/tool/event core with `transformContext`, `convertToLlm`, `prepareRequest` and `finishTurn` seams; no LoopX authority or performance claim | + +No live benchmark or hardware operation was performed for this proposal. diff --git a/docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md b/docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md new file mode 100644 index 0000000000..210b309989 --- /dev/null +++ b/docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md @@ -0,0 +1,310 @@ +# RFC：小内核与运行时装配（v0） + +- **RFC status:** Accepted, design acceptance takes effect on merge +- **替代 / 关闭：** 无 +- **Delivery maturity:** Proposal +- **作者 / 负责人：** LoopX 维护者 +- **创建日期：** 2026-10-29 +- **最近规范修订：** 2026-10-29 +- **实现基线：** `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` +- **相关契约：** [发行拆分](monorepo-distribution-split-v0.zh-CN.md)、[Controller/Executor 统一契约](controller-executor-unified-contract-v0.zh-CN.md)、[Session 执行模式](agent-session-execution-modes-v0.zh-CN.md)、[总体路线图](loopx-overall-roadmap-v0.zh-CN.md)、[扩展机制](../../reference/extensions.md) +- **Language mirror:** [English](small-kernel-runtime-composition-v0.md) + +## 文档地图与维护契约 + +第 1–11 节定义设计与验收契约，其中第 4 节记录指定实现基线的事实。 +第 12 节记录未决事项，建议答案不代表批准。附录保存来源证据。 +中英文是语义镜像。合并代表接受设计依据，不代表实现、性能、宿主资格或新默认值已经成立。 +带日期的交付证据进入 [RFC ledger](ledger/README.md)。 + +## 1. 决策摘要 + +LoopX 应保留一个小型治理内核，装配成 **minimal** 与 **standard** 两种预设。 +研究配置冻结某种装配及其实验改动，不产生第三套治理实现。 + +内核负责持久工作的准入与结算：Goal 要求、工作身份、claim/lease、预算、停止规则、 +effect 身份、receipt 与恢复。宿主负责模型和工具执行。Capability 提供任务策略与领域行为。 +前端通过同一套 owner 展示状态、提交操作。 + +“小”有四个独立维度：安装依赖、加载代码、激活服务、模型可见上下文。 +安装 standard 不应让每条命令都加载或启动全部能力。Minimal 仍必须能完成真实的受治理 +Turn，并在中断后恢复。 + +本 RFC 在既有发行拆分与统一工作契约下细化运行时装配，不重新命名它们的包， +不新增插件体系、Session 协议或路线图。现有默认行为、强制工作义务与 authority +持续生效，直到合格迁移明确改变它们。接受本设计不批准 benchmark 运行、设备操作或宿主晋级。 + +## 2. 问题与动机 + +简短的 CLI 读取不应初始化研究栈或 IM 服务。嵌入式 managed 任务不应依赖交互式 App Session。 +Standard 产品用户仍需要可理解的进展、干预、恢复，以及把结果送回原请求。 +Benchmark 需要测量同一份实现，同时避免引入无关产品服务或改变原生 evaluator。 + +只拆包无法满足这些要求：已安装依赖仍可能被提前导入，未使用服务仍可能轮询， +很小的二进制仍可能在每次模型调用发送过量上下文。单独的 loader 也无法提供 LoopX 的持久治理语义。 + +设计必须支持以下可观察旅程： + +| 旅程 | 必须得到的结果 | 对装配的要求 | +| --- | --- | --- | +| 有界 managed 任务 | 无交互 App 也能启动、执行、结算并回读结果 | Minimal 包含一条合格宿主路径与持久 authority | +| 长程研究 | 先产出有用的首个结果，持续工作后有证据支持的修订或新成果 | 规划、研究、记忆策略按需；进展不能只是时间变长或重复总结 | +| 两三个 peer 协作 | 证据返回协调者，记录采纳，中断后恢复所有权 | 复用工作/租约 authority；peer 生命周期与结果采纳分离 | +| App 或 IM 请求 | 暂停、纠正、继续，并在原目的地收到已验收结果 | 前端与交付 provider 围绕同一工作身份装配 | +| 硬件或外部操作 | 完成多步任务，核对不确定副作用，并在对应边界验证停止 | 显式激活的 operation provider 负责回读、联锁与安全重试 | +| 可复现 benchmark | 用原生对照与完整成本比较合格产品装配 | 冻结实验输入；原生 runner、verifier 与评分保留各自所有权 | + +这些是共享产品要求，不表示一次性交付所有旅程或组合。 +内容、办公与工程能力使用同样的边界，无须成为强制启动依赖。 + +### 不变量 + +- I1. 每个状态迁移与 effect 只有一个 authority；预设不能分叉它。 +- I2. 未选择的可选组件不得初始化、注册 timer、联网、执行 hook 或注入模型指令。 +- I3. 缺少执行前提时，dispatch 前给出可操作错误；不能降级到不受治理的执行路径。 +- I4. 必需上下文保持完整、新鲜；缩短 prompt 不能成为删除要求、required reads 或停止条件的授权。 +- I5. 重放先核对持久身份与外部证据，再决定重试；完成、结算、结果交付保持可区分。 +- I6. 性能与成果声明必须注明所测装配、基线、环境及范围。Help 加速不能证明任务效果提升。 + +## 3. 范围与非目标 + +范围包括：运行时所有权、显式装配、按需加载、上下文边界、benchmark 保真，以及产品旅程的分阶段资格验证。 + +非目标：新模型 loop、capability catalog、scheduler、记忆数据库、benchmark 原生 runner、 +存储迁移、设备抽象框架或微服务拆分。本提案不增加 CLI 参数、包或持久 schema，不删除存储字段。 +具体配置语法由后续实现按现有扩展与发行契约确定。 + +## 4. 当前系统契约 + +指定基线的 [entrypoint.py](../../../loopx/entrypoint.py) 已有轻量 version 路径和部分 +原生 scheduler 后续调用；[cli_runtime.py](../../../loopx/cli_runtime.py) 按所选命令分发， +其余命令仍走完整 parser。`performance-diagnosis` 无须 registry，但尚未进入 selected-command +集合。这提供了有界的首个加载接缝，不代表所有启动路径都已经延迟加载。 + +类型化领域 authority 正按 [TypeScript 迁移](typescript-control-plane-migration-v0.md) +集中到 [control_plane](../../../loopx/control_plane/)。Python 仍负责适配器和部分既有路径。 +新装配工作必须复用现有 owner，迁移前先刻画旧行为；不能在另一门语言里悄悄重建规则。 + +发行 RFC 负责 `loopx-core`、`loopx-workspace` 与可选包。 +[三层协议](../../reference/protocols/multi-agent-three-layer-minimality-v0.md) 的 “kernel” +指更宽的可复用层，包含 runner/展示设施。本文的 **治理内核** 指 authority 边界， +**启动依赖闭包** 指所选入口必需的代码。设施可以继续属于更宽的复用层，而不进入每个启动闭包。 + +Controller/Executor 统一 RFC 负责受治理工作契约。Session 模式负责 `managed_runtime` +与 `attached_host`。[DSH/Pi 选择 RFC](harness-selection-dsh-pi-v0.zh-CN.md) 负责宿主资格； +有界 headless adapter 与拥有 Session 的 runtime 职责不同。 +[Benchmark toolkit](../../../loopx/capabilities/benchmark_toolkit/README.md) 负责通用的权限、 +并发和完整性支持，[benchmark 政策](../../../benchmark/README.md) 把原生执行与评估留在 benchmark。 +本 RFC 不恢复第二个 launcher。 + +## 5. 提议架构 + +### 5.1 所有权与放置 + +| 边界 | Owner 与职责 | 不承担的职责 | +| --- | --- | --- | +| Bootstrap | 现有 entrypoint/CLI 路由；解析命令与已安装装配元数据 | Goal 决策、发现阶段激活 provider | +| 治理内核 | 现有类型化 Goal、work、quota、runtime、coordination owner；准入、迁移、effect、结算、恢复规则 | LLM/tool loop、任务策略、UI、传输、benchmark 评分 | +| 宿主执行 | 已准入的 managed 或 attached host provider；模型调用、工具、Session 生命周期、执行观测 | 第二份工作账本或独立权限 authority | +| Capability 策略 | 最近的结果型 capability；规划、上下文选择、研究、召回、评审 | 覆盖强制迁移、租约、停止或预算 | +| Extension 生命周期 | 现有 manifest、registry、兼容与激活机制 | 另一套通用插件/容器框架 | +| 产品界面 | Workspace、CLI、IM 或交付 provider 消费公开安全投影并提交命令 | 从私有源文件或展示文字推断规范状态 | + +放置理由：此处不引入新 capability id 或 provider id。核心治理属于 `control_plane`； +加载/生命周期机制属于现有入口与 `extensions`；benchmark 支持留在 `benchmark_toolkit`。 +后续可选宿主/设备集成在现有结果型 owner 足够时复用它，独立发行的 provider 放在 +`packages//`。新 capability 必须有真实、provider-neutral 的调用者契约， +不能仅因 bundle 可以安装就创建。 + +治理是逻辑边界，不要求把全部规则移入一个文件。保留内聚的类型化领域。 +Planner 可以建议工作或 stride，只有所属迁移规则决定准入与义务。 +替换策略不能把机器强制的 `must_attempt_work` 变成文字 guidance。 +改变此类默认值必须单独披露契约变化。 + +### 5.2 预设与独立维度 + +| 装配 | 必需内容 | 显式可选内容 | +| --- | --- | --- | +| Minimal | Bootstrap、现有治理实现、一个受支持的 authority provider、一条合格执行路径、紧凑状态/结果回读与恢复 | 任务能力、持久召回、observer、connector、workspace UI | +| Standard | 同一内核与面向普通使用的兼容产品装配 | 只为所选工作流激活 capability、宿主集成、UI/IM 服务与外部 connector | +| 研究配置 | 固定版本的 minimal 或 standard 装配及声明过的实验 overlay | 实验设计中明确列出的 instrumentation 或 ablation | + +Minimal 是受支持的完整执行装配，不是在已全部初始化的 standard 上加关闭开关。 +Kernel library 可以不带宿主做只读嵌入，但这不构成可执行 minimal 预设的资格。 +Standard 是便利装配，安装本身不授予激活或权限。发行 RFC 的迁移门槛通过前，安装行为保持现状。 + +以下维度保持独立：装配、managed/attached 模式、宿主 provider、一个/两个模型 Session、 +存储 provider、benchmark arm。尤其 minimal 不等于 attached，standard 不要求双模型 Session， +research 不等于不受治理。只发布已测组合。遵守 Session 模式 RFC 的默认值与显式准入； +改变装配不能静默改变 binding 的执行 owner。 + +### 5.3 解析、加载、激活、提供上下文 + +1. **解析：** 读取 build/install 或显式 extension 注册时生成的本地版本化元数据。 + 顶层 help、命令列表与未知命令拒绝不能扫描仓库、导入所有 provider 或联网。 + 重复注册、过期或不兼容元数据必须可见；优先级显式确定，不能依赖导入顺序。 +2. **加载：** 导入所选命令及其依赖闭包。详细命令 help 可以加载自身 parser，但不能激活执行服务。 + 可选导入留在所属路由之后，fallback 路径也须遵守。 +3. **激活：** 校验 installed/enabled/ready 状态及作用域权限，再经现有生命周期 owner 启动所需服务。 + 可选代码缺失时说明如何安装/启用；必需 authority 或 runtime 缺失时 fail closed。 + Kernel 导入/help 不要求 Node；有副作用命令保留发行 RFC 的类型化 `node_unavailable` 边界。 +4. **提供上下文：** 为所选工作和 executor 渲染现有受治理工作契约，复用统一 Controller/Executor + 设计的首次完整、后续差量与恢复语义。Required reads 和来源完整性仍有约束力。 + +相关来源/要求版本变化、Session generation 变化、compaction 或 ACK 丢失时，必须使上下文复用失效。 +不能因为 packet 更小，就认为 executor 已掌握前文。连续性未知时走所属契约的恢复路径。 +Capability 指令仅在适用时提供；authority 不能从 prompt 文字推导。 + +可选 observer 消费已提交事件或有界投影。除非现有契约明确要求它的 receipt， +其延迟不能进入准入/结算事务。只批处理尽力而为的 telemetry；不能为满足时间目标而延迟 +authority receipt 持久化、弱化 fsync/事务保证，或缓存过期权限/租约决策。 + +### 5.4 持久生命周期与外部副作用 + +通过统一工作契约使用既有 Goal/Agent/work/Turn 身份、revision、lease、effect id 与 receipt。 +解析装配，校验要求和 authority，准入工作，经绑定宿主执行，验证并持久化证据，结算一次， +再经所属 channel 交付/回读。各步骤使用既有合法迁移与重放规则；这段描述不新增竞争的 status enum +或事务协调者。 + +Executor 崩溃、effect ACK 丢失、结果交付 ACK 丢失是不同恢复情形。 +Operation provider 必须说明某个 effect 能否核对、能否安全重试。 +外部状态未知时，后续依赖操作须等待回读或人工干预；“未观测到”不等于“未执行”。 +设备幂等、物理联锁与补偿归 provider 负责，不能虚构为内核保证。 + +模型取消、进程终止、设备确认停止是不同事实。模型停止不能在缺少设备证据时生成 +“设备已停止”声明。需要持续监督的 provider，在 effect 尚未解决时不能卸载。 +结果验收、传输交付、用户回读也必须保留现有的不同证据。 + +### 5.5 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. 替代方案与设计选择 + +| 方案 | 决策与取舍 | +| --- | --- | +| 只拆包或加 lazy import | 可作为首批切片，但不足以定义激活、authority 和上下文边界 | +| Minimal 与 standard 各自一套引擎 | 拒绝：重复状态迁移，破坏产品/benchmark 一致性 | +| 所有规则都插件化 | 拒绝：预算、停止、租约、结算可能随预设消失 | +| 用上游 agent runtime 替代 LoopX 内核 | 拒绝：上游模型执行可以是 provider，但不能替代 LoopX 工作 authority | +| 强制统一 daemon 或远端服务 | 不要求：给有界本地使用增加生命周期与部署成本；daemon 仍按其现有 RFC 演进 | + +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。固定来源见附录 A。 + +## 7. 安全、隐私与兼容 + +装配不能把现有权限或强制门槛变成可选项。宿主可用、extension 已安装、runtime capability +声明都是观测，不是授权。每次 provider 调用保留 Goal、Agent、workspace 与 delivery 作用域； +凭据通过现有 provider 边界解析。公开投影排除私有源内容和本地工件。 + +不提议删除 schema/字段。按既有兼容窗口保留已知 reader/writer 和外部 import。 +未迁移 CLI 路由保留现有 fallback，直到替代路径通过命令一致性验证。 +不支持的版本/provider 组合在 dispatch 前拒绝；不能为了让混合版本看似可用而让一个 binding +同时存在两个 writer。 + +## 8. 迁移与回滚 + +先刻画 CLI parsing、输出、错误、required reads 与 effect 行为。 +一次迁移一个内聚路由并更新活跃调用者；真实调用者迁完后再删除内部 bridge。 +加载优化不能顺带迁移存储或降低持久性。 + +可执行 minimal 以 opt-in 引入，必须能显式回读解析后的装配。 +切换活跃 binding 前先检查兼容性，让其 owner 静止，并核对未完成 effect。 +恢复前验证新 owner 与回读；不能跨活跃 lease 热切换。 +回滚到旧的合格装配也先做同样核对，保留持久状态。 +后续任何不可逆数据变化都需要单独的迁移/导出门槛。 + +Standard 采用须通过下述产品旅程验收。 +只有全部受支持命令迁移，且 global options、help、错误、exit code 保持兼容后，才能移除完整 parser +fallback。默认值变化需要 release notes 与明确 owner 决策；本 RFC 不改变默认值。 + +## 9. 验证与验收 + +以下是拟定验收条件，不是已通过声明。确定性 fixture 根据语义独立设计，不能从当前实现输出反推期望。 +Live、性能和晋级证据分别记录。 + +| Id / 声明 | 测试或证据 | 必须得到的结果 | 边界 | +| --- | --- | --- | --- | +| A1 / 按需加载 | 两种预设下对 import、help、列表、未知命令、所选路由做导入/进程/网络追踪 | 只加载声明过的依赖闭包；无可选激活 | 不证明执行性能 | +| A2 / authority 一致性 | 对要求、过期 claim、停止、预算、重放、结算做刻画与负例测试 | 两种预设具有相同合法/非法迁移，只结算一次 | Minimal 不得绕过 authority | +| A3 / CLI 兼容 | 受支持命令的差分语料，含 fallback、Node/provider 缺失 | Parsing、输出契约、exit code 稳定，失败可操作 | 明确列出未迁移路由 | +| A4 / managed minimal | 一个真实 managed 任务、注入中断、重启、证据验证与结果回读 | 身份相同，effect 已核对，无重复工作或计费，已验收结果可获取 | 初期一个合格宿主即可；纯 mock 执行不够 | +| A5 / 上下文连续性 | 首次上下文、无变化续行、来源修订、compaction、ACK 丢失 | 必需上下文完整或明确恢复；拒绝过期上下文 | 单独测 token 减少 | +| A6 / standard 旅程 | 原始 App/IM 请求、纠正/暂停、继续、完成与返回 | 一个执行 owner；已验收结果和成本可见；目的地不静默改变 | 每个前端/provider 分别合格 | +| A7 / 研究与 peers | 有用首个结果后的证据性改善；owner 恢复后的 peer 结果返回与采纳 | 新成果或有理由的决策修订，并有可归属证据 | 更多时间、peer 或文字本身不能通过 | +| A8 / benchmark 保真 | 固定的匹配实验、native/passive/governed 边界、记忆隔离、完整成本账本 | 原生语义完整；C0–C4 证据遵守研究/诊断 owner | 本 RFC 不声称分数或因果收益 | +| A9 / 物理副作用 | 模拟器/故障注入，再做显式授权的 provider 专属 live 验证 | 核对丢失 ACK；在保证范围内防重复动作；独立确认设备停止 | 不承诺通用 exactly-once 或紧急停止 | +| A10 / 开销 | 指定环境中重复、成对测量冷进程与热路径 | 报告 median/p95、RSS、模块数、文件 I/O、Node 启动/IPC、字节与模型 token；持久性无退化 | M0 确定数字预算；CLI 基线无须付费任务运行 | + +本地开发候选目标为 p95：import 低于 50 ms、顶层 help 低于 100 ms、所选命令 help 低于 200 ms。 +它们是 D3 的建议，不是已验证结果或跨机器 CI 阈值。 +采用前要定义解释器启动、缓存条件、样本数、机器/runtime 版本。 +真实 status/admission/settlement 延迟须在有代表性的小/大状态上单独测量，包含 SQLite 竞争和恢复； +不能把 CLI-help 目标套在这些操作上，也不能减掉其必需 I/O。 + +## 10. 运维契约 + +回读应解释：解析后的装配及版本、所选宿主和 Session 模式、必需/可选 provider、激活/readiness， +以及加载某组件的原因。复用现有诊断/投影 owner，不新增状态数据库。 +前提缺失、元数据不兼容、authority 过期、effect 不确定必须保持可区分。 + +启动开销与 Turn 开销分别记录。可选 observer 故障应可见，但不能改写已提交执行结果； +强制 delivery 或证据 receipt 失败继续由所属 owner 治理。 +容量限制、背压归既有 work/host/provider 契约。运维恢复先核对持久 receipt 与 provider 回读，再继续执行。 + +## 11. 规范交付计划 + +以下切片归入既有路线图的 runtime、发行与产品工作流，不建立平行项目， +也不要求全仓重写后才能交付局部性能改善。 + +| 里程碑 | 交付行为 | 进入条件 | 退出证据 | 回滚 | +| --- | --- | --- | --- | --- | +| M0 / 一个加载接缝 | `performance-diagnosis` selected route 与实测加载边界 | 现有路由刻画；owner/依赖图；D3 测量决策 | 本路由的 A1/A3、A10 基线，无无关导入或行为变化 | 撤回路由提取 | +| M1 / 可执行 minimal | 一条合格 managed 受治理任务，含持久重启/结果回读 | D1 装配内容、D2 宿主/provider 选择；既有 authority 契约 | 此受支持组合的 A1–A5、A10 | 显式返回旧的合格装配 | +| M2 / standard 旅程 | Standard 解析同一内核，只激活所选产品工作流 | M1；现有 Session/前端准入 | A2/A5/A6/A10，含冷安装与功能关闭一致性 | 关闭 opt-in 装配并保留状态 | +| M3 / 研究资格 | 匹配的产品路径实验，以及一个长程/peer 旅程 | 所选界面的 M1 或 M2；冻结设计与单独运行授权 | A7/A8、完整成本与隐私检查、既有 C0–C4 门槛 | 停用实验 overlay，保留有界证据 | +| M4 / 外部操作 provider | 一个真实调用者，具备 provider 专属 effect 核对与停止证据 | D4；具名设备/操作 owner 与显式操作授权 | A9 加继承的治理门槛 | 停用前先静止并核对 provider | + +M0 不代表内核合格。M3、M4 是可选资格分支，不必阻塞已合格的 CLI 或 managed 任务。 +真实调用者出现前，不加入闲置 provider、配置字段、框架或通用测试矩阵。 +每个 PR 记录考虑、应用或推迟的有界重构及兼容证据。 + +## 12. 未决事项 + +| Id / owner | 选项与建议 | 所需证据 / 决策点 | +| --- | --- | --- | +| D1 / 发行与 runtime 维护者 | 将预设映射到已接受的发行方案；建议 minimal 先 opt-in，standard 最终承接兼容装配，当前不选择新默认值 | M1 打包前给出精确安装/加载/激活闭包及升级/回读契约 | +| D2 / 宿主与 authority 维护者 | 从既有 provider 选择首个 managed 宿主与受支持存储组合；建议最小且已满足资格的路径，DSH/Pi 仍按既有选择 RFC 评估 | M1 退出前给出 A4 宿主/Session 连续性与 authority 恢复证据；不声称所有宿主合格 | +| D3 / 性能维护者 | 采用机器相关 p95 预算或相对回归界限；建议候选预算加明确测量条件 | M0 退出前提供可复现基线；真实 Turn 预算独立推导 | +| D4 / operation-provider owner | 选择一个具体外部操作调用者，或推迟物理资格；建议真实调用者出现前不做通用设备框架 | M4 前确定范围、幂等/回读/停止契约及授权 | + +批准必须经相应评审决策记录；建议、实现进展或沉默都不能关闭未决事项。 + +## 附录 A：来源证据（非规范） + +| 证据 | 固定来源 | 支持的声明与限制 | +| --- | --- | --- | +| E1 / LoopX | 上述实现基线；第 4 节链接的入口、CLI 与所属契约 | 仅证明现有接缝与所有权；没有新性能测量 | +| E2 / DSH | [`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 宿主资格或权限建议 | +| E3 / Pi | [`agent` core](https://github.com/badlogic/pi-mono/blob/f14813e96510a7cf7562a120e809c6a134af073d/packages/agent/README.md) | Agent/tool/event core，以及 `transformContext`、`convertToLlm`、`prepareRequest`、`finishTurn` 接缝；无 LoopX authority 或性能声明 | + +本提案没有执行 live benchmark 或硬件操作。 From d3fa3d5d6fe8488e32c715211c1fc387a9880f79 Mon Sep 17 00:00:00 2001 From: "lusendong.6789" Date: Thu, 29 Oct 2026 22:14:27 +0800 Subject: [PATCH 2/3] docs(rfc): unify distribution and runtime composition design Signed-off-by: lusendong.6789 Co-authored-by: TRAE CLI --- docs/architecture/rfcs/README.md | 22 +- docs/architecture/rfcs/STATUS.md | 5 +- docs/architecture/rfcs/STATUS.zh-CN.md | 5 +- .../rfcs/monorepo-distribution-split-v0.md | 316 +++++++++++++- .../monorepo-distribution-split-v0.zh-CN.md | 239 ++++++++++- .../small-kernel-runtime-composition-v0.md | 390 ------------------ ...all-kernel-runtime-composition-v0.zh-CN.md | 310 -------------- 7 files changed, 544 insertions(+), 743 deletions(-) delete mode 100644 docs/architecture/rfcs/small-kernel-runtime-composition-v0.md delete mode 100644 docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index dabfa3e944..ba739fedeb 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -150,23 +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. - -- [Small Kernel and Runtime Composition v0](small-kernel-runtime-composition-v0.md) - ([中文版](small-kernel-runtime-composition-v0.zh-CN.md)) - - **Delivery on `main`:** Proposal only; no runtime or default change. - - **Current boundary:** One governance implementation, minimal/standard - composition and frozen research configurations. Defines demand loading, - activation and context boundaries, product/benchmark parity, and staged - managed-task, product-journey and external-operation qualification under - the existing distribution and controller/executor contracts. + - **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 e953bbb5ff..035ecd07c1 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -18,7 +18,7 @@ appendix may keep dated history, but no dated log heading may precede it. [中文版](STATUS.zh-CN.md) is the semantic mirror of this file. -## Accepted (48) +## Accepted (47) | RFC | Header status | Supersedes / closes | Ledger | | --- | --- | --- | --- | @@ -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 | — | @@ -68,7 +68,6 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Shared Goal Alignment and Governed Amendment Protocol (v0)](shared-goal-alignment-and-governed-amendment-v0.md) | Accepted | none | [2 entries](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC: LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.md) | Accepted | none | [24 entries](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | Accepted | none | — | -| [RFC: Small Kernel and Runtime Composition (v0)](small-kernel-runtime-composition-v0.md) | Accepted | none | — | | [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [18 entries](ledger/typescript-control-plane-migration-v0/) | ## Superseded (1) diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index db75be9956..a0b1ad1601 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -15,7 +15,7 @@ [English](STATUS.md) 与本文互为语义镜像。 -## 已接受 (48) +## 已接受 (47) | RFC | 头部状态 | 替代 / 关闭 | Ledger | | --- | --- | --- | --- | @@ -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) | 已接受 | 无 | — | @@ -65,7 +65,6 @@ | [RFC：共享 Goal 对齐与受治理 Amendment 协议（v0）](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md) | 已接受 | 无 | [2 条](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC：LoopX 共享控制面权威与可插拔状态 Provider（v0）](shared-goal-authority-state-provider-v0.zh-CN.md) | 已接受 | 无 | [24 条](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | 已接受 | none | — | -| [RFC：小内核与运行时装配（v0）](small-kernel-runtime-composition-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC：LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [18 条](ledger/typescript-control-plane-migration-v0/) | ## 已被替代 (1) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 4491ef8fa3..73b81b572b 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,21 @@ 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. | + +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 +480,12 @@ 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. + ## 8. Migration and rollback | Step | Gate | Rollback | @@ -280,8 +497,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 +519,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 +556,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 R1 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 | M3, R1; existing frontend/session admission | V2/V5/V6/V10, cold install and feature-off parity | 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 +596,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 +607,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 +705,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..e0c5fa89a9 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,17 @@ 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。 | + +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 +334,10 @@ 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 前拒绝。 + ## 8. 迁移与回滚 | 步骤 | 门禁 | 回滚 | @@ -186,7 +349,12 @@ capability 包直接采用现有 `extension.toml` 契约，不做扩展。唯一 | capability 包迁移 | 逐个 capability，内核调用方清单已解决 | revert 单个包 | | 移除 shim | 迁移后一个 minor 版本；弃用记入 update notes | 不适用；需调用方迁移 | -任何步骤都不需要数据迁移，因为没有规范记录改变。 +切换活跃 binding 的装配前，检查兼容、让执行 owner 静止并核对未完成 effect。 +继续前验证新 owner 与解析后的装配；不能跨活跃 lease 热切换。回滚同样先核对并保留持久状态。 +后续不可逆数据变化须另设迁移/导出门槛。 + +这些结构/装配变化的回滚不需要数据迁移。默认值变化须有明确 owner 决策与 release notes； +本提案不改变现有默认值。 ## 9. 验证与验收 @@ -200,7 +368,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 +399,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 | 撤下预发布 | +| R1 | Opt-in 可执行 minimal，含一个真实 managed Turn、重启与结果回读 | R0；所选 D2 内容和 D5 宿主/authority；可先于 M3 验证源码装配 | 此受支持组合的 V1–V5/V10；源码证据本身不代表拆包安装合格 | 核对后返回旧合格装配 | +| R2 | Standard 使用同一内核，只激活所选产品工作流 | M3、R1；现有前端/Session 准入 | V2/V5/V6/V10、冷安装与关闭一致性 | 关闭 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 +508,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：被拒绝或被取代的备选 diff --git a/docs/architecture/rfcs/small-kernel-runtime-composition-v0.md b/docs/architecture/rfcs/small-kernel-runtime-composition-v0.md deleted file mode 100644 index df51db33ff..0000000000 --- a/docs/architecture/rfcs/small-kernel-runtime-composition-v0.md +++ /dev/null @@ -1,390 +0,0 @@ -# RFC: Small Kernel and Runtime Composition (v0) - -- **RFC status:** Accepted, design acceptance takes effect on merge -- **Supersedes / closes:** none -- **Delivery maturity:** Proposal -- **Authors / owners:** LoopX maintainers -- **Created:** 2026-10-29 -- **Last normative revision:** 2026-10-29 -- **Implementation baseline:** `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` -- **Related contracts:** [Distribution split](monorepo-distribution-split-v0.md), [Unified controller/executor contract](controller-executor-unified-contract-v0.md), [Session execution modes](agent-session-execution-modes-v0.md), [Overall roadmap](loopx-overall-roadmap-v0.md), [Extensions](../../reference/extensions.md) -- **Language mirror:** [中文版](small-kernel-runtime-composition-v0.zh-CN.md) - -## Document map and maintenance contract - -Sections 1–11 define the design and acceptance contract; section 4 records the -named implementation baseline. Section 12 records unresolved decisions, whose -recommendations are not approval. The appendix contains source evidence. -English and Chinese are semantic mirrors. Merge accepts a design basis; it -does not establish implementation, performance, host qualification or a new -default. Dated delivery evidence belongs in the [RFC ledger](ledger/README.md). - -## 1. Decision summary - -LoopX should have one small governance kernel, composed into **minimal** and -**standard** presets. A research configuration freezes a composition and its -experimental changes; it does not create a third governance implementation. - -The kernel owns durable work admission and settlement: Goal requirements, -work identity, claims/leases, budget, stop rules, effect identity, receipts and -recovery. Hosts own model/tool execution. Capabilities supply task strategies -and domain behavior. Frontends display and submit through these same owners. - -Smallness has four independent meanings: installed dependencies, loaded code, -activated services, and model-visible context. Installing standard must not -make every command load or start every capability. Minimal must still perform -a real governed Turn and recover it after interruption. - -This RFC refines runtime composition under the existing distribution split -and unified work contract. It neither renames their packages nor adds another -plugin system, session protocol or roadmap. Existing defaults, mandatory work -obligations and authority remain in force until a qualified migration changes -them explicitly. No benchmark, device operation or host promotion is approved -by accepting this design. - -## 2. Problem and motivation - -A short CLI read should not initialize a research stack or an IM service. An -embedded managed task should not need an App session. A standard product user -still needs understandable progress, intervention, recovery and delivery back -to the original request. A benchmark needs to measure that same implementation -without importing unrelated product services or changing the native evaluator. - -Package splitting alone cannot meet these needs: an installed dependency can -still be eagerly imported, an unused service can still poll, and a small -binary can still send excessive context on every model call. Conversely, a -loader alone cannot provide LoopX's durable governance semantics. - -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. Each state transition and effect has one authority; presets cannot fork it. -- I2. Omitting an optional component causes no initialization, timer, network - call, hook or model instruction from that component. -- I3. A missing execution prerequisite fails with actionable context before - dispatch; it never falls back to an ungoverned execution path. -- I4. Required context remains complete and fresh; smaller prompts do not - authorize dropping requirements, required reads or stop conditions. -- I5. Replay reconciles durable identity and external evidence before retry; - completion, settlement and result delivery remain distinguishable. -- I6. Performance and outcome claims name the measured composition, baseline, - environment and scope. Faster help is not evidence of better task outcomes. - -## 3. Scope and non-goals - -In scope: runtime ownership, explicit composition, demand loading, context -boundaries, benchmark fidelity and staged qualification for product journeys. - -Non-goals: a new model loop, capability catalog, scheduler, memory database, -benchmark-native runner, storage migration, device abstraction framework or -microservice split. This proposal adds no CLI flag, package or persisted schema. -It removes no stored field. Actual configuration syntax is an implementation -decision under the existing extension and distribution contracts. - -## 4. Current-system contract - -On the named baseline, [entrypoint.py](../../../loopx/entrypoint.py) has a small -version route and selected native scheduler follow-ups; -[cli_runtime.py](../../../loopx/cli_runtime.py) dispatches selected commands and -retains the full-parser path for other commands. `performance-diagnosis` is -registry-optional but is not in the selected-command set. This supplies a -bounded first loading seam; it is not evidence that all startup is already lazy. - -Typed domain authority is being consolidated under -[control_plane](../../../loopx/control_plane/) according to the -[TypeScript migration](typescript-control-plane-migration-v0.md). Python still -owns adapters and some existing paths. New composition work must use the -existing owner and characterize legacy behavior before moving it; it must not -silently recreate rules in a second language. - -The distribution RFC owns `loopx-core`, `loopx-workspace` and optional packages. -The [three-layer protocol](../../reference/protocols/multi-agent-three-layer-minimality-v0.md) -uses “kernel” for a broader reusable layer including runner/presentation -facilities. Here, **governance kernel** means the authority boundary, while -**boot closure** means code required by a selected entrypoint. A reusable -facility can remain in that broader layer without belonging to every boot closure. - -The unified controller/executor RFC owns the governed work contract. Session -modes own `managed_runtime` versus `attached_host`. The -[DSH/Pi selection RFC](harness-selection-dsh-pi-v0.md) owns host qualification; -a bounded headless adapter and a session-owning runtime have different duties. -[Benchmark toolkit](../../../loopx/capabilities/benchmark_toolkit/README.md) -owns reusable permission, concurrency and integrity support, while -[benchmark policy](../../../benchmark/README.md) keeps native execution and -evaluation with the benchmark. This RFC does not restore a second launcher. - -## 5. Proposed architecture - -### 5.1 Ownership and placement - -| Boundary | Owner and responsibility | Excluded responsibility | -| --- | --- | --- | -| Bootstrap | Existing entrypoint/CLI route; resolve command and installed composition metadata | Goal decisions, provider activation during discovery | -| Governance kernel | Existing typed Goal, work, quota, runtime and coordination owners; admission, transition, effect, settlement and recovery rules | LLM/tool loop, task strategy, UI, transport, benchmark scoring | -| Host execution | Admitted managed or attached host provider; model calls, tools, session lifecycle and execution observations | A second work ledger or independent permission authority | -| Capability strategy | Nearest outcome capability; planning, context selection, research, recall, review | Overriding required transitions, leases, stop or budget | -| Extension lifecycle | Existing manifest, registry, compatibility and activation machinery | Another generic plugin/container framework | -| Product surface | Workspace, CLI, IM or delivery provider consumes public-safe projections and submits commands | Inferring canonical state from private source files or display text | - -Placement rationale: no new capability id or provider id is introduced here. -Core governance belongs to `control_plane`; loading/lifecycle mechanics belong -to existing entrypoints and `extensions`; benchmark support stays with -`benchmark_toolkit`. A later optional host/device integration uses an existing -outcome owner when sufficient, with its independently distributed provider in -`packages//`. A new capability requires a real provider-neutral -caller contract, not merely an installable bundle. - -Governance is a logical boundary, not a request to move every rule into one -file. Keep cohesive typed domains. A planner may recommend work or a stride; -only the owning transition decides admission and obligations. Replacing a -strategy must not turn a machine-enforced `must_attempt_work` rule into prose -guidance. Changing such a default requires its own disclosed contract change. - -### 5.2 Presets and independent axes - -| Composition | Required content | Explicit optional content | -| --- | --- | --- | -| Minimal | Bootstrap, existing 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 | The same kernel and compatible product composition for ordinary use | Activate capabilities, host integration, UI/IM services and external connectors only for the chosen workflow | -| Research configuration | A pinned minimal or standard composition plus a declared experiment overlay | Instrumentation or ablations explicitly named in the experimental design | - -Minimal is a supported end-to-end composition, not a disabling flag on a -fully initialized standard runtime. A kernel library may be used for read-only -embedding without a host, but that does not qualify the executable minimal preset. -Standard is a convenience composition; installation alone grants no activation -or permission. Existing installation behavior remains until the distribution -RFC's migration gates are met. - -Keep these axes independent: composition; managed/attached mode; host provider; -one/two model sessions; storage provider; benchmark arm. In particular, minimal -does not mean “attached,” standard does not require two model sessions, and -research does not mean “ungoverned.” Publish only tested combinations. Preserve -the session-mode RFC's defaults and explicit mode admission; do not silently -change a binding's execution owner when changing composition. - -### 5.3 Resolve, load, activate, provide 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 the distribution 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. - -### 5.4 Durable 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. - -### 5.5 Benchmark uses the product implementation - -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 | Decision and trade-off | -| --- | --- | -| Only split packages or add lazy imports | Useful first slices; insufficient to define activation, authority and context boundaries | -| Separate minimal and standard engines | Rejected: duplicates transitions and invalidates product/benchmark parity | -| Make every rule a plugin | Rejected: budget, stop, lease and settlement could disappear with a preset | -| Adopt an upstream agent runtime as the LoopX kernel | Rejected: upstream model execution can be a provider, but does not replace LoopX work authority | -| One mandatory daemon or remote service | Not required: adds lifecycle and deployment cost to bounded local use; any daemon remains under its existing RFC | - -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 A. - -## 7. Safety, privacy, and compatibility - -No existing permission or mandatory gate becomes optional through composition. -Host availability, extension installation and runtime capability declarations -are observations, not grants. Keep Goal, Agent, workspace and delivery scopes -through every provider call; resolve secrets through the existing provider -boundary. Public projections exclude private source content and local artifacts. - -No schema/field removal is proposed. Preserve known readers/writers and external -imports for their documented compatibility windows. Unmigrated CLI routes keep -the existing fallback until command parity qualifies their replacement. Reject -unsupported version/provider combinations before dispatch; never run two writers -against one binding to make mixed-version rollout appear available. - -## 8. Migration and rollback - -First characterize CLI parsing, output, errors, required reads and effect -behavior. Move one cohesive route and update active callers; remove an internal -bridge only after its real callers migrate. Do not migrate storage or weaken -durability as a side effect of loading work. - -Introduce executable minimal as opt-in with an explicit resolved composition -readback. Before switching an active binding, check compatibility, quiesce its -owner and reconcile outstanding effects. Validate the new owner/readback before -resuming; never hot-swap across an active lease. Roll back to the previous -qualified composition after the same reconciliation. Keep durable state intact. -Any later irreversible data change needs a separate migration/export gate. - -Standard adoption requires the product journey gates below. Retire the full -parser fallback only after all supported commands have migrated and global -options, help, errors and exit codes preserve compatibility. Default changes -require release notes and an explicit owner decision; this RFC makes none. - -## 9. Validation and acceptance - -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 | -| --- | --- | --- | --- | -| A1 / 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 | -| A2 / 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 | -| A3 / 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 | -| A4 / managed minimal | One real managed task, injected interruption, restart, evidence validation and result readback | Same identity, reconciled effect, no duplicate work or charge; accepted result reachable | One qualified host is enough initially; mock-only execution is insufficient | -| A5 / 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 | -| A6 / 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 | -| A7 / 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 | -| A8 / 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 | -| A9 / 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 | -| A10 / 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 | M0 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 D3 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 - -Readback should explain the resolved composition and versions, selected host -and session mode, required versus optional providers, activation/readiness and -the reason a component was loaded. Reuse current diagnostics/projection owners; -do not introduce another status database. Missing prerequisites, incompatible -metadata, stale authority and uncertain effects must remain distinguishable. - -Record startup and Turn overhead separately. Optional observer failure is -visible without rewriting committed execution results; mandatory delivery or -evidence receipt failure remains governed by its owner. Capacity limits and -backpressure belong to the existing work/host/provider contracts. Operator -recovery reconciles persisted receipts and provider readback before resuming. - -## 11. Normative delivery plan - -These slices fit the existing roadmap's runtime, distribution and product -streams; they do not establish a parallel program or require a repository-wide -rewrite before a local performance improvement can ship. - -| Milestone | Shipped behavior | Entry gate | Exit evidence | Rollback | -| --- | --- | --- | --- | --- | -| M0 / one loading seam | Selected `performance-diagnosis` route and measured loading boundary | Current-route characterization; owner/dependency map; D3 measurement decision | A1/A3 for this route, A10 baseline, no unrelated imports or behavior change | Revert route extraction | -| M1 / executable minimal | One qualified managed governed task with durable restart/result readback | D1 composition contents and D2 host/provider choice; existing authority contracts | A1–A5 and A10 for this supported combination | Explicit return to previous qualified composition | -| M2 / standard journey | Standard resolves the same kernel and activates only a chosen product workflow | M1; existing session/frontend admission | A2/A5/A6/A10 including cold install and feature-off parity | Disable the opt-in composition and retain state | -| M3 / research qualification | Matched product-path experiment and one long-horizon/peer journey | M1 or M2 for the selected surface; frozen design and separate run authorization | A7/A8, complete cost and privacy review, existing C0–C4 gates | Retire experimental overlay; retain bounded evidence | -| M4 / external operation provider | One real caller with provider-specific effect reconciliation and stop evidence | D4; named device/operation owner and explicit operation authorization | A9 plus inherited governance gates | Quiesce/reconcile provider before disabling | - -M0 does not qualify the kernel. M3 and M4 are optional qualification branches; -they need not block a qualified CLI or managed task. No unused provider, -configuration field, framework or generic test matrix is added ahead of its -first real caller. Each PR records the bounded refactor considered, applied -or deferred and its compatibility evidence. - -## 12. Open decisions - -| Id / owner | Options and recommendation | Evidence needed / decision point | -| --- | --- | --- | -| D1 / distribution and runtime maintainers | Map presets to the accepted distribution scheme; recommend opt-in minimal and standard as the eventual compatibility composition, without choosing a new default now | Exact installed/load/activation closures and upgrade/readback contract before M1 packaging | -| D2 / host and authority maintainers | Select the first managed host and supported storage combination from existing providers; recommend the smallest already qualifying path, with DSH/Pi judged by the existing selection RFC | A4 host/session continuity and authority recovery evidence before M1 exit; no universal host claim | -| D3 / performance maintainers | Adopt machine-specific p95 budgets or relative regression limits; recommend the candidate budgets plus explicit measurement conditions | Reproducible baseline before M0 exit; real Turn budget derived independently | -| D4 / operation-provider owner | Choose one concrete external-operation caller, or defer physical qualification; recommend no generic device framework before a caller exists | Scope, idempotency/readback/stop contract and authorization before M4 | - -Approval must be recorded through the corresponding reviewed decision; a -recommendation, implementation progress or silence cannot close a decision. - -## Appendix A: Source evidence (non-normative) - -| Evidence | Pinned source | Supported claim and limit | -| --- | --- | --- | -| E1 / LoopX | Implementation baseline above; linked entrypoint, CLI and owning contracts in section 4 | Existing seams and ownership only; no new performance measurement | -| E2 / DSH | [`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) | Shared preset composition and a self-contained SDK bundle; not a LoopX host qualification or permission recommendation | -| E3 / Pi | [`agent` core](https://github.com/badlogic/pi-mono/blob/f14813e96510a7cf7562a120e809c6a134af073d/packages/agent/README.md) | Agent/tool/event core with `transformContext`, `convertToLlm`, `prepareRequest` and `finishTurn` seams; no LoopX authority or performance claim | - -No live benchmark or hardware operation was performed for this proposal. diff --git a/docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md b/docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md deleted file mode 100644 index 210b309989..0000000000 --- a/docs/architecture/rfcs/small-kernel-runtime-composition-v0.zh-CN.md +++ /dev/null @@ -1,310 +0,0 @@ -# RFC：小内核与运行时装配（v0） - -- **RFC status:** Accepted, design acceptance takes effect on merge -- **替代 / 关闭：** 无 -- **Delivery maturity:** Proposal -- **作者 / 负责人：** LoopX 维护者 -- **创建日期：** 2026-10-29 -- **最近规范修订：** 2026-10-29 -- **实现基线：** `9cae3b28939f72fa4aadab5cfe49e19bcbdab372` -- **相关契约：** [发行拆分](monorepo-distribution-split-v0.zh-CN.md)、[Controller/Executor 统一契约](controller-executor-unified-contract-v0.zh-CN.md)、[Session 执行模式](agent-session-execution-modes-v0.zh-CN.md)、[总体路线图](loopx-overall-roadmap-v0.zh-CN.md)、[扩展机制](../../reference/extensions.md) -- **Language mirror:** [English](small-kernel-runtime-composition-v0.md) - -## 文档地图与维护契约 - -第 1–11 节定义设计与验收契约，其中第 4 节记录指定实现基线的事实。 -第 12 节记录未决事项，建议答案不代表批准。附录保存来源证据。 -中英文是语义镜像。合并代表接受设计依据，不代表实现、性能、宿主资格或新默认值已经成立。 -带日期的交付证据进入 [RFC ledger](ledger/README.md)。 - -## 1. 决策摘要 - -LoopX 应保留一个小型治理内核，装配成 **minimal** 与 **standard** 两种预设。 -研究配置冻结某种装配及其实验改动，不产生第三套治理实现。 - -内核负责持久工作的准入与结算：Goal 要求、工作身份、claim/lease、预算、停止规则、 -effect 身份、receipt 与恢复。宿主负责模型和工具执行。Capability 提供任务策略与领域行为。 -前端通过同一套 owner 展示状态、提交操作。 - -“小”有四个独立维度：安装依赖、加载代码、激活服务、模型可见上下文。 -安装 standard 不应让每条命令都加载或启动全部能力。Minimal 仍必须能完成真实的受治理 -Turn，并在中断后恢复。 - -本 RFC 在既有发行拆分与统一工作契约下细化运行时装配，不重新命名它们的包， -不新增插件体系、Session 协议或路线图。现有默认行为、强制工作义务与 authority -持续生效，直到合格迁移明确改变它们。接受本设计不批准 benchmark 运行、设备操作或宿主晋级。 - -## 2. 问题与动机 - -简短的 CLI 读取不应初始化研究栈或 IM 服务。嵌入式 managed 任务不应依赖交互式 App Session。 -Standard 产品用户仍需要可理解的进展、干预、恢复，以及把结果送回原请求。 -Benchmark 需要测量同一份实现，同时避免引入无关产品服务或改变原生 evaluator。 - -只拆包无法满足这些要求：已安装依赖仍可能被提前导入，未使用服务仍可能轮询， -很小的二进制仍可能在每次模型调用发送过量上下文。单独的 loader 也无法提供 LoopX 的持久治理语义。 - -设计必须支持以下可观察旅程： - -| 旅程 | 必须得到的结果 | 对装配的要求 | -| --- | --- | --- | -| 有界 managed 任务 | 无交互 App 也能启动、执行、结算并回读结果 | Minimal 包含一条合格宿主路径与持久 authority | -| 长程研究 | 先产出有用的首个结果，持续工作后有证据支持的修订或新成果 | 规划、研究、记忆策略按需；进展不能只是时间变长或重复总结 | -| 两三个 peer 协作 | 证据返回协调者，记录采纳，中断后恢复所有权 | 复用工作/租约 authority；peer 生命周期与结果采纳分离 | -| App 或 IM 请求 | 暂停、纠正、继续，并在原目的地收到已验收结果 | 前端与交付 provider 围绕同一工作身份装配 | -| 硬件或外部操作 | 完成多步任务，核对不确定副作用，并在对应边界验证停止 | 显式激活的 operation provider 负责回读、联锁与安全重试 | -| 可复现 benchmark | 用原生对照与完整成本比较合格产品装配 | 冻结实验输入；原生 runner、verifier 与评分保留各自所有权 | - -这些是共享产品要求，不表示一次性交付所有旅程或组合。 -内容、办公与工程能力使用同样的边界，无须成为强制启动依赖。 - -### 不变量 - -- I1. 每个状态迁移与 effect 只有一个 authority；预设不能分叉它。 -- I2. 未选择的可选组件不得初始化、注册 timer、联网、执行 hook 或注入模型指令。 -- I3. 缺少执行前提时，dispatch 前给出可操作错误；不能降级到不受治理的执行路径。 -- I4. 必需上下文保持完整、新鲜；缩短 prompt 不能成为删除要求、required reads 或停止条件的授权。 -- I5. 重放先核对持久身份与外部证据，再决定重试；完成、结算、结果交付保持可区分。 -- I6. 性能与成果声明必须注明所测装配、基线、环境及范围。Help 加速不能证明任务效果提升。 - -## 3. 范围与非目标 - -范围包括：运行时所有权、显式装配、按需加载、上下文边界、benchmark 保真，以及产品旅程的分阶段资格验证。 - -非目标：新模型 loop、capability catalog、scheduler、记忆数据库、benchmark 原生 runner、 -存储迁移、设备抽象框架或微服务拆分。本提案不增加 CLI 参数、包或持久 schema，不删除存储字段。 -具体配置语法由后续实现按现有扩展与发行契约确定。 - -## 4. 当前系统契约 - -指定基线的 [entrypoint.py](../../../loopx/entrypoint.py) 已有轻量 version 路径和部分 -原生 scheduler 后续调用；[cli_runtime.py](../../../loopx/cli_runtime.py) 按所选命令分发， -其余命令仍走完整 parser。`performance-diagnosis` 无须 registry，但尚未进入 selected-command -集合。这提供了有界的首个加载接缝，不代表所有启动路径都已经延迟加载。 - -类型化领域 authority 正按 [TypeScript 迁移](typescript-control-plane-migration-v0.md) -集中到 [control_plane](../../../loopx/control_plane/)。Python 仍负责适配器和部分既有路径。 -新装配工作必须复用现有 owner，迁移前先刻画旧行为；不能在另一门语言里悄悄重建规则。 - -发行 RFC 负责 `loopx-core`、`loopx-workspace` 与可选包。 -[三层协议](../../reference/protocols/multi-agent-three-layer-minimality-v0.md) 的 “kernel” -指更宽的可复用层，包含 runner/展示设施。本文的 **治理内核** 指 authority 边界， -**启动依赖闭包** 指所选入口必需的代码。设施可以继续属于更宽的复用层，而不进入每个启动闭包。 - -Controller/Executor 统一 RFC 负责受治理工作契约。Session 模式负责 `managed_runtime` -与 `attached_host`。[DSH/Pi 选择 RFC](harness-selection-dsh-pi-v0.zh-CN.md) 负责宿主资格； -有界 headless adapter 与拥有 Session 的 runtime 职责不同。 -[Benchmark toolkit](../../../loopx/capabilities/benchmark_toolkit/README.md) 负责通用的权限、 -并发和完整性支持，[benchmark 政策](../../../benchmark/README.md) 把原生执行与评估留在 benchmark。 -本 RFC 不恢复第二个 launcher。 - -## 5. 提议架构 - -### 5.1 所有权与放置 - -| 边界 | Owner 与职责 | 不承担的职责 | -| --- | --- | --- | -| Bootstrap | 现有 entrypoint/CLI 路由；解析命令与已安装装配元数据 | Goal 决策、发现阶段激活 provider | -| 治理内核 | 现有类型化 Goal、work、quota、runtime、coordination owner；准入、迁移、effect、结算、恢复规则 | LLM/tool loop、任务策略、UI、传输、benchmark 评分 | -| 宿主执行 | 已准入的 managed 或 attached host provider；模型调用、工具、Session 生命周期、执行观测 | 第二份工作账本或独立权限 authority | -| Capability 策略 | 最近的结果型 capability；规划、上下文选择、研究、召回、评审 | 覆盖强制迁移、租约、停止或预算 | -| Extension 生命周期 | 现有 manifest、registry、兼容与激活机制 | 另一套通用插件/容器框架 | -| 产品界面 | Workspace、CLI、IM 或交付 provider 消费公开安全投影并提交命令 | 从私有源文件或展示文字推断规范状态 | - -放置理由：此处不引入新 capability id 或 provider id。核心治理属于 `control_plane`； -加载/生命周期机制属于现有入口与 `extensions`；benchmark 支持留在 `benchmark_toolkit`。 -后续可选宿主/设备集成在现有结果型 owner 足够时复用它，独立发行的 provider 放在 -`packages//`。新 capability 必须有真实、provider-neutral 的调用者契约， -不能仅因 bundle 可以安装就创建。 - -治理是逻辑边界，不要求把全部规则移入一个文件。保留内聚的类型化领域。 -Planner 可以建议工作或 stride，只有所属迁移规则决定准入与义务。 -替换策略不能把机器强制的 `must_attempt_work` 变成文字 guidance。 -改变此类默认值必须单独披露契约变化。 - -### 5.2 预设与独立维度 - -| 装配 | 必需内容 | 显式可选内容 | -| --- | --- | --- | -| Minimal | Bootstrap、现有治理实现、一个受支持的 authority provider、一条合格执行路径、紧凑状态/结果回读与恢复 | 任务能力、持久召回、observer、connector、workspace UI | -| Standard | 同一内核与面向普通使用的兼容产品装配 | 只为所选工作流激活 capability、宿主集成、UI/IM 服务与外部 connector | -| 研究配置 | 固定版本的 minimal 或 standard 装配及声明过的实验 overlay | 实验设计中明确列出的 instrumentation 或 ablation | - -Minimal 是受支持的完整执行装配，不是在已全部初始化的 standard 上加关闭开关。 -Kernel library 可以不带宿主做只读嵌入，但这不构成可执行 minimal 预设的资格。 -Standard 是便利装配，安装本身不授予激活或权限。发行 RFC 的迁移门槛通过前，安装行为保持现状。 - -以下维度保持独立：装配、managed/attached 模式、宿主 provider、一个/两个模型 Session、 -存储 provider、benchmark arm。尤其 minimal 不等于 attached，standard 不要求双模型 Session， -research 不等于不受治理。只发布已测组合。遵守 Session 模式 RFC 的默认值与显式准入； -改变装配不能静默改变 binding 的执行 owner。 - -### 5.3 解析、加载、激活、提供上下文 - -1. **解析：** 读取 build/install 或显式 extension 注册时生成的本地版本化元数据。 - 顶层 help、命令列表与未知命令拒绝不能扫描仓库、导入所有 provider 或联网。 - 重复注册、过期或不兼容元数据必须可见；优先级显式确定，不能依赖导入顺序。 -2. **加载：** 导入所选命令及其依赖闭包。详细命令 help 可以加载自身 parser，但不能激活执行服务。 - 可选导入留在所属路由之后，fallback 路径也须遵守。 -3. **激活：** 校验 installed/enabled/ready 状态及作用域权限，再经现有生命周期 owner 启动所需服务。 - 可选代码缺失时说明如何安装/启用；必需 authority 或 runtime 缺失时 fail closed。 - Kernel 导入/help 不要求 Node；有副作用命令保留发行 RFC 的类型化 `node_unavailable` 边界。 -4. **提供上下文：** 为所选工作和 executor 渲染现有受治理工作契约，复用统一 Controller/Executor - 设计的首次完整、后续差量与恢复语义。Required reads 和来源完整性仍有约束力。 - -相关来源/要求版本变化、Session generation 变化、compaction 或 ACK 丢失时，必须使上下文复用失效。 -不能因为 packet 更小，就认为 executor 已掌握前文。连续性未知时走所属契约的恢复路径。 -Capability 指令仅在适用时提供；authority 不能从 prompt 文字推导。 - -可选 observer 消费已提交事件或有界投影。除非现有契约明确要求它的 receipt， -其延迟不能进入准入/结算事务。只批处理尽力而为的 telemetry；不能为满足时间目标而延迟 -authority receipt 持久化、弱化 fsync/事务保证，或缓存过期权限/租约决策。 - -### 5.4 持久生命周期与外部副作用 - -通过统一工作契约使用既有 Goal/Agent/work/Turn 身份、revision、lease、effect id 与 receipt。 -解析装配，校验要求和 authority，准入工作，经绑定宿主执行，验证并持久化证据，结算一次， -再经所属 channel 交付/回读。各步骤使用既有合法迁移与重放规则；这段描述不新增竞争的 status enum -或事务协调者。 - -Executor 崩溃、effect ACK 丢失、结果交付 ACK 丢失是不同恢复情形。 -Operation provider 必须说明某个 effect 能否核对、能否安全重试。 -外部状态未知时，后续依赖操作须等待回读或人工干预；“未观测到”不等于“未执行”。 -设备幂等、物理联锁与补偿归 provider 负责，不能虚构为内核保证。 - -模型取消、进程终止、设备确认停止是不同事实。模型停止不能在缺少设备证据时生成 -“设备已停止”声明。需要持续监督的 provider，在 effect 尚未解决时不能卸载。 -结果验收、传输交付、用户回读也必须保留现有的不同证据。 - -### 5.5 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. 替代方案与设计选择 - -| 方案 | 决策与取舍 | -| --- | --- | -| 只拆包或加 lazy import | 可作为首批切片，但不足以定义激活、authority 和上下文边界 | -| Minimal 与 standard 各自一套引擎 | 拒绝：重复状态迁移，破坏产品/benchmark 一致性 | -| 所有规则都插件化 | 拒绝：预算、停止、租约、结算可能随预设消失 | -| 用上游 agent runtime 替代 LoopX 内核 | 拒绝：上游模型执行可以是 provider，但不能替代 LoopX 工作 authority | -| 强制统一 daemon 或远端服务 | 不要求：给有界本地使用增加生命周期与部署成本；daemon 仍按其现有 RFC 演进 | - -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。固定来源见附录 A。 - -## 7. 安全、隐私与兼容 - -装配不能把现有权限或强制门槛变成可选项。宿主可用、extension 已安装、runtime capability -声明都是观测，不是授权。每次 provider 调用保留 Goal、Agent、workspace 与 delivery 作用域； -凭据通过现有 provider 边界解析。公开投影排除私有源内容和本地工件。 - -不提议删除 schema/字段。按既有兼容窗口保留已知 reader/writer 和外部 import。 -未迁移 CLI 路由保留现有 fallback，直到替代路径通过命令一致性验证。 -不支持的版本/provider 组合在 dispatch 前拒绝；不能为了让混合版本看似可用而让一个 binding -同时存在两个 writer。 - -## 8. 迁移与回滚 - -先刻画 CLI parsing、输出、错误、required reads 与 effect 行为。 -一次迁移一个内聚路由并更新活跃调用者；真实调用者迁完后再删除内部 bridge。 -加载优化不能顺带迁移存储或降低持久性。 - -可执行 minimal 以 opt-in 引入，必须能显式回读解析后的装配。 -切换活跃 binding 前先检查兼容性，让其 owner 静止，并核对未完成 effect。 -恢复前验证新 owner 与回读；不能跨活跃 lease 热切换。 -回滚到旧的合格装配也先做同样核对，保留持久状态。 -后续任何不可逆数据变化都需要单独的迁移/导出门槛。 - -Standard 采用须通过下述产品旅程验收。 -只有全部受支持命令迁移，且 global options、help、错误、exit code 保持兼容后，才能移除完整 parser -fallback。默认值变化需要 release notes 与明确 owner 决策；本 RFC 不改变默认值。 - -## 9. 验证与验收 - -以下是拟定验收条件，不是已通过声明。确定性 fixture 根据语义独立设计，不能从当前实现输出反推期望。 -Live、性能和晋级证据分别记录。 - -| Id / 声明 | 测试或证据 | 必须得到的结果 | 边界 | -| --- | --- | --- | --- | -| A1 / 按需加载 | 两种预设下对 import、help、列表、未知命令、所选路由做导入/进程/网络追踪 | 只加载声明过的依赖闭包；无可选激活 | 不证明执行性能 | -| A2 / authority 一致性 | 对要求、过期 claim、停止、预算、重放、结算做刻画与负例测试 | 两种预设具有相同合法/非法迁移，只结算一次 | Minimal 不得绕过 authority | -| A3 / CLI 兼容 | 受支持命令的差分语料，含 fallback、Node/provider 缺失 | Parsing、输出契约、exit code 稳定，失败可操作 | 明确列出未迁移路由 | -| A4 / managed minimal | 一个真实 managed 任务、注入中断、重启、证据验证与结果回读 | 身份相同，effect 已核对，无重复工作或计费，已验收结果可获取 | 初期一个合格宿主即可；纯 mock 执行不够 | -| A5 / 上下文连续性 | 首次上下文、无变化续行、来源修订、compaction、ACK 丢失 | 必需上下文完整或明确恢复；拒绝过期上下文 | 单独测 token 减少 | -| A6 / standard 旅程 | 原始 App/IM 请求、纠正/暂停、继续、完成与返回 | 一个执行 owner；已验收结果和成本可见；目的地不静默改变 | 每个前端/provider 分别合格 | -| A7 / 研究与 peers | 有用首个结果后的证据性改善；owner 恢复后的 peer 结果返回与采纳 | 新成果或有理由的决策修订，并有可归属证据 | 更多时间、peer 或文字本身不能通过 | -| A8 / benchmark 保真 | 固定的匹配实验、native/passive/governed 边界、记忆隔离、完整成本账本 | 原生语义完整；C0–C4 证据遵守研究/诊断 owner | 本 RFC 不声称分数或因果收益 | -| A9 / 物理副作用 | 模拟器/故障注入，再做显式授权的 provider 专属 live 验证 | 核对丢失 ACK；在保证范围内防重复动作；独立确认设备停止 | 不承诺通用 exactly-once 或紧急停止 | -| A10 / 开销 | 指定环境中重复、成对测量冷进程与热路径 | 报告 median/p95、RSS、模块数、文件 I/O、Node 启动/IPC、字节与模型 token；持久性无退化 | M0 确定数字预算；CLI 基线无须付费任务运行 | - -本地开发候选目标为 p95：import 低于 50 ms、顶层 help 低于 100 ms、所选命令 help 低于 200 ms。 -它们是 D3 的建议，不是已验证结果或跨机器 CI 阈值。 -采用前要定义解释器启动、缓存条件、样本数、机器/runtime 版本。 -真实 status/admission/settlement 延迟须在有代表性的小/大状态上单独测量，包含 SQLite 竞争和恢复； -不能把 CLI-help 目标套在这些操作上，也不能减掉其必需 I/O。 - -## 10. 运维契约 - -回读应解释：解析后的装配及版本、所选宿主和 Session 模式、必需/可选 provider、激活/readiness， -以及加载某组件的原因。复用现有诊断/投影 owner，不新增状态数据库。 -前提缺失、元数据不兼容、authority 过期、effect 不确定必须保持可区分。 - -启动开销与 Turn 开销分别记录。可选 observer 故障应可见，但不能改写已提交执行结果； -强制 delivery 或证据 receipt 失败继续由所属 owner 治理。 -容量限制、背压归既有 work/host/provider 契约。运维恢复先核对持久 receipt 与 provider 回读，再继续执行。 - -## 11. 规范交付计划 - -以下切片归入既有路线图的 runtime、发行与产品工作流，不建立平行项目， -也不要求全仓重写后才能交付局部性能改善。 - -| 里程碑 | 交付行为 | 进入条件 | 退出证据 | 回滚 | -| --- | --- | --- | --- | --- | -| M0 / 一个加载接缝 | `performance-diagnosis` selected route 与实测加载边界 | 现有路由刻画；owner/依赖图；D3 测量决策 | 本路由的 A1/A3、A10 基线，无无关导入或行为变化 | 撤回路由提取 | -| M1 / 可执行 minimal | 一条合格 managed 受治理任务，含持久重启/结果回读 | D1 装配内容、D2 宿主/provider 选择；既有 authority 契约 | 此受支持组合的 A1–A5、A10 | 显式返回旧的合格装配 | -| M2 / standard 旅程 | Standard 解析同一内核，只激活所选产品工作流 | M1；现有 Session/前端准入 | A2/A5/A6/A10，含冷安装与功能关闭一致性 | 关闭 opt-in 装配并保留状态 | -| M3 / 研究资格 | 匹配的产品路径实验，以及一个长程/peer 旅程 | 所选界面的 M1 或 M2；冻结设计与单独运行授权 | A7/A8、完整成本与隐私检查、既有 C0–C4 门槛 | 停用实验 overlay，保留有界证据 | -| M4 / 外部操作 provider | 一个真实调用者，具备 provider 专属 effect 核对与停止证据 | D4；具名设备/操作 owner 与显式操作授权 | A9 加继承的治理门槛 | 停用前先静止并核对 provider | - -M0 不代表内核合格。M3、M4 是可选资格分支，不必阻塞已合格的 CLI 或 managed 任务。 -真实调用者出现前，不加入闲置 provider、配置字段、框架或通用测试矩阵。 -每个 PR 记录考虑、应用或推迟的有界重构及兼容证据。 - -## 12. 未决事项 - -| Id / owner | 选项与建议 | 所需证据 / 决策点 | -| --- | --- | --- | -| D1 / 发行与 runtime 维护者 | 将预设映射到已接受的发行方案；建议 minimal 先 opt-in，standard 最终承接兼容装配，当前不选择新默认值 | M1 打包前给出精确安装/加载/激活闭包及升级/回读契约 | -| D2 / 宿主与 authority 维护者 | 从既有 provider 选择首个 managed 宿主与受支持存储组合；建议最小且已满足资格的路径，DSH/Pi 仍按既有选择 RFC 评估 | M1 退出前给出 A4 宿主/Session 连续性与 authority 恢复证据；不声称所有宿主合格 | -| D3 / 性能维护者 | 采用机器相关 p95 预算或相对回归界限；建议候选预算加明确测量条件 | M0 退出前提供可复现基线；真实 Turn 预算独立推导 | -| D4 / operation-provider owner | 选择一个具体外部操作调用者，或推迟物理资格；建议真实调用者出现前不做通用设备框架 | M4 前确定范围、幂等/回读/停止契约及授权 | - -批准必须经相应评审决策记录；建议、实现进展或沉默都不能关闭未决事项。 - -## 附录 A：来源证据（非规范） - -| 证据 | 固定来源 | 支持的声明与限制 | -| --- | --- | --- | -| E1 / LoopX | 上述实现基线；第 4 节链接的入口、CLI 与所属契约 | 仅证明现有接缝与所有权；没有新性能测量 | -| E2 / DSH | [`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 宿主资格或权限建议 | -| E3 / Pi | [`agent` core](https://github.com/badlogic/pi-mono/blob/f14813e96510a7cf7562a120e809c6a134af073d/packages/agent/README.md) | Agent/tool/event core，以及 `transformContext`、`convertToLlm`、`prepareRequest`、`finishTurn` 接缝；无 LoopX authority 或性能声明 | - -本提案没有执行 live benchmark 或硬件操作。 From bffb6b5cc52506be4b6fb3f65fb81e5e77ae2f99 Mon Sep 17 00:00:00 2001 From: "lusendong.6789" Date: Thu, 29 Oct 2026 22:22:47 +0800 Subject: [PATCH 3/3] docs(rfc): preserve independent runtime qualification gates Signed-off-by: lusendong.6789 Co-authored-by: TRAE CLI --- docs/architecture/rfcs/monorepo-distribution-split-v0.md | 8 ++++++-- .../rfcs/monorepo-distribution-split-v0.zh-CN.md | 7 +++++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 73b81b572b..6a4b46ff83 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -452,6 +452,7 @@ weakening the initial result, adding more text or running longer is not progress | **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 @@ -485,6 +486,9 @@ 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 @@ -572,9 +576,9 @@ owner. Capacity/backpressure and recovery retain existing work/host contracts. | 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; selected D2/D5 composition mapped | rows 3–4, 7; repeat R1 against clean split-package install | 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 | M3, R1; existing frontend/session admission | V2/V5/V6/V10, cold install and feature-off parity | Disable opt-in composition, retain state | +| 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 | 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 e0c5fa89a9..9d64e1d4d2 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -317,6 +317,7 @@ checkpoint/恢复策略、数据集与 verifier 版本。按 run/arm 隔离记 | **Minimal 与 standard 各自一套引擎** | 重复状态迁移，破坏产品/benchmark 一致性。 | | **全部治理规则插件化** | 预算、停止、租约、结算可能随预设消失。 | | **以上游 agent runtime 替代 LoopX 内核** | 模型执行可以是宿主 provider，不能替代 LoopX 工作 authority。 | +| **每种装配都强制依赖一个 daemon 或远程服务** | 增加有界本地使用的生命周期与部署成本；可选 daemon 仍遵循其既有契约。 | Pi 展示了小型 agent core、工具/事件执行，以及与 coding 产品分离的显式上下文转换。 DSH 展示了同一 runtime 的多预设装配与自包含的最小 SDK bundle。 @@ -337,6 +338,8 @@ minimal 包含持久 shell、图像读取与 compaction。SDK minimal 还提供 宿主可用、安装和 capability 声明都是观测，不是授权。Provider 调用保持 Goal/Agent/workspace/delivery 作用域。预设不能把必需上下文或停止/预算规则变为可选。未迁 CLI 路由保留 fallback，直到 parsing、global options、输出、错误与 exit code 合格；不兼容版本在 dispatch 前拒绝。 +只有全部受支持命令完成迁移、help 与诊断一致性验证通过后，才能退役完整 parser。 +不能让两个 writer 同时写同一 binding 来制造混合版本 rollout 可用的假象。 ## 8. 迁移与回滚 @@ -412,9 +415,9 @@ Live、性能和晋级证据分别记录。 | 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 已决；所选 D2/D5 装配已映射 | 第 3–4、7 行；在干净拆包安装上重验 R1 | 撤下预发布 | +| 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 使用同一内核，只激活所选产品工作流 | M3、R1；现有前端/Session 准入 | V2/V5/V6/V10、冷安装与关闭一致性 | 关闭 opt-in 装配，保留状态 | +| 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，保留有界证据 |