diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index ab879d9632..ec096a05db 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -541,6 +541,15 @@ Paired diffs do not certify translation accuracy. - **Current boundary:** The RFC remains a discussion contract. Runtime work is held until repeated real usage demonstrates a second need without weakening non-blocking authority boundaries. +- [Calli Workbench and Session Fabric v0](calli-workbench-and-session-fabric-v0.md) + ([中文版](calli-workbench-and-session-fabric-v0.zh-CN.md)) + - **Delivery on `main`:** Proposal only; no `apps/**` or `packages/**` delivery yet. + - **Current boundary:** Two default-off units are proposed — an + `apps/presentation/calli-workbench/` projection-consumer UI and a + `packages/loopx-session-fabric/` optional package — with Goal/Todo/Gate + authority staying in `loopx-core` and Calli's own task tables retired. + Directory placement, L0 package boundary and naming await maintainer + decisions D1–D3. ## Benchmark And Reliability Engineering diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 8b3652811e..fc0bd77712 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 (51) +## Accepted (52) | RFC | Header status | Supersedes / closes | Ledger | | --- | --- | --- | --- | @@ -28,6 +28,7 @@ appendix may keep dated history, but no dated log heading may precede it. | [App conversations and reusable asynchronous work delivery](app-conversation-and-async-inbox-v0.md) | Accepted | none | — | | [RFC: Automatic Execution Admission (v0)](automatic-execution-admission-v0.md) | Accepted | none | — | | [RFC: Benchmark Study Upload and Dashboard Projection v0](benchmark-study-upload-dashboard-v0.md) | Accepted | none | — | +| [RFC: Calli Workbench and Session Fabric in LoopX (v0)](calli-workbench-and-session-fabric-v0.md) | Accepted | none | — | | [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 | — | diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index c9e6f61545..806dc2aceb 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -15,7 +15,7 @@ [English](STATUS.md) 与本文互为语义镜像。 -## 已接受 (51) +## 已接受 (52) | RFC | 头部状态 | 替代 / 关闭 | Ledger | | --- | --- | --- | --- | @@ -25,6 +25,7 @@ | [App 会话与可复用的异步工作投递](app-conversation-and-async-inbox-v0.zh-CN.md) | 已接受 | none | — | | [RFC:自动执行准入(v0)](automatic-execution-admission-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC: Benchmark Study Upload and Dashboard Projection v0](benchmark-study-upload-dashboard-v0.md) | 已接受 | none | — | +| [RFC:Calli 工作台与会话底座合入 LoopX(v0)](calli-workbench-and-session-fabric-v0.zh-CN.md) | 已接受 | 无 | — | | [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) | 已接受 | 无 | — | diff --git a/docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.md b/docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.md new file mode 100644 index 0000000000..166d34b13b --- /dev/null +++ b/docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.md @@ -0,0 +1,485 @@ +# RFC: Calli Workbench and Session Fabric in LoopX (v0) + +- **RFC status:** Accepted (effective on merge; a proposal under review until then) +- **Supersedes / closes:** none +- **Delivery maturity:** Proposal +- **Authors / owners:** [@maxliux5](https://github.com/maxliux5) ([Calli](https://github.com/maxliux5/calli) maintainer, MIT); directory placement, L0 package boundary and merge authorization belong to LoopX maintainers +- **Created:** 2026-11-14 +- **Last normative revision:** 2026-11-14 +- **Implementation baseline:** LoopX `80c694972`; Calli `87adcde` +- **Related contracts:** + [Monorepo distribution split](monorepo-distribution-split-v0.md), + [Agent session execution modes](agent-session-execution-modes-v0.md), + [Desktop execution frontends](desktop-execution-frontends-v0.md), + [App conversations and async inbox](app-conversation-and-async-inbox-v0.md), + [Overall roadmap](loopx-overall-roadmap-v0.md), + [Status data contract](../../status-data-contract.md), + [Compute quota](../../quota-allocation.md), + [Design system](../../development/design.md) +- **Language mirror:** [中文版](calli-workbench-and-session-fabric-v0.zh-CN.md) + +## Document map and maintenance contract + +Sections 1–10 are the design and acceptance contract, Section 11 is the +normative delivery plan, and Section 12 lists open decisions (proposed answers +are not approval). Appendices are non-normative. The proposed in-repository +file name is `docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.md` +with a same-basename `.zh-CN.md` mirror, submitted in the same PR and checked +by `scripts/check_rfc_bilingual.py`. + +--- + +## 1. Decision summary + +1. **What becomes authoritative or changes.** Calli enters LoopX as two + separate units: a **product surface** (the Calli workbench UI, in its own + directory under `apps/`) and an **optional session-fabric distribution** + (SSH multi-host, non-invasive attachment of heterogeneous CLIs, + quota-aware handover, under `packages/`). Neither becomes an authority for + Goal/Todo/Gate. +2. **What stays unchanged.** `loopx-core` remains the only writer of Goal, + Todo, claim, lease, quota, effect and Gate state. The official dashboard, + the `/status.json` contract and `/api/chat/*` keep their behavior. +3. **Default and opt-in boundary.** Both units are off by default: a user who + installs only `loopx-core` or uses only the official dashboard sees no + difference. The workbench is a separately built and launched frontend; the + session fabric installs and uninstalls through the existing + `extension.toml` lifecycle. +4. **Principal safety and compatibility constraint.** No dual authority: each + fact has exactly one owner. Calli's own task system (the `owner: me|agent` + todo table, `waitingOn`, its handover state machine, team/coordination + tables) **does not enter LoopX**; existing data is imported once through + LoopX's public Todo dry-run/apply interface. +5. **What this RFC does not approve.** No change to `loopx/` core, no new + default behavior, and no default-on quota handover. Every `apps/**` and + `packages/**` PR still requires explicit maintainer merge authorization. + +## 2. Problem and motivation + +[Calli](https://github.com/maxliux5/calli) (MIT) is a multi-agent workbench. It attaches Claude Code, Codex, pi, TRAE, +zcode, Antigravity, DeepSeek Harness and other CLIs already installed on local +or remote machines to one interface, lets the user view and take over sessions +across machines, and moves work to another account or model when one account +nears its quota. LoopX already owns a strict governance kernel (Goal, Todo, +Gate, lease, turn fencing, receipt) and is advancing two execution modes, +Managed Host and Attached Session. + +Evolving separately, users hit these failures: + +- **Two ledgers for one task.** A user creates a "waiting for the agent" todo + in Calli and has a matching Todo in LoopX. Completion, waiting target and + owner drift apart, and the user no longer knows which to trust. +- **Two stewards for one person.** Calli's "needs you" reminder and the LoopX + Lark steward notify about the same Gate separately; confirming one leaves the + other pending. +- **Two multi-host models for one machine.** The LoopX dashboard already has + `ssh_host_catalog_v0` and `/api/ssh-source/*`; Calli has its own SSH tunnel + registry in `hosts.ts`. Host names, online state and failure reasons can + contradict each other. +- **Two meanings of handover.** Calli switches accounts at a quota threshold; + LoopX uses leases and turn fencing so one Todo has at most one executor at a + time. A Calli switch that bypasses fencing could let two executors advance + the same Todo. + +Calli cannot fix this locally: as long as it keeps its own task state, any +sync is reconciliation between two authorities. The correct fix is for Calli to +give up ownership of that state and keep only the host-layer capabilities +LoopX does not yet have. + +### Invariants + +- **I1 Single authority.** Goal/Todo/Gate/lease/quota decisions are written + only by `loopx-core`; the workbench and session fabric read projections and + submit commands only through control-plane APIs. +- **I2 The UI is not a second state source.** The workbench persists no + Goal/Todo/Gate fact. It may store only display preferences (theme, pane + widths, selected machine) locally, and clearing them changes no business + outcome. +- **I3 One Gate, one confirmation.** A Gate appears as the same record in the + workbench and the Lark steward; after either side confirms it, the other + drops it on its next projection refresh. +- **I4 Handover respects fencing.** Any account or model switch first ends the + current turn at its fence, then the new session reacquires the lease; one + Todo never has two active executors. +- **I5 Feature-off parity.** When not installed or not enabled, LoopX behavior, + CLI output and dashboard rendering match the baseline byte for byte. +- **I6 The host stays in its lane.** The session fabric does not modify an + agent's configuration, directories or session files, and injects no prompts + or tools (Calli's existing principle, and LoopX's Attached Session rule that + the external host keeps process ownership). + +## 3. Scope and non-goals + +### In scope + +This RFC organizes the contribution into four layers. They map one-to-one onto +the ownership table already in +[Monorepo distribution split §5](monorepo-distribution-split-v0.md#5-proposed-architecture) +and introduce no new layering concept: + +| Layer | Existing ownership row | What Calli brings | Destination | +| --- | --- | --- | --- | +| **L0 Host & Session Fabric** | Host | SSH multi-host connection and tunnel lifecycle; non-invasive attachment of heterogeneous CLIs (local and remote native conversation threads); multi-account quota-aware handover | `packages/loopx-session-fabric/`, combined with Managed Host into a complete session substrate | +| **L1 Minimal Governance Kernel** | Governance kernel | **Nothing.** Calli's tasks, handover state machine and team collaboration are removed | Existing `loopx-core` only | +| **L2 Capability Packs** | Capability strategy | Nothing new; Calli's research-oriented extensions stay out of core and hidden from general users by default | Unchanged; submitted separately through the capability-package process | +| **L3 Unified Surfaces** | Extension and product surface | Three-pane workbench: machine switcher on top, "host + machine + model" launch bar at the bottom, right-side "Needs you / Running / Failed" triage drawer | `apps/presentation/calli-workbench/`, sharing one Inbox/Gate projection with the Lark steward | + +### Non-goals + +- **No rebuilt L1.** No second task table, handover state machine, team or + collaboration model. Calli's `todos`, `todo_threads`, `todo_notes`, + `todo_proposals`, `sections`, `wishes`, `todo_summaries`, `teams` and + `coordination` tables are not moved into LoopX. +- **No second state authority.** The workbench does not cache, infer or + synthesize Goal/Todo/Gate state. A missing field first enters the LoopX + status contract as an additive field, then the workbench reads it. +- **No Calli daemon transplant.** The Calli Node daemon (hundreds of `/api/*` + routes, SSE, SQLite) does not enter LoopX as a whole; only audited L0 modules + are ported, one package module at a time. +- **No wholesale frontend move.** Of Calli's ~40k-line web app, only the + workbench shell, triage drawer, machine switcher, launch bar and session view + enter. Skills/MCP resource management, pets, voice and other peripheral + features are out of scope. +- **No replacement of the official dashboard.** Both frontends coexist and read + the same projections; any future merge is a separate maintainer decision + based on usage evidence. +- **No change to LoopX's default executor, provider or quota policy.** + +## 4. Current-system contract (baseline facts) + +**LoopX (`80c694972`)** + +- `apps/` is the product surface, `packages/` holds optional distributions, + `loopx/` is core. [`apps/presentation/README.md`](../../../apps/presentation/README.md) + states that apps there consume only public-safe projections and fixtures, + own no control-plane state and never write LoopX registries directly. +- The official dashboard (React 19 / Vite 8) reads `/status.json`, validates + it with zod (`apps/presentation/dashboard/src/data/status.ts`), and checks + compatibility via `status_contract.schema_version` and + `minimum_dashboard_schema_version`. +- Public write entrypoints already exist: `/api/chat/todo/dry-run` and + `/api/chat/todo/apply`, `/api/actions/*`, `/api/chat/request-control`, + `/api/chat/codex-attached` (Attached Session), `/api/ssh-source/*` and + `/ssh-hosts` (`ssh_host_catalog_v0`). +- Session execution modes are defined by + [Agent session execution modes](agent-session-execution-modes-v0.md): + in Attached mode the external host keeps process and session ownership; in + Managed mode LoopX launches the runtime and advances bounded `loopx_turn_v0` + transactions. +- Quota observation is described in [Compute quota](../../quota-allocation.md): + `loopx quota status/plan` are Goal-scoped read-only observations. + +**Calli (`87adcde`)** + +- `packages/web`: React 18 / Vite 5 / hand-written CSS. The three-pane layout, + machine switcher, launch bar and triage drawer already ship. +- `packages/daemon`: Node backend with SQLite; currently the owner of all + Calli state. **L0 parts:** `hosts.ts` (SSH tunnel registry, backoff + reconnect, typed failures `no_ssh/host_key/auth/unreachable/ssh_failed/daemon_missing/forward_denied`), + `adapters/*` (codex, claude, pi, traex, zcode, agy, dsh, acp, …), + `auto-handover.ts` and `quota-resume.ts` (quota windows, thresholds, + cross-account order, switch-back on reset). **L1 parts to remove:** the todo + tables, `teams`, `coordination`, and the handover state machine. +- `packages/ext-loopx`: a stdio JSON-RPC plugin that reads + `worksource.snapshot` via `loopx status --format json`. It accepts only + `version === '1.4.2'`, which no longer matches LoopX 2.0. + +## 5. Proposed architecture + +### 5.1 Directory and placement + +The hard requirement is that the Calli UI lives in its own directory, clearly +separated from LoopX core. Proposed layout (**final placement is a maintainer +decision, see §12 D1**): + +```text +apps/presentation/ + dashboard/ # official dashboard, unchanged + calli-workbench/ # new: Calli three-pane workbench (L3) + package.json # built independently; React/Vite aligned with dashboard + src/data/ # projection schemas and read-only queries only; no state store + smoke/ # fixture-driven browser smokes + README.md +packages/ + loopx-session-fabric/ # new: L0 session fabric (optional, default-off) + extension.toml + src/hosts/ # SSH multi-host, as a provider for ssh_host_catalog_v0 + src/attached/ # Attached adapters per CLI, one adapter per PR + src/quota/ # quota-window observation and handover proposals +``` + +Rationale: + +- **Fits existing layering.** The workbench only renders projections and + submits commands, which is exactly what `apps/presentation/` means; the + session fabric is an independently installable and removable host + capability, which is exactly what `packages/` means. Neither touches + `loopx/`. +- **Easy to review and roll back.** Each directory has its own + `package.json` and CODEOWNERS line, so merge permission can be granted or + withdrawn per directory; deleting a directory is a complete rollback. +- **Beside the official dashboard, not inside it.** Embedding would interleave + two interaction models in one route tree and contradict the separate + directory requirement. + +Alternatives: `apps/calli-workbench/` (a sibling of `apps/presentation/`; +stronger isolation but outside the presentation grouping); splitting L0 into +several packages (e.g. `packages/loopx-host-ssh/`, +`packages/loopx-attached-/`). + +### 5.2 Ownership and authority + +| Fact | Sole owner | How the workbench reads it | How the workbench changes it | +| --- | --- | --- | --- | +| Goal / Todo / claim / Gate | `loopx-core` | `/status.json` and its sub-projections | `/api/chat/todo/dry-run` → `/api/chat/todo/apply`; `/api/actions/*`; `/api/chat/request-control` | +| Session messages, streaming output | Executing host (external CLI when Attached; LoopX when Managed) | `/api/chat/sessions/*` | Same interface | +| Inbox / Gates needing a human | `loopx-core` | Same projection as the Lark steward | Same confirmation command | +| Machine topology and connection state | Session fabric (L0) | Exposed via `ssh_host_catalog_v0` plus additive fields | `/api/ssh-source/*` | +| Quota-window observation | Session fabric (L0), as a quota observation provider | Added to the quota observation projection | Not writable; the user can only confirm a handover in a Gate | +| Theme, pane widths, selected machine | Browser-local | `localStorage` | Local | + +Forbidden alternate authorities: the workbench's local state, the session +fabric's private storage, and any Calli daemon table must never be read as +evidence of whether a Todo is done, a Gate was handled, or who holds a lease. + +### 5.3 The workbench as a LoopX projection consumer + +- **Reads.** The workbench data layer consists only of zod schemas and + read-only queries, reusing or mirroring the dashboard's `status.ts` + contract. On start it validates `status_contract.schema_version`; on + mismatch it shows "update the local LoopX service" instead of guessing. +- **The triage drawer's three groups derive entirely from projections:** + - "Needs you" = Gates awaiting a human, pending decisions and Inbox items; + - "Running" = Todos with a live lease and active sessions; + - "Failed" = failed or blocked receipts, offline machines, quota-exhausted + sessions. + If a group needs a field the projection lacks, a separate **additive field** + PR to the status contract comes first (additive fields need no RFC per the + [RFC README](README.md#when-a-change-needs-an-rfc)); the workbench reads it + afterwards. The workbench never "infers completion" on its own. +- **Writes.** Every operation that changes Goal/Todo/Gate calls dry-run first, + then apply, then reads the projection back. On failure or conflict it shows + the control plane's typed error and performs no optimistic local update of + business state. +- **Design system.** It follows the [LoopX design system](../../development/design.md): + Geist type, black-and-white hairline surfaces, restrained accents, designed + empty/loading/error states and status glyphs. Calli's hand-written CSS + migrates to LoopX CSS custom properties and passes the same kind of + `check:css-custom-properties` check. Every UI PR attaches public-safe + screenshots and self-reviews with that document's Populated Page Review. + React and Vite are upgraded to the dashboard's versions. + +### 5.4 One Inbox/Gate projection shared with the Lark steward + +The workbench's "Needs you" and the Lark steward read the same Inbox/Gate +projection and confirm through the same control-plane command with the same +idempotency identity. The workbench sends no notifications of its own; it only +shows entries already in the projection. This satisfies I3: a Gate confirmed in +Lark disappears from the workbench on the next refresh, and vice versa. + +### 5.5 L0 session fabric + +**SSH multi-host: join the existing model rather than add a parallel one.** +LoopX already has `ssh_host_catalog_v0` and `/api/ssh-source/*`. The session +fabric acts as a provider that adds what Calli has already validated: Unix +socket tunnels, `BatchMode=yes`, never accepting unknown host keys on the +user's behalf, 2 s–2 min backoff reconnect, a 15 s health check and typed +failure codes. Host identity and aliases remain owned by +`ssh_host_catalog_v0`; Calli's `hosts.json` stops being a source. Remote access +stays replaceable: local SSH is the first implementation, and future cloud or +gateway sources plug into the same interface under +[roadmap R6 Local/Cloud Convergence](loopx-overall-roadmap-v0.md). + +**Heterogeneous CLI attachment: maps to Attached Session.** Each Calli adapter +is ported as an Attached host adapter that follows the admission contract in +[Agent session execution modes](agent-session-execution-modes-v0.md): the +external CLI keeps process, session and interruption ownership; LoopX records +the binding and turn boundaries. Adapters are independent and ported one per +PR, starting with those that already have a LoopX counterpart (Codex, pi, +dsh). Process launch, worktree isolation and turn fencing owned by Managed Host +are not reimplemented here; this package fills the Attached side so the two +together form the full session substrate. + +**Quota-aware handover: from "executing an action" to "a governed +proposal".** Calli currently acts at configurable thresholds (for example, +around 85% it compacts context and moves to a cheaper model; around 90% it +hands over to another account; after the quota resets it switches back). +After the merge: + +1. The session fabric only **observes**: it reports each host account's quota + windows (used percent, reset time, applicable models) as a quota + observation provider, exposing no credentials or account identity, only + opaque profile ids. +2. LoopX's quota and admission rules **decide** whether to switch; the switch + happens at the current turn's fence: the old session ends its turn → + releases the lease → the new session, under a new profile, reacquires the + lease on the same Todo → a receipt records the handover. +3. It is off by default; when on, every switch leaves an auditable Inbox + record. A user can require "ask me before switching", in which case it is + an ordinary Gate. +4. "Switch back after reset" runs the same fence → lease flow; silent + switching is not allowed. + +### 5.6 `ext-loopx`: from a hard-coded version to contract probing + +`ext-loopx` serves only users who keep running Calli standalone (the workbench +inside LoopX does not need it). Changes: + +- Drop the `version === '1.4.2'` check; read `status_contract.schema_version` + from `loopx status --format json` and compare it with the plugin's declared + known range. +- Three outcomes: `compatible` (normal display), `newer_unverified` (read-only + display labelled "newer, unverified contract"), `incompatible` (show the + reason, do not parse). +- Optional capabilities (Inbox projection, quota observation) are enabled per + field presence, not inferred from a version number. +- Contract tests with 1.4.2, 2.0, missing-field and unknown-schema fixtures. + +This change lands in the Calli repository, not in a LoopX PR. + +### 5.7 Command lifecycle and failure handling + +- Every write carries an idempotency key; after a timeout or disconnect the + client reads the projection back to see whether it took effect before + retrying. +- When a projection is stale (older than its refresh period), the workbench + marks the affected area "possibly stale" and disables writes that depend on + it. +- A session-fabric crash does not affect `loopx-core`: Attached session + ownership already lies with the external CLI, and after restart the fabric + reattaches from `ssh_host_catalog_v0` and the binding records. + +## 6. Alternatives and design choices + +| Option | Verdict | Reason | +| --- | --- | --- | +| A. Calli stays standalone and only reads LoopX via `ext-loopx` | Rejected as an end state | Dual authority remains; sync is permanent reconciliation | +| B. Move the whole Calli daemon into LoopX, converge later | Rejected | Introduces a second state authority on day one, violating I1; review surface too large | +| C. Workbench as a route inside the dashboard | Rejected as default | Contradicts the separate-directory requirement; mixes two interaction models in one route tree | +| D. **Separate frontend directory + optional L0 package + removal of Calli L1** | **Chosen** | Satisfies I1–I6; every step is independently mergeable and revertible | + +## 7. Safety, privacy, and compatibility + +- **Feature-off parity (I5):** neither directory enters the `loopx-core` boot + closure; CI adds a check that `loopx status` output is unchanged when they + are not installed. +- **Credential boundary:** SSH credentials and host-key policy stay in the + running user's OpenSSH; the fabric stores no keys and forwards no browser + token. Agent account credentials never enter projections, logs or receipts. +- **Public/private boundary:** fixtures, screenshots and test data are fully + synthetic, with no real sessions, paths or accounts, per the + [public/private boundary](../../public-private-boundary.md). +- **License:** Calli is MIT; LoopX is Apache-2.0. Ported code is resubmitted + by its author under Apache-2.0 with DCO sign-off; code by other contributors + needs their sign-off or a rewrite (see §12 D5). +- **Mixed versions:** the workbench rejects incompatible servers through + `status_contract.schema_version`; the session fabric declares a minimum + `loopx-core` version in `extension.toml`. + +## 8. Migration and rollback + +**Existing Calli users** + +1. Standalone Calli keeps working; `ext-loopx` switches to contract probing + (§5.6). +2. A one-time export tool turns Calli todos, notes and linked threads into + LoopX Todo proposals. It **dry-runs first**; the user confirms item by item; + it writes through `/api/chat/todo/apply` and reads the projection back to + compare counts and text. `owner: me|agent` maps to the Todo's responsible + party and `waitingOn` maps to a Gate or a waiting note; the mapping rules + live in the tool's README. +3. After a successful import, Calli's old tables become read-only and are + labelled "moved to LoopX"; they are deleted only after explicit user + confirmation. The export file stays on the user's machine and is never + uploaded. + +**Convergence of Calli daemon tables** + +| Table / module | Destination | +| --- | --- | +| `todos`, `todo_threads`, `todo_notes`, `todo_proposals`, `sections`, `wishes`, `todo_summaries` | Deleted after import into LoopX Todos | +| `teams`, `coordination`, handover state machine | Deleted; replaced by LoopX Goal collaboration and semantic handoff | +| `schedules`, `schedule_runs` | Open (§12 D4): merge into LoopX scheduling, or keep as a pure host-layer timer | +| `hosts.json`, tunnels | Folded into the `ssh_host_catalog_v0` provider | +| Quota windows, handover settings | L0 observation and user preferences; the decision moves to LoopX | +| Threads, events, turn text | Owned by the external CLI when Attached; read through `/api/chat/sessions/*` | + +**Rollback:** each milestone PR only adds a directory or an additive field; +rollback is a revert. Todos written by the import tool are ordinary LoopX +Todos that do not depend on Calli; old tables remain until the user confirms +deletion, so rolling back the migration only requires disabling the imported +results. + +## 9. Validation and acceptance + +| Claim | Test or evidence | Required result | Boundary / exclusions | +| --- | --- | --- | --- | +| Feature-off parity | Run `loopx status --format json` and a dashboard build without the two directories; diff against baseline | Identical | Says nothing about enabled behavior | +| No second state source in the workbench | Static check: no persisted Goal/Todo/Gate writes under `calli-workbench/src`; reload after clearing browser storage | Page matches projection | Does not prove server correctness | +| Writes only via the control plane | Browser smoke intercepting network: every mutating request hits dry-run/apply/actions/request-control | No other write endpoint | Does not cover future entrypoints | +| One Gate, one confirmation (I3) | Fixture-driven: confirm a Gate on the Lark side, refresh the workbench | Item leaves "Needs you" | Does not prove the live Lark network path | +| Handover respects fencing (I4) | Two simulated profiles; quota crosses threshold; inspect lease and receipt sequence | At most one lease per Todo at any time; a handover receipt exists | Does not prove real quota APIs are accurate | +| One SSH multi-host model | A machine appears once in `ssh_host_catalog_v0`; a fixture per failure code | No duplicate machine; codes map 1:1 to UI copy | Does not replace real-machine deployment acceptance | +| `ext-loopx` contract probing | 1.4.2, 2.0, missing-field and unknown-version fixtures | compatible / compatible / read-only degrade / incompatible | Does not prove every future version | +| Design consistency | Desktop and mobile, light and dark screenshots per the design system's Populated Page Review | Review passes | Screenshots are not a usability study | +| Migration readback | Synthetic Calli DB → dry-run → apply → readback | Counts and text match; reruns are idempotent | Does not cover user-defined fields | + +Deterministic conformance, live qualification, performance evidence and +default promotion are reported separately; an unrun or skipped row is not green. + +## 10. Operational contract + +- **Observability:** the workbench footer shows projection source, + `schema_version` and freshness; the session fabric reports connection state + and failure codes through the existing doctor output. +- **Typed failures:** SSH failures keep Calli's seven validated codes; missing + quota observation is "unknown" and never triggers a switch. +- **Capacity:** one SSH child process per machine; projection polling follows + the dashboard cadence with no new high-frequency polling. +- **Upgrade/downgrade:** the workbench and `loopx-core` negotiate through the + schema version; the session fabric can be uninstalled on its own, after + which Attached sessions remain owned by their CLIs. + +## 11. Normative delivery plan + +Each milestone is a small, independently mergeable and revertible PR (or a set +of small PRs) on a `codex/` branch in a dedicated worktree, with +`Signed-off-by` on every commit. + +| Milestone | Shipped behavior | Entry gate | Exit evidence | Rollback | +| --- | --- | --- | --- | --- | +| **M0 RFC** | This RFC as an English/Chinese pair | — | `check_rfc_bilingual.py` passes; maintainers decide §12 D1–D3 | revert | +| **M1 Workbench shell (fastest path)** | `apps/presentation/calli-workbench/`: three panes, machine switcher, launch bar, session view; reads `/status.json` and `/api/chat/sessions/*` only; no `loopx/` change | M0 merged; D1 decided | Fixture smoke, build, screenshots, no-second-state-source check | Delete directory | +| **M2 Triage and writes** | "Needs you / Running / Failed" drawer; Todo/Gate writes via dry-run/apply; Inbox shared with the Lark steward; a separate additive status-contract PR first if needed | M1 merged | I3 smoke; write-endpoint interception smoke | revert; additive fields may stay | +| **M3 SSH multi-host provider** | First module of `packages/loopx-session-fabric/`: tunnels, reconnect and failure classification for `ssh_host_catalog_v0` | M1 merged; D2 decided | Seven failure-code fixtures; single-host-model check | Uninstall package | +| **M4 Attached adapters** | One PR per CLI, in the order Codex → pi → dsh → others | M3 merged | Bind/detach/turn-boundary smoke per adapter | Uninstall one adapter | +| **M5 Quota observation and governed handover** | Quota windows as an observation provider; handover via fence → lease → receipt; default-off | At least one M4 adapter merged; maintainer authorization of the quota policy | I4 smoke; feature-off parity | Turn off; uninstall module | +| **M6 Calli data import and L1 retirement** | One-time import tool; standalone Calli drops task, team and coordination tables; `ext-loopx` contract probing | M2 merged | Migration readback test; Calli-side regression | Old tables kept until confirmed deletion | + +M1 is the fastest usable slice: once M0 merges and the directory is decided, M1 +can be reviewed on its own without waiting for any core change. + +## 12. Open decisions + +| Id | Question | Owner | Options | Recommendation | Dependent milestone | +| --- | --- | --- | --- | --- | --- | +| D1 | Workbench directory | Maintainers | `apps/presentation/calli-workbench/` / `apps/calli-workbench/` | The former, beside the dashboard | M1 | +| D2 | L0 package boundary | Maintainers | One `loopx-session-fabric` package / several per-capability packages | One package with internal module directories; split when a second consumer appears | M3 | +| D3 | Naming | Maintainers | Keep "Calli" as the product name, or a neutral name (e.g. "LoopX Workbench") | Directory `calli-workbench` for traceability; UI name decided by maintainers | M1 | +| D4 | Ownership of scheduled tasks | Maintainers | Merge into LoopX scheduling / keep in the host layer | Merge into LoopX scheduling to avoid a second scheduler | M6 | +| D5 | License and history | Author + maintainers | Merge with history / recontribute as new commits | Recontribute as new commits for clean LoopX history and complete DCO | M1 | +| D6 | Long-term relationship with the official dashboard | Maintainers | Coexist / merge components later | Coexist first; decide from usage evidence | After M2 | + +Recommendations are non-binding until recorded in Appendix B. + +--- + +## Appendix A: Execution ledger (non-normative) + +After merge, entries live under `ledger/calli-workbench-and-session-fabric-v0/`. + +## Appendix B: Decision log + +| Date | Decision | Owner / approval | Alternatives | Normative sections changed | +| --- | --- | --- | --- | --- | +| — | — | — | — | — | diff --git a/docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.zh-CN.md b/docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.zh-CN.md new file mode 100644 index 0000000000..3611d59815 --- /dev/null +++ b/docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.zh-CN.md @@ -0,0 +1,283 @@ +# RFC:Calli 工作台与会话底座合入 LoopX(v0) + +- **RFC 状态:** 已接受(合入后生效;合入前为待评审提案) +- **替代 / 关闭:** 无 +- **交付成熟度:** Proposal +- **作者 / 负责人:** [@maxliux5](https://github.com/maxliux5)([Calli](https://github.com/maxliux5/calli) 维护者,MIT);目录位置、L0 包边界与合并授权由 LoopX maintainer 决定 +- **创建日期:** 2026-11-14 +- **最近规范性修订:** 2026-11-14 +- **实现基线:** LoopX `80c694972`;Calli `87adcde` +- **相关契约:** + [Monorepo 分发拆分](monorepo-distribution-split-v0.zh-CN.md)、 + [Agent 会话执行模式](agent-session-execution-modes-v0.zh-CN.md)、 + [桌面执行前端](desktop-execution-frontends-v0.zh-CN.md)、 + [App 会话与异步收件箱](app-conversation-and-async-inbox-v0.zh-CN.md)、 + [总体路线图](loopx-overall-roadmap-v0.zh-CN.md)、 + [状态数据契约](../../status-data-contract.md)、 + [算力额度](../../quota-allocation.md)、 + [设计系统](../../development/design.md) +- **语言镜像:** [English](calli-workbench-and-session-fabric-v0.md) + +## 文档地图与维护约定 + +第 1–10 节是设计与验收契约,第 11 节是规范性交付计划,第 12 节是未决问题(文中给出的建议不等于批准)。附录不具规范性。本 RFC 合入后在仓库中的文件名建议为 `docs/architecture/rfcs/calli-workbench-and-session-fabric-v0.md` 及同名 `.zh-CN.md` 镜像,两者在同一个 PR 中提交并通过 `scripts/check_rfc_bilingual.py`。 + +--- + +## 1. 决策摘要 + +1. **什么成为权威、什么行为改变。** Calli 以两个独立单元进入 LoopX:一个**产品面**(Calli 工作台 UI,放在 `apps/` 下的独立目录)和一个**可选会话底座分发包**(SSH 多机、异构 CLI 挂接、额度感知交接,放在 `packages/` 下)。两者都不成为 Goal/Todo/Gate 的权威。 +2. **什么不变。** `loopx-core` 仍然是 Goal、Todo、claim、lease、quota、effect、Gate 状态的唯一写入方。官方 dashboard、`/status.json` 契约与 `/api/chat/*` 不因本 RFC 改变行为。 +3. **默认与 opt-in 边界。** 两个单元都默认关闭:只装 `loopx-core` 或只用官方 dashboard 的用户看不到任何差异。工作台是一个可单独构建、可单独启动的前端;会话底座通过现有 `extension.toml` 生命周期安装与卸载。 +4. **主要安全与兼容约束。** 不出现「双权威」:同一事实只有一个所有者。Calli 自建的任务系统(`owner: me|agent` 待办表、`waitingOn`、自建交接状态机、团队/协作表)**不进入 LoopX**,其存量数据通过 LoopX 公开的 Todo dry-run/apply 接口一次性迁入。 +5. **本 RFC 不批准的事项。** 不批准任何对 `loopx/` 核心的修改、不批准新增默认行为、不批准额度自动交接的默认开启;每个阶段的 `apps/**` 与 `packages/**` PR 仍需 maintainer 的显式合并授权。 + +## 2. 问题与动机 + +[Calli](https://github.com/maxliux5/calli)(MIT)是一个多 agent 工作台:在同一个界面里接入本机或远端已经安装的 Claude Code、Codex、pi、TRAE、zcode、Antigravity、DeepSeek Harness 等 CLI,跨多台机器查看和接手会话,并在某个账号额度接近耗尽时把工作交给另一个账号或模型继续。LoopX 已经拥有严格的治理内核(Goal、Todo、Gate、lease、turn fencing、receipt),并在推进 Managed Host 与 Attached Session 两种执行模式。 + +两者独立演进时,用户实际遇到的问题是: + +- **同一件事有两本账。** 用户在 Calli 里建了一条「等 agent 回复」的待办,又在 LoopX 里有一条对应 Todo。两边完成状态、等待对象和责任人各自演化,最终用户不知道该信哪一个。 +- **同一个人有两个管家。** Calli 的「需要你」提醒和 LoopX 的 Lark 管家会对同一个 Gate 各发一次通知,确认了一边,另一边仍然挂着。 +- **同一台机器有两套多机模型。** LoopX dashboard 已有 `ssh_host_catalog_v0` 与 `/api/ssh-source/*`,Calli 另有 `hosts.ts` 的 SSH 隧道登记。机器名、在线状态和失败原因可能互相矛盾。 +- **同一次交接有两种语义。** Calli 在额度阈值处切换账号续跑;LoopX 以 lease 和 turn fencing 保证同一 Todo 同一时刻只有一个执行者。如果 Calli 绕过 fencing 切换,可能出现两个执行者同时推进同一 Todo。 + +这些问题不能在 Calli 内部单独解决:只要 Calli 保留自己的任务状态,任何同步机制都只是在两个权威之间做调和。正确的做法是让 Calli 放弃这些状态的所有权,只保留 LoopX 当前没有、且属于宿主层的能力。 + +### 不变量 + +- **I1 单一权威。** Goal/Todo/Gate/lease/quota 决策只由 `loopx-core` 写入;工作台与会话底座只读投影、只经控制面 API 提交命令。 +- **I2 UI 不做第二状态源。** 工作台不持久化任何 Goal/Todo/Gate 事实;本地只允许保存纯展示偏好(主题、栏宽、当前选中的机器),且删除后不影响任何业务结果。 +- **I3 一个 Gate 一次确认。** 同一个 Gate 在工作台和 Lark 管家里显示同一条记录;任一面确认后,另一面在下一次投影刷新时消失。 +- **I4 交接受 fencing 约束。** 任何账号或模型切换都必须先在当前 turn 的 fence 处结束,再由新会话重新获得 lease;同一 Todo 不会同时有两个活跃执行者。 +- **I5 默认关闭等价。** 未安装或未启用时,LoopX 的行为、CLI 输出与 dashboard 渲染与基线逐字节一致。 +- **I6 宿主不越权。** 会话底座不修改各 agent 的配置、目录和会话文件,不向 agent 注入 prompt 或工具(沿用 Calli 现有原则与 LoopX Attached Session 的「外部宿主保留进程所有权」约定)。 + +## 3. 范围与非目标 + +### 范围内 + +本 RFC 用四层组织合入内容。这四层与 [Monorepo 分发拆分 §5](monorepo-distribution-split-v0.zh-CN.md#5-提议的架构) 中已有的所有权表一一对应,不引入新的层级概念: + +| 层 | 对应现有所有权行 | Calli 带来的内容 | 去向 | +| --- | --- | --- | --- | +| **L0 宿主与会话底座** | Host | SSH 多机连接与隧道生命周期;异构 CLI 无侵入挂接(覆盖本机与远端的原生对话线程);多账号额度感知交接 | `packages/loopx-session-fabric/`,与 Managed Host 拼成完整会话底座 | +| **L1 最小治理内核** | Governance kernel | **无**。Calli 的任务、交接状态机和团队协作全部删除 | 只使用 `loopx-core` 现有能力 | +| **L2 能力包** | Capability strategy | 无新增;Calli 现有的科研向扩展不进核心,默认对普通用户隐藏 | 维持现状,另行按能力包流程提交 | +| **L3 统一界面** | Extension and product surface | 三栏工作台:顶部机器切换、底部「宿主 + 机器 + 模型」启动条、右侧「需要你 / 在跑 / 出错」Triage 抽屉 | `apps/presentation/calli-workbench/`,与 Lark 管家共用同一 Inbox/Gate 投影 | + +### 非目标 + +- **不重建 L1。** 不引入第二个任务表、第二个交接状态机、第二套团队或协作模型,也不把 Calli 的 `todos`、`todo_threads`、`todo_notes`、`todo_proposals`、`sections`、`wishes`、`todo_summaries`、`teams`、`coordination` 表搬进 LoopX。 +- **不做第二个状态权威。** 工作台不缓存、不推断、不合成 Goal/Todo/Gate 状态。投影里没有的字段,以附加字段的方式先进入 LoopX 的状态契约,再由工作台读取。 +- **不搬 Calli daemon。** Calli 的 Node daemon(上百条 `/api/*` 路由、SSE、SQLite)作为整体不进入 LoopX;只有 L0 模块经逐个审计后以包的形式移植。 +- **不整体搬运 Calli 前端。** Calli web 约 4 万行,只有工作台外壳、Triage 抽屉、机器切换、启动条和会话视图进入;skills/MCP 资源管理、宠物、语音等外围功能不在本 RFC 范围内。 +- **不替换官方 dashboard。** 两个前端并存,读取同一套投影;是否在未来合并由 maintainer 依据使用数据另行决定。 +- **不改变 LoopX 的默认执行器、默认 provider 或默认额度策略。** + +## 4. 当前系统契约(基线事实) + +**LoopX(`80c694972`)** + +- `apps/` 是产品面,`packages/` 是可选分发,`loopx/` 是核心。[`apps/presentation/README.md`](../../../apps/presentation/README.md) 约定:此目录下的应用只消费公开安全的投影与 fixture,不拥有控制面状态,也不直接写 LoopX registry。 +- 官方 dashboard(React 19 / Vite 8)读取 `/status.json`,以 zod 契约校验(`apps/presentation/dashboard/src/data/status.ts`),并通过 `status_contract.schema_version` 与 `minimum_dashboard_schema_version` 判断兼容性。 +- 写操作已经有公开入口:`/api/chat/todo/dry-run` 与 `/api/chat/todo/apply`(Todo 预览与提交)、`/api/actions/*`、`/api/chat/request-control`、`/api/chat/codex-attached`(Attached Session)、`/api/ssh-source/*` 与 `/ssh-hosts`(`ssh_host_catalog_v0`)。 +- 会话执行模式由 [Agent 会话执行模式](agent-session-execution-modes-v0.zh-CN.md) 定义:Attached 模式由外部宿主保留进程与会话所有权;Managed 模式由 LoopX 启动并以 `loopx_turn_v0` 事务推进。 +- 额度观测见 [算力额度](../../quota-allocation.md):`loopx quota status/plan` 是按 Goal 过滤的只读观测。 + +**Calli(`87adcde`)** + +- `packages/web`:React 18 / Vite 5 / 自写 CSS。三栏布局、机器切换条、启动条和 Triage 抽屉已经实现。 +- `packages/daemon`:Node 后端,SQLite 存储,目前是 Calli 所有状态的拥有者。其中**属于 L0 的**:`hosts.ts`(SSH 隧道登记、退避重连、失败分类 `no_ssh/host_key/auth/unreachable/ssh_failed/daemon_missing/forward_denied`)、`adapters/*`(codex、claude、pi、traex、zcode、agy、dsh、acp 等)、`auto-handover.ts` 与 `quota-resume.ts`(额度窗口、阈值、跨账号顺序、额度恢复后切回)。**属于 L1、需要删除的**:`todos` 系列表、`teams`、`coordination`、自建交接状态机。 +- `packages/ext-loopx`:stdio JSON-RPC 插件,经 `loopx status --format json` 读取 `worksource.snapshot`。源码以 `version === '1.4.2'` 判定兼容,与当前 LoopX 2.0 不匹配。 + +## 5. 提议架构 + +### 5.1 目录与放置 + +用户层面的硬要求是:Calli 界面单独一个目录,与 LoopX 核心目录明确分开。建议如下(**最终位置由 maintainer 决定,见 §12 D1**): + +```text +apps/presentation/ + dashboard/ # 官方 dashboard,不变 + calli-workbench/ # 新增:Calli 三栏工作台(L3) + package.json # 独立构建;React/Vite 版本与 dashboard 对齐 + src/data/ # 只放投影 schema 与只读查询;不放任何状态存储 + smoke/ # fixture 驱动的浏览器 smoke + README.md +packages/ + loopx-session-fabric/ # 新增:L0 会话底座(可选分发,默认关闭) + extension.toml + src/hosts/ # SSH 多机:作为 ssh_host_catalog_v0 的 provider + src/attached/ # 各 CLI 的 Attached 适配器,一个适配器一个 PR + src/quota/ # 额度窗口观测与交接建议 +``` + +理由: + +- **符合现有分层。** 工作台只渲染投影、提交命令,正是 `apps/presentation/` 的定义;会话底座是可独立安装、可卸载的宿主能力,正是 `packages/` 的定义。两者都不碰 `loopx/`。 +- **便于审核与回滚。** 每个目录有独立的 `package.json` 和 CODEOWNERS 行,可以按目录授予或撤回合并权限;删除一个目录就是完整回滚。 +- **与官方 dashboard 并列而不是嵌入。** 嵌入 dashboard 会让两套交互模型在同一路由树里交叉,也违背「单独目录」的要求。 + +备选位置:`apps/calli-workbench/`(与 `apps/presentation/` 平级,隔离更强但脱离「展示应用」分组);将 L0 拆为多个包(如 `packages/loopx-host-ssh/`、`packages/loopx-attached-/`)。 + +### 5.2 所有权与权威 + +| 事实 | 唯一所有者 | 工作台如何得到 | 工作台如何修改 | +| --- | --- | --- | --- | +| Goal / Todo / claim / Gate | `loopx-core` | `/status.json` 及其子投影 | `/api/chat/todo/dry-run` → `/api/chat/todo/apply`;`/api/actions/*`;`/api/chat/request-control` | +| 会话消息、流式输出 | 执行宿主(Attached 时为外部 CLI;Managed 时为 LoopX) | `/api/chat/sessions/*` | 同一接口发送 | +| Inbox / 需要人处理的 Gate | `loopx-core` | 与 Lark 管家相同的投影 | 同一个确认命令 | +| 机器拓扑与连接状态 | 会话底座(L0) | 以 `ssh_host_catalog_v0` 及其附加字段公开 | `/api/ssh-source/*` | +| 额度窗口观测 | 会话底座(L0),作为 quota 的观测 provider | 附加到额度观测投影 | 不可写,只可由用户在 Gate 中确认交接 | +| 主题、栏宽、当前机器 | 浏览器本地 | `localStorage` | 本地 | + +被禁止的替代权威:工作台的本地状态、会话底座的私有 SQLite、Calli daemon 的任何表,都不得被读作 Todo 是否完成、Gate 是否已处理、谁持有 lease 的依据。 + +### 5.3 工作台改造为「LoopX 投影消费者」 + +- **读取。** 工作台的数据层只由 zod schema 和只读查询组成,复用或镜像 dashboard 的 `status.ts` 契约;启动时校验 `status_contract.schema_version`,不兼容时显示「需要更新本机 LoopX 服务」而不是尝试猜测。 +- **Triage 抽屉的三组完全由投影派生:** + - 「需要你」= 投影中待人处理的 Gate、待决定事项与 Inbox 条目; + - 「在跑」= 持有有效 lease 的 Todo 与活跃会话; + - 「出错」= 失败或被阻塞的 receipt、离线机器、额度耗尽的会话。 + 如果现有投影缺少某个分组需要的字段,先单独提交一个对状态契约的**附加字段** PR(依 [RFC README](README.md#when-a-change-needs-an-rfc),附加字段不需要 RFC),工作台再读取它。工作台自己不做任何「推断完成」。 +- **写入。** 所有改变 Goal/Todo/Gate 的操作都先调用 dry-run 预览,再 apply,并读回投影确认结果。失败或冲突时展示控制面返回的类型化错误,不在本地乐观更新业务状态。 +- **设计系统。** 遵循 [LoopX 设计系统](../../development/design.md):Geist 字体、黑白细线面、克制的强调色、设计过的空态/加载态/错误态和状态字形;Calli 自写 CSS 迁移为 LoopX 的 CSS 自定义属性,并通过 `check:css-custom-properties` 同类检查。每个 UI PR 附公开安全的截图,并按该文档的 Populated Page Review 自查。React 与 Vite 升级到与 dashboard 一致的版本。 + +### 5.4 与 Lark 管家共用 Inbox/Gate 投影 + +工作台的「需要你」与 Lark 管家读取的是同一个 Inbox/Gate 投影,确认走同一个控制面命令,并带同一个幂等标识。工作台不发自己的通知;需要提醒时只显示投影里已有的条目。由此满足 I3:在 Lark 里确认的 Gate,工作台在下一次投影刷新时移除;反之亦然。 + +### 5.5 L0 会话底座 + +**SSH 多机:并入现有模型,而不是并列一套。** LoopX 已有 `ssh_host_catalog_v0` 与 `/api/ssh-source/*`。会话底座以 provider 的方式为它补充 Calli 已经验证过的能力:Unix socket 隧道、`BatchMode=yes`、不替用户接受未知主机密钥、2 秒到 2 分钟的退避重连、15 秒健康检查和类型化失败码。机器的身份与别名仍以 `ssh_host_catalog_v0` 为准,Calli 的 `hosts.json` 不再作为来源。远端访问方式保持可替换:本地 SSH 是第一个实现,未来的云端或网关来源按 [路线图 R6 本地/云端收敛](loopx-overall-roadmap-v0.zh-CN.md) 接入同一个接口。 + +**异构 CLI 挂接:对应 Attached Session。** 每个 Calli 适配器移植为一个 Attached 宿主适配器,遵守 [Agent 会话执行模式](agent-session-execution-modes-v0.zh-CN.md) 的准入契约:外部 CLI 保留进程、会话和中断所有权;LoopX 记录绑定和 turn 边界。适配器之间互不依赖,一个 PR 移植一个,从已有 LoopX 对应物的适配器开始(Codex、pi、dsh)。Managed Host 负责的进程启动、worktree 隔离与 turn fencing 不在本包中重复实现;本包只在 Attached 一侧补齐,两侧拼成完整的会话底座。 + +**额度感知交接:从「执行动作」改为「受治理的提议」。** Calli 现有策略是按可配置阈值行动(例如约 85% 时压缩上下文并切到更便宜的模型,约 90% 时跨账号交接,额度恢复后切回)。合入后: + +1. 会话底座只负责**观测**:把每个宿主账号的额度窗口(已用百分比、重置时间、适用模型)作为 quota 观测 provider 上报,不对外暴露账号凭据或账号身份,只使用不透明的 profile 标识。 +2. 是否切换由 LoopX 的额度与准入规则**决定**;切换在当前 turn 的 fence 处发生:旧会话结束本 turn → 释放 lease → 新会话以新的 profile 重新获得同一 Todo 的 lease → 由 receipt 记录交接。 +3. 默认关闭;开启时每次切换在 Inbox 里留下可审计的记录;用户可以要求「切换前先问我」,此时它就是一个普通 Gate。 +4. 「额度恢复后切回」同样走一次完整的 fence → lease 流程,不允许静默切换。 + +### 5.6 `ext-loopx` 插件:从版本硬编码改为契约探测 + +`ext-loopx` 只服务于继续单独使用 Calli 的用户(合入 LoopX 的工作台不需要它)。改动: + +- 删除 `version === '1.4.2'` 判定;改为读取 `loopx status --format json` 的 `status_contract.schema_version`,与插件声明的已知区间比较。 +- 结果分三类:`compatible`(正常显示)、`newer_unverified`(以只读方式显示,并标注「未验证的较新契约」)、`incompatible`(只显示原因,不解析)。 +- 可选能力(例如 Inbox 投影、额度观测)按字段是否存在逐项启用,不再按版本号推断。 +- 补充契约测试:1.4.2 fixture、2.0 fixture、缺字段 fixture、未知 schema 版本 fixture。 + +此项改动在 Calli 仓库内完成,不进入 LoopX PR。 + +### 5.7 命令生命周期与失败处理 + +- 所有写命令带幂等键;超时或连接中断后先读回投影判断是否已生效,再决定是否重试。 +- 投影过期(超过刷新周期)时,工作台把相关区域标为「可能过时」,并禁用依赖该数据的写操作。 +- 会话底座崩溃不影响 `loopx-core`:Attached 会话所有权本来就在外部 CLI,底座重启后按 `ssh_host_catalog_v0` 与绑定记录重新挂接。 + +## 6. 备选方案与取舍 + +| 方案 | 结论 | 原因 | +| --- | --- | --- | +| A. Calli 继续独立,只通过 `ext-loopx` 读 LoopX | 拒绝作为终态 | 双权威问题依旧存在,同步永远是调和 | +| B. 把 Calli daemon 整体搬进 LoopX,再逐步收敛 | 拒绝 | 合入当天即引入第二个状态权威,违反 I1;审核面过大 | +| C. 工作台作为 dashboard 内的一个路由 | 拒绝作为默认 | 违背单独目录要求;两套交互模型混在一个路由树中 | +| D. **独立前端目录 + 可选 L0 包 + 删除 Calli L1** | **采纳** | 满足 I1–I6;每一步可单独合并、单独回滚 | + +## 7. 安全、隐私与兼容 + +- **默认关闭等价(I5):** 两个目录不进入 `loopx-core` 的启动闭包;CI 增加一项检查,确认未安装时 `loopx status` 输出不变。 +- **凭据边界:** SSH 凭据与主机密钥策略只在运行用户的 OpenSSH 中;会话底座不保存密钥、不转发浏览器 token。各 agent 的账号凭据不进入投影、日志或 receipt。 +- **公开与私有边界:** fixture、截图和测试数据全部合成,不含真实会话、真实路径或真实账号;遵守 [公开与私有边界](../../public-private-boundary.md)。 +- **许可:** Calli 为 MIT,LoopX 为 Apache-2.0。移植的代码由作者以 Apache-2.0 重新提交并附 DCO 签名;其他贡献者的代码需取得其签名或重写(见 §12 D5)。 +- **混合版本:** 工作台通过 `status_contract.schema_version` 拒绝不兼容的服务端;会话底座在 `extension.toml` 中声明最低 `loopx-core` 版本。 + +## 8. 迁移与回滚 + +**Calli 现有用户** + +1. 独立版 Calli 继续可用,`ext-loopx` 改为契约探测(§5.6)。 +2. 提供一次性导出工具:把 Calli 的待办、备注和关联线程导出为 LoopX Todo 提案,**先 dry-run**,由用户逐项确认后经 `/api/chat/todo/apply` 写入,最后读回投影核对条数和文字。`owner: me|agent` 映射为 Todo 的负责方,`waitingOn` 映射为 Gate 或等待说明,二者的映射规则写在迁移工具的 README 里。 +3. 导入成功后,Calli 的旧表变为只读并在界面标注「已迁入 LoopX」;用户明确确认后才删除。导出文件保留在用户本机,不上传。 + +**Calli daemon 状态表的收敛路线** + +| 表 / 模块 | 去向 | +| --- | --- | +| `todos`、`todo_threads`、`todo_notes`、`todo_proposals`、`sections`、`wishes`、`todo_summaries` | 迁入 LoopX Todo 后删除 | +| `teams`、`coordination`、自建交接状态机 | 删除;由 LoopX Goal 协作与语义交接替代 | +| `schedules`、`schedule_runs` | 待定(§12 D4):并入 LoopX 调度,或保持为纯宿主层的定时触发 | +| `hosts.json`、隧道 | 并入 `ssh_host_catalog_v0` provider | +| 额度窗口、交接设置 | 作为 L0 观测与用户偏好;交接决策移交 LoopX | +| 线程、事件、turn 文本 | Attached 时属于外部 CLI;工作台通过 `/api/chat/sessions/*` 读取 | + +**回滚:** 每个阶段的 PR 只新增目录或附加字段,回滚就是 revert 该 PR。迁移工具写入的 Todo 是普通 LoopX Todo,不依赖 Calli 存在;旧表在用户确认删除前一直保留,所以迁移回滚只需停用导入结果。 + +## 9. 验证与验收 + +| 声明 | 测试或证据 | 要求结果 | 不证明什么 | +| --- | --- | --- | --- | +| 默认关闭等价 | 未安装两个目录时运行 `loopx status --format json` 与 dashboard 构建,与基线对比 | 输出一致 | 不证明启用后的行为 | +| 工作台无第二状态源 | 静态检查:`calli-workbench/src` 中无对 Goal/Todo/Gate 的持久化写入;清空浏览器存储后重新加载 | 页面内容与投影一致 | 不证明服务端正确 | +| 写操作只走控制面 | 浏览器 smoke:拦截网络,所有修改请求只命中 dry-run/apply/actions/request-control | 无其他写端点 | 不覆盖未来新增入口 | +| 一个 Gate 一次确认(I3) | fixture 驱动:在 Lark 侧确认同一 Gate 后刷新工作台 | 「需要你」中该条目消失 | 不证明真实 Lark 网络链路 | +| 交接受 fencing 约束(I4) | 两个模拟 profile,额度越过阈值时触发交接;检查 lease 与 receipt 序列 | 任意时刻同一 Todo 至多一个 lease;有交接 receipt | 不证明真实账号额度接口准确 | +| SSH 多机单一模型 | 同一台机器只在 `ssh_host_catalog_v0` 中出现一次;七种失败码各有 fixture | 无重复机器;失败码与界面文案一一对应 | 不替代真实机器部署验收 | +| `ext-loopx` 契约探测 | 1.4.2、2.0、缺字段、未知版本四个 fixture | 分别为 compatible / compatible / 只读降级 / incompatible | 不证明所有未来版本 | +| 设计一致 | 按设计系统的 Populated Page Review 提交桌面与手机、亮色与暗色截图 | 评审通过 | 截图不等于可用性研究 | +| 迁移可读回 | 合成 Calli 数据库 → dry-run → apply → 读回 | 条数与文字一致;重复执行幂等 | 不覆盖用户自定义字段 | + +确定性测试、真实环境验收、性能数据与默认开启分开报告;未运行或跳过的行不算通过。 + +## 10. 运行契约 + +- **可观测性:** 工作台在页脚显示投影来源、`schema_version` 与新鲜度;会话底座通过现有 doctor 输出连接状态和失败码。 +- **类型化失败:** SSH 失败码沿用 Calli 已验证的七类;额度观测缺失时标为「未知」,不做切换。 +- **容量:** 每台机器一个 SSH 子进程;投影轮询沿用 dashboard 的频率,不另起高频轮询。 +- **升级与降级:** 工作台与 `loopx-core` 通过 schema 版本协商;会话底座可以单独卸载,卸载后 Attached 会话仍由各 CLI 保有。 + +## 11. 规范性交付计划 + +每个里程碑都是独立、可合并、可回滚的小 PR(或一组小 PR),使用 `codex/` 分支和独立 worktree,每个 commit 带 `Signed-off-by`。 + +| 里程碑 | 交付行为 | 进入条件 | 退出证据 | 回滚 | +| --- | --- | --- | --- | --- | +| **M0 RFC** | 本 RFC 中英文一对 | — | `check_rfc_bilingual.py` 通过;maintainer 对 §12 D1–D3 给出决定 | revert | +| **M1 工作台外壳(最快路径)** | `apps/presentation/calli-workbench/`:三栏布局、机器切换、启动条、会话视图;只读 `/status.json` 与 `/api/chat/sessions/*`;不改 `loopx/` | M0 合入;D1 已定 | fixture smoke、构建、截图、无第二状态源检查 | 删除目录 | +| **M2 Triage 与写入** | 「需要你 / 在跑 / 出错」抽屉;Todo/Gate 写入走 dry-run/apply;与 Lark 管家共用 Inbox;必要时先提交状态契约附加字段的独立 PR | M1 合入 | I3 smoke;写端点拦截 smoke | revert;附加字段可保留 | +| **M3 SSH 多机 provider** | `packages/loopx-session-fabric/` 首个模块:为 `ssh_host_catalog_v0` 提供隧道、重连与失败分类 | M1 合入;D2 已定 | 七类失败码 fixture;单一机器模型检查 | 卸载包 | +| **M4 Attached 适配器** | 每个 CLI 一个 PR,按 Codex → pi → dsh → 其他顺序 | M3 合入 | 每个适配器的绑定/detach/turn 边界 smoke | 卸载单个适配器 | +| **M5 额度观测与受治理交接** | 额度窗口作为 quota 观测 provider;交接按 fence → lease → receipt;默认关闭 | M4 至少一个适配器合入;maintainer 对额度策略授权 | I4 smoke;默认关闭等价 | 关闭开关;卸载模块 | +| **M6 Calli 数据迁入与 L1 退役** | 一次性迁移工具;Calli 独立版删除任务、团队、协作表;`ext-loopx` 契约探测 | M2 合入 | 迁移读回测试;Calli 侧回归 | 旧表在确认删除前保留 | + +M1 是「最快可用」的切面:只要 M0 合入并确定目录位置,M1 即可独立评审,不需要等待任何核心改动。 + +## 12. 待决事项 + +| 编号 | 问题 | 决定人 | 选项 | 建议 | 依赖 | +| --- | --- | --- | --- | --- | --- | +| D1 | 工作台目录位置 | maintainer | `apps/presentation/calli-workbench/` / `apps/calli-workbench/` | 前者,与 dashboard 并列 | M1 | +| D2 | L0 包边界 | maintainer | 一个 `loopx-session-fabric` 包 / 按能力拆为多个包 | 先一个包、内部按目录分模块,等第二个使用方出现再拆 | M3 | +| D3 | 命名 | maintainer | 是否保留「Calli」作为产品名,或改为中性名称(如「LoopX Workbench」) | 目录用 `calli-workbench` 便于溯源;界面名称由 maintainer 定 | M1 | +| D4 | 定时任务归属 | maintainer | 并入 LoopX 调度 / 留在宿主层 | 并入 LoopX 调度,避免第二个调度器 | M6 | +| D5 | 许可与历史 | 作者 + maintainer | 带历史合入 / 以新提交重新贡献 | 以新提交重新贡献,保持 LoopX 历史干净、DCO 完整 | M1 | +| D6 | 与官方 dashboard 的长期关系 | maintainer | 长期并存 / 未来合并组件 | 先并存,以使用数据决定 | M2 之后 | + +建议在相应决策记录进入附录 B 之前均不具约束力。 + +--- + +## 附录 A:执行记录(非规范) + +合入后在 `ledger/calli-workbench-and-session-fabric-v0/` 下记录。 + +## 附录 B:决策记录 + +| 日期 | 决定 | 负责人 / 批准 | 备选 | 修改的规范章节 | +| --- | --- | --- | --- | --- | +| — | — | — | — | — |