docs(rfc): clarify capability projection across session modes

[huangruiteng]

Summary

• clarify that attached and managed working sessions project the same existing Goal-bound external capabilities
• keep extension lifecycle, caller-outcome capability contracts, and optional domain capability packs as distinct existing owners
• require material operations to preserve work-attempt authority, validation, provider readback, and settlement evidence in both modes
• make toolkit repositories and prompt skills explicit non-authority sources instead of introducing a parallel toolkit schema

Validation

• git diff --check
• python3 examples/docs-governance-smoke.py
• python3 -m loopx.cli check --scan-path docs/architecture/rfcs/desktop-execution-frontends-v0.md
• loopx canary premerge --from-git-diff

The contract scan reports only pre-existing active-state projection warnings outside the changed RFC.

[huangruiteng]

@maxliu This is the focused follow-up to #3351: it clarifies that attached and managed Agent sessions project the same existing Goal-bound external capabilities, without adding a parallel toolkit schema or authorization layer. Could you review the frontend/session semantics and capability boundary when convenient?

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Exact head reviewed: 17a2d97198f73e7f12a34222461c7e4c8ea93ac0

动机

现有 RFC 已经分别定义了 Desktop 的 attached/managed 执行模式、runtime adapter 与 provider profile，但没有把“Agent 最终能看到哪些外部能力”明确收口到同一个 Goal binding。缺少这段约束时，实现方容易误把 toolkit 仓库、安装动作、prompt skill 或同名 provider 当成授权来源，也容易在 attached 与 managed 两条路径上形成不同的能力和结算语义。

改动思路

本 PR 没有再发明一个 external toolkit 运行时对象，而是复用已有的三层边界：extension 负责安装与生命周期，external capability 负责 caller-outcome/权限/schema/readback/receipt，必要时由 domain capability pack 承担领域策略和投影。两种会话模式都从 Agent 的 Goal binding 投影能力；material operation 还必须绑定当前被授权的 work attempt，并继续经过验证、provider readback 与 settlement。Goal/Todo 状态写入权仍只属于 LoopX control plane。

具体改动

关键内容讲解

• 在 Desktop execution RFC 中新增 “Goal-bound external capabilities in both modes”，明确 attached 与 managed 使用同一 Goal-bound 能力来源和 exact ready provider revision。
• 区分 read-only reuse 与 material operation：前者不创造 work truth，后者必须进入 managed Turn 或 attached host/automation 的等价授权与结算链路。
• 明确 toolkit 仓库只是 source distribution；安装、发现 prompt skill 或观察到同名 provider 都不自动授予执行权限，重复 provider 在未被 Goal binding 精确选择时 fail closed。
• 补齐 owner-local 隐私边界：credentials、provider coordinates、logs/traces/rows/content 不进入 LoopX durable state，只保留 public-safe identity、revision/profile digest、evidence reference 和 admitted receipt。
• 在 shared validation criteria、non-goals 与 references 中同步加入外部能力的可验收约束，避免正文成为孤立说明。

改动仅涉及 1 个 RFC 文件、43 行新增；每一段都服务于同一能力归属与授权边界，没有引入未被调用的代码结构。与 docs/reference/extensions.md、control-plane course 的 extension/Todo/Turn 边界，以及 attached session broker 的 Goal/Agent 绑定语义交叉检查后保持一致。

对主干的风险

这是 docs-only 变更，不改变运行时默认行为。主要风险是规范漂移或把机器强制义务写成模糊 guidance；本次文字使用了明确的 must/fail-closed 约束，并对 exact revision、work-attempt authority、readback、receipt、privacy 和 Goal/Todo ownership 给出可验证边界，未发现冲突。

验证结果：git diff --check 通过；examples/docs-governance-smoke.py 通过；用 Python 3.13 执行分支上的 python3 -m loopx.cli check --scan-path docs/architecture/rfcs/desktop-execution-frontends-v0.md 通过且 errors=0；loopx canary premerge --from-git-diff 10/10 checks 通过、0 failures、0 manual holds；DCO、Dependency Review、SonarCloud 通过。Frontstage Pages 的 build/deploy jobs 在 npm setup 阶段被 GitHub 标记为 cancelled，而不是代码失败；若分支保护要求该检查，合并前应重跑它。

我的整体评价

在该 exact head 上没有发现 blocking finding。这个补充是必要且边界清晰的：它把 Desktop 的工具集来源统一回既有 Goal/capability/extension 合同，同时避免新增第二套 capability-pack 或状态权威。未来向的小型重构检查结论为“不需要”：当前 PR 主动拒绝新增 runtime object，并通过 canonical references 消除了重复权威；更大的 runtime 实现应留给后续实际 call site，而不应塞入本 RFC 补丁。

English verdict: Approval conclusion at exact head 17a2d97198f73e7f12a34222461c7e4c8ea93ac0; no blocking finding. The RFC reuses the existing extension/capability/Goal authority boundaries and makes material-operation settlement explicit without adding speculative runtime structure. Local docs governance, exact contract scan, and premerge validation passed; rerun the cancelled Frontstage Pages job before merge if branch protection requires it.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Exact head reviewed: 17a2d97198f73e7f12a34222461c7e4c8ea93ac0

动机

现有 RFC 已经分别定义了 Desktop 的 attached/managed 执行模式、runtime adapter 与 provider profile，但没有把“Agent 最终能看到哪些外部能力”明确收口到同一个 Goal binding。缺少这段约束时，实现方容易误把 toolkit 仓库、安装动作、prompt skill 或同名 provider 当成授权来源，也容易在 attached 与 managed 两条路径上形成不同的能力和结算语义。

改动思路

本 PR 没有再发明一个 external toolkit 运行时对象，而是复用已有的三层边界：extension 负责安装与生命周期，external capability 负责 caller-outcome/权限/schema/readback/receipt，必要时由 domain capability pack 承担领域策略和投影。两种会话模式都从 Agent 的 Goal binding 投影能力；material operation 还必须绑定当前被授权的 work attempt，并继续经过验证、provider readback 与 settlement。Goal/Todo 状态写入权仍只属于 LoopX control plane。

具体改动

关键内容讲解

• 在 Desktop execution RFC 中新增 “Goal-bound external capabilities in both modes”，明确 attached 与 managed 使用同一 Goal-bound 能力来源和 exact ready provider revision。
• 区分 read-only reuse 与 material operation：前者不创造 work truth，后者必须进入 managed Turn 或 attached host/automation 的等价授权与结算链路。
• 明确 toolkit 仓库只是 source distribution；安装、发现 prompt skill 或观察到同名 provider 都不自动授予执行权限，重复 provider 在未被 Goal binding 精确选择时 fail closed。
• 补齐 owner-local 隐私边界：credentials、provider coordinates、logs/traces/rows/content 不进入 LoopX durable state，只保留 public-safe identity、revision/profile digest、evidence reference 和 admitted receipt。
• 在 shared validation criteria、non-goals 与 references 中同步加入外部能力的可验收约束，避免正文成为孤立说明。

改动仅涉及 1 个 RFC 文件、43 行新增；每一段都服务于同一能力归属与授权边界，没有引入未被调用的代码结构。与 docs/reference/extensions.md、control-plane course 的 extension/Todo/Turn 边界，以及 attached session broker 的 Goal/Agent 绑定语义交叉检查后保持一致。

对主干的风险

这是 docs-only 变更，不改变运行时默认行为。主要风险是规范漂移或把机器强制义务写成模糊 guidance；本次文字使用了明确的 must/fail-closed 约束，并对 exact revision、work-attempt authority、readback、receipt、privacy 和 Goal/Todo ownership 给出可验证边界，未发现冲突。

验证结果：git diff --check 通过；examples/docs-governance-smoke.py 通过；用 Python 3.13 执行分支上的 python3 -m loopx.cli check --scan-path docs/architecture/rfcs/desktop-execution-frontends-v0.md 通过且 errors=0；loopx canary premerge --from-git-diff 10/10 checks 通过、0 failures、0 manual holds；DCO、Dependency Review、SonarCloud 通过。Frontstage Pages 的 build/deploy jobs 在 npm setup 阶段被 GitHub 标记为 cancelled，而不是代码失败；若分支保护要求该检查，合并前应重跑它。

我的整体评价

在该 exact head 上没有发现 blocking finding。这个补充是必要且边界清晰的：它把 Desktop 的工具集来源统一回既有 Goal/capability/extension 合同，同时避免新增第二套 capability-pack 或状态权威。未来向的小型重构检查结论为“不需要”：当前 PR 主动拒绝新增 runtime object，并通过 canonical references 消除了重复权威；更大的 runtime 实现应留给后续实际 call site，而不应塞入本 RFC 补丁。

English verdict: APPROVE at exact head 17a2d97198f73e7f12a34222461c7e4c8ea93ac0; no blocking finding. The RFC reuses the existing extension/capability/Goal authority boundaries and makes material-operation settlement explicit without adding speculative runtime structure. Local docs governance, exact contract scan, and premerge validation passed; rerun the cancelled Frontstage Pages job before merge if branch protection requires it.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[huangruiteng]

Maintainer self-review completed against exact head 078e94f78e902ef94c4d33dda0bfc795151061b4.

Judgment and refinement

The RFC addition matches the shipped authority model in loopx.extensions.capability_admission: a durable Goal binding pins one external capability to an exact doctor-ready provider revision/profile; read-only invocation creates no work truth, while material external writes require selected-Todo/Turn admission, provider readback, durable writeback, and settlement.

I found one documentation-governance gap in the original head: this is an existing bilingual canonical RFC, but only the English file had been updated. The refinement adds the corresponding Chinese section, validation criteria, non-goals, and canonical links. The two languages now describe the same extension/capability/domain-pack ownership and the same attached/managed authority boundary.

No TypeScript companion refactor was added. This PR intentionally defines a frontend/session contract and has no production call site to cut over; adding a TS model here would create speculative structure rather than delete duplicate runtime authority.

Validation

• python3 examples/docs-governance-smoke.py: passed
• LoopX contract scan over both English and Chinese RFCs: errors=0; four unrelated existing runtime-state warnings only
• standard premerge canary: 3 direct + 10 selected checks, 0 failures, 0 warnings, 0 manual holds
• Frontstage Pages build: passed; deploy intentionally skipped for a pull request
• DCO and dependency review: passed
• git diff --check: passed
• public/private boundary scan: clean

The future-facing pass was applied by restoring one bilingual source of truth and rejecting a speculative TS schema. Result: approved for maintainer self-merge.