Skip to content

docs(rfc): Calli workbench and session fabric v0 - #8778

Open
maxliux5 wants to merge 1 commit into
loopx-project:mainfrom
maxliux5:codex/rfc-calli-workbench
Open

maxliux5 wants to merge 1 commit into
loopx-project:mainfrom
maxliux5:codex/rfc-calli-workbench

Conversation

@maxliux5

Copy link
Copy Markdown
Collaborator

Summary

This RFC proposes how Calli, a multi-agent
workbench (MIT), can join LoopX without
creating a second source of truth. It is docs only: no change to loopx/,
apps/** or packages/** in this PR.

The proposal is organized in four layers that map onto the existing ownership
table in monorepo-distribution-split-v0 §5:

Layer What Calli contributes Where
L0 Host & Session Fabric SSH multi-host tunnels, Attached adapters for existing CLIs (local and remote native threads), quota-window observation for multi-account handover. Complements Managed Host rather than duplicating it packages/loopx-session-fabric/ (optional, default-off)
L1 Governance Kernel Nothing. Calli drops its own task table, handover state machine and team/coordination model; Goal/Todo/Gate stay in loopx-core —
L2 Capability Packs Nothing new in core; research-oriented extensions stay out and hidden by default —
L3 Unified Surfaces Three-pane workbench: machine switcher, "host + machine + model" launch bar, "Needs you / Running / Failed" triage drawer, sharing one Inbox/Gate projection with the Lark steward apps/presentation/calli-workbench/ (separate directory beside the dashboard)

How dual authority is avoided

  • One ledger. The workbench reads /status.json and existing projections;
    every Goal/Todo/Gate change goes through /api/chat/todo/dry-run → apply,
    /api/actions/* or /api/chat/request-control, then reads back. It stores
    only display preferences locally.
  • One steward. "Needs you" and the Lark steward read the same Inbox/Gate
    projection and confirm through the same command.
  • One multi-host model. Calli's SSH tunnel and reconnect logic becomes a
    provider for the existing ssh_host_catalog_v0, not a parallel registry.
  • One handover semantics. Quota switching becomes a governed proposal:
    the fabric only observes quota windows; switching happens at the turn fence
    with lease release/reacquire and a receipt, default-off.

Delivery plan (each step a small, revertible PR)

  • M0 this RFC (en + zh-CN).
  • M1 workbench shell in its own directory, read-only on public projections,
    no core change — the fastest usable slice.
  • M2 triage drawer and control-plane writes; additive status-contract
    fields in a separate PR if needed.
  • M3 SSH provider for ssh_host_catalog_v0.
  • M4 Attached adapters, one CLI per PR (Codex → pi → dsh → others).
  • M5 quota observation and fenced handover, default-off, after explicit
    maintainer authorization of the quota policy.
  • M6 one-time import of existing Calli todos via dry-run/apply; Calli's own
    task tables retired.

UI work follows docs/development/design.md, with
public-safe screenshots and a Populated Page Review in each UI PR.

Decisions requested from maintainers

  1. D1 Workbench directory: apps/presentation/calli-workbench/ (proposed)
    or apps/calli-workbench/.
  2. D2 L0 boundary: one loopx-session-fabric package (proposed) or
    several per-capability packages.
  3. D3 Naming: keep "Calli" or use a neutral product name.

D4–D6 (scheduler ownership, license/history, long-term relationship with the
dashboard) are listed in §12 and do not block M1.

Validation

  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD
  • python3 scripts/generate_rfc_status_index.py --check (and --write if the index needs the new entry)
  • Public/private scan: no credentials, local paths, private links or internal material

中文摘要

本 RFC 提议 Calli 以「独立目录的工作台(L3)+ 可选会话底座包(L0)」进入 LoopX,并删除 Calli 自建的任务、交接状态机和团队协作,Goal/Todo/Gate 统一由 loopx-core 管理。工作台只读公开投影、写操作只走控制面 API,与 Lark 管家共用同一 Inbox/Gate 投影。落地分 M0–M6 七步,每步一个可单独合并、可回滚的小 PR;M1 不改核心,是最快可用的切面。需要 maintainer 决定目录位置、L0 包边界和命名。

🤖 Generated with Claude Code

Propose absorbing the Calli operator workbench as a separate
apps/presentation/calli-workbench/ surface and its host/session
capabilities as a default-off packages/loopx-session-fabric/
optional distribution, with Goal/Todo/Gate authority staying in
loopx-core and Calli's own task tables retired. Delivery is staged
as independent M0-M6 PRs; directory placement, L0 package boundary
and naming are listed as maintainer decisions D1-D3.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Signed-off-by: maxliux5 <lualiudd@gmail.com>
@cocolord

Copy link
Copy Markdown
Member

@maxliux5 请在 RFC 中补充「与现有工作台的用户任务差异,以及新增多机器会话入口的必要性」的论证。

当前 §5.1 解释了目录放置、可审查/回滚,以及与 dashboard 并列的方式;这些回答了怎么隔离实现,还没有回答为什么用户需要再进入一套工作台。共享一个状态权威是必要的架构约束,但第二套界面的入口、设置、交互和维护成本仍需单独论证。独立目录与独立产品入口也应分别讨论。

对照 main 的 58cc5817e,已有:

这些来源不证明现有界面已经覆盖全部异构 CLI 或多机器旅程;请据此明确缺口,而不是仅以三栏布局、已有 Calli 界面或「单独目录」作为新入口的理由。

建议在本 RFC 中给出:

  1. 具体用户与完整任务。 用户为什么从现有工作台切到 Calli?请用两三个真实任务比较:查看/接手不同机器的原生会话、把会话绑定到共同 Goal、处理待决事项、交接执行并回读结果。标明现有入口、已交付边界、失败点和 Calli 的可观察改善;区分纯会话管理与共享 Goal 协作。
  2. 功能缺口对照。 对机器发现/选择、会话发现/读取/输入、宿主与模型选择、Attached/Managed、Inbox/Gate、额度观测与交接逐项说明:现有实现覆盖什么、需要补哪些 provider/adapter、哪些变化必须由新的界面承担。每项给当前代码/契约与实际使用证据;有 backend 能力不等于已有完整 UI,但 UI 重排本身也不证明新能力。
  3. 三种方案的比较。 A:扩展现有 Personal Workspace 的多机器/会话旅程;B:先补 L0 会话底座并复用现有界面;C:独立 Calli 工作台。比较用户入口与导航成本、操作/恢复路径、配置重复、权限一致性、可访问性、打包升级和持续维护成本。若选 C,请说明独立产品入口不可替代的优势,以及什么证据会使该选择重新评估。
  4. 最小交付与退出证据。 M1 要交付哪条真实任务链,而不只是 demo 外壳?通过同一用户任务的现有/新界面对比、长内容与多机器混合状态、失败恢复和正确结果读回来验证。真实 backend、合成预览和安装态分开标识。另请明确:有价值的 L0 缺口是否可以独立交付,以及它为什么需要或不需要等待新的工作台。

这次请求是产品必要性与方案选择的设计澄清,不是合并结论。请把论证更新到双语 RFC,让后续评审能判断「为什么需要这个入口」,再讨论目录和命名。

English: Please justify the new workbench against the existing Personal Workspace with concrete user journeys, verified capability gaps, and a comparison of extending the current UI, adding only the session fabric, and shipping a separate frontend. One state authority and a separate directory do not by themselves establish the need for a second product entry point.

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.1-sol · OpenAI · runtime_reported · reasoning_effort=max

评审提交 20d6ae692a68a3b3a7c61a9bdab098ef4676ff05,分叉基线 80c6949727c1f239fd0b105dd01cf556091c8b02,对照当前主干 74ca883d5bd3e4bc64671bac54210eac9e97ed05。这是 RFC 评审。

[P2] 指定的迁移接口不能保留负责方及等待条件。 M6 迁移一个等待本人确认、带备注和关联会话的 Calli Todo。 File 和 SQLite 上,现有 HTTP 入口对负责方、等待条件、备注和会话等字段返回 400。只提交文本时创建无这些事实、可选入候选工作的 open Agent Todo。该接口不能将一条待人确认的记录原样迁入。 位置

[P2] 断线时读投影不能恢复原写入收据。 M2 或 M6 的 apply 已提交,但浏览器丢失响应,显示随后发生独立更新。 在两库中让原 apply 提交并丢弃返回,再提交不相关工作。原 preview_id 重试得到 409/preview_stale;此前迁入的 Todo 仍存在,修订未因重试改变。投影和返回的本次失败均不能回读原提交身份。 位置

[P2] 仅有租约和收据无法证明 Attached 旧宿主已停止。 M5 触发账号切换时,旧的外部宿主失联或仍有已发出的工具操作。 M5 的验收只要求仓库内至多一把租约和一张收据;没有证明外部 Attached 宿主已停止、旧的结果或工具效果不会迟到,也没有定义遇到未知原结果时谁阻止新 Profile 启动。没有第二把租约仍可能发生外部双执行。 位置

动机 / Motivation

已经用 Calli 记录任务并在多台机器继续工作的用户,需要把这些任务接回 LoopX,并知道遇到等待、断线或换账号后哪一边仍然负责。 两边编辑同一条任务时,完成或等待状态会各自变化。RFC 拟让独立工作台读 LoopX 投影,逐步使用原确认、迁移和宿主交接,在最早的只读阶段先让用户查看任务与会话。 精确候选只有文档。工作台与控制面分开、M1 只读及现有 Todo 文本预览确实可作为增量起点;两种语言的配对和生成索引通过。 本次只评审 M0 的设计与验收门。没有安装工作台或会话包,没有验证线上通知、跨账号执行或发布。目录、包边界和命名继续是维护者决策。

改动思路 / Approach

独立工作台读公开投影、LoopX 持有唯一业务权威,这个切分可以保留。让 M1 保持只读;把 M2 的一次真实确认及原操作恢复、M5 的观察与实际接力、M6 的单条完整迁移分别成为各阶段可验证的结果。分发契约 · Attached 的执行和停止所有权 · 原效果回执恢复。

具体改动 / Changes

5 个文档,增加 781 行、删除 2 行。两种语言写下 M0–M6,以及三个近期维护者选项。§8 对迁移的描述超过当前 Todo API 能表达的范围;现有 HTTP 入参 和 写入 owner 只能按预览提交文本并创建普通 Agent 工作。另一路受审 Actions 已有明确提案与回执,可复用其原操作恢复,不能把每种写入简化为读一次投影。§9 的切换和迁移验收应分别加入停止/迟到确认,以及责任、等待与关联来源读回。对照 主干路线图,只读工作台 可保留先行;迁移保留权威事实、原操作恢复、旧宿主停止与新准入 都需要具体说明。这一轮只修改验收设计,M0 不需要先实现它们。

对主干的风险 / Risks

双语脚本、生成索引、DCO、diff、与当前主干的模拟合并均通过。实际 Todo HTTP 两库负例通过,另外现有 Todo/动作回执对照 14 项通过。 当前候选不会直接改变主干执行行为,风险是后续实现照规范通过错误的验收。本轮用真实本地 HTTP、File 和 SQLite 测了已存在的路径;复现模拟了调用者丢失已提交的响应。没有测试未来 Calli 前端、真实 Lark、SSH、跨账号停止或托管 CI。

我的整体评价 / Verdict

请求修改设计合同。保留选用现有控制面的方向和只读 M1,补齐后续写入恢复、真实迁移及 Attached 接力门槛。把未覆盖范围写成未来验收,不把过期显示、单租约或文本条数当成已经读回原结果。

English verdict: REQUEST_CHANGES at 20d6ae6. The proposed migration endpoint cannot preserve ownership and wait relationships. Read back ambiguous writes by their original authoritative operation, and require proven quiescence and stale-result rejection before an Attached profile handover.


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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 指定的迁移接口不能保留负责方及等待条件。 File 和 SQLite 上,现有 HTTP 入口对负责方、等待条件、备注和会话等字段返回 400。只提交文本时创建无这些事实、可选入候选工作的 open Agent Todo。该接口不能将一条待人确认的记录原样迁入。 先用现有有作用域的 canonical create/update/关系与原操作回读定义一个完整的小样本;按原目标/负责方/等待状态/安全可访问的上下文逐项验收,无法表示的记录保持旧源权威,禁止据此将其变为可执行 Todo 或退役旧记录。


### 5.7 Command lifecycle and failure handling

- Every write carries an idempotency key; after a timeout or disconnect the

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 断线时读投影不能恢复原写入收据。 在两库中让原 apply 提交并丢弃返回,再提交不相关工作。原 preview_id 重试得到 409/preview_stale;此前迁入的 Todo 仍存在,修订未因重试改变。投影和返回的本次失败均不能回读原提交身份。 指定每类写入已有的 owner、原提案/请求身份和精确回执恢复;在原收据或权威证明缺失时保留未知,不因投影迟到创建新预览或发出新写入。

| 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 |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 仅有租约和收据无法证明 Attached 旧宿主已停止。 M5 的验收只要求仓库内至多一把租约和一张收据;没有证明外部 Attached 宿主已停止、旧的结果或工具效果不会迟到,也没有定义遇到未知原结果时谁阻止新 Profile 启动。没有第二把租约仍可能发生外部双执行。 M5 首阶段只观察并建议;若要交付可自动切换,先在现有 Host/绑定和 Turn owner 上明确停止确认、原效果/结算恢复、目标 Profile 新准入以及旧代际迟到结果拒绝。相同条件适用于切回。

@loopx-agent

Copy link
Copy Markdown
Collaborator

基于当前精确版本群核验(#8778@20d6ae692a、#8782@1b582b554e、#8783@9c53d15f91、#8784@f3a2788bbb、#8843@e1087d9032),直接回应 #issuecomment-6882346040 的方案对比与 L0 独立交付问题:

  1. 为什么不应经由 #8782–#8784(+40k / +44k 行 apps/presentation/calli-workbench/)或 #8843(+192,784 / -4 行、881 个文件 apps/workbench/)引入第二套前端壳层与守护进程:
    • main 已有 ssh_host_catalog_v0(loopx/control_plane/status/ssh_host_catalog.py、apps/presentation/dashboard/src/data/ssh-host-catalog.ts)与 Goal 作用域挂接/托管会话页面(loopx/presentation/codex_attached_api.py、attached-agent-conversations.tsx、goal-agent-work-page.tsx)。
    • #8783/#8784 与 #8843 若作为独立前端与独立 Node 守护进程并入,会产生两套导航、两套样式与代理面,并直接与 #8778 §3 Non-goals(不整体搬迁 calli 守护进程、不另建 todos/调度器权威)冲突。
  2. 推荐收敛路线(方案 B:独立交付 L0 底座并嵌入既有单一 Goal 工作台):
    • L0 主机就绪观测、不透明 profile 额度窗口及受 Turn/租约围栏保护的交接前置检查完全不需要等待新工作台即可独立交付。
    • 我们已将最小可独立评审的 L0 Session & Quota Fabric 契约(TypeScript 纯函数与双语收敛 RFC) 拆出为伴随 PR:feat(control-plane,rfc): add L0 session & quota fabric contract for single-workbench convergence #8886 。
    • 后续按 #8886 的 M1(将 codex_attached_api.py 从硬编码 host_surface == "codex-app" 泛化为按能力解析 + 可选挂载 SSH 探活)与 M2(将机器切换、多 CLI 会话、额度徽标与共享 Gate 交接直接嵌入 GoalAgentWorkPage)分小 PR 收口即可,无需再合并 4 万–19 万行平行壳层。

@mergify

mergify Bot commented Nov 17, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @maxliux5.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added needs-rebase Mergify: the pull request has merge conflicts with its base branch and removed needs-rebase Mergify: the pull request has merge conflicts with its base branch labels Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants