dsh-primer 0.4.3 → 0.4.5

package/references/official-docs/docs/subsystems/liveshare.i18n.yaml

@@ -0,0 +1,25 @@
+# Bilingual-pair consistency record for liveshare.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/liveshare.md
+/liveshare:
+  en: bcec4b0a3d28942b
+  zh: 2d3271b6abe51c75
+/liveshare/enabling-and-visibility:
+  en: f6144f8e81359a9c
+  zh: 1924869ac7475b59
+/liveshare/share-modes:
+  en: 17b6227cb7294e69
+  zh: cea4a9064b3d5655
+/liveshare/forks-and-their-ceiling:
+  en: 7174fa32aa611279
+  zh: e85e8142a0e9e650
+/liveshare/retries-recovery-and-revocation:
+  en: 6b1346e73ab6eab9
+  zh: 888cfc08c6bc8522
+/liveshare/constraining-a-shared-session:
+  en: 7607ed3f99df06cc
+  zh: 290c9b8ed064da00
+/liveshare/viewer-states:
+  en: b8bcb009e419fa25
+  zh: 31c4662b52e99ea7

package/references/official-docs/docs/subsystems/liveshare.md

@@ -0,0 +1,167 @@
+# LiveShare
+
+English | [中文](liveshare.zh.md)
+
+The opt-in LiveShare bundle (`@deepseek-ai/dsh-experimental-liveshare`) lets one owner share one or more Sessions 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.
+
+A share starts with the Session it was created for, and `liveshareShares.addSessions` adds more source Sessions to it. Every source is served under the share's ACL, tier, lifetime, fork switch, and exposed endpoints; the Relay registration and the viewer page keep the first source, and a reader reaches the others through the Session list the policy now binds. Every source must belong to the share's one Workspace: the Host refuses an addition it cannot place there, so all readers stay inside one workspace root. Stopping the share ends all of its sources.
+
+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, a share that carries several source Sessions installs one layer per source, 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 Sessions 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>
+
+/**
+ * Add source Sessions to one share this host already publishes.
+ * @param request - Share and the Sessions to add.
+ * @returns The source Sessions the share now serves.
+ */
+@Remote('addSessions') addSessions(request: AddShareSessionsRequest): Promise<ShareSessions>
+
+/**
+ * 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/references/official-docs/docs/subsystems/liveshare.zh.md

@@ -0,0 +1,167 @@
+# 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)负责其背后的安全姿态。
+
+分享以创建它时的会话来开始，`liveshareShares.addSessions` 可以为它增加更多源会话。每个源会话都按该分享的 ACL、档位、有效期、fork 开关与暴露的插件端点提供服务；Relay 注册与 viewer 页面保留第一个源会话，读者通过策略现在绑定的会话列表访问其余源会话。每个源会话必须属于该分享的同一个工作区：Host 会拒绝无法放进该工作区的源，因此所有读者都停留在同一个工作区根目录内。停止该分享会结束它的全部源会话。
+
+源码：[`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>
+
+/**
+ * Add source Sessions to one share this host already publishes.
+ * @param request - Share and the Sessions to add.
+ * @returns The source Sessions the share now serves.
+ */
+@Remote('addSessions') addSessions(request: AddShareSessionsRequest): Promise<ShareSessions>
+
+/**
+ * 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/references/official-docs/docs/subsystems/llm-streaming.i18n.yaml

@@ -27,8 +27,8 @@
   en: cbab49d689311d4d
   zh: 76246140eabaa55e
 /llm-streaming/appidentity-app-attribution:
-  en: e053f18c7dc070a8
-  zh: 90ded9a892ed2fd5
+  en: 2da6911c03ea8195
+  zh: ae55da1a7e22be3a
 /llm-streaming/tokenusage:
   en: 33830f78fdb845fa
   zh: f43a4502c4c3bfff
@@ -36,14 +36,17 @@
   en: 58dec2259b0b1c6f
   zh: fc99fe965acaabf3
 /llm-streaming/the-model-request:
-  en: 2b0831aaae8e1cdf
-  zh: f669d93d1b9d6025
+  en: 834d3d8d6b5871ab
+  zh: 393889ec6075f622
 /llm-streaming/the-model-request/the-request-envelope-llmcallconfig-and-the-logged-header:
-  en: f2e6932e211f179b
-  zh: 75112586a6f3f4aa
+  en: b0eb4620c6953646
+  zh: fabf51c7245a4855
 /llm-streaming/official-deepseek-request-extensions:
   en: 42bc50394b070e96
   zh: 007caa743ec3c790
+/llm-streaming/pi-ai-request-headers:
+  en: 8c140f9c5a799f01
+  zh: f66b895594247e92
 /llm-streaming/service-and-provider-contracts:
   en: 8dc79d4cc82824c2
   zh: 3ebabd3a117ad717

package/references/official-docs/docs/subsystems/llm-streaming.md

@@ -311,7 +311,7 @@ Retry configuration resolves before route registration into an immutable discrim
 
 ## `AppIdentity` — app attribution
 
-The static public application identity every adapter sends to providers ([`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)). `attributionHeaders(identity?)` maps it to the standard `User-Agent` header only; OpenRouter-specific app attribution headers are intentionally not supported by this contract. The default `APP_IDENTITY` sources its version from the package manifest; every field is a public product fact - no secrets, paths, session ids, or per-user identifiers, and nothing per-request may influence the values.
+The static public application identity every adapter sends to providers ([`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)). `attributionHeaders(identity?)` maps it to the standard `User-Agent` header only; OpenRouter-specific app attribution headers are intentionally not supported by this contract. The default `APP_IDENTITY` sources its version from the package manifest; every field is a public product fact - no secrets, paths, session ids, or per-user identifiers, and nothing per-request may influence the values. `APP_IDENTITY.suffix` reads `DSH_USER_AGENT_SUFFIX` on each use, and `userAgent()` appends it after the comment; a value that is not an RFC 9110 product token fails the request. The `dsh` launcher sets it to `dsh-profile/<profile>` before any plugin loads, percent-encoding profile-name bytes outside `tchar` and `%` itself, so Desktop sends `deepseek-harness/<version> (+<url>) dsh-profile/desktop` and a profile named `my web` sends `dsh-profile/my%20web`. A dsh subagent child reports its own profile, because child processes do not inherit `DSH_*` variables.
 
 ```ts type-equiv
 /**
@@ -328,6 +328,8 @@ interface AppIdentity {
   version: string
   /** Repository home URL of the app, used as the `User-Agent` comment. */
   url: string
+  /** RFC 9110 product token appended after the comment, such as `dsh-profile/web`. */
+  suffix?: string | undefined
 }
 ```
 
@@ -525,6 +527,26 @@ interface LlmNativeAuth {
 }
 ```
 
+A catalog entry may carry a provider-authored `badge` that selectors show beside the model name. It is display data: `resolveModelInfo` omits it, and no model request carries it.
+
+```ts type-equiv
+/**
+ * Emphasis of a model badge: `neutral` states a plain fact, `info` highlights
+ * the model, `success` marks a benefit, and `warning` asks for attention.
+ */
+type LlmModelBadgeTone = 'neutral' | 'info' | 'success' | 'warning'
+```
+
+```ts type-equiv
+/** Short provider-authored label a selector shows beside one advertised model name. */
+interface LlmModelBadge {
+  /** One literal, or translations keyed by lowercase language id with a required English entry. */
+  text: LocalizedText
+  /** Emphasis of the label. */
+  tone: LlmModelBadgeTone
+}
+```
+
 ```ts type-equiv
 /** One adapter-discovered model; catalog membership is advisory, not request validation. */
 interface LlmModelInfo {
@@ -538,6 +560,11 @@ interface LlmModelInfo {
   description?: string
   /** Accepted request modalities; absent means unknown, while an explicit omission is negative capability. */
   inputModalities?: readonly ModelModality[]
+  /**
+   * Selector label advertised by catalog discovery; exact-route resolution
+   * omits it, and no model request or Session event carries it.
+   */
+  badge?: LlmModelBadge
 }
 ```
 
@@ -617,8 +644,21 @@ type RequestMessage = Message | RequestUserInput
 ```
 
 ```ts type-equiv
-/** A single model request, fully assembled. */
-interface GenerateOptions {
+/** Auxiliary request purposes declared by their producer packages. */
+interface LlmRequestPurposeMap {}
+```
+
+```ts type-equiv
+/** Declared auxiliary request purpose; ordinary conversation requests leave it absent. */
+type LlmRequestPurpose = Extract<keyof LlmRequestPurposeMap, string>
+```
+
+```ts type-equiv
+/**
+ * A single model request, fully assembled.
+ * @typeParam Purpose - declared purpose keys for callers; forwarding adapters may accept `string`.
+ */
+interface GenerateOptions<Purpose extends string = LlmRequestPurpose> {
   /** Registered provider route selecting the adapter instance. */
   provider: string
   model: string
@@ -659,7 +699,7 @@ interface GenerateOptions {
    * map the purpose to model-hidden transport metadata. Ordinary conversation
    * requests leave it unset.
    */
-  purpose?: 'compaction' | 'session-title'
+  purpose?: Purpose
 }
 ```
 
@@ -760,7 +800,7 @@ interface LlmDiscoveredModel {
 
 The loop builds each request from logged state. `EpochHeader` records call config, marks the fields supplied by adapter defaults, and records the authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. The rendered prompt is derived history — the `system/message` at surface node 0, plus any later system node an `in-history` route appended — so the header and the derived history together make the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
-`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus the fields supplied by adapter defaults under the turn signal. On step admission, this waterfall and preparation run after assembly and `step/start` but before the system prompt and accepted user batch are committed; cancellation during either commits neither. The prepared capability governs prompt reconciliation, and the call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
+The deprecated `agent/request` hook remains available to existing listeners. New code selects models and reasoning effort through [Session model selection](../../packages/core/agent/README.md#use-this-package). The hook receives a frozen call-config seed based on the step's captured model selection and may replace controls such as sampling. A replacement must preserve provider, model, and the optional explicit reasoning effort; record a new Session selection before the next step to change them. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus the fields supplied by adapter defaults under the turn signal. On step admission, this waterfall and preparation run after assembly and `step/start` but before the system prompt and accepted user batch are committed; cancellation during either commits neither. The prepared capability governs prompt reconciliation, and the call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
 
 On the wire, a loop-built request is the derived history alone: the rendered prompt travels as the leading `system`-role message (surface node 0, a `system/message` event) and, when the prepared call declares `systemPromptUpdate: 'in-history'`, a non-empty changed prompt may follow the cached history as a later `system`-role message that the model reads as the effective prompt; the request's `system` field is unset — `GenerateOptions.system` serves direct one-shot callers such as title providers. An empty rendering leaves no system messages in derived history, even when earlier requests retained several prompt versions. The logged request ends with the newest `user/message` on a turn's first step and the previous step's tool results on later steps.
 
@@ -822,6 +862,10 @@ interface LlmCallConfigAdapterDefaults {
 
 The [wire reference](../deepseek-llm-api-wire-extensions.md) defines the exact request headers, extension transaction, field versions, and receiver obligations. The shipped composition registers [`dsh_session_log`](../../packages/session/session-log-deepseek/README.md) as a lossless incremental canonical-log suffix and [`dsh_plugin_packages`](../../packages/llm/plugin-package-inventory-deepseek/README.md) as the complete active Loader-backed package set. These fields remain outside model messages and are absent from the pi-ai adapter path.
 
+## Pi-ai request headers
+
+`PiAiRequestHeaderContext` contains the prepared call's provider, model, resolved model `baseURL`, and optional Session id and auxiliary purpose. It is immutable, contains no messages or authentication fields, and accompanies a request-owned `Headers` object in the synchronous `llm-pi-ai/request-headers` waterfall. The [adapter's request-header documentation](../../packages/llm/llm-pi-ai/README.md#request-headers) defines contribution ownership, attribution precedence, and failure behavior. This extension point is specific to pi-ai inference requests.
+
 ## Service and provider contracts
 
 `LlmAdapter` is the provider contract: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmRuntime.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmRuntime.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. [architecture.md](../architecture.md#turn-flow) shows where `ctx.llm.stream()` and the `llm/stream` waterfall sit in one turn.
@@ -1170,6 +1214,23 @@ The provider topology changed: an adapter registered or unregistered routes, or
 
 Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
+<a id="llmmodels-updated--emit"></a>
+
+#### `llm/models-updated` — emit
+
+A provider's advertised models or display metadata changed; consumers reload `listModels()`.
+
+```ts cordis-catalog
+/**
+ * A provider's advertised models or display metadata changed; consumers reload `listModels()`.
+ * @mode emit
+ * @param provider - route whose model catalog changed.
+ */
+'llm/models-updated'(provider: string): void
+```
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
 <a id="llmstream--waterfall"></a>
 
 #### `llm/stream` — waterfall
@@ -1193,4 +1254,33 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 ```
 
 Source: [`packages/llm/llm/src/index.ts`](../../packages/llm/llm/src/index.ts)
+
+<a id="llm-pi-ai-events"></a>
+
+### `llm-pi-ai/*` events
+
+<a id="llm-pi-airequest-headers--waterfall"></a>
+
+#### `llm-pi-ai/request-headers` — waterfall
+
+Prepare headers for one pi-ai inference call, excluding model discovery. Listeners run synchronously and must call next(); they may edit only the request-owned headers and must not retain them. Throws fail the call with REQUEST_HEADERS before inference I/O. Harness attribution wins afterward. Non-TypeError messages are user-visible and must exclude secrets. TypeError details and non-Error values are replaced with safe guidance.
+
+```ts cordis-catalog
+/**
+ * Prepare headers for one pi-ai inference call, excluding model discovery.
+ * Listeners run synchronously and must call next(); they may edit only the
+ * request-owned headers and must not retain them. Throws fail the call with
+ * REQUEST_HEADERS before inference I/O. Harness attribution wins afterward.
+ * Non-TypeError messages are user-visible and must exclude secrets. TypeError
+ * details and non-Error values are replaced with safe guidance.
+ * @mode waterfall
+ * @param request - immutable routing metadata from the exact prepared call.
+ * @param headers - fresh profile headers, shared only within this dispatch.
+ * @param next - continue header preparation through the remaining listeners.
+ * @returns headers passed to pi-ai after Harness attribution is applied.
+ */
+'llm-pi-ai/request-headers'(request: PiAiRequestHeaderContext, headers: Headers, next: () => Headers): Headers
+```
+
+Source: [`packages/llm/llm-pi-ai/src/index.ts`](../../packages/llm/llm-pi-ai/src/index.ts)
 <!-- END GENERATED cordis-surface -->