dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/subsystems/liveshare.md

@@ -0,0 +1,158 @@
+# LiveShare
+
+English | [中文](liveshare.zh.md)
+
+The opt-in LiveShare bundle (`@deepseek-ai/dsh-experimental-liveshare`) lets one owner share a single Session with an external viewer through the separate Liveshare server. A viewer never receives the owner's tools: the owner host reads each viewer request itself, dispatches it as that viewer's own Peer, whose `share-viewer` principal the Gateway decides through the [remote access](../../packages/api/remote-access/README.md) policy this package registers, and constrains everything a shared Session runs on the viewer's behalf to the workspace the share granted. The [package README](../../packages/experimental/liveshare/README.md) owns configuration, the client faces, and the limitations; the [Owner note](../../.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.md) owns the security posture behind them.
+
+Source: [`packages/experimental/liveshare/src/host/fork-enforcement.ts`](../../packages/experimental/liveshare/src/host/fork-enforcement.ts)
+
+<a id="enabling-and-visibility"></a>
+
+## Enabling and visibility
+
+The package ships with dsh but stays out of the plugin manager's lists until a profile enables it. A profile either inserts the two rows the bundle declares into its own `cordis.patch.yml`, which keeps the bundle unselected while its plugins run, or selects the bundle in `dsh.profile.bundles`. The [package README](../../packages/experimental/liveshare/README.md#default-visibility-and-enabling) owns the exact entries and the placeholders a deployment replaces.
+
+The plugin manager lists the card under **Experimental plugins** only while at least one row the bundle declares runs, and removing the rows, disabling them, or deselecting the bundle takes it out of both that list and **More** again. Both routes apply on the profile's next recomposition rather than mid-task: with HMR enabled the profile is re-read, and without it the change waits for the next start.
+
+## Share modes
+
+`ViewerSessionMode` has two tiers, and both name a sandbox: `view` reads the shared Session and drives its loop inside a read-only sandbox in the granted workspace, so its file tools never write; it may use the read and search surface (`read`, `read_image`, `glob`, `grep`, `present`) and the tools with no local file effect (`todo_write`, `skill`, `web_search`, `web_fetch`), with every declared path checked against the grant. Both tiers also admit the PTC transport `run_code`: the program runs under the owner's standing file policy rather than the share tier, so it can read and write outside the grant, while its nested tool calls still pass the same guard and path checks. `write` runs in a bounded writable sandbox that also modifies files inside that workspace by adding bounded `edit` and `write`, under the Host's write ceiling. Forking is not a tier: the share carries its own `allowsFork` switch, independent of the tier. Attachment upload is not a tier either: every Session a share serves the reader accepts files, whatever the tier and the fork switch. The withdrawn `fork-readonly` name is not read back as `view`: a persisted owner record that names it is rejected when the owner state loads. Nothing infers `write`, and a share whose mode the host cannot establish stays readable but is never driven.
+
+## Forks and their ceiling
+
+A fork creates a new Session the viewer owns and leaves the source untouched. Fork authorization checks the share, its fork switch, expiry, viewer admission, source identity, and the requested boundary. `READ_ONLY_FORK_CEILING` permits the view surface — `read`, `read_image`, `glob`, `grep`, `present`, `todo_write`, `skill`, `web_search`, `web_fetch` — admits the PTC transport `run_code`, and `WRITE_FORK_CEILING` adds the Host’s bounded `edit` and `write`. Each path-bearing tool gets a confined replacement that resolves every declared path against the granted root and delegates with its canonical form; `bash`, `pwsh`, `cua`, `plugin_manager`, the `schedule_*` tools, and every other name is refused.
+
+Each child is recorded with the share that authorized it, the trusted viewer the Liveshare server asserted, and the boundary it started from, so a viewer's list shows only its own children and a removed share stops them. A child is driven only after its ceiling is installed on its own scope: `ForkRegistry` refuses every prompt for a child whose guard is not installed (`fork-ceiling-uninstalled`), and installation is verified per child rather than per host. A child whose scope refuses the confined replacement or the limit is refused instead of being published with the deployment's own tools.
+
+Cold source and child activation uses the Host’s ordinary Agent lookup, not a Remote `session/prepare` endpoint. Serial `agent/created` listeners install scoped enforcement before queued work is released; an already live Agent needs its own installation check. `forkLineage` is a LiveShare-owned, per-viewer UI projection, not a Session-summary field, durable log event, or permission grant.
+
+## Retries, recovery, and revocation
+
+One logical fork request may be sent more than once. Its identity binds the trusted viewer, the share, the source, and the caller's operation id; the boundary is compared against that identity rather than folded into it, so a retry repeats the child it already produced, an identity naming another boundary conflicts instead of silently receiving the earlier child, and the reservation is durable before any child exists. The host records the child the owner's fork answer returned, and a retry of a recorded operation replays that answer. The owner's `SessionForkRequest` mints the child id, so a host that dies between creating the child and recording it cannot name that child on retry and creates a second one; closing that window needs a Session Controller request that accepts a caller-supplied child identity.
+
+Child tool guards recheck the share’s current mode, expiry, viewer admission, and revocation record. Viewer withdrawal cancels affected child work and pending calls. A `write` to `view` downgrade denies later writes through the write guard without granting any new tool, and does not promise immediate cancellation of a running turn. Removing a share revokes recorded children and stops the Session's running turn; the source enforcement layer is released once no share over the Session is left, and with Agent disposal. Revoked children retain their logs, and the source’s owner-visible history is never rewritten.
+
+## Constraining a shared Session
+
+Every share lets its viewer drive the *source* Session through the normal prompt path, and any share at either tier installs the bounded sandbox while it is active. `installSourceSessionAccess` registers a confined replacement for every view-surface tool the deployment ships in that Session's own scope, and bounded `edit` and `write` replacements whenever any share over the Session allows writing. The layer is mounted on the Session, but it confines only the turns a share viewer starts: `agent/pre-step` records, in Host memory, whether a turn's admitted input names a share viewer, and the guard and the replacements read that answer for every execution of that turn. A viewer-started turn runs those replacements and nothing else; a turn the owner starts keeps the Session's own tools, including `bash` and its unrestricted filesystem tools. The answer is decided when the turn is admitted and never written to the Session log; a restart recomputes it from the next admitted step. An owner's steering input inside a viewer's turn stays confined with it. Stopping every share over the Session disposes the layer, which restores the Session's own tools; narrowing the last write share to `view` re-installs the read-only layer.
+
+The installation reports whether the source Session is actually confined. A deployment without the `read` tool, or a scope that refuses that replacement's registration, leaves the guard in place and reports the refusal; a tool whose own replacement failed stays refused while the rest of the surface runs, and the reader refuses the prompt with `source-write-unavailable`: no viewer-started turn of a shared Session is driven against the owner's own tools because a limit could not be installed.
+
+Each operation re-reads the Relay grants of the shares that keep the Session drivable, and each reading is synchronous with the tool call it authorizes, so input queued past the grant that admitted it cannot act on that stale admission. The layer is per Session: several shares over one Session share the one installation, and a share that narrows or ends changes what the layer permits — its bounded write is refused once no active share may write, and the layer is released once no share is left. The Host does not attribute a running turn to the viewer that admitted it, so ending one share's grant stops the Session's running turn rather than singling out that viewer's work; the in-memory viewer-start marker only decides which tool surface that turn runs.
+
+Confined file tools resolve every path their own arguments declare, check that the granted root contains each result, and delegate with the target’s canonical path. A pathless `glob` or `grep` searches the Session’s working directory, which the replacement supplies and checks like a named path; a `present` call checks every file it lists; the tools with no local file effect are delegated unchanged. Bounded edits run the same containment check, use `fs/edit-intent`, and publish the version `editText` returns; bounded writes use `fs/write-intent` and publish the version `writeText` returns. After the asynchronous intent wait, the Host resolves the current Session sandbox policy and rechecks share authority. It passes that policy as the fifth `editText` or `writeText` argument, after `signal`, so the sandboxing backend fences the mutation by it. Containment is checked by path, so a directory inside the grant that a local process replaces with a symlink between the check and the open can redirect the operation; anchoring operations to a directory handle is deferred to a separate change.
+
+A viewer's source prompt and source stop both travel the standard Gateway dispatch under the `share-viewer` policy's source-write role: the policy admits them while the share's tier is established and its Session is confined, and the owner's own Session controller then stops whatever turn the Session is running. Cancellation performs no per-viewer comparison, so a reader's stop of the shared Session also ends a turn the owner started. The [Session Controller](../../packages/api/session-controller/README.md) reads `remoteAccess.allows()` again inside `prompt` immediately before delivery and in the same synchronous step as a `cancel`, so a viewer whose access ends after the Gateway admitted its call delivers or cancels nothing. Queued external source input refreshes Liveshare server authority in `agent/pre-step`; missing authority rejects the step before a model request.
+
+<a id="viewer-states"></a>
+
+## Viewer states
+
+A viewer read that ends in a refusal names its own condition rather than one failure for every cause: the Liveshare server answers a missing link, a share the owner stopped, an expired share, an owner whose machine holds no route, an expired sign-in, a reader who has not asked, a request still waiting, a request the owner refused, and a notification the owner never received each with their own status and code, and a page that cannot reach the Liveshare server states that itself. `VIEWER_STATE_ANSWERS` in `@deepseek-ai/dsh-experimental-liveshare-protocol` is the whole vocabulary, and the [shared protocol](../../packages/experimental/liveshare-protocol/README.md) owns the answer each condition carries. No answer widens what a viewer may read: an offline owner, a stopped share, and a refused request all deny.
+
+The workspace feed a viewer's page renders is filtered through the same policy as its session list: a workspace is delivered while it holds the shared Session or a branch that viewer made from it, and its membership and its manual order keep only those. A workspace that loses them leaves the feed when that workspace or the workspace order next changes, and the stream then replaces the reader's baseline; an access change alone sends no frame. A reader therefore sees the owner's workspace names and grouping around the one Session it was granted, never the rest of the owner's workspaces.
+
+Viewer streams bind the opening actor across polling, replacement, and cancellation. Session notifications, control baselines, and workspace membership expose only the source and that actor’s children: the Gateway forwards a reader only the `api-session/*` notifications the policy allows on those Sessions, and the Session and Workspace controllers filter their lists and streams through the same policy; interactive approvals and questions stay on the Host. Refused reads open no upstream subscription. Expiry and revocation cancel affected pending calls and streams; unpolled streams are reclaimed after 120 seconds. Worker IPC responses and cancellations must match the request’s token, share id, Liveshare server id, and original socket or worker generation; late answers cannot settle a replacement request.
+
+The Liveshare server’s optional `share-access-state` capability publishes a complete, versioned authority snapshot on connection and committed mutations, including mutations on another Liveshare server instance. Authenticated `GET /__liveshare/requests` returns the same fields. The Host clears cached authority on connection loss, rejects stale revisions within a generation, and fences asynchronous refreshes against generation changes. Missing complete authority refuses admission; this does not establish immediate distributed stop semantics.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxliveshareshares--liveshareshares"></a>
+
+### `ctx.liveshareShares` — `LiveshareShares`
+
+Owner-only Remote surface over the share-management operations.
+
+The Gateway decides each call through remote access, so a `share-viewer` Peer is refused before a method runs; the owner Peer reaches the one implementation that owns each share-management side effect. `create` takes its Session as the `sessionId` of its single request object, so the Session resource kind's default resolver names that Session for the call without a reader declared here.
+
+```ts cordis-catalog
+/**
+ * Publish one Session and store the share.
+ * @param request - Session, title, access, lifetime, and both switches the owner chose.
+ * @returns The created share's link and stored values.
+ */
+@Remote('create') create(request: CreateShareRequest): Promise<CreatedShare>
+
+/**
+ * Refresh titles and Liveshare server authority, then list this host's shares.
+ * @returns Every share this host publishes.
+ */
+@Remote('list') list(): Promise<OwnerShareList>
+
+/**
+ * Stop one share locally, revoke its forks, and delete its row on the Liveshare server when reachable.
+ * @param request - Share to stop.
+ * @returns Whether the row on the Liveshare server still needs a retry.
+ */
+@Remote('stop') stop(request: StopShareRequest): Promise<StopShareResult>
+
+/**
+ * Change one share's tier, fork switch, or both.
+ * @param request - Share and the switches to change.
+ * @returns The permissions the share now carries.
+ */
+@Remote('updatePermissions') updatePermissions(request: UpdateSharePermissionsRequest): Promise<SharePermissions>
+
+/**
+ * Replace one share's exposed plugin endpoints.
+ * @param request - Share and the selection to store.
+ * @returns The capability selection the share now carries.
+ */
+@Remote('setCapabilities') setCapabilities(request: SetShareCapabilitiesRequest): Promise<ShareCapabilities>
+
+/**
+ * Read the endpoints plugins currently offer.
+ * @returns The live offer list.
+ */
+@Remote('capabilities') capabilities(): ShareCapabilityOffers
+
+/**
+ * Read the Liveshare server address the owner saved.
+ * @returns The current Liveshare server state, with both address fields absent while none is saved.
+ */
+@Remote('relay') relay(): OwnerRelayState
+
+/**
+ * Choose the Liveshare server address later shares publish to.
+ * @param request - Normalized address or null to clear the saved one.
+ * @returns The Liveshare server state after the change.
+ */
+@Remote('setRelay') setRelay(request: SetRelayRequest): Promise<OwnerRelayState>
+
+/**
+ * Report this host's owner identity for one Liveshare server address.
+ * @param request - Address to report, or the effective one when absent.
+ * @returns The owner identity status, without the credential.
+ */
+@Remote('identity') identity(request: OwnerIdentityRequest): Promise<OwnerIdentityStatus>
+
+/**
+ * Read the Liveshare server's durable audit trail for one share.
+ * @param request - Share whose audit is read.
+ * @returns The audit events, or a structured failure when the Liveshare server cannot answer.
+ */
+@Remote('audit') audit(request: ShareAuditRequest): Promise<ShareAudit>
+
+/**
+ * Check that the effective Liveshare server answers at all.
+ * @returns The anonymous connectivity result.
+ */
+@Remote('testRelay') testRelay(): Promise<RelayConnectivityView>
+
+/**
+ * Register one throwaway share to check whether this host may publish.
+ * @param request - Session the throwaway registration names.
+ * @returns The Liveshare server's decision about this host's credential.
+ */
+@Remote('testPublish') testPublish(request: TestPublishRequest): Promise<RelayPublishView>
+```
+
+Source: [`packages/experimental/liveshare/src/host/share-remote.ts`](../../packages/experimental/liveshare/src/host/share-remote.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/liveshare.zh.md

@@ -0,0 +1,158 @@
+# LiveShare
+
+[English](liveshare.md) | 中文
+
+可选的 LiveShare bundle（`@deepseek-ai/dsh-experimental-liveshare`）让一位所有者通过独立的 Liveshare 服务端 把一个会话分享给外部 viewer。viewer 永远拿不到所有者的工具：所有者宿主机自己读取 viewer 的每个请求，以该 viewer 自己的 Peer 分派它，Gateway 依据本包注册的 [remote access](../../packages/api/remote-access/README.zh.md) 策略判定该 Peer 的 `share-viewer` principal，并把共享会话代表 viewer 运行的一切限制在分享所授予的工作区内。[包 README](../../packages/experimental/liveshare/README.zh.md)负责配置、客户端界面与限制；[Owner 说明](../../.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.zh.md)负责其背后的安全姿态。
+
+源码：[`packages/experimental/liveshare/src/host/fork-enforcement.ts`](../../packages/experimental/liveshare/src/host/fork-enforcement.ts)
+
+<a id="enabling-and-visibility"></a>
+
+## 启用与可见性
+
+本包随 dsh 一同交付，但在 profile 启用它之前不会出现在插件管理器的任何列表中。profile 可以把自己的 `cordis.patch.yml` 插入组合包声明的两条行，这样组合包本身保持未选中而插件照常运行；也可以改在 `dsh.profile.bundles` 中选中该组合包。[包 README](../../packages/experimental/liveshare/README.zh.md#default-visibility-and-enabling)负责具体条目和部署需要替换的占位符。
+
+插件管理器只有在组合包声明的行至少有一条在运行时才把卡片列在**实验性插件**下；删除这些行、把它们置为 disabled，或取消选中组合包，卡片会再次从该列表和**更多**页消失。两条路线都在 profile 下一次重新组合时生效，而不是在当前任务中途：启用 HMR 时会重新读取 profile，未启用时则等下一次启动。
+
+## 分享模式
+
+`ViewerSessionMode` 只有两档，两档都对应一个沙箱：`view` 读取共享会话，并在授予工作区的只读沙箱里驱动它的 loop，其文件工具绝不写入；它可以使用读取与检索面（`read`、`read_image`、`glob`、`grep`、`present`）和无本地文件副作用的工具（`todo_write`、`skill`、`web_search`、`web_fetch`），每个声明路径都按授予范围检查。`write` 在受宿主写入上限约束的可写沙箱里运行，通过有界 `edit` 与 `write` 修改该工作区内的文件。fork 不是一档：分享自带独立的 `allowsFork` 开关，与档位无关。附件上传也不是一档：分享向读者提供的每条会话都接受文件，与档位和分叉开关无关。已退场的 `fork-readonly` 名称不会读回为 `view`：持久化的 owner 记录若写有该值，owner 状态加载时会直接拒绝。任何环节都不会推断出 `write`，而宿主机无法确定模式的分享仍可读取，但绝不会被驱动。两档也都准入 PTC 传输工具 `run_code`：程序运行在所有者自己的常驻文件策略下而不是分享档位下，因此可以读写授权范围之外的文件；它发起的嵌套工具调用仍走同样的守卫与路径检查。
+
+## fork 与其上限
+
+fork 创建查看者拥有的新会话，源会话保持不变。Fork 授权检查分享、其 fork 开关、有效期、查看者准入、源身份与请求的边界。`READ_ONLY_FORK_CEILING` 允许读取与检索面——`read`、`read_image`、`glob`、`grep`、`present`、`todo_write`、`skill`、`web_search`、`web_fetch`——并放行 PTC 传输工具 `run_code`，`WRITE_FORK_CEILING` 增加 Host 的有界 `edit` 与 `write`。每个带路径的工具都有受限替代定义：解析它声明的所有路径并按授予根目录检查，再以规范路径委托；`bash`、`pwsh`、`cua`、`plugin_manager`、`schedule_*` 及其他任何未列出的名字一律拒绝。
+
+每个分叉会话都会记录授权它的分享、Liveshare 服务端断言的可信 viewer，以及它起始的边界，因此 viewer 的列表只显示它自己的分叉会话，被移除的分享会终止它们。只有在分叉会话自身作用域上安装好上限之后它才会被驱动：`ForkRegistry` 会拒绝每个上限未安装的分叉会话的 prompt（`fork-ceiling-uninstalled`），且安装是按分叉会话逐个验证，而非按宿主机验证。若分叉会话作用域拒绝注册受限替换或上限，就拒绝该分叉会话，而不是让它带着部署自身的工具发布。
+
+冷态源会话与分叉会话通过 Host 常规 Agent lookup 激活，而非 Remote `session/prepare` 端点。串行 `agent/created` 监听器在排队工作放行前安装作用域执行限制；已经在线的 Agent 仍需检查自身安装。`forkLineage` 是 LiveShare 自有的按查看者 UI 投影，不是会话摘要字段、持久日志事件或权限授予。
+
+## 重试、恢复与撤销
+
+同一个逻辑 fork 请求可能被发送多次。其身份绑定可信 viewer、分享、源会话与调用方的操作 id；边界是与该身份比较而非折入其中，因此重试会重复它已经产生的分叉会话，同一身份指向另一个边界会冲突而不是悄悄拿到更早的分叉会话，且预留在任何分叉会话存在之前就已持久化。宿主机记录 owner 的 fork 应答返回的分叉会话，重试已记录的操作会重放该应答。owner 的 `SessionForkRequest` 自己生成分叉会话 id，因此在创建分叉会话与记录它之间崩溃的宿主机重试时无法指名该分叉会话，会再创建一个；要关闭这一窗口，需要 Session Controller 的请求接受调用方提供的分叉会话身份。
+
+分叉会话工具守卫重新检查分享当前模式、有效期、查看者准入与撤销记录。撤回查看者会取消受影响的分叉会话工作与未决调用。`write` 降级为 `view` 后，写入守卫拒绝后续写入，不授予任何新工具，也不承诺立即取消正在运行的轮次。移除分享撤销已记录分叉会话并停止该会话正在运行的轮次；源执行层在该会话不再有任何分享时释放，并随 Agent 释放。已撤销分叉会话保留日志，源会话所有者可见历史绝不改写。
+
+## 约束共享会话
+
+每个分享都让它的 viewer 通过正常 prompt 路径驱动*源*会话，任一档位的分享在活跃期间都会安装有界沙箱。`installSourceSessionAccess` 在该会话自身作用域中为部署提供的每个读取与检索面工具注册受限替代，并在任一同会话分享允许写入时再注册有界 `edit` 与 `write` 替代。执行层挂在会话上，但只约束分享查看者发起的轮次：`agent/pre-step` 在 Host 内存中记录一个轮次的已准入输入是否带有 share-viewer principal，守卫与替代定义对该轮次的每次执行读取这一结论。查看者发起的轮次只能运行这些替代定义；所有者自己发起的轮次保留会话原生工具，包括 `bash` 与不受限的文件工具。该结论在轮次准入时确定，不写入会话日志；重启后从下一个准入步骤重新计算。所有者在查看者轮次中追加的输入仍留在该受限轮次内。该会话的所有分享停止后执行层被释放，会话恢复自己的工具；最后一个可写分享降为 `view` 时重装只读层。
+
+安装结果报告源会话是否真正受到限制。没有 `read` 工具的部署或拒绝该替代注册的作用域会保留守卫并报告失败；某个工具自己的替代注册失败时，该工具保持拒绝，其余工具面照常运行。读取处理器以 `source-write-unavailable` 拒绝消息：限制未安装时，共享会话中查看者发起的轮次不会用所有者工具驱动。
+
+每次操作都会重新读取维持该会话可驱动的分享的 Relay 授权，且读取与其授权的工具调用在同一同步步骤内完成，因此排队超过其准入授权的输入无法凭过期准入行动。执行层按会话安装：同一会话的多个分享共用一个安装；分享收窄或结束时改变该层允许的操作——没有任何活跃分享可写时拒绝有界写入，会话不再有分享时释放执行层。Host 不把正在运行的轮次归属给准入它的查看者，因此结束某个分享的授权会停止该会话正在运行的轮次，而不是只挑出该查看者的工作；内存中的查看者轮次标记只决定该轮次运行哪套工具面。
+
+受限文件工具解析其自身参数声明的每个路径，检查获授根目录包含每个目标，再以目标的规范路径委托。无路径的 `glob` 或 `grep` 搜索会话的工作目录，由替代定义补齐并按命名路径一样检查；`present` 调用检查它列出的每个文件；无本地文件副作用的工具原样委托。有界编辑执行同样的包含检查，使用 `fs/edit-intent`，并发布 `editText` 返回的版本；有界写入使用 `fs/write-intent`，并发布 `writeText` 返回的版本。异步意图等待后，Host 解析当前会话沙箱策略并重新检查分享授权。该策略作为 `editText` 或 `writeText` 的第五个参数，位于 `signal` 之后，由沙箱后端据此限制变更。包含关系按路径检查，若本地进程在检查与打开之间把获授范围内的目录换成符号链接，操作可能被改指别处；基于目录句柄锚定操作留待单独变更引入。
+
+查看者对源会话的提示词与停止都按标准 Gateway 分派走 `share-viewer` 策略的源会话写入角色：分享档位已确立且其会话受沙箱限制时策略放行，随后由所有者自己的会话控制器停止该会话当前运行的轮次。取消不按查看者比对，因此读者对共享会话的停止也会结束所有者发起的轮次。[Session Controller](../../packages/api/session-controller/README.zh.md) 在 `prompt` 投递前、以及与 `cancel` 同一同步步骤内再次读取 `remoteAccess.allows()`，因此 Gateway 放行调用之后访问权才结束的查看者不会投递或取消任何内容。排队的外部源输入在 `agent/pre-step` 刷新 Liveshare 服务端授权；缺少授权时在模型请求之前拒绝步骤。
+
+<a id="viewer-states"></a>
+
+## viewer 状态
+
+一次以拒绝结束的 viewer 读取会指明它自己的状态，而不是让所有原因共用一种失败：链接不存在、owner 已停止分享、分享已过期、owner 的机器没有路由、登录已过期、读者尚未申请、申请仍在等待、申请被 owner 拒绝、owner 从未收到通知，每种都有各自的 HTTP 状态与错误码；页面联系不上 Liveshare 服务端时由页面自己陈述。`@deepseek-ai/dsh-experimental-liveshare-protocol` 中的 `VIEWER_STATE_ANSWERS` 就是这份词汇表，每种状态对应的答案由 [共享协议](../../packages/experimental/liveshare-protocol/README.zh.md) 维护。没有任何一种答案会扩大 viewer 能读到的内容：owner 离线、分享已停止、申请被拒，三者都是拒绝。
+
+viewer 页面渲染所用的工作区流与会话列表经同一策略过滤：只要工作区还持有共享会话或该 viewer 自己创建的分支就会下发，其成员与手工顺序只保留这些。失去它们的工作区要到该工作区或工作区顺序下次变化时才离开工作区流，届时流替换读者的基线；仅访问变化不会发送帧。因此读者看到的是围绕它被授予的那一个会话的 owner 工作区名称与分组，而不是 owner 其余的工作区。
+
+查看流在轮询、替换与取消时均绑定打开它的主体。会话通知、控制基线与工作区成员只暴露源会话及该主体的分叉会话：Gateway 只向读者转发策略在这些会话上允许的 `api-session/*` 通知，Session 与 Workspace 控制器也经同一策略过滤其列表和流；交互审批与提问保留在 Host。被拒绝的读取不创建上游订阅。过期与撤权取消受影响的未决调用和流；120 秒未轮询的流被回收。Worker IPC 响应与取消必须匹配请求 token、分享 ID、Liveshare 服务端 ID 及原始 socket 或 worker generation；迟到响应不能结算替换请求。
+
+Liveshare 服务端可选的 `share-access-state` 能力在连接和已提交变更时发布完整、带版本的授权快照，包括其他 Liveshare 服务端实例提交的变更。鉴权 `GET /__liveshare/requests` 返回同一组字段。Host 在连接丢失时清空缓存授权，在同一 generation 内拒绝过期修订，并对异步刷新检查 generation。缺少完整授权时拒绝准入；这不构成立即的分布式停止语义保证。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxliveshareshares--liveshareshares"></a>
+
+### `ctx.liveshareShares` — `LiveshareShares`
+
+Owner-only Remote surface over the share-management operations.
+
+The Gateway decides each call through remote access, so a `share-viewer` Peer is refused before a method runs; the owner Peer reaches the one implementation that owns each share-management side effect. `create` takes its Session as the `sessionId` of its single request object, so the Session resource kind's default resolver names that Session for the call without a reader declared here.
+
+```ts cordis-catalog
+/**
+ * Publish one Session and store the share.
+ * @param request - Session, title, access, lifetime, and both switches the owner chose.
+ * @returns The created share's link and stored values.
+ */
+@Remote('create') create(request: CreateShareRequest): Promise<CreatedShare>
+
+/**
+ * Refresh titles and Liveshare server authority, then list this host's shares.
+ * @returns Every share this host publishes.
+ */
+@Remote('list') list(): Promise<OwnerShareList>
+
+/**
+ * Stop one share locally, revoke its forks, and delete its row on the Liveshare server when reachable.
+ * @param request - Share to stop.
+ * @returns Whether the row on the Liveshare server still needs a retry.
+ */
+@Remote('stop') stop(request: StopShareRequest): Promise<StopShareResult>
+
+/**
+ * Change one share's tier, fork switch, or both.
+ * @param request - Share and the switches to change.
+ * @returns The permissions the share now carries.
+ */
+@Remote('updatePermissions') updatePermissions(request: UpdateSharePermissionsRequest): Promise<SharePermissions>
+
+/**
+ * Replace one share's exposed plugin endpoints.
+ * @param request - Share and the selection to store.
+ * @returns The capability selection the share now carries.
+ */
+@Remote('setCapabilities') setCapabilities(request: SetShareCapabilitiesRequest): Promise<ShareCapabilities>
+
+/**
+ * Read the endpoints plugins currently offer.
+ * @returns The live offer list.
+ */
+@Remote('capabilities') capabilities(): ShareCapabilityOffers
+
+/**
+ * Read the Liveshare server address the owner saved.
+ * @returns The current Liveshare server state, with both address fields absent while none is saved.
+ */
+@Remote('relay') relay(): OwnerRelayState
+
+/**
+ * Choose the Liveshare server address later shares publish to.
+ * @param request - Normalized address or null to clear the saved one.
+ * @returns The Liveshare server state after the change.
+ */
+@Remote('setRelay') setRelay(request: SetRelayRequest): Promise<OwnerRelayState>
+
+/**
+ * Report this host's owner identity for one Liveshare server address.
+ * @param request - Address to report, or the effective one when absent.
+ * @returns The owner identity status, without the credential.
+ */
+@Remote('identity') identity(request: OwnerIdentityRequest): Promise<OwnerIdentityStatus>
+
+/**
+ * Read the Liveshare server's durable audit trail for one share.
+ * @param request - Share whose audit is read.
+ * @returns The audit events, or a structured failure when the Liveshare server cannot answer.
+ */
+@Remote('audit') audit(request: ShareAuditRequest): Promise<ShareAudit>
+
+/**
+ * Check that the effective Liveshare server answers at all.
+ * @returns The anonymous connectivity result.
+ */
+@Remote('testRelay') testRelay(): Promise<RelayConnectivityView>
+
+/**
+ * Register one throwaway share to check whether this host may publish.
+ * @param request - Session the throwaway registration names.
+ * @returns The Liveshare server's decision about this host's credential.
+ */
+@Remote('testPublish') testPublish(request: TestPublishRequest): Promise<RelayPublishView>
+```
+
+Source: [`packages/experimental/liveshare/src/host/share-remote.ts`](../../packages/experimental/liveshare/src/host/share-remote.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/mcp.md

@@ -23,6 +23,8 @@ Model Context Protocol (MCP) connects the model to tools supplied by external se
 
 MCP servers are opt-in. Configure one `@deepseek-ai/dsh-mcp-client` entry per server in the intended Cordis scope. Every shipped profile supplies the [tool registry](tools.md) and mounts the shared resource service once; users configure only client entries. Callers with no visible configured server receive no MCP prompt text or tools in native or PTC mode.
 
+The Web and Desktop profiles also mount the [MCP server manager](../../packages/mcp/mcp-manager/README.md) once. It runs servers configured through Settings and servers that installed plugins register for their own lifetime, and serves their status, restart, and probe operations to Remote clients.
+
 | Choice | Configuration owner |
 |---|---|
 | Server identity, local process or HTTP endpoint, credentials, and process environment | [Client configuration](../../packages/mcp/mcp-client/README.md#use-this-package) |
@@ -38,7 +40,7 @@ Protocol negotiation follows the SDK's supported revisions; there is no product
 <a id="responsibilities-and-scope"></a>
 ## Responsibilities and scope
 
-The client is a per-server connection plugin and a consumer of the harness tool registry. It does not publish a shared `ctx.mcp` service. The external server implements MCP operations; the SDK owns protocol exchange; the client adapts discovered tools to harness execution.
+The client is a per-server connection plugin and a consumer of the harness tool registry. It does not publish a shared `ctx.mcp` service; the manager publishes `ctx.mcpManager` for the Host-global servers it mounts. The external server implements MCP operations; the SDK owns protocol exchange; the client adapts discovered tools to harness execution.
 
 `mcp-resources` owns the shared resource tools and selects providers in the caller's scope. Each MCP client supplies resource operations through its own connection. The first provider in a scope enables the local shared tools, and removing the last removes them; inherited providers remain visible. The service owns these tool registrations independently of any one client. Connection failures do not remove shared resource tools while a visible client entry remains active.
 
@@ -107,6 +109,7 @@ MCP prompt templates, human-input elicitation, task-based execution, and resourc
 
 - [MCP package group](../../packages/mcp/README.md) — package entry points.
 - [MCP resources](../../packages/mcp/mcp-resources/README.md) — shared tools and resource-provider semantics.
+- [MCP manager](../../packages/mcp/mcp-manager/README.md) — Settings-configured and plugin-registered servers, status, and Remote operations.
 - [Resource visibility reference](../../packages/mcp/mcp-resources/README.md) — shared profile mounting and visibility from configured servers.
 - [Third-party memory servers](../user/guide/mcp-memory.md) — product configuration guide.
 - [Protocol negotiation reference](../../packages/mcp/mcp-client/README.md) — SDK ownership and compatibility decisions.
@@ -119,6 +122,71 @@ MCP prompt templates, human-input elicitation, task-based execution, and resourc
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxmcpmanager--mcpservermanager"></a>
+
+### `ctx.mcpManager` — `McpServerManager`
+
+The manager service. Reconciliation and `restart` serialize instance replacement. Probes run independently and are cancelled before replacement or disposal waits for their cleanup.
+
+```ts cordis-catalog
+/**
+ * Read configured and registered servers and retained runtime records without mounting or probing.
+ * @returns configured entries in document order, then registered entries, then retained records for removed entries.
+ */
+list(): McpManagedServerView[]
+
+/**
+ * Contribute one server for the calling plugin's lifetime. A registered
+ * entry is enabled while registered; its removal awaits the instance's
+ * unmount, so plugin disposal withdraws the server's tools before settling.
+ * @param name - server key and tool namespace, unique across configured and registered servers.
+ * @param entry - transport, endpoint, and budgets, validated like a configured entry.
+ * @returns an idempotent disposer that removes the registration.
+ * @throws when the name is taken, the entry is invalid, or the manager is disposed.
+ */
+register(name: string, entry: McpServerRegistration): () => void
+
+/**
+ * Stream server views for a management surface: the current list on
+ * subscription, then the complete list again after each status or entry change.
+ * @param signal - subscription lifetime; aborting ends only this stream.
+ * @returns coalesced server lists until the subscriber or the manager stops.
+ */
+@Remote({ mode: 'stream' }) async* watch(signal: AbortSignal): AsyncIterable<McpManagedServerView[]>
+
+/**
+ * Rebuild one server from its current entry: dispose the live instance (if
+ * any) and mount a fresh one with a fresh reconnect budget. Incomplete
+ * cleanup blocks replacement until the Host restarts.
+ * @param name - the configured or registered server key.
+ * @throws when the manager is disposed, no such entry exists, or cleanup is incomplete.
+ */
+@Remote async restart(name: string): Promise<void>
+
+/**
+ * Probe one server for a management surface; see {@link McpServerManager.probe}.
+ * @param name - the configured or registered server key.
+ * @param signal - caller cancellation.
+ * @returns the stage-classified probe outcome and independent cleanup result.
+ */
+@Remote('probe') probeFromClient(name: string, signal: AbortSignal): Promise<McpProbeResult>
+
+/**
+ * Probe one configured server without touching its live instance: resolve
+ * the entry's templates, connect, list tools, close. A disabled entry can be
+ * probed — that is how a management surface tests it before enabling.
+ * Configuration changes and manager disposal cancel the probe.
+ * @param name - the configured or registered server key.
+ * @param options - probe budget, listing caps, and abort signal.
+ * @returns the stage-classified probe outcome and independent cleanup result.
+ * @throws when the manager is disposed, the entry is absent or changing, cleanup is
+ * incomplete, options are invalid, or a required credentials provider is missing.
+ */
+async probe(name: string, options?: McpProbeOptions): Promise<McpProbeResult>
+```
+
+Source: [`packages/mcp/mcp-manager/src/index.ts`](../../packages/mcp/mcp-manager/src/index.ts)
+
 <a id="ctxmcpresources--mcpresourceruntime"></a>
 
 ### `ctx.mcpResources` — `McpResourceRuntime`
@@ -136,4 +204,31 @@ register(server: string, provider: McpResourceProvider): () => void
 ```
 
 Source: [`packages/mcp/mcp-resources/src/index.ts`](../../packages/mcp/mcp-resources/src/index.ts)
+
+<a id="mcp-manager-events"></a>
+
+### `mcp-manager/*` events
+
+<a id="mcp-managerstatus--parallel"></a>
+
+#### `mcp-manager/status` — parallel
+
+One managed server's status transitioned. Emitted for every published change while the manager is live and either the entry is configured or registered, or a runtime record remains. Removed entries may emit cleanup failures; `watch` and `list()` report removals. Lifecycle operations do not wait for listeners. Synchronous throws and returned promise rejections are logged without skipping other listeners.
+
+```ts cordis-catalog
+/**
+ * One managed server's status transitioned. Emitted for every published
+ * change while the manager is live and either the entry is configured or
+ * registered, or a runtime record remains. Removed entries may emit cleanup
+ * failures; `watch` and `list()` report removals.
+ * Lifecycle operations do not wait for listeners. Synchronous throws and
+ * returned promise rejections are logged without skipping other listeners.
+ * @param name - the configured `servers` key or registered name.
+ * @param status - the status now current for that server.
+ * @mode parallel
+ */
+'mcp-manager/status'(name: string, status: McpManagedServerStatus): void | Promise<void>
+```
+
+Source: [`packages/mcp/mcp-manager/src/types.ts`](../../packages/mcp/mcp-manager/src/types.ts)
 <!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/mcp.zh.md

@@ -23,6 +23,8 @@
 
 MCP 服务器需要主动配置。在目标 Cordis 作用域中，为每台服务器配置一个 `@deepseek-ai/dsh-mcp-client` 条目。每个随附 profile 都提供[工具注册表](tools.zh.md)，并统一挂载共享资源服务一次；用户只需配置客户端条目。调用方没有可见的已配置服务器时，在 native 或 PTC 模式下都不会获得 MCP 提示词文本或工具。
 
+Web 与 Desktop profile 还统一挂载一次 [MCP 服务器管理器](../../packages/mcp/mcp-manager/README.zh.md)。它运行通过 Settings 配置的服务器，以及已安装插件在自身生命周期内注册的服务器，并向 Remote 客户端提供它们的状态、重启与探测操作。
+
 | 选择 | 配置维护位置 |
 |---|---|
 | 服务器身份、本地进程或 HTTP 端点、凭据和进程环境 | [客户端配置](../../packages/mcp/mcp-client/README.zh.md#use-this-package) |
@@ -38,7 +40,7 @@ MCP 服务器需要主动配置。在目标 Cordis 作用域中，为每台服
 <a id="responsibilities-and-scope"></a>
 ## 职责与作用域
 
-客户端是每服务器一个的连接插件，也是 Harness 工具注册表的消费者。它不发布共享的 `ctx.mcp` 服务。外部服务器实现 MCP 操作；SDK 拥有协议交换；客户端将发现的工具适配到 Harness 执行过程。
+客户端是每服务器一个的连接插件，也是 Harness 工具注册表的消费者。它不发布共享的 `ctx.mcp` 服务；管理器为其挂载的宿主全局服务器发布 `ctx.mcpManager`。外部服务器实现 MCP 操作；SDK 拥有协议交换；客户端将发现的工具适配到 Harness 执行过程。
 
 `mcp-resources` 拥有共享资源工具，并在调用方作用域中选择提供方。每个 MCP 客户端通过自己的连接提供资源操作。作用域中的首个提供方启用本地共享工具，移除最后一个提供方时移除这些工具；继承的提供方仍然可见。服务独立于任何单一客户端拥有这些工具注册。只要可见的客户端条目保持激活，连接失败就不会移除共享资源工具。
 
@@ -107,6 +109,7 @@ interface McpResourceProvider {
 
 - [MCP 包组](../../packages/mcp/README.zh.md) — 包入口。
 - [MCP 资源](../../packages/mcp/mcp-resources/README.zh.md) — 共享工具与资源提供方语义。
+- [MCP 管理器](../../packages/mcp/mcp-manager/README.zh.md) — 通过 Settings 配置与插件注册的服务器、状态及 Remote 操作。
 - [资源可见性参考](../../packages/mcp/mcp-resources/README.zh.md) — profile 统一挂载及由已配置服务器决定的可见性。
 - [第三方记忆服务器](../user/guide/mcp-memory.zh.md) — 产品配置指南。
 - [协议协商参考](../../packages/mcp/mcp-client/README.zh.md) — SDK 职责与兼容性决策。
@@ -119,6 +122,71 @@ interface McpResourceProvider {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxmcpmanager--mcpservermanager"></a>
+
+### `ctx.mcpManager` — `McpServerManager`
+
+The manager service. Reconciliation and `restart` serialize instance replacement. Probes run independently and are cancelled before replacement or disposal waits for their cleanup.
+
+```ts cordis-catalog
+/**
+ * Read configured and registered servers and retained runtime records without mounting or probing.
+ * @returns configured entries in document order, then registered entries, then retained records for removed entries.
+ */
+list(): McpManagedServerView[]
+
+/**
+ * Contribute one server for the calling plugin's lifetime. A registered
+ * entry is enabled while registered; its removal awaits the instance's
+ * unmount, so plugin disposal withdraws the server's tools before settling.
+ * @param name - server key and tool namespace, unique across configured and registered servers.
+ * @param entry - transport, endpoint, and budgets, validated like a configured entry.
+ * @returns an idempotent disposer that removes the registration.
+ * @throws when the name is taken, the entry is invalid, or the manager is disposed.
+ */
+register(name: string, entry: McpServerRegistration): () => void
+
+/**
+ * Stream server views for a management surface: the current list on
+ * subscription, then the complete list again after each status or entry change.
+ * @param signal - subscription lifetime; aborting ends only this stream.
+ * @returns coalesced server lists until the subscriber or the manager stops.
+ */
+@Remote({ mode: 'stream' }) async* watch(signal: AbortSignal): AsyncIterable<McpManagedServerView[]>
+
+/**
+ * Rebuild one server from its current entry: dispose the live instance (if
+ * any) and mount a fresh one with a fresh reconnect budget. Incomplete
+ * cleanup blocks replacement until the Host restarts.
+ * @param name - the configured or registered server key.
+ * @throws when the manager is disposed, no such entry exists, or cleanup is incomplete.
+ */
+@Remote async restart(name: string): Promise<void>
+
+/**
+ * Probe one server for a management surface; see {@link McpServerManager.probe}.
+ * @param name - the configured or registered server key.
+ * @param signal - caller cancellation.
+ * @returns the stage-classified probe outcome and independent cleanup result.
+ */
+@Remote('probe') probeFromClient(name: string, signal: AbortSignal): Promise<McpProbeResult>
+
+/**
+ * Probe one configured server without touching its live instance: resolve
+ * the entry's templates, connect, list tools, close. A disabled entry can be
+ * probed — that is how a management surface tests it before enabling.
+ * Configuration changes and manager disposal cancel the probe.
+ * @param name - the configured or registered server key.
+ * @param options - probe budget, listing caps, and abort signal.
+ * @returns the stage-classified probe outcome and independent cleanup result.
+ * @throws when the manager is disposed, the entry is absent or changing, cleanup is
+ * incomplete, options are invalid, or a required credentials provider is missing.
+ */
+async probe(name: string, options?: McpProbeOptions): Promise<McpProbeResult>
+```
+
+Source: [`packages/mcp/mcp-manager/src/index.ts`](../../packages/mcp/mcp-manager/src/index.ts)
+
 <a id="ctxmcpresources--mcpresourceruntime"></a>
 
 ### `ctx.mcpResources` — `McpResourceRuntime`
@@ -136,4 +204,31 @@ register(server: string, provider: McpResourceProvider): () => void
 ```
 
 Source: [`packages/mcp/mcp-resources/src/index.ts`](../../packages/mcp/mcp-resources/src/index.ts)
+
+<a id="mcp-manager-events"></a>
+
+### `mcp-manager/*` events
+
+<a id="mcp-managerstatus--parallel"></a>
+
+#### `mcp-manager/status` — parallel
+
+One managed server's status transitioned. Emitted for every published change while the manager is live and either the entry is configured or registered, or a runtime record remains. Removed entries may emit cleanup failures; `watch` and `list()` report removals. Lifecycle operations do not wait for listeners. Synchronous throws and returned promise rejections are logged without skipping other listeners.
+
+```ts cordis-catalog
+/**
+ * One managed server's status transitioned. Emitted for every published
+ * change while the manager is live and either the entry is configured or
+ * registered, or a runtime record remains. Removed entries may emit cleanup
+ * failures; `watch` and `list()` report removals.
+ * Lifecycle operations do not wait for listeners. Synchronous throws and
+ * returned promise rejections are logged without skipping other listeners.
+ * @param name - the configured `servers` key or registered name.
+ * @param status - the status now current for that server.
+ * @mode parallel
+ */
+'mcp-manager/status'(name: string, status: McpManagedServerStatus): void | Promise<void>
+```
+
+Source: [`packages/mcp/mcp-manager/src/types.ts`](../../packages/mcp/mcp-manager/src/types.ts)
 <!-- END GENERATED cordis-surface -->