diff --git a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml index 23935ef2ad..93feec2b95 100644 --- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml @@ -27,14 +27,14 @@ en: d5d0d6a57a4fa581 zh: 265973b157f957d9 /agent-note-session-history-control-state-and-remote-event-transport/decision/session-controller: - en: e338ac27490a380f - zh: 12600011ec742e5b + en: f432480a52414d56 + zh: 15a3f175b69cdb53 /agent-note-session-history-control-state-and-remote-event-transport/decision/session-controller/activation-policy: - en: 534dcc62a26d305e - zh: 03d64abc0a46bbec + en: 03e24cdee8519a92 + zh: 82dc02eb26d7d7f4 /agent-note-session-history-control-state-and-remote-event-transport/decision/session-controller/session-journal: - en: bb710f8cf35f2028 - zh: aae2cfb8cd848069 + en: 4de2965717900b96 + zh: 1d129003824fa6bd /agent-note-session-history-control-state-and-remote-event-transport/decision/session-controller/session-live-control: en: a11d627cd68650c3 zh: 9aff565b9f712853 diff --git a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md index de05a0e62b..ee43b551eb 100644 --- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md +++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md @@ -139,11 +139,11 @@ If a page request is canceled with its physical carrier generation, the journal `packages/api/session-controller` provides Host `ctx.sessionController` and the generated `ctx.remote.session` namespace. -It owns Session list, search, create, selectModel, rename, fork, prompt, attachment, updateQueue, cancel, page, follow, and control. The Host-generation model catalog is exposed separately through `session/modelCatalog` because it is not Session-specific. +It owns Session list, search, create, selectModel, rename, fork, prompt, attachment, updateQueue, cancel, `events`, the deprecated `page`, `follow`, `control`, plus `observeEvent`, `projections`, `observeProjections`, `state`, `observeState`, and `wait`. The Host-generation model catalog is exposed separately through `session/modelCatalog` because it is not Session-specific. The package separates agent, commands, control, history, and list controllers internally, but Session identity resolution, activation policy, subagent ownership, and Remote error projection have one public owner. -Other Host Remote namespaces reuse the same identity rules through `ctx.sessionController.inspect()` or `resolveAgent()`; they do not retain a second Session resolver. +Other Host Remote namespaces reuse the same resume-capable identity rules through `ctx.sessionController.resolveAgent()`; they do not retain a second Session resolver. #### Activation policy @@ -157,7 +157,8 @@ Each method explicitly selects a cold inspection, live-only lookup, or resume-ca | `session.page(address)` | attached Session or persistence log | Never resumes an Agent | | `session.follow(address)` | one live or prepared observation carrying the opening page and projections | Publishes the snapshot first, then promotes an ordinary cold Session once in the background | | `session.control()` | current attached Agents, pending registry, and process-local registries | Baseline and reconnect do not resume an Agent | -| `session.attachment`, fork source read | authorized durable Session data | A read does not resume an Agent | +| Fork source read | authorized durable Session data | A read does not resume an Agent | +| `session.attachment` | attachment store under the [image access rule](2026-10-23-store-scoped-image-reads.md) | A read does not resume an Agent | | `session.updateQueue` | live Agent or ordinary persisted Session | Resumes an ordinary cold Session before mutating its Inbox | | `session.cancel` | only the current live Agent | Does not resume vanished state | | `models`, `selectModel`, `rename`, `prompt` | command resolves the target Session | Resumes only when the method explicitly permits it | @@ -173,9 +174,9 @@ Reading titles, lists, and projections does not require an Agent. An observation #### Session journal -`session.page` returns a history window clipped on message boundaries with contiguous internal sequence numbers. Every request must carry an explicit `throughSeq`; this value comes from the corresponding `session.follow` generation's opening cursor and fixes the read at the same log cut. A tail page without `beforeSeq` must end exactly at `throughSeq`, where `-1` denotes an empty log. `beforeSeq` only selects an older page before that cut and cannot replace the synchronization cursor. `maxMessages` limits user/assistant message count without dropping chunks, tools, or state events between those messages. +`session.events` returns a history window clipped on message boundaries with contiguous internal sequence numbers. `throughSeq` is optional: when omitted, the read selects the observed log end and returns it as the page's inclusive `cursor`; a supplied value fixes the read at that cut. A page without `beforeSeq` ends exactly at the selected cut, where `-1` denotes an empty log. `beforeSeq` only selects an older page before that cut and cannot replace the synchronization cursor. `maxMessages` limits user/assistant message count without dropping chunks, tools, or state events between those messages. The deprecated `session.page` entry returns the same type. -The tail page also carries a projection baseline no later than `throughSeq`; older pages carry only historical entries. The Client merges pages and subsequent live control updates by projection watermark. +A page carries only its records, `hasMore`, and inclusive `cursor`; a projection baseline comes from a follow opening snapshot or the control stream, never from a page. The Client merges pages and subsequent live control updates by projection watermark. Ordinary Sessions and direct subagents use one `SessionAddress` protocol. A direct-subagent address carries parent Session, child Session, and mode; a cold Host read verifies durable ownership and descriptor rather than authorizing access from the child id alone. diff --git a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md index 004da80fee..9df5c55701 100644 --- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md @@ -139,11 +139,11 @@ repair 期间旧 window 保持可读；page 与期间积累的 live entries 拼 `packages/api/session-controller` 提供 Host `ctx.sessionController` 与生成的 `ctx.remote.session` namespace。 -它拥有 Session list、search、create、selectModel、rename、fork、prompt、attachment、updateQueue、cancel、page、follow 与 control。Host generation 的 model catalog 通过独立的 `session/modelCatalog` 公开，因为它不属于特定 Session。 +它拥有 Session list、search、create、selectModel、rename、fork、prompt、attachment、updateQueue、cancel、`events`、已弃用的 `page`、`follow`、`control`，以及 `observeEvent`、`projections`、`observeProjections`、`state`、`observeState` 与 `wait`。Host generation 的 model catalog 通过独立的 `session/modelCatalog` 公开，因为它不属于特定 Session。 包内的 agent、commands、control、history 与 list controller 分开实现，但 Session 身份解析、激活策略、subagent ownership 和 Remote 错误投影只有一个公开 owner。 -其他 Host Remote namespace 通过 `ctx.sessionController.inspect()` 或 `resolveAgent()` 复用同一身份规则，不保留第二份 Session resolver。 +其他 Host Remote namespace 通过 `ctx.sessionController.resolveAgent()` 复用同一套允许恢复 Session 的身份规则，不保留第二份 Session resolver。 #### 激活策略 @@ -157,7 +157,8 @@ Session Remote 方法传递 `SessionId` 或 `SessionAddress`，不靠参数类 | `session.page(address)` | attached Session 或 persistence 日志 | 永不恢复 Agent | | `session.follow(address)` | 一份携带 opening page 与 projection 的 live 或 prepared observation | 先发布 snapshot，再在后台把普通冷 Session 提升一次 | | `session.control()` | 当前 attached Agent、pending registry 与进程内 registry | baseline 与重连不恢复 Agent | -| `session.attachment`、fork 源读取 | 已授权的持久 Session 数据 | 读取不恢复 Agent | +| Fork 源读取 | 已授权的持久 Session 数据 | 读取不恢复 Agent | +| `session.attachment` | 按[图片访问规则](2026-10-23-store-scoped-image-reads.zh.md)读取附件存储 | 读取不恢复 Agent | | `session.updateQueue` | live Agent 或普通持久 Session | 修改 Inbox 前恢复普通冷 Session | | `session.cancel` | 仅命中当前 live Agent | 不为已消失状态恢复 Agent | | `models`、`selectModel`、`rename`、`prompt` | 命令解析目标 Session | 仅按方法约定显式恢复 | @@ -173,9 +174,9 @@ Session Remote 方法传递 `SessionId` 或 `SessionAddress`，不靠参数类 #### Session 日志 -`session.page` 返回一段按消息边界裁剪、内部 seq 连续的历史窗口。每个请求必须显式携带 `throughSeq`；该值来自对应 `session.follow` generation 的 opening cursor，并把本次读取固定在同一个日志切点。无 `beforeSeq` 的 tail page 必须精确结束于 `throughSeq`，其中 `-1` 表示空日志；`beforeSeq` 只选择该切点之前的更早页面，不能替代同步 cursor。`maxMessages` 限制 user／assistant 消息数，不丢弃这些消息之间的 chunk、tool 或状态事件。 +`session.events` 返回一段按消息边界裁剪、内部 seq 连续的历史窗口。`throughSeq` 可省略：省略时选取观察到的日志末尾，并把该切点作为页面的 inclusive `cursor` 返回；显式提供时把本次读取固定在该切点。无 `beforeSeq` 的 page 精确结束于所选切点，其中 `-1` 表示空日志；`beforeSeq` 只选择该切点之前的更早页面，不能替代同步 cursor。`maxMessages` 限制 user／assistant 消息数，不丢弃这些消息之间的 chunk、tool 或状态事件。已弃用的 `session.page` 入口返回同一类型。 -tail page 同时携带不晚于 `throughSeq` 的 projection baseline；旧页只携带历史 entries。Client 以 projection watermark 合并 page 与后续 live control 更新。 +page 只携带记录、`hasMore` 和 inclusive `cursor`；projection baseline 来自 follow 的开场快照或 control 流，不来自 page。Client 以 projection watermark 合并 page 与后续 live control 更新。 普通 Session 与 direct subagent 使用同一个 `SessionAddress` 协议。direct subagent 地址同时携带父 Session、子 Session 与 mode，Host 冷读时验证持久 ownership 和 descriptor，不能只凭 child id 越权读取。 diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml index e70e858963..86b5f42ac4 100644 --- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml @@ -51,8 +51,8 @@ en: 51f99cfca9c4c808 zh: ce95bab241d306f7 /agent-note-client-derived-presentation-from-raw-session-tool-events/host-design: - en: 16fd2b3e545ede21 - zh: 4d28f52132495441 + en: d5e5d1376dc42558 + zh: c2f302b2a5d1de39 /agent-note-client-derived-presentation-from-raw-session-tool-events/host-design/performance-constraints: en: 102b14e3eb9367ff zh: d391099dbc41db24 diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md index 8a0c4ea6fc..8c32436c6a 100644 --- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md +++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md @@ -195,9 +195,9 @@ The Client narrows `meta` locally at runtime. Renaming `presentationMeta` to mor ## Host Design -After obtaining source events, `SessionHistoryController.page()` performs only pagination and the existing projection-baseline calculation. Attached Sessions use the projection registry snapshot; detached Sessions use its restore path over the inspected log. History does not mount a preset to change the registered projection set. +After obtaining source events, `HistoryController.history()` performs only pagination and requests projections only for a subagent address that needs descriptor validation. Attached Sessions use the projection registry snapshot; detached Sessions use its restore path over the inspected log. History does not mount a preset to change the registered projection set. -`SessionHistoryController.follow()` retains listener-first setup, opening cursors, gap-free replay, live buffering, cancellation, and teardown. It maintains no additional state for tool events. +`WebController.follow()` retains listener-first setup, opening cursors, gap-free replay, live buffering, cancellation, and teardown. It maintains no additional state for tool events. The controller has no `presenterScopeFor()`, `viewFor()`, `backscanArgs()`, `parseToolCall()`, or `jsonView()` path. Page state contains no presenter scope or argument resolver; follow state contains no `openCalls`, `fallbackEvents`, or presentation argument resolver. Each page/follow event is wrapped only as `{event}` while addressing, ownership, cursor, sequence, and projection logic remains intact. diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md index 2dd4ad8bc9..6ba3e040bd 100644 --- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md @@ -195,9 +195,9 @@ Client 对 `meta` 做局部运行时收窄。是否把 `presentationMeta` 改名 ## Host 端设计 -`SessionHistoryController.page()` 在取得 source events 后只执行分页与现有 projection baseline 计算。attached Session 使用 projection registry snapshot；detached Session 使用该 registry 对 inspected log 的 restore 路径。history 不通过挂载 preset 改变已注册的 projection 集合。 +`HistoryController.history()` 在取得 source events 后只执行分页，并且只有需要校验 descriptor 的 subagent 地址才请求投影。attached Session 使用 projection registry snapshot；detached Session 使用该 registry 对 inspected log 的 restore 路径。history 不通过挂载 preset 改变已注册的 projection 集合。 -`SessionHistoryController.follow()` 保留 listener-first、opening cursor、gap-free replay、live buffering、取消和 teardown；它不为工具事件维护额外状态。 +`WebController.follow()` 保留 listener-first、opening cursor、gap-free replay、live buffering、取消和 teardown；它不为工具事件维护额外状态。 Controller 不存在 `presenterScopeFor()`、`viewFor()`、`backscanArgs()`、`parseToolCall()` 或 `jsonView()` 路径。page state 不含 presenter scope 或参数 resolver；follow state 不含 `openCalls`、`fallbackEvents` 或 presentation 参数 resolver。每个 page/follow event 只包装成 `{event}`，地址、ownership、cursor、seq 与 projection 逻辑保持完整。 diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml index bd2626e850..c67dff0722 100644 --- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml @@ -15,17 +15,17 @@ en: 480284ae1a6ce210 zh: d42c72ada9f019f8 /agent-note-session-observations-and-projection-owned-client-state/decision/observation-is-the-point-read-unit: - en: fac92f8547482a49 - zh: 60240c47fbe4611f + en: 283136ae36512767 + zh: e342b446c77ae300 /agent-note-session-observations-and-projection-owned-client-state/decision/source-resolution-and-lifetime: - en: e550ae9892474276 - zh: fb6a2d9e91ebd4d9 + en: bced4b90cb03525d + zh: b0c1ca4bf1064f89 /agent-note-session-observations-and-projection-owned-client-state/decision/projection-execution-boundary: - en: 148de86941b90f41 - zh: c065a8e96e28b9d7 + en: b3b235fa0250868a + zh: 0bb5eedf14cdafee /agent-note-session-observations-and-projection-owned-client-state/decision/read-audiences: - en: 888f62659f4d868d - zh: e74491e8c85046ee + en: e394e9480340f69c + zh: 7eea994ee9fa380d /agent-note-session-observations-and-projection-owned-client-state/decision/replayable-client-facts-are-projection-owned: en: efded09f0cd30a8e zh: 5e16580a39ff3359 @@ -48,11 +48,11 @@ en: 8d699dfc22ab5c5f zh: 8dcd9fc6bd1594db /agent-note-session-observations-and-projection-owned-client-state/verification: - en: df17217023668428 - zh: 88f7da4deffc6bf9 + en: 29f364d1031b7d85 + zh: 2b193ceb52fb0406 /agent-note-session-observations-and-projection-owned-client-state/alternatives-considered: - en: a25138b4298cda16 - zh: 92799a9bd8867d47 + en: 90574351058d5d8c + zh: 6aa514cf47495ed2 /agent-note-session-observations-and-projection-owned-client-state/consequences: en: e1f8bd8fa68de603 zh: 5afcd06f2611bc1e diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md index 523122c9ae..530aeb36e1 100644 --- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md +++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md @@ -24,7 +24,7 @@ The two ownership rules meet at the observation's projection snapshot. Lightweig flowchart LR List["list / search"] --> Corpus["SessionQuery corpus"] Follow["follow"] --> Observe["observeSession"] - Page["page / attachment / fork"] --> Observe + Page["page / fork"] --> Observe Subagent["subagent list / continuation"] --> Observe Corpus --> Cache["projection cache hints"] Cache --> ClientList["Client Session list"] @@ -46,7 +46,7 @@ flowchart LR `SessionQueryEngine.observeSession(sessionId, options)` returns a disposable `SessionObservation` containing one source kind, header, contiguous event prefix, cursor, optional projection snapshot, and the durable revision for a prepared source. An attached Session wins. Otherwise the reader's own prepared cache — keyed by `stat().revision` and pinned by observation leases — serves the cold Session, sharing one persistence read (`open(id, 'read')` + `read`) across concurrent observations, including an in-flight cold load. -Every owner disposes its observation. `retain()` creates another lease over the same cut, which lets `session.follow` publish a snapshot and then transfer that exact prepared source to background Agent promotion without rereading the log. A live Session that appears during cold resolution wins before publication; a disappeared live source is retried as cold. +Every owner disposes its observation. `retain()` creates another lease over the same cut, which lets `session.follow` transfer that exact prepared source to background Agent promotion before delivering the snapshot, without rereading the log. A live Session that appears during cold resolution wins before publication; a disappeared live source is retried as cold. ### Source resolution and lifetime @@ -56,7 +56,7 @@ Live preference is checked both before and after a cold borrow. The second check Persistence absence maps to Session-not-found only after no attached Session exists. Durable corruption, source-identity conflict, cancellation, and operational persistence failure remain distinct `SessionQueryError` outcomes so API owners can preserve their own public error vocabulary without duplicating source detection. -The observation owns no mutation authority. Its event array is an immutable prefix, and its prepared Session remains unpublished. Promotion is an explicit ownership transfer performed by the Session Controller after it has emitted the opening snapshot; other readers cannot turn an observation into a live Agent. +The observation owns no mutation authority. Its event array is an immutable prefix, and its prepared Session remains unpublished. Promotion is an explicit ownership transfer the Session Controller starts once the opening is computed, before delivering it; other readers cannot turn an observation into a live Agent. Projection work is deliberately `all | none`. `all` computes every registered projection at the observation's event cursor; `none` leaves projection state untouched. There is no per-key preparation state, `projectionKeys` mode, or cached `viewedState`/`viewedValue` layer. A publisher may filter the completed values for an audience, but the underlying observation is never partly projected. @@ -72,7 +72,7 @@ The registry owns fold state; each domain owns its `init`, `apply`, `view`, sche Corpus listing remains a separate lightweight operation. `listSessions()` returns live-preferred headers without materializing every log. Session list first uses live projection state or durable projection-cache rows. Subagent discovery reads parent-catalog projections through exact observations. Session list may take one complete observation for an individually stored artifact within its configured small-log limit when cached metadata cannot establish whether it is blank; a large or unreadable cache miss remains visible with unknown hints. -`session.follow` publishes a required opening snapshot containing header, cursor, the initial event window, and a complete projection baseline. Reconnect replaces the previous generation from another complete snapshot. `session.page` is reserved for older-history reads and gap repair. Observation-only reads never activate an Agent; only an ordinary follow may retain its prepared observation and request promotion after the opening snapshot has been delivered. +`session.follow` publishes a required opening snapshot containing header, cursor, the initial event window, and a complete projection baseline. Reconnect replaces the previous generation from another complete snapshot. `session.page` supports current or fixed-cut history reads, older-history reads, and gap repair. Observation-only reads never activate an Agent; only an activation-enabled ordinary Follow may retain its prepared observation and request promotion once the opening snapshot is computed, before it is delivered. The [snapshot and subscription decision](2026-10-21-session-history-stream-and-snapshot.md) defines the Controller composition and passive subscription semantics. ### Read audiences @@ -82,9 +82,10 @@ Each public operation chooses one query and projection policy. The choice is par |---|---|---|---| | `session.list` | Corpus headers, live state, and cached rows; bounded small-log fallback | Partial hints, or one full small-log observation | Never | | `session.search` | Corpus authorization plus the configured search provider | None for result listing | Never | -| `session.follow` | One exact observation | All, carried in the opening snapshot | Ordinary cold Session only, after snapshot delivery | +| `session.follow` | One exact observation | All, carried in the opening snapshot | Only with `activate: true`, for an ordinary cold Session once the opening is computed, before delivery | | `session.page` | One exact observation | None, except projection-backed subagent authorization | Never | -| Attachment and fork source | One exact observation | None unless authorization requires it | Never for the source | +| Fork source | One exact observation | None unless authorization requires it | Never for the source | +| Attachment | Direct store read under the [image access rule](2026-10-23-store-scoped-image-reads.md) | None | Never | | Subagent list and continuation | Parent-catalog observations for listing; target observations for continuation | All; listing consumes catalog values, continuation consumes identity and inherited values | Never for listing; continuation follows its explicit command semantics | ### Replayable Client facts are projection-owned @@ -171,7 +172,7 @@ These rules apply to new Session-derived Client state even when a direct event s ## Verification -Persistence and SessionQuery tests pin shared cold loading, cancellation, live-source races, retained observations, disposal, and all-or-none projection calculation. Session Controller and Gateway tests pin snapshot-first opening, replacement reconnect, older-page reads, gap repair, list-cache hints, bounded small-log fallback, and promotion after snapshot delivery. +Persistence and SessionQuery tests pin shared cold loading, cancellation, live-source races, retained observations, disposal, and all-or-none projection calculation. Session Controller and Gateway tests pin snapshot-first opening, replacement reconnect, older-page reads, gap repair, list-cache hints, bounded small-log fallback, and promotion once the opening is computed. Client tests pin higher-sequence-wins projection storage, title updates, model catalog and selection readiness, preset roster refresh and Session-specific selection, and subagent loading without transient offline presentation. Subagent tests pin parent-catalog order, recursive traversal, branch diagnostics, cancellation, fork isolation, and no Agent activation during listing. @@ -179,7 +180,7 @@ Client tests pin higher-sequence-wins projection storage, title updates, model c **Keep source resolution in each consumer.** Rejected because every caller would continue to implement its own live race, persistence error mapping, preparation lifetime, cancellation, and projection cut, allowing both duplicate work and inconsistent results. -**Activate an Agent for every exact read.** Rejected because list, history, attachment, search, and subagent inspection are read operations. Activation loads plugins and changes process state, and it has no natural retirement point for pagination or catalog reads. +**Activate an Agent for every exact read.** Rejected because list, history, search, and subagent inspection are read operations. Activation loads plugins and changes process state, and it has no natural retirement point for pagination or catalog reads. **Prepare only requested projection keys.** Rejected because a partially projected Session creates another lifecycle state that every cache, restore, plugin-registration, and caller path must track. Projection units are pure and few; computing all registered units for an exact observation is simpler than maintaining `O(E*k)` partial state instead of `O(E*P)` complete state. diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md index 6639047731..62ac9db852 100644 --- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md @@ -24,7 +24,7 @@ Session 精确读取使用可保留的 `SessionObservation`，向 Client 暴露 flowchart LR List["list / search"] --> Corpus["SessionQuery corpus"] Follow["follow"] --> Observe["observeSession"] - Page["page / attachment / fork"] --> Observe + Page["page / fork"] --> Observe Subagent["subagent list / continuation"] --> Observe Corpus --> Cache["projection cache hints"] Cache --> ClientList["Client Session list"] @@ -46,7 +46,7 @@ flowchart LR `SessionQueryEngine.observeSession(sessionId, options)` 返回可 dispose（资源释放）的 `SessionObservation`，其中包含同一份 source kind、header、连续事件前缀、cursor、可选 projection snapshot，以及 prepared source 的持久化 revision。已挂载 Session 优先；否则由读取方自己的 prepared cache——以 `stat().revision` 为键、由 observation lease 固定——提供冷 Session，让并发 observation 共享同一次持久化读取（`open(id, 'read')` + `read`），包括尚未完成的冷加载。 -每个 owner 都会 dispose 自己的 observation。`retain()` 为同一切面创建另一份 lease，使 `session.follow` 能够先发布 snapshot，再把完全相同的 prepared source 转交给后台 Agent promotion，而无需重读日志。冷解析期间出现的 live Session 会在发布前胜出；已经消失的 live source 会按 cold source 重试。 +每个 owner 都会 dispose 自己的 observation。`retain()` 为同一切面创建另一份 lease，使 `session.follow` 能把完全相同的 prepared source 转交给后台 Agent promotion，并在交付 snapshot 前启动它，而无需重读日志。冷解析期间出现的 live Session 会在发布前胜出；已经消失的 live source 会按 cold source 重试。 ### 数据源解析与生命周期 @@ -56,7 +56,7 @@ flowchart LR 只有在不存在已挂载 Session 后，persistence absence 才映射为 Session-not-found。持久数据损坏、source identity 冲突、取消和 persistence 操作失败分别保留不同的 `SessionQueryError`，API owner 因而可以维持自身公开错误词汇，而不用重复数据源判定。 -Observation 不拥有任何 mutation 权限。其事件数组是不可变前缀，prepared Session 保持未发布。Promotion 是 Session Controller 在 opening snapshot 发出后执行的显式 ownership transfer；其他读方不能把 observation 变成 live Agent。 +Observation 不拥有任何 mutation 权限。其事件数组是不可变前缀，prepared Session 保持未发布。Promotion 是 Session Controller 在 opening 计算完成后、交付前启动的显式 ownership transfer；其他读方不能把 observation 变成 live Agent。 Projection 工作明确只有 `all | none` 两种模式。`all` 在 observation 的事件 cursor 上计算所有已注册 projection；`none` 完全不触碰 projection 状态。系统不存在按 key preparation 的状态、`projectionKeys` 模式或额外的 `viewedState`／`viewedValue` cache。发布方可以按 audience 筛选已完成的值，但底层 observation 不会处于只算完部分 projection 的状态。 @@ -72,7 +72,7 @@ Registry 拥有 fold state；各领域拥有自己的 `init`、`apply`、`view` 语料库 list 仍是独立的轻量操作。`listSessions()` 返回 live-preferred header，而不物化每份日志。Session list 先读取 live projection 状态或持久 projection-cache row。Subagent 发现通过精确 observation 读取父目录 projection。当 cache 无法判断 Session 是否为空，且该 Session 拥有的独立产物未超过配置的小日志限制时，Session list 可以执行一次完整 observation；大型或不可读的 cache miss 仍以 hints 未知但 row 可见的方式返回。 -`session.follow` 发布必需的 opening snapshot，其中包含 header、cursor、首个事件窗口和完整 projection baseline。重连使用另一份完整 snapshot 替换上一 generation。`session.page` 仅用于旧历史读取与 gap repair。只读 observation 不激活 Agent；只有普通 follow 可以保留 prepared observation，并在 opening snapshot 已交付后请求 promotion。 +`session.follow` 发布必需的 opening snapshot，包含 header、cursor、初始事件窗口与完整 projection baseline。重连通过另一份完整快照替换之前的 generation。`session.page` 支持当前或固定切点的历史读取、旧历史分页及缺口修复。只读 Observation 不激活 Agent；只有显式启用激活的普通 Follow 可以在开场计算完成后、交付之前 retain prepared observation 并请求提升。[快照与订阅决策](2026-10-21-session-history-stream-and-snapshot.zh.md)定义 Controller 组合和纯订阅语义。 ### 读取 audience @@ -82,9 +82,10 @@ Registry 拥有 fold state；各领域拥有自己的 `init`、`apply`、`view` |---|---|---|---| | `session.list` | Corpus header、live state 和 cached row；有界小日志 fallback | 部分 hints，或一次完整小日志 observation | 从不 | | `session.search` | Corpus 鉴权加已配置 search provider | 结果列表不计算 | 从不 | -| `session.follow` | 一份精确 observation | 全算，并由 opening snapshot 携带 | 仅普通 cold Session，且在 snapshot 交付后 | +| `session.follow` | 一份精确 observation | 全算，并由 opening snapshot 携带 | 仅 `activate: true` 的普通 cold Session，且在开场计算完成后、交付前 | | `session.page` | 一份精确 observation | 不计算，但 projection-backed subagent 鉴权除外 | 从不 | -| Attachment 与 fork source | 一份精确 observation | 鉴权不要求时不计算 | source 从不激活 | +| Fork source | 一份精确 observation | 鉴权不要求时不计算 | source 从不激活 | +| Attachment | 按[图片访问规则](2026-10-23-store-scoped-image-reads.zh.md)直接读取存储 | 不计算 | 从不 | | Subagent list 与 continuation | Listing 观察父目录；continuation 观察目标 | 全算；listing 消费目录值，continuation 消费身份与继承值 | Listing 从不；continuation 遵循显式命令语义 | ### 可回放的 Client 事实归 projection 所有 @@ -171,7 +172,7 @@ Client 本地交互状态也继续留在本地：loading 和 error 状态、打 ## 验证 -Persistence 与 SessionQuery 测试固定共享冷加载、取消、live-source race、retained observation、dispose 和 all-or-none projection 计算。Session Controller 与 Gateway 测试固定 snapshot-first opening、replacement reconnect、旧分页读取、gap repair、list-cache hints、小日志有界 fallback，以及 snapshot 交付后的 promotion。 +Persistence 与 SessionQuery 测试固定共享冷加载、取消、live-source race、retained observation、dispose 和 all-or-none projection 计算。Session Controller 与 Gateway 测试固定 snapshot-first opening、replacement reconnect、旧分页读取、gap repair、list-cache hints、小日志有界 fallback，以及开场计算完成后的 promotion。 Client 测试固定 higher-sequence-wins projection store、title 更新、model catalog 与 selection readiness、preset roster refresh 与 Session 专属选择，以及不会短暂展示离线状态的 subagent loading。Subagent 测试固定父目录顺序、递归遍历、分支诊断、取消、fork 隔离，以及 listing 期间不激活 Agent。 @@ -179,7 +180,7 @@ Client 测试固定 higher-sequence-wins projection store、title 更新、model **由各消费方继续解析数据源。** 否决，因为每个调用方都需要重复实现 live race、persistence error mapping、preparation lifetime、cancellation 和 projection cut，既会重复工作，也会产生不一致结果。 -**每次精确读取都激活 Agent。** 否决，因为 list、history、attachment、search 与 subagent inspection 都是读取操作。Activation 会加载插件并改变进程状态，也没有适合分页或 catalog 读取的自然退出点。 +**每次精确读取都激活 Agent。** 否决，因为 list、history、search 与 subagent inspection 都是读取操作。Activation 会加载插件并改变进程状态，也没有适合分页或 catalog 读取的自然退出点。 **只 prepare 被请求的 projection key。** 否决，因为只完成部分 projection 的 Session 会增加一种生命周期状态，所有 cache、restore、plugin registration 和调用路径都必须追踪它。Projection unit 数量少且为纯函数；精确 observation 计算全部已注册 unit，比为了 `O(E*k)` 而维护部分状态、取代 `O(E*P)` 完整状态更简单。 diff --git a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml index 93080791e0..ed47cbd168 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.i18n.yaml @@ -30,8 +30,8 @@ en: 9d2d50cb76754b74 zh: 9ceed3652475f18d /agent-note-historical-session-reads-prepare-before-write-publication/decision/follow-and-agent-promotion: - en: 692c29db3e7ab07e - zh: 7da0cfdbc80f407d + en: 46da45b9b63e7298 + zh: 3d55099479a80bd9 /agent-note-historical-session-reads-prepare-before-write-publication/problem-to-solution-mapping: en: e067e187cd4d0a8c zh: b0c79b635a637296 diff --git a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md index 081044e34d..4948e31a32 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md +++ b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.md @@ -102,7 +102,7 @@ No external caller can append before the handle exists. `append`, `flush`, and ` ### Follow and Agent promotion -`session.follow` opens history through the read path, restores the Session and projections, emits the opening snapshot, and then starts Agent promotion. Agent resume uses write open, so it waits for publication before the Agent accepts a new turn. History visibility and write readiness are separate timing points without introducing an unpublished append state. +`session.follow` opens history through the read path, restores the Session and projections, starts Agent promotion from the separately retained Observation when the caller requests activation, and then delivers the opening snapshot. Agent resume uses write open, so it waits for publication before the Agent accepts a new turn. History visibility and write readiness are separate timing points without introducing an unpublished append state. ## Problem-to-solution mapping diff --git a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md index 7406e7cf31..41a87efa86 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-05-read-only-session-migration-preparation.zh.md @@ -102,7 +102,7 @@ Handle 返回前，外部 caller 无法 append。因此 `append`、`flush` 与 ` ### Follow 与 Agent promotion -`session.follow` 通过 read path 打开历史、恢复 Session 与 projections、发出 opening snapshot，然后启动 Agent promotion。Agent resume 使用 write open，因此会在 Agent 接收新一轮对话前等待 publication。历史可见与写入就绪成为两个明确时间点，同时不引入 unpublished append state。 +`session.follow` 通过 read path 打开历史、恢复 Session 与 projections，在调用方请求激活时先用单独 retain 的 Observation 启动 Agent promotion，再交付 opening snapshot。Agent resume 使用 write open，因此会在 Agent 接收新一轮对话前等待 publication。历史可见与写入就绪成为两个明确时间点，同时不引入 unpublished append state。 ## 问题与方案对照 diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml index 38d42e7d93..59746973b8 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml @@ -39,8 +39,8 @@ en: ef015f605f7b00ab zh: eee9c79faebf3dff /agent-note-workspace-file-service/alternatives-considered: - en: 8eee658526db4465 - zh: 4a655accf6a5c08a + en: c750d88e0e746a99 + zh: 9e904ad4172fda49 /agent-note-workspace-file-service/consequences: en: 246bb7aed62f6c9b zh: debf6d4129ee477b diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md index 02937e54e2..e475fb24b2 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md +++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md @@ -117,7 +117,7 @@ The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, **Serving navigable workspace documents.** Rejected on origin grounds; the [binary transfer](2026-09-17-workspace-file-binary-transfer.md) returns multipart data while HTML remains isolated in a Blob iframe. -**Log-reachable or workspace-contained authorization for file reads.** The one precedent that sends file content over the wire, command attachments, authorizes only files that appear in the session log. That excludes typed paths, while workspace containment excludes readable files elsewhere on the Session backend. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) instead makes the backend's read decision authoritative and keeps containment only for workspace-shaped operations. +**Log-reachable or workspace-contained authorization for file reads.** Requiring a Session-log reference excludes typed paths, while workspace containment excludes readable files elsewhere on the Session backend. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) makes the backend's read decision authoritative and keeps containment only for workspace-shaped operations. Image attachment reads separately follow the [store-level access rule](2026-10-23-store-scoped-image-reads.md). **Whole-file read and slice for the byte window.** The interim form of `readBytes` read the file from its start to the window's end through `readBytes(target, signal, offset + length)` and sliced. It cannot read a window of a file longer than that end — the seam refuses such a file as too large — so no window could ever report `eof: false`, which contradicts the reason the method exists. Rejected in favour of the `readByteRange` seam, whose bound is the window. diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md index 60b9597225..b11f7d5388 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md @@ -117,7 +117,7 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`，存 **提供可导航的工作区文档。** 因源隔离问题不采用；[二进制传输](2026-09-17-workspace-file-binary-transfer.zh.md)返回 multipart 数据，HTML 仍隔离在 Blob iframe 中。 -**文件读取采用“日志可达”或工作区包含授权。** 唯一把文件内容送过线路的先例——命令附件——只授权出现在会话日志里的文件，这会排除手输路径；工作区包含则会排除 Session 后端其他位置的可读文件。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)改为以后端读取决策为准，只对工作区形态的操作保留包含限制。 +**文件读取采用“日志可达”或工作区包含授权。** 要求 Session 日志引用会排除手输路径；工作区包含则会排除 Session 后端其他位置的可读文件。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)以后端读取决策为准，只对工作区形态的操作保留包含限制。图片附件读取另行遵循[存储范围的访问规则](2026-10-23-store-scoped-image-reads.zh.md)。 **为字节窗口整文件读取再切片。** `readBytes` 的临时形态经 `readBytes(target, signal, offset + length)` 从文件开头读到窗口末端再切片。它读不了比该末端更长的文件的窗口——seam 会以过大拒绝这样的文件——因此没有任何窗口能报告 `eof: false`，与该方法存在的理由相悖。被否，改为以窗口为界的 `readByteRange` seam。 diff --git a/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.i18n.yaml index 47d3a65a12..057703698a 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.i18n.yaml @@ -6,8 +6,8 @@ en: 982ac05aa02da2f0 zh: 225f89c994efb1c4 /agent-note-awaited-per-agent-initialization/problem: - en: 03e6b75365b29406 - zh: cc880a33cf2303d0 + en: 6e9393e78ff71286 + zh: b931a7e606cad37e /agent-note-awaited-per-agent-initialization/decision: en: 48cdb570d3feb222 zh: 904a1169540e3111 @@ -15,5 +15,5 @@ en: 466a9ebbb13f68c6 zh: ab88fb34786d2c2b /agent-note-awaited-per-agent-initialization/consequences: - en: d8cfe8d88ccacfc8 - zh: 8d2aa21408e6e40e + en: 3fc2b36a94ace3ba + zh: 65bb386b89ff89ce diff --git a/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.md b/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.md index 40dcec53a8..1c49baf206 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.md +++ b/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.md @@ -6,7 +6,7 @@ English | [中文](2026-09-09-awaited-agent-creation.zh.md) ## Problem -Shared presets install tools and prompt sections separately for each Agent. That installation can await plugin activation, and external SessionStart hooks can produce context asynchronously. A creator must know that these contributions have finished before the Agent's first model request. +Agent-specific plugins can install tools asynchronously, and external SessionStart hooks can produce context asynchronously. A creator must know that these contributions have finished before the Agent's first model request. ## Decision @@ -28,4 +28,6 @@ This decision owns asynchronous creation timing. The [scope runtime reference](. Creation latency includes asynchronous plugin and SessionStart work. Initializer failures become caller-visible creation failures, and cancellation relies on listeners settling cooperatively. Notifications already delivered cannot be undone; rollback pairs them with disposal notifications. -Scoped installer tests verify rollback, lifecycle tests verify ordered completion and cancellation, and the SDK serial-created scenario verifies that asynchronous prompt context reaches the first request. Hook tests cover awaited context injection and subprocess disposal. +Lifecycle tests verify initialization rollback, ordered completion and cancellation, and the SDK serial-created scenario verifies that asynchronous prompt context reaches the first request. Hook tests cover awaited context injection and subprocess disposal. + +Delegation tools use [shared preset registrations](../bug-fix/2026-10-25-shared-preset-delegation-tools.md); they do not require per-Agent installation. This event still owns asynchronous Agent initialization. diff --git a/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.zh.md b/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.zh.md index 43b0bfa7d1..29b50eefb1 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-09-awaited-agent-creation.zh.md @@ -6,7 +6,7 @@ Status: implemented ## 问题 -共享 preset 为每个 Agent（智能体）分别安装工具与提示词段。安装可能要等待插件激活，外部 SessionStart 钩子也可能异步产生上下文。创建方必须知道这些贡献已完成，才能允许 Agent 发起首次模型请求。 +针对单个 Agent（智能体）的插件可能异步安装工具，外部 SessionStart 钩子也可能异步产生上下文。创建方必须知道这些贡献已完成，才能允许 Agent 发起首次模型请求。 ## 决策 @@ -28,4 +28,6 @@ AgentLoop 在 setup 与创建分发期间保留现有的维护活动。初始化 创建延迟包括异步插件与 SessionStart 工作。初始化器失败成为调用方可见的创建失败，取消依赖监听器协作结算。已经送达的通知无法撤回；回滚会为其配对销毁通知。 -作用域安装器测试验证回滚，生命周期测试验证有序完成与取消，SDK serial-created 场景验证异步提示词上下文进入首次请求。钩子测试覆盖需等待的上下文注入与子进程 dispose。 +生命周期测试验证初始化回滚、有序完成与取消，SDK serial-created 场景验证异步提示词上下文进入首次请求。钩子测试覆盖需等待的上下文注入与子进程 dispose。 + +委派工具使用[预设共享注册](../bug-fix/2026-10-25-shared-preset-delegation-tools.zh.md)，无须按 Agent 安装。此事件仍负责异步 Agent 初始化。 diff --git a/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.i18n.yaml index 511e290621..e0b3e158eb 100644 --- a/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.i18n.yaml @@ -9,8 +9,8 @@ en: edefff7cd986a509 zh: a270839fa86976a2 /agent-note-guided-plugin-installation/decision: - en: 5448b9f8aaa9a569 - zh: 9024c5328c5da3bd + en: ca0224ae08a4b383 + zh: 780603ca24487949 /agent-note-guided-plugin-installation/alternatives-considered: en: be64b541f4d81e7c zh: 8600531c08ab4288 diff --git a/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.md b/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.md index 40cbf6179b..aa62340f84 100644 --- a/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.md +++ b/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.md @@ -14,7 +14,7 @@ The install dialog put a spec straight into `pnpm add` and showed pnpm's termina **A failed or cancelled installation restores the profile files.** `installBundle` snapshots `package.json` and `pnpm-lock.yaml` before pnpm runs and puts them back when pnpm fails, when the run is cancelled, or when the package pnpm added declares no bundle patch. This reverses, for installations only, the [manager's decision](2026-09-14-current-profile-plugin-management.md) to retain partial changes: an installation that did not produce a usable bundle must not leave a dependency the page cannot show. Removals keep that decision. Downloaded files can stay under `node_modules` and the pnpm store. -**A failed run is classified where the facts are.** `classifyInstallFailure` reads how the run ended and what pnpm printed — its `ERR_PNPM_*` codes and Node's errno names — into `packageResult.kind`. A run the manager terminated is classified `timeout` whatever exit status the signal left behind, so installation restores the files and removal reports failure instead of reading it as a success ([run bounds](../../../../packages/boot/plugin-manager/README.md)). The client shows the kind as one line and folds pnpm's output behind the details. Parsing the log is confined to this one function with a fixture-driven test. +**A failed run is classified where the facts are.** `classifyInstallFailure` reads how the run ended and what pnpm printed — its `ERR_PNPM_*` codes and Node's errno names — into `packageResult.kind`. A run the manager terminated is classified `timeout` whatever exit status the signal left behind, so installation restores the files and removal reports failure instead of reading it as a success ([run bounds](../../../../packages/boot/plugin-manager/README.md)). The client shows the kind as one line and folds pnpm's output behind the details, which also name the complete log and a failure that stopped before pnpm ran ([details](../bug-fix/2026-10-28-plugin-install-failure-diagnostics.md)). Parsing the log is confined to this one function with a fixture-driven test. **GitHub connection failures have a short budget before installation.** The Host runs a read-only `git ls-remote` check with the profile's Git and proxy configuration and a default `githubConnectionTimeoutMs` of 5000 ms. Credential helpers and prompts are disabled for this check, so authentication cannot consume the connection budget. Only network failures and timeouts prevent pnpm from starting; pnpm still owns authentication, HTTPS-to-SSH fallback, ref resolution and the full installation. The budget does not limit downloads or builds. The existing failure kind and `failedAt: 'spec-host'` let the Client show a connection error or timeout and offer a domestic registry for a replacement package spec. Cancellation and manager disposal terminate the check and its descendants before settling. diff --git a/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.zh.md b/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.zh.md index c53c138059..09c2c2e572 100644 --- a/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.zh.md @@ -14,7 +14,7 @@ Status: implemented **失败或被取消的安装恢复 profile 文件。** `installBundle` 在 pnpm 运行前快照 `package.json` 与 `pnpm-lock.yaml`，在 pnpm 失败、运行被取消、或 pnpm 装入的包没有声明组合包 patch 时把它们放回去。这只针对安装反转了[管理器的决定](2026-09-14-current-profile-plugin-management.zh.md)中"保留部分改动"的部分：没有产出可用组合包的安装，不能留下一个页面无法显示的依赖。删除仍沿用那个决定。已下载文件可能留在 `node_modules` 与 pnpm 缓存中。 -**失败在事实所在处分类。** `classifyInstallFailure` 依据运行的结束方式和 pnpm 的输出——它的 `ERR_PNPM_*` 码和 Node 的 errno 名——给出 `packageResult.kind`。被管理器终止的运行，不论信号留下什么退出状态都归类为 `timeout`，因此安装会还原文件，删除则报告失败而不会读成成功（[运行上界](../../../../packages/boot/plugin-manager/README.zh.md)）。客户端把 kind 显示成一句话，把 pnpm 输出折叠进详情。对日志的解析只存在于这一个函数，用夹具驱动的测试钉住。 +**失败在事实所在处分类。** `classifyInstallFailure` 依据运行的结束方式和 pnpm 的输出——它的 `ERR_PNPM_*` 码和 Node 的 errno 名——给出 `packageResult.kind`。被管理器终止的运行，不论信号留下什么退出状态都归类为 `timeout`，因此安装会还原文件，删除则报告失败而不会读成成功（[运行上界](../../../../packages/boot/plugin-manager/README.zh.md)）。客户端把 kind 显示成一句话，把 pnpm 输出折叠进详情；详情还会指出完整日志，以及尚未运行 pnpm 就停下的一次失败（[详情](../bug-fix/2026-10-28-plugin-install-failure-diagnostics.zh.md)）。对日志的解析只存在于这一个函数，用夹具驱动的测试钉住。 **GitHub 连接失败在安装前有单独的短时限。** 宿主通过只读的 `git ls-remote` 检查连接，沿用 profile 的 Git 与代理配置，`githubConnectionTimeoutMs` 默认为 5000 毫秒。这次检查禁用凭据助手和认证提示，避免认证过程占用连接预算。只有网络失败与超时会阻止 pnpm 启动；认证、HTTPS 到 SSH 的回退、ref 解析及完整安装仍由 pnpm 负责。时限不约束下载或构建。已有的失败类型与 `failedAt: 'spec-host'` 让客户端显示连接失败或超时，并提供国内镜像供用户输入另一个包名。取消安装或销毁管理器会先终止检查及其子进程，再结束操作。 diff --git a/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.i18n.yaml index fae09a79ee..8d1fed4a2e 100644 --- a/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.i18n.yaml @@ -15,8 +15,8 @@ en: eced414858f08ef9 zh: 40639593b0d5bb6f /agent-note-fatal-diagnostics-and-desktop-crash-reports/relationship-to-the-desktop-logging-design: - en: 7dc438912d10574a - zh: 07d05f9f17043d67 + en: ca4a912437c7b02e + zh: 2c7953ce5e8c196f /agent-note-fatal-diagnostics-and-desktop-crash-reports/testing: en: 864a8e71e3b3378b zh: a71807db24d9409c diff --git a/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.md b/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.md index 0cf5f64b89..541d22b228 100644 --- a/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.md +++ b/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.md @@ -32,7 +32,7 @@ This partially supersedes the [native Desktop fatal recovery](2026-09-15-desktop ## Relationship to the Desktop logging design -The Desktop local logging design (a Worker-owned rolling JSONL log with a closed event vocabulary, redaction, and rate limits) is a continuous-log design and remains future work. It stated that Host stderr and renderer console output are never persisted and that errors reach the log only as fixed categories. This decision carves out one exception: the one-time crash report of a fatal failure keeps the raw error and the retained stderr and console tails, because that raw content is what both field diagnoses needed and the report is bounded (the error section is cut at 256 KiB, the Host diagnostic at 64 KiB, the renderer console tail at 64 KiB), local, owner-only, and written only when the application is already showing its fatal dialog. The dialog names the file so a user knows what they would be sharing. The continuous-log privacy posture is unchanged for anything that is not a crash report. +Desktop continuously persists a bounded plugin-management journal with whitelisted facts, two rotating segments and a bounded write queue; its budgets and failure guarantees belong to the [Desktop README](../../../../apps/desktop/README.md). It excludes raw installation specs, error text and package-manager output. The broader Worker-owned continuous log remains deferred. Fatal crash reports independently retain raw errors and bounded stderr and renderer-console tails because these contain the field-diagnosis evidence; files are local and owner-only where supported. An isolated Worker appends bounded management history after the basic report is saved, preserving access to the basic report when collection fails or is still running. Recent operations provide context, not causal attribution. ## Testing diff --git a/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.zh.md b/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.zh.md index c3513bbddd..045134bb2e 100644 --- a/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-22-fatal-diagnostics-and-crash-reports.zh.md @@ -32,7 +32,7 @@ macOS 上，启动审计把一组 Web 客户端行列为 `import failed (see con ## 与 Desktop 日志体系设计的关系 -Desktop 本地日志设计（Worker 独占写入的滚动 JSONL 日志、封闭事件词汇、脱敏与限流）是持续日志设计，仍是未来工作。它规定 Host stderr 与渲染进程 console 输出永不持久化、错误只以固定分类进入日志。本决定划出一个例外：致命失败的一次性崩溃报告保留原始错误以及保留的 stderr 与 console 尾部，因为两次现场定位需要的正是这些原始内容，而报告有界（error 段截至 256 KiB、Host 诊断 64 KiB、渲染进程 console 尾部 64 KiB）、本地、仅所有者可读，且只在应用已经弹出致命对话框时写入。对话框标明文件名，用户知道自己会分享什么。任何非崩溃报告的内容仍遵循持续日志的隐私姿态。 +Desktop 持续保存有界的插件管理日志，使用事实白名单、两个轮换文件段和有界写入队列；预算及失败保障由 [Desktop README](../../../../apps/desktop/README.zh.md) 定义。日志不包含原始安装 spec、错误文本或包管理器输出。更广泛的 Worker 独占持续日志仍属延期工作。致命崩溃报告独立保留原始错误以及有界的 stderr 和渲染进程 console 尾部，因为这些内容包含现场定位证据；文件保存在本地，并在平台支持时仅所有者可读。独立 Worker 在基本报告保存后追加有界管理历史，收集失败或尚未结束时仍可获取基本报告。近期操作提供上下文，不构成因果归因。 ## Testing diff --git a/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.i18n.yaml index 615a8d43cf..9ed59785ea 100644 --- a/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.i18n.yaml @@ -9,11 +9,11 @@ en: e42db40b879fdbf4 zh: 6017da9c4da17835 /agent-note-node-ptc-execution-modes-and-in-memory-state/decision: - en: d2d08c54c6520f02 - zh: 520a9b3421ff5c65 + en: 7b5808a31493ac1e + zh: 8d9c698c41dbf18e /agent-note-node-ptc-execution-modes-and-in-memory-state/alternatives-considered: en: 396157a9fc293198 zh: a061f05b4423e26f /agent-note-node-ptc-execution-modes-and-in-memory-state/consequences: - en: 9b9172f4aafe907f - zh: 022a6bd52d7caf05 + en: 56fa39e2958afdff + zh: d04f539437d0c00d diff --git a/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.md b/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.md index 153a63b87e..fac34c9f7f 100644 --- a/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.md +++ b/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.md @@ -12,7 +12,7 @@ Interactive automation retains application objects, imported modules and helper The existing `@deepseek-ai/dsh-ptc-runtime-node` plugin selects its execution mode through `executionMode`. The default `per-call` mode starts a fresh process under the configured file policy. Opt-in `persistent-in-memory` mode keeps a Node REPL process per explicit, object-identity state owner. Both modes provide the same `ctx.ptcRuntime` service. PTC uses the live Agent as owner and awaits release during its context disposal. Changing the configuration reloads the provider and releases its processes. The [sandboxed Node decision](2026-09-11-sandboxed-node-ptc-runtime.md) owns per-call confinement; the [PTC foundation](../feature/2026-06-15-ptc.md) owns tool dispatch and logged model requests. -Mode names describe state retention rather than a process implementation or source syntax. `per-call` retains state for one invocation; `persistent-in-memory` retains it across invocations until the process or owner ends. `durable` names the deferred ability to save and restore execution state across restarts. It is not an accepted configuration value: a future implementation must define its recovery point, recoverable values and external-resource handling before exposing that mode. The [retained-process permission decision](2026-10-08-persistent-ptc-sandbox.md) owns confinement, policy changes and temporary escalation. +The `per-call` and `persistent-in-memory` names describe their fixed state-retention policies: one invocation or across invocations until the process or owner ends. The [Script evaluation decision](2026-10-20-ptc-script-evaluation-and-retention.md) extends these modes with independently configured syntax and retention. `durable` names the deferred ability to save and restore execution state across restarts. It is not an accepted configuration value: a future implementation must define its recovery point, recoverable values and external-resource handling before exposing that mode. The [retained-process permission decision](2026-10-08-persistent-ptc-sandbox.md) owns confinement, policy changes and temporary escalation. One npm package and one plugin entry keep existing installation and loading paths stable. Communication, binding proxies, JSON encoding and output limits remain package-local modules. The Node provider delegates retained process ownership to an internal execution object, which registers no additional Cordis service. Per-call and in-memory execution keep their distinct lifecycle rules. `programFormat` describes source evaluation independently of retention: a REPL need not retain state. The runtime owns syntax, completion and retention instructions through `executionInstructions`; tools own call arguments, SDK declarations and image attachment. Workflow uses `programFormat` to wrap its program and refuses restricted file policies when the selected runtime cannot enforce them. @@ -34,4 +34,4 @@ A realm inside the Harness process shares process lifetime with model code and c Selecting `persistent-in-memory` retains execution state; the [permission decision](2026-10-08-persistent-ptc-sandbox.md) defines its file restrictions. Nested tools keep their normal authorization and logging. Memory and native handles may disappear without a Harness restart. The model must recover from reference or resource errors; the runtime never retries a program automatically. -An idle owner retains a process with no expiration timer. Callers release owners explicitly; ownerless service calls use temporary processes. Programs use REPL statements and a final expression rather than top-level return, and calls for one retained owner cannot overlap. Tool schemas and program guidance follow the selected mode. +An idle owner retains a process with no expiration timer. Callers release owners explicitly; ownerless service calls use temporary processes. The `persistent-in-memory` mode uses REPL statements and a final expression rather than top-level return, and calls for one retained owner cannot overlap. Tool schemas and program guidance follow the selected mode. diff --git a/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.zh.md b/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.zh.md index a4c4a52828..93959fe07a 100644 --- a/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-23-best-effort-persistent-ptc.zh.md @@ -12,7 +12,7 @@ Status: implemented 现有 `@deepseek-ai/dsh-ptc-runtime-node` 插件通过 `executionMode` 选择执行模式。默认的 `per-call` 模式按配置的文件策略启动新进程。显式启用的 `persistent-in-memory` 模式为每个以对象身份标识的状态所有者保留一个 Node REPL 进程。两种模式都提供同一个 `ctx.ptcRuntime` 服务。PTC 使用存活的 Agent 作为所有者，在其上下文销毁时等待释放。修改配置会重载提供方并释放其进程。[Node 沙箱决策](2026-09-11-sandboxed-node-ptc-runtime.zh.md)负责逐次执行的文件约束，[PTC 基础决策](../feature/2026-06-15-ptc.zh.md)负责工具分派与模型请求日志。 -模式名称描述状态保留方式，不绑定进程实现或代码语法。`per-call` 只为一次调用保留状态；`persistent-in-memory` 跨调用保留状态，直到进程或所有者结束。`durable` 用于命名未来跨重启保存与恢复执行状态的能力。它不是可接受的配置值：实现必须先明确恢复点、可恢复的值以及外部资源的处理方式，才能公开这个模式。[常驻进程权限决策](2026-10-08-persistent-ptc-sandbox.zh.md)负责文件约束、权限切换与临时提权。 +`per-call` 和 `persistent-in-memory` 名称描述各自固定的状态保留策略：只保留一次调用，或跨调用保留至进程或所有者结束。[Script 求值决策](2026-10-20-ptc-script-evaluation-and-retention.zh.md)在这两种模式之外增加独立配置的语法与保留方式。`durable` 用于命名未来跨重启保存与恢复执行状态的能力。它不是可接受的配置值：实现必须先明确恢复点、可恢复的值以及外部资源的处理方式，才能公开这个模式。[常驻进程权限决策](2026-10-08-persistent-ptc-sandbox.zh.md)负责文件约束、权限切换与临时提权。 一个 npm 包和一个插件入口保持现有安装与加载路径稳定。通信、绑定代理、JSON 编码和输出限制继续作为包内模块复用。Node 提供方将保留进程的所有权交给内部执行对象，该对象不注册额外的 Cordis 服务。逐次执行和内存保留各自管理不同的生命周期。`programFormat` 描述代码求值形式，与状态保留独立：REPL 不必跨调用保留状态。运行时通过 `executionInstructions` 负责语法、完成值和状态保留指引；工具层负责调用参数、SDK 声明和图片附加。工作流根据 `programFormat` 包装程序；所选运行时无法执行受限文件策略时，工作流拒绝执行。 @@ -34,4 +34,4 @@ Harness 进程内的独立执行上下文与模型代码共享进程生命周期 选择 `persistent-in-memory` 会保留执行状态；[权限决策](2026-10-08-persistent-ptc-sandbox.zh.md)定义其文件限制。嵌套工具仍遵循原有授权和日志规则。即使 Harness 没有重启，内存和原生句柄也可能丢失。模型需要从引用或资源错误中恢复，运行时不会自动重试程序。 -空闲所有者保留一个没有过期计时器的进程。调用方显式释放所有者，没有所有者的服务调用使用临时进程。程序使用 REPL 语句和末尾表达式，不支持顶层 return；同一保留所有者的调用不能重叠。工具 schema 和程序指引跟随所选模式。 +空闲所有者保留一个没有过期计时器的进程。调用方显式释放所有者，没有所有者的服务调用使用临时进程。`persistent-in-memory` 模式使用 REPL 语句和末尾表达式，不支持顶层 return；同一保留所有者的调用不能重叠。工具 schema 和程序指引跟随所选模式。 diff --git a/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.i18n.yaml index 2f89f011b6..03e2dc829a 100644 --- a/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.i18n.yaml @@ -9,11 +9,11 @@ en: b32a7ce6483b9b48 zh: ec0938ad032b99d8 /agent-note-application-consent-for-native-computer-use/decision: - en: 36c560c24c376f12 - zh: 5e4ff72f66574e38 + en: b34d24e39879277e + zh: 03363665d4682ddb /agent-note-application-consent-for-native-computer-use/alternatives-considered: - en: 80cd5fd93a42d937 - zh: 2a0e241b1b8c2e1d + en: 18b2c124f1d4e601 + zh: 621a6c9512d5612b /agent-note-application-consent-for-native-computer-use/consequences: en: 4bda3366af65250a zh: 7c83561b4db07284 diff --git a/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.md b/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.md index 389a994714..84cfd7fe65 100644 --- a/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.md +++ b/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.md @@ -10,17 +10,15 @@ macOS privileges authorize an execution host, not a user's choice of target appl ## Decision -The CUA executor owns application consent for every object-API and native-tool dispatch. It uses the existing User Questions service for human decisions and the provider's existing profile configuration for saved grants. The existing question UI presents the offered labels; the executor rejects custom text or answers that do not select exactly one offered label. Permission-page icons and names are presentation metadata, excluded from saved identities and model results. General tool approval and operating-system privileges remain separate requirements. Arbitrary persistent PTC code and separately authorized shell tools retain their own execution authority. +The CUA executor owns application consent for every object-API and native-tool dispatch. It uses the existing User Questions service for human decisions and profile-scoped domain storage for saved grants. Its fixed approval presentation reuses the tool-approval card without adopting the session's tool-approval policy. Native icons and names are presentation metadata, excluded from saved identities and model results. General tool approval and operating-system privileges remain separate requirements. Arbitrary persistent PTC code and separately authorized shell tools retain their own execution authority. System-permission buttons call the native helper on the DSH host and remain available to remote browsers. The [usage documentation](../../../../packages/experimental/cua/README.md#use-this-package) explains where to complete authorization; the page has no persistent remote-access notice. -A saved identity combines the canonical executable path with a verified designated signing requirement, represented by a SHA-256 digest. The path prevents authorization from following a copied application, and the signing requirement distinguishes replacements while allowing matching signed updates. Unverifiable and ad-hoc applications receive session access only, tied to a process instance. Labels do not establish identity. +Application identity is owned by [bundle-ID consent](2026-10-25-cua-bundle-id-consent.md), which supersedes this note's original path/signature choice. That original choice prevented copied or replaced applications from inheriting access, at the cost of separate grants per installation and no saved grants for unsigned applications. Enforcement and human decision ownership remain as described here. -Cold application selection prepares an executable identity and handle without launching. The same consent decision guards the private launch continuation, and the helper checks the executable again before launch and binds the resulting process afterward. Signed selections retain the normal designated-requirement identity; an unverifiable executable uses a content identity for this pending selection and cannot create a saved grant. Preparing metadata before asking avoids starting an application the user refuses. +Cold application selection prepares an executable identity and handle without launching. The same consent decision guards the private launch continuation, and the helper checks the executable again before launch and binds the resulting process afterward. Selections with a bundle identifier retain that identity after launch; an application without one uses its canonical executable path before and after launch and can save that grant. Preparing metadata before asking avoids starting an application the user refuses. -Session decisions are kept in memory by Session ID and application identity. Agent disposal and helper replacement release native handles without discarding these decisions; provider disposal or DSH restart clears them. This scope covers follow-up turns without relying on the model to decide when a user intent has ended. - -Selections of the same application within one session are serialized, so a pending question does not produce competing decisions. Saved-grant additions and revocations share one mutation queue and read the current grant list inside it. Provider shutdown cancels writes still waiting for HMR admission; admitted writes settle before disposal completes. Refusals prevent another prompt until the user permits asking again; a restored saved grant takes precedence in both dispatch and the permission-page projection. +Conversation decisions survive provider disposal and DSH restart according to [profile consent storage](2026-10-19-cua-profile-consent-storage.md). That decision owns persistence, migration and cross-process revocation. The executor continues to serialize application selections within a conversation, refuse repeated prompts after denial, and give an explicit long-term grant precedence over conversation refusals. Revocation invalidates the Agent connections that retain the application's handles, then awaits native cleanup. Reauthorization uses a fresh connection, so old app and window snapshots cannot become valid again. The [native object decision](2026-09-17-experimental-cua-object-api.md) continues to own process identity, coordinate semantics, and separation from the evaluator. @@ -28,9 +26,9 @@ Revocation invalidates the Agent connections that retain the application's handl **Trust model instructions or hide controls.** Retained objects and direct tool calls can still reach native operations. The executor must enforce the decision at dispatch. -**Persist application names or unsigned paths.** A replacement can reuse both. Durable grants require a verifiable signing identity; session access supports unsigned development applications without that promise. +**Persist application names or unsigned paths.** A replacement can reuse both. [Bundle-ID consent](2026-10-25-cua-bundle-id-consent.md) owns the identity choices and the decision to share permission between installations. -**Add an approval database or Session control stream.** Profile settings already own user configuration, and User Questions already owns interactive answers. The permission UI observes the provider and its owning settings namespace without another authorization store or event channel. +**Add an approval database or Session control stream.** User Questions already owns interactive answers. The existing domain service provides durable state without introducing a dedicated database or Session control stream; storage tradeoffs are owned by the profile consent decision. **Disable permission buttons based on the browser address.** A user may operate the DSH host through screen sharing and complete authorization there. Port forwarding and proxies make the address an unreliable indication of whether the browser and DSH run on the same computer. diff --git a/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.zh.md b/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.zh.md index e7311dfc6d..17590a47c0 100644 --- a/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-26-cua-application-consent.zh.md @@ -10,17 +10,15 @@ macOS 权限授权执行宿主，不能表达用户允许操作哪些目标应 ## 决策 -CUA 执行器在每次对象 API 和原生工具调用时检查应用授权。人工决定复用 User Questions 服务，长期许可保存在 provider 的现有 profile 配置中。通用工具审批和操作系统权限仍是独立要求。任意 persistent PTC 代码和另行授权的 shell 工具保留各自的执行权限。现有问答界面展示授权选项；执行器拒绝自由文本或未准确选中一个所给选项的回答。权限页图标和名称仅用于展示，不进入保存的身份信息或模型结果。 +CUA 执行器在每次对象 API 和原生工具调用时检查应用授权。人工决定复用 User Questions 服务，长期许可保存在按 profile 隔离的存储域中。通用工具审批和操作系统权限仍是独立要求。任意 persistent PTC 代码和另行授权的 shell 工具保留各自的执行权限。 固定审批呈现复用工具审批卡片，同时保留独立于会话工具审批策略的授权规则。本机图标和名称仅用于展示，不进入保存的身份信息或模型结果。 系统权限按钮调用运行 DSH 的电脑上的原生 helper，远程访问时仍可使用。授权地点写在[使用说明](../../../../packages/experimental/cua/README.zh.md#use-this-package)中，页面不常驻远程访问提示。 -长期身份由规范化可执行文件路径和经过验证的签名指定要求组成，以 SHA-256 摘要表示。路径阻止许可跟随应用副本，签名要求区分替换程序，并允许符合相同签名要求的更新。签名不可验证或使用 ad-hoc 签名的应用只能获得会话授权，许可绑定进程实例。显示名称不用于确定身份。 +应用身份由[Bundle ID 授权](2026-10-25-cua-bundle-id-consent.zh.md)负责，取代本记录原先的路径和签名选择。原选择防止应用副本或替换程序继承许可，代价是各安装副本必须分别授权，未签名应用无法保存长期许可。执行检查和用户决定的所有权仍由本记录规定。 -选择尚未运行的应用时，先准备可执行文件身份和句柄，不立即启动。同一授权决定保护内部启动续接，helper 在启动前再次核对可执行文件，并在启动后绑定实际进程。已签名应用沿用签名指定要求身份；签名不可验证的程序使用本次待启动选择的内容身份，不能生成长期许可。先准备元数据再询问，可以避免启动用户拒绝的应用。 +选择尚未运行的应用时，先准备可执行文件身份和句柄，不立即启动。同一授权决定保护内部启动续接，helper 在启动前再次核对可执行文件，并在启动后绑定实际进程。有 Bundle ID 的应用在启动后沿用该身份；没有 Bundle ID 的程序在启动前后使用规范化可执行路径，并可保存该许可。先准备元数据再询问，可以避免启动用户拒绝的应用。 -会话决定按 Session ID 和应用身份保存在内存中。Agent 销毁或 helper 重建会释放原生句柄，但保留授权决定；提供方卸载或 DSH 重启后清除。会话范围可以覆盖用户的后续指令，无须由模型判断一次用户意图何时结束。 - -同一会话对同一应用的选择串行执行，避免未完成的问题产生相互冲突的决定。长期许可的新增和撤销共用写入队列，并在队列内读取当前许可列表。提供方关闭时取消尚在等待 HMR 调度的写入，已开始的写入会在销毁完成前结束。拒绝会阻止再次询问，直到用户允许重询；重新添加的长期许可在执行检查和权限页中均优先于旧拒绝记录。 +会话决定按[profile 授权存储](2026-10-19-cua-profile-consent-storage.zh.md)的规则，在提供方卸载和 DSH 重启后保留。该记录负责持久化、迁移和跨进程撤销。执行器继续将同一对话对同一应用的选择串行化，拒绝后不再次询问，显式长期许可优先于会话拒绝。 撤销使保留目标应用句柄的 Agent 连接失效，并等待原生清理完成。重新授权使用新连接，因此旧应用对象和窗口快照不能重新生效。[原生对象决策](2026-09-17-experimental-cua-object-api.zh.md)继续负责进程身份、坐标语义和与执行器分离的设计。 @@ -28,9 +26,9 @@ CUA 执行器在每次对象 API 和原生工具调用时检查应用授权。 **依赖模型指引或隐藏控件。** 保留的对象和直接工具调用仍能到达原生操作。执行器必须在派发时检查用户决定。 -**保存应用名称或未签名路径。** 替换程序可以复用二者。长期许可需要可验证的签名身份；会话授权支持未签名的开发应用，但不承诺跨进程复用。 +**保存应用名称或未签名路径。** 替换程序可以复用二者。身份选择和在安装副本之间共用许可的决定由[Bundle ID 授权](2026-10-25-cua-bundle-id-consent.zh.md)负责。 -**新增审批数据库或 Session 控制流。** Profile settings 已负责用户配置，User Questions 已负责交互回答。权限界面查询 provider，并监听其配置 namespace，无须另一份授权存储或事件通道。 +**增加审批数据库或 Session 控制流。** User Questions 已经负责交互式回答。现有域服务提供持久状态，无须增加专用数据库或 Session 控制流；存储取舍由 profile 授权存储决策负责。 **根据浏览器访问地址禁用权限按钮。** 用户可能通过屏幕共享操作运行 DSH 的电脑，并在该电脑上完成授权。端口转发和代理使访问地址无法可靠判断浏览器与 DSH 是否运行在同一台电脑上。 diff --git a/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.i18n.yaml index 04a53081d6..dc596b4fae 100644 --- a/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.i18n.yaml @@ -9,8 +9,8 @@ en: 386864a282e5ad58 zh: a4ea75ec70eb7778 /agent-note-shared-native-cua-process-with-agent-scoped-state/decision: - en: ebf231a6aad109bb - zh: 53b553e679569da1 + en: 11bab6870c3d802f + zh: a22114f2217a3a41 /agent-note-shared-native-cua-process-with-agent-scoped-state/alternatives-considered: en: 883f71387f599160 zh: 4b5f1450be799397 diff --git a/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.md b/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.md index 1bc795dd52..8e986aaa2f 100644 --- a/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.md +++ b/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.md @@ -12,6 +12,8 @@ On macOS 26.6.2, replayd derives capture-client identity from the executable pat One user shares a native service per executable content digest across Agents and Hosts. A version lock elects the service; an additional canonical-executable-path lock prevents different builds published at one path from running together. Locks remain held until process exit. The managed startup command hands service lifetime to its client connections, and the last connection's completed cleanup ends the service. The diagnostic stdin/stdout entry proxies to this same service. +The service runs as a signed application launched through LaunchServices. Directly spawning the executable inherits its launcher’s TCC responsibility, so it cannot give the helper independent system permissions. A launch lock serializes discovery and startup. Complete signed applications use immutable content-addressed directories: replacing an executable used by a live process would violate both path-lock ownership and code-signature integrity. Ad-hoc builds can require fresh grants when their code hash changes; a stable bundle identifier alone does not preserve those grants. Installed packages retain their distributed signatures. + Each Agent connection owns its application handles, AX snapshots, limits and cancellation state. An app handle grants no exclusive use of the application. A FIFO orders complete desktop operations, including clipboard transactions, while response writes are independent. Agent disposal retires only its connection. The [object API decision](2026-09-17-experimental-cua-object-api.md) retains evaluator independence and coordinate semantics; the [consent decision](2026-09-26-cua-application-consent.md) retains application authorization. Cancellation and timeout first stop one request and wait for acknowledgement. A timed-out screenshot retains the single system-RPC slot until the real callback completes; new screenshots fail with `CAPTURE_BUSY` instead of accumulating requests. Late pixels are discarded, while other AX and input operations remain available. Ending an await or creating a wrapper does not prove that the system connection has recovered. An operation or cleanup that cannot stop can invalidate the process, making every old handle unusable. Uncertain input is never replayed automatically. diff --git a/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.zh.md b/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.zh.md index c40d277837..371ae5cc3a 100644 --- a/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.zh.md +++ b/.agents/notes/implemented/architecture/2026-10-09-cua-shared-native-helper.zh.md @@ -12,6 +12,8 @@ Status: implemented 同一用户的多个 Agent 和 Host 按可执行文件内容摘要共享原生服务。版本锁选出服务实例，规范化可执行路径上的另一把锁阻止发布在同一路径的不同构建同时运行。进程退出才释放锁。受管启动命令将服务生命期交给客户端连接，最后一条连接清理完成后服务退出。诊断用 stdin/stdout 入口也代理到同一个服务。 +服务通过 LaunchServices 以已签名应用运行。直接启动可执行文件会继承启动器的 TCC 责任，无法让 helper 独立取得系统权限。启动锁串行处理发现与启动。完整签名应用保存在不可变的内容寻址目录中，替换运行中进程的可执行文件会破坏路径锁的归属与代码签名完整性。临时签名构建的代码哈希变化后可能需要重新授权，固定 Bundle ID 不能保证保留授权。安装版保留分发时的签名。 + 每条 Agent 连接独立持有应用句柄、AX 快照、资源限制和取消状态。持有 app 句柄不代表独占应用。FIFO 队列串行执行包含剪贴板事务的完整桌面操作，响应写入独立进行。Agent 销毁只释放自己的连接。[对象接口决策](2026-09-17-experimental-cua-object-api.zh.md)继续负责执行器独立性及坐标语义，[授权决策](2026-09-26-cua-application-consent.zh.md)继续负责应用许可。 取消或超时先停止单次请求并等待确认。截图超时后，唯一的系统 RPC 槽位保留到真实回调结束；新截图返回 `CAPTURE_BUSY`，不继续堆积请求。迟到图片被丢弃，其他 AX 与输入操作仍可执行。结束 await 或创建包装对象不能证明系统连接已恢复。操作或清理无法停止时，才可能使进程失效，届时所有旧句柄均不可用。结果不确定的输入不会自动重放。 diff --git a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml index a644575d18..4cf8989458 100644 --- a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml @@ -36,8 +36,8 @@ en: d50ae22978165c57 zh: 8c1fcfb7dc2d3367 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/endpoint-resources: - en: 056a141b31270cba - zh: 3f6caafb3a13c192 + en: 582f5f527ecc58c8 + zh: 4a4b68361de2dcf0 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/roles-bindings-and-policies-deepseek-ai-dsh-api-remote-access: en: e57f396239ea9f56 zh: ddb26278b1521ceb diff --git a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md index 6b1cc15750..7c13d393f3 100644 --- a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md +++ b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md @@ -241,7 +241,7 @@ The table lists the endpoints #3854 viewers use and where their resources come f | `llm/listProviders` | `global` | no resource | no | | `commands/list` | session: `args.agentId` (the Agent lookup's wire field) | Agent lookup `resource: 'session'` | no | | `goals/get` | session: `args.agentId` | Agent lookup `resource: 'session'` | no | -| `session/attachment` | session: `args.request.sessionId` | default resolver | no | +| `session/attachment` | session: `args.request.sessionId` | default resolver | no: a grant on one Session permits reads from the whole attachment store | | `skills/list` | session: `args.request.sessionId` | default resolver | no | | `session/fork` | session: `args.request.sessionId` | default resolver | no | | `session/prompt` | session: `args.request.sessionId` | default resolver | no | @@ -251,6 +251,8 @@ The table lists the endpoints #3854 viewers use and where their resources come f | `session/follow` | same as above | default resolver | no | | `remoteAccess/follow` | `global` | no resource; remote-access allows it for every principal | no | +For `session/attachment`, `sessionId` identifies the resource for the Gateway check; it does not constrain which image may be read. Once that check permits the call, an image may belong to another Session or no Session, and the handler does not check whether the supplied Session exists. Policy authors must treat this action as access to the whole attachment store, as defined by the [image access rule](2026-10-23-store-scoped-image-reads.md). + A subagent address reads the child transcript, so its resource is the child Session. A Client rereads the projections of known Sessions after a reconnect, including the parent of a subagent Session; a reader without a grant on that parent has its projection read refused. Whether a grant on a parent Session covers its subagent children is the policy's decision, that is, whether it gives a binding for the child Session; the generic layer derives no parent resource. Methods that need no non-owner access declare nothing, and a method no role lists is refused. The request fields of subagent `prompt` are `parentSessionId` / `childSessionId`, so automatic resolution finds no Session and resolves it to `global`; it must therefore stay out of every `global` role. `session/search` filters its hits per Session inside the method. `subagents/list` is not a Remote endpoint (`SubagentRuntime.list()` carries no `@Remote`). diff --git a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md index 00e418b8c7..9503b430aa 100644 --- a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md +++ b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md @@ -241,7 +241,7 @@ export function RemoteScope | `llm/listProviders` | `global` | 无资源 | 否 | | `commands/list` | session：`args.agentId`（Agent lookup 的 wire 字段） | Agent lookup `resource: 'session'` | 否 | | `goals/get` | session：`args.agentId` | Agent lookup `resource: 'session'` | 否 | -| `session/attachment` | session：`args.request.sessionId` | 默认 resolver | 否 | +| `session/attachment` | session：`args.request.sessionId` | 默认 resolver | 否：一条 Session 上的授权允许读取整个附件存储 | | `skills/list` | session：`args.request.sessionId` | 默认 resolver | 否 | | `session/fork` | session：`args.request.sessionId` | 默认 resolver | 否 | | `session/prompt` | session：`args.request.sessionId` | 默认 resolver | 否 | @@ -251,6 +251,8 @@ export function RemoteScope | `session/follow` | 同上 | 默认 resolver | 否 | | `remoteAccess/follow` | `global` | 无资源；remote-access 对任何 principal 放行 | 否 | +对于 `session/attachment`，`sessionId` 指定 Gateway 检查的资源，不限制可读取哪张图片。该检查放行后，图片可以属于其他 Session 或不属于任何 Session，处理函数也不检查请求中的 Session 是否存在。policy 作者必须把此 action 视为整个附件存储的读取权限，具体规则见[图片访问规则](2026-10-23-store-scoped-image-reads.zh.md)。 + subagent 地址读取的是子会话转录，因此其资源是子会话。Client 在重连后会重新读取已知会话的 projections，其中包括 subagent 会话的父会话；没有该父会话授权的读者，其 projection 读取被拒。父会话的授权是否覆盖其 subagent 子会话由 policy 决定，即是否为子会话给出 binding；通用层不推导父资源。 不需要非 owner 访问的方法不做任何声明，没有 role 列出它即被拒。subagent `prompt` 的请求字段为 `parentSessionId` / `childSessionId`，自动解析不到会话，解析为 `global`，因此不得放进任何 `global` 级 role；`session/search` 在方法内按会话逐项过滤命中。`subagents/list` 不是 Remote 端点（`SubagentRuntime.list()` 未标 `@Remote`）。 diff --git a/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.i18n.yaml new file mode 100644 index 0000000000..d95e587c31 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-19-cua-profile-consent-storage.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 .agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.md +/agent-note-durable-computer-use-consent-within-one-profile: + en: b2aa270d586efd93 + zh: 99606fa28dc4a752 +/agent-note-durable-computer-use-consent-within-one-profile/problem: + en: f2c70036a57ddb41 + zh: 9bbbf3dd09d486f5 +/agent-note-durable-computer-use-consent-within-one-profile/decision: + en: 11622523090f5d88 + zh: 1d0f8ad94645f069 +/agent-note-durable-computer-use-consent-within-one-profile/alternatives-considered: + en: 2af74afa3ecaf3b9 + zh: 96f7f43c5d1150df +/agent-note-durable-computer-use-consent-within-one-profile/consequences: + en: 66fe232589e46d64 + zh: fc69831be76248d9 diff --git a/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.md b/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.md new file mode 100644 index 0000000000..c70651899c --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.md @@ -0,0 +1,31 @@ +# Agent Note: Durable Computer Use consent within one profile + +Status: implemented + +English | [中文](2026-10-19-cua-profile-consent-storage.zh.md) + +## Problem + +Application grants stored as plugin configuration make each authorization change depend on configuration reconciliation. Process-local conversation decisions also disappear when the same conversation resumes after a restart. A shared in-memory storage handle cannot observe another process revoking permission. + +## Decision + +The CUA owner uses the existing domain storage service, with one domain per canonical profile directory. It stores long-term grants and conversation decisions by native application identity. Conversation IDs scope permission without turning it into permission for every conversation. The native identity policy remains owned by [bundle-ID consent](2026-10-25-cua-bundle-id-consent.md); this note replaces only that note's storage and restart-lifetime choices. + +Every operation opens fresh domain state while holding the profile's existing file-lock primitive and closes the domain before releasing the lock. Native dispatch and revocation use a separate lock for the selected application. Storage reads and unrelated applications remain available during a native call. Revocation cancels this process's affected work first, then commits after other processes' already-admitted operations have finished. A completed revocation therefore leaves no operation using the old authority. App-wide revocation generations and per-conversation decision revisions prevent an old handle or delayed answer from restoring revoked access. + +The JSON backend remains the shipped default. The domain name contains the SHA-256 digest of the canonical profile directory, isolating profiles that share one storage root. Legacy `allowedApps` is imported once; a persisted migration marker prevents an old configuration from restoring a revoked grant. Users can remove that configuration after checking the migrated list. Corrupt or unavailable profile storage fails closed. A composition without a profile has only temporary conversation state. + +## Alternatives considered + +**Keep authorization in configuration.** It preserves existing storage but retains configuration-write and HMR coupling for runtime application decisions. + +**Keep one domain open and rely on change events.** Domain notifications are process-local. Another host could continue to use stale grants after revocation. + +**Add a new watcher, revision file or authorization broker.** The existing domain and file-lock primitives provide fresh reads and serialized operation admission without a new shared storage or IPC framework. Operations on the same application are serialized across processes; other applications and their conversation decisions remain independent. + +## Consequences + +File locks coordinate processes on one machine and PID namespace. A network-mounted profile shared across hosts is unsupported. Revocation may wait for another process's native call to settle. No timer establishes authorization validity. + +The permission page still omits conversation-only grants and reads current state on entry, focus, actions and reconnection. Storage changes do not emit configuration events. System permissions remain owned by macOS. Tests cover restart retention, profile isolation, another process's write, cancellation, corrupted data, legacy import and non-resurrection after revocation. Stored conversation records currently require explicit retention management rather than automatic eviction. diff --git a/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.zh.md b/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.zh.md new file mode 100644 index 0000000000..ef6be5c57b --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-19-cua-profile-consent-storage.zh.md @@ -0,0 +1,31 @@ +# Agent Note: 同一 profile 内的持久 Computer Use 授权 + +Status: implemented + +[English](2026-10-19-cua-profile-consent-storage.md) | 中文 + +## 问题 + +把应用许可保存为插件配置，会让每次授权变更依赖配置重组。只保存在进程内的会话决定，也会在重启后恢复同一对话时丢失。长期持有的内存存储句柄无法观察另一个进程的撤销操作。 + +## 决策 + +CUA 使用现有域存储服务，每个 profile 的真实目录对应独立存储域，按本机应用身份保存长期许可和会话决定。对话 ID 限定权限范围，不把本会话许可扩展为所有对话的许可。本机身份规则仍由[Bundle ID 授权](2026-10-25-cua-bundle-id-consent.zh.md)负责，本记录仅替代其中的存储和重启后有效期选择。 + +每个操作使用现有文件锁，在 profile 锁内打开并读取最新存储状态，关闭域后才释放锁。原生操作和撤销使用单独的目标应用锁；原生调用期间仍可读取存储或访问其他应用。撤销先取消本进程中受影响的工作，再等待其他进程已获准执行的操作结束后提交。因此，撤销完成后不会留下仍使用旧授权的操作。应用级撤销代次和各对话的决定版本，阻止旧句柄或迟到回答恢复被撤销的访问权限。 + +随附配置继续使用 JSON 后端。域名包含 profile 真实目录的 SHA-256 摘要，隔离共用存储根目录的不同 profile。旧 `allowedApps` 只导入一次，持久化迁移标记阻止旧配置恢复已撤销的许可。用户确认列表迁移完成后可删除旧配置。profile 存储损坏或不可用时拒绝访问。没有 profile 的组合只保留临时会话状态。 + +## 考虑过的替代方案 + +**继续将授权保存在配置中。** 可以复用旧存储，但运行时应用决定仍依赖配置写入和 HMR。 + +**长期打开域并依赖变更事件。** 域事件只在进程内传播，另一个宿主可能在撤销后继续使用旧许可。 + +**增加新的监听器、版本文件或授权代理。** 现有域存储和文件锁已经能提供最新状态与串行准入，无须增加通用存储或 IPC 框架。不同进程对同一应用的操作串行执行，其他应用及其会话决定保持独立。 + +## 后果 + +文件锁协调同一电脑及 PID 命名空间中的进程，不支持跨主机共用网络目录。撤销可能等待其他进程的原生调用结束。授权是否有效不由计时器决定。 + +权限页仍不显示仅对单个会话生效的许可，在进入页面、返回窗口、完成操作和重连后读取最新状态。存储变更不发送配置事件，系统权限仍归 macOS 管理。测试覆盖重启恢复、profile 隔离、其他进程写入、取消、数据损坏、旧配置导入和撤销后不恢复。已保存的会话记录目前需要显式管理保留期限，不自动淘汰。 diff --git a/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.i18n.yaml new file mode 100644 index 0000000000..89f47b3ea8 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-20-ptc-script-evaluation-and-retention.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 .agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.md +/agent-note-ptc-script-evaluation-and-state-retention: + en: e222c8cda4cee561 + zh: 9e624e5643ad2984 +/agent-note-ptc-script-evaluation-and-state-retention/problem: + en: 2da844a2a4e1903b + zh: 3b74ba7c1bcdae89 +/agent-note-ptc-script-evaluation-and-state-retention/decision: + en: 4beff8714f1d1555 + zh: a22019a90989eb66 +/agent-note-ptc-script-evaluation-and-state-retention/alternatives-considered: + en: 8ee3f3c7e04b4f25 + zh: ac604fa8debcfebf +/agent-note-ptc-script-evaluation-and-state-retention/consequences: + en: 64b7d3a5d247d82b + zh: 6f94d6b37f1ea4c1 diff --git a/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.md b/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.md new file mode 100644 index 0000000000..ef8a85dbfb --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.md @@ -0,0 +1,33 @@ +# Agent Note: PTC Script evaluation and state retention + +Status: implemented + +English | [中文](2026-10-20-ptc-script-evaluation-and-retention.zh.md) + +## Problem + +Program syntax and memory lifetime answer different questions. A consumer may need Script declarations and completion values while requiring either a fresh environment or retained references. Inferring memory lifetime from REPL syntax prevents that choice. + +## Decision + +The Node provider adds `executionMode: vm-script` and a separate `scriptPersistence` option, defaulting to false. `PtcRuntime.programFormat` describes accepted syntax; `retainsState` describes owner-scoped memory. Consumers use the latter for persistence controls and guidance. Existing `per-call` and `persistent-in-memory` configurations retain their meanings and defaults. + +This extends the mode-naming decision in [best-effort persistent PTC](2026-09-23-best-effort-persistent-ptc.md), whose ownership, non-durability and recovery decisions remain active. The Node provider selects its evaluator once and shares managed process mechanisms across temporary and retained lifetimes. AsyncFunction, REPL and Script remain separate evaluator implementations, so process reuse does not define syntax. + +VM Script uses a separate realm inside the managed child process. Top-level await uses the Node.js v26.6.0 REPL transform, with Acorn and acorn-walk supplying parsing and traversal. Detection precedes native compilation because non-strict Script can compile `await` as an identifier. The adapted visitors traverse computed method keys without entering method bodies. The source retains upstream attribution and license; the [package reference](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#known-limitations-and-deferred-work) owns declaration and realm limitations. + +## Alternatives considered + +**Replace existing modes with Script.** This would change async-function return syntax and REPL declaration behavior for existing consumers. An additional mode preserves those choices while exposing Script semantics. + +**Encode syntax and retention in every mode name.** Separate names for fresh and retained Script would repeat syntax choices and encourage consumers to infer persistence from the format. One Script mode and an explicit retention option keep each fact separately observable. + +**Use native Script without await conversion.** Native Script cannot evaluate top-level await. Parsing only after native compilation fails also misses valid programs where `await` compiles as an identifier. The Node transform supplies retained declarations and completion handling while keeping its known semantic tradeoffs explicit. + +**Own a generic AST walker.** A local walker duplicates traversal provided by acorn-walk and must independently track new Acorn nodes. The maintained walker removes that implementation; only the evaluation-specific visitors remain local. + +## Consequences + +Script state is best-effort process memory, with the same explicit owner release and sandbox invalidation rules as retained REPL execution. It is neither serialized nor reconstructed by rerunning earlier programs. An uncaught callback exception or unhandled rejection terminates the Script process; programs must await asynchronous work. + +The published format union now includes `script`, and custom retained providers must report `retainsState`. The [upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md) describes consumer migration. Source deployments need the evaluator modules and Acorn packages; private process bundles include those dependencies. diff --git a/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.zh.md b/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.zh.md new file mode 100644 index 0000000000..1dcdf4f1bc --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-20-ptc-script-evaluation-and-retention.zh.md @@ -0,0 +1,33 @@ +# Agent Note: PTC Script 求值与状态保留 + +Status: implemented + +[English](2026-10-20-ptc-script-evaluation-and-retention.md) | 中文 + +## 问题 + +程序语法和内存生命周期回答不同的问题。消费者可能需要 Script 声明和完成值，同时要求全新环境或保留引用。根据 REPL 语法推断内存生命周期会阻碍这种选择。 + +## 决策 + +Node 提供方增加 `executionMode: vm-script` 和独立的 `scriptPersistence` 选项，后者默认为 false。`PtcRuntime.programFormat` 描述接受的语法，`retainsState` 描述按所有者保留的内存。消费者通过后者提供持久化控制和指引。已有 `per-call` 和 `persistent-in-memory` 配置保留原有含义与默认值。 + +本决策扩展[尽力保留 PTC 状态](2026-09-23-best-effort-persistent-ptc.zh.md)中的模式命名决策；其中的所有权、非持久存储及恢复决策仍然有效。Node 提供方一次性选择求值器，并在临时和保留生命周期之间共用受管进程机制。AsyncFunction、REPL 和 Script 仍是独立的求值器实现，进程复用不决定语法。 + +VM Script 在受管子进程内使用独立 realm。顶层 await 使用 Node.js v26.6.0 REPL 转换，由 Acorn 和 acorn-walk 提供解析与遍历。在原生编译之前检测 await，因为非严格 Script 可以将 `await` 编译为标识符。适配后的 visitor 遍历方法的计算属性名，但不进入方法体。源码保留上游署名和许可；[包参考](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#known-limitations-and-deferred-work)负责声明与 realm 限制。 + +## 考虑过的替代方案 + +**用 Script 替换已有模式。** 这会改变现有消费者的异步函数返回语法和 REPL 声明行为。增加模式可在提供 Script 语义的同时保留已有选择。 + +**在每个模式名称中同时编码语法与保留方式。** 为全新和保留状态的 Script 分别命名，会重复语法选项，并鼓励消费者根据格式推断持久化。一个 Script 模式加显式保留选项，让两项事实可以分别观测。 + +**仅使用原生 Script，不转换 await。** 原生 Script 无法求值顶层 await。只在原生编译失败后解析，也会漏掉将 `await` 编译为标识符的有效程序。Node 转换提供声明保留和完成值处理，同时明确其已知语义取舍。 + +**自行维护通用 AST 遍历器。** 局部遍历器重复 acorn-walk 已提供的遍历功能，还必须独立跟踪新增 Acorn 节点。使用维护中的遍历器可以删除这部分实现，只保留与求值相关的局部 visitor。 + +## 影响 + +Script 状态是尽力保留的进程内存，遵循与保留 REPL 相同的显式所有者释放和沙箱失效规则。状态不会序列化，也不会通过重新执行旧程序重建。未捕获的回调异常或未处理的 Promise 拒绝会终止 Script 进程；程序必须等待异步工作。 + +公开格式联合类型现包含 `script`，自定义保留状态的提供方必须报告 `retainsState`。[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.zh.md)说明消费者迁移。源码部署需要求值器模块和 Acorn 包，私有进程 bundle 包含这些依赖。 diff --git a/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.i18n.yaml new file mode 100644 index 0000000000..bcc252082f --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.i18n.yaml @@ -0,0 +1,37 @@ +# Bilingual-pair consistency record for 2026-10-20-workspace-tree-state-per-pane.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 .agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.md +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open: + en: 3768a6ac42af3a0b + zh: ba3c0826b2a4d287 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/problem: + en: 3a7f14dd68a3ff14 + zh: b21be07e8a7e6024 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/decision: + en: a15c7c13f167e5ac + zh: ff261e3705c47ff0 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/decision/the-tree-is-drawn-inside-each-file-tab-and-its-state-is-kept-per-pane: + en: 432aff475f1dfd21 + zh: bbc058c1f967c067 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/decision/the-rows-are-a-controlled-component-factory-over-flat-entries: + en: a06955933f9f7f0e + zh: ccda2bd27175d36b +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/decision/the-plugin-that-mounts-the-tree-decides-where-a-file-lands: + en: 7cf8e3671900fe71 + zh: 952f69cba9c44c10 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/decision/navigation-is-consumed-by-the-destination-tab: + en: e7b254df55d9768d + zh: d3303f20bb9ebdd6 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/decision/each-package-works-without-the-others: + en: dd160808a3ac77bc + zh: f63741f159717072 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/alternatives-considered: + en: 1c5501c71afc7748 + zh: 3a2b0ec2d7923a12 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/consequences: + en: 586ec09cfcf60b82 + zh: ef683318fbf68d71 +/agent-note-the-workspace-tree-is-per-pane-state-drawn-inside-each-file-tab-and-the-plugin-mounting-it-decides-where-files-open/verification: + en: eae354783022bed8 + zh: fe2563a3bb259d55 diff --git a/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.md b/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.md new file mode 100644 index 0000000000..3f1756978a --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.md @@ -0,0 +1,74 @@ +# Agent Note: The workspace tree is per-pane state drawn inside each file tab, and the plugin mounting it decides where files open + +Status: implemented + +English | [中文](2026-10-20-workspace-tree-state-per-pane.zh.md) + +## Problem + +Reading several workspace files needs a tree beside their previews without losing expansion, loaded levels, width, scroll, or keyboard position on every tab switch. The dock mounts only the selected tab's body, so a component instance cannot own the state shared by a pane's file tabs. + +A floating panel holds one tab. A preview's file picker must replace that tab in its panel, while the files page must remain available and open content in the dock. A covering tree must close where content is navigated to, not where the initiating click happened. + +## Decision + +### The tree is drawn inside each file tab, and its state is kept per pane + +`ui-sidebar-right` supplies `useTabInfo().panel` with the containing pane's `id` and `isFloating`; moving a tab updates those fields without changing `tab.id`. It supplies no pane lifetime. `ui-sidebar-files` owns each pane's tree state, visibility, width, listing, directory watches, scroll, and last revealed file. The navigator and toggle are Session-scoped Component Factories; `ui-sidebar-documentpreview` renders them inside the tab's content row and header, with stable positions across loading states. The docking kit does not acquire a files-specific overlay or layout rule. + +A pane's records follow the tabs whose navigator last drew there, using each tab's `signal`. A replacement in the same pane retains the records. A moved tab uses its destination pane's records; a pane without records starts hidden at the default width. Tab-owned preview scroll is independent of that tree state. Records are released after their last associated tab closes or draws the navigator elsewhere. + +Directory watches follow visible drawings rather than retained records. Hidden trees hold no Host directory watch; showing them again refreshes the root and expanded directories while retaining rows. A same-pane tab switch keeps the listing and watches across the replacement drawing. This extends the [directory watch lifetimes](../feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md) from one tab to the pane's drawn tree. + +The files face owns ancestor reveal, scrolling, row measurement, and focus across drawings, so replacing a drawing does not discard an ongoing interaction. [The navigator reference](../../../../packages/client/ui-sidebar-files/README.md#the-navigator) owns layout, workspace-command, and keyboard rules. + +### The rows are a controlled Component Factory over flat entries + +The root-scoped `sidebar.files.tree` Factory keeps reusable rows, its local `accessory` slot, and localized copy with the files plugin. Callers own data access, expansion, opening, and reveal. The workspace navigator adapts its pane's directory states to these inputs. + +### The plugin that mounts the tree decides where a file lands + +`FileNavigatorInput.onOpen(address)` is the containing plugin's callback. The navigator constructs the file address but neither chooses placement nor closes the initiating tree after the call. Its `page` input controls layout only. A callback keeps the same navigator usable for the files page and document previews without teaching its rows either host's opening policy. + +The [preview and files-page callbacks](../../../../packages/client/ui-sidebar-files/README.md#the-navigator) express different lifetimes: the preview gives way to new content, while the files page remains a directory browser. [Right Sidebar placement](../../../../packages/client/ui-sidebar-right/README.md#ctxsidebarright) owns replacement and reveal; the navigator does not duplicate those policies. + +### Navigation is consumed by the destination tab + +The files face follows the existing navigation observable only for tabs attached to its navigator. It retains each tab's consumed revision independently of the drawing and releases that subscription on tab closure or plugin disposal. It does not require a layout inventory, navigation-origin field, or an opening result from the right Sidebar. + +The face waits for the destination drawing and measures its current row, so the previous tab's width cannot decide whether content is covered. It consumes navigation even while hidden to prevent a later manual show from replaying an old close. [The navigator reference](../../../../packages/client/ui-sidebar-files/README.md#the-navigator) defines the navigation sources and revision exclusions. + +### Each package works without the others + +The packages compose through the right Sidebar's tab information, the files Factories, and the tab-type registry. The preview imports only the files Factory declarations; files has no preview dependency. Without a registered viewer, the files page still lists the workspace and disables file rows it cannot open. Without the files plugin, the unregistered Factory positions render nothing and the preview keeps its own header, body, and file-handoff slots. + +## Alternatives considered + +**A static tree package or a component in `ui-primitives`.** The [package-shape rule](../../../../docs/defensive-patterns/package-surface.md) excludes new static libraries. A primitive would also require each caller to supply the generic tree labels. The Factory keeps that copy and registration with files, at the cost of requiring that plugin to draw rows. + +**A tree that owns directory reads or requires a complete path list.** A workspace is listed one expanded directory at a time. The tree therefore accepts partial entries and per-directory loading, failure, and truncation state. Owning reads inside each drawing would split the state and watch lifetimes that must survive tab switches. + +**A pane lifetime signal.** Floating and docking can replace the pane while retaining the tab. A pane signal would end tree state too early and invite attaching tab-owned resources to the wrong lifetime; transferring the signal would make it outlive the pane id used as the state key. The tabs' existing signals provide the required release condition. + +**A pane-level overlay that stays mounted.** It requires a layer above docked and floating tab hosts and changes to layout, focus, measurement, and drop targets to avoid intercepting input, including floating resize handles. Drawing inside tabs keeps these concerns in their existing owners. + +**Keep visited bodies mounted or copy per-tab trees.** Retaining every body still creates independent trees and watches for tabs sharing a pane and retains each preview's rendered content. Copying state cannot transfer watches and needs a conflict rule when tabs move between panes. + +**Keep watches for a pane's whole lifetime or release by inspecting its layout.** The main docked pane rarely disappears, so lifetime-bound watches remain after hiding. Inspecting tab kinds in the layout couples files to every navigator consumer and still does not express whether the tree is drawn. + +**A focus request bit consumed by a component effect.** A request stored on the initiating pane can survive a reveal elsewhere and affect a later drawing; a hidden consumer has no element to focus. The face ties focus to its actual drawings instead. + +**Carry a dragged tab's tree preference into its new pane.** This needs another transfer policy and conflicts with the state already owned by the destination pane. A new pane starts with the same defaults as every other new pane. + +## Consequences + +Tab remounts do not own or reset the pane's tree. Moving a tab selects the destination's state rather than copying the source's; hiding releases directory watches without deleting expansion and scroll. Navigation consumption is per tab, while display preferences remain per pane, so an open in another pane does not close the source tree. + +The files page retains directory reload and directory-action controls; a preview retains its file controls and handoff. Opening policy remains with those hosts, not the reusable rows. + +## Verification + +- `packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx`, `service.client.spec.ts`, and `seat.client.spec.tsx` cover live pane information, replacement, reveal, and framework tab hooks. +- `packages/client/ui-sidebar-files/tests/` covers per-pane state, navigation consumption, drawing lifetimes, workspace roots, and file opening callbacks. +- `packages/client/ui-sidebar-files/tests/file-tree.client.spec.tsx`, `file-tree-interactions.client.spec.tsx`, and `file-tree-factory.client.spec.tsx` cover generic rows, independent accessories, and real Factory composition with locale and fallback. +- `apps/web/tests/file-browser.e2e.ts` and `apps/web/tests/file-browser-composition.e2e.ts` own browser evidence; the latter disables each of `ui-sidebar-documentpreview` and `ui-sidebar-files` in the shipped Web composition. diff --git a/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.zh.md b/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.zh.md new file mode 100644 index 0000000000..e3580c7fe1 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-20-workspace-tree-state-per-pane.zh.md @@ -0,0 +1,74 @@ +# Agent Note: 工作区目录树是按分栏保存的状态，在每个文件 tab 内绘制；挂载它的插件决定文件在哪里打开 + +Status: implemented + +[English](2026-10-20-workspace-tree-state-per-pane.md) | 中文 + +## 问题 + +连续阅读多个工作区文件需要预览旁的目录树在每次切换 tab 后保留展开状态、已加载的层、宽度、滚动位置与键盘位置。停靠布局只挂载选中 tab 的正文，因此组件实例不能拥有分栏内各文件 tab 共用的状态。 + +一个浮窗只容纳一个 tab。预览的文件选择器必须在浮窗内替换该 tab，文件页则必须保持可用，并在停靠区打开内容。遮盖正文的目录树应在内容被导航到的地方关闭，而不是在发起点击的地方关闭。 + +## 决定 + +### 目录树在每个文件 tab 内绘制，其状态按分栏保存 + +`ui-sidebar-right` 通过 `useTabInfo().panel` 提供所在分栏的 `id` 与 `isFloating`；移动 tab 时更新这些字段，`tab.id` 保持不变。它不提供分栏生命周期。`ui-sidebar-files` 拥有各分栏的目录树状态、可见性、宽度、列举、目录监听、滚动与上次定位的文件。导航栏和开关是 Session 作用域的 Component Factory；`ui-sidebar-documentpreview` 在 tab 的内容行与头部渲染它们，加载状态变化时保持位置稳定。停靠套件不增加 files 专属的覆盖层或布局规则。 + +分栏记录跟随最近在该分栏绘制导航栏的 tab，以各 tab 的 `signal` 为依据。同一分栏内的替换保留记录。移走的 tab 使用目标分栏的记录；没有记录的分栏默认隐藏目录树、使用默认宽度。tab 拥有的预览滚动状态独立于目录树状态。最后一个关联 tab 关闭或在别处绘制导航栏后，记录被释放。 + +目录监听跟随可见的绘制，而不是保留的记录。隐藏的目录树不持有 Host 目录监听；再次显示时保留行并刷新根目录与已展开目录。同一分栏内切换 tab 时，替代绘制之间保留目录列表与监听。这把[目录监听生命周期](../feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md)从单个 tab 扩展为分栏中已绘制的目录树。 + +files face 负责跨绘制的祖先定位、滚动、行宽测量与焦点，因此替换绘制不会丢弃进行中的交互。[导航栏参考](../../../../packages/client/ui-sidebar-files/README.zh.md#the-navigator)定义布局、工作区命令与键盘规则。 + +### 各行是以扁平条目为输入的受控 Component Factory + +root 作用域的 `sidebar.files.tree` Factory 将可复用的行、局部 `accessory` slot 和本地化文案留在 files 插件。调用方负责数据访问、展开、打开与定位。工作区导航栏把分栏的目录状态转换为这些输入。 + +### 挂载目录树的插件决定文件落在哪里 + +`FileNavigatorInput.onOpen(address)` 是容纳导航栏的插件提供的回调。导航栏构造文件地址，但不选择落位，也不在调用后关闭发起侧目录树。`page` 输入只控制布局。回调使同一导航栏能同时用于文件页与文档预览，不必让各行知道这两种宿主的打开策略。 + +[预览与文件页的回调](../../../../packages/client/ui-sidebar-files/README.zh.md#the-navigator)表达不同的生命周期：预览让位给新内容，文件页则保持为目录浏览器。[右侧 Sidebar 落位](../../../../packages/client/ui-sidebar-right/README.zh.md#ctxsidebarright)负责替换与揭示，导航栏不重复这些策略。 + +### 导航由目标 tab 消费 + +files face 仅跟随已关联到其导航栏的 tab 的现有导航可观察值。它独立于绘制保留各 tab 已消费的 revision，并在 tab 关闭或插件卸载时释放订阅。它不需要右侧 Sidebar 提供布局清单、导航来源字段或打开结果。 + +face 等待目标绘制并测量其当前行宽，因此上一个 tab 的宽度不能决定内容是否被覆盖。隐藏期间也消费导航，防止之后手动显示时重放旧的关闭操作。[导航栏参考](../../../../packages/client/ui-sidebar-files/README.zh.md#the-navigator)定义导航来源与 revision 排除规则。 + +### 每个包都可以单独工作 + +各包通过右侧 Sidebar 的 tab 信息、files Factory 和 tab 类型注册表组合。预览仅导入 files Factory 的声明；files 不依赖预览。没有已注册查看器时，文件页仍列出工作区，并禁用无法打开的文件行。没有 files 插件时，未注册的 Factory 位置不绘制内容，预览保留自己的头部、正文和文件交接 slot。 + +## 考虑过的替代方案 + +**静态目录树包或 `ui-primitives` 中的组件。** [包形态规则](../../../../docs/defensive-patterns/package-surface.zh.md)排除新增静态库。primitive 还要求各调用方传入通用目录树文案。Factory 使文案与注册留在 files，代价是绘制各行必须加载该插件。 + +**由目录树读取目录，或要求完整路径列表。** 工作区逐个展开的目录列出。因此目录树接收不完整条目，以及各目录的加载、失败与截断状态。在每次绘制中拥有读取会拆散必须跨 tab 切换保留的状态和监听生命周期。 + +**分栏生命周期信号。** 浮出和停靠可能替换分栏，但保留 tab。分栏信号会过早结束目录树状态，还会诱使调用方把 tab 资源绑到错误的生命周期；转移信号则让它比用作状态键的 pane id 活得更久。tab 已有的信号提供了所需的释放条件。 + +**始终挂载的分栏级覆盖层。** 它需要在停靠与浮动 tab 宿主之上增加一层，并修改布局、焦点、测量与拖放目标，避免拦截包括浮窗缩放手柄在内的输入。在 tab 内绘制则让这些职责留在原有所有者处。 + +**保留已访问正文或复制逐 tab 的目录树。** 保留所有正文仍会为同一分栏的不同 tab 创建独立目录树与监听，并保留各预览的已渲染内容。复制状态无法转移监听，还需要在 tab 跨分栏移动时决定冲突如何处理。 + +**让监听与分栏同寿，或检查布局后释放。** 主停靠分栏很少消失，因此按其生命周期持有的监听在隐藏后仍存在。检查布局中的 tab 类型会让 files 与每个导航栏消费方耦合，仍不能表达目录树是否正在绘制。 + +**由组件 effect 消费的聚焦请求位。** 保存在发起分栏的请求可能在揭示别处后留存，影响之后的绘制；隐藏的消费方也没有可聚焦元素。face 则把焦点与实际绘制绑定。 + +**把被拖动 tab 的目录树偏好带到新分栏。** 这需要另一套转移策略，并与目标分栏已经拥有的状态冲突。新分栏使用与其他新分栏相同的默认值。 + +## 后果 + +tab 重新挂载不拥有也不重置分栏目录树。移动 tab 时选择目标状态，不复制源状态；隐藏释放目录监听，但不删除展开与滚动状态。导航消费按 tab 保存，显示偏好仍按分栏保存，因此在另一分栏打开内容不会关闭源目录树。 + +文件页保留目录重新读取与目录操作控件；预览保留文件控件与交接操作。打开策略由这些宿主拥有，不属于可复用的行。 + +## 验证 + +- `packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx`、`service.client.spec.ts` 与 `seat.client.spec.tsx` 覆盖实时分栏信息、原位替换、揭示与框架 tab hook。 +- `packages/client/ui-sidebar-files/tests/` 覆盖逐分栏状态、导航消费、绘制生命周期、工作区根目录与文件打开回调。 +- `packages/client/ui-sidebar-files/tests/file-tree.client.spec.tsx`、`file-tree-interactions.client.spec.tsx` 与 `file-tree-factory.client.spec.tsx` 覆盖通用行、独立附件，以及带 locale 和 fallback 的真实 Factory 组合。 +- `apps/web/tests/file-browser.e2e.ts` 与 `apps/web/tests/file-browser-composition.e2e.ts` 负责浏览器验证；后者在随包发布的 Web 组合中分别禁用 `ui-sidebar-documentpreview` 与 `ui-sidebar-files`。 diff --git a/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.i18n.yaml new file mode 100644 index 0000000000..458cbcc733 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-21-context-menu-contributions.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 .agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.md +/agent-note-context-menu-contributions: + en: 380bed76b1989558 + zh: ecbb5c15933431f6 +/agent-note-context-menu-contributions/problem: + en: baf7f6e331fd9f03 + zh: 8a45faaad34e6b0c +/agent-note-context-menu-contributions/decision: + en: f04341778de57140 + zh: 12147060ea28feb1 +/agent-note-context-menu-contributions/alternatives-considered: + en: 1fc419cf3a0642d3 + zh: f774e64679bed2ab +/agent-note-context-menu-contributions/consequences: + en: 7a55e405714d598f + zh: d7ff74ace672bf22 diff --git a/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.md b/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.md new file mode 100644 index 0000000000..da02632cf2 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.md @@ -0,0 +1,29 @@ +# Agent Note: Context menu contributions + +Status: implemented + +English | [中文](2026-10-21-context-menu-contributions.zh.md) + +## Problem + +Session and tab menus already accept React Slot entries. Reusing only those entries would require external plugins to supply React components and would leave action discovery, target capture, and cancellation coupled to each trigger. + +## Decision + +[Context menus](../../../../packages/client/ui-context-menu/README.md) own typed target families, contribution resolution, and callback lifetime. Feature plugins register actions through the same service available to external Client plugins. Plain presentation fields let a renderer consume resolved actions without loading contributed React components. Existing Session and tab Slots remain in feature-owned adapters, preserving those extension positions. + +[File actions](../../../../packages/client/ui-file-actions/README.md) own original-content transfer separately from menus and image components. Saving retains original encoding; clipboard interoperability may require PNG conversion. A browser download supplies no local path, so reveal requires a verified Host file or the destination returned by a native save. + +The menu plugin contributes `useContextMenu` through the existing Slot root binding. Its ordinary `getTriggerProps` factory centralizes DOM gestures while business owners still provide captured targets. Plain children receive props or existing delegates; a separate React Context or utility package would duplicate the established lifetime and injection mechanism. + +## Alternatives considered + +**React Slots alone.** They preserve arbitrary visual content but cannot supply a presentation-independent action model. They remain available for existing component contributions. + +**A central switch over built-in target kinds.** It would make each new plugin-owned target require changes to the menu implementation. Declaration merging and registered providers instead keep target-specific behavior with its owner. + +**Native menus first.** It would duplicate the existing keyboard, placement, and dismissal implementation while excluding component-only legacy entries. The shared Web renderer serves Desktop too; another renderer can consume the plain action view independently. + +## Consequences + +An opening captures its target and contribution set. Dismissal cancels metadata work; unloading withdraws that provider's actions. Selected actions own execution and must recheck mutable resources. Legacy React entries are absent from plain-data resolution, so native rendering cannot assume complete parity. These lifetimes are covered by registry tests; browser scenarios cover unchanged selection, original bytes, and nested-overlay dismissal. diff --git a/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.zh.md b/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.zh.md new file mode 100644 index 0000000000..cb0b3c5f3c --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-21-context-menu-contributions.zh.md @@ -0,0 +1,29 @@ +# Agent Note: 右键菜单贡献 + +Status: implemented + +[English](2026-10-21-context-menu-contributions.md) | 中文 + +## 问题 + +Session 和标签页菜单已经支持 React Slot 条目。仅复用这些条目会要求外部插件提供 React 组件，并使动作发现、目标捕获和取消逻辑继续耦合到各个触发位置。 + +## 决策 + +[右键菜单](../../../../packages/client/ui-context-menu/README.zh.md)负责类型化目标类别、贡献解析和回调生命周期。功能插件通过与外部 Client 插件相同的服务注册动作。纯数据展示字段让渲染器无需加载贡献方的 React 组件即可消费已解析动作。现有 Session 和标签页 Slot 保留在各功能所属的适配器中，从而保留这些扩展位置。 + +[文件动作](../../../../packages/client/ui-file-actions/README.zh.md)独立于菜单和图片组件负责原始内容传输。保存保留原始编码；剪贴板互操作可能需要转换为 PNG。浏览器下载不提供本机路径，因此在文件夹显示要求已验证的 Host 文件，或原生保存返回的目标路径。 + +菜单插件通过现有 Slot root 绑定贡献 `useContextMenu`。普通函数 `getTriggerProps` 统一处理 DOM 手势，业务所有者继续提供捕获的目标。普通子组件通过 props 或现有 delegate 接收能力；独立 React Context 或工具包会重复已有生命周期与注入机制。 + +## 考虑过的替代方案 + +**仅使用 React Slot。** 它们支持任意视觉内容，但无法提供独立于展示方式的动作模型。现有组件贡献仍可使用它们。 + +**在中心位置按内置目标类型分支。** 这种方式会使每个新增的插件目标都要求修改菜单实现。声明合并与注册式提供方让目标特有行为保留在其所属插件。 + +**优先实现原生菜单。** 这会重复已有的键盘、定位和关闭实现，同时无法容纳仅提供组件的旧条目。Desktop 同样使用共享 Web 渲染器；其他渲染器可以独立消费纯数据动作视图。 + +## 影响 + +打开菜单时捕获目标和贡献集合。关闭取消元数据任务；插件卸载撤回该提供方的动作。已选动作自行负责执行，并须重新检查可变资源。旧 React 条目不参与纯数据解析，因此原生渲染不能假定功能完全一致。注册表测试覆盖这些生命周期；浏览器场景覆盖选择不变、原始字节以及嵌套浮层关闭。 diff --git a/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.i18n.yaml new file mode 100644 index 0000000000..9ae0452069 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.i18n.yaml @@ -0,0 +1,28 @@ +# Bilingual-pair consistency record for 2026-10-21-session-history-stream-and-snapshot.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 .agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.md +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation: + en: 0c9a7bc6591feb16 + zh: 3606a2c1caffd36f +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/problem: + en: ac1583e7ae1377f8 + zh: c60bdbda9ee89144 +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/decision: + en: 45c63df5dac389eb + zh: d72a5bcb94de22f1 +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/decision/reads-and-subscriptions: + en: 38df4f3c4fba2cc9 + zh: a34f3376faf26f0c +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/decision/follow-ordering-and-ownership: + en: 352ff87a3e9cd110 + zh: 4ac6366cecfc08a3 +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/decision/state-and-wait: + en: a87c7427582e6b03 + zh: b28d2a73b36eb27f +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/alternatives-considered: + en: c5fb06ab9df9e7ad + zh: b20adf151018111c +/agent-note-session-snapshots-passive-subscriptions-and-web-aggregation/consequences: + en: dc1da262b4911a31 + zh: 2a4e503696fc477b diff --git a/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.md b/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.md new file mode 100644 index 0000000000..b5e1112a18 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.md @@ -0,0 +1,59 @@ +# Agent Note: Session snapshots, passive subscriptions, and Web aggregation + +Status: implemented + +English | [中文](2026-10-21-session-history-stream-and-snapshot.zh.md) + +## Problem + +A point read, an event subscription, and a Web conversation opening have different lifetimes. Combining them inside one history controller makes passive observation perform unnecessary reads and gives each aggregate its own acquisition logic. Reading before subscribing also creates a gap that requires another read to repair. The APIs need independent operations that can compose without losing events or duplicating ownership. + +## Decision + +`SessionController` is the single Session Remote Service. It owns ordinary `HistoryController`, `StateController`, and `WebController` instances, not three additional Cordis Services or Remote namespaces. The implementation separates six operations: history snapshot and observation, projection snapshot and observation, and state snapshot and observation. Follow and Wait compose those capabilities for their callers; the existing `page` entry forwards to the history reader. + +### Reads and subscriptions + +History reads return chronological records, `hasMore`, and an inclusive cursor. An omitted `throughSeq` selects the observed log end; `beforeSeq` selects older records without changing that read cut. Projection reads return exact sequenced values, sequence-free cache hints when migration is required, or null when the Session is absent. Live projection reads avoid persistence metadata access. + +`usingObservation({ sessionId, projection }, signal, callback?)` acquires the existing disposable SessionObservation. A callback borrows it until the callback settles; without a callback the caller owns disposal. Ordinary history, state, and Wait output reads do not request projections. Follow, exact projection reads, and subagent history descriptor validation request them. No read activates an Agent implicitly. + +`observeEvent` and `observeProjections` install listeners without acquiring an Observation. Their initial `ready` confirms subscription, not a snapshot cursor, existence, parent-child validity, or Agent readiness. History establishes continuity from its first received event; projection updates replace individual keys and may share a sequence number. `observeState` instead begins with a complete state read and coalesces later Session and Agent invalidations. + +History, history observation, and Follow accept Address requests; projection and state operations accept Session IDs. All internal readers and listeners use Session IDs. History and Follow validate Address against their opening Observation at the Controller layer, including the existing subagent descriptor rules. Pure history observation does not acquire a read for entity validation. Gateway resource authorization remains independent: the registered Session resolver extracts the target ID from the request before access is decided. + +### Follow ordering and ownership + +Follow installs history and optional assistant listeners first, then acquires one projected Observation. It captures the assistant baseline and binding-local arrival ordinal synchronously, sets both cuts, publishes the opening snapshot, and consumes the shared output queue. History notifications at or before the snapshot cursor and assistant notifications at or before the ordinal are discarded at consumption. Later notifications remain ordered without a second history read, background merge pumps, or a tail repair introduced by the opening itself. + +`session/created` contributes constructor seed events through the same history buffer. The adapter retains the supplied Session and its captured end position, then reads that in-memory prefix when consumed; it does not acquire another Observation. Each binding owns its subscriptions; a shared output queue belongs to Follow rather than to either listener. + +Follow activates only when the caller passes `activate: true`; the Web Client does so explicitly. Background promotion starts once the opening is computed and before it is delivered, and does not promise Agent readiness. Ordinary promotion reuses the existing Agent controller and receives a separately retained Observation. Either Follow releases its opening Observation once the opening is computed, before yielding it; activation continues on the separately retained lease, so the cold entry's reference count drops to that lease alone. Subagent Sessions do not use ordinary promotion. + +### State and Wait + +State contains the event cursor, active and running flags, the complete readable queue or null, and pending-input kinds. It exposes neither a header nor an internal revision. Gateway owns unsettled Remote events; State samples their detached metadata and classifies approval, question, or other input without copying a request registry. + +Wait evaluates complete states, confirms active-Agent quiescence with `whenIdle`, and rejects stale observations using listener-local revisions and Agent/Session identity checks. Session and Agent events wake reads immediately; while waiting, a one-second recheck detects pending input that produces no such event. This avoids adding a Gateway change event, at the cost of polling and bounded sampling delay rather than instantaneous notification. `observeState` does not poll, so pending-only changes need another state invalidation to become visible there. + +Wait returns idle, input-required, or timeout with the last state it accepted and bounded assistant output. Output contains only `assistant/message` records in `(afterSeq, state.cursor]`, newest first, and reports truncation only when another eligible record exists. The caller's cancellation signal controls that output read independently of the expired wait deadline. A wait that accepts no state before its deadline fails instead of inventing a state. + +## Alternatives considered + +**Read history, then subscribe and repair the gap.** Subscription-before-read already captures opening-time increments. A second read adds acquisition and replay obligations without improving that ordering. + +**Give pure subscriptions an Observation or ready cursor.** These values conflate subscription readiness with an independently selected read cut. Callers that need both subscribe and buffer first, then read and discard covered increments. + +**Keep separate Remote Services for the implementation controllers.** The classes divide behavior, not external service identity. One Session Service owns their composition, resource policy, and Remote entry points. + +**Have Gateway interpret pending input or emit Session status.** Gateway only owns Remote event transport and unsettled-event metadata. State owns classification; Wait's periodic sampling avoids adding a transport notification solely for Session waiting. + +**Merge assistant and history with independent asynchronous pumps.** One caller-owned buffer retains cross-source arrival order without extra pump cancellation or queue ownership. Snapshot construction and per-binding buffering retain distinct lifetimes. + +## Consequences + +The standard reads and Web aggregate share one Observation acquisition path, while pure subscriptions remain read-free. The old combined History controller is removed; still-used pagination, validation, and wire helpers remain at their original path. Cancellation, consumer termination, failed opening reads, and Context disposal release subscriptions and owned leases without cancelling Agent execution. + +The [Observation decision](2026-08-25-session-observations-and-projection-owned-client-state.md) remains the authority for exact read cuts and projection derivation. The [history and Remote transport decision](2026-08-18-session-history-and-event-transport.md) retains ownership of Client reconnection and transport lifetimes. This decision refines Session API composition rather than replacing either broader decision. + +The migrated history, cold-read, and transport tests exercise the new classes, including cursor overlap, assistant ordinal cuts, sequence gaps, subagent validation, and teardown. Slow consumers can still retain queued notifications; silent dropping is not a supported recovery strategy. Independent completion-acknowledged activation is not implemented by these reads or by Follow's background activation option. diff --git a/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.zh.md b/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.zh.md new file mode 100644 index 0000000000..773ab039b3 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-21-session-history-stream-and-snapshot.zh.md @@ -0,0 +1,59 @@ +# Agent Note: Session 快照、纯订阅与 Web 聚合 + +Status: implemented + +[English](2026-10-21-session-history-stream-and-snapshot.md) | 中文 + +## Problem + +定点读取、事件订阅和 Web 会话开场具有不同的生命周期。把它们合并在同一个历史控制器中，会使被动观察执行不必要的读取，并让每个聚合各自维护获取数据的逻辑。先读后订阅还会产生需要再次读取来修复的缺口。接口需要相互独立的操作，使组合既不丢事件，也不重复资源所有权。 + +## Decision + +`SessionController` 是唯一的 Session Remote Service。它持有普通的 `HistoryController`、`StateController` 和 `WebController` 实例，而不是额外的三个 Cordis Service 或 Remote namespace。实现分离六个操作：历史快照与观察、投影快照与观察、状态快照与观察。Follow 和 Wait 为调用方组合这些能力；已有的 `page` 入口转发到历史读取器。 + +### 读取与订阅 + +历史读取返回时间正序的记录、`hasMore` 和包含末项的游标。省略 `throughSeq` 时选择观察到的日志末尾；`beforeSeq` 只选择更早的记录，不改变读取点位。投影读取返回精确的有序值、需要迁移时无序号的缓存提示，或在 Session 不存在时返回 null。live 投影读取不访问持久化元信息。 + +`usingObservation({ sessionId, projection }, signal, callback?)` 获取已有的可释放 SessionObservation。有回调时租约借给回调直到其结束；无回调时由调用方释放。普通历史、状态及 Wait 输出读取不请求投影。Follow、精确投影读取和子会话历史 descriptor 校验请求投影。读取不会隐式激活 Agent。 + +`observeEvent` 和 `observeProjections` 安装监听而不获取 Observation。首个 `ready` 确认订阅生效，不代表快照游标、实体存在、父子关系有效或 Agent 就绪。历史从首个收到的事件建立连续性；投影更新替换单个键，多个更新可以共享序号。`observeState` 则从完整状态读取开始，并合并后续 Session 和 Agent 失效通知。 + +历史、历史观察和 Follow 接收 Address 请求；投影和状态操作接收 Session ID。所有内部读取器和监听器都使用 Session ID。History 和 Follow 在 Controller 层以开场 Observation 校验 Address，包括已有的子会话 descriptor 规则。纯历史观察不为实体校验获取读取。Gateway 资源授权与之独立：注册的 Session 解析器在访问判定前从请求提取目标 ID。 + +### Follow 顺序与所有权 + +Follow 先安装历史和可选 assistant 监听，再获取一份带投影的 Observation。它同步捕获 assistant 基线和绑定局部的到达序号，设置两种截断点，发布开场快照，然后消费共享输出队列。消费时丢弃序号不超过快照游标的历史通知，以及到达序号不超过截断点的 assistant 通知。后续通知保持顺序，无需第二次历史读取、后台合并任务，或由开场自身引入的尾部修复。 + +`session/created` 经同一历史缓冲提供构造期种子事件。适配器保留收到的 Session 及捕获的末尾位置，在消费时读取对应内存前缀，不获取另一份 Observation。每个绑定拥有自己的订阅；共享输出队列属于 Follow，而不是任一监听器。 + +只有调用方传入 `activate: true` 时 Follow 才激活；Web Client 显式传入该参数。后台提升在开场计算完成后、交付之前启动，不承诺 Agent 已就绪。普通提升复用已有 Agent controller，并接收单独 retain 的 Observation。两种 Follow 都在开场计算完成后、交付前释放开场 Observation；激活则继续使用单独 retain 的租约，因此冷 entry 的引用计数只剩那一份。子会话不走普通提升。 + +### 状态与 Wait + +State 包含事件游标、active 与 running 标志、完整可读队列或 null，以及待输入种类。它不暴露 header 或内部 revision。Gateway 拥有未结算的 Remote 事件；State 采样独立元数据，将输入分类为 approval、question 或 other，不复制请求注册表。 + +Wait 判断完整状态，通过 `whenIdle` 确认活跃 Agent 已静止，并通过监听器局部 revision 和 Agent/Session 身份检查拒绝过时观察。Session 和 Agent 事件立即唤醒读取；等待期间每秒重查一次，检测没有产生上述事件的待输入请求。这避免新增 Gateway change 事件，代价是轮询和采样延迟，而非即时通知。`observeState` 不轮询，因此仅有 pending 变化时，需要另一项状态失效通知才会显示更新。 + +Wait 返回 idle、input-required 或 timeout，以及最后一次被接受的状态和有界 assistant 输出。输出仅包含 `(afterSeq, state.cursor]` 内从新到旧的 `assistant/message` 记录，只有存在另一条符合条件的记录时才报告截断。输出读取使用调用方的取消信号，不受已过期的等待截止信号控制。截止前没有任何状态通过校验的 wait 会失败，不构造虚假的状态。 + +## Alternatives considered + +**先读历史，再订阅并修复缺口。** 先订阅后读取已经捕获开场期间的增量。第二次读取增加资源获取和重放责任，却不改善这个顺序。 + +**给纯订阅提供 Observation 或 ready 游标。** 这会混淆订阅就绪和独立选取的读取点位。需要两者的调用方先订阅并缓冲，再读取并丢弃已覆盖增量。 + +**为各实现 Controller 保留独立 Remote Service。** 这些类划分行为，而不是外部服务身份。一个 Session Service 拥有其组合、资源策略和 Remote 入口。 + +**让 Gateway 解释待输入状态或发送 Session status。** Gateway 只拥有 Remote 事件传输和未结算事件元数据。State 拥有分类；Wait 定期采样，避免仅为 Session 等待增加传输通知。 + +**用独立异步任务合并 assistant 与历史。** 调用方拥有的单个缓冲保留跨来源到达顺序，不引入额外任务取消或队列所有权。快照构造和各绑定缓冲仍保留不同生命周期。 + +## Consequences + +标准读取和 Web 聚合共享同一 Observation 获取路径，纯订阅不读取数据。旧的合并 History controller 已删除；仍使用的分页、校验和 wire 辅助函数留在原路径。取消、消费者结束、开场读取失败和 Context 释放都会释放订阅及拥有的租约，而不取消 Agent 执行。 + +[Observation 决策](2026-08-25-session-observations-and-projection-owned-client-state.zh.md)仍拥有精确读取点位和投影派生规则。[历史与 Remote 传输决策](2026-08-18-session-history-and-event-transport.zh.md)继续拥有 Client 重连和传输生命周期。本决策细化 Session API 组合，而不取代上述更广泛的决策。 + +迁移后的历史、冷读取和传输测试覆盖新类，包括游标重叠、assistant 到达序号截断、序号缺口、子会话校验和释放。慢消费者仍可能积累队列通知；静默丢弃不是支持的恢复策略。这些读取以及 Follow 的后台激活选项均未实现独立的、确认完成后返回的激活接口。 diff --git a/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.i18n.yaml new file mode 100644 index 0000000000..0acdacdd56 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-10-23-store-scoped-image-reads.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 .agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.md +/agent-note-image-reads-use-attachment-store-access: + en: 31c8a0d9016d99af + zh: 05db308dec85db67 +/agent-note-image-reads-use-attachment-store-access/problem: + en: ff8886cfa4634163 + zh: 46dfdd50638b64c2 +/agent-note-image-reads-use-attachment-store-access/decision: + en: 439a3277ee3b169d + zh: c9f1e10254850844 +/agent-note-image-reads-use-attachment-store-access/alternatives-considered: + en: 0c7a8319c0c91dc2 + zh: 6b7b58b142839571 +/agent-note-image-reads-use-attachment-store-access/consequences: + en: a46c3d951077ec7d + zh: 30a0cc5bcb681a21 +/agent-note-image-reads-use-attachment-store-access/verification: + en: 89603b3a4c3e12df + zh: f1b01d166f399f87 diff --git a/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.md b/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.md new file mode 100644 index 0000000000..8805102882 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.md @@ -0,0 +1,52 @@ +# Agent Note: Image reads use attachment-store access + +Status: implemented + +English | [中文](2026-10-23-store-scoped-image-reads.zh.md) + +## Problem + +Historical image loading read the requesting Session and searched its event content for every uncached attachment. The search established that the Session referenced the image; it did not locate the bytes, whose storage path already follows from the content-addressed ID. This added work proportional to history length to each image read. The reported loading delay also involved uploads; this finding alone does not identify all of that delay. + +## Decision + +Session membership is not an image-access restriction. After connection authentication and Gateway permission checks authorize `session/attachment`, every caller may read any image in the same attachment store using a complete `ImageAttachmentRef`, including objects referenced only by other Sessions or not referenced at all. The request retains `sessionId` for the existing Session resource permission check. After that check passes, the handler does not require that Session to exist and does not return `session/not-found` solely because it is absent. No identity receives a separate history-scanning path. + +The Client already holds the message's complete image reference and sends it as `attachment` beside `sessionId`. Session Controller delegates directly to the existing `AttachmentStore.readImage(ref)`. Its local provider validates the canonical ID, derives the path within its object directory, verifies SHA-256, and compares the actual format, byte length, width, and height with the supplied reference. A missing, unreadable, corrupt, or mismatched object rejects the operation. No Session history is needed to recover the reference. + +The response preserves the supplied reference. Its optional `name` and `originalDimensions` are caller-supplied display information and are not verified against the stored object. The Client's existing historical-image cache continues to own per-Session results and object URLs; the Host adds no image-byte cache. + +This rule narrows the readers covered by [Session observations](2026-08-25-session-observations-and-projection-owned-client-state.md) and the [history transport activation policy](2026-08-18-session-history-and-event-transport.md). [Workspace file reads](2026-09-05-workspace-files-service.md) keep their own filesystem authorization. + +## Alternatives considered + +**Keep a Session-to-image map or projection.** An index removes repeated scans but preserves an access restriction the product does not require, adding derivation, lifetime, and invalidation work. + +**Issue signed image tickets.** Tickets add issuance and validation state for the same unnecessary Session-membership restriction. + +**Optimize only owner reads.** That gives identities different image-access semantics and leaves the scan cost for permitted non-owner callers without a product requirement. + +## Consequences + +Knowing a valid image reference and having permission to invoke the endpoint for the supplied Session resource permits reading that object across Sessions. The local ID is the SHA-256 of normalized bytes. For known PNG, JPEG, or WebP bytes that admission preserves unchanged, a caller can calculate the ID, derive the format, byte length, and dimensions, and use an authorized read to test whether the object exists. The required reference fields need not come from a Session log. + +Image isolation requires separate Host instances with separate `DSH_HOME` directories. The shipped composition uses one attachment store per Host and does not select a store by Session. Authentication, Gateway action/resource checks, fixed storage paths, digest verification, and explicit failures remain required. + +Image reads no longer depend on history length or Session materialization. File reading, integrity verification, encoding, and transport still cost time; this change makes no claim about upload or model inference latency. Existing Session data and fork references need no migration. + +## Verification + +The read-path invariant is zero Session-history queries or traversal for attachment reads. Coverage must distinguish a permitted cross-Session image read from a denied Gateway call and exercise valid references, invalid IDs, mismatched intrinsic metadata, preserved optional display fields, missing and corrupt objects, old history pages, and inherited fork images. Performance evidence must separate historical scanning, storage work, and transport rather than attribute the entire reported delay to the scan. + +The diagnostic is [`image-read.perf.ts`](../../../../packages/api/session-controller/tests/image-read.perf.ts), compiled by its [tsdown configuration](../../../../packages/api/session-controller/tests/image-read.perf.config.ts). The baseline worker pairs the pre-change controller with `{ sessionId, attachmentId: ref.attachmentId }`; the candidate worker pairs the current controller with `{ sessionId, attachment: ref }`. Both use the same image fixtures, workload, and output checks, and run against the same built Local store with `readImage(ref)` verification. From the candidate checkout root, compile and run: + +```sh +pnpm exec tsdown --config-loader native --config packages/api/session-controller/tests/image-read.perf.config.ts +(cd packages/api/session-controller && node --expose-gc .dsh-build/image-read/image-read.perf.js --expect-no-history) +``` + +Run the separately compiled baseline worker without `--expect-no-history`; its diagnostic request must match the baseline controller's ID-only request fields. The baseline negative control adds `--sample typical --expect-no-history` and must fail because that implementation queries and traverses history. The parent process runs each workload in five fresh child processes, each with a loaded Session and a first uncached read of every image. Images are deterministic synthetic 1024 × 768 PNGs; the two workloads contain 120 turns, 960 events, and 8 images, or 2,000 turns, 16,000 events, and 32 images. Fixture writes can leave the operating system's file cache warm. + +`controllerMs` covers the direct controller call through base64 return. `storeMs` includes file I/O, SHA-256, and header verification; `snapshotMs` measures history snapshot acquisition separately. `scanAndDispatchMs` is the time before store entry minus `snapshotMs`, so it includes dispatch overhead and is not an isolated scan timer. JSON serialization and loopback HTTP transfer are separate measurements over retained responses. `requestJsonBytes` and `idOnlyRequestJsonBytes` compare serialized request lengths; they do not measure request transmission time. Cold Session restoration, Gateway processing, browser rendering, remote-network latency, upload, and model inference are excluded. PR #7021 records the worker revisions and before/after results under these limits. + +The memory endpoints run GC after fixture setup and after all image responses. The Session, admitted image references, and every base64 response remain reachable at the second endpoint. These retained endpoints include setup-owned objects, and peak RSS is cumulative from process start, including fixture generation. They do not measure image-request memory in isolation or impose a retained-memory budget. diff --git a/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.zh.md b/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.zh.md new file mode 100644 index 0000000000..0fe69e71a0 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.zh.md @@ -0,0 +1,52 @@ +# Agent Note: 图片读取使用附件存储访问权限 + +Status: implemented + +[English](2026-10-23-store-scoped-image-reads.md) | 中文 + +## Problem + +历史图片加载会为每个未缓存的附件读取请求中的 Session，并搜索其事件内容。搜索用于确认 Session 引用了图片；它不负责定位字节，存储路径已经能由内容寻址 ID 推导。每次读图因此增加了与历史长度成正比的工作。用户反馈的加载延迟还涉及上传；这项发现本身不能确定全部延迟的来源。 + +## Decision + +Session 关联不构成图片访问限制。连接身份认证和 Gateway 权限检查允许调用 `session/attachment` 后，任何调用者都可以通过完整的 `ImageAttachmentRef` 读取同一附件存储中的任意图片，包括仅被其他 Session 引用或未被任何 Session 引用的对象。请求保留 `sessionId`，供现有 Session 资源权限检查使用。该检查通过后，处理函数不要求该 Session 存在，也不会仅因其不存在而返回 `session/not-found`。所有身份使用相同的读图路径。 + +Client 已经持有消息中的完整图片引用，将其作为 `attachment` 与 `sessionId` 一起发送。Session Controller 直接调用已有的 `AttachmentStore.readImage(ref)`。本地提供方校验规范 ID，在自己的对象目录内推导路径，校验 SHA-256，并把实际格式、字节数、宽度和高度与传入引用比对。对象缺失、不可读、损坏或与引用不符时，操作失败。取得引用无需查询 Session 历史。 + +响应保留传入引用。可选的 `name` 和 `originalDimensions` 是调用方提交的显示信息，不根据存储对象校验。Client 现有的历史图片缓存继续按 Session 管理结果和对象 URL；Host 不增加图片字节缓存。 + +该规则缩小了 [Session observation](2026-08-25-session-observations-and-projection-owned-client-state.zh.md) 与[历史传输激活策略](2026-08-18-session-history-and-event-transport.zh.md)涵盖的读取范围。[工作区文件读取](2026-09-05-workspace-files-service.zh.md)保留自己的文件系统授权。 + +## Alternatives considered + +**保留 Session 到图片的 Map 或 projection。** 索引可以消除重复扫描，但保留了产品不需要的访问限制，并增加派生、生命周期和失效处理。 + +**签发图片签名票据。** 票据为同一项不需要的 Session 关联限制增加签发和验证状态。 + +**只优化 owner 的读取。** 这会让不同身份使用不同的图片访问规则，并让获准调用的非 owner 继续承担扫描成本，没有相应产品需求。 + +## Consequences + +调用方知道有效图片引用，且有权为请求中的 Session 资源调用该接口，就可以跨 Session 读取对象。本地 ID 是规范化字节的 SHA-256。对于准入时原样保留的已知 PNG、JPEG 或 WebP 字节，调用方可以计算 ID，取得格式、字节数和尺寸，并通过获准的读取请求探测对象是否存在。这些必需的引用字段不一定来自 Session 日志。 + +图片隔离需要独立 Host 实例及各自的 `DSH_HOME` 目录。随附组合在每个 Host 中使用一个附件存储，不会按 Session 选择存储。身份认证、Gateway 操作与资源检查、固定存储路径、摘要校验和明确失败仍是必需的。 + +图片读取不再依赖历史长度或 Session 物化。文件读取、完整性校验、编码和传输仍有耗时；本次改动不说明上传或模型推理延迟已得到改善。已有 Session 数据和 fork 引用无需迁移。 + +## Verification + +附件读取不得查询或遍历 Session 历史。验证必须区分获准的跨 Session 图片读取与被 Gateway 拒绝的调用，并覆盖正常引用、无效 ID、固有元数据不符、可选显示字段原样保留、缺失和损坏的对象、旧历史页以及 fork 继承图片。性能证据必须区分历史扫描、存储操作和传输，不能把用户反馈的全部延迟归因于扫描。 + +诊断脚本是 [`image-read.perf.ts`](../../../../packages/api/session-controller/tests/image-read.perf.ts)，通过配套的 [tsdown 配置](../../../../packages/api/session-controller/tests/image-read.perf.config.ts)编译。基线 worker 使用改动前的控制器与 `{ sessionId, attachmentId: ref.attachmentId }`；候选 worker 使用当前控制器与 `{ sessionId, attachment: ref }`。两者使用相同图片 fixture、工作量和输出校验，并通过同一套已构建的 Local store 执行 `readImage(ref)` 校验。在候选检出目录的根目录编译并运行： + +```sh +pnpm exec tsdown --config-loader native --config packages/api/session-controller/tests/image-read.perf.config.ts +(cd packages/api/session-controller && node --expose-gc .dsh-build/image-read/image-read.perf.js --expect-no-history) +``` + +运行单独编译的基线 worker 时不带 `--expect-no-history`；诊断请求必须匹配基线控制器仅接收 ID 的请求字段。基线负对照加上 `--sample typical --expect-no-history`，该实现会查询和遍历历史，因此负对照必须失败。父进程为每种工作量运行五个新子进程，每个子进程使用已加载的 Session，并对每张图片执行第一次未缓存读取。图片是确定性合成的 1024 × 768 PNG；两种工作量分别为 120 轮、960 个事件、8 张图片，以及 2,000 轮、16,000 个事件、32 张图片。fixture 写入可能已经预热操作系统的文件缓存。 + +`controllerMs` 覆盖从直接调用控制器到返回 base64 的时间。`storeMs` 包含文件 I/O、SHA-256 和文件头校验；`snapshotMs` 单独测量取得历史快照的时间。`scanAndDispatchMs` 是进入存储前的时间减去 `snapshotMs`，因此也包含分派开销，不是独立的扫描计时。JSON 序列化和本机回环 HTTP 传输使用保留的响应单独测量。`requestJsonBytes` 与 `idOnlyRequestJsonBytes` 比较序列化后的请求长度，不测量请求传输时间。冷 Session 恢复、Gateway 处理、浏览器渲染、远端网络延迟、上传和模型推理均不在测量范围内。PR #7021 记录 worker 修订，以及在这些限制下测得的修改前后结果。 + +内存端点在 fixture 准备完成后，以及所有图片响应完成后执行 GC。第二个端点仍保留 Session、已准入的图片引用和每个 base64 响应。这两个保留内存端点包含准备阶段拥有的对象，峰值 RSS 则从进程启动累计，包含 fixture 生成。它们不单独测量图片请求内存，也不规定保留内存预算。 diff --git a/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.i18n.yaml new file mode 100644 index 0000000000..7a21fc65bd --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-25-cua-bundle-id-consent.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 .agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.md +/agent-note-macos-consent-shared-by-bundle-identifier: + en: 41cd1b8e2629e049 + zh: f1bcef434b6d247f +/agent-note-macos-consent-shared-by-bundle-identifier/problem: + en: bb387fc89c1c578c + zh: 947456baea45cc95 +/agent-note-macos-consent-shared-by-bundle-identifier/decision: + en: 7b1bbab1f95b7610 + zh: 434e7a3fba81174b +/agent-note-macos-consent-shared-by-bundle-identifier/alternatives-considered: + en: 637b1fd2bafb1b28 + zh: 06d882818ffaf800 +/agent-note-macos-consent-shared-by-bundle-identifier/consequences: + en: 1af6d29a57ff86e2 + zh: 32517607b2fc935f diff --git a/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.md b/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.md new file mode 100644 index 0000000000..b5cfc122cd --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.md @@ -0,0 +1,33 @@ +# Agent Note: macOS consent shared by bundle identifier + +Status: implemented + +English | [中文](2026-10-25-cua-bundle-id-consent.zh.md) + +## Problem + +Users who install multiple versions of one application want one permission decision for that software. Executable paths split those decisions, and signing checks exclude unsigned development applications from saved access. + +## Decision + +macOS application consent uses the exact, case-sensitive native bundle identifier. The helper hashes `macos:bundle-id:` followed by that identifier into `CuaApplicationId`. When a bundle identifier exists, installation paths, versions and signatures do not distinguish grants. Otherwise, the helper hashes `macos:executable-path:` followed by the canonical executable path. Both identities support saved access; path identities survive restart and in-place updates, while a different path requires a new decision. Conversation decisions and saved grants retain the scopes and revocation behavior of [profile consent storage](2026-10-19-cua-profile-consent-storage.md). + +This supersedes the executable/signature identity choice in [application consent](2026-09-26-cua-application-consent.md); that note still owns enforcement and human decisions. The running process path comes from the operating system. A valid runtime bundle identifier does not depend on path-query success. Missing paths omit optional grant metadata; they never substitute a cached catalog path. When both bundle identity and process path are unavailable, consent fails with the path query cause. Process identity must still be verified, and any available process path must match the selected target. Missing catalog path metadata does not block consent when the process path is available. If the runtime bundle identifier is unavailable, a reported application bundle can supply it only when its main executable matches the process path; otherwise the executable path identifies the grant. Native process, executable-location and window checks continue to bind each handle to its selected target. Launch checks reread the bundle identifier and executable path from disk; they do not fingerprint executable content. Replacing bytes at the same path while retaining the identifier or path identity therefore retains consent, including during an approval wait. + +The identity prefixes separate new grants from old path/signature, process-instance and executable-content digests. Old grants remain removable but do not grant access to new bundle identities; users decide again before permission covers other installations. + +Apple’s [PPPC configuration](https://support.apple.com/guide/deployment/privacy-preferences-policy-control-payload-dep38df53c2a/web) supports bundle-ID or path selectors and separately requires a code-signing requirement. [TN3127](https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements) explains that designated requirements track code identity across versions, while unsigned and ad-hoc code cannot provide the same stability. DSH adopts the selector alternatives for application management without requiring publisher authentication. + +## Alternatives considered + +**Bundle identifier and path.** This distinguishes installed copies but requires separate decisions for the multiple versions the user wants to authorize together. + +**Bundle identifiers only.** Missing identifiers would exclude otherwise usable applications from saved access. Canonical executable paths supply a stable fallback without using a PID or content hash. + +**Verified signing identity.** This distinguishes publishers but denies saved access when signing is absent or cannot be verified. Publisher authentication is outside this application-management policy. + +## Consequences + +Another program declaring the same bundle identifier or replacing an executable at its approved fallback path inherits consent, including a program created or changed through separately authorized model tools. The worst consequence is observing or controlling an application that the user did not approve separately, within its available data and capabilities. The model cannot supply the authorization identity through the CUA request; the native helper reads it from the selected application. Different bundle identifiers require different decisions, even when users consider them versions of one product. + +Revocation applies to every installation sharing the identifier. Tests exercise unsigned copies, different identifiers, missing identifiers with persistent path consent, process restarts, symlink aliases, pending and running identity agreement, shared handle revocation and refusal to widen old grants. diff --git a/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.zh.md b/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.zh.md new file mode 100644 index 0000000000..bfc0bc5020 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-25-cua-bundle-id-consent.zh.md @@ -0,0 +1,33 @@ +# Agent Note: 按 Bundle ID 共用 macOS 应用授权 + +Status: implemented + +[English](2026-10-25-cua-bundle-id-consent.md) | 中文 + +## 问题 + +用户安装同一应用的多个版本时，希望对这个软件只做一次权限决定。可执行文件路径会拆分这些决定，签名检查也会让未签名的开发版应用无法保存长期授权。 + +## 决策 + +macOS 应用授权使用原生应用提供的、区分大小写的完整 Bundle ID。helper 将 `macos:bundle-id:` 和该标识连接后计算摘要，生成 `CuaApplicationId`。有 Bundle ID 时，安装路径、版本和签名不区分授权。否则，helper 对 `macos:executable-path:` 与规范化可执行路径计算摘要。两种身份都支持长期许可；路径身份在重启和原地更新后保持不变，另一个路径需要新的决定。会话决定和长期许可保留[profile 授权存储](2026-10-19-cua-profile-consent-storage.zh.md)规定的范围和撤销行为。 + +本决策取代[应用授权](2026-09-26-cua-application-consent.zh.md)中的可执行文件和签名身份选择，原记录仍负责执行检查与用户决定。运行进程的可执行路径由操作系统提供。有效的运行时 Bundle ID 不依赖路径查询成功。无法取得路径时省略授权记录中的可选路径信息，不用缓存的应用目录路径代替。Bundle ID 和实际路径均不可用时，授权失败并报告路径查询原因。进程身份仍须验证，可取得的实际路径仍须与所选目标一致。只要能取得实际进程路径，应用目录信息中缺少路径不会阻止授权。运行时无法取得 Bundle ID 时，仅在其报告的应用 bundle 主可执行文件与进程路径一致时读取该标识，否则按可执行路径识别授权。原生进程、可执行文件位置和窗口检查继续把每个句柄绑定到所选目标。启动检查从磁盘重新读取 Bundle ID 和可执行路径，但不计算可执行内容指纹。因此，在相同路径下替换内容且保留相同标识或路径身份时，许可仍会沿用，包括等待用户批准期间的替换。 + +身份前缀将新授权与旧的路径和签名、进程实例、可执行内容摘要分开。旧授权仍可撤销，但不能授予新 Bundle ID 身份访问权限；许可覆盖其他安装副本前，需要用户重新决定。 + +Apple 的 [PPPC 配置](https://support.apple.com/guide/deployment/privacy-preferences-policy-control-payload-dep38df53c2a/web)支持 Bundle ID 或路径选择条件，同时另行要求代码签名条件。[TN3127](https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements)说明了指定要求如何跨版本识别代码，以及未签名和临时签名代码无法提供同等稳定性。DSH 采用这两种选择条件管理应用，不要求验证发布者身份。 + +## 考虑过的替代方案 + +**Bundle ID 加路径。** 可以区分安装副本，但用户希望共同授权的多个版本仍需分别确认。 + +**仅使用 Bundle ID。** 缺少标识会让本可操作的应用无法获得长期许可。规范化可执行路径提供稳定的后备标识，无须使用进程号或内容摘要。 + +**验证签名身份。** 可以区分发布者，但没有签名或验签失败时无法保存长期授权。发布者身份验证不属于本项应用管理规则。 + +## 后果 + +其他程序声明相同 Bundle ID，或替换路径授权对应的可执行文件时，会继承许可，包括通过其他已授权模型工具创建或修改的程序。最坏后果是在应用已有数据和能力范围内，读取或控制用户未单独批准的程序。模型不能在 CUA 请求中提交授权身份，该身份由原生 helper 从实际选中的应用读取。不同 Bundle ID 仍需分别授权，即使用户将它们视为同一产品的不同版本。 + +撤销作用于同一标识的所有安装副本。测试覆盖未签名副本、不同标识、缺少标识时的持久路径许可、进程重启、符号链接、启动前后身份一致、多个句柄共同撤销，以及不扩大旧授权。 diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.i18n.yaml new file mode 100644 index 0000000000..e910137117 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-09-20-unambiguous-tool-arguments.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 .agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.md +/agent-note-unambiguous-tool-argument-compatibility: + en: dcb2b9835f9ee758 + zh: 68be9713f74571c4 +/agent-note-unambiguous-tool-argument-compatibility/problem: + en: c389c332bdadbbe4 + zh: 217520278ccf0932 +/agent-note-unambiguous-tool-argument-compatibility/decision: + en: 71c04efcfd972b02 + zh: d1f842920b1b0e3f +/agent-note-unambiguous-tool-argument-compatibility/alternatives-considered: + en: b2a96695819a978f + zh: c6f84b244be0dddf +/agent-note-unambiguous-tool-argument-compatibility/consequences: + en: bd24ad737c617c90 + zh: dbb7fa67c41af828 diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.md b/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.md new file mode 100644 index 0000000000..7e2a5111c3 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.md @@ -0,0 +1,25 @@ +# Agent Note: Unambiguous tool argument compatibility + +Status: implemented + +English | [中文](2026-09-20-unambiguous-tool-arguments.zh.md) + +## Problem + +Models can populate optional fields that do not affect the requested operation. Rejecting these calls adds retries without protecting any state. + +## Decision + +`grep` treats an exact empty `include` as omitted. Whitespace-only, negated, and comma-separated filters remain invalid. `update_goal` uses replacement fields only for `edit` and a blocker reason only for `blocked`; other actions ignore those known fields. Declared types, consumed values, authority, and exact revisions remain validated. Ignored fields never reach another goal operation or change unrelated state, and call summaries select only values used by the action. `write` and `edit` allow absent or blank justification when no sandbox mode is requested or the effective mode is repeated; actual widening retains its reason and approval requirements, and filesystem observation and denial checks remain active. + +This partially supersedes the unused-field rejection in the [goal-tool decision](../feature/2026-07-19-model-facing-goal-tools.md). Its authority, lifecycle, scheduling, and persistence decisions remain active. The rules apply to every provider and stay inside the owning tool rather than weakening its underlying service. + +## Alternatives considered + +- **Complete strict-schema adaptation first** — deferred because it is a separate provider-wide change; these cases have deterministic meanings and direct regression evidence. +- **Normalize all empty, null, or zero values** — rejected because such values can be meaningful input, including empty file contents and numeric limits. +- **Reject every populated inactive field** — rejected because the explicit action determines the goal operation, and unused fields cannot alter it. + +## Consequences + +The tools accept these calls without extra mutations. Unit tests cover ignored fields for every goal action, consumed-field and authority failures, stale revisions, filter validation, and real search results. A headless recorded-session scenario verifies both file extensions are searched and completion preserves the original objective and round cap. These rules give up detecting conflicting intent expressed only in inactive goal fields; they do not weaken authorization or establish a generic coercion policy. diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.zh.md b/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.zh.md new file mode 100644 index 0000000000..6887d9feb8 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-20-unambiguous-tool-arguments.zh.md @@ -0,0 +1,25 @@ +# Agent Note: 无歧义的工具参数兼容 + +Status: implemented + +[English](2026-09-20-unambiguous-tool-arguments.md) | 中文 + +## 问题 + +模型可能填写不影响所请求操作的可选字段。拒绝这些调用只会增加重试，并不保护任何状态。 + +## 决策 + +`grep` 将值恰好为空字符串的 `include` 视为省略。仅含空白、否定形式和逗号分隔的过滤器仍然无效。`update_goal` 仅在 `edit` 时使用替换字段，仅在 `blocked` 时使用阻塞原因；其他 action 忽略这些已知字段。声明的类型、实际使用的值、权限和精确修订号仍会校验。被忽略的字段不会传入另一种目标操作，也不会改变无关状态；调用摘要仅选择当前 action 使用的值。未请求沙箱模式或重复当前生效模式时，`write` 和 `edit` 允许省略理由或提供空白理由；真正升权仍需理由和审批，文件系统观察与拒绝检查继续生效。 + +本决策部分取代[目标工具决策](../feature/2026-07-19-model-facing-goal-tools.zh.md)中对无关字段的拒绝规则。其权限、生命周期、调度和持久化决策继续生效。这些规则适用于所有提供方，并保留在所属工具内，不削弱底层服务的校验。 + +## 考虑过的替代方案 + +- **先完成严格 schema 适配**——暂缓，因为这是单独的提供方级改造；这些情况具有确定含义和直接的回归证据。 +- **统一规范化所有空值、null 或零值**——不予采纳，因为这些值可能是有意义的输入，包括空文件内容和数值限制。 +- **拒绝所有已填写的非当前 action 字段**——不予采纳，因为显式 action 决定目标操作，而未使用的字段无法改变该操作。 + +## 后果 + +工具接受这些调用，且不会产生额外变更。单元测试覆盖每种目标 action 对无关字段的忽略、有效字段与权限失败、陈旧修订号、过滤器校验以及真实搜索结果。headless 会话回放验证两种扩展名的文件都参与搜索，并且完成操作保留原始目标和轮数上限。这些规则放弃检测仅由非当前 action 的目标字段表达的冲突意图；它们不削弱授权，也不建立通用类型转换策略。 diff --git a/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.i18n.yaml new file mode 100644 index 0000000000..5b65ef830c --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-25-shared-preset-delegation-tools.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 .agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.md +/agent-note-shared-preset-delegation-tools: + en: 2f33b8a19d8291b8 + zh: 4f49de632ac53d01 +/agent-note-shared-preset-delegation-tools/problem: + en: 3150532ae6efd14c + zh: 3c3d662c5bcb323b +/agent-note-shared-preset-delegation-tools/decision: + en: ccaa0792d54fe79d + zh: b2993214c35c1db0 +/agent-note-shared-preset-delegation-tools/alternatives-considered: + en: 2f53caf2af750178 + zh: cd4d9b823a9348dc +/agent-note-shared-preset-delegation-tools/consequences: + en: 4aaaaec2038b3f1d + zh: b52bdd02118ffb6f diff --git a/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.md b/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.md new file mode 100644 index 0000000000..5fc077b02c --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.md @@ -0,0 +1,31 @@ +# Agent Note: Shared preset delegation tools + +Status: implemented + +English | [中文](2026-10-25-shared-preset-delegation-tools.zh.md) + +## Problem + +Agents sharing a preset need the same delegation definitions immediately after a preset switch. Installing identical tools separately for each Agent introduces an asynchronous visibility gap and places those definitions in the Agent's own registration layer, which is exempt from inherited-tool restrictions. + +## Decision + +Each tool-subagent instance registers its definition in its owning composition. Agents sharing a preset revision inherit that registration. Switching presets changes ancestry; it requires no per-Agent installation or tool-change reconciliation. Provider availability and the owning composition's disposal control registration lifetime. + +Tool configuration validates its own fields, allowlist consistency, required services and provider capabilities. Candidate preset documents are not read during registration, for either Host-mounted or preset-mounted tools. The delegation executor validates the model's selection against the allowlist; child startup resolves the selected id against the current registry. A later declaration can therefore satisfy a previously unavailable target without reinstalling the tool. Independent selection and restoration retain the [spawn preset semantics](../feature/2026-09-20-spawn-agent-preset-selection.md). + +The schema contains preset ids and default or inheritance guidance without candidate descriptions. This keeps shared definitions independent of other presets' declaration order and avoids retaining document text that can become stale. [Awaited Agent initialization](../architecture/2026-09-09-awaited-agent-creation.md) remains necessary for other asynchronous contributions. + +## Alternatives considered + +**Reinstall tools for each Agent.** Identical definitions gain extra installation, disposal and reconciliation work, and Agent-local ownership prevents inherited-tool restrictions from applying. + +**Validate every target at tool registration.** A target declared later is rejected even though it can be available when used. An early successful lookup also cannot guarantee availability after registry changes. + +**Retain candidate descriptions in shared schemas.** Reading descriptions during registration makes the result depend on declaration order. Keeping those descriptions current requires additional update coordination; the tool exposes ids instead. + +## Consequences + +Unknown or unloadable targets fail the selected delegation without leaving a child Agent or Session. An unused invalid reference remains undetected. Agent restrictions and restored historical filters apply to inherited delegation schemas, execution and guidance; sibling Agents retain their tools. + +Focused preset-selection tests cover immediate switch visibility, shared ownership and disposal, restrictions, missing targets and retry after declaration. The Web Loader cases cover shipped composition compatibility, and the headless preset snapshot pins model-visible choices. The historical-filter tests exercise child composition directly; they do not establish cold-resume coverage. diff --git a/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.zh.md b/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.zh.md new file mode 100644 index 0000000000..3c3cadfd1a --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.zh.md @@ -0,0 +1,31 @@ +# Agent Note: 预设共享委派工具 + +Status: implemented + +[English](2026-10-25-shared-preset-delegation-tools.md) | 中文 + +## 问题 + +共享预设的 Agent（智能体）需要在预设切换完成后立即取得相同的委派定义。为每个 Agent 分别安装相同工具会产生异步可见性缺口，并将定义放在 Agent 自身的注册层，而该层不受继承工具限制约束。 + +## 决策 + +每个 tool-subagent 实例在所属组装中注册定义。共享同一预设代际的 Agent 继承该注册。切换预设只改变祖先关系，无须按 Agent 安装或协调工具变更。提供方可用性及所属组装的 dispose（资源释放）决定注册的生命周期。 + +工具配置校验自身字段、白名单一致性、必需服务及提供方能力。Host 挂载和预设内挂载的工具都不在注册时读取候选预设文档。委派执行器按白名单校验模型选择，子级启动时再从当前注册表解析所选 id。因此，后续声明能够使原先不可用的目标变得可用，无须重新安装工具。独立选择与恢复保留 [spawn 预设语义](../feature/2026-09-20-spawn-agent-preset-selection.zh.md)。 + +schema 包含预设 id 及默认或继承提示，不包含候选描述。这使共享定义不依赖其他预设的声明顺序，也避免保留可能陈旧的文档文本。其他异步贡献仍需要[等待 Agent 初始化](../architecture/2026-09-09-awaited-agent-creation.zh.md)。 + +## 考虑过的替代方案 + +**为每个 Agent 重新安装工具。** 相同定义需要额外的安装、释放与协调工作，Agent 本地所有权还会阻止继承工具限制生效。 + +**在工具注册时校验所有目标。** 后声明的目标即使在使用时可用，也会被拒绝。提前查找成功同样无法保证注册表变更后的可用性。 + +**在共享 schema 中保留候选描述。** 注册时读取描述会使结果依赖声明顺序。保持描述同步需要额外的更新协调；工具选择公开 id。 + +## 后果 + +未知或无法加载的目标会使选中它的委派失败，不残留子 Agent 或 Session。未使用的无效引用仍不会被发现。Agent 限制及恢复的历史过滤器约束继承的委派 schema、执行与指导文本；同级 Agent 保留各自的工具。 + +针对性预设选择测试覆盖切换完成时的即时可见性、共享所有权与释放、限制、缺失目标及补声明后重试。Web Loader 用例覆盖 shipped 组装兼容性，headless 预设快照固定模型可见选项。历史过滤器测试直接执行子级组装，不证明冷恢复覆盖。 diff --git a/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.i18n.yaml new file mode 100644 index 0000000000..22e56fbdd0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-26-malformed-charset-declaration.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 .agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.md +/agent-note-malformed-charset-recovery-prefers-utf-8: + en: d8a759b84c36b308 + zh: 3b6ff2eb5519afb1 +/agent-note-malformed-charset-recovery-prefers-utf-8/problem: + en: dce96445b3801a7f + zh: e026d26fa680556a +/agent-note-malformed-charset-recovery-prefers-utf-8/decision: + en: ba74ad57757231ca + zh: 46999cd0100814ae +/agent-note-malformed-charset-recovery-prefers-utf-8/alternatives-considered: + en: 9fafffb6a7a78a29 + zh: ee1dcc27d0315e68 +/agent-note-malformed-charset-recovery-prefers-utf-8/consequences: + en: c8aad3cc3f02e81e + zh: 29d9313afd1c7b5b diff --git a/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.md b/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.md new file mode 100644 index 0000000000..9e36964e09 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.md @@ -0,0 +1,33 @@ +# Agent Note: Malformed charset recovery prefers UTF-8 + +Status: implemented + +English | [中文](2026-10-26-malformed-charset-declaration.zh.md) + +## Problem + +A response can declare `charset=utf-8,gbk` over readable UTF-8 HTML. Passing that entire parameter to `TextDecoder` rejects the page before reading it. Compatibility needs an explicit encoding preference because successful decoding alone cannot identify the server's intended encoding. + +## Decision + +`decoderForCharset` preserves valid single-label declarations and the absent-header UTF-8 default. If a declaration is unsupported as a whole, it checks its comma- and whitespace-separated labels for UTF-8, including standard aliases. A match selects a fatal UTF-8 decoder; otherwise the declaration fails before the response body is read and the provider cancels the stream. + +The provider decodes once. Recovery rejects invalid UTF-8 with `WEB_UNSUPPORTED_CONTENT_TYPE` and preserves the decoding error as its cause. Only an actual byte-cap truncation enables streaming decode, which omits an incomplete suffix and keeps `truncated: true`. Complete responses, including those exactly at the cap, validate the final sequence at EOF. + +UTF-8 recovery is an explicit heuristic, not proof of the original encoding. The bytes `C2 A9` represent `©` in UTF-8 and `漏` in GBK; repeating them preserves that ambiguity at any length. The provider accepts that ambiguity for UTF-8 recovery but does not extend it to arbitrary legacy-encoding guesses. + +## Alternatives considered + +**Choose the first declared encoding that decodes.** A GBK body can also decode as `windows-1252` with different text. Declaration order does not resolve the conflict, and single-byte encodings can turn a decoding failure into silent corruption. Rejected. + +**Use strict probes followed by ordinary decoding.** This decodes successful bodies twice. An unflushed streaming probe also accepts an incomplete EOF sequence that the ordinary decoder replaces. One fatal decode with explicit truncation state is sufficient. + +**Read BOM and HTML meta declarations.** This would add HTML encoding identification and a dependency or parser, with a separate policy for missing metadata and non-HTML content. It remains deferred; the bounded UTF-8 preference resolves the reported response without claiming browser-equivalent detection. + +## Consequences + +- Malformed declarations containing UTF-8 can return readable text; a failed UTF-8 recovery never falls back to another encoding or inserts replacement characters. +- Malformed declarations without a UTF-8 label remain unsupported, including repeated legacy aliases. Valid single-label legacy decoding is unchanged. +- [`fetch-http.spec.ts`](../../../../packages/web/web-fetch-http/tests/fetch-http.spec.ts) covers recovery, conflicting labels, invalid bytes, EOF, truncation, and response-stream cancellation. +- The recorded [`web-fetch`](../../../../snapshots/session/web-fetch/snapshot.yml) scenario serves literal UTF-8 characters with `charset=gbk,utf-8` through the real HTTP provider and verifies the same model-visible text. +- HTML `` remains ignored. The package README documents the remaining ambiguity. diff --git a/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.zh.md b/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.zh.md new file mode 100644 index 0000000000..8e9d1f31ed --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-26-malformed-charset-declaration.zh.md @@ -0,0 +1,33 @@ +# Agent Note: 畸形 charset 声明的恢复优先使用 UTF-8 + +Status: implemented + +[English](2026-10-26-malformed-charset-declaration.md) | 中文 + +## Problem + +响应可能在可读的 UTF-8 HTML 上声明 `charset=utf-8,gbk`。把整个参数交给 `TextDecoder` 会在读取前拒绝页面。兼容处理需要明确的编码优先规则，因为解码成功本身无法识别服务器原本使用的编码。 + +## Decision + +`decoderForCharset` 保留合法的单标签声明，以及未声明时默认使用 UTF-8 的行为。如果整个声明不受支持，它检查按逗号和空白分隔的标签是否包含 UTF-8（含标准别名）。匹配时选择 fatal UTF-8 解码器；否则在读取正文前拒绝声明，由提供方取消响应流。 + +提供方只解码一次。恢复路径以 `WEB_UNSUPPORTED_CONTENT_TYPE` 拒绝非法 UTF-8，并保留解码错误作为 cause。只有真正触发字节上限截断时才启用流式解码，省略不完整的末尾序列并保持 `truncated: true`。完整响应（包括恰好达到上限的响应）在 EOF 校验末尾序列。 + +UTF-8 恢复是明确的启发式规则，不是原始编码的证明。字节 `C2 A9` 在 UTF-8 下表示 `©`，在 GBK 下表示 `漏`；重复这些字节后，任意长度都保留该歧义。提供方为 UTF-8 恢复接受这种歧义，但不将其扩展为任意传统编码的猜测。 + +## Alternatives considered + +**选择声明中第一个能解码的编码。** GBK 正文也可能按 `windows-1252` 解出不同文本。声明顺序不能解决冲突，单字节编码还可能把解码失败变成静默的内容损坏。拒绝。 + +**先严格探测，再常规解码。** 这会对成功的正文解码两次。未结束的流式探测还会接受 EOF 处不完整的序列，随后被常规解码器替换。一次 fatal 解码配合显式截断状态已经足够。 + +**读取 BOM 和 HTML meta 声明。** 这会增加 HTML 编码识别能力及依赖或解析器，还需单独规定缺少元数据和非 HTML 内容的策略。继续延期；有范围的 UTF-8 优先规则可以处理所报告的响应，无需宣称与浏览器等价的编码检测。 + +## Consequences + +- 含有 UTF-8 的畸形声明可以返回可读文本；UTF-8 恢复失败时不会回退到其他编码，也不会插入替换字符。 +- 不含 UTF-8 标签的畸形声明仍不受支持，包括重复的传统编码别名。合法的单标签传统编码解码保持不变。 +- [`fetch-http.spec.ts`](../../../../packages/web/web-fetch-http/tests/fetch-http.spec.ts) 覆盖恢复、冲突标签、非法字节、EOF、截断和响应流取消。 +- 已录制的 [`web-fetch`](../../../../snapshots/session/web-fetch/snapshot.yml) 场景通过真实 HTTP 提供方，以 `charset=gbk,utf-8` 提供包含原样 UTF-8 字符的页面，并验证相同的模型可见文本。 +- HTML `` 仍然被忽略。包 README 记录了剩余歧义。 diff --git a/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.i18n.yaml new file mode 100644 index 0000000000..99a0eb8afa --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-28-forge-git-session-permissions.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 .agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.md +/agent-note-session-permissions-for-forge-git-queries: + en: a06c42342d1f0bad + zh: 88b063883336cb0b +/agent-note-session-permissions-for-forge-git-queries/problem: + en: ee1e5ba8190a9419 + zh: 88d6c35a3a400eb0 +/agent-note-session-permissions-for-forge-git-queries/decision: + en: 77d7706b2577e552 + zh: a4538a19656d5945 +/agent-note-session-permissions-for-forge-git-queries/alternatives-considered: + en: 69f0bbbc412a546f + zh: 9527e87b5adfc7c3 +/agent-note-session-permissions-for-forge-git-queries/consequences: + en: acf5249a959ac14c + zh: 268fc51ec3278dcb diff --git a/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.md b/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.md new file mode 100644 index 0000000000..fd753156d0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.md @@ -0,0 +1,31 @@ +# Agent Note: Session permissions for Forge Git queries + +Status: implemented + +English | [中文](2026-10-28-forge-git-session-permissions.zh.md) + +## Problem + +The [Forge panel](../feature/2026-10-09-forge-panel.md) forces read-only confinement even when a Session grants full access. On hosts without a usable sandbox, its checkout and local changes remain unavailable while the Session's shell works. Background queries also reach repository-configured executable helpers through working-tree comparisons. + +## Decision + +Git inspection uses the Session's resolved sandbox mode and subprocess provider. Full access requires no sandbox backend; confined modes retain their enforcement and never retry unconfined. The Session remains the authority for filesystem permissions, including workspace-write access. Query commands do not request repository mutations. + +Local patches and statistics apply command-local Git configuration to disable clean/process filters without changing user configuration. Environment entries preserve subsection names containing equals signs. Existing hook, fsmonitor, external-diff, textconv, optional-lock, and lazy-fetch restrictions remain; submodule queries show commit changes without scanning internal dirty files. Configuration read failure stops the comparison; the changes view reports the filter configuration failure separately from oversized diffs and offers a retry. These restrictions follow the informational-diff approach in Codex while retaining DSH's execution-world and cancellation ownership. + +## Alternatives considered + +**Force read-only for every query.** This makes an explicitly unconfined Session depend on an unavailable backend. Using the Session mode keeps tool and panel permission behavior consistent. + +**Retry without confinement after failure.** This would silently grant authority that a restricted Session does not have. + +**Run configured content converters.** They can execute programs and write files during automatic refresh. Disabling them trades converted-content equivalence for predictable query behavior. + +## Consequences + +Operating-system write protection follows the Session mode rather than a separate panel policy. With clean/process filters disabled, comparisons still apply Git's built-in newline, ident, and encoding conversions: materialized LFS and other filtered files can appear changed even when ordinary Git considers them clean. Pointer-only checkouts compare normally. Uncommitted submodule contents are omitted. The original Forge note remains active for panel ownership and worktree lifecycle; this note supersedes only its unconditional read-only policy. + +Filter overrides require Git 2.31 or newer; older Git can ignore them and execute configured helpers under Session permissions. Enumeration and diff run in separate processes, so a concurrently added driver can escape the overrides. These restrictions limit incidental helper execution; the Session sandbox determines the permissions of every process that runs. + +Real-repository tests cover permission modes, unavailable confinement, unchanged index/configuration, configured helper markers, submodule commits, filtered bytes, and failed filter enumeration. The Web replay covers permission changes through the picker and the resulting checkout and local-change view. diff --git a/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.zh.md b/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.zh.md new file mode 100644 index 0000000000..49ad8f7be5 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-28-forge-git-session-permissions.zh.md @@ -0,0 +1,31 @@ +# Agent Note: Forge Git 查询的 Session 权限 + +Status: implemented + +[English](2026-10-28-forge-git-session-permissions.md) | 中文 + +## 问题 + +[Forge 面板](../feature/2026-10-09-forge-panel.zh.md)即使在 Session 授予完全权限时也强制使用只读沙箱。在没有可用沙箱的主机上，Session 的 shell 可以工作，检出信息与本地变更却持续不可用。后台查询还会通过工作区比较执行仓库配置的辅助程序。 + +## 决策 + +Git 检查使用 Session 解析出的沙箱模式与子进程提供方。完全权限无需沙箱后端；受限模式保留强制约束，绝不以无沙箱方式重试。Session 统一决定文件系统权限，包括工作区写入权限。查询命令不请求修改仓库。 + +本地补丁与统计应用命令级 Git 配置以禁用 clean/process filter，不修改用户配置。环境项保留包含等号的子节名称。现有钩子、fsmonitor、外部 diff、textconv、可选锁与延迟获取限制继续生效；子模块查询展示提交变化，不扫描内部脏文件。配置读取失败时停止比较；变更视图区分过滤器配置失败与 diff 过大，并提供重试。这些限制参考 Codex 的信息展示型 diff，同时保留 DSH 对执行环境与取消过程的管理。 + +## 考虑过的替代方案 + +**所有查询强制只读。** 这让已明确取消限制的 Session 依赖不可用的后端。使用 Session 模式使工具与面板的权限行为一致。 + +**失败后无沙箱重试。** 这会静默授予受限 Session 原本没有的权限。 + +**运行已配置的内容转换器。** 它们可能在自动刷新时执行程序并写入文件。禁用它们以放弃转换后内容等价性为代价，换取可预测的查询行为。 + +## 后果 + +操作系统的写入保护跟随 Session 模式，而非独立的面板策略。禁用 clean/process filter 后，比较仍应用 Git 内置的换行、ident 与编码转换：已物化的 LFS 文件及其他过滤文件可能显示为变更，即使普通 Git 认为它们未变。仅保留指针的检出可正常比较。子模块内部未提交内容不显示。原 Forge 记录仍保留面板所有权与工作树生命周期的决策；本记录仅替代其无条件只读策略。 + +过滤器覆盖需要 Git 2.31 或更新版本；旧 Git 可能忽略覆盖，按 Session 权限执行已配置的辅助程序。枚举与 diff 在独立进程中执行，因此并发新增的驱动可能绕过覆盖。这些限制减少附带的辅助程序执行；所有实际运行进程的权限由 Session 沙箱决定。 + +真实仓库测试覆盖权限模式、沙箱不可用、索引与配置不变、辅助程序标记、子模块提交、过滤文件字节和过滤器枚举失败。Web 回放覆盖通过选择器切换权限及相应的检出信息与本地变更视图。 diff --git a/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.i18n.yaml new file mode 100644 index 0000000000..aaf821df79 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.i18n.yaml @@ -0,0 +1,25 @@ +# Bilingual-pair consistency record for 2026-10-28-plugin-install-failure-diagnostics.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 .agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.md +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog: + en: dc13db49685fee98 + zh: 65896465ceaba16a +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/problem: + en: 34c85dbc0fdaeeaf + zh: b11042edb1eb8e3b +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/decision: + en: fa3f10f9d7502077 + zh: c6b83153a0f5e324 +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/alternatives-considered: + en: 2616d060183a7a74 + zh: 15179fd42ea2b6dc +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/consequences: + en: 246d2a60f856c631 + zh: d7a552af3ad32b6f +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/related: + en: e0709383c16148e9 + zh: 00765408d0ad25f1 +/agent-note-install-failures-keep-their-diagnostics-in-the-dialog/testing: + en: 336df2ffde183519 + zh: 86e62a8a052c1f91 diff --git a/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.md new file mode 100644 index 0000000000..89712bf9f7 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.md @@ -0,0 +1,47 @@ +# Agent Note: Install failures keep their diagnostics in the dialog + +Status: implemented + +English | [中文](2026-10-28-plugin-install-failure-diagnostics.zh.md) + +## Problem + +A failed plugin installation could show the generic sentence "Something went wrong during the install; the details say what" while its expanded details showed only "No output". The dialog rendered the live install-log stream and the failure kind, and the two Host diagnostics that explain such a failure never entered that stream. A pnpm run that printed nothing had its diagnostic (`result.shortMessage`, or `pnpm failed` as the fallback) written to the complete log and the returned result but never streamed, so the dialog's terminal stayed empty. The GitHub connection check that stops an installation before pnpm runs kept its captured output only in `packageResult.output`. The Client also ignored the settled result's `packageResult.logPath` and `stage`, so a failure with recorded diagnostics offered no path to the complete log and could not say that a finished installation failed while the bundle was being activated. + +## Decision + +**The install-log stream carries the Host diagnostic of every run the dialog shows.** A pnpm run that fails without printing anything streams the diagnostic the Host records for it, so the complete log and the dialog show the same text. The GitHub connection check reports the `git … ls-remote` command line it ran, with the user information of an http(s) repository URL removed; when its network failure or timeout stops the installation, `installBundle` emits that command, the captured output, and the failure's exit status as the installation's only install-log run under the caller's request id. A check failure the installation survives streams nothing. A timed-out check's Git returned no exit status, so that run settles without one; the returned result records the coerced status 1, because `PackageResult.exitCode` is a number, and `PackageResult.timedOut` states that the status is the one the failure is read as. The command line itself stays module-local: `installBundle` strips it off the plain `PackageResult` it returns, so no second wire field appears. + +**The failed screen keeps what the settled result reports, not only the live stream.** `InstallState` holds the settled `packageResult.logPath` — the run that settled the dialog, on the Host's filesystem — and the details name it as the complete log. `InstallState['failure'].stage` and `ChangeResult.enabled` add the sentence that the installation finished and enabling the bundle failed, only when that change did ask to enable it; an install that left activation to **Enable now** never claims it failed enabling. Details on a settled screen without a streamed run say the dialog received no terminal output, never that the run printed none, and a running install makes no such claim. The generic sentence names the failed install command, except when the failed step is applying an enabled bundle, where the enabling sentence stands alone. The answer and the log travel over separate transports, so a run whose first chunk arrives after the answer is kept in the settled dialog as a settled run rather than dropped or shown as running. + +No wire type, public export, or config key is added: `ChangeResult.packageResult.logPath`, `ChangeResult.stage`, `ChangeResult.enabled`, and `packageResult.timedOut` already carry these facts to every consumer. The check's command line is a module-local `GithubConnectionFailure` in `github-connection.ts`. + +## Alternatives considered + +**Have the Client synthesize a terminal run from `packageResult.output`.** Rejected: the install-log stream would stay incomplete for every other reader, including the agent tool and the complete Host log, and the dialog would carry two notions of a run — one streamed, one rebuilt from the result. + +**Render `packageResult.output` as a separate Host-diagnostic block.** Rejected: it duplicates the terminal surface with a second styling and copy path, and the failing check's command line would still be missing. + +**Add a failure-stage field to `ChangeResult`.** Rejected: `stage` already names installation and activation, and only activation needed its own sentence; a second stage vocabulary would make every consumer learn two fields for one fact. + +**Keep the generic sentence and rely on the details.** Rejected: the empty details panel this fixes was exactly what the sentence pointed at, so the sentence must not promise diagnostics the dialog does not show. + +**Report the check's coerced exit code in the streamed run too.** Rejected: the stream describes what the process did, and a Git the deadline killed returned no status; the result keeps the coerced status only because its exit code is a number, which the JSDoc states. + +## Consequences + +- A failed installation always offers something to act on: a pnpm diagnostic for a silent failure, the failing Git command and its output for a GitHub connection failure, the complete log of the settled run, and a sentence naming the failed step when an enabled installation could not be applied. +- The generic sentence becomes "The install command failed; the details say why" in every dictionary; the details' no-run note says the dialog received no terminal output. +- A GitHub connection failure reports `timedOut` and returns the coerced exit status 1, while its streamed run settles without an exit code; the displayed command line omits URL user information, and no `argv` field joins the Remote answer. +- The details' log path covers the run that settled the dialog and is a Host path, so earlier registry attempts and a remote browser may not reach it. +- No new configuration, wire field, or public package export. + +## Related + +[Guided plugin installation](../architecture/2026-09-15-guided-plugin-installation.md) owns the install dialog's screens, the pre-install spec check, and the failure classification; this note extends its failed screen and install-log stream. + +## Testing + +- `packages/boot/plugin-manager/tests/operations.spec.ts` pins the no-output diagnostic stream; `github-connection.spec.ts` pins the recorded command line without URL user information and the timeout state, including the coerced status in the result; `manager.spec.ts` pins the single streamed check run under the request id, its absent exit code on timeout, that the returned `packageResult` carries no command line, and that a check failure pnpm may resolve streams nothing. +- `packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts` pins the settled log path, stage and enablement fact, the run kept when its first chunk arrives after the answer, and the reset on retry; `components.client.spec.tsx` pins the enabling sentence (only for an install that asked to enable), the complete-log line, and the settled no-output sentence. +- `apps/web/tests/plugin-install-github.e2e.ts` expands the details of a real GitHub connection failure and finds the Git command, its output, and the log path; `apps/web/tests/plugin-install-silent-failure.e2e.ts` fails a real installation through a package manager that prints nothing and finds the run's command line, its diagnostic, and the complete log in the details. diff --git a/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.zh.md new file mode 100644 index 0000000000..5c8220ed13 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-10-28-plugin-install-failure-diagnostics.zh.md @@ -0,0 +1,47 @@ +# Agent Note: Install failures keep their diagnostics in the dialog + +Status: implemented + +[English](2026-10-28-plugin-install-failure-diagnostics.md) | 中文 + +## Problem + +一次插件安装失败时，界面可能显示通用的“安装过程中出错，原因见安装详情”，而展开后的详情只有“无输出”。对话框渲染的是实时的 install-log 流和失败 kind，而解释这类失败的 Host 诊断从未进入该流。打印了空输出的 pnpm 运行，其诊断（`result.shortMessage`，缺省为 `pnpm failed`）只写进完整日志和返回结果，从未被流式发送，因此对话框的终端一直是空的。在 pnpm 运行前就中止安装的 GitHub 连接检查，其捕获的输出只留在 `packageResult.output` 里。客户端同时也忽略了已结束结果中的 `packageResult.logPath` 和 `stage`，所以即使诊断已被记录，失败界面也没有指向完整日志的入口，也无法说明安装其实已经完成、失败发生在启用 bundle 时。 + +## Decision + +**install-log 流携带对话框所展示的每一次运行的 Host 诊断。** 没有打印任何内容就失败的 pnpm 运行，会把 Host 为其记录的那条诊断流式发送出来，于是完整日志和对话框显示同样的文本。GitHub 连接检查会报告它实际执行的 `git … ls-remote` 命令行，并去掉 http(s) 仓库 URL 中的用户信息；当它的网络失败或超时中止安装时，`installBundle` 把该命令、捕获的输出和这次失败的退出状态作为该次安装唯一的 install-log 运行、以调用方的 request id 发出。安装仍能继续进行的检查失败不发送任何内容。超时的检查里 Git 没有返回退出状态，所以该运行不带退出码结束；返回结果记录强制填入的状态 1，因为 `PackageResult.exitCode` 是数字，而 `PackageResult.timedOut` 说明该状态只是失败被读取成的状态。命令行本身仍只在模块内：`installBundle` 在返回的普通 `PackageResult` 上剥掉它，因此不会多出 wire 字段。 + +**失败界面保留已结束结果所报告的内容，而不只是实时流。** `InstallState` 持有已结束的 `packageResult.logPath`——结束对话框的那次运行，位于 Host 文件系统——详情把它标为完整日志。`InstallState['failure'].stage` 与 `ChangeResult.enabled` 补充一句话：安装已完成，启用 bundle 时失败；只有当这次变更确实要求启用时才出现，把启用留给**立即启用**的安装不会声称启用失败。已结束界面里没有任何流式运行的详情会说明对话框没有收到终端输出，而不会断言运行本身没有输出；安装进行中也不会这样说。通用提示句点明失败的是安装命令，但失败步骤是应用已启用的 bundle 时，只使用启用阶段的那句话。安装应答与日志走不同传输，因此首个 chunk 晚于应答到达的运行会作为已结束的运行保留在已结束的对话框里，既不会被丢弃，也不会显示成运行中。 + +不新增 wire 类型、公开导出或配置键：`ChangeResult.packageResult.logPath`、`ChangeResult.stage`、`ChangeResult.enabled` 和 `packageResult.timedOut` 本来就把这些事实带给每个消费方。检查的命令行是 `github-connection.ts` 内模块级的 `GithubConnectionFailure`。 + +## Alternatives considered + +**让客户端从 `packageResult.output` 合成一次终端运行。** 否决：对其他读取方（agent 工具和完整的 Host 日志）来说 install-log 流仍然不完整，而且对话框会出现两种“运行”的概念——一种来自流，一种从结果重建。 + +**把 `packageResult.output` 渲染成单独的 Host 诊断块。** 否决：它会以第二套样式和文案路径重复终端界面，而且失败检查的命令行仍然缺失。 + +**给 `ChangeResult` 新增失败阶段字段。** 否决：`stage` 已经区分安装和启用，而且只有启用需要自己的提示句；第二套阶段词汇会让每个消费方为一个事实学两个字段。 + +**保留通用提示句、只依赖详情。** 否决：这次要修的正是被该提示句指向的空详情面板，因此提示句不能承诺对话框并不显示的诊断。 + +**在流式运行里也报告检查被强制的退出码。** 否决：流描述的是进程实际做了什么，而被期限终止的 Git 没有返回任何状态；结果保留强制状态只是因为它的退出码字段是数字，JSDoc 已写明这一点。 + +## Consequences + +- 安装失败后总有可行动的信息：静默失败时的 pnpm 诊断、GitHub 连接失败时出错的 Git 命令及其输出、结束对话框那次运行的完整日志，以及已启用的安装在应用阶段失败时点名失败步骤的一句话。 +- 通用提示句在所有词典中变为“安装命令失败，原因见安装详情”；详情里的无运行提示改为说明对话框没有收到终端输出。 +- GitHub 连接失败会报告 `timedOut` 并返回强制状态 1，而它的流式运行不带退出码结束；展示的命令行去掉 URL 用户信息，Remote 应答里也不会多出 `argv` 字段。 +- 详情里的日志路径只覆盖结束对话框的那次运行，且是 Host 路径，因此更早的换源尝试与远端浏览器可能都够不到它。 +- 不新增配置、wire 字段或公开包导出。 + +## Related + +[Guided plugin installation](../architecture/2026-09-15-guided-plugin-installation.zh.md) 拥有安装对话框的各个界面、安装前的 spec 检查和失败分类；本记录扩展了它的失败界面和 install-log 流。 + +## Testing + +- `packages/boot/plugin-manager/tests/operations.spec.ts` 钉住无输出诊断的流式发送；`github-connection.spec.ts` 钉住去掉 URL 用户信息的记录命令行与超时状态（含结果里的强制状态）；`manager.spec.ts` 钉住以 request id 发送的唯一检查运行、超时下缺失的退出码、返回的 `packageResult` 不含命令行，以及 pnpm 可能自行解决的检查失败不发送任何运行。 +- `packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts` 钉住已结束的日志路径、stage 与启用事实、首个 chunk 晚于应答到达时保留的运行，以及重试时的重置；`components.client.spec.tsx` 钉住启用阶段的提示句（只对要求启用的安装）、完整日志行，以及已结束界面的无输出提示句。 +- `apps/web/tests/plugin-install-github.e2e.ts` 展开一次真实 GitHub 连接失败的详情，找到 Git 命令、它的输出和日志路径；`apps/web/tests/plugin-install-silent-failure.e2e.ts` 让一次真实安装通过不打印任何内容的包管理器失败，并在详情中找到该运行的命令行、诊断和完整日志。 diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml index 179198d487..e35994c87c 100644 --- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml @@ -12,8 +12,8 @@ en: 0ab1e1c40cb2dac9 zh: b4180b6681c130b2 /agent-note-model-facing-same-session-goal-tools/decision/tools-and-model-contract: - en: 288a819f644611c9 - zh: d6bd7986ba091519 + en: 8589421c225beac0 + zh: d2a49dec31ba260c /agent-note-model-facing-same-session-goal-tools/decision/execution-authority: en: 63a9e7e85303b9f1 zh: d3f1d0c225103cfe @@ -24,8 +24,8 @@ en: 92650dd6648ca455 zh: 5b57276a6a983fea /agent-note-model-facing-same-session-goal-tools/alternatives-considered: - en: e84b9fc4823bcc1e - zh: a125628e4746bf50 + en: 84f7829c020f282b + zh: 37c4366efc9dd8dc /agent-note-model-facing-same-session-goal-tools/consequences: en: e254571a176b37e5 zh: 01f76aff35e3618d diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md index d3dd654e02..0a37311be3 100644 --- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md +++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md @@ -16,7 +16,7 @@ The tool API also needs to preserve the separation between durable state and liv ### Tools and model contract -`get_goal()` returns the current goal or `null`. A non-null result contains the compare-and-set id and revision, objective, durable phase, admitted and maximum goal rounds, any blocker reason, plus the process-local activation observation. `create_goal(objective, max_goal_rounds?)` creates one long-running same-session objective. `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`; replacement fields are valid only for `edit`, while a non-empty `blocked_reason` is required only for `blocked` and persists under the stable `model-reported` code. A durable paused goal rejects `resume` with `GOAL_TOOL_RESUME_PAUSED`; the user-facing command or Web control owns that transition. The executor treats exact empty-string optional fields and a zero `max_goal_rounds` as strict-schema fillers: they count as omitted, an edit still requires at least one meaningful replacement, and all non-filler values retain the action restrictions. +`get_goal()` returns the current goal or `null`. A non-null result contains the compare-and-set id and revision, objective, durable phase, admitted and maximum goal rounds, any blocker reason, plus the process-local activation observation. `create_goal(objective, max_goal_rounds?)` creates one long-running same-session objective. `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`; replacement fields are used only for `edit`, while a non-empty `blocked_reason` is required only for `blocked` and persists under the stable `model-reported` code. A durable paused goal rejects `resume` with `GOAL_TOOL_RESUME_PAUSED`; the user-facing command or Web control owns that transition. For `edit`, exact empty-string objectives and a zero `max_goal_rounds` count as omitted, and at least one meaningful replacement is required. Each action ignores known optional fields it does not use ([rationale](../bug-fix/2026-09-20-unambiguous-tool-arguments.md)). The prompt tells the model that it may infer goal intent from a direct human request in any wording or language, but should not convert routine single-turn work into a goal. It must read the current goal before updating and copy the exact id and revision. On a restored or forked active-but-disarmed goal, a semantic human request to continue is grounds for `resume`. The prompt does not announce the durable paused boundary; execution rejects that attempt with `GOAL_TOOL_RESUME_PAUSED`, and the user-facing resume path owns the transition. Completion is reserved for an achieved objective, and difficulty or uncertainty alone is not a blocker; a block report must name the concrete condition. @@ -48,7 +48,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr - **Authorize from persisted root or fork metadata** — rejected because a fork that becomes an independently resumed top-level session should accept new human authority, while a currently owned child should not. - **Let autonomous rounds edit or resume the goal** — rejected because continuation authority is narrower than authority to redefine or restart the human objective. - **Treat the blocked threshold as an evaluator** — rejected because event counts cannot prove that an obstacle is semantically unchanged or truly terminal. -- **Reject every present action-specific field** — rejected because strict-schema providers can serialize zero-value placeholders for every optional field; only meaningful values can express a conflicting action. +- **Reject every present action-specific field** — rejected because strict-schema providers can serialize zero-value placeholders for every optional field; only meaningful values can express a conflicting action. The [unused-field decision](../bug-fix/2026-09-20-unambiguous-tool-arguments.md) defines which populated fields are ignored. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md index 8c5c502f37..e840230358 100644 --- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md +++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md @@ -16,7 +16,7 @@ Status: implemented ### 工具与模型约定 -`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。持久 paused goal 会以 `GOAL_TOOL_RESUME_PAUSED` 拒绝 `resume`；面向用户的命令或 Web 控件拥有该转换。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。 +`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅在 `edit` 时使用，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。持久 paused goal 会以 `GOAL_TOOL_RESUME_PAUSED` 拒绝 `resume`；面向用户的命令或 Web 控件拥有该转换。对于 `edit`，值恰好为空字符串的目标描述和值为 0 的 `max_goal_rounds` 视为省略，且至少需要一个有实际意义的替换字段。每个 action 都忽略它不使用的已知可选字段（[理由](../bug-fix/2026-09-20-unambiguous-tool-arguments.zh.md)）。 提示词告诉模型：它可以从任何措辞或语言的直接人类请求中推断目标意图，但不应把常规单轮工作转换为目标。更新前必须读取当前目标，并复制准确的 id 和修订号。对于恢复或 fork 后处于活跃但未激活状态的目标，人类在语义上要求继续即可成为执行 `resume` 的依据。提示词不会静态声明持久 paused 的边界；执行时以 `GOAL_TOOL_RESUME_PAUSED` 拒绝该尝试，面向用户的恢复路径拥有该转换。只有目标已经实现时才能标记完成，困难或不确定性本身不构成阻塞；阻塞报告必须说明具体条件。 @@ -48,7 +48,7 @@ Status: implemented - **根据持久的根或 fork 元数据授权**——不予采纳，因为作为顶层会话独立恢复的 fork 应接受新的人类权限，而当前仍受所有权约束的 subagent 则不应接受。 - **允许自主 Round 编辑或恢复目标**——不予采纳，因为继续执行权限比重新定义或重启人类目标的权限更窄。 - **把阻塞阈值当作评估器**——不予采纳，因为事件计数无法证明障碍在语义上未改变或确实不可继续。 -- **拒绝所有已提供的特定操作字段**——不予采纳，因为采用严格 schema 的提供方可能为每个可选字段序列化零值占位符；只有有实际意义的字段值才能表示与指定操作相冲突的另一项操作。 +- **拒绝所有已提供的特定操作字段**——不予采纳，因为采用严格 schema 的提供方可能为每个可选字段序列化零值占位符；只有有实际意义的字段值才能表示与指定操作相冲突的另一项操作。[无关字段决策](../bug-fix/2026-09-20-unambiguous-tool-arguments.zh.md)规定了哪些已填写字段会被忽略。 ## 后果 diff --git a/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.i18n.yaml index 98b9eecb42..cd33be628c 100644 --- a/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.i18n.yaml @@ -9,14 +9,14 @@ en: f62d87b7623a9904 zh: 48bbb7c35298f96c /agent-note-windows-sandbox-rung-raw-acl-restricted-tokens-over-mxc-and-appcontainer/decision: - en: 125dea7427047966 - zh: 1e459b1106597695 + en: 10e9cfb7972cff03 + zh: 8406ba64d72a1fcc /agent-note-windows-sandbox-rung-raw-acl-restricted-tokens-over-mxc-and-appcontainer/acl-diagnosis-and-recovery: en: a5bcdf2a6133abfe zh: 477d4915d61945e3 /agent-note-windows-sandbox-rung-raw-acl-restricted-tokens-over-mxc-and-appcontainer/how-the-restriction-works-why-no-new-identity: - en: ac9b3d800889ea39 - zh: 9db1065b6027f65f + en: 1ba89a61a733b371 + zh: 4fa134ad1b2059a1 /agent-note-windows-sandbox-rung-raw-acl-restricted-tokens-over-mxc-and-appcontainer/alternatives-considered: en: 6119e2aff3b6be5a zh: 4237c596c10e1ee9 @@ -38,3 +38,6 @@ /agent-note-windows-sandbox-rung-raw-acl-restricted-tokens-over-mxc-and-appcontainer/related: en: dd16f0c5815df991 zh: df3c1cf511ee52bf +/agent-note-windows-sandbox-rung-raw-acl-restricted-tokens-over-mxc-and-appcontainer/follow-up-2026-10-26-lua-token-is-dropped: + en: 5262178f0035b215 + zh: 10505c394ea33ee3 diff --git a/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.md b/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.md index a108e42626..6cda3f1970 100644 --- a/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.md +++ b/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.md @@ -10,7 +10,7 @@ The original [historical sandbox decision](../../archived/feature/2026-07-06-san ## Decision -Implement the rung directly on the raw ACL mechanism: duplicate the caller's token into a `WRITE_RESTRICTED` token (`CreateRestrictedToken` with `WRITE_RESTRICTED` + `DISABLE_MAX_PRIVILEGE` + `LUA_TOKEN`) whose restricting SIDs carry distinct workspace and private-temp capabilities. `WRITE_RESTRICTED` intersects write accesses only, so reads keep the caller's ambient access while a write must also match one of these capability ACEs. That intersection covers only the object's own access check, and Windows also authorizes a write or a delete from the PARENT directory's `FILE_DELETE_CHILD` right — which no restricting SID has to co-sign, so `cmd /c del` deleted files outside the workspace wherever the caller's ambient SIDs hold Modify. The token is therefore also lowered to Low integrity and every granted directory receives a Low no-write-up mandatory label in the same call that adds its ACE; the kernel applies that policy inside the access check, whichever right supplied the authority, so the granted roots stay writable and everything else becomes delete-proof as well as write-proof. Because every granted root is labeled Low, the integrity check alone would still let one confined child delete inside ANOTHER granted root (another workspace, a live sibling temp directory), so each grant also DENIES `FILE_DELETE_CHILD` to the world SID: the capability ACE's DELETE bit becomes the only delete authority inside a granted root, for the confined child and for the user's own processes, whose ordinary deletes keep working because the same DACL grants them DELETE directly. The mechanism is the one huoyaoyuan/windows-acl-restrict-poc (`10e4dfb`) demonstrates; this port checks every API call and fails closed (the POC fail-opened on ignored failures). The per-workspace SID is derived deterministically from the canonical workspace path (`workspaceWriteSid` — sha256 → `S-1-4-x-y`); its standing workspace ACE is the cross-session reuse cache, and an exact-ACE skip prevents repeated eager tree propagation. Each live session/workspace pair instead gets a random private temp directory and a domain-separated SID derived from that path (`tempWriteSid`); its ACE is revocable, TMP/TEMP point at that directory, and the token default DACL names the temp SID so newly created temp objects do not acquire the shared workspace capability. A fork therefore cannot write its sibling's temp tree. A fresh provider chooses a new path and SID even for the same resumed session, so crash residue is inert litter rather than a collision or inherited capability; agentless calls create and remove the same shape per invocation. The ambient temp root is never an implicit grant. A workspace equal to or containing the temp root fails before any ACL mutation because its inheritable standing ACE would otherwise reach every private child; the direct API rejects overlap in either direction between a writable root and the actual private temp directory. PowerShell can complete its startup AppLocker probe through this private-temp capability, so `workspace-write` remains FullLanguage absent a host-wide policy; `read-only` cannot create the probe files and conservatively enters ConstrainedLanguage. That split is PowerShell startup behavior, not part of the ACL boundary. The token lists are read-only = [logon SID, Everyone] and workspace-write = [logon SID, Everyone, workspace SID, optional temp SID]. Logon SID + Everyone are keep-alive invariants (early DLL init dies with 0xC0000142 and CNG crashes pwsh with 0xE0434352 without them). Everyone remains in both lists but no longer confers write authority, because the label layer denies it; because NTFS ACLs belong to file objects, a granted workspace hard link still grants an external alias; and because a Low-integrity token cannot open an object whose DACL names another sandbox's AppContainer package SID, a tree stamped by such a tool becomes unreadable to the confined child. Rejecting all hard links would reject ordinary pnpm workspaces, so the provider reports `enforcement: 'partial'` and the native suite pins both gaps. Read-only carries no capability SID, so standing workspace ACEs remain inert across a mode downgrade. Authenticated Users is absent from both lists — CIM is unavailable, closing the C:\-root tree-creation escape — and INTERACTIVE/LOCAL are absent, denying Public-tree writes. New anonymous pipes and sync objects inherit the temp SID (or workspace SID when temp is disabled, Everyone under read-only) through `SetTokenInformation(TokenDefaultDacl)`; named pipes keep the Win32 layer's owner/SYSTEM/Admins-full, Everyone/ANONYMOUS-read-only template, so piped grandchild stdio remains denied. It ships as [`@deepseek-ai/dsh-sandbox-windows-acl`](../../../../packages/sandbox/sandbox-windows-acl/README.md), the `win32` rung of [`dsh-sandbox-local`](../../../../packages/sandbox/sandbox-local/README.md), and [`@deepseek-ai/dsh-pwsh-sandbox`](../../../../packages/shell/pwsh-sandbox/README.md) as the confining executor. +Implement the rung directly on the raw ACL mechanism: duplicate the caller's token into a `WRITE_RESTRICTED` token (`CreateRestrictedToken` with `WRITE_RESTRICTED` + `DISABLE_MAX_PRIVILEGE`; `LUA_TOKEN` is not used) whose restricting SIDs carry distinct workspace and private-temp capabilities. `WRITE_RESTRICTED` intersects write accesses only, so reads keep the caller's ambient access while a write must also match one of these capability ACEs. That intersection covers only the object's own access check, and Windows also authorizes a write or a delete from the PARENT directory's `FILE_DELETE_CHILD` right — which no restricting SID has to co-sign, so `cmd /c del` deleted files outside the workspace wherever the caller's ambient SIDs hold Modify. The token is therefore also lowered to Low integrity and every granted directory receives a Low no-write-up mandatory label in the same call that adds its ACE; the kernel applies that policy inside the access check, whichever right supplied the authority, so the granted roots stay writable and everything else becomes delete-proof as well as write-proof. Because every granted root is labeled Low, the integrity check alone would still let one confined child delete inside ANOTHER granted root (another workspace, a live sibling temp directory), so each grant also DENIES `FILE_DELETE_CHILD` to the world SID: the capability ACE's DELETE bit becomes the only delete authority inside a granted root, for the confined child and for the user's own processes, whose ordinary deletes keep working because the same DACL grants them DELETE directly. The mechanism is the one huoyaoyuan/windows-acl-restrict-poc (`10e4dfb`) demonstrates; this port checks every API call and fails closed (the POC fail-opened on ignored failures). The per-workspace SID is derived deterministically from the canonical workspace path (`workspaceWriteSid` — sha256 → `S-1-4-x-y`); its standing workspace ACE is the cross-session reuse cache, and an exact-ACE skip prevents repeated eager tree propagation. Each live session/workspace pair instead gets a random private temp directory and a domain-separated SID derived from that path (`tempWriteSid`); its ACE is revocable, TMP/TEMP point at that directory, and the token default DACL names the temp SID so newly created temp objects do not acquire the shared workspace capability. A fork therefore cannot write its sibling's temp tree. A fresh provider chooses a new path and SID even for the same resumed session, so crash residue is inert litter rather than a collision or inherited capability; agentless calls create and remove the same shape per invocation. The ambient temp root is never an implicit grant. A workspace equal to or containing the temp root fails before any ACL mutation because its inheritable standing ACE would otherwise reach every private child; the direct API rejects overlap in either direction between a writable root and the actual private temp directory. PowerShell can complete its startup AppLocker probe through this private-temp capability, so `workspace-write` remains FullLanguage absent a host-wide policy; `read-only` cannot create the probe files and conservatively enters ConstrainedLanguage. That split is PowerShell startup behavior, not part of the ACL boundary. The token lists are read-only = [logon SID, Everyone] and workspace-write = [logon SID, Everyone, workspace SID, optional temp SID]. Logon SID + Everyone are keep-alive invariants (early DLL init dies with 0xC0000142 and CNG crashes pwsh with 0xE0434352 without them). Everyone remains in both lists but no longer confers write authority, because the label layer denies it; because NTFS ACLs belong to file objects, a granted workspace hard link still grants an external alias; and because a Low-integrity token cannot open an object whose DACL names another sandbox's AppContainer package SID, a tree stamped by such a tool becomes unreadable to the confined child. Rejecting all hard links would reject ordinary pnpm workspaces, so the provider reports `enforcement: 'partial'` and the native suite pins both gaps. Read-only carries no capability SID, so standing workspace ACEs remain inert across a mode downgrade. Authenticated Users is absent from both lists — CIM is unavailable, closing the C:\-root tree-creation escape — and INTERACTIVE/LOCAL are absent, denying Public-tree writes. New anonymous pipes and sync objects inherit the temp SID (or workspace SID when temp is disabled, Everyone under read-only) through `SetTokenInformation(TokenDefaultDacl)`; named pipes keep the Win32 layer's owner/SYSTEM/Admins-full, Everyone/ANONYMOUS-read-only template, so piped grandchild stdio remains denied. It ships as [`@deepseek-ai/dsh-sandbox-windows-acl`](../../../../packages/sandbox/sandbox-windows-acl/README.md), the `win32` rung of [`dsh-sandbox-local`](../../../../packages/sandbox/sandbox-local/README.md), and [`@deepseek-ai/dsh-pwsh-sandbox`](../../../../packages/shell/pwsh-sandbox/README.md) as the confining executor. ## ACL diagnosis and recovery @@ -22,7 +22,7 @@ Both extracted and recovery scripts are user-writable, so this workflow never re ## How the restriction works (why no new identity) -The identity routes restrict by *who* runs the child; this rung restricts by *token derivation*. An identity route (landstrip's restricted-user, AppContainer) runs the child under a fresh account or container SID that starts with zero ACEs on the host's files — everything, reads included, defaults to denied, and every path the child may touch must then be opened back up by writing ACEs for that identity: the wholesale DACL mutation that disqualified both alternatives. The restricted token keeps the caller's own SID and logon session: [`CreateRestrictedToken`](https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-createrestrictedtoken) derives a token that adds the restricting SIDs and the `WRITE_RESTRICTED` flag, so Windows performs the access check twice — once against the normal SIDs, once against the restricting SIDs — and grants write-class access only where both checks pass. Reads pass on the normal check alone (the caller's SIDs already carry read access everywhere the caller can read), which is why this rung needs no read grants and no new account; writes must additionally clear the capability-SID check, which only the workspace and temp ACEs satisfy. `DISABLE_MAX_PRIVILEGE | LUA_TOKEN` synthesize the limited-user effect of a fresh account token-side, so even an elevated caller derives a filtered token. The same primitive could restrict reads (`SidsToDisable` turning SIDs deny-only), but a read-restricted token would need per-path read grants — reintroducing exactly the cost the identity routes pay — and the sandbox vocabulary never requires read confinement. +The identity routes restrict by *who* runs the child; this rung restricts by *token derivation*. An identity route (landstrip's restricted-user, AppContainer) runs the child under a fresh account or container SID that starts with zero ACEs on the host's files — everything, reads included, defaults to denied, and every path the child may touch must then be opened back up by writing ACEs for that identity: the wholesale DACL mutation that disqualified both alternatives. The restricted token keeps the caller's own SID and logon session: [`CreateRestrictedToken`](https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-createrestrictedtoken) derives a token that adds the restricting SIDs and the `WRITE_RESTRICTED` flag, so Windows performs the access check twice — once against the normal SIDs, once against the restricting SIDs — and grants write-class access only where both checks pass. Reads pass on the normal check alone (the caller's SIDs already carry read access everywhere the caller can read), which is why this rung needs no read grants and no new account; writes must additionally clear the capability-SID check, which only the workspace and temp ACEs satisfy. `DISABLE_MAX_PRIVILEGE` disables every privilege except `SeChangeNotifyPrivilege`; `LUA_TOKEN` is not used, so the derived token keeps the caller's group SIDs. The same primitive could restrict reads (`SidsToDisable` turning SIDs deny-only), but a read-restricted token would need per-path read grants — reintroducing exactly the cost the identity routes pay — and the sandbox vocabulary never requires read confinement. ## Alternatives considered @@ -51,3 +51,7 @@ The product-visible Windows roster flip is win32-only, so keyless snapshots that The [pwsh executor decision](../../archived/feature/2026-08-01-pwsh-tool-and-executor.md) owns the pwsh-sandbox/tool-pwsh dialect split this rung consumes. The [delete-confinement decision](2026-09-19-windows-acl-mandatory-integrity-confinement.md) extends this rung with the Low integrity layer and the ambient-delete deny; it supersedes only the delete route documented here. + +## Follow-up (2026-10-26): `LUA_TOKEN` is dropped + +`CreateRestrictedToken` keeps `DISABLE_MAX_PRIVILEGE | WRITE_RESTRICTED` and no longer passes `LUA_TOKEN`: with that flag, the built-in Administrator user cannot start any process, so every confined launch failed. The write restriction still comes from the restricting SIDs and the Low label. diff --git a/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md b/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md index 63d97f85a8..1f2848d31c 100644 --- a/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md +++ b/.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md @@ -10,7 +10,7 @@ Status: implemented ## 决策 -直接基于原始 ACL 机制实现该档：把调用者令牌复制为 `WRITE_RESTRICTED` 受限令牌（`CreateRestrictedToken`，`WRITE_RESTRICTED` + `DISABLE_MAX_PRIVILEGE` + `LUA_TOKEN`），其 restricting SIDs 携带彼此独立的工作区能力与私有临时目录能力。`WRITE_RESTRICTED` 只对写访问做交集检查，因此读取保留调用者的环境访问，而写入还必须匹配这些能力 ACE 之一。该交集只覆盖对象自身的那次访问检查，而 Windows 也会依据父目录的 `FILE_DELETE_CHILD` 权限批准写入或删除——这项权限不需要任何 restricting SID 副署，因此只要调用者的环境 SID 持有 Modify，`cmd /c del` 就能删除工作区之外的文件。所以令牌还会被降级为 Low 完整性，每个被授权目录都在添加 ACE 的同一次调用中收到 Low 禁止上调强制标签；无论权限来自哪一项，内核都会在访问检查内部执行该策略，于是被授权根目录保持可写，而其他一切不仅防写、也防删。由于每个授权根目录都被标记为 Low，仅靠完整性检查仍会让一个受限子进程删除**另一个授权根目录**（别的工作区、同级的活跃临时目录）内的文件，因此每次授权还会向 world SID 拒绝 `FILE_DELETE_CHILD`：能力 ACE 的 DELETE 位由此成为授权根目录内唯一的删除授权来源——对受限子进程如此，对用户自身进程亦如此，而后者的日常删除仍然可用，因为同一份 DACL 直接向其授予 DELETE。该机制来自 huoyaoyuan/windows-acl-restrict-poc（`10e4dfb`）的演示；本移植检查每个 API 调用并 fail-closed（POC 因忽略失败而 fail-open）。工作区 SID 由规范工作区路径确定性派生（`workspaceWriteSid`——sha256 → `S-1-4-x-y`）；其常驻工作区 ACE 是跨会话复用缓存，精确 ACE 跳过可避免重复的急切全树传播。每个活跃的会话/工作区对则获得一个随机私有临时目录，以及一个从该路径派生的、经过域分离的 SID（`tempWriteSid`）；其 ACE 可回收，TMP/TEMP 指向该目录，令牌默认 DACL 列入该临时 SID，因此新建的临时对象不会获得共享的工作区能力。fork 因此无法写入同级会话的临时目录树。即使恢复的是同一会话，新的提供方也会选择新的路径和 SID，因此崩溃残留只是失效垃圾，而非冲突或继承的能力；无 agent（智能体）的调用会逐调用创建并移除同样的形态。环境临时根目录绝不会被隐式授权。如果工作区等于或包含临时根目录，调用会在任何 ACL 改动发生前失败，因为否则其可继承的常驻 ACE 会向每个私有子目录授权；直接 API 会拒绝可写根目录与实际私有临时目录在任一方向上的重叠。PowerShell 可借助这项私有临时目录能力完成启动时的 AppLocker 探针，因此在没有主机范围策略时，`workspace-write` 会保持 FullLanguage；`read-only` 无法创建探针文件，会保守地进入 ConstrainedLanguage。这一区别属于 PowerShell 启动行为，不是 ACL 边界的一部分。令牌列表为 read-only = [登录 SID、Everyone]，workspace-write = [登录 SID、Everyone、工作区 SID、可选临时 SID]。登录 SID + Everyone 是保活不变式（没有它们，早期 DLL 初始化会以 0xC0000142 死亡，CNG 会让 pwsh 以 0xE0434352 崩溃）。Everyone 仍留在列表中，但它带来的写权限已被标签层否定；由于 NTFS ACL 属于文件对象，工作区内获授权的硬链接仍会使同一对象的外部别名获得授权，而 DACL 中携带其他沙箱 AppContainer 包 SID 的文件对 Low 完整性子进程不可读。拒绝所有硬链接会让普通 pnpm 工作区不可用，因此提供方报告 `enforcement: 'partial'`，原生套件则钉住这些缺口。Read-only 不含任何能力 SID，因此常驻工作区 ACE 在模式降级后保持失效。Authenticated Users 在两种列表中都不存在——CIM 不可用，从而关闭 C:\-root 建树逃逸——INTERACTIVE/LOCAL 也不存在，因此 Public 树写入被拒绝。新建匿名管道和同步对象通过 `SetTokenInformation(TokenDefaultDacl)` 继承临时 SID（禁用临时目录时继承工作区 SID，read-only 下继承 Everyone）；named pipe 保持 Win32 层 owner/SYSTEM/Admins 全权、Everyone/ANONYMOUS 只读的模板，因此受限孙进程的管道 stdio 仍被拒绝。它以 [`@deepseek-ai/dsh-sandbox-windows-acl`](../../../../packages/sandbox/sandbox-windows-acl/README.zh.md)、[`dsh-sandbox-local`](../../../../packages/sandbox/sandbox-local/README.zh.md) 的 `win32` 档，以及作为隔离执行器的 [`@deepseek-ai/dsh-pwsh-sandbox`](../../../../packages/shell/pwsh-sandbox/README.zh.md) 交付。 +直接基于原始 ACL 机制实现该档：把调用者令牌复制为 `WRITE_RESTRICTED` 受限令牌（`CreateRestrictedToken`，`WRITE_RESTRICTED` + `DISABLE_MAX_PRIVILEGE`，不采用 `LUA_TOKEN`），其 restricting SIDs 携带彼此独立的工作区能力与私有临时目录能力。`WRITE_RESTRICTED` 只对写访问做交集检查，因此读取保留调用者的环境访问，而写入还必须匹配这些能力 ACE 之一。该交集只覆盖对象自身的那次访问检查，而 Windows 也会依据父目录的 `FILE_DELETE_CHILD` 权限批准写入或删除——这项权限不需要任何 restricting SID 副署，因此只要调用者的环境 SID 持有 Modify，`cmd /c del` 就能删除工作区之外的文件。所以令牌还会被降级为 Low 完整性，每个被授权目录都在添加 ACE 的同一次调用中收到 Low 禁止上调强制标签；无论权限来自哪一项，内核都会在访问检查内部执行该策略，于是被授权根目录保持可写，而其他一切不仅防写、也防删。由于每个授权根目录都被标记为 Low，仅靠完整性检查仍会让一个受限子进程删除**另一个授权根目录**（别的工作区、同级的活跃临时目录）内的文件，因此每次授权还会向 world SID 拒绝 `FILE_DELETE_CHILD`：能力 ACE 的 DELETE 位由此成为授权根目录内唯一的删除授权来源——对受限子进程如此，对用户自身进程亦如此，而后者的日常删除仍然可用，因为同一份 DACL 直接向其授予 DELETE。该机制来自 huoyaoyuan/windows-acl-restrict-poc（`10e4dfb`）的演示；本移植检查每个 API 调用并 fail-closed（POC 因忽略失败而 fail-open）。工作区 SID 由规范工作区路径确定性派生（`workspaceWriteSid`——sha256 → `S-1-4-x-y`）；其常驻工作区 ACE 是跨会话复用缓存，精确 ACE 跳过可避免重复的急切全树传播。每个活跃的会话/工作区对则获得一个随机私有临时目录，以及一个从该路径派生的、经过域分离的 SID（`tempWriteSid`）；其 ACE 可回收，TMP/TEMP 指向该目录，令牌默认 DACL 列入该临时 SID，因此新建的临时对象不会获得共享的工作区能力。fork 因此无法写入同级会话的临时目录树。即使恢复的是同一会话，新的提供方也会选择新的路径和 SID，因此崩溃残留只是失效垃圾，而非冲突或继承的能力；无 agent（智能体）的调用会逐调用创建并移除同样的形态。环境临时根目录绝不会被隐式授权。如果工作区等于或包含临时根目录，调用会在任何 ACL 改动发生前失败，因为否则其可继承的常驻 ACE 会向每个私有子目录授权；直接 API 会拒绝可写根目录与实际私有临时目录在任一方向上的重叠。PowerShell 可借助这项私有临时目录能力完成启动时的 AppLocker 探针，因此在没有主机范围策略时，`workspace-write` 会保持 FullLanguage；`read-only` 无法创建探针文件，会保守地进入 ConstrainedLanguage。这一区别属于 PowerShell 启动行为，不是 ACL 边界的一部分。令牌列表为 read-only = [登录 SID、Everyone]，workspace-write = [登录 SID、Everyone、工作区 SID、可选临时 SID]。登录 SID + Everyone 是保活不变式（没有它们，早期 DLL 初始化会以 0xC0000142 死亡，CNG 会让 pwsh 以 0xE0434352 崩溃）。Everyone 仍留在列表中，但它带来的写权限已被标签层否定；由于 NTFS ACL 属于文件对象，工作区内获授权的硬链接仍会使同一对象的外部别名获得授权，而 DACL 中携带其他沙箱 AppContainer 包 SID 的文件对 Low 完整性子进程不可读。拒绝所有硬链接会让普通 pnpm 工作区不可用，因此提供方报告 `enforcement: 'partial'`，原生套件则钉住这些缺口。Read-only 不含任何能力 SID，因此常驻工作区 ACE 在模式降级后保持失效。Authenticated Users 在两种列表中都不存在——CIM 不可用，从而关闭 C:\-root 建树逃逸——INTERACTIVE/LOCAL 也不存在，因此 Public 树写入被拒绝。新建匿名管道和同步对象通过 `SetTokenInformation(TokenDefaultDacl)` 继承临时 SID（禁用临时目录时继承工作区 SID，read-only 下继承 Everyone）；named pipe 保持 Win32 层 owner/SYSTEM/Admins 全权、Everyone/ANONYMOUS 只读的模板，因此受限孙进程的管道 stdio 仍被拒绝。它以 [`@deepseek-ai/dsh-sandbox-windows-acl`](../../../../packages/sandbox/sandbox-windows-acl/README.zh.md)、[`dsh-sandbox-local`](../../../../packages/sandbox/sandbox-local/README.zh.md) 的 `win32` 档，以及作为隔离执行器的 [`@deepseek-ai/dsh-pwsh-sandbox`](../../../../packages/shell/pwsh-sandbox/README.zh.md) 交付。 ## ACL 诊断与恢复 @@ -23,7 +23,7 @@ Status: implemented ## How the restriction works (why no new identity) -身份路线靠"**谁**在跑子进程"来限制，本档靠"令牌派生"来限制。身份路线（landstrip 的 restricted-user、AppContainer）用全新账户或容器 SID 运行子进程，该身份在宿主的文件上从零条 ACE 开始——一切访问（包括读）默认拒绝，子进程要碰的每条路径都必须事后为那个身份补写 ACE 才能放行：这正是让两个备选方案出局的全盘 DACL 改造。受限令牌保留调用者自己的 SID 与 logon session：[`CreateRestrictedToken`](https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-createrestrictedtoken) 派生一个加入 restricting SIDs 与 `WRITE_RESTRICTED` 标志的令牌，于是 Windows 做两次访问检查——一次按正常 SID，一次按 restricting SIDs——只有两次都放行，写类访问才被授予。读只凭正常检查即可通过（调用者的 SID 在其可读范围内本来就携带读权限），所以本档不需要任何读授权、也不需要新账户；写还必须额外通过能力 SID 检查，而只有工作区与临时目录的 ACE 能满足它。`DISABLE_MAX_PRIVILEGE | LUA_TOKEN` 在令牌侧合成了新账户的受限用户效果，即使提升过的调用者派生的也是过滤令牌。同一原语其实也能限制读（`SidsToDisable` 把 SID 变为 deny-only），但受限读的令牌需要逐路径的读授权——恰好重新引入身份路线付出的代价——而沙盒词汇表从不要求读隔离。 +身份路线靠"**谁**在跑子进程"来限制，本档靠"令牌派生"来限制。身份路线（landstrip 的 restricted-user、AppContainer）用全新账户或容器 SID 运行子进程，该身份在宿主的文件上从零条 ACE 开始——一切访问（包括读）默认拒绝，子进程要碰的每条路径都必须事后为那个身份补写 ACE 才能放行：这正是让两个备选方案出局的全盘 DACL 改造。受限令牌保留调用者自己的 SID 与 logon session：[`CreateRestrictedToken`](https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-createrestrictedtoken) 派生一个加入 restricting SIDs 与 `WRITE_RESTRICTED` 标志的令牌，于是 Windows 做两次访问检查——一次按正常 SID，一次按 restricting SIDs——只有两次都放行，写类访问才被授予。读只凭正常检查即可通过（调用者的 SID 在其可读范围内本来就携带读权限），所以本档不需要任何读授权、也不需要新账户；写还必须额外通过能力 SID 检查，而只有工作区与临时目录的 ACE 能满足它。`DISABLE_MAX_PRIVILEGE` 禁用除 `SeChangeNotifyPrivilege` 外的所有特权；不采用 `LUA_TOKEN`，因此派生令牌保留调用者的组 SID。同一原语其实也能限制读（`SidsToDisable` 把 SID 变为 deny-only），但受限读的令牌需要逐路径的读授权——恰好重新引入身份路线付出的代价——而沙盒词汇表从不要求读隔离。 ## 考虑过的替代方案 @@ -52,3 +52,7 @@ landstrip 评估在实现前已被否决（未经实战检验；自建 launcher [pwsh 执行器决策](../../archived/feature/2026-08-01-pwsh-tool-and-executor.md)拥有本档所消费的 pwsh-sandbox/tool-pwsh 方言划分。 [删除约束决策](2026-09-19-windows-acl-mandatory-integrity-confinement.zh.md)以 Low 完整性层与环境性删除拒绝扩展本档；它只取代本文档所述的删除路径。 + +## 后续追记（2026-10-26）：去掉 `LUA_TOKEN` + +`CreateRestrictedToken` 仍传 `DISABLE_MAX_PRIVILEGE | WRITE_RESTRICTED`，不再传 `LUA_TOKEN`：带上该标志时，内置 Administrator 用户无法启动任何进程，受限启动全部失败。写限制仍来自 restricting SIDs 与 Low 标签。 diff --git a/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml b/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml index f50ce14bc9..96e5042c3e 100644 --- a/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml @@ -15,8 +15,8 @@ en: db0a2deb9193a00d zh: dab5a65b88957464 /agent-note-experimental-auto-review-before-each-tool-call/decision/one-complete-reviewer-request: - en: 7bd9fef90e8639b9 - zh: e2a096885c9c1e83 + en: 45ac7b4e759b29ad + zh: 5374cc89e587f076 /agent-note-experimental-auto-review-before-each-tool-call/decision/result-and-cancellation: en: 647fe68c52b907e0 zh: 267a739bad44ad65 diff --git a/.agents/notes/implemented/feature/2026-08-28-auto-review.md b/.agents/notes/implemented/feature/2026-08-28-auto-review.md index 9434c92f41..547dd3a2cf 100644 --- a/.agents/notes/implemented/feature/2026-08-28-auto-review.md +++ b/.agents/notes/implemented/feature/2026-08-28-auto-review.md @@ -41,6 +41,8 @@ The integration uses only the latest `request/header.config` provider/model and Each item is its own message and keeps the same text in later reviews: the pending call becomes a historical call, and the integration remembers, for each live Session, the schema each reviewed call showed so that it reappears at the same position. A review's messages therefore begin with all messages of the previous review. Providers that cache only at message ends, such as OpenAI implicit breakpoints on GPT-5.6 and later, or at a final marker with lookback, such as Anthropic `cache_control`, reuse the previous review; one growing user message let them reuse only the policy. The schema memory is process-local, so the first review after a restart omits earlier schemas and misses the cache once. +The request also carries the reviewed Session's `sessionId` and `purpose: 'auto-review'`. Routes that require a per-conversation identity or key prompt caching on one, such as the `x-opencode-session` header OpenCode requires and OpenAI `prompt_cache_key`, derive it from that id; without it OpenCode rejects every review, and Auto fails every call. The [DeepSeek Session-log upload](../../../../packages/session/session-log-deepseek/README.md#request-field) applies the same eligibility and registered exclusions to reviews as to other requests. The uploaded data is the canonical Session log; review prompts and decisions remain outside that log. + The reviewer builds the history and the pending call from the Session's complete action history: an authorization is the earlier call the `REVIEW_POLICY` source rules make eligible, and a duplicate or conflicting identity has to be visible anywhere in the log rather than inside a recent window, so neither the Session projections nor a bounded read serves the decision. The read is the deprecated synchronous `snapshotEvents()` under a line-scoped `typescript/no-deprecated` waiver. The main agent's V3 `system/message` nodes, assistant text/reasoning, and tool results are excluded. The current call must belong to the open step recorded by `step/start`; missing step ownership fails closed. It appears only as the final message; an unstarted sibling has no historical call fact. Native schema comes from the latest request header. PTC captures a frozen schema at binding construction and passes it through the scheduler into `ToolExecution`; descriptions and parameter schemas never enter start/settle events or the Session/SDK wire. Missing, inconsistent, or ambiguous action facts reject the call without consulting the live registry. An oversized request fails closed without summarization, truncation, another compaction pass, or a small output-token budget. diff --git a/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md b/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md index 5ba7a8b39c..bc833d3fc3 100644 --- a/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md +++ b/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md @@ -41,6 +41,8 @@ Integration 只使用最新 `request/header.config` 的 provider／model 与 shi 每个条目各占一条消息，并在后续评审中保持相同文本：待审调用会变成历史调用，integration 为每个存活 Session 记住每次已审调用展示的 schema，使其在同一位置再次出现。因此一次评审的消息以上一次评审的全部消息开头。只在消息结尾缓存的 provider（如 GPT-5.6 及以后的 OpenAI 隐式断点），或在末尾标记处向前回溯的 provider（如 Anthropic `cache_control`），都能复用上一次评审；单条不断增长的 user 消息只能让它们复用策略。Schema 记忆只在进程内，因此重启后的第一次评审会缺少先前的 schema，并有一次缓存未命中。 +请求还携带被评审 Session 的 `sessionId` 与 `purpose: 'auto-review'`。需要按对话标识路由或以其为 prompt 缓存键的路由（例如 OpenCode 要求的 `x-opencode-session` header 与 OpenAI 的 `prompt_cache_key`）由该 id 派生；缺少它时 OpenCode 会拒绝每次评审，Auto 会让每个调用失败。[DeepSeek session-log 上传](../../../../packages/session/session-log-deepseek/README.zh.md#request-field)对评审和其他请求应用相同的上传资格与注册排除条件。上传的是权威 Session 日志；评审提示词和决策仍不进入该日志。 + reviewer 从 Session 的完整动作历史构建历史与待审调用：授权是符合 `REVIEW_POLICY` 来源规则的那个更早调用，而重复或冲突的身份必须在整份日志的任何位置都可见，而不是只在近期窗口内可见，因此 Session 投影与有界读取都无法支撑该判定。这次读取使用已废弃的同步 `snapshotEvents()`，并带有行级 `typescript/no-deprecated` 豁免。 主 agent 的 V3 `system/message` 节点、assistant 正文／reasoning 与 tool results 全部排除。当前调用必须属于 `step/start` 记录的开放 step；缺少 step 归属时拒绝执行。该调用只作为最后一条消息出现；尚未开始的 sibling 没有历史调用事实。原生 schema 来自最新 request header。PTC 在 binding 构造时捕获冻结 schema，经由调度器传入 `ToolExecution`；描述与参数 schema 不进入开始／结算事件或 Session／SDK wire。动作事实缺失、不一致或有歧义时拒绝调用，不查询 live registry。超窗请求直接拒绝，不做摘要、截断、额外 compaction 或设置小型输出 token 预算。 diff --git a/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.i18n.yaml b/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.i18n.yaml new file mode 100644 index 0000000000..fc9f88a600 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.i18n.yaml @@ -0,0 +1,55 @@ +# Bilingual-pair consistency record for 2026-09-13-liveshare-protocol-and-owner-surfaces.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 .agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.md +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague: + en: e73b246e19c9b412 + zh: c87594ad5eccbfb5 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/problem: + en: 17bc15d382139909 + zh: 3eff34b5ddea951e +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision: + en: a15c7c13f167e5ac + zh: a15c7c13f167e5ac +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/what-a-share-is: + en: ff1dbb0f7c2355e4 + zh: 3de92b2e6c5e9e15 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/what-a-reader-can-do: + en: 5652ed7f515a2a5d + zh: 993378f78f5a4120 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/two-driving-tiers: + en: 0b9303333bf482ae + zh: 6dfc68ad9e2924c3 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/default-visibility: + en: 754705367c350b31 + zh: e10b6541458c4a45 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/how-shared-work-stays-inside-its-grant: + en: fa3ab42895a16ce1 + zh: 429be63cfb8e55a6 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/keeping-one-branch-across-retries: + en: 6b0369dafe34a5aa + zh: aea9465216204122 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/who-the-owner-is: + en: 7e6d1305782d2822 + zh: 66fb2cbef0f49d47 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/what-the-reader-sees-at-the-top: + en: 44d02a91cf0c5715 + zh: dabbf6c59ff08e4a +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/when-the-connection-breaks: + en: 36ee6e090797806b + zh: 21809a0cf990d905 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/how-the-served-page-is-exercised: + en: d9cbb8277862587c + zh: 867fa6c4db95d09c +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/decision/what-the-package-exposes: + en: d13a0df787f212d4 + zh: 24794e8bf4d92492 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/alternatives-considered: + en: 2daeba6e763383e4 + zh: fe0fe3f7f4d546e7 +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/verification: + en: 76cc786336c5daf5 + zh: 98bd2b9cc7d1791c +/agent-note-liveshare-sharing-a-dsh-session-with-a-colleague/consequences: + en: 8a6e06a9fba917e2 + zh: 68a9d19b15119345 diff --git a/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.md b/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.md new file mode 100644 index 0000000000..a4d1c6af81 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.md @@ -0,0 +1,156 @@ +# Agent Note: Liveshare — sharing a DSH session with a colleague + +Status: implemented + +English | [中文](2026-09-13-liveshare-protocol-and-owner-surfaces.zh.md) + +## Problem + +A DSH session runs on your own computer. A colleague sometimes needs to watch one while you work — to follow a debugging session, or to see how a long task is going. Today there is no way to do that. Sending the session log is not the same thing: the colleague would need your plugins, configuration, and sandbox to render it, and the session only makes sense while it is running on your machine. + +So a share needs three things at once. A **page the colleague opens in a browser** that shows the session running on your machine, without connecting them to it. A **limit on what that page can do**, starting with "read without writing" — anything the page offers beyond what you agreed is a security hole, not a convenience. And an **answer to "who shared this?"**, because a page that cannot say who its owner is cannot be trusted by whoever opens it. + +This note covers the half that runs inside the owner's DSH — the share dialog, the owner-side service behind it, the package's browser face, and the page a reader opens — plus the protocol package both sides speak. The Liveshare server, the shared service in the middle, is its own package (`@deepseek-ai/dsh-experimental-liveshare-relay`) and is reviewed and deployed separately. + +## Decision + +### What a share is + +An owner creates a share for one session from DSH itself. The share is published to the Liveshare server, a service both sides can reach, and DSH returns a link. Opening that link shows the session rendered by the owner's own DSH with its own plugins, so the reader never needs the owner's configuration. The reader's list contains the source Session and any children that reader created through the share. Workspace names, membership, and ordering are trimmed to those Sessions; unrelated Sessions and workspaces stay hidden. + +A share created from the DSH Share dialog is an **organization link** share: it carries `accessMode: 'open'`, so anyone in the organization who has the link is admitted. The deployment's `LIVESHARE_ALLOWED_SUBJECTS` is unioned into every share's ACL: it narrows an `open` share to the subjects it lists, and on a stored `selected` record it adds those subjects beside the record's own selection. + +**Specific colleagues (`selected`) and the older `approval` spelling are legacy stored records.** The Host still reads them with their recorded ACL and shows their access summary, and the Liveshare server still admits their viewers by that ACL, but the shipped Share dialog offers no way to create one. `liveshareShares.create` keeps its `accessMode` and `allowedSubjectIds` fields for those records and for callers that invoke the Remote directly; the shipped dialog sends neither. + +### What a reader can do + +The reader's page is the normal DSH client, not a cut-down copy. The sidebar, the session list, expanding, collapsing, and selecting are all there, because browsing is part of reading. What is missing is every action the reader is not allowed to perform: creating an unrelated session, renaming, archiving, deleting, and managing a workspace. Branching follows the share's own fork switch, prompting is available in both tiers and runs inside that tier's sandbox, and attachment upload follows the Sessions the reader can see; management permissions remain independent of the tier and the fork switch. + +These actions are not hidden with CSS. One access snapshot decides what the page may do: the remote-access client follows the reader's own `remoteAccess/follow`, and each button and menu entry reads its endpoint's answer on the global resource, a Session, or a Workspace through `useRemoteAccess`, `useAccess` or `useSessionAccess`, or `useWorkspaceAccess`, rendering again whenever the answer changes. The owner's DSH computes the snapshot from this share's `share-viewer` policy, so an ability the owner withdraws closes without reloading the page — and the server refuses those actions anyway; the page only avoids offering what would be refused. The served index carries the reader's opening snapshot, so no entry appears before the page knows it is allowed, and after the snapshot stream fails every answer is refused. The owner's own page opens with the owner baseline and behaves exactly like an ordinary DSH. Per-Session refusal reasons are not part of the snapshot: the page states the page-level reason (share mode, stop, expiry, lost access) and generic read-only copy. A page that cannot read the Session at all — offline owner, stopped or expired share, lapsed sign-in — states that condition at the top and gives the reader an action, instead of leaving an empty shell or a bare code. + +### Two driving tiers + +Every share carries a `ViewerSessionMode` with two values, and both drive the shared Session: + +- **view** — the reader drives the shared Session's loop through the normal prompt path, inside a read-only sandbox in the granted workspace, so the Session's tools never write a file. The read and search surface (`read`, `read_image`, `glob`, `grep`, `present`), the tools with no local file effect (`todo_write`, `skill`, `web_search`, `web_fetch`). Every declared path is checked before the tool runs, and a tool whose call cannot be checked is refused. +- **write** — the reader drives the same loop in a bounded writable sandbox that also modifies files inside the granted workspace, under the Host's write ceiling. + +The sandbox is installed on the Session, but it confines only the turns a share viewer starts: `agent/pre-step` records whether an admitted turn's entering input names a share viewer, and the guard and the replacements read that answer for each execution. A turn the owner starts keeps the Session's tools; an owner's steering input inside a viewer's turn stays confined with it. The marker lives in Host memory, is recomputed for each turn, and never enters the Session log. Stopping every share, or letting them all expire, disposes the layer and gives the Session its own tools back. + +The earlier vocabulary had three tiers — `view` watched, `fork-readonly` branched, and `write` could write. `view` and `fork-readonly` differed only in whether the reader could branch and drive a child, which the share's own `allowsFork` switch already decides; a third mode duplicated that switch and let the two answers disagree, so the two driving tiers replaced it. + +Forking is not a tier. The share carries its own `allowsFork` switch, independent of the tier: a `view` share may allow it and a `write` share may refuse it. A fork creates a child the viewer owns with its own read-only or writable ceiling and leaves the source untouched. + +Attachment upload is not a tier or a switch. `fileUploads/upload` rides the read role, so every Session a share serves the reader accepts files; visibility alone decides it, and the owner has no separate attachment switch. + +A mode this version does not recognize, and a persisted record whose mode the host cannot establish, are not driven: the share stays readable, and the page reports what it could not establish. 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. + +The sandbox is a property of the Session, but it applies per turn: the Host records, in memory, whether the admitted input of the running turn names a share viewer, and confines that turn while leaving an owner-started turn on the Session's native tools. The earlier shipped design confined every turn, including the owner's; it needed no turn read, but a share changed how the owner's own work ran. Persisting a turn's requester was rejected: a committed-message projection had to be folded, re-read for every execution, and kept in step with the share that admitted it, and it still had to fail closed on mixed or unestablished requesters. The in-memory marker keeps the guard and the replacements reading one answer per execution without adding a Session event; a restart recomputes it from the next admitted step, and a rejected or never-admitted step leaves no marker. + +### Default visibility + +The package ships as a runtime dependency of every dsh installation, but a default installation must show it nowhere in the plugin manager: neither under **Built-in plugin settings**, nor under **Experimental plugins**, nor on the **More** page. A person enables it deliberately — by inserting the bundle's rows in the active profile's `cordis.patch.yml`, or by selecting the bundle in `dsh.profile.bundles`; the [package README](../../../../packages/experimental/liveshare/README.md) owns both routes. The package must still ship with the release and stay installable, and users who enabled it before this rule keep seeing it. + +The Host's bundle `enabled` flag states whether the profile selected the bundle, which is not the same as whether the bundle's plugins run: inserting the bundle's rows through `cordis.patch.yml` starts its plugins while leaving the bundle unselected, so a visibility rule built on `enabled` would hide a bundle the person had just enabled and would strand the documented enable path. + +The package declares the hiding intent in its own bundle manifest as `dsh.bundle.listedByDefault: false`; the manager keeps one generic visibility rule rather than a client-side name set. A bundle whose manifest does not declare `listedByDefault: false` is listed; one that declares it is listed only when the profile enables it, the installation carries it selected, or one of the rows its bundle patch declares is running (`pkg.rows.some(row => row.enabled)`). The filter applies before both lists are derived, so the name is absent from the main Experimental plugins group, the More page, Built-in plugin settings, and the Installed plugins group until one of those holds. The Host's `listBundles` contract, the profile format, and the installed package set are unchanged. `BundleInfo.rows` already joins each declared row with the Loader entry currently carrying it, and the client's `PackageView` carries whether that entry runs, so row state is the effective answer for both enable routes: removing the rows, disabling them, or deselecting the bundle stops them and the card leaves both lists again. + +A default-hidden bundle is not addressable by ID while its card is hidden: `openPkg` resolves only the listed inventory, so `pluginNavigation.openBundle('@deepseek-ai/dsh-experimental-liveshare')` renders no details until the same enablement conditions list it. + +### How shared work stays inside its grant + +The Owner, not the viewer page or the Liveshare server, authorizes each Session operation. A child receives its real scoped tool restrictions before it can accept a prompt, including after a cold resume: the host installs the limit from the base `agent/created` event. That listener runs after the agent entered the registry, but creation has not resolved, AgentLoop holds the agent's queued input, and a throw fails creation, so a refused limit still prevents any prompt. A missing host service or failed installation refuses the child; a configuration flag, a tool name, or a promise to install later is not enforcement. + +A shared source Session can still serve its owner's own work. Every reader call is dispatched through the owner's own Connection and Gateway as that share-and-reader pair's own Peer, whose `share-viewer` principal (the share id and the server-asserted identity triple) is fixed by in-process owner code when the Peer is created; no wire field can change it. The Gateway decides the Peer's calls, and the Session notifications it forwards to the Peer, through remote access: this package registers the `share-viewer` policy, which binds a served reader to read roles on the shared Session, its own forks, and the Workspaces holding them, and to fork and write roles whose conditions apply the share mode; it binds nothing else, so every other endpoint and notification is refused, and it binds nothing once the share stops serving the reader. The owner invalidates the reader's access on every grant, revocation, mode change, and expiry, and disposes the reader's Peer when the grant ends or the share stops or expires. A reader's prompt enters the Session as a `user-rpc` message whose `source.principal` names that reader; owner messages carry no principal. While any share over that Session is active, the owner host mounts its own confined replacements for the read and search surface and the no-effect tools — plus bounded `edit` and `write` when some share may write — in the Session's own scope, and a viewer-started turn may run nothing else. An owner-started turn keeps the Session's native tools, so a share never narrows the owner's own work. The pre-step records which kind of turn is running, in memory only. Each operation re-reads the shares' current Relay grants and checks the resolved target against the granted root; the pre-step re-checks every entering message's viewer against the Relay's admission before a model step, so reader input queued before a revocation never drives the model. A reader's stop of the shared Session is dispatched through the Gateway like a prompt: the policy admits it while the share's tier is established and the Session is confined, and the owner's own Session controller stops whatever turn that Session is running, the owner's included. The general Peer, principal, and remote-access design is in [Peer principals and remote access](../../implemented/architecture/2026-10-12-peer-principal-and-remote-access.md). + +A confined file tool resolves every path its own arguments declare, checks that the granted root contains each result, and hands the deployment's tool that canonical path; a pathless search uses the Session's working directory, which the replacement checks like a named path. A bounded edit or write performs the same containment check and then edits or writes through the filesystem backend with the Session's current sandbox policy and the normal observation policy. + +### Keeping one branch across retries + +One fork request binds its viewer, share, source, operation identity, and completed prefix. The Owner reserves that operation durably before creating a child, and records the child the owner's fork answer returned; a retry of a recorded operation replays that answer instead of forking again. A different prefix under the same identity is refused. The owner's `SessionForkRequest` mints the child id, so the Host sends no child identity: a host that dies after the child was created but before the operation was recorded cannot name that child on retry and creates a new one. Closing that window needs a Session Controller request that accepts a caller-supplied child identity. The inherited prefix stops before unrelated queued input; only immediately following request metadata is retained. Revoked children keep their logs but cannot resume with broader access, and removing a share does not expose the source Session's unrestricted tools. + +### Who the owner is + +A share can only be created by a verified owner. The dialog shows the identity the owner's DSH read back — name, expiry, when it will renew — and uses a label derived from the identity when there is no display name. The code that creates the share refuses an unverified owner as well, so the question is not settled by whether a button was clickable. + +Signing in happens once, in a window the page opens while the owner clicks. The DSH creates a short-lived transaction tied to the Liveshare server address, to the Liveshare server instance, and to the page allowed to finish it; the page opens the sign-in page the DSH names, accepts one one-time code only from that exact origin, window, and transaction, and hands it back to its own DSH. + +The Owner redeems the code with the verifier it retained, stores the credential with owner-only permissions, and sends it only to the Liveshare server address that issued it. New registration requires that verified credential; existing-share reconnect uses the share's management token, and explicit identity claim preserves the share's ACL, mode, expiry, and token. A share's named colleagues are the owner's stored selection plus the deployment's own allowlist; nothing is derived from a display identity. + +### What the reader sees at the top + +The served page reuses the sidebar's existing brand row instead of adding a bar on top of the app: the usual Harness mark, plus a LiveShare entry that names who shared the session and which DSH version they run, with the Liveshare server's own release labeled separately. Clicking it returns to the page listing the shares you can open. + +### When the connection breaks + +A reader's feed can fail: a stream disappears, the Liveshare server cancels a request, a read times out. The page retries only the failures that are defined as repeatable, and stops for good on authentication, permission, and missing-share errors, showing the reason instead of reconnecting forever. + +### How the served page is exercised + +The page a viewer opens is the owner's own Web page. The Liveshare server asks the owner for its rendered index document, places a short carrier script at its top, and passes the page's shell assets and plugin bundles through from the owner, so the page runs every owner plugin at the owner's version. The carrier only turns the page's calls and streams into reads over the Liveshare server's channel; the Liveshare plugin itself recognizes a viewer page and mounts the viewer surfaces instead of the Share action. The owner renders that index with the reader's own access snapshot in place of the owner baseline, and the page then follows the reader's `remoteAccess/follow` snapshot; no other read carries a reader's grants. + +The viewer page is tested in-process: the test assembles the page from the carrier, the shell, and the client plugins including Liveshare's, stands in for the Liveshare server's read channel, and answers the page's reads from a scripted owner, so the assertions see the real shell, carrier, and presentation plugins. + +### What the package exposes + +The package ships one Host program and one browser face. Its public entries are the Host export (`lib/index.js`), `./client` (`lib/client.js`, a closure-factory bundle), `./viewer-declarations`, the share-management Remote's `./typert` and `./remote` faces, `./types`, the bundle patch `./cordis.patch.yml`, and the locale JSON files. The manifest declares the browser face as `dsh.client` with `platform: web` and the client services it needs; that face reads `__DSH_LIVESHARE_VIEWER__`, mounts the viewer session plugin and its brand, model, permission, session-row, and share-path surfaces on a served viewer page, and otherwise mounts the owner's generated Remote before the Session-header Share action. + +Share management is one `liveshareShares` Typert Remote with twelve methods — `create`, `list`, `stop`, `updatePermissions`, `setCapabilities`, `capabilities`, `relay`, `setRelay`, `identity`, `audit`, `testRelay`, and `testPublish` — over the operations the owner host runs. The only same-origin HTTP routes left are the four owner sign-in and credential routes: `/api/liveshare.ownerLoginStart`, `/api/liveshare.ownerLoginRedeem`, `/api/liveshare.ownerLoginCancel`, and `/api/liveshare.ownerCredential`. + +The outgoing gateway is a supervised child process whose source entry is `src/owner-gateway/cli.ts` and whose published entry is `lib/owner-gateway/cli.js`; the directory name keeps it distinct from the DSH API gateway. + +## Alternatives considered + +- **Build a separate read-only page instead of serving the normal client.** Rejected: reading needs browsing, grouping, and selecting, so a second page would have to rebuild all of it and would quietly lose the navigation the product keeps. +- **Decide each button's availability where the button is.** Rejected: every entry reads one access snapshot the owner computes, so a screen added later cannot quietly reintroduce an action the reader may not perform. +- **Let the reader's page decide its own access.** Rejected: only the owner and the service decide what a share grants; the page states what it was told. +- **Treat an older share with no mode as writable.** Rejected: that would hand a reader access the owner never configured, so a share without a mode is read-only. +- **Put the sign-in code in the page address, or read the credential from the popup's cookies.** Rejected: addresses leak through history, referrers, and logs, and a page should not hold credentials. +- **Show the service's own error text when the page cannot explain a refusal.** Rejected: that text may contain a file path, a credential, or another reader's session, so the page shows the stable reason it can vouch for. +- **Put execution restrictions only in editable configuration or a sandbox mode.** Rejected: a child can change configuration, and per-call execution choices can outrank a mode. The real operation needs a monotonic guard and a verified implementation. +- **Check a model-supplied path only before dispatch, or globally constrain every filesystem read.** Rejected: a pre-dispatch check is separated from the tool call by other listeners, while a global read rule would also constrain unrelated Owner work. The containment check runs inside the authorized Session's own read and write. +- **Reuse the deployment's default root or copy the entire source tail into a child.** Rejected: both can include files or pending input the viewer was never granted. +- **Use a deployment-wide secret or self-reported display fields as owner identity.** Rejected: neither identifies the logged-in person who approved this publication. +- **Keep three tiers.** Rejected: `view` and `fork-readonly` differ only in whether the reader can branch and drive a child, which is already the independent fork switch. A third mode duplicates that switch and lets the two answers disagree. +- **Keep a per-share attachment-upload switch.** Rejected: an attachment is part of a prompt on a Session the reader can already see. The separate switch duplicated visibility and could only subtract from it, while the upload role already rides the read role. +- **Attribute every turn to a requester and exempt the owner's own turns.** Rejected after it shipped, then narrowed: persisting a turn's requester needed a Host-only projection over message sources, a turn-boundary read per execution, and a re-check of the share that admitted each turn, and it still had to fail closed on mixed or unestablished requesters. The shipped design keeps only an in-memory marker for the running turn — `agent/pre-step` reads the entering principals and the guard reads that answer — so an owner-started turn keeps the Session's native tools without adding a Session event. The accepted cost is that an owner's steering input inside a viewer's turn stays confined; a viewer message that reaches a later step narrows that turn. +- **Let each tool name its own tier or sandbox.** Rejected: the tier belongs to the share. A per-call choice would let one execution outrank the grant that admitted it. +- **Test the bundle's `enabled` flag directly.** Rejected: it would keep the code smallest, but the patch route starts the bundle's plugins while leaving the bundle unselected, so the card would stay hidden exactly when its plugins started, contradicting the product rule. +- **Derive effective enablement in the Host.** Rejected: `listBundles` could report a new or redefined effective state, but that would change a cross-package contract for one client-only presentation rule and invite every bundle consumer to reinterpret `enabled`, which must keep meaning "selected in the profile". +- **Ship LiveShare outside the installation's optional bundles.** Rejected: that would make it visible nowhere by construction, but the package must still ship as an npm package with the release and be installable, and it would also remove the bundle from the Host's list entirely, taking the details entry with it. +- **Keep the colleague picker, or replace it with a directory-backed selector.** Deferred: naming a colleague needs an identity directory the Liveshare server does not provide, so the dialog cannot offer a choice it can verify. Stored `selected` and `approval` records keep working through their ACL, and the creation entry point stays retired until a directory contract exists; `liveshareShares.create` keeps its fields for those records and direct Remote callers, so this defers the API rather than deleting it. + +## Verification + +- A reader's page keeps the normal navigation, and no action the reader may not perform appears on the shared session or on any branch. +- A DSH without the Liveshare bundle, and the owner's own page, behave exactly as before. +- A share uses one of two tiers and that tier's sandbox; unknown modes, unreadable answers, and shares without a mode stay readable but are never driven. +- A share cannot be created without a verified owner identity. +- A share created from the dialog carries `open`; a stored `selected` or `approval` record keeps its recorded ACL and access summary, and `create` still stores a requested `selected` mode with its subjects. +- Sign-in accepts one one-time code from the transaction's origin, window, and state, and nothing else; a failed or abandoned attempt discards the transaction, and no credential, cookie, or code reaches a URL, storage, or a log. +- Real Controller, ToolRuntime, filesystem, and profile tests cover fork identity, cold enforcement, bounded execution, revocation, and normal cancellation. The built viewer must use its real POST carrier and Owner authorization handler; deterministic display fixtures do not replace execution or persistence tests. +- Generated API documentation and both SDK projections remain aligned with the `user-rpc` source principal, which only the `agent/pre-step` admission check consumes. +- `ViewerSessionMode` has two members, and a persisted `fork-readonly` record is rejected when the owner state loads. +- A `view` share drives the source Session, refuses file writes and out-of-grant reads, and can fork when `allowsFork` is set. +- `fileUploads/upload` is allowed on every Session the reader can see, for every tier and fork combination. +- Source tool decisions read only the Session's mounted layer: the guard permits this installation's confined replacements for the read and search surface and the no-effect tools, plus bounded `edit` and `write` on a writable Session, and refuses every other name, with no turn, requester, or origin consulted. +- Unit and real-runtime tests cover the tier policy, confined reads and writes, fork ceilings, the layer's installation and release, and the pre-step admission check over the durable message source. +- The plugin-manager component tests hold the bundle out of both lists while its declared rows are off, list it once a declared row runs, and still open it by bundle ID while it is hidden; the recorded goldens and the refresh card count move with that rule. + +## Consequences + +The reader's page can only be as accurate as what the service tells it. Capability answers, the owner's identity status, the session mode, the owner's DSH version, and the sign-in endpoints all come from the owner's DSH and the Liveshare server; until those are deployed together with this layer, the page stays at its most conservative setting — read-only, with a sign-in that cannot complete — rather than guessing. + +The page is not a security boundary. The owner's DSH and the Liveshare server refuse a reader's writes no matter what the page does; the access snapshot exists so the page does not offer actions that would only be refused. + +Existing ACLs are retained. A record without a mode is readable but not driven, and contradictory mode fields are refused. Unattributed shares are shown as unverified history. + +Owner reconnect state is atomically replaced and queued within one process, but multiple processes sharing one file can still lose updates or compete for a gateway. Cross-process execution ownership is unresolved; atomic replacement alone is not a transaction or a route claim. Containment is checked by path: a local process that replaces a directory inside the grant with a symlink between the check and the open can redirect a viewer's read, or a write elsewhere within the sandbox's writable roots. Operations anchored to a directory handle would close this window and are left to a separate change. Final viewer-artifact and SDK snapshot evidence remains required before release. + +A `view` share is not watch-only: it runs the reader's prompts and tool calls inside the read-only sandbox. A deployment that wants a passive reader has no separate mode and must rely on the reader not sending prompts rather than on a tier name. Fork reach is the only independently switchable action; attachment upload cannot be disabled separately. + +The sandbox reaches the owner's own turns too. While any share over a Session is active the owner can only read inside the granted workspace, and can write only when some share allows writing; a share that is merely published — even one nobody is using — therefore changes the owner's own tool surface until it is stopped or expires. Cancellation has no attribution either: a reader's stop ends whatever turn the shared Session is running. + +The default cards list, the More page, and their recorded goldens lose one card, and the manager's refresh card count drops by one. A person who only knows the plugin page cannot discover LiveShare or switch it on from that page; the package README owns the two enable routes instead. A bundle enabled through the patch route shows its card with the switch off while its rows run, because the switch reflects the profile's bundle selection and writes that selection; the documentation states the two routes and this difference. The rule covers one explicitly named bundle rather than a manifest flag, so adding another hidden-until-running bundle, or retiring this one, is a one-line set edit with a test and docs update. + +Shipped creation produces organization-link shares only: the Share dialog sends neither `accessMode` nor `allowedSubjectIds`, so every new share is `open`, and the deployment's `LIVESHARE_ALLOWED_SUBJECTS` is the only subject-level narrowing a new share can carry. Stored `selected` and `approval` records keep working and keep their access summaries, and the create fields stay on the Remote for those records and direct callers while no UI exposes them. diff --git a/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.zh.md b/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.zh.md new file mode 100644 index 0000000000..871eb3fe91 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-09-13-liveshare-protocol-and-owner-surfaces.zh.md @@ -0,0 +1,156 @@ +# Agent Note: Liveshare —— 把 DSH 会话分享给同事看 + +Status: implemented + +[English](2026-09-13-liveshare-protocol-and-owner-surfaces.md) | 中文 + +## Problem + +DSH 会话跑在你自己的电脑上。同事有时需要在你工作的同时看某个会话——跟着一起排查问题，或者看看一个长任务进展到哪了。现在没有这个能力。把会话日志发过去并不等价：对方要有你的插件、配置和沙箱才能渲染出来，而且会话只有在你机器上运行时才有意义。 + +所以一次分享要同时解决三件事：一个**同事用浏览器打开就能看的页面**，看到你机器上正在跑的会话，但不需要连到你的机器；一个**对页面能做什么的限制**，从"能读、不能写文件"开始——页面多给一个你没同意的操作就是安全漏洞，不是便利；以及一个**"这是谁分享的"的答案**，因为说不清归属的页面，打开它的人无从信任。 + +这条 Note 覆盖 owner 自己 DSH 里运行的那一半——分享对话框、背后的 owner 端服务、本包的浏览器端，以及读者打开的页面——以及双方共用的协议包。中间的 Liveshare 服务端是独立的包（`@deepseek-ai/dsh-experimental-liveshare-relay`），单独审查与部署。 + +## Decision + +### 一次分享是什么 + +owner 在 DSH 里为某一个会话创建分享。分享发布到 Liveshare 服务端（双方都能访问的服务）后，DSH 返回一个链接。打开链接看到的是 owner 自己的 DSH 用自己插件渲染出的会话，读者不需要 owner 的配置。读者列表包含源会话，以及该读者通过分享创建的子会话。工作区名称、成员和顺序裁剪为这些会话；无关会话和工作区保持不可见。 + +从 DSH 分享弹窗新建的分享是**组织内持链接**分享：它携带 `accessMode: 'open'`，组织内拿到链接的人都能看。部署级 `LIVESHARE_ALLOWED_SUBJECTS` 会并入每份分享的 ACL：对 `open` 分享，它把准入收窄到列出的主体；对已存储的 `selected` 记录，它把列出的主体加在记录自己的选择旁边。 + +**指定同事（`selected`）与更早的 `approval` 拼写是旧版持久记录。** Host 仍按记录里的 ACL 读取它们并展示访问摘要，Liveshare 服务端仍按该 ACL 接纳它们的查看者，但随版本发布的分享弹窗不提供新建入口。`liveshareShares.create` 的 `accessMode` 与 `allowedSubjectIds` 字段保留给这些记录以及直接调用该 Remote 的调用方；随版本发布的弹窗两个都不发送。 + +### 读者能做什么 + +读者页面就是正常的 DSH 客户端，不是精简版：侧栏、会话列表、展开折叠、选择都在，因为浏览本来就是"看"的一部分。缺的只是读者无权执行的动作——创建无关会话、重命名、归档、删除、管理工作区。分支遵循分享自己的 fork 开关；发送消息在两档里都可用，并在该档的沙箱内运行；附件上传跟随读者可见的会话。管理权限与档位和 fork 开关都保持独立。 + +这些动作不是用 CSS 藏起来的。页面能做什么由一份访问快照决定：remote-access 客户端跟随读者自己的 `remoteAccess/follow`，每个按钮和菜单项经 `useRemoteAccess`、`useAccess` 或 `useSessionAccess`、`useWorkspaceAccess` 读取其端点在全局资源、某个会话或某个工作区上的答案，答案变化时重新渲染。owner 的 DSH 依据该分享的 `share-viewer` 策略计算快照，因此 owner 收回某项能力时，对应入口不用重新加载页面就会关闭——而且服务端本来就会拒绝这些操作，页面只是不去提供注定被拒绝的按钮。读者收到的 index 已带上读者的首份快照，因此页面在确认允许之前不会显示任何入口；快照流失败后，所有答案都为拒绝。owner 自己的页面以 owner 基线打开，行为与普通 DSH 完全一致。快照不包含逐会话的拒绝原因：页面陈述页面级原因（分享模式、停止、过期、失去访问权）和通用的只读文案。拿不到分享正文时，页面顶部直接陈述该状态，并且每一档都给出读者自己能做的动作（重试、重新登录、回到分享列表，或明确指引联系分享者），不会停在空白外壳或错误码上。 + +### 两档驱动 + +每个分享带一个 `ViewerSessionMode`，只有两个值，且两档都会驱动共享会话： + +- **view** —— 读者通过普通 prompt 路径驱动共享会话的 loop，在授予工作区的只读沙箱里运行，因此会话的工具绝不写文件。读取与检索面（`read`、`read_image`、`glob`、`grep`、`present`）、无本地文件副作用的工具（`todo_write`、`skill`、`web_search`、`web_fetch`）都限制在授权范围内：工具运行前检查其声明的每个路径，无法检查的调用一律拒绝。 +- **write** —— 读者在受宿主写入上限约束的可写沙箱里驱动同一个 loop，沙箱也会修改授予工作区内的文件。 + +沙箱安装在会话上，但只约束分享查看者发起的轮次：`agent/pre-step` 记录一个已准入轮次的进入输入是否带有 share-viewer principal，守卫与替代定义对该轮次的每次执行读取这一结论。所有者自己发起的轮次保留会话自己的工具；所有者在查看者轮次中追加的输入仍留在该受限轮次内。该标记只存在于 Host 内存，按轮次重算，不写入会话日志。所有分享停止或全部过期后执行层被释放，会话恢复自己的工具。 + +较早的词汇有三档——`view` 只观看、`fork-readonly` 分支、`write` 可写。`view` 与 `fork-readonly` 只差在读者能否分支并驱动子会话，而这已经由分享自己的 `allowsFork` 开关决定；第三档重复了该开关，还会让两处答案互相矛盾，因此由两档驱动取代。 + +fork 不是一档。分享自带独立的 `allowsFork` 开关，与档位无关：`view` 分享可以允许 fork，`write` 分享也可以拒绝。fork 创建的子会话归读者所有，带有自己的只读或可写上限，源会话保持不变。 + +附件上传既不是一档，也不是一个开关。`fileUploads/upload` 随读角色授予，因此分享向读者提供的每条会话都接受文件；只由可见性决定，所有者没有单独的附件开关。 + +本版本不认识的模式、以及宿主无法确定模式的持久记录，都不会被驱动：分享仍可读取，页面会说明它无法确定什么。已退场的 `fork-readonly` 名称不会读回为 `view`；持久化的 owner 记录若写有该值，owner 状态加载时会直接拒绝。 + +沙箱是会话的属性，但按轮次生效：Host 在内存中记录运行中轮次的已准入输入是否带有 share-viewer principal，只约束该轮次，把所有者发起的轮次留在会话原生工具上。此前上线的实现限制每个轮次（包括所有者的），虽不需要读取轮次，却让分享改变了所有者自己的工作方式。持久化轮次请求者被否决：那需要从已提交消息来源折叠的投影、每次执行读取 turn boundary、并与接纳该轮次的分享保持同步，而且在混合或无法确立请求者时仍必须默认拒绝。内存标记让守卫与替代定义对每次执行读取同一个结论，且不新增会话事件；重启后从下一个准入步骤重新计算，被拒绝或从未准入的步骤不留下标记。 + +### 默认可见性 + +本包作为运行时依赖随每个 dsh 安装一同交付，但默认安装必须在插件管理器里完全不显示它：**内置插件配置**下不显示，**实验性插件**下不显示，**更多**页也不显示。用户主动启用它——在当前 profile 的 `cordis.patch.yml` 中插入组合包的行，或在 `dsh.profile.bundles` 中选中该组合包；两条启用路径由[包 README](../../../../packages/experimental/liveshare/README.zh.md)负责。该包仍必须随版本发布、保持可安装，且在此规则之前已启用的用户继续能看到它。 + +Host 的组合包 `enabled` 标志表示 profile 是否选中了这个组合包，这与它的插件是否在运行并不等价：通过 `cordis.patch.yml` 插入组合包的行会让插件运行，而组合包本身仍未选中；因此以 `enabled` 为准的可见性规则会把用户刚刚启用的组合包隐藏起来，使写入文档的启用路径失效。 + +因此管理器维护一个 `HIDDEN_UNTIL_RUNNING` 组合包名集合——当前只有 `@deepseek-ai/dsh-experimental-liveshare`——集合中的组合包只有在它 patch 声明的行至少有一条在运行时才会被列出（`pkg.rows.some(row => row.enabled)`）。过滤发生在两个列表派生之前，因此在满足条件前，它不会出现在主"实验性插件"组、**更多**页、**内置插件配置**和"已安装插件"组中。该集合是 `PluginManagerPage.tsx` 中的客户端数据；Host 的 `listBundles` 契约、profile 格式和已安装包集合都保持不变。`BundleInfo.rows` 已把每条声明的行与当前承载它的 Loader 条目关联起来，客户端的 `PackageView` 携带该条目是否在运行，因此行状态就是两条启用路径的有效答案：删除这些行、把它们置为 disabled，或取消选中组合包，都会让它们停止运行，卡片随之从两个列表消失。 + +卡片隐藏期间组合包 ID 仍可按 ID 打开：`openPkg` 会从未过滤的 Host 组合包列表中解析隐藏的组合包，因此 `pluginNavigation.openBundle('@deepseek-ai/dsh-experimental-liveshare')` 仍能渲染其详情。其它按 ID 链接组合包的界面因此继续可用，组合包页也像其它未选中组合包的页面一样列出各行及其关闭状态。 + +### 分享工作如何限制在授权范围内 + +Owner 而不是查看页或 Liveshare 服务端授权每次会话操作。子会话必须先安装真实作用域工具限制，才能接受消息，冷恢复后也一样：宿主机从基础 `agent/created` 事件安装该限制。该监听器运行时智能体已登记进注册表，但创建尚未完成，AgentLoop 会扣住其排队输入，且监听器抛错会使创建失败，因此被拒绝的限制仍能阻止任何消息。宿主机服务缺失或安装失败都会拒绝子会话；配置开关、工具名或稍后安装的承诺都不是执行限制。 + +共享源会话仍可服务所有者自己的工作。每次读者调用都以「该分享与该读者」专属的 Peer 经所有者自己的 Connection 与 Gateway 分派，该 Peer 的 `share-viewer` principal（分享 ID 与服务端断言的身份三元组）由所有者进程内代码在创建 Peer 时确定，任何线路字段都无法改变它。Gateway 经 remote access 判定该 Peer 的调用以及转发给它的会话通知：本包注册 `share-viewer` 策略，把受服务的读者绑定到共享会话、其自己的 fork 及包含它们的工作区上的读取角色，以及条件按分享模式判定的 fork 与写入角色；除此之外不做任何绑定，因此其它端点和通知一律被拒绝，分享不再服务该读者后也不再有任何绑定。所有者在每次授权、撤权、模式变化与过期时使读者的访问失效，并在授权结束、分享停止或过期时释放读者的 Peer。读者的提示词以 `user-rpc` 消息进入会话，其 `source.principal` 指明该读者；所有者的消息不带 principal。只要该会话还有分享活跃，所有者 Host 就在会话自身作用域内挂载读取与检索面与无副作用工具的受限替代，以及（某个分享允许写入时）有界 `edit` 与 `write`，查看者发起的轮次只能运行这些。所有者自己发起的轮次保留会话原生工具，因此分享不会收窄所有者自己的工作。pre-step 只在内存中记录当前轮次属于哪一类。每次操作都会重新读取分享当前的 Relay 授权，并按授予根目录检查解析后的目标；pre-step 在模型步骤前按 Relay 准入重新检查每条进入消息的查看者，因此撤权前排队的读者输入永远不会驱动模型。读者对共享会话的停止与提示词一样经 Gateway 分派：策略在分享档位确立且会话受沙箱限制时放行，随后由所有者自己的会话控制器停止该会话当前运行的轮次，包括所有者发起的轮次。通用的 Peer、principal 与 remote access 设计见 [Peer principal 与 remote access](../../implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md)。 + +受限文件工具解析其自身参数声明的每个路径，检查获授根目录包含解析结果，再把规范路径交给部署的工具；无路径的搜索使用会话工作目录，由替代定义按命名路径一样检查。受限编辑或写入执行同样的包含检查，然后按会话当前沙箱策略和正常观察策略经文件系统后端编辑或写入。 + +### 重试时保留同一个分支 + +一次 fork 请求绑定查看者、分享、源会话、操作身份和已完成前缀。Owner 在创建子会话前持久化预留该操作，并记录 owner 的 fork 应答返回的子会话；重试已记录的操作会重放该应答，而不是再次 fork。同一身份指定不同前缀会被拒绝。owner 的 `SessionForkRequest` 自己生成子会话 id，因此 host 不发送子会话身份：若 host 在子会话已创建、但操作尚未记录时退出，重试无法指名该子会话，会再创建一个。要关闭这一窗口，需要 Session Controller 的请求接受调用方提供的子会话身份。继承前缀停在无关排队输入之前；只保留紧随其后的请求元数据。被撤销的子会话保留日志，但不能以更宽权限恢复；移除分享不会暴露源会话不受限制的工具。 + +### owner 是谁 + +只有已验证的 owner 才能创建分享。对话框显示 owner 的 DSH 回读到的身份——名字、有效期、何时续期——没有显示名时用身份派生出来的标签。创建分享的代码本身也会拒绝未验证的 owner，不是只看按钮能不能点。 + +登录只做一次，且发生在 owner 点击时页面预留的窗口里。DSH 生成一个短寿命事务，绑定 Liveshare 服务端地址、Liveshare 服务端实例，以及允许完成它的页面；页面打开 DSH 指定的登录页，只接受来自该 origin、该窗口、该事务的一次性 code，并把它交回自己的 DSH。 + +Owner 使用自己保留的校验值兑换代码，以仅所有者可读写的权限保存凭据，并只向签发它的 Liveshare 服务端地址发送。首次登记需要已验证凭据；已有分享重连使用分享管理 token，显式身份认领保留该分享的 ACL、模式、过期时间和 token。分享指定的同事是 owner 的存储选择加上部署自身的允许列表；不会从显示身份派生任何内容。 + +### 读者页面顶部显示什么 + +被服务的页面复用侧栏原有的品牌行，而不是在应用上再压一条横条：原本的 Harness 标记，加上一个 LiveShare 入口，写明是谁分享的、对方跑的是哪个 DSH 版本（Liveshare 服务端自己的 release 另行标注）。点击它回到"我能看的分享"列表页。 + +### 连接断开时 + +读者的数据流可能失败：流消失、Liveshare 服务端取消请求、读取超时。页面只重试定义上可重复的失败；遇到认证、权限与分享不存在的错误就直接停下并显示原因，不会无休止地重连。 + +### 服务出去的页面怎么测 + +读者打开的页面就是 owner 自己的 Web 页面。Liveshare 服务端向 owner 要渲染好的 index 文档，在最前面插入一段很短的 carrier 脚本，页面的 shell 资源和插件 bundle 也从 owner 透传过来，所以页面跑的是 owner 版本的全部插件。carrier 只把页面的调用和流转成 Liveshare 服务端通道上的读请求；由 Liveshare 插件自己识别 viewer 页，挂上 viewer 界面，而不是分享按钮。owner 渲染这份 index 时用读者自己的访问快照取代 owner 基线，页面随后跟随读者的 `remoteAccess/follow` 快照；其他读请求都不夹带读者的授权。 + +读者页面在进程内测试：测试用 carrier、shell 和包括 Liveshare 在内的 client 插件拼出页面，顶替 Liveshare 服务端的读通道，并用脚本化的 owner 回答页面的读请求，因此断言看到的是真实 shell、carrier 与呈现插件。 + +### 本包对外提供什么 + +本包交付一个 Host 程序和一个浏览器端。公开入口包括 Host 导出（`lib/index.js`）、`./client`（`lib/client.js`，closure-factory bundle）、`./viewer-declarations`、分享管理 Remote 的 `./typert` 与 `./remote` 两个面、`./types`、组合包 patch `./cordis.patch.yml`，以及 locale JSON 文件。manifest 以 `dsh.client` 声明浏览器端，`platform` 为 `web`，并列出它需要的客户端服务；该入口读取 `__DSH_LIVESHARE_VIEWER__`：在被服务的查看页上挂载查看页 session 插件及其品牌、模型、权限、会话行与分享路径界面，否则先挂载 owner 生成的 Remote，再挂载 Session 头部操作。 + +分享管理是一个 `liveshareShares` Typert Remote，共十二个方法——`create`、`list`、`stop`、`updatePermissions`、`setCapabilities`、`capabilities`、`relay`、`setRelay`、`identity`、`audit`、`testRelay` 与 `testPublish`——背后是 owner 宿主执行的操作。仅存的同源 HTTP 路由是四条 owner 登录与凭据路由：`/api/liveshare.ownerLoginStart`、`/api/liveshare.ownerLoginRedeem`、`/api/liveshare.ownerLoginCancel` 与 `/api/liveshare.ownerCredential`。 + +出站网关是受监督的子进程，源码入口为 `src/owner-gateway/cli.ts`，发布入口为 `lib/owner-gateway/cli.js`；目录名让它与 DSH API gateway 明确区分。 + +## Alternatives considered + +- **单独做一个只读页面，不服务正常客户端。** 否决：阅读需要浏览、分组与选择，另做一个页面就得把这些全部重建，还会悄悄丢掉产品要保留的导航。 +- **每个按钮各自判断能不能点。** 否决：每个入口都读取 owner 计算的同一份访问快照，后加的界面才不会悄悄重新引入读者无权执行的动作。 +- **让读者页面自己决定权限。** 否决：分享授予什么，只由 owner 与服务端决定；页面只陈述被告知的结果。 +- **把没有模式字段的旧分享当作可写。** 否决：那会把 owner 从未配置的权限交给读者，因此没有模式的分享一律只读。 +- **把登录 code 放进页面地址，或从弹窗的 cookie 读凭据。** 否决：地址会经浏览历史、referrer 和日志泄漏，页面也不应该持有凭据。 +- **页面解释不了某个拒绝时，直接展示服务端的错误原文。** 否决：那段文本可能包含文件路径、凭据或别的读者的会话，所以页面只显示它能担保的稳定原因。 +- **只在可编辑配置或沙箱模式中写执行限制。** 否决：子会话能够改变配置，而逐调用执行选择可能优先于模式。真实操作必须经过单调拒绝的守卫和已验证实现。 +- **只在分派前检查模型路径，或全局限制所有文件系统读取。** 否决：分派前检查与工具调用之间还隔着其他监听器，而全局读取规则还会限制无关 Owner 工作。包含检查在已授权会话自身的读写中执行。 +- **复用部署默认根目录，或把源会话整个尾部复制到子会话。** 否决：两者都可能包含查看者未获授的文件或待处理输入。 +- **以部署共享密钥或自报显示字段作为所有者身份。** 否决：两者都不能识别批准本次发布的已登录人员。 +- **保留三档。** 否决：`view` 与 `fork-readonly` 只差在读者能否分支并驱动子会话，而这已经是独立的 fork 开关。第三档重复了该开关，还会让两处答案互相矛盾。 +- **保留分享级的附件上传开关。** 否决：附件是读者已经能看到的会话上的一条 prompt 的一部分。单独的开关重复了可见性，且只能从可见性里做减法，而上传角色本来就随读角色授予。 +- **按轮次归属请求者并让所有者轮次豁免。** 上线后否决，之后缩小范围：持久化轮次请求者需要仅 Host 可见的消息来源投影、每次执行读取 turn boundary、重新检查接纳该轮次的分享，而且在混合或无法确立请求者时仍必须默认拒绝。现在的实现只为运行中轮次保留内存标记——`agent/pre-step` 读取进入消息的 principal，守卫读取该结论——因此所有者发起的轮次保留会话原生工具，且不新增会话事件。接受的代价是：所有者在查看者轮次中追加的输入仍留在受限轮次内；查看者消息若进入后续步骤，会立即收窄该轮次。 +- **让每个工具自行声明档位或沙箱。** 否决：档位属于分享。逐调用选择会让某次执行凌驾于批准它的授权之上。 +- **严格的 manifest 选中判断。** 否决：直接判断 `pkg.enabled` 代码最少，但默认安装启用 LiveShare 的唯一文档路径是编辑 `cordis.patch.yml`，那不会让组合包被选中。卡片会在插件恰好开始运行时仍然隐藏，与产品规则矛盾。 +- **在 Host 派生有效启用状态。** 否决：`listBundles` 可以以新字段或改写字段报告有效状态，但这会为一条纯客户端的展示规则改动跨包契约，并诱使每个组合包消费方重新解释 `enabled`——它必须继续表示"profile 已选中"。 +- **把 LiveShare 移出安装随附的可选组合包。** 否决：将它从可选集合移除即可从构造上让它处处不可见，但该包仍需随版本作为 npm 包发布并可安装，而且这会把组合包从 Host 列表中完全移除，详情入口也会随之消失。 +- **保留选人器，或换成由目录支撑的选择器。** 推迟：点名同事需要身份目录，而 Liveshare 服务端目前不提供；弹窗无法给出它能验证的选择。已存储的 `selected` 与 `approval` 记录仍按 ACL 工作，在有目录契约之前新建入口保持退役；`liveshareShares.create` 的字段保留给这些记录与直接调用方，所以这是推迟 API，而不是删除它。 + +## Verification + +- 读者页面保留正常导航，且在共享会话与任何分支上都不会出现读者无权执行的动作。 +- 没有 Liveshare bundle 的 DSH 以及 owner 自己的页面，行为与以前完全一致。 +- 分享使用两档之一及该档的沙箱；未知模式、读不懂的应答、没有模式的分享仍可读取，但绝不会被驱动。 +- 没有已验证的 owner 身份，就无法创建分享。 +- 弹窗创建的分享携带 `open`；已存储的 `selected` 或 `approval` 记录保留记录中的 ACL 与访问摘要，`create` 仍会存储调用方请求的 `selected` 模式及其主体。 +- 登录只接受来自该事务 origin、窗口与 state 的一次性 code，别的都不接受；失败或放弃都会丢弃事务，凭据、cookie 与 code 都不进入 URL、存储或日志。 +- 真实 Controller、ToolRuntime、文件系统和 profile 测试覆盖 fork 身份、冷恢复限制、有界执行、撤权和正常取消。已构建查看页必须使用真实 POST 载体和 Owner 授权处理器；确定性显示 fixture（测试前置数据）不替代执行或持久化测试。 +- 生成的 API 文档和两种 SDK 投影与 `user-rpc` 来源 principal 保持一致；该字段只由 `agent/pre-step` 准入校验消费。 +- `ViewerSessionMode` 只有两个成员；持久化的 `fork-readonly` 记录在 owner 状态加载时被拒绝。 +- `view` 分享驱动源会话，拒绝文件写入与越界读取，并在设置 `allowsFork` 时可以 fork。 +- 对读者可见的每条会话，无论档位与 fork 开关如何组合，`fileUploads/upload` 都被允许。 +- 源会话的工具决策只读取会话上挂载的执行层：守卫放行本次安装的读取与检索面与无副作用工具的受限替代，可写会话下另有有界 `edit` 与 `write`，拒绝其它所有工具名，不读取轮次、请求者或来源。 +- 单元测试与真实运行时测试覆盖档位策略、受限读写、fork 上限、执行层的安装与释放，以及基于持久消息来源的 pre-step 准入校验。 +- 插件管理器的组件测试在声明行全部关闭时把该组合包排除在两个列表之外，在声明行有一条运行后列出它，并在它隐藏时仍能按组合包 ID 打开；录制的 golden 与刷新卡片数随该规则变化。 + +## Consequences + +读者页面只能准确到服务端告诉它的程度。能力回答、owner 身份状态、会话模式、owner 的 DSH 版本、登录端点，都由 owner 的 DSH 与 Liveshare 服务端提供；在与本层一起部署之前，页面保持最保守的状态——只读，且登录无法完成——而不是去猜。 + +页面不是安全边界。无论页面做什么，owner 的 DSH 与 Liveshare 服务端都会拒绝读者的写入；这份访问快照的作用只是让页面不去提供注定被拒绝的按钮。 + +已有 ACL 保持不变。无模式记录仍可读取，但不会被驱动；互相矛盾的模式字段被拒绝。没有归属的分享显示为“未验证历史”。 + +Owner 重连状态以原子替换写入，并在单进程内排队，但多个进程共享一个文件仍可能丢失更新或争用网关。跨进程执行归属尚未解决；原子替换本身不是事务或路由认领。包含关系按路径检查：若本地进程在检查与打开之间把获授范围内的目录换成符号链接，可以让查看者的读取改指别处，或让写入落到沙箱可写根内的其他位置。基于目录句柄锚定的操作可以消除这一窗口，留待单独变更引入。发布前仍需完成查看页产物和 SDK 快照验证。 + +`view` 分享不是"只看"：它会在只读沙箱里运行读者的 prompt 与工具调用。想要被动观看的部署没有单独模式，只能依赖读者不发送 prompt，而不能依赖档位名称。fork 是唯一可独立关闭的动作；附件上传无法单独关闭。 + +沙箱同样作用于所有者自己的轮次。只要某会话还有分享活跃，所有者也只能在授予工作区内读取，且只有在某个分享允许写入时才能写入；因此一条仅仅发布、并没有人在用的分享也会改变所有者自己的工具面，直到它停止或过期。取消同样没有归属：读者的一次停止会结束共享会话正在运行的任何轮次。 + +默认卡片列表、**更多**页及其录制 golden 各少一张卡片，管理器的刷新卡片数也减一。只认识插件页的人无法从该页发现 LiveShare 或直接开启它；启用路径由包 README 负责。通过 patch 路径启用的组合包，其卡片显示为关闭状态而行在运行，因为开关反映并写入 profile 的组合包选中状态；文档会说明两条路径及其差异。该规则覆盖一个显式命名的组合包而不是 manifest 标志，因此新增另一个"运行前隐藏"的组合包或退役这一个，都只是一行集合改动，并配一条测试和文档更新。 + +随版本发布的创建流程只产生组织链接分享：分享弹窗不发送 `accessMode` 与 `allowedSubjectIds`，因此新分享一律为 `open`，部署级 `LIVESHARE_ALLOWED_SUBJECTS` 是新分享唯一能获得的主体级收窄。已存储的 `selected` 与 `approval` 记录继续工作并保留访问摘要；`liveshareShares.create` 的字段仍留在 Remote 上供这些记录与直接调用方使用，而界面不暴露它们。 diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml index 368a5a645b..2db7ec7484 100644 --- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml @@ -18,8 +18,8 @@ en: ca63fb903b447c2d zh: 3014adbdb0a890ee /agent-note-on-demand-watching-and-automatic-refresh-for-sidebar-previews-and-file-trees/implementation-and-responsibilities/client-and-sidebar: - en: 5cb8326d8a5b0407 - zh: a31173f990276856 + en: 5be003d933357fee + zh: 0aec7cea1b06a7ce /agent-note-on-demand-watching-and-automatic-refresh-for-sidebar-previews-and-file-trees/watch-requests-and-notifications: en: 025ba83ae78824df zh: 264d74d2bdfe3d27 @@ -42,8 +42,8 @@ en: d688642e5f272d48 zh: 96088fbc0471aeae /agent-note-on-demand-watching-and-automatic-refresh-for-sidebar-previews-and-file-trees/directory-node-tree-and-lifecycle: - en: 2ea8615be8d5229b - zh: 0c73fa4ebb06445e + en: eb011d181eeb83e3 + zh: 7d2cb793fd1737b5 /agent-note-on-demand-watching-and-automatic-refresh-for-sidebar-previews-and-file-trees/user-flows: en: eb4005a334103895 zh: e2c207faffa64e57 @@ -57,8 +57,8 @@ en: 4f343f7a6c4d3ba4 zh: a4390843a20f8dde /agent-note-on-demand-watching-and-automatic-refresh-for-sidebar-previews-and-file-trees/readiness-races-and-refresh-coalescing: - en: caadd187479e9074 - zh: 3deedd8093f60703 + en: baff3282e8925728 + zh: 2052ca0afadd7a1b /agent-note-on-demand-watching-and-automatic-refresh-for-sidebar-previews-and-file-trees/alternatives-considered: en: 8a8c19229647c760 zh: 2de283fc2c815e65 diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md index 99639db2e5..8d9005858d 100644 --- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md +++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md @@ -60,10 +60,11 @@ Notifications invoke existing reload/list operations; a failed reload does not r | Package-private `ResourceGroup` | [resource-group.ts](../../../../packages/client/ui-sidebar-documentpreview/src/client/document/resource-group.ts) | Observes members through existing `resources.source(address)`; `add` joins a resource, `set` reconciles full membership, and `close` releases all members without changing the generic Resource service | | `DocumentBodyOwner`, `HtmlBody`, `createReadHtmlRelative` | [Renderer inputs](../../../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts), [HTML body](../../../../packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.tsx), [Related-file reader](../../../../packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts) | Renderers declare read members through `addResource` and publish the current dependency list through `setResources`; HTML adds CSS/JS resources from Host-reported paths after each read returns and releases unreferenced members after parsing | | Document renderers | [DocumentContent](../../../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) and renderer directories in the same package | Do not watch directly; keep consuming text, bytes, or renderer revisions; `failed()` ends renderer loading without recording a successful version. Check cancellation of previous work, release of old objects, and retention of existing view preferences during refresh | -| `filesFace`, `FilesInjected` | [Files face](../../../../packages/client/ui-sidebar-files/src/client/face.ts) | Remain the existing business entry point, directly owning each Tab's root node; bind directory reads and change streams and forward expand, collapse, refresh, and automatic-refresh operations without a new `FilesController` | +| `filesFace`, `FilesInjected` | [Files face](../../../../packages/client/ui-sidebar-files/src/client/face.ts) | Remain the existing business entry point, directly owning each pane's root node while a navigator draws the pane's tree ([per-pane state](../architecture/2026-10-20-workspace-tree-state-per-pane.md)); bind directory reads and change streams and forward expand, collapse, refresh, and automatic-refresh operations without a new `FilesController` | | Package-private `DirectoryNode` | [directory-node.ts](../../../../packages/client/ui-sidebar-files/src/client/directory-node.ts) | Represents one open directory, owning its stream, read state, and open children; handles local refresh, expansion, recursive closure, and propagation of automatic-refresh state; `setExpanded` updates pending restoration from the latest expansion preferences | -| `createFilesStore`, `FilesTabState`, `LevelState` | [Files store](../../../../packages/client/ui-sidebar-files/src/client/store.ts) | Retain expansion, scrolling, and displayed directory data; distinguish initial loading from refresh over existing content to avoid unmounting subtrees on every background read; hold no watcher or AbortController | -| `FilesBody`, `Level`, `Entry` | [FilesBody.tsx](../../../../packages/client/ui-sidebar-files/src/client/FilesBody.tsx) | Delegate expansion, collapse, refresh, and panel unmount to injected callbacks; render node results without scanning the entire tree into a watch set, using existing framework hooks and store reads | +| `createFilesStore`, `FilesPaneState`, `FilesTreeState`, `LevelState` | [Files store](../../../../packages/client/ui-sidebar-files/src/client/store.ts) | Retain expansion and displayed directory data; distinguish initial loading from refresh over existing content to avoid unmounting subtrees on every background read; hold no watcher or AbortController | +| `FileNavigator` | [FileNavigator.tsx](../../../../packages/client/ui-sidebar-files/src/client/FileNavigator.tsx), [workspace-tree.ts](../../../../packages/client/ui-sidebar-files/src/client/workspace-tree.ts) | Read per-pane state through framework hooks; convert listed levels into entries and directory states; pass expansion, collapse, and drawing lifetimes to the injected Files face, which owns listing, refresh, and watches | +| `FileTree` | [FileTree.tsx](../../../../packages/client/ui-sidebar-files/src/client/FileTree.tsx) | Draw entries, directory states, and expansion from props; report row actions through `onToggle` and `onOpen`. The root-scoped `sidebar.files.tree` Factory reads localized copy and its local `accessory` Component through framework seats, without owning listings or watches | | Files registration | [Files client/index.ts](../../../../packages/client/ui-sidebar-files/src/client/index.ts) | Add a directory-change callback to the existing `filesFace`; keep async effects in injection, without importing another feature plugin's runtime exports | ## Watch requests and notifications @@ -176,13 +177,14 @@ Pause and play use existing icons; manual reload retains its circular arrow. No ```text Files.open - → FilesBody → Session.cwd + Tab - → filesFace.start → DirectoryNode.open + → FileNavigator → Session.cwd + pane + → filesFace.hold → DirectoryNode.open → changes(sessionId, path) → Host.watch(depth: 0) → ready → DirectoryNode → list(sessionId, path) - → createFilesStore.levels[path] - → Level / Entry + → createFilesStore.byPane[paneId].tree.levels[path] + → FileNavigator → workspace-tree.ts: workspaceEntries / workspaceDirectories + → renderFactorySlot('sidebar.files.tree', input) → Level / Entry Entry.expand → filesFace.toggle @@ -204,7 +206,7 @@ The directory panel obtains invalidations and listings through injected Remote c ## Directory-node tree and lifecycle -The Files runtime is itself an on-demand directory tree. It does not first construct the whole Workspace tree or separately derive a flat watcher set. Existing `filesFace` owns each Tab's root; `DirectoryNode` owns reads, observation, and release recursively, without another controller class. +The Files runtime is itself an on-demand directory tree. It does not first construct the whole Workspace tree or separately derive a flat watcher set. Existing `filesFace` owns each pane's root; `DirectoryNode` owns reads, observation, and release recursively, without another controller class. | Node responsibility | Behavior | |---|---| @@ -239,14 +241,14 @@ The parent's watch still detects deletion, renaming, or replacement of a collaps | First open | Subscribe to the file Resource and read contents | Open the root node, which subscribes and lists | | Expand child | No effect | The parent opens the child; the child subscribes and reads direct entries, progressively restoring still-present descendants from preferences | | Collapse child | Open file previews keep their watches | Release that directory and its hidden descendants; expansion preferences and displayed cache may remain | -| Switch Tab or unmount panel | The Tab pin retains file metadata; an unmounted body does not reread, and refreshes on return according to pending Resource changes and toggle state | Retain expanded nodes and watchers for the Tab lifetime; do not introduce another panel-visibility lifetime | +| Switch Tab or hide the tree | The Tab pin retains file metadata; an unmounted body does not reread, and refreshes on return according to pending Resource changes and toggle state | Switching between a pane's file tabs keeps expanded nodes and watchers, because the next tab draws the tree in the same commit; hiding the tree or showing a tab without it closes them while the store keeps expansion and displayed levels, which the next drawing lists again in place | | Manual refresh | Reuse the current preview reload without rebuilding the Resource system | Recursively refresh open children from the root, without entering collapsed directories or rebuilding all watchers | -| Last holder closes | Resource abort ends the file stream; the Host awaits watcher closure | Tab closure ends every directory stream, cancels reads, and forgets Tab state | +| Last holder closes | Resource abort ends the file stream; the Host awaits watcher closure | Once no navigator is mounted in a pane and no open tab last drew one there, every directory stream ends, reads are cancelled, and the pane's state is forgotten | | Connection recovers | Stat again after the new stream's ready frame, discovering changes even without event replay | List every still-watched directory after its new stream's ready frame | -Files watches follow Tab lifetimes. Collapse closes the corresponding subtree; Tab closure releases the root and its entire active tree. Temporarily hiding the panel does not rebuild nodes, keeping implementation within the existing entry point and directory objects. The store retains expansion preferences; nodes use them for progressive restoration only when reopened, without a second global expansion set. +Files watches follow each pane's drawn tree. Collapse closes the corresponding subtree; the end of the pane's last drawing releases the root and its entire active tree, and the pane's state is forgotten once no open tab last drew the tree there. The store retains expansion preferences and displayed levels; nodes use them for progressive restoration only when reopened, without a second global expansion set. -`ResourceRegistry` continues sharing identical complete file Resource addresses. Parent-child ownership prevents duplicate active branches inside one Tab. This version adds no global watcher deduplication across Sessions, windows, or path aliases. Ordinary file rows do not each subscribe to file watches; only files opened as preview Resources acquire independent file observation. +`ResourceRegistry` continues sharing identical complete file Resource addresses. Parent-child ownership prevents duplicate active branches inside one pane. This version adds no global watcher deduplication across Sessions, windows, or path aliases. Ordinary file rows do not each subscribe to file watches; only files opened as preview Resources acquire independent file observation. ## User flows @@ -281,8 +283,8 @@ Observation, reads, and presentation need a few explicit ordering rules, not dis - Events mean that a target may have changed, not exact replay of a user operation. Duplicate Chokidar events and consecutive writes may coalesce; files deduplicate versions, and directories coalesce pending refreshes. - Each directory has at most one active list. Further invalidation during that request or its completion marks a pending reread, which runs afterwards rather than building an arbitrary queue of refresh jobs. - File refresh reuses read generations and renderer revisions. Consecutive notifications must not let old requests overwrite new content or endlessly reload an already handled version. -- Background directory refresh retains the displayed listing without a display-unused `refreshing` flag. Only a directory without displayable entries enters `loading`, avoiding subtree flicker and repeated watcher reconstruction. -- After collapse, deletion, or Tab closure, late cancelled reads cannot recreate state or restore watchers. Cancellation closes the Host watcher even while the generator is suspended at a yielded frame; stream and plugin teardown await closure. +- Background directory refresh retains the displayed listing and marks it `refreshing`; the display ignores the mark, while locating a file waits on it for the directory to be listed again. Only a directory without displayable entries enters `loading`, avoiding subtree flicker and repeated watcher reconstruction. +- After collapse, deletion, the end of a drawing, or the pane's state being forgotten, late cancelled reads cannot recreate state or restore watchers. Cancellation closes the Host watcher even while the generator is suspended at a yielded frame; stream and plugin teardown await closure. - Temporary file disappearance while its parent remains does not end observation. Ordinary file changes and watcher failures remain distinct; same-path file watches cover atomic saves and delete/recreate. - Existing file reads are not transaction snapshots: writes can occur between stat and content reading. Later notifications trigger refresh; automatic refresh does not promise an atomic snapshot for every read. diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md index 5d11041a5c..ef557b336a 100644 --- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md +++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md @@ -60,10 +60,11 @@ Sidebar 的 Document Preview 和 Files 面板都需要反映磁盘上的最新 | 包内 `ResourceGroup` | [resource-group.ts](../../../../packages/client/ui-sidebar-documentpreview/src/client/document/resource-group.ts) | 通过现有 `resources.source(address)` 观察成员；`add` 加入资源，`set` 更新完整成员列表，`close` 释放全部成员，不改变通用 Resource 服务 | | `DocumentBodyOwner`、`HtmlBody`、`createReadHtmlRelative` | [渲染器输入](../../../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts)、[HTML body](../../../../packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.tsx)、[关联文件读取](../../../../packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts) | 渲染器通过 `addResource` 声明读取到的成员，通过 `setResources` 提交本次依赖列表；HTML 在每次读取返回后按 Host 报告的路径加入 CSS／JS 资源，解析结束后释放不再引用的成员 | | 各文档渲染器 | [DocumentContent](../../../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) 及同包各渲染器目录 | 不接 watch；继续消费文本、字节或 renderer revision；`failed()` 结束渲染器加载但不记录成功版本。检查刷新时取消旧任务、释放旧对象及保留现有视图偏好 | -| `filesFace`、`FilesInjected` | [Files face](../../../../packages/client/ui-sidebar-files/src/client/face.ts) | 继续作为已有业务入口，直接持有各 Tab 根节点；绑定目录读取和变化流，转发展开、折叠、刷新及自动刷新开关，不新增 `FilesController` | +| `filesFace`、`FilesInjected` | [Files face](../../../../packages/client/ui-sidebar-files/src/client/face.ts) | 继续作为已有业务入口，在导航栏绘制分栏目录树期间直接持有各分栏的根节点（[按分栏保存状态](../architecture/2026-10-20-workspace-tree-state-per-pane.zh.md)）；绑定目录读取和变化流，转发展开、折叠、刷新及自动刷新开关，不新增 `FilesController` | | 包内 `DirectoryNode` | [directory-node.ts](../../../../packages/client/ui-sidebar-files/src/client/directory-node.ts) | 表示一个已打开的目录，拥有本目录变化流、读取状态和已打开子节点；负责局部刷新、展开、递归关闭，以及向子节点传递自动刷新状态；`setExpanded` 按最新展开偏好更新待恢复节点 | -| `createFilesStore`、`FilesTabState`、`LevelState` | [Files store](../../../../packages/client/ui-sidebar-files/src/client/store.ts) | 保留展开、滚动和目录显示数据；区分首次加载与已有内容上的刷新，避免每次后台重读都把子树卸载；不保存 watcher 或 AbortController | -| `FilesBody`、`Level`、`Entry` | [FilesBody.tsx](../../../../packages/client/ui-sidebar-files/src/client/FilesBody.tsx) | 将展开、折叠、刷新和面板卸载交给注入回调；按节点展示结果渲染，不扫描整棵树生成监听集合，展示仍只读已有框架钩子与存储 | +| `createFilesStore`、`FilesPaneState`、`FilesTreeState`、`LevelState` | [Files store](../../../../packages/client/ui-sidebar-files/src/client/store.ts) | 保留展开和目录显示数据；区分首次加载与已有内容上的刷新，避免每次后台重读都把子树卸载；不保存 watcher 或 AbortController | +| `FileNavigator` | [FileNavigator.tsx](../../../../packages/client/ui-sidebar-files/src/client/FileNavigator.tsx)、[workspace-tree.ts](../../../../packages/client/ui-sidebar-files/src/client/workspace-tree.ts) | 通过框架钩子读取各分栏状态；将已列出的层级转换为条目与目录状态；将展开、折叠和绘制生命周期交给注入的 Files face，由它负责列出目录、刷新与监听 | +| `FileTree` | [FileTree.tsx](../../../../packages/client/ui-sidebar-files/src/client/FileTree.tsx) | 根据属性绘制条目、目录状态与展开状态，通过 `onToggle` 和 `onOpen` 报告行操作。root 作用域的 `sidebar.files.tree` Factory 通过框架席位读取本地化文案与局部 `accessory` 组件，不持有目录列表或监听 | | Files 注册入口 | [Files client/index.ts](../../../../packages/client/ui-sidebar-files/src/client/index.ts) | 给现有 `filesFace` 增加目录变化流回调；异步副作用留在注入实现，不引入另一个功能插件的运行时导出 | ## 监听接口与事件内容 @@ -176,13 +177,14 @@ Document Preview 和 Files 各自保留原 reload 按钮。独立自动刷新开 ```text Files.open - → FilesBody → Session.cwd + Tab - → filesFace.start → DirectoryNode.open + → FileNavigator → Session.cwd + pane + → filesFace.hold → DirectoryNode.open → changes(sessionId, path) → Host.watch(depth: 0) → ready → DirectoryNode → list(sessionId, path) - → createFilesStore.levels[path] - → Level / Entry + → createFilesStore.byPane[paneId].tree.levels[path] + → FileNavigator → workspace-tree.ts: workspaceEntries / workspaceDirectories + → renderFactorySlot('sidebar.files.tree', input) → Level / Entry Entry.expand → filesFace.toggle @@ -204,7 +206,7 @@ Process → create / remove / rename ## 目录节点树与生命周期 -Files 的运行时对象本身就是一棵按需打开的目录树，不先建立整棵 Workspace 树，也不另算一个扁平的 watcher 集合。现有 `filesFace` 持有各 Tab 根节点，读取、监听和释放逐层交给 `DirectoryNode`，不另抽控制器类。 +Files 的运行时对象本身就是一棵按需打开的目录树，不先建立整棵 Workspace 树，也不另算一个扁平的 watcher 集合。现有 `filesFace` 持有各分栏的根节点，读取、监听和释放逐层交给 `DirectoryNode`，不另抽控制器类。 | 节点职责 | 具体行为 | |---|---| @@ -239,14 +241,14 @@ workspace/ watch | 首次打开 | 打开文件 Resource 监听并读取正文 | 打开根节点，由根节点建立监听并读取列表 | | 展开子目录 | 无影响 | 父节点打开对应子节点；子节点监听并读取直接子项，按偏好逐层恢复仍存在的后代 | | 折叠子目录 | 已打开的文件预览继续监听 | 释放该目录及其当前不可见后代的监听；可保留展开偏好和显示缓存 | -| 切走 Tab 或面板卸载 | Tab pin 继续持有文件元数据流；正文组件不在时不主动重读，切回来按待处理 Resource 变化与开关状态补刷新 | 此版沿用 Tab 生命周期，保留已展开目录节点和监听；不另外引入面板显隐生命周期 | +| 切走 Tab 或隐藏目录树 | Tab pin 继续持有文件元数据流；正文组件不在时不主动重读，切回来按待处理 Resource 变化与开关状态补刷新 | 在分栏的文件 tab 之间切换时保留已展开目录节点和监听，因为下一个 tab 在同一次提交中绘制目录树；隐藏目录树或显示不带目录树的 tab 时关闭它们，存储保留展开状态与已显示的层级，下一次绘制时就地重新列出 | | 手动刷新 | 重用当前预览 reload，不重建整套 Resource | 从根节点递归刷新已打开子节点，不进入折叠目录，也不重建全部 watcher | -| 关闭最后一个持有者 | Resource abort，文件流结束，Host 等待 watcher 关闭 | Tab 关闭时终止全部目录流、取消读取并删除 Tab 状态 | +| 关闭最后一个持有者 | Resource abort，文件流结束，Host 等待 watcher 关闭 | 分栏中没有挂载的导航栏、也没有最近一次在那里绘制导航栏的打开 tab 时，终止全部目录流、取消读取并删除该分栏的状态 | | 连接恢复 | 新流 ready 后重新 stat，即使断线期间没有可回放事件也能发现变化 | 新流 ready 后重新 list 所有仍需观察的目录 | -Files 监听跟随 Tab 生命周期；折叠关闭对应子树，关闭 Tab 则释放根节点与整棵活动树。暂时隐藏面板不额外拆除和重建节点，这使改动集中在现有入口和目录对象。存储保留展开偏好，节点只在重新展开时用这份偏好逐层恢复，不维护第二份全局展开集合。 +Files 监听跟随各分栏已绘制的目录树；折叠关闭对应子树，分栏最后一次绘制结束时释放根节点与整棵活动树，没有打开的 tab 最近一次在该分栏绘制目录树时，还会删除其状态。存储保留展开偏好与已显示的层级，节点只在重新展开时用这份偏好逐层恢复，不维护第二份全局展开集合。 -同一个完整文件 Resource 地址的共享继续由 `ResourceRegistry` 完成。目录节点的父子所有权保证一个 Tab 内同一分支不会重复打开；第一版不增加跨 Session、跨窗口或路径别名的全局 watcher 去重系统。目录下的普通文件项不各自订阅文件 watch，只有真正打开为预览 Resource 的文件才取得独立文件监听。 +同一个完整文件 Resource 地址的共享继续由 `ResourceRegistry` 完成。目录节点的父子所有权保证一个分栏内同一分支不会重复打开；第一版不增加跨 Session、跨窗口或路径别名的全局 watcher 去重系统。目录下的普通文件项不各自订阅文件 watch，只有真正打开为预览 Resource 的文件才取得独立文件监听。 ## 用户可见动线 @@ -281,8 +283,8 @@ Files 监听跟随 Tab 生命周期；折叠关闭对应子树，关闭 Tab 则 - 事件表示“目标可能变化”，不是一次用户操作的精确回放。Chokidar 的重复通知和连续写入可以合并；文件按版本去重，目录按待刷新状态合并。 - 同一目录最多有一次有效 list 在途；在途或读取收尾期间再次失效，只记录需要补读，随后读取最新状态，不累计任意长度的刷新任务队列。 - 文件自动刷新复用读取代次和 renderer revision。连续通知不能让旧请求覆盖新内容，也不能因同一已处理版本而无限 reload。 -- 目录后台刷新保留当前列表，不另存没有显示用途的 `refreshing` 标记；只有没有可显示列表时才进入 `loading`，避免子树闪烁和监听反复重建。 -- 目录折叠、删除或 Tab 关闭后，已取消读取的晚到结果不得重新创建状态或恢复监听。即使生成器停在已产出的帧上，取消也会关闭 Host watcher；流与插件拆除等待关闭完成。 +- 目录后台刷新保留当前列表并标记 `refreshing`；显示不受该标记影响，定位文件据此等待目录重新列出；只有没有可显示列表时才进入 `loading`，避免子树闪烁和监听反复重建。 +- 目录折叠、删除、绘制结束或分栏状态被删除后，已取消读取的晚到结果不得重新创建状态或恢复监听。即使生成器停在已产出的帧上，取消也会关闭 Host watcher；流与插件拆除等待关闭完成。 - 父目录保持存在时，文件短暂消失不结束监听；正常文件变化与监听自身失败分别处理。同路径文件监听覆盖原子保存与删除重建。 - 原有文件读取并非事务快照，stat 与正文读取之间仍可能发生写入；后续通知触发刷新，自动刷新不保证每次读取都获得原子快照。 diff --git a/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml b/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml new file mode 100644 index 0000000000..53d2b74f3a --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-10-09-forge-panel.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 .agents/notes/implemented/feature/2026-10-09-forge-panel.md +/agent-note-change-request-panel-and-worktree-sessions: + en: a524673f0d9cc9d8 + zh: db8a2c1ad8f9c8a3 +/agent-note-change-request-panel-and-worktree-sessions/problem: + en: 344bcc7e9825bbc8 + zh: c1d0f4b54f5b3786 +/agent-note-change-request-panel-and-worktree-sessions/decision: + en: 6a0dc836205863ba + zh: 3d4feb0385953dda +/agent-note-change-request-panel-and-worktree-sessions/deferred: + en: 32ef8af85f4d2f66 + zh: b82b67f94346399e +/agent-note-change-request-panel-and-worktree-sessions/alternatives-considered: + en: e471e16b6b6450ca + zh: 5fbc9242edc8d112 +/agent-note-change-request-panel-and-worktree-sessions/consequences: + en: 81790c448f0a7d3b + zh: ec63ccb2ad315ff8 diff --git a/.agents/notes/implemented/feature/2026-10-09-forge-panel.md b/.agents/notes/implemented/feature/2026-10-09-forge-panel.md new file mode 100644 index 0000000000..1285ba6cdf --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-09-forge-panel.md @@ -0,0 +1,92 @@ +# Agent Note: Change request panel and worktree Sessions + +Status: implemented + +English | [中文](2026-10-09-forge-panel.zh.md) + +## Problem + +[Session change request bindings](2026-10-09-session-change-request-bindings.md) give each Session a list of change requests, but nothing shows it. A user who asks the agent to open change requests needs their checks, reviews, and mergeability without leaving the conversation, and wants a new Session's edits and commits kept out of the current checkout. Git must run where the Session's commands run, which can be a remote or confined execution world; inspection must not change the repository, and a worktree must exist before the model's first action. + +## Decision + +[`dsh-experimental-client-ui-forge`](../../../../packages/experimental/client-ui-forge/README.md) is a two-face package. Its Host half, the `forgePanel` Remote, assembles everything the panel shows for one Session into one streamed state; the forge registry and the binding service keep only their domain operations. Its Client half is a right-sidebar tab, a Session header button that shows or hides it, a New Session option, a creation card above the composer, a toast, and the [Session list icons and hover card section](2026-10-20-forge-session-list.md). Every surface calls a bound item a change request, the forge registry's term, whatever its code host calls it. The [forge bundle](../../../../packages/experimental/forge-bundle/README.md) ships the panel, the forge registry, the GitHub provider, the bindings, and an isolated worktree service as one default-disabled Plugins page entry. + +The Remote inspects the checkout through the Session's subprocess provider under its [resolved permissions and query restrictions](../bug-fix/2026-10-28-forge-git-session-permissions.md), so it reads what the Session's commands see. Inspection reads the top-level, Git, and common Git directories, the branch or the abbreviated HEAD commit, the upstream, the remotes, and the size of the branch's changes against its fork point. It runs when a Session is followed, after each `working-directory/change`, `tool/result`, and `sandbox/mode` event, and on refresh, one at a time with one trailing rerun. + +Status polling follows panel subscriptions: a Session's bindings are watched only while one of its surfaces is mounted, and the registry stops polling change requests nobody watches. Each card keeps the last snapshot a poll returned, so a transient failure keeps the title and number visible. A Session's only open change request starts expanded, and with several every card starts collapsed; the user's first toggle replaces this default. + +An expanded card marks a draft ready for review and merges a change request the host would merge now. The forge seam carries both as provider actions that return a typed failure, and every snapshot says whether the host would merge the change request now for the signed-in user and which methods the repository allows, so the panel offers only actions that can succeed. A merge carries the head commit the card showed, and the host refuses it once new commits arrived. The panel acts only on change requests bound to the Session. + +A new Session starts in a worktree through a request, not an immediate creation. Checking the option in the New Session row, a `conversation.hero.options` entry, appends a `plugin:client-ui-forge/worktree` record with the base branch; changing the base or clearing the option appends another, and nothing touches the repository until the user sends. The option is offered only where creation can succeed: under `workspace-write`, the checkout and its common Git directory must lie inside the writable root, which excludes a project that is itself a linked worktree. The worktree must exist before the first message's turn starts, so the turn runs there and its first request already names the new directory. When the message enters the Session's inbox, the panel's `agent/inbox/inserted` listener starts maintenance of the Agent before the delivery wakes it; the Agent latches the wake until the maintenance ends, and the panel creates and enters the worktree inside it. The creation's stage streams to a card above the composer, where Cancel stops the attempt. After a stopped or failed attempt the message keeps waiting in the inbox, and the card keeps the failure and offers another attempt with a new branch name or Continue without a worktree, which withdraws the request and lets the message go on. An `agent/pre-step` listener still creates the worktree at the first step proposal of a Session whose request is open, because a message that enters while the Agent runs a turn or other maintenance gets no hold; it moves the working-directory notice into the proposed messages, and a failure ends the turn. The `forgeWorktree` projection ignores requests after the first `turn/start` and creations after the first `step/start`, so a running Session never moves. The tab's first row names the branch the Session works on, and the Session list marks a Session that works in its created worktree. + +The worktree a Session works in can be removed outside it. Each inspection checks whether the created worktree's directory still exists, and every message that enters while the Agent is idle starts a hold that checks again, so the message waits without starting its turn while the directory is missing. The check must come before the turn: while it assembles a step's context, the working-directory service moves a Session whose directory is gone back to its project, before any pre-step listener runs. Restore checks the branch out again at the recorded directory, or creates the branch again at its base commit when it is gone; Continue in the project moves the Session to the source checkout. Either runs inside the hold and lets the waiting message go on. + +The panel does not move a Session between existing worktrees. Removing a change request appends a `dismiss` record, and its toast offers Undo through `track`. + +The panel also shows the changes behind a Session's work in a changes view, a resource tab type of this package. The Remote parses every diff on the Host into files and hunks, so the browser draws them without a patch parser, and bounds each read with `maxDiffBytes` and `maxUntrackedFiles`. Local changes come from `git diff` using the Session's permissions and execution world, in a scope the user picks: the branch against its fork point by default, or the uncommitted, unstaged, or staged changes; untracked files are read through the Session's filesystem and shown as new files. A change request's changes come from its code host at the head of the binding's latest status, through two provider reads the forge seam gained, `diff` and `fileText`. The Host keeps the patch it read last for each change request, keyed by the head commit and base branch and bounded by `maxCachedDiffBytes`, so reopening, refreshing, and navigating at the same head download nothing again; a host or provider that refuses an answer over its size limit reports the forge failure `too-large`, and the view then offers the change request's web page instead of a retry. Unchanged lines between hunks expand from the file's new side, which is the working tree, the index, or the head commit, and only while that text still matches the hunks. Each inspection also sizes the branch's changes for a local changes card, shown while no open change request carries the checked-out branch; its Create change request sends the Session a user message, so the Agent creates the change request with its own tools and the binding follows from `gh pr create` as for any other. + +Review comments capture the file, side, range, complete hunk, and reviewed head when the user selects code. Agent references enter the existing composer quote mechanism, so the user controls batching and the sent message records exactly what the model receives. GitHub writes belong to the optional forge provider operation: preflight checks the current head, the write addresses that commit, and an ambiguous outcome blocks another write until the user reconciles it. Review drafts and inline records belong to a browser tab occurrence, not to the Session log or a GitHub pending review. Switching Sessions retains that occurrence; closing it discards the local state and rejects late write completions. Published GitHub comments remain external records. + +## Deferred + +A left-navigation review page next to Plugins and Scheduled tasks, listing the user's pull requests or merge requests on the selected provider, is deferred. It attaches without changing this package's Session surfaces: + +- **Provider capability** — an optional `ForgeProvider` method such as `listForViewer(host, filter, signal)` returns change request references; GitHub implements it with `gh search prs --author @me` or the GraphQL `viewer`, and the registry aggregates enabled providers. +- **Remote** — a stream like `follow` that is keyed by provider and filter instead of a Session and polls through the same `ctx.forge.watch`. +- **Client** — a `sidebar.panellist` entry with a `main` page in this package, as `ui-schedule` does, rendering `ChangeRequestCard`, which takes a change request, its snapshot, and optional actions. +- **Settings** — provider choice and hosts on the bundle's configuration page. + +The changes view offers no scope for one commit or for the last turn yet; both would be further `ForgeLocalScope` kinds read through `localDiff`. + +## Alternatives considered + +**Per-host nouns.** Calling items pull requests on GitHub and merge requests on GitLab would need each provider to declare its noun and every string to take it; GitHub is the only provider, and one term keeps the copy fixed. + +**Merging through `gh pr merge`.** It enables auto-merge while required checks are pending and joins a merge queue when the base requires one, so a click could schedule a later merge instead of merging. The REST merge endpoint merges at once or refuses. + +**Deleting the head branch after a merge.** The Session's worktree can be on that branch. + +**A Host service package for Git inspection.** No second consumer needs checkout facts yet; a model tool can move them into a shared service when it exists. + +**Running Git as a Host process.** Remote and confined execution worlds would show the Host's files instead of the Session's, and the Host would read directories the Session cannot. + +**Creating the worktree when the option is checked.** Every toggle or base change would create and abandon a checkout, and the Session would move before the user decided to send. + +**Carrying the option in the Session creation request.** The Session controller owns a closed request; a plugin record keeps the option inside this package and survives a reload of the blank Session. + +**Switching between existing worktrees from the panel.** A switched Session keeps the sandbox root of its project, so a worktree outside the project stays read-only, and moving mid-conversation splits the model's view of the files. Starting a Session in its worktree avoids both. + +**The option in the composer tool row.** The tool row stays after the first message, when the option no longer applies; the New Session row disappears once the Session starts. The row offered only single slots, so `ui-conversation` gained the list slot `conversation.hero.options`. + +**Creating the worktree within the first turn.** The turn has started when the first step proposal runs: its context was assembled for the old directory, a failure can only end the turn and drop the claimed message, and the working-directory service has already moved a Session out of a removed worktree. It remains the fallback for a message no hold took. + +**Holding the message at Agent admission.** An `agent-controller/admission` stage would hold a message before it enters the inbox, so the composer keeps it until the worktree exists and a failure returns it for editing. It needs a controller service in front of every sender's delivery, a core addition that one panel does not justify; a hold at inbox insertion uses the existing inbox event and maintenance, and covers every sender. + +**Returning a waiting message to the composer.** Once the Host accepted a message the composer cannot take it back without a new public API in the conversation package for one plugin; the message keeps waiting with the card's actions instead. + +**A submit gate in the Web composer.** The browser held the message before the Host saw it, so every check needed a Remote call, the stage of a refused message lived only in the browser, and other senders bypassed it. A hold at inbox insertion keeps the message where it enters the Agent and the failure in the panel state. + +**The creation card in the transcript.** Transcript nodes accept no plugin kinds; the input dock above the composer is the nearest list slot, and it renders on the New Session screen. + +**Manual URL tracking.** It duplicated the bindings the Session's own commands record. Bindings come from `gh pr create`, the `gh pr` commands that act on one change request, pushes, and the branch the checkout tracks, and `track` remains for Undo. + +**Parsing patches in the browser.** The Remote would carry unbounded patch text, and the browser would need a patch parser; the Host bounds the read and parses it once. + +**Reusing the review tab's file comparison.** It belongs to another plugin, which this package may not import at run time, and moving it into the shared primitives would change a shared package for one consumer; the view is built from the shared highlighter, menu, tooltip, and diff color tokens instead. + +**Reading a change request's diff from the local repository.** The checked-out branch can be ahead of or behind the host, and the base may not be fetched; the host's diff is what reviewers see. The view says when the checked-out branch has commits beyond the head instead. + +**Recognizing a too-large diff from the failure message in the panel.** The message belongs to the provider and its host and changes with them; a failure code lets each provider report its own limits, and the panel branches on the code. + +**Creating the change request from the card.** The panel would need to push the branch and compose the title and description; a message lets the Agent do both with its tools and the user's instructions, and keeps one way to bind change requests. + +**Sending each line comment immediately to the Agent.** It starts a turn before the user can collect related comments or add a shared instruction; composer references preserve that choice. + +**Keeping review drafts after their tab closes.** Reopening the same PR would restore abandoned review state. A tab occurrence gives closing a clear discard meaning while preserving Session switching. + +**Automatically retrying a review write.** A lost response does not mean that GitHub rejected the request. Retaining the outgoing request and requiring reconciliation prevents a transport failure from silently duplicating comments. + +## Consequences + +The panel shows current status only while it is open; checks that finish while nothing is mounted produce no notification. Changes made outside the Session appear after Refresh or the next tool result. Every inspection spawns up to twelve short Git processes in the Session's execution world with one remote, and two more for each further remote it tries for a fork point. A worktree exists only for a Session that requested it before its first step, and a failed or cancelled attempt can leave its branch or checkout behind. A message that enters while the Agent runs a turn or other maintenance gets no hold, so its worktree is created within the first turn and a removed worktree is not checked. While a message waits, the Agent stays idle in maintenance: the composer offers no stop, and callers waiting for the Agent to become idle wait as well. Restoring loses changes that were never committed. A base branch that requires a merge queue cannot merge from the panel. With Git Worktrees also enabled, two independent worktree services exist; the model's tool never sees the panel's service. A local or change request diff over `maxDiffBytes`, or one the host refuses, shows no files. Expanding unchanged lines of a change request reads each file from the code host once. diff --git a/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md b/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md new file mode 100644 index 0000000000..432f2b10a8 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md @@ -0,0 +1,92 @@ +# Agent Note: 变更请求面板与 worktree Session + +Status: implemented + +[English](2026-10-09-forge-panel.md) | 中文 + +## Problem + +[Session 变更请求绑定](2026-10-09-session-change-request-bindings.zh.md)为每个 Session 提供了变更请求列表，但没有地方展示。让 agent 开变更请求的用户需要在不离开对话的情况下看到它们的检查、评审与能否合并，也希望新 Session 的修改和提交不影响当前检出。Git 必须在 Session 命令运行的地方执行，这可能是远程或受限的执行环境；检查不能改动仓库，而且 worktree 必须在模型第一次动作之前就存在。 + +## Decision + +[`dsh-experimental-client-ui-forge`](../../../../packages/experimental/client-ui-forge/README.zh.md) 是一个双端包。宿主端的 `forgePanel` Remote 把面板为一个 Session 展示的全部内容组装成一条流式状态；forge 注册表与绑定服务只保留各自的领域操作。客户端包括一个右侧边栏标签页、一个显示或隐藏它的 Session 标题栏按钮、一个新会话选项、一张位于输入框上方的创建卡片、一个 toast，以及[会话列表中的图标与悬浮卡片部分](2026-10-20-forge-session-list.zh.md)。所有界面都把已绑定的条目称为变更请求（forge 注册表的术语），不随代码托管平台的叫法变化。[forge 套件](../../../../packages/experimental/forge-bundle/README.zh.md)把面板、forge 注册表、GitHub 提供方、绑定服务与一个隔离的 worktree 服务作为插件页中默认禁用的一个条目发布。 + +Remote 通过 Session 的子进程提供方，按其[解析出的权限与查询限制](../bug-fix/2026-10-28-forge-git-session-permissions.zh.md)检查检出，因此它读到的与 Session 命令看到的相同。检查读取顶层目录、Git 目录与公共 Git 目录、分支或缩写的 HEAD 提交、上游与远端，以及分支相对于其分叉点的变更规模。它在 Session 被关注时、每个 `working-directory/change`、`tool/result` 与 `sandbox/mode` 事件之后以及刷新时运行，一次只运行一个，最多再追加一次。 + +状态轮询跟随面板订阅：只有该 Session 的某个界面挂载时才监听其绑定，注册表停止轮询无人监听的变更请求。每张卡片保留最近一次轮询得到的快照，因此短暂的失败不会让标题与编号消失。Session 只有一个打开的变更请求时，它的卡片默认展开；有多个时全部折叠；用户第一次展开或收起卡片后，以用户的选择为准。 + +展开的卡片可以把草稿标记为可评审，也可以合并主机现在就会合并的变更请求。forge seam 把两者作为提供方操作承载，失败时返回带类型的结果；每个快照都说明主机现在是否会为已登录用户合并该变更请求、仓库允许哪些合并方式，因此面板只提供能够成功的操作。合并带上卡片显示的 head 提交，有新提交到达后主机会拒绝。面板只操作绑定到该 Session 的变更请求。 + +新 Session 通过请求而不是立即创建来以 worktree 开始。勾选新会话那一行中的选项（一个 `conversation.hero.options` 条目）会追加一条带基准分支的 `plugin:client-ui-forge/worktree` 记录；更换基准或取消勾选会再追加一条；用户发送之前不会改动仓库。只有创建能够成功时才提供该选项：在 `workspace-write` 下，检出及其公共 Git 目录必须位于可写根之内，这排除了本身就是链接 worktree 的项目。worktree 必须在第一条消息的这一轮开始之前就存在，这样这一轮才会在其中运行，第一次请求也已经写明新目录。消息进入 Session 的收件箱时，面板的 `agent/inbox/inserted` 监听器在这次投递唤醒 Agent 之前启动 Agent 的维护任务；Agent 会暂存唤醒直到维护任务结束，面板在维护任务内创建并进入 worktree。创建的阶段以流的形式推送给输入框上方的卡片，卡片上的“取消”停止这次尝试。尝试被停止或失败后，消息继续在收件箱中等待，卡片保留失败信息，并提供用新分支名再试一次，或“不使用工作树”：撤回请求并让消息继续。一个 `agent/pre-step` 监听器仍会在请求未完成的 Session 的第一个步骤提议中创建 worktree，因为 Agent 正在运行一轮或其他维护任务时进入的消息不会被暂留；它把工作目录通知移入本步提议的消息，失败时这一轮结束。`forgeWorktree` 投影忽略第一个 `turn/start` 之后的请求以及第一个 `step/start` 之后的创建，因此运行中的 Session 永远不会移动。标签页顶部一行写出 Session 所在的分支，会话列表标出在所创建 worktree 中工作的 Session。 + +Session 所在的 worktree 可能在 Session 之外被删除。每次检查都会确认所创建 worktree 的目录是否还在；Agent 空闲时进入的每条消息都会启动一次暂留并再确认一次，目录缺失期间消息等待、不开始这一轮。这次确认必须发生在这一轮之前：组装一个步骤的上下文时，工作目录服务会把目录已不存在的 Session 移回其项目，而这发生在任何 pre-step 监听器运行之前。“恢复”在记录的目录重新检出分支；分支也已删除时，在其基准提交重新创建分支。“在项目目录继续”把 Session 移回源检出。两者都在暂留内运行，之后放行等待中的消息。 + +面板不在现有 worktree 之间移动 Session。移除变更请求会追加一条 `dismiss` 记录，它的 toast 通过 `track` 提供“撤销”。 + +面板还通过变更视图展示 Session 工作背后的变更；变更视图是本包的一个资源标签页类型。Remote 在宿主上把每个 diff 解析成文件与 hunk，因此浏览器无需补丁解析器即可绘制，每次读取都受 `maxDiffBytes` 与 `maxUntrackedFiles` 约束。本地变更来自使用 Session 权限与执行环境的 `git diff`，范围由用户选择：默认是分支相对于分叉点的变更，也可以是未提交、未暂存或已暂存的变更；未跟踪文件经 Session 的文件系统读取，显示为新文件。变更请求的变更来自代码托管平台，取自绑定最新状态中的 head，经 forge seam 新增的两个提供方读取操作 `diff` 与 `fileText` 获得。Host 为每个变更请求保留最近读到的补丁，按 head 提交与目标分支区分，总量受 `maxCachedDiffBytes` 约束，因此在同一 head 下重新打开、刷新与导航都不会再次下载；托管平台或提供方因结果超过其大小上限而拒绝时报告 forge 失败 `too-large`，视图随之提供变更请求的网页而不是重试。hunk 之间未变更的行从文件的新版本展开，即工作树、暂存区或 head 提交，并且只在该文本仍与 hunk 吻合时展开。每次检查还会为变更卡片统计分支的变更规模；没有打开中的变更请求以当前检出分支为源分支时才显示该卡片。卡片上的“创建变更请求”向 Session 发送一条用户消息，由 Agent 用自己的工具创建变更请求，绑定像其他变更请求一样来自 `gh pr create`。 + +评审评论在用户选择代码时固定文件、侧、行范围、完整 hunk 与所评审的 head。Agent 引用进入既有输入框引用机制，由用户决定批量发送，发送后的消息记录模型实际收到的内容。GitHub 写入属于 forge 提供方的可选操作：预检核对当前 head，写入明确指向该提交；结果不明时阻止再次写入，直到用户核对。评审草稿与行内记录归浏览器页签实例所有，不进入 Session 日志，也不创建 GitHub 待提交评审。切换 Session 保留该实例；关闭时丢弃本地状态并拒绝迟到的写入结果。已发布的 GitHub 评论仍保留在外部平台。 + +## Deferred + +在左侧导航“插件”“自动化任务”旁边新增代码审查页、列出用户在所选提供方上的 pull request 或 merge request，这项工作推迟。它的接入不需要改动本包面向 Session 的界面： + +- **提供方能力**——`ForgeProvider` 增加一个可选方法，例如 `listForViewer(host, filter, signal)`，返回变更请求引用；GitHub 用 `gh search prs --author @me` 或 GraphQL `viewer` 实现，注册表汇总已启用的提供方。 +- **Remote**——一条类似 `follow` 的流，以提供方与筛选条件而不是 Session 为键，通过同一个 `ctx.forge.watch` 轮询。 +- **客户端**——在本包中以 `sidebar.panellist` 条目加一个 `main` 页面实现（与 `ui-schedule` 相同），渲染接收变更请求、其快照与可选操作的 `ChangeRequestCard`。 +- **设置**——在套件的配置页中选择提供方与主机。 + +变更视图目前还没有单个提交与上一轮的范围；两者将是经 `localDiff` 读取的更多 `ForgeLocalScope` 种类。 + +## Alternatives considered + +**按平台使用不同名称。** 在 GitHub 上称 pull request、在 GitLab 上称 merge request，需要每个提供方声明自己的名称，所有文案也要随之变化；而 GitHub 是唯一的提供方，统一的术语让文案保持不变。 + +**通过 `gh pr merge` 合并。** 必需检查尚未完成时它会启用自动合并，基准分支要求合并队列时它会加入队列，因此一次点击可能安排了一次以后的合并而不是立即合并。REST 合并接口要么立即合并，要么拒绝。 + +**合并后删除 head 分支。** Session 的 worktree 可能就在这个分支上。 + +**为 Git 检查单独建一个宿主服务包。** 目前没有第二个使用方需要检出信息；出现模型工具时，可以再把它们移入共享服务。 + +**以宿主进程运行 Git。** 远程与受限的执行环境会显示宿主的文件而不是 Session 的文件，宿主还会读取 Session 无法读取的目录。 + +**勾选时立即创建 worktree。** 每次切换勾选或更换基准都会创建并丢弃一个检出，而且用户决定发送之前 Session 就已经移动。 + +**在创建 Session 的请求中携带该选项。** 这个请求由 Session 控制器拥有，字段是封闭的；插件记录让选项留在本包之内，并且在空白 Session 重新加载后仍然保留。 + +**在面板中切换现有 worktree。** 切换后的 Session 仍保留其项目的沙箱根，因此项目之外的 worktree 依然只读；对话中途移动还会让模型对文件的认识前后割裂。让 Session 从一开始就在自己的 worktree 中运行可以同时避免这两点。 + +**把选项放在输入框工具栏。** 发出第一条消息后工具栏依然存在，而那时该选项已不再适用；新会话那一行在 Session 开始后就会消失。那一行原先只提供单值 slot，因此 `ui-conversation` 增加了列表型 slot `conversation.hero.options`。 + +**在第一轮之内创建 worktree。** 第一个步骤提议运行时这一轮已经开始：上下文按旧目录组装，失败只能结束这一轮并丢弃已认领的消息，而工作目录服务已经把 Session 移出被删除的 worktree。它只作为没有被暂留的消息的兜底。 + +**在 Agent 接纳阶段暂留消息。** `agent-controller/admission` 阶段会在消息进入收件箱之前暂留它，因此 worktree 建好之前消息一直留在输入框里，失败时退回以便编辑。它需要在每个发送方的投递之前加一个控制器服务，单个面板不足以支撑这项核心改动；在收件箱插入时暂留只用现有的收件箱事件与维护任务，并覆盖所有发送方。 + +**把等待中的消息退回输入框。** 宿主接收消息之后，输入框没有办法把它收回，除非为一个插件在会话包里新增公共 API；消息改为在卡片的操作下继续等待。 + +**在 Web 输入框里设发送闸门。** 浏览器在宿主看到消息之前就拦住它，因此每次检查都要一次 Remote 调用，被拒绝消息的阶段只存在于浏览器中，其他发送方也会绕过它。在收件箱插入时暂留，让消息停在它进入 Agent 的位置，并把失败保留在面板状态中。 + +**把创建卡片放进对话记录。** 对话记录的节点不接受插件定义的类型；输入框上方的停靠区是最近的列表型 slot，而且它在新会话页也会渲染。 + +**手动粘贴 URL 跟踪。** 它与 Session 自己的命令记录下的绑定重复。绑定来自 `gh pr create`、操作单个变更请求的 `gh pr` 命令、推送以及检出所跟踪的分支，`track` 保留给“撤销”使用。 + +**在浏览器中解析补丁。** Remote 将传输不受限的补丁文本，浏览器也需要补丁解析器；宿主约束读取并只解析一次。 + +**复用代码审查标签页的文件对比。** 它属于另一个插件，本包在运行时不能导入；把它移入共享基础组件又会为一个使用方改动共享包。变更视图改用共享的高亮器、菜单、提示与 diff 颜色 token 构建。 + +**从本地仓库读取变更请求的 diff。** 当前检出分支可能领先或落后于托管平台，基准分支也可能没有拉取；评审者看到的是托管平台的 diff。视图改为在当前检出分支有超出 head 的提交时给出说明。 + +**在面板里根据失败信息识别 diff 过大。** 失败信息属于提供方及其托管平台，会随它们变化；失败代码让每个提供方报告自己的上限，面板只按代码分支。 + +**直接在卡片上创建变更请求。** 面板需要推送分支并撰写标题与描述；发送消息让 Agent 用自己的工具和用户的指示完成这两件事，绑定变更请求的方式也只保留一种。 + +**把每条行内评论立即发送给 Agent。** 用户还没来得及收集相关评论或补充共同指令，就会开始一轮；输入框引用保留用户的选择。 + +**关闭页签后仍保留评审草稿。** 重新打开同一个 PR 会恢复已放弃的评审状态。页签实例让关闭明确表示丢弃，同时保留切换 Session 的状态。 + +**自动重试评审写入。** 丢失响应不代表 GitHub 拒绝了请求。保留发出的请求并要求核对，可以避免传输失败悄悄产生重复评论。 + +## Consequences + +面板只在打开时显示当前状态；没有任何界面挂载时检查结束不会有通知。Session 之外的改动要等到刷新或下一个工具结果才会出现。只有一个远端时，每次检查最多在 Session 的执行环境中启动十二个短暂的 Git 进程；为寻找分叉点每多尝试一个远端，就多启动两个。只有在第一步之前提出请求的 Session 才会有 worktree，失败或被取消的尝试可能留下它的分支或检出。Agent 正在运行一轮或其他维护任务时进入的消息不会被暂留，因此它的 worktree 在第一轮之内创建，已删除的 worktree 也不会被检查。消息等待期间，Agent 以空闲状态处于维护任务中：输入框不提供停止，等待 Agent 空闲的调用方也会一并等待。恢复会丢失从未提交的修改。要求合并队列的基准分支无法从面板合并。同时启用 Git Worktrees 时会存在两个互不影响的 worktree 服务；模型的工具看不到面板的服务。本地或变更请求的 diff 超过 `maxDiffBytes`，或被托管平台拒绝时，不显示任何文件。展开变更请求中未变更的行时，每个文件只从托管平台读取一次。 diff --git a/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.i18n.yaml b/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.i18n.yaml new file mode 100644 index 0000000000..5f8577a2b1 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-09-session-change-request-bindings.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 .agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.md +/agent-note-session-change-request-bindings: + en: 89ec58adddf53fec + zh: 919e8557d9923fdb +/agent-note-session-change-request-bindings/problem: + en: e736740546fb8219 + zh: 46a16a7a633716ec +/agent-note-session-change-request-bindings/decision: + en: 2bbd058f4edc8bb5 + zh: 5cc12bb0aa0864e2 +/agent-note-session-change-request-bindings/alternatives-considered: + en: 15fdaef4e432fc72 + zh: 8d36c859bd89f403 +/agent-note-session-change-request-bindings/consequences: + en: a2960e50ec52c9b6 + zh: fd23f4fe1137787d diff --git a/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.md b/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.md new file mode 100644 index 0000000000..3c767fde01 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.md @@ -0,0 +1,31 @@ +# Agent Note: Session change request bindings + +Status: implemented + +English | [中文](2026-10-09-session-change-request-bindings.zh.md) + +## Problem + +A Session that opens or updates pull requests leaves them only in its shell output. Neither the user nor later consumers have a list of the change requests the Session works on or a shared view of their status. Code hosts differ in URLs, command-line tools, and status models, and any association must survive fork and resume without changing what the model sees. + +## Decision + +The experimental forge capability seam has three roles. [`dsh-experimental-forge`](../../../../packages/experimental/forge/README.md) defines provider-neutral repository and change request references, a provider registry, and shared polling: watchers of one change request share one loop, each forge has one batched fetch in flight, and the cadence follows check, mergeability, and lifecycle state. [`dsh-experimental-forge-github`](../../../../packages/experimental/forge-github/README.md) is the first provider; it reads GitHub through the GitHub CLI on the host, so credentials stay in that tool's own store and never enter Session execution worlds. [`dsh-experimental-forge-session`](../../../../packages/experimental/forge-session/README.md) binds change requests to Sessions. + +Bindings derive from the Session log instead of a separate store. A Session projection reads `bash` and `pwsh` calls: `gh pr create` results bind the URLs they print, `gh pr view`, `gh pr edit`, and `gh pr checkout` calls bind the change request they act on, and `git push` results record the branches they updated. Those three commands act on one change request, so only the URL given as their first argument and the URL their output prints for that change request count; links in a description name other change requests. Caller actions and discovery results are `plugin:forge-session/binding` records. Because every input is a log event, fork and resume carry bindings without new persistence, and the projection rebuilds them from any checkpoint. The printed URL or ref line is the evidence, not the exit status: an existing pull request reported by a failing `gh pr create` still binds, and a partially rejected push still records the branches it updated. + +After each push result, and when a caller such as the forge panel reports the branch a Session's checkout tracks, the service looks up open change requests for that branch through the provider and records the unbound ones. A dismissed binding stays hidden from discovery and returns only through `track`. Polled status is not logged; it is process-local state that exists while a watcher displays the Session. The projection's client view therefore carries bindings without status. + +## Alternatives considered + +**A host-side binding database.** A separate store would need its own fork, resume, and deletion rules; plugin records and projections already provide them. + +**A model tool that registers each change request.** The association would depend on the model calling an extra tool, and every request would carry its schema. Parsing the commands the model already runs costs no tokens. + +**Logging polled status in the Session.** Status changes independently of the conversation. Logging it would grow the log with every poll and expose stale snapshots to later readers. + +**Running `gh` through the Session's subprocess provider.** Remote and sandboxed execution worlds would need GitHub credentials, and status would depend on the world a Session uses. The host CLI keeps one credential owner. + +## Consequences + +Bindings appear without model cooperation for the common `gh pr create`, `gh pr view`, `gh pr edit`, `gh pr checkout`, and `git push` flows and add no model tokens. Commands run through scripts, aliases, or other command-line tools are not recognized, and a change request opened elsewhere for a branch appears only after another push, another report of that branch, or a `track`. Another provider adds its own access and URL forms behind the same provider contract without changing the binding rules or the polling. The host needs `gh` signed in for each GitHub host. diff --git a/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.zh.md b/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.zh.md new file mode 100644 index 0000000000..caa153fe79 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-09-session-change-request-bindings.zh.md @@ -0,0 +1,31 @@ +# Agent Note: Session 变更请求绑定 + +Status: implemented + +[English](2026-10-09-session-change-request-bindings.md) | 中文 + +## Problem + +打开或更新 pull request 的 Session 只在 shell 输出里留下它们。用户和后续消费方都无法得到该 Session 正在处理的变更请求（change request）列表，也无法共享查看其状态。各代码托管平台的 URL、命令行工具与状态模型各不相同，而这种关联必须在 fork 与恢复后保留，且不能改变模型看到的内容。 + +## Decision + +实验性的 forge 能力 seam 由三个角色组成。[`dsh-experimental-forge`](../../../../packages/experimental/forge/README.zh.md) 定义提供方无关的仓库与变更请求引用、提供方注册表与共享轮询：同一变更请求的监听方共享一个循环，每个 forge 同时只有一次批量读取，轮询节奏随检查、可合并性与生命周期状态变化。[`dsh-experimental-forge-github`](../../../../packages/experimental/forge-github/README.zh.md) 是第一个提供方；它通过宿主上的 GitHub CLI 读取 GitHub，因此凭据保留在该工具自己的存储中，从不进入 Session 的执行环境。[`dsh-experimental-forge-session`](../../../../packages/experimental/forge-session/README.zh.md) 把变更请求绑定到 Session。 + +绑定从 Session 日志派生，而不是存放在单独的存储中。一个 Session 投影读取 `bash` 与 `pwsh` 调用：`gh pr create` 的结果绑定其输出的 URL，`gh pr view`、`gh pr edit` 与 `gh pr checkout` 调用绑定它们所操作的变更请求，`git push` 的结果记录其更新的分支。这三个命令只操作一个变更请求，因此只计入作为第一个参数给出的 URL 和输出为该变更请求打印的 URL；描述正文里的链接指向的是其他变更请求。调用方操作与发现结果是 `plugin:forge-session/binding` 插件记录。由于所有输入都是日志事件，fork 与恢复无需新的持久化即可带上绑定，投影也能从任意检查点重建它们。证据是输出中的 URL 或 ref 行，而不是退出状态：失败的 `gh pr create` 报告的已有 pull request 仍会绑定，部分被拒绝的推送仍会记录它已更新的分支。 + +每次推送结果之后，以及 forge 面板等调用方报告 Session 检出所跟踪的分支时，服务通过提供方为该分支查找打开状态的变更请求，并记录尚未绑定的那些。被隐藏的绑定不会被发现逻辑恢复，只能通过 `track` 恢复。轮询到的状态不写入日志；它是进程内状态，仅在有监听方展示该 Session 时存在。因此投影的客户端视图只带绑定，不带状态。 + +## Alternatives considered + +**宿主侧绑定数据库。** 单独的存储需要自己的 fork、恢复与删除规则；插件记录与投影已经提供了这些规则。 + +**由模型工具登记每个变更请求。** 关联将取决于模型是否调用额外的工具，而且每个请求都要携带该工具的 schema。解析模型本来就会运行的命令不消耗 token。 + +**把轮询状态写入 Session 日志。** 状态的变化独立于对话。写入日志会让日志随每次轮询增长，并把过期快照暴露给后续读取方。 + +**通过 Session 的子进程提供方运行 `gh`。** 远端与沙箱执行环境将需要 GitHub 凭据，状态也会取决于 Session 使用的执行环境。宿主 CLI 让凭据只有一个所有者。 + +## Consequences + +在常见的 `gh pr create`、`gh pr view`、`gh pr edit`、`gh pr checkout` 与 `git push` 流程中，绑定无需模型配合即可出现，且不增加模型 token。通过脚本、别名或其他命令行工具运行的命令无法识别；在别处为某个分支打开的变更请求，要等到下一次推送、再次报告该分支或 `track` 之后才会出现。新的提供方在同一提供方契约之后加入自己的访问方式与 URL 形式，无需改变绑定规则或轮询。宿主需要为每个 GitHub 主机登录 `gh`。 diff --git a/.agents/notes/implemented/feature/2026-10-20-forge-session-list.i18n.yaml b/.agents/notes/implemented/feature/2026-10-20-forge-session-list.i18n.yaml new file mode 100644 index 0000000000..2f6f65eb10 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-20-forge-session-list.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-20-forge-session-list.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 .agents/notes/implemented/feature/2026-10-20-forge-session-list.md +/agent-note-forge-state-in-the-session-list: + en: b5876f7873857921 + zh: 56fac53370de206d +/agent-note-forge-state-in-the-session-list/problem: + en: 07ba0c3bf73a2446 + zh: 2413783a6697133e +/agent-note-forge-state-in-the-session-list/decision: + en: e1d03cf4e1afd5aa + zh: b2386cb7c17c58dd +/agent-note-forge-state-in-the-session-list/alternatives-considered: + en: 3b08440ee2bf7809 + zh: a90e3fcb89cf3f74 +/agent-note-forge-state-in-the-session-list/consequences: + en: 25a17eac43beb705 + zh: c138f693ff07c91d diff --git a/.agents/notes/implemented/feature/2026-10-20-forge-session-list.md b/.agents/notes/implemented/feature/2026-10-20-forge-session-list.md new file mode 100644 index 0000000000..cec6faa265 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-20-forge-session-list.md @@ -0,0 +1,39 @@ +# Agent Note: Forge state in the Session list + +Status: implemented + +English | [中文](2026-10-20-forge-session-list.zh.md) + +## Problem + +The [forge panel](2026-10-09-forge-panel.md) named a Session's branch in a chip beside the Session title. The header's action row does not shrink, so a long branch overlapped other header entries such as the background task label. Finding which Sessions work in their own worktrees, and which of their change requests need attention, also meant opening each Session's tab. The Session list offers seats for row icons and a hover card section, `sidebar.session.row.trailing` and `sidebar.session.row.hover`, whose occupants must not load or bind Sessions. A row needs two kinds of fact: what the Session log records, which is the worktree the panel created and entered and the change requests the Session binds, and what only polling knows, which is each change request's state and checks. + +## Decision + +The chip beside the Session title is gone, and the tab's first row names the branch. A Session row shows, after its time, a branch glyph while the Session works in the worktree the panel created for it, and the glyph of its most urgent change request: one needing attention first, then open, draft, not yet polled, merged, and closed. An open change request's glyph keeps the row's subdued color with a dot for its checks; merged and closed ones keep their state colors. The row's hover card section names the worktree branch and what it started from, then up to three change requests with their state and checks, and how many more there are. + +Log facts reach the list as projection client views, which the Session summary carries. The `forgeWorktree` projection also records the Session's directory from its header and each `working-directory/change`, and its view is the created worktree while that directory is the worktree or lies below it, else null. The `forgeChangeRequests` view lists the bindings without status, as the [binding decision](2026-10-09-session-change-request-bindings.md) intended. The projection cache keeps both for Sessions that are not loaded. + +Polled states reach the list through the `forgePanel.changeRequestStates` stream. One Host run serves every stream and stops with the last one. It lists Sessions through `sessionQuery` without loading them, takes the visible bindings of loaded Sessions from `ctx.forgeSession` and those of other Sessions from their cached summary, follows binding changes of loaded Sessions, and subscribes to each bound change request through the shared `ctx.forge.watch`; closed requests use the idle polling cadence, and merged requests remain subscribed for explicit refresh. Every changed state is stored in the `forge_panel_change_requests` storage domain under the SHA-256 digest of its URL, so a restart shows the last known states before the next poll, and unbound stored states are dropped only when every listed Session has known bindings. A stream sends a `baseline` of the states its caller may read, then `changed` frames, filtered through Remote access. + +The browser keeps one source of states for every row and hover section: the first subscriber opens the stream, the last one closes it, and a transport reset reopens it. + +## Alternatives considered + +**Leaving change requests to the tab.** The forge panel first rejected a Session-row hover section because, for one Session, it repeated the tab. The list compares every Session at once, which no tab does, and the hover section adds only the facts a row's glyphs summarize. + +**Keeping the branch beside the Session title.** Truncating the chip would hide the branch name, and the header shows only the open Session; the list shows every Session, and the tab names the branch in full. + +**Polled states in a projection.** Projections fold the Session log, and polled states are not logged. A projection would either log every poll, adding events that no model request needs, or depend on process-local state that a replay cannot reconstruct. + +**Following every listed Session's panel.** A panel inspects its checkout with Git in the Session's execution world and probes sign-in; the list needs only bindings and change request states. + +**Loading listed Sessions to read their bindings.** Listing would replay every Session log; the cached summary answers without loading. + +**Keeping the states only in memory.** Every row would show unknown states after a restart until each change request is polled again. The stored states are derived data, so a record that fails its schema is set aside instead of failing the run. + +**A branch line for a Session that works in its project directory.** Reading that branch needs Git in the Session's execution world, which the list must not reach without loading the Session. + +## Consequences + +The list shows every Session's worktree and change request states without loading a Session, a restart shows the last known states at once, and the header no longer overlaps. While a row is shown, every open change request that a listed Session binds is polled, so many Sessions with open change requests mean more requests to the code host; closed requests keep polling at the idle cadence, and merged ones stop automatic polling. A Session without a cached summary shows its worktree and change requests in the list only after it is opened, and one last used before this change shows its worktree only then, because the `forgeWorktree` state changed and older cached rows are discarded. Checks that finish while no row is shown produce no notification. diff --git a/.agents/notes/implemented/feature/2026-10-20-forge-session-list.zh.md b/.agents/notes/implemented/feature/2026-10-20-forge-session-list.zh.md new file mode 100644 index 0000000000..73bfee90a7 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-20-forge-session-list.zh.md @@ -0,0 +1,39 @@ +# Agent Note: 会话列表中的 forge 状态 + +Status: implemented + +[English](2026-10-20-forge-session-list.md) | 中文 + +## Problem + +[forge 面板](2026-10-09-forge-panel.zh.md)原先在 Session 标题旁的标签中写出 Session 的分支。标题栏的操作行不会收缩，因此较长的分支名会与后台任务标签等其他标题栏条目重叠。想知道哪些 Session 在自己的 worktree 中工作、它们的哪些变更请求需要处理，也必须逐个打开 Session 的标签页。会话列表为行图标与悬浮卡片提供了位置，即 `sidebar.session.row.trailing` 与 `sidebar.session.row.hover`，其中的条目不得加载或绑定 Session。一行需要两类事实：Session 日志记录的事实，即面板创建并进入的 worktree 以及 Session 绑定的变更请求；以及只有轮询才知道的事实，即每个变更请求的状态与检查。 + +## Decision + +Session 标题旁的标签已移除，由标签页顶部一行写出分支。Session 在面板为它创建的 worktree 中工作时，会话行在时间之后显示分支图标；另有一个图标显示它最需要关注的变更请求，依次为需要处理、打开、草稿、尚未轮询、已合并、已关闭。打开中的变更请求图标保持会话行的浅色，并用圆点标出检查；已合并与已关闭的保留各自的状态颜色。会话行悬浮卡片中的部分写出 worktree 分支及其起点，再列出最多三个变更请求的状态与检查，并说明还有多少个。 + +日志事实经投影的客户端视图进入列表，由 Session 摘要携带。`forgeWorktree` 投影还从 Session 头部与每个 `working-directory/change` 记录 Session 的目录；该目录就是所创建的 worktree 或位于其下时，视图为该 worktree，否则为 null。`forgeChangeRequests` 视图列出绑定但不含状态，与[绑定决策](2026-10-09-session-change-request-bindings.zh.md)的设想一致。投影缓存为未加载的 Session 保留这两项。 + +轮询到的状态经 `forgePanel.changeRequestStates` 流进入列表。宿主用一次运行服务所有流，最后一条流结束时运行停止。它经 `sessionQuery` 列出 Session 而不加载它们，已加载 Session 的可见绑定取自 `ctx.forgeSession`，其他 Session 的取自缓存的摘要；它跟随已加载 Session 的绑定变化，并经共享的 `ctx.forge.watch` 订阅每个已绑定的变更请求；已关闭的按空闲间隔轮询，已合并的保留订阅以接收显式刷新结果。每个变化了的状态以其 URL 的 SHA-256 摘要为键存入 `forge_panel_change_requests` 存储域，因此重启后在下次轮询之前就能显示最近已知的状态；仅在所有已列出 Session 的绑定均已知时删除无人绑定的已存状态。每条流先发送调用方可读状态的 `baseline`，之后发送 `changed` 帧，均经 Remote 访问控制过滤。 + +浏览器为所有会话行与悬浮卡片部分只保留一个状态来源：第一个订阅方打开流，最后一个关闭它，传输重置后重新打开。 + +## Alternatives considered + +**把变更请求只留给标签页。** forge 面板最初否决了 Session 行悬浮分区，因为对单个 Session 而言它与标签页重复。列表能同时比较所有 Session，这是任何标签页都做不到的；悬浮部分也只补充会话行图标所概括的事实。 + +**保留 Session 标题旁的分支。** 截断标签会遮住分支名，而且标题栏只显示当前打开的 Session；列表显示每个 Session，标签页则完整写出分支。 + +**把轮询状态放进投影。** 投影折叠的是 Session 日志，而轮询到的状态不写入日志。放进投影要么为每次轮询记录事件，而这些事件没有任何模型请求需要；要么让投影依赖重放无法重建的进程内状态。 + +**为每个已列出的 Session 跟随其面板。** 面板会在 Session 的执行环境中用 Git 检查检出并检查登录状态；列表只需要绑定与变更请求状态。 + +**加载已列出的 Session 来读取绑定。** 列表将重放每个 Session 的日志；缓存的摘要无需加载就能回答。 + +**只把状态保存在内存中。** 重启后每一行都会显示未知状态，直到每个变更请求再次被轮询。已存状态是派生数据，因此不符合 schema 的记录会被放到一边，而不是让运行失败。 + +**为在项目目录中工作的 Session 显示分支一行。** 读取该分支需要在 Session 的执行环境中运行 Git，而列表不加载 Session 就无法到达那里。 + +## Consequences + +列表无需加载 Session 就能显示每个 Session 的 worktree 与变更请求状态，重启后立即显示最近已知的状态，标题栏也不再重叠。有会话行显示期间，已列出 Session 绑定的每个打开中的变更请求都会被轮询，因此有大量带打开变更请求的 Session 时，对代码托管平台的请求会增多；已关闭的继续按空闲间隔轮询，已合并的停止自动轮询。没有缓存摘要的 Session 要打开之后才会在列表中显示其 worktree 与变更请求；此变更之前最后使用的 Session 也要到那时才显示其 worktree，因为 `forgeWorktree` 的状态已变化，旧的缓存行会被丢弃。没有会话行显示期间结束的检查不会有通知。 diff --git a/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.i18n.yaml b/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.i18n.yaml new file mode 100644 index 0000000000..dad8343dcf --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.i18n.yaml @@ -0,0 +1,37 @@ +# Bilingual-pair consistency record for 2026-10-21-floating-window-edge-recovery.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 .agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.md +/agent-note-spring-based-edge-recovery-for-floating-dock-panels: + en: 73438e22c1bef8d3 + zh: 5f817eb06259f8ef +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/problem: + en: c3b007f5cce80d8b + zh: c08b07f7e71eaa5f +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/decision: + en: f88f165ca80a57b8 + zh: 98559f2239b03445 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/decision/legal-region-and-displayed-position: + en: 6dea90dc406eacf5 + zh: 6ecae0fdad78c855 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/decision/drag-with-resistance: + en: 5214241925b52bc3 + zh: bbd66dc72c03f960 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/decision/release-and-spring: + en: ba2b5a3b4923d585 + zh: 99544462a464ac50 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/decision/reduced-motion: + en: 7e29bf1c45b5386d + zh: c913a2ce6d1722d1 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/decision/change-scope: + en: 6459103379aefe41 + zh: 501dee08a977b6a0 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/testing: + en: da3b2b6781aa99f3 + zh: 37e49fa22f72fb84 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/alternatives-considered: + en: 3d901f0f5e270e29 + zh: c1fb89b567ea3c70 +/agent-note-spring-based-edge-recovery-for-floating-dock-panels/consequences: + en: 360bd69c918f23fe + zh: 48642fd59ad3279b diff --git a/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.md b/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.md new file mode 100644 index 0000000000..a4e9ca4e25 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.md @@ -0,0 +1,106 @@ +# Agent Note: Spring-based edge recovery for floating dock panels + +Status: implemented + +English | [中文](2026-10-21-floating-window-edge-recovery.zh.md) + +## Problem + +The dock kit's floating panels are the client's floating windows. `FloatLayer` and the retained `DockLayout` renderer draw them in viewport coordinates through one shared gesture hook, `useFloatGestures`, and the right Sidebar embeds them, so the same panels run in the Web client and inside the Desktop window. Their drag followed the pointer one to one with only a top floor (`--dsh-dockkit-float-top`, which keeps the header below the Windows caption). A panel could therefore be dragged past the left, right or bottom edge until its header was out of reach; a viewport that shrank left a panel outside it; and the creation cascade could place a new panel outside a small viewport. The required behavior is that a panel pushed past an edge visibly resists, and on release is pulled back inside with spring physics instead of being stopped by a wall or left outside. + +The reference implementation examined, Claude Desktop, has no portable edge-recovery rule: its Electron fallback corrects an off-screen window once, without animation, on the right and bottom edges only. The behavior had to be designed, not ported. + +The change keeps these obligations: a panel header is always reachable; one gesture still records at most one history entry; reduced motion is honored; the persisted Sidebar layout format and every embedder stay unchanged; and the motion is deterministic enough to test without a real browser clock. + +## Decision + +The behavior lives entirely in `packages/client/ui-dockkit`, inside `useFloatGestures` and the pure engine helpers it calls. Both float renderers take their rectangles from that hook through `rectOf`, so Web and Desktop share the behavior, and no embedder, shell or persisted format changed. The rule extends the floating panels of [right Sidebar docking](2026-09-04-right-sidebar-docking-infrastructure.md) and the fixed-position floating frames of the [retained tab layout](../architecture/2026-09-20-sidebar-retained-tab-layout.md); it supersedes neither note. + +### Legal region and displayed position + +The legal region of a panel is the viewport (`window.innerWidth` by `window.innerHeight`) with the existing top floor: the Windows caption height plus 20 px when `data-windows-titlebar` is set (20 px in native fullscreen), otherwise 0. `floatBounds` reads only these values and the root's attributes, so starting a gesture forces no layout. `legalFloatRect` projects a rectangle into the region per axis; when a panel is wider or taller than the region it is drawn at the region's size on that axis, so its header controls and its resize corner stay on screen; the stored size is unchanged. + +A panel draws at its stored rectangle projected into the viewport. The stored rectangle is never rewritten for the viewport: a shrinking window pushes the panel in without recording an operation, and a growing window returns it toward its stored position. The hook re-reads the bounds at every press and on every window `resize` event, and a gesture in progress uses the new bounds. Persisted layouts that hold off-screen rectangles display inside the viewport without migration. + +At rest a panel publishes its rectangle to the `.float` rule as CSS variables through `floatStyle`, and the rule clamps its position and size into the viewport (`100vw` by `100dvh`, which follows `window.innerHeight` as the hook does) and below the caption floor once more; an oversized panel takes the viewport's size there as it does in `legalFloatRect`. A bounds reading the hook has not refreshed, such as one taken before a fullscreen change settles, therefore still leaves the panel inside. A gesture or a return writes its position and size inline, outside the clamp. + +### Drag with resistance + +A move computes the desired rectangle from the gesture's start rectangle and the pointer travel, then `resistedRect` splits it per axis into the legal projection and the overflow `o` beyond it and draws it at `legal + sign(o) * K * |o| / (K + |o|)` with `K = FLOAT_RESISTANCE = 120` px. The mapping applies on all four edges, including above the top floor, is continuous, has slope 1 at the edge, and approaches `K`: + +| pointer overflow (px) | panel displacement past the edge (px) | share of the overflow | +|---|---|---| +| 10 | 9.2 | 92.3% | +| 40 | 30.0 | 75.0% | +| 120 | 60.0 | 50.0% | +| 400 | 92.3 | 23.1% | + +A resize clamps the bottom-right corner to the region through `boundedResize` and keeps `FLOAT_MIN_SIZE`; resizing has no resistance, because a corner that lags the pointer reads as a broken handle. + +### Release and spring + +A release records the legal rectangle: `moveFloat` or `resizeFloat` when it differs from the legal rectangle at the press, otherwise only the raise a click records. A click on a panel drawn projected therefore keeps its stored rectangle. A move or resize therefore records only legal rectangles, and undo restores the pre-gesture position in one step. Panel creation (the drop rectangle of `floatTab` and the cascade) can still store a rectangle outside the viewport; the projection draws it inside. When the panel was drawn outside the legal region, the hook keeps a preview and springs it from where it was drawn to the recorded rectangle, then clears the preview. A release inside the region animates nothing. + +The spring in `engine/spring.ts` is underdamped, because its bounce goes inward and is always legal: response 0.32 s and damping ratio 0.72. An overflowing axis starts with the velocity of the drawn panel over the last 100 ms of the drag, so the speed is continuous across the release; it is capped at `SPRING_MAX_VELOCITY` (1500 px/s), and `launchVelocity` caps its outward part at `omega0 * (K - d)` for a drawn overflow `d`. A fling past the edge travels further before it turns back, and because the spring carries an offset `d` with speed `v` at most `d + 0.46 * v / omega0` from its target, the whole return stays within `K` of the edge. An axis that did not overflow keeps still. Per axis the update is: + +``` +a = -omega0^2 * (x - target) - 2 * zeta * omega0 * v +v = v + a * h +x = x + v * h +``` + +`stepSpring` integrates in equal substeps of at most `h = 1/480 s`, so the motion does not depend on the frame rate. One `requestAnimationFrame` loop in the hook clamps a frame to 64 ms, ends at the target when a frame gap exceeds 250 ms or 900 ms have passed, and otherwise stops when each axis is within 1 px of the target and slower than 60 px/s. From rest, a 200 px overflow settles in 367 ms with an inward overshoot within one percentage point of the analytic bound `exp(-pi * zeta / sqrt(1 - zeta^2)) = 3.8%`. The integrator is pure and takes `dt`, so the engine keeps its rule of reading no clock. + +A press on the grip or the corner during a return cancels it and picks the panel up where it is drawn. A move does so through `unresistedRect`: it inverts the resistance, so zero pointer travel draws the same rectangle. A resize keeps the drawn origin and caps only the corner by the viewport; its release records the legal rectangle and springs the origin inside, as does a resize whose viewport shrank past its origin. Either way a release in place resumes the return without recording a second operation. One hook runs at most one return. A window resize ends a running return at its recorded rectangle, a press on another panel ends it at its target, a change of the panel's record that does not project to the target (an undo, a dock, a close) ends it at the new record on the next frame, and unmounting cancels the pending frame. + +### Reduced motion + +When `matchMedia('(prefers-reduced-motion: reduce)')` matches, a move clamps to the legal region with no resistance, and release records the legal rectangle with no animation. Environments without `matchMedia` report no preference. The rule only removes motion; it never removes the legality correction. + +### Change scope + +The change touches one package, `@deepseek-ai/dsh-client-ui-dockkit`, and leaves its exports and `DockIntents` unchanged; the `TabRenderer` contract now states when the kit reuses a body. + +| File | Change | +|---|---| +| `packages/client/ui-dockkit/src/engine/geometry.ts` | `FloatBounds`, `FLOAT_RESISTANCE`, `legalFloatRect`, `resistedRect`, `unresistedRect`, `boundedResize` | +| `packages/client/ui-dockkit/src/engine/spring.ts` | the pure spring integrator, its rest predicate `springSettled`, `launchVelocity` and its timing limits | +| `packages/client/ui-dockkit/src/components/FloatLayer.tsx` | `useFloatGestures`: viewport projection, resistance, release spring, drawn-velocity sampling, reduced motion, frame loop and cancellation; `rectOf` and `floatStyle` for both renderers | +| `packages/client/ui-dockkit/src/components/TabLayout.tsx` | draws the hook's displayed rectangle through `floatStyle` | +| `packages/client/ui-dockkit/src/components/TabBody.tsx` | the memoized body every layout (`FloatLayer`, `TabLayout`, `TabPanel`) draws | +| `packages/client/ui-dockkit/src/contract/adapter.ts` | when `TabRenderer` is called again | +| `packages/client/ui-dockkit/src/components/dockkit.module.css` | the resting clamp of position and size on `.float` | +| `packages/client/ui-dockkit/README.md` pair | the edge rule beside the float renderer description | +| `apps/web/tests/sidebar-right.e2e.ts` | a browser case for the resistance and the return | + +`ui-sidebar-right` and its persisted layout schema, the `apps/web` source, `apps/desktop`, the shared primitives and the theme are untouched. No dependency was added. + +## Testing + +`tests/float-bounds.client.spec.ts` covers the projection (inside, each edge, corner, the top floor, an oversized panel), the resistance (the table values, slope 1 at the edge, monotone growth bounded by `K`, independent axes), its inverse and its cap, the bounded resize, and the legal size kept by the resistance and its inverse. `tests/spring.client.spec.ts` covers settling inside the deadline, the overshoot bound, frame-rate independence at 30, 60 and 120 Hz, the effect of release velocity, determinism, and the launch cap keeping every return within `K`. `tests/app-region-styles.client.spec.ts` pins the resting clamp in the stylesheet. + +`tests/float-recovery.client.spec.tsx` renders `FloatLayer` over a live controller with hand-driven frames and clock: the resisted preview past an edge, exactly one legal `moveFloat` per release and the spring to it with an inward overshoot, undo in one step, fling against slow push, a fast fling staying within `K`, a drag above the top floor, no animation for a release inside, a push that ends at the stored position, a press mid-return picking the panel up without a jump, the stall snap, the deadline, a body not re-rendered through a drag and its return but re-rendered for a new renderer, a corner press during a return picking the panel up where it is drawn and a resize from there springing in, a resize whose viewport shrank past its origin recording a legal rectangle, with no animation under reduced motion, the 20 px floor on a Windows root without a published caption height, a return yielding to an undo, a close and a press on another panel, unmount cancellation, both reduced-motion answers, the viewport projection on shrink and growth without any intent, a click on a projected panel recording nothing, a window resize during a gesture bounding its release, a resize ending a return, and an off-screen stored rectangle drawn inside. `tests/tab-layout.client.spec.tsx` adds that a float drag re-renders no docked or floating body until the renderer changes, and `components.client.spec.tsx` the same for a `DockSurface` divider drag. The existing `FloatLayer` and `TabLayout` specs still pass with their position assertions read from the resting variables, including the rule that starting a gesture forces no layout read; every changed source file is fully covered. `apps/web/tests/sidebar-right.e2e.ts` drags a Sidebar float past the right and bottom edges in Chromium, checks that the drawn panel stays within 120 px beyond them, waits for the release to settle flush against both edges, then publishes a resting rectangle far outside and larger than the viewport and checks that the stylesheet alone draws it exactly over the viewport. + +## Alternatives considered + +**Hard clamp at the edge.** Stopping the panel at the viewport edge is the cheapest correct rule, but it feels like hitting a wall and gives no sense of the boundary before contact. It remains as the reduced-motion path. + +**Clamp during the drag and rebound on release.** Clamping the drag at the edge and converting the outward pointer speed into an inward bounce keeps every frame inside the viewport. It hides how far the user pushed, so the bounce has no visible cause; the resistance shows the push and still bounds the overflow at 120 px. + +**Eased tween on release.** A fixed 240-300 ms ease-out from the released position is predictable, but it carries no velocity, so a fling and a slow push return identically, and a press during it either jumps or restarts. The spring keeps velocity continuous and is interruptible. + +**Store the off-screen position and correct it later.** Recording the released rectangle and fixing it on the next render would persist off-screen positions and make undo restore them. Recording the legal rectangle keeps one history entry per gesture with a legal value. + +**Rewrite stored rectangles when the viewport shrinks.** Moving panels through operations on resize would add history entries the user never made and change persisted layouts on every window resize. Projecting at render achieves the visible result without either, at the cost of the elastic return described below. + +**Native always-on-top OS window.** A real Electron floating window could float above other applications, but only on Desktop; the Web client cannot do it at all, and native frameless dragging gives no per-frame control, so the resistance would be impossible and the spring could only start after release. It is a separate product decision with its own window, IPC and platform work, and this decision does not preclude it. + +**Animation library dependency.** A spring library would replace a pure integrator of a few dozen lines and its tests with a new dependency in a statically linked package. The integrator also has to be clock-free for the engine's deterministic tests. + +**A shared primitive in `ui-primitives`.** Placing the hook in the primitives package would widen the change to a second package with no second consumer. It can move there when another floating surface needs it. + +## Consequences + +Floating panels can no longer be lost off screen, in either client, and a push past an edge reads as a pull back rather than a wall. History, persistence and every embedder are unaffected, and the motion is covered by deterministic tests instead of manual checks. + +A drag and the spring update the preview through React state, so the layout re-renders on every frame, for up to 900 ms after release as well. Every layout draws tab bodies through `TabBody`, which is memoized on the renderer and the tab record, so such a frame re-renders only the panel frames and headers (the header still calls `renderTabTitle`), never the tab bodies; writing a transform on the panel element directly is the fallback if the remaining cost measures as a problem. A panel pushed in by a shrinking window returns toward its stored position when the window grows, which a user who expects it to stay where it was pushed may find surprising. Content inside a panel, such as a webview, can observe up to 900 ms of motion after release. The constants are tuned for a mouse or trackpad; touch input works through the same pointer events but remains untuned. diff --git a/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.zh.md b/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.zh.md new file mode 100644 index 0000000000..6ec92d9326 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-21-floating-window-edge-recovery.zh.md @@ -0,0 +1,106 @@ +# Agent Note: 悬浮停靠面板的弹簧式边界收回 + +Status: implemented + +[English](2026-10-21-floating-window-edge-recovery.md) | 中文 + +## 问题 + +dock kit 的悬浮面板就是客户端里的悬浮窗。`FloatLayer` 与保留式 `DockLayout` 渲染器通过同一个手势 hook `useFloatGestures` 以视口坐标绘制它们，右侧 Sidebar 嵌入了它们，因此同一套面板既运行在 Web 客户端中，也运行在 Desktop 窗口内。它们的拖拽过去一比一跟随指针，只有一个顶部下限（`--dsh-dockkit-float-top`，让标题栏保持在 Windows 标题栏之下）。因此面板可以被拖过左、右或下边界，直到标题栏够不着；视口缩小会把面板留在外面；新建面板的级联位置也可能落在小视口之外。期望行为是：面板被推过边界时可见地受到阻力，松手后以弹簧物理被拉回视口内，而不是像撞墙一样被挡住或被留在外面。 + +所考察的参考实现 Claude Desktop 没有可移植的边界收回规则：它的 Electron 回退只对屏幕外窗口做一次无动画修正，且只修正右边界和下边界。该行为必须被设计，而不是移植。 + +变更维持以下义务：面板标题栏始终可达；一个手势仍然最多记录一条历史；遵循减弱动态效果；Sidebar 的持久化布局格式与所有嵌入方保持不变；运动足够确定，无需真实浏览器时钟即可测试。 + +## 决定 + +该行为完全位于 `packages/client/ui-dockkit` 内，在 `useFloatGestures` 及其调用的纯 engine 辅助函数中实现。两个悬浮渲染器都通过 `rectOf` 从该 hook 取得矩形，因此 Web 与 Desktop 共享该行为，任何嵌入方、壳或持久化格式都没有改变。该规则扩展了 [右侧 Sidebar 停靠](2026-09-04-right-sidebar-docking-infrastructure.zh.md) 的悬浮面板与 [保留式标签布局](../architecture/2026-09-20-sidebar-retained-tab-layout.zh.md) 的固定定位悬浮框，不取代其中任何一篇。 + +### 合法区域与显示位置 + +面板的合法区域是视口（`window.innerWidth` × `window.innerHeight`）加上既有的顶部下限：设置了 `data-windows-titlebar` 时为 Windows 标题栏高度加 20 px（原生全屏时为 20 px），否则为 0。`floatBounds` 只读取这些值和根元素属性，因此开始手势不会触发布局。`legalFloatRect` 逐轴把矩形投影进该区域；面板比区域更宽或更高时，在该轴上按区域尺寸绘制，使标题栏控件和缩放角留在屏幕上；存储的尺寸不变。 + +面板绘制在其存储矩形投影到视口后的位置。存储矩形从不因视口而被改写：窗口缩小时面板被推入且不记录操作，窗口变大时面板朝存储位置回移。hook 在每次按下和每次窗口 `resize` 事件时重新读取区域，进行中的手势使用新区域。包含屏幕外矩形的持久化布局无需迁移即在视口内显示。 + +静止时面板通过 `floatStyle` 把矩形以 CSS 变量发布给 `.float` 规则，该规则再次把它的位置和尺寸钳制在视口（`100vw` × `100dvh`；`dvh` 与 hook 读取的 `window.innerHeight` 一致）内并保持在标题栏下限之下；超尺寸面板在这里同样按视口尺寸绘制，与 `legalFloatRect` 一致。因此即使 hook 读到的区域尚未刷新（例如全屏切换完成前读取的值），面板仍在视口内。手势或回弹把位置和尺寸写在行内样式中，不受该钳制。 + +### 带阻力的拖拽 + +移动时由手势起始矩形和指针位移计算期望矩形，然后 `resistedRect` 逐轴把它拆分为合法投影与超出它的溢出量 `o`，并绘制在 `legal + sign(o) * K * |o| / (K + |o|)`，其中 `K = FLOAT_RESISTANCE = 120` px。该映射作用于全部四条边，包括顶部下限之上，连续、在边界处斜率为 1、渐近于 `K`： + +| 指针溢出（px） | 面板越过边界的位移（px） | 占溢出的比例 | +|---|---|---| +| 10 | 9.2 | 92.3% | +| 40 | 30.0 | 75.0% | +| 120 | 60.0 | 50.0% | +| 400 | 92.3 | 23.1% | + +缩放通过 `boundedResize` 把右下角钳制在区域内并保持 `FLOAT_MIN_SIZE`；缩放不加阻力，因为落后于指针的角看起来像坏掉的手柄。 + +### 松手与弹簧 + +松手时记录合法矩形：与按下时的合法矩形不同时记录 `moveFloat` 或 `resizeFloat`，否则只记录点击会记录的提升。因此单击以投影绘制的面板会保留其存储矩形。因此移动或缩放只记录合法矩形，撤销一步即可恢复手势前的位置。创建面板（`floatTab` 的落点矩形与级联）仍可能存储视口外的矩形，由投影把它绘制在视口内。若面板绘制在合法区域之外，hook 保留预览，用弹簧把它从绘制位置带到记录的矩形，然后清除预览。在区域内松手不播放动画。 + +`engine/spring.ts` 中的弹簧是欠阻尼的，因为它的回弹朝向内侧，始终合法：响应时间 0.32 s、阻尼比 0.72。溢出的轴以拖拽最后 100 ms 内绘制面板的速度起步，因此速度在松手前后连续；该速度上限为 `SPRING_MAX_VELOCITY`（1500 px/s），且对绘制溢出量 `d`，`launchVelocity` 把其向外分量限制在 `omega0 * (K - d)` 以内。甩过边界的面板会先走得更远再折返；由于弹簧从偏移 `d`、速度 `v` 出发时距目标至多 `d + 0.46 * v / omega0`，整条回弹轨迹都不超出边界 `K`。没有溢出的轴保持不动。每轴更新为： + +``` +a = -omega0^2 * (x - target) - 2 * zeta * omega0 * v +v = v + a * h +x = x + v * h +``` + +`stepSpring` 以等长且不超过 `h = 1/480 s` 的子步积分，因此运动与帧率无关。hook 中唯一的 `requestAnimationFrame` 循环把单帧钳制到 64 ms，帧间隔超过 250 ms 或已过 900 ms 时直接停在目标，否则在每轴距目标 1 px 内且慢于 60 px/s 时停止。从静止开始，200 px 溢出在 367 ms 内稳定，向内过冲与解析上限 `exp(-pi * zeta / sqrt(1 - zeta^2)) = 3.8%` 相差不超过一个百分点。积分器是纯函数并接收 `dt`，因此 engine 保持不读取时钟的规则。 + +回弹期间按下抓手或右下角会取消回弹，并从绘制位置接住面板。移动通过 `unresistedRect` 做到这一点：它反演阻力，因此零指针位移绘制同一矩形。缩放保留绘制时的原点，只用视口约束右下角；松手时记录合法矩形并用弹簧把原点收回视口，手势中视口缩到原点以内的缩放也是如此。两种情况下原地松手都会恢复回弹且不记录第二次操作。一个 hook 最多运行一个回弹。窗口缩放会让进行中的回弹停在记录的矩形；按下另一个面板会让它停在目标；面板记录的变化若不再投影到目标（撤销、停靠、关闭），会在下一帧让它停在新记录；卸载会取消待处理的帧。 + +### 减弱动态效果 + +`matchMedia('(prefers-reduced-motion: reduce)')` 匹配时，移动钳制在合法区域内且无阻力，松手时记录合法矩形且不播放动画。没有 `matchMedia` 的环境视为无偏好。该规则只移除运动，从不移除合法性修正。 + +### 改动范围 + +变更只涉及一个包 `@deepseek-ai/dsh-client-ui-dockkit`，其导出与 `DockIntents` 保持不变；`TabRenderer` 的约定写明了套件何时复用标签页内容。 + +| 文件 | 变更 | +|---|---| +| `packages/client/ui-dockkit/src/engine/geometry.ts` | `FloatBounds`、`FLOAT_RESISTANCE`、`legalFloatRect`、`resistedRect`、`unresistedRect`、`boundedResize` | +| `packages/client/ui-dockkit/src/engine/spring.ts` | 纯弹簧积分器、静止判定函数 `springSettled`、`launchVelocity` 与时间上限 | +| `packages/client/ui-dockkit/src/components/FloatLayer.tsx` | `useFloatGestures`：视口投影、阻力、松手弹簧、绘制速度采样、减弱动态效果、帧循环与取消；供两个渲染器使用的 `rectOf` 与 `floatStyle` | +| `packages/client/ui-dockkit/src/components/TabLayout.tsx` | 通过 `floatStyle` 绘制 hook 给出的显示矩形 | +| `packages/client/ui-dockkit/src/components/TabBody.tsx` | 各布局（`FloatLayer`、`TabLayout`、`TabPanel`）共用的 memo 化标签页内容 | +| `packages/client/ui-dockkit/src/contract/adapter.ts` | `TabRenderer` 何时被再次调用 | +| `packages/client/ui-dockkit/src/components/dockkit.module.css` | `.float` 上位置与尺寸的静止钳制 | +| `packages/client/ui-dockkit/README.md` 对 | 在悬浮渲染器说明旁补充边界规则 | +| `apps/web/tests/sidebar-right.e2e.ts` | 覆盖阻力与回弹的浏览器用例 | + +`ui-sidebar-right` 及其持久化布局 schema、`apps/web` 源码、`apps/desktop`、共享基础组件与主题均未改动。没有新增依赖。 + +## 测试 + +`tests/float-bounds.client.spec.ts` 覆盖投影（内部、每条边、角、顶部下限、超尺寸面板）、阻力（表中数值、边界处斜率为 1、以 `K` 为上界的单调增长、各轴独立）、其反演与上限，受限缩放，以及阻力与其反演都保持合法尺寸。`tests/spring.client.spec.ts` 覆盖在截止时间内稳定、过冲上限、30／60／120 Hz 下与帧率无关、松手速度的作用、确定性，以及启动速度上限让每条回弹都不超出 `K`。`tests/app-region-styles.client.spec.ts` 固定样式表中的静止钳制。 + +`tests/float-recovery.client.spec.tsx` 在活的控制器上渲染 `FloatLayer`，帧与时钟由测试手动推进：越过边界时带阻力的预览、每次松手恰好一次合法的 `moveFloat` 以及带向内过冲的弹回、一步撤销、甩出与慢推的对比、快速甩出不超出 `K`、拖过顶部下限、区域内松手不播放动画、推到存储位置的手势、回弹中按下接住面板且不跳变、停顿直接跳转、截止时间、拖拽与回弹期间不重渲染标签页内容而换新渲染函数后重渲染、回弹中按下右下角从绘制位置接住面板、从那里缩放后弹回、手势中视口缩到缩放原点以内时记录合法矩形且减弱动态效果下不播放动画、未发布标题栏高度的 Windows 根元素仍保持 20 px 下限、回弹让位于撤销、关闭与按下另一个面板、卸载取消、两种减弱动态效果答复、视口缩小与变大时的投影且不调用任何 intent、单击投影面板不记录任何操作、手势中窗口缩放约束其松手结果、缩放结束回弹，以及屏幕外存储矩形在视口内绘制。`tests/tab-layout.client.spec.tsx` 新增：悬浮面板拖拽期间停靠与悬浮的标签页内容都不重渲染，直到渲染函数改变；`components.client.spec.tsx` 对 `DockSurface` 拖动分隔条做同样的检查。既有的 `FloatLayer` 与 `TabLayout` 测试在位置断言改为读取静止变量后通过，包括开始手势不做布局读取这一规则；每个改动的源文件都被完全覆盖。`apps/web/tests/sidebar-right.e2e.ts` 在 Chromium 中把 Sidebar 悬浮面板拖过右边界和下边界，检查绘制的面板越过两边均不超过 120 px，等待松手后面板贴合两条边静止，再发布一个远在视口外且大于视口的静止矩形，检查仅靠样式表就把它恰好绘制成覆盖整个视口。 + +## 考虑过的替代方案 + +**在边界处硬钳制。** 在视口边界停住面板是成本最低的正确规则，但手感像撞墙，接触之前也感觉不到边界。它保留为减弱动态效果的路径。 + +**拖拽中钳制、松手时回弹。** 在边界处钳制拖拽，并把向外的指针速度转换为向内的回弹，能让每一帧都留在视口内。但它隐藏了用户推了多远，回弹因此没有可见的起因；阻力显示了推动，同时把溢出限制在 120 px 内。 + +**松手后的缓动补间。** 从松手位置开始的固定 240–300 ms 缓出补间可预测，但不携带速度，因此甩出与慢推的返回完全相同，补间中按下要么跳变要么重启。弹簧保持速度连续且可打断。 + +**存储屏幕外位置并在之后修正。** 记录松手矩形、在下一次渲染时修正，会持久化屏幕外位置，并让撤销恢复它们。记录合法矩形则保持每个手势一条历史且值合法。 + +**视口缩小时改写存储矩形。** 在缩放时通过操作移动面板会增加用户从未做过的历史条目，并在每次窗口缩放时改变持久化布局。渲染时投影无需二者即可得到可见结果，代价是下文描述的弹性返回。 + +**原生始终置顶 OS 窗口。** 真正的 Electron 悬浮窗可以浮在其他应用之上，但只在 Desktop 上可行；Web 客户端完全无法做到，而且原生无边框拖拽不提供逐帧控制，因此阻力无法实现，弹簧只能在松手后启动。它是一个独立的产品决策，有自己的窗口、IPC 与平台工作，本决定不排斥它。 + +**动画库依赖。** 弹簧库会用一个静态链接包里的新依赖替换几十行的纯积分器及其测试。积分器还必须不依赖时钟，才能用于 engine 的确定性测试。 + +**放进 `ui-primitives` 的共享基础组件。** 把 hook 放进基础组件包会把改动扩大到第二个包，而没有第二个使用方。等另一个悬浮界面需要它时再迁移。 + +## 后果 + +悬浮面板在两个客户端中都不会再丢失到屏幕外，推过边界读起来是被拉回而不是撞墙。历史、持久化与所有嵌入方不受影响，运动由确定性测试而非手动检查覆盖。 + +拖拽与弹簧都通过 React state 更新预览，因此布局每帧都会重渲染，松手后最多还会持续 900 ms。各布局都通过 `TabBody` 绘制标签页内容，它以渲染函数和标签记录为键做了 memo，因此这样的一帧只重渲染面板框与标题栏（标题栏仍会调用 `renderTabTitle`），从不重渲染标签页内容；如果剩余成本经测量构成问题，退路是直接在面板元素上写 transform。被缩小窗口推入的面板会在窗口变大时朝存储位置回移，期望它留在被推到位置的用户可能会感到意外。面板内的内容（例如 webview）在松手后可能观察到最多 900 ms 的运动。常量针对鼠标或触控板调优；触控输入经由同样的 pointer 事件可用，但仍未调优。 diff --git a/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.i18n.yaml b/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.i18n.yaml new file mode 100644 index 0000000000..e3b8a71842 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-10-22-listed-model-badges.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 .agents/notes/implemented/feature/2026-10-22-listed-model-badges.md +/agent-note-model-selector-badges-come-from-the-model-listing: + en: cc4b8fee78e75a98 + zh: 3cf21a37bea4410c +/agent-note-model-selector-badges-come-from-the-model-listing/problem: + en: ed011e743511ef25 + zh: 2389e339f1a6dcbf +/agent-note-model-selector-badges-come-from-the-model-listing/decision: + en: 84b99f80d8824117 + zh: 94cd96f59caf5b43 +/agent-note-model-selector-badges-come-from-the-model-listing/alternatives-considered: + en: 079466e0dd56584e + zh: 8e33049c422d77cb +/agent-note-model-selector-badges-come-from-the-model-listing/consequences: + en: 3ba39c2a109e49cd + zh: 3eb16676854230f9 diff --git a/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.md b/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.md new file mode 100644 index 0000000000..cb4260bdb1 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.md @@ -0,0 +1,47 @@ +# Agent Note: Model selector badges come from the model listing + +Status: implemented + +English | [中文](2026-10-22-listed-model-badges.zh.md) + +## Problem + +The Web model selector showed `1017` beside `DeepSeek-V4.1-Flash` through a dedicated client package that matched two DeepSeek providers, one model id, and one exact catalog name. Changing or retiring that release marker, or labeling another model, required a client release, while both DeepSeek routes already read model metadata from the service's `GET /models` listing. + +## Decision + +- Each `/models` entry may declare `badge: { text, tone }` under `client_metadata["deepseek-harness"]`, keyed like `client_requirements` by the User-Agent product token. `client_metadata` holds client-specific data that every build may ignore, so the public model fields stay unchanged and later DeepSeek Harness fields join the same object. `text` uses the package-metadata `LocalizedText` form: one string, or translations keyed by lowercase language id that include `en`. Each text is trimmed and holds 1 to 12 user-perceived characters on one line; controls, Unicode line separators, bidi controls, and text made only of whitespace or default-ignorable characters are rejected. +- `tone` is `neutral`, `info`, `success`, or `warning`: the `Tag` palettes for a plain fact, a highlight, a benefit, and attention. The shipped release marker used `info`; the surveyed selectors draw plan and capability tags neutral, new features with an accent, and usage hints in a warning color. `danger` and `solid` keep their failure and selection meanings. +- [`parseModelListing`](../../../../packages/llm/llm-deepseek/src/listing.ts) decodes the badge beside the entry's other declarations, and [`resolveListedCatalog`](../../../../packages/llm/llm-deepseek/src/listed-catalog.ts) keeps the badges of offered models; both routes attach them through `catalogModelInfo`. An absent or `null` value at any level of that path shows no badge, and an absent or unrecognized tone shows `neutral`. A level that is not an object or an unreadable badge drops the badge, which is reported with the listing's other problems and never hides its model. +- `LlmModelInfo.badge` and `ModelCatalogModel.badge` carry the badge from discovery through the Host model catalog to the browser. `resolveModelInfo` omits it, and no model request, Session event, or model-facing tool reads it. +- [`ui-model-selection`](../../../../packages/client/ui-model-selection/README.md) renders the badge before the catalog name in the trigger and after it in the root-menu value and each option, resolving its text with `ctx.locale.resolveText`. A `conversation.input.model.label` contribution replaces the name and badge together and receives the badge in its owner props. +- The build ships no badge of its own: a route before its first listing shows none. The API-key route does not follow listings for customized catalogs or non-official endpoints; the account route follows the origin of its configured `baseURL`, including custom endpoints. The fixed `ui-deepseek-model-label-1017` package and its Web bundle row are removed. +- After first use, the credential-scoped cache refreshes automatically at `modelsMaxAgeMs` (ten minutes by default) and publishes changed catalogs through `llm/models-updated`. Successful listings replace all badge metadata, so omission or `null` clears an old badge. Failed refreshes retain the last successful listing, including badges: a failed request does not establish that the server withdrew a badge. This avoids independent polling in every browser. A zero interval preserves access-only refresh. + +## Alternatives considered + +**A top-level `badge` field.** The public `/models` fields describe model capabilities and limits for every client, while the badge is DeepSeek Harness release and campaign copy. A top-level field reads as a model attribute that other clients could start rendering, after which the service could no longer change or retire it freely, and two clients could not show different badges. + +**`badge` inside `client_requirements["deepseek-harness"]`.** It adds no top-level field, and released builds ignore an extra key there. But an unreadable requirement hides its model on every build, released ones included, so a serializer that writes the emptied object as `null` after a badge is retired would hide the model. Requirements gate availability; display data must stay ignorable. + +**A narrower map such as `client_presentation` or `client_annotations`.** These names limit the object to display data or descriptive notes, so the next client-specific field of another kind, such as a default, would need another top-level field; `client_metadata` takes any field a build may ignore. + +**A semantic badge kind mapped to client dictionaries.** OpenCode, ZCode, and DeepSeek-Reasonix translate a closed set of client-owned tag kinds, and none renders text a server sends. A fixed vocabulary cannot express a release code such as `1017`, and each new wording would need the client release the listing exists to avoid. Listing text is provider data, which the [locale-owned copy decision](../architecture/2026-08-23-locale-owned-client-ui-copy.md) renders verbatim; the `LocalizedText` form still lets the service supply translations. + +**Accept colors, CSS, or markup from the listing.** No surveyed product accepts styling from a catalog, and arbitrary colors bypass the theme's light and dark palettes and their contrast. A closed tone set maps onto the existing `Tag` palettes, and an unrecognized tone degrades to `neutral`, so a value a newer service adds never removes the text. + +**Keep `1017` as a built-in default.** A bundled badge would keep the marker offline and on custom endpoints. Under the listing rule that an absent field keeps the build's value, the service could then remove it only with a special empty value, and old builds would keep the stale marker wherever no listing loads. Shipping no badge makes the listing the only source, so omitting the field removes the badge. + +**An expiry or start time on the badge.** The listing cache lives in memory and refreshes on access after `modelsMaxAgeMs`, so a badge the service drops disappears within one refresh. Client-side time windows would add dependence on the client clock without removing reachable staleness. + +**Drop the whole entry or listing for a bad badge.** OpenCode drops a model whose catalog status it cannot decode, and Codex fails its catalog decode on one unknown enum value. A badge is presentation only, so a bad one is dropped by itself. + +**A DeepSeek-specific badge Remote beside the catalog.** Keeping the badge out of `LlmModelInfo` would need a second Remote, a second client fetch, and agreement between two caches about which models exist. One optional field on the existing catalog reaches every placement in one load. + +## Consequences + +- The service changes, localizes, or removes a badge without a client release; a running client shows the change after its next listing refresh and catalog reload. +- A condition that older builds must enforce belongs in `client_requirements`; every field under `client_metadata` must be safe for a build that does not read it. +- `deepseek-flash` shows no badge until the service declares one and a listing loads. Customized catalogs and non-official endpoints on the API-key route do not receive listed badges. +- The `/model` popup, the trigger's accessible name, and the Models settings page keep plain names. +- A profile patch that still targets `ui-deepseek-model-label-1017` matches no row and boots with a warning ([upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md)). diff --git a/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.zh.md b/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.zh.md new file mode 100644 index 0000000000..6b2e42032d --- /dev/null +++ b/.agents/notes/implemented/feature/2026-10-22-listed-model-badges.zh.md @@ -0,0 +1,47 @@ +# Agent Note: 模型选择器角标来自模型列表 + +Status: implemented + +[English](2026-10-22-listed-model-badges.md) | 中文 + +## 问题 + +Web 模型选择器通过一个专门的客户端包在 `DeepSeek-V4.1-Flash` 旁显示 `1017`，该包写死匹配两个 DeepSeek 提供方、一个模型 id 和一个确切的目录名称。修改或撤下这个版本标记、给其他模型加标签，都要发一次客户端版本；而两条 DeepSeek 路由早已从服务端的 `GET /models` 列表读取模型元数据。 + +## 决策 + +- 每个 `/models` 条目可以在 `client_metadata["deepseek-harness"]` 下声明 `badge: { text, tone }`，与 `client_requirements` 一样以 User-Agent 的产品名为键。`client_metadata` 存放所有版本都可以忽略的客户端专属数据，因此公开的模型字段保持不变，以后新增的 DeepSeek Harness 字段也放进同一个对象。`text` 采用包元数据的 `LocalizedText` 形式：单个字符串，或以小写语言 id 为键且包含 `en` 的译文。每段文字去掉首尾空白后须为单行，长度为 1 到 12 个用户可见字符；拒绝控制字符、Unicode 行分隔符、双向控制符及仅由空白或默认可忽略字符组成的文字。 +- `tone` 取 `neutral`、`info`、`success` 或 `warning`，分别是 `Tag` 表示普通事实、强调、利好和需要注意的配色。已发布的版本标记使用 `info`；调研的选择器把套餐和能力标签画成中性色，新功能用强调色，用量提示用警示色。`danger` 和 `solid` 保留各自表示失败和当前选中的含义。 +- [`parseModelListing`](../../../../packages/llm/llm-deepseek/src/listing.ts) 与条目的其他声明一起解码角标，[`resolveListedCatalog`](../../../../packages/llm/llm-deepseek/src/listed-catalog.ts) 保留已提供模型的角标；两条路由都通过 `catalogModelInfo` 附上角标。这条路径上任何一层缺省或为 `null` 时不显示角标；`tone` 缺省或无法识别时按 `neutral` 显示。某一层不是对象或角标无法读取时，角标被丢弃，并与列表的其他问题一起报告，但不会隐藏所属模型。 +- `LlmModelInfo.badge` 与 `ModelCatalogModel.badge` 把角标从模型发现经 Host 模型目录送到浏览器。`resolveModelInfo` 不返回它，模型请求、Session 事件和面向模型的工具都不读取它。 +- [`ui-model-selection`](../../../../packages/client/ui-model-selection/README.zh.md) 在触发按钮中把角标放在目录名称之前，在根菜单当前值和各选项中仍放在名称之后，并用 `ctx.locale.resolveText` 解析其文字。`conversation.input.model.label` 的扩展会同时替换名称与角标，并从 owner props 收到角标。 +- 本版本不内置任何角标：路由加载到第一份列表之前不显示角标。API key 路由在自定义目录或非官方端点上不跟随列表；账号路由跟随配置的 `baseURL` 的源，包括自定义端点。写死的 `ui-deepseek-model-label-1017` 包及其 Web bundle 条目已移除。 +- 按凭据区分的缓存首次使用后按 `modelsMaxAgeMs`（默认十分钟）自动刷新，通过 `llm/models-updated` 发布目录变化。成功加载会替换所有角标元数据，因此省略或 `null` 都会清除旧角标。刷新失败时保留上次成功加载的列表及其角标：请求失败并不能证明服务端撤下了角标。这样也避免了每个浏览器独立轮询。间隔为零时仍只在访问时刷新。 + +## 考虑过的替代方案 + +**顶层 `badge` 字段。** 公开的 `/models` 字段为所有客户端描述模型的能力与限制，而角标是 DeepSeek Harness 的发版和运营文案。放在顶层会被当作模型属性，其他客户端可能开始显示它，此后服务端就无法随意修改或撤下；两个客户端也无法显示不同的角标。 + +**把 `badge` 放进 `client_requirements["deepseek-harness"]`。** 这样不增加顶层字段，已发布版本也会忽略其中多出的键。但版本要求无法读取时，所有版本都会隐藏该模型，已发布的版本也不例外；撤下角标后，序列化器若把清空的对象写成 `null`，模型就会被隐藏。版本要求决定模型能否使用，展示数据必须可以忽略。 + +**范围更窄的映射，例如 `client_presentation` 或 `client_annotations`。** 这些名称把对象限定为展示数据或附加说明，下一个其他类型的客户端专属字段（例如默认值）又要新开一个顶层字段；`client_metadata` 可以容纳任何版本都能忽略的字段。 + +**用语义化的角标类别映射到客户端字典。** OpenCode、ZCode 和 DeepSeek-Reasonix 都翻译一组封闭的、由客户端持有的标签类别，没有一家直接渲染服务端发来的文字。固定词表表达不了 `1017` 这样的版本代号，每出现一种新说法都要发一次客户端版本，而列表正是为了免去这一步。列表文字属于提供方数据，按[客户端文案归 locale 管理的决定](../architecture/2026-08-23-locale-owned-client-ui-copy.zh.md)原样渲染；`LocalizedText` 形式仍允许服务端提供译文。 + +**接受列表下发的颜色、CSS 或标记。** 调研的产品都不接受目录下发的样式；任意颜色会绕过主题的明暗配色及其对比度。封闭的语调集合直接对应现有 `Tag` 配色；无法识别的语调降级为 `neutral`，因此较新的服务端新增的取值不会让文字消失。 + +**把 `1017` 保留为内置默认值。** 内置角标能让标记在离线和自定义端点下继续显示。但按照“字段缺失时沿用本版本的值”的列表规则，服务端只能用特殊的空值才能去掉它，而且旧版本在加载不到列表时会一直显示过时的标记。不内置角标，列表就是唯一来源，省略字段即可去掉角标。 + +**给角标加过期时间或生效时间。** 列表缓存只在内存中，超过 `modelsMaxAgeMs` 后在访问时刷新，服务端撤下的角标在一次刷新内就会消失。客户端时间窗口会引入对客户端时钟的依赖，却消除不了实际可能出现的陈旧数据。 + +**角标有误时丢弃整个条目或整份列表。** OpenCode 会丢掉目录状态无法解码的模型，Codex 遇到一个未知枚举值就让整份目录解码失败。角标只用于展示，有误时只丢弃角标本身。 + +**在目录之外为 DeepSeek 单独提供角标 Remote。** 让角标不进入 `LlmModelInfo`，就需要第二个 Remote、客户端的第二次请求，以及两份缓存对“有哪些模型”保持一致。在现有目录上增加一个可选字段，一次加载即可送到所有显示位置。 + +## 影响 + +- 服务端无需客户端发版即可修改、翻译或撤下角标；运行中的客户端在下一次列表刷新和目录重新加载后显示变化。 +- 旧版本必须执行的条件放在 `client_requirements`；`client_metadata` 下的每个字段都必须保证不读取它的版本也能安全运行。 +- 服务端声明并加载到列表之前，`deepseek-flash` 不显示角标。API key 路由的自定义目录与非官方端点不接收列表角标。 +- `/model` 弹窗、触发按钮的无障碍名称和模型设置页仍只显示名称。 +- 仍指向 `ui-deepseek-model-label-1017` 的 profile patch 不再匹配任何条目，启动时会给出警告（[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.zh.md)）。 diff --git a/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.i18n.yaml b/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.i18n.yaml index c8ae9617c4..7005f647dc 100644 --- a/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.i18n.yaml +++ b/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.i18n.yaml @@ -9,14 +9,14 @@ en: 46916488210ba493 zh: 98107c3805a22b2c /agent-note-dual-release-install-layout-work-budget/decision: - en: c432b68c4ad1b3c1 - zh: a11e958fa68dc2f3 + en: b900469750b27f81 + zh: d5380d7751332e9c /agent-note-dual-release-install-layout-work-budget/what-the-resolution-costs: - en: 36d3e3ef39cbba2f - zh: 2480acf6260817b3 + en: 463df1fae15ae2fc + zh: 733c9ddb4900e3fc /agent-note-dual-release-install-layout-work-budget/alternatives-considered: en: 29987b7634c84d28 zh: a1469e4b6aaa46e2 /agent-note-dual-release-install-layout-work-budget/consequences: - en: 8dffc0c3fa699980 - zh: 99ec25001e5aa716 + en: 4226e2216abe042d + zh: db8f308ef40f47e9 diff --git a/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.md b/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.md index 24e2ae8fe7..43dd69c9df 100644 --- a/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.md +++ b/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.md @@ -10,14 +10,16 @@ The `Dependency layout` lane packs two incompatible synthetic DSH releases into ## Decision -`scripts/verify-npm-install-layout.ts` decides growth with `assertResolutionWorkBudget`, which bounds `dshPackagesPerVersion * checkedDshEdges` against `MAX_RESOLUTION_WORK_UNITS = 875_000`. Both counts come from the summary `assertDualDshInstallLayout` returns, so the budget applies to the graph npm actually produced rather than to a prediction of it. A graph above the budget fails with its own counts, the budget, and the instruction to measure the new resolution cost and raise the constant. +`scripts/verify-npm-install-layout.ts` decides growth with `assertResolutionWorkBudget`, which bounds `dshPackagesPerVersion * checkedDshEdges` against `MAX_RESOLUTION_WORK_UNITS = 1_134_400`. Both counts come from the summary `assertDualDshInstallLayout` returns, so the budget applies to the graph npm actually produced rather than to a prediction of it. A graph above the budget fails with its own counts, the budget, and the instruction to measure the new resolution cost and raise the constant. -The npm child keeps a wall-clock limit, `NPM_HANG_GUARD_MS`, derived as `4 * MAX_RESOLUTION_WORK_UNITS * SECONDS_PER_WORK_UNIT` (910 s). It is a hang guard, not the growth criterion: a runner up to four times slower than the measured host cannot decide the gate's outcome, and deriving it from the budget keeps the two values from drifting apart. +The npm child keeps a wall-clock limit, `NPM_HANG_GUARD_MS`, derived as `4 * MAX_RESOLUTION_WORK_UNITS * SECONDS_PER_WORK_UNIT` (about 1,180 s). It is a hang guard, not the growth criterion: a runner up to four times slower than the measured host cannot decide the gate's outcome, and deriving it from the budget keeps the two values from drifting apart. This restores the [published dependency faces](2026-08-26-published-dependency-faces.md) decision that `verify-npm-install-layout` does not enforce resolver duration; the 300 s deadline had contradicted it. ## What the resolution costs +Measured 2026-10-26 on an idle Apple M5 Pro with Node 24.17.0 and npm 11.13.0, using `buildDualDshRegistry`, `resolveNpmPackageLock`, and `assertDualDshInstallLayout` sequentially with fresh temporary consumers: the #5960 graph (315 packages per release, 2782 internal edges, 876,330 work units) resolved in 75.27 s; the #5961 graph (320 packages, 2836 edges, 907,520 units) resolved in 71.03 s, with a second verification at 97.73 s. All placements passed, shared one Cordis installation, and requested no archives. The measurements calibrate graph admission and do not establish a runtime improvement. The current budget is 1.25 times its 907,520 units; the earlier, slower per-unit timing remains the conservative hang-guard calibration. + Measured 2026-09-28 on an idle M-series host, against `origin/master` (277 DSH packages per release, 2524 internal edges), by running the lane's own npm invocation with `--timing` and `--cpu-prof`: | Phase | Cost | @@ -47,4 +49,4 @@ Repeated runs of the same graph on one host span 137.8 s to 204.8 s of npm time, ## Consequences -The lane's failure now depends on the graph, so a pull request that adds a few DSH packages passes on any runner, and a graph that grows the packages-times-edges product by more than about a quarter — about 12% in packages and internal edges together — fails deterministically with its measured counts. The budget is a ratchet: raising it is a deliberate edit that must come with a new resolution measurement, and the constant's comment records the counts it was derived from. A graph inside the budget still spends its full resolution time, because the change moves the decision and not the work; nothing here reduces the 153 s npm needs to place the dual release. A genuine npm hang now consumes up to 910 s of the lane before failing, where the old deadline capped it at 300 s. Growth that changes the shape of the graph without changing packages times edges stays inside the budget and is caught only if the hang guard expires. +The lane's failure now depends on the graph, so a pull request that adds a few DSH packages passes on any runner, and a graph that grows the packages-times-edges product by more than about a quarter — about 12% in packages and internal edges together — fails deterministically with its measured counts. The budget is a ratchet: raising it is a deliberate edit that must come with a new resolution measurement, and the constant's comment records the counts it was derived from. A graph inside the budget still spends its full resolution time, because the change moves the decision and not the work; nothing here reduces the 153 s npm needs to place the dual release. A genuine npm hang now consumes up to about 1,180 s of the lane before failing, where the old deadline capped it at 300 s. Growth that changes the shape of the graph without changing packages times edges stays inside the budget and is caught only if the hang guard expires. diff --git a/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.zh.md b/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.zh.md index 03380bca7a..07c58d75e1 100644 --- a/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.zh.md +++ b/.agents/notes/implemented/process/2026-09-28-dual-release-install-layout-work-budget.zh.md @@ -10,14 +10,16 @@ Status: implemented ## Decision -`scripts/verify-npm-install-layout.ts` 用 `assertResolutionWorkBudget` 判定规模增长，它以 `dshPackagesPerVersion * checkedDshEdges` 为工作量单位，与 `MAX_RESOLUTION_WORK_UNITS = 875_000` 比较。两个计数都来自 `assertDualDshInstallLayout` 返回的汇总，因此预算作用于 npm 实际产出的图，而不是对图的预测。超过预算的图会带着自己的计数、预算值，以及「测量新的解析开销并调高该常量」的指示失败。 +`scripts/verify-npm-install-layout.ts` 用 `assertResolutionWorkBudget` 判定规模增长，它以 `dshPackagesPerVersion * checkedDshEdges` 为工作量单位，与 `MAX_RESOLUTION_WORK_UNITS = 1_134_400` 比较。两个计数都来自 `assertDualDshInstallLayout` 返回的汇总，因此预算作用于 npm 实际产出的图，而不是对图的预测。超过预算的图会带着自己的计数、预算值，以及「测量新的解析开销并调高该常量」的指示失败。 -npm 子进程仍保留墙钟上限 `NPM_HANG_GUARD_MS`，由 `4 * MAX_RESOLUTION_WORK_UNITS * SECONDS_PER_WORK_UNIT` 推导（910 秒）。它是挂起保护，不是增长判据：比实测主机慢四倍以内的 runner 无法决定该门禁的结果，而由预算推导可避免两个数值彼此漂移。 +npm 子进程仍保留墙钟上限 `NPM_HANG_GUARD_MS`，由 `4 * MAX_RESOLUTION_WORK_UNITS * SECONDS_PER_WORK_UNIT` 推导（约 1,180 秒）。它是挂起保护，不是增长判据：比实测主机慢四倍以内的 runner 无法决定该门禁的结果，而由预算推导可避免两个数值彼此漂移。 这恢复了[发布依赖门面](2026-08-26-published-dependency-faces.zh.md)中「`verify-npm-install-layout` 不限制 resolver 耗时」的决定；300 秒期限与该决定相矛盾。 ## What the resolution costs +2026-10-26 在空闲 Apple M5 Pro 上使用 Node 24.17.0 与 npm 11.13.0，通过 `buildDualDshRegistry`、`resolveNpmPackageLock` 和 `assertDualDshInstallLayout`，对独立的新建临时消费者目录依次测量：#5960 的依赖图（每个发布 315 个包、2782 条内部边、876,330 个工作量单位）用 75.27 秒解析；#5961 的依赖图（320 个包、2836 条边、907,520 个工作量单位）用 71.03 秒解析，第二次验证耗时 97.73 秒。所有布局校验均通过，共享一个 Cordis 安装，未请求包归档。这些测量用于校准依赖图的准入规模，不代表运行时性能提升。当前预算为其 907,520 个工作量单位的 1.25 倍；挂起保护仍采用此前较慢的单位工作量耗时作为保守校准。 + 2026-09-28 在空闲的 M 系列主机上，针对 `origin/master`（每个发布 277 个 DSH 包、2524 条内部边），用 `--timing` 和 `--cpu-prof` 运行 lane 自身的 npm 调用测得： | 阶段 | 开销 | @@ -47,4 +49,4 @@ npm 子进程仍保留墙钟上限 `NPM_HANG_GUARD_MS`，由 `4 * MAX_RESOLUTION ## Consequences -lane 的失败判定如今取决于依赖图，因此新增少量 DSH 包的 pull request 在任何 runner 上都能通过，而「包数乘边数」增长超过约四分之一的图——即包数与内部边数同步增长约 12%——会带着实测计数确定性地失败。预算是棘轮：调高它是一次刻意修改，必须附带新的解析实测，该常量注释里记录了推导所用的计数。预算内的图仍会花掉完整的解析时间，因为这次改动移动的是判定位置而不是工作本身；这里没有任何东西能减少 npm 摆放双发布所需的 153 s。真正挂起的 npm 现在会消耗该 lane 最多 910 秒才失败，而旧期限把它限制在 300 秒。若图的增长改变了形状却没有改变「包数乘边数」，它仍留在预算内，只有在挂起保护到期时才被发现。 +lane 的失败判定如今取决于依赖图，因此新增少量 DSH 包的 pull request 在任何 runner 上都能通过，而「包数乘边数」增长超过约四分之一的图——即包数与内部边数同步增长约 12%——会带着实测计数确定性地失败。预算是棘轮：调高它是一次刻意修改，必须附带新的解析实测，该常量注释里记录了推导所用的计数。预算内的图仍会花掉完整的解析时间，因为这次改动移动的是判定位置而不是工作本身；这里没有任何东西能减少 npm 摆放双发布所需的 153 s。真正挂起的 npm 现在会消耗该 lane 最多约 1,180 秒才失败，而旧期限把它限制在 300 秒。若图的增长改变了形状却没有改变「包数乘边数」，它仍留在预算内，只有在挂起保护到期时才被发现。 diff --git a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.i18n.yaml b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.i18n.yaml index 8cbe83c2f7..31c799468d 100644 --- a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.i18n.yaml @@ -29,6 +29,9 @@ /agent-note-frontend-large-session-performance-budgets/calibration/history-selector-invalidation: en: 2d2f78f4cf6aad8a zh: aec6af5f7c66de16 +/agent-note-frontend-large-session-performance-budgets/calibration/streaming-assistant-visibility: + en: 5dc3c84b80be0e8e + zh: 4bbd16e1f455ef85 /agent-note-frontend-large-session-performance-budgets/alternatives-considered: en: 4d2a4a64ccd14507 zh: 8a4aaf4d4abea13d diff --git a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md index 16277f4f37..50cc863788 100644 --- a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md +++ b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.md @@ -102,6 +102,23 @@ These local runs both failed the independent open budget: their open medians wer Post-GC browser heap was 80.70/80.71 MiB. GNU time reported maximum RSS of 535.78/561.80 MiB for each benchmark command and its children; this is not input-phase memory or an aggregate browser-memory measurement. Moving the composer's selection reveal into an animation frame was rejected: profiling showed the style flush moved to another geometry read, without improving typing. The product fix removes the invalidation source instead. +### Streaming Assistant visibility + +Chat retains visibility per Assistant block. Same-kind text and reasoning appends inspect only the incoming delta until the block becomes visible, then reuse that result. This avoids repeated `trim()` calls on accumulated strings without changing whitespace, first-token timing, or visible anchors. Replacements recalculate visibility, retry resets it, and final messages rebuild it. Copying the block array remains proportional to its length; this does not make every Assembler operation constant-time. + +The [conversation-fold worker](../../../../benchmarks/conversation-fold/conversation-fold.worker.client.ts) measures a single 256 KiB block split into 4,096 or 16,384 deltas, using ordinary text or reasoning whose first half is whitespace. Five fresh compiled Node children per case reuse the existing benchmark registrations, production Assembler and Chat builder. Timing includes every append, one final flush, and reading every output character. Fixture preparation and GC are excluded; retained heap is the post-GC increment with the Assembler, live entries and published state still reachable. + +Local macOS arm64 measurements on Node 26.8.2 give these elapsed medians. The time limits use reference allowances of 12/32 ms and the existing shared scale and headroom; they are not new hosted-runner calibration. + +| Workload | Deltas | Repeated accumulated trim | Cached visibility | Time limit | +|---|---:|---:|---:|---:| +| Ordinary text | 4,096 | 42.25 ms | 7.32 ms | 30 ms | +| Half-leading-whitespace reasoning | 4,096 | 252.75 ms | 7.96 ms | 30 ms | +| Ordinary text | 16,384 | 206.71 ms | 23.06 ms | 80 ms | +| Half-leading-whitespace reasoning | 16,384 | 1114.18 ms | 23.08 ms | 80 ms | + +All four cases reject accumulated trimming and pass with cached visibility. Retained heap remains approximately 2.8/9.9 MiB for the two fragment counts, below the 20 MiB limit derived from a 16 MiB allowance. Maximum worker RSS across these samples falls from 185.70 to 89.36 MiB; it is a whole-process diagnostic, not aggregate application memory. This endpoint measures local assembly with one final publication, excluding network, browser rendering and Trajectory. Separate browser regressions cover settlement, cancellation, retry, reload, reopening and blank reasoning without asserting a browser speedup. + ## Alternatives considered **Use the Node fold as paint evidence.** Rejected because it never performs DOM mutation, layout, or browser scheduling. The focused reconnect case likewise makes no GUI speed claim. diff --git a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md index 159c31f935..1c469a7768 100644 --- a/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md +++ b/.agents/notes/implemented/testing/2026-09-06-frontend-performance-budgets.zh.md @@ -102,6 +102,23 @@ Trajectory 激活在动画帧上采样可见搜索框与 `[data-trajectory-scrol 强制 GC 后的浏览器 heap 为 80.70/80.71 MiB。GNU time 为两次基准命令及其子进程报告的最大 RSS 为 535.78/561.80 MiB；这不是输入阶段内存，也不是浏览器总内存测量。曾尝试将输入框的选区显示推迟到动画帧，但分析显示样式刷新转移到另一处几何读取，没有改善键入，因此未采用。产品修复直接移除样式失效的来源。 +### 流式 Assistant 可见性 + +Chat 保存每个 Assistant 块的可见状态。同类型文本和推理追加只检查新增片段，直到该块可见，之后复用结果。这避免对累计字符串重复调用 `trim()`，同时保留空白、首 token 时间及可见锚点。块替换重新计算可见性，重试清空状态，最终消息重建状态。块数组复制仍与其长度成正比，因此并非每次 Assembler 操作都是常数时间。 + +[conversation-fold worker](../../../../benchmarks/conversation-fold/conversation-fold.worker.client.ts) 测量单个 256 KiB 块，拆成 4,096 或 16,384 个片段，内容为普通文本或前半段为空白的推理。每个用例使用五个全新的已编译 Node 子进程，复用现有基准注册、生产 Assembler 和 Chat builder。计时包含每次追加、一次最终 flush 及逐字符读取输出。夹具准备和 GC 不计时；保留堆内存为 GC 后的增量，此时 Assembler、实时条目和已发布状态仍可达。 + +macOS arm64、Node 26.8.2 上的本地测量得到以下耗时中位数。时间上限使用 12/32 ms 参考额度及现有共享缩放与余量，不代表新的托管运行器校准。 + +| 工作负载 | 片段数 | 累计文本重复 trim | 缓存可见性 | 时间上限 | +|---|---:|---:|---:|---:| +| 普通文本 | 4,096 | 42.25 ms | 7.32 ms | 30 ms | +| 前半段为空白的推理 | 4,096 | 252.75 ms | 7.96 ms | 30 ms | +| 普通文本 | 16,384 | 206.71 ms | 23.06 ms | 80 ms | +| 前半段为空白的推理 | 16,384 | 1114.18 ms | 23.08 ms | 80 ms | + +四个用例都拒绝累计文本重复 trim，并在缓存可见性后通过。两个片段规模的保留堆内存仍约为 2.8/9.9 MiB，低于 16 MiB 额度经余量计算后的 20 MiB 上限。这些样本中的 worker 最大 RSS 从 185.70 降至 89.36 MiB；它是整个进程的诊断值，不是应用总内存。该终点只测量一次最终发布的本地组装，不包含网络、浏览器渲染和 Trajectory。独立浏览器回归覆盖结算、取消、重试、刷新、重开及空白推理，不据此声称浏览器提速。 + ## 考虑过的替代方案 **用 Node 折叠作为绘制证据。** 拒绝，因为它不执行 DOM 修改、布局或浏览器调度。聚焦重连用例同样不声称 GUI 提速。 diff --git a/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.i18n.yaml b/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.i18n.yaml index 4a98c2f555..c8b3188032 100644 --- a/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.i18n.yaml @@ -18,11 +18,11 @@ en: 1310a89c351e5bfe zh: e6386ae10b893c2d /agent-note-performance-baselines-for-large-session-corpora/decision/measured-endpoints: - en: 11937dfa4a349a19 - zh: b91a136890fe92e8 + en: add81088ce51033f + zh: c7065dc3052648fa /agent-note-performance-baselines-for-large-session-corpora/calibration-evidence: - en: f934c95748dcbfe0 - zh: df6a68286c21510f + en: adb815c213373d8e + zh: 44d4c6752a4df51f /agent-note-performance-baselines-for-large-session-corpora/alternatives-considered: en: 4eaa4666262a1aee zh: 7e2eb44b94bad05d diff --git a/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.md b/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.md index 2efe66ead2..7890b73070 100644 --- a/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.md +++ b/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.md @@ -47,6 +47,8 @@ The shared corpus and projection-list controller fixture awaits controller activ The file must finish within five minutes on standard hosted CI, including seeding, and its last case asserts that limit. Search over 1,000 Sessions and one fork of the longest Session take about 170 s of it, so each has one sample. The list corpus is the largest that fits the remainder. Budgets enforce medians of list boot, first, and repeat, and of the fork median over strata and rank 990; search and the longest fork enforce their single samples. Search and fork use separate 1,000-Session roots, so fork children never reach the search index. Rank 988 is the highest top-level rank at the measured p99 (7,229 events); forking a subagent child adds a lineage lookup, and rank 990 already falls in the 99.3% anchor. Peak RSS of the list, search, and fork processes has a budget with the shared 1.25 headroom and no time scale. Each child's deadline equals the file limit, and each test's deadline outlasts its sequential children, so a failed case reaps every child before the scratch root is removed. +Fork workers use a 512 MiB V8 old-space limit so every runner measures the same heap constraint. The corpus, timed endpoints, and whole-process peak RSS budget stay unchanged; native buffers still count toward RSS. The longest fork retains about 193 MiB after collection, so the limit leaves room for live objects while forcing collection before a larger host-selected heap delays it. This measures a bounded-heap workload, not the default-heap peak of every deployment. + ## Calibration evidence Budgets use standard two-CPU hosted CI expectations (Linux x64, Node 24.21, PR #5403), rounded above the higher recorded median across the AMD EPYC 7763 and EPYC 9V74 runners and multiplied by the shared 1.25 headroom. Samples varied by up to 15% within one run; the runner models differed by up to 25% per endpoint. The hosted-to-reference ratio is 2.4 to 3.4, above the shared reference scale of 2, so reference-machine scaling would reject ordinary hosted runs. @@ -67,6 +69,8 @@ With seeding in one process, the complete file took 294.5 s on the EPYC 7763 run On Apple M5 Pro with Node 26.5, isolated runs measured list 1,000 at 311–358 ms first, list 5,000 at 1,364–1,603 ms first, search at 57 s first, and fork of the longest Session at 6.0–6.4 s. A 10,000-Session list took 3.2–5.4 s for the first call with 1.9 GB peak RSS. +Node 24.22 hosted runs of the unchanged longest-fork workload recorded 696 MiB peak RSS on EPYC 9V74 and 1,077.7 MiB on EPYC 7763, against the same 938 MiB budget. On Apple M5 Pro with Node 24.19, two default-heap runs retained 192.8–193.4 MiB and peaked at 770.7–812.6 MiB in 2.416–2.447 s; two 512 MiB old-space runs retained the same range and peaked at 764.2–764.7 MiB in 2.487–2.528 s. The fixed limit controls the heap policy without raising the RSS or timing budgets. + ## Alternatives considered - **Sanitized copies of real Sessions.** Rejected: benchmarks never use recorded user material. diff --git a/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.zh.md b/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.zh.md index f964d640b8..132619b19d 100644 --- a/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.zh.md +++ b/.agents/notes/implemented/testing/2026-09-28-session-corpus-performance.zh.md @@ -47,6 +47,8 @@ worker 是编译后的纯 Node 进程，每次都针对已播种根目录全新 此文件（包括播种）必须在标准托管 CI 上五分钟内完成，其最后一个用例断言该上限。1,000 个 Session 的搜索和最长 Session 的一次 fork 约占其中 170 s，因此两者各取一个样本。列表语料是剩余时间内能容纳的最大规模。预算约束列表启动、首次和重复的中位数，以及 fork 分层中位数和排名 990 的中位数；搜索和最长 fork 约束各自的单个样本。搜索和 fork 使用各自独立的 1,000 个 Session 根目录，因此 fork 子会话不会进入搜索索引。排名 988 是实测 p99（7,229 个事件）上最高的顶层排名；fork subagent 子会话会增加一次谱系查找，而排名 990 已落入 99.3% 锚点。列表、搜索和 fork 进程的峰值 RSS 设有预算，使用共享的 1.25 余量，不做时间缩放。每个子进程的截止时间等于文件上限，每个测试的截止时间长于其顺序子进程之和，因此失败的用例会在删除临时根目录之前回收所有子进程。 +Fork worker 使用 512 MiB 的 V8 old-space 上限，让各运行器在相同的堆约束下测量。语料、计时终点和整个进程的峰值 RSS 预算保持不变，原生缓冲区仍计入 RSS。最长 fork 回收后保留约 193 MiB，因此该上限为存活对象保留空间，同时避免较大的宿主默认堆延迟回收。该用例测量受限堆下的工作负载，不代表每种部署默认堆下的峰值。 + ## 校准证据 预算使用标准双 CPU 托管 CI 的期望值（Linux x64、Node 24.21、PR #5403），取高于 AMD EPYC 7763 与 EPYC 9V74 运行器中较高记录中位数的整数，再乘以共享的 1.25 余量。同一次运行内的样本差异最多 15%；两种运行器型号在单个端点上最多相差 25%。托管与参考机器的比值为 2.4 到 3.4，高于共享的参考缩放系数 2，因此按参考机器缩放会拒绝正常的托管运行。 @@ -67,6 +69,8 @@ worker 是编译后的纯 Node 进程，每次都针对已播种根目录全新 在 Apple M5 Pro 和 Node 26.5 上的隔离运行中，1,000 个 Session 的首次列表为 311–358 ms，5,000 个 Session 的首次列表为 1,364–1,603 ms，首次搜索为 57 s，fork 最长 Session 为 6.0–6.4 s。10,000 个 Session 的首次列表耗时 3.2–5.4 s，峰值 RSS 为 1.9 GB。 +未改动的最长 fork 工作负载在 Node 24.22 托管运行中，EPYC 9V74 的峰值 RSS 为 696 MiB，EPYC 7763 为 1,077.7 MiB，使用的预算均为 938 MiB。在 Apple M5 Pro、Node 24.19 上，两次默认堆运行回收后保留 192.8–193.4 MiB，峰值为 770.7–812.6 MiB，耗时 2.416–2.447 s；两次 512 MiB old-space 运行保留量相同，峰值为 764.2–764.7 MiB，耗时 2.487–2.528 s。固定上限用于控制堆策略，没有提高 RSS 或耗时预算。 + ## 考虑过的替代方案 - **脱敏复制真实 Session。** 已否决：基准从不使用录制的用户材料。 diff --git a/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.i18n.yaml b/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.i18n.yaml index 4d929aec54..0fa00ec1bf 100644 --- a/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.i18n.yaml @@ -21,11 +21,11 @@ en: f07bb6fbbdd01fe4 zh: 9313a0ef2a22af12 /agent-note-linear-credential-matching-and-performance-gates-for-user-text/decision/performance-gate: - en: fcc52be9892b2bfc - zh: ac259aba407efcbc + en: 37faaffb4662fd54 + zh: df0a4bf016393be9 /agent-note-linear-credential-matching-and-performance-gates-for-user-text/alternatives-considered: - en: 168bda1a4e9e0325 - zh: af9cf7b804db84b7 + en: 559a8037caa9e3aa + zh: 4f3719ed09445cc2 /agent-note-linear-credential-matching-and-performance-gates-for-user-text/consequences: en: 8f9d25b72d3e7660 zh: e5c6ae0194905876 diff --git a/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.md b/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.md index e4373eb7dc..c3c361047f 100644 --- a/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.md +++ b/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.md @@ -43,7 +43,7 @@ English | [中文](2026-10-11-user-text-credential-matching.zh.md) | Item | Content | |---|---| | Workloads | Without credentials: ordinary messages, and long prose, code, base64, Markdown, log, JSON, and shell text. With credentials: messages each carrying one kind (model key, GitHub token, cloud key ID, JWT, address password, private-key block), and batches of `.env` keys. Adversarial: repeated input shaped against each format's prefix, length, and separator rules, at two sizes. All generated from constants; credential samples are assembled at run time | -| Timing | Ten unmeasured pairs warm each workload with the same evaluation count as measured pairs. Five measured pairs alternate baseline-first and matcher-first order; each evaluation builds a fresh registry, document, and matcher instance and times evaluation only. A single-document sample averages twenty evaluations, or forty for the half-sized input of a scaling pair, so both sizes process the same total keys or characters per sample; a 5,000-message sample evaluates the batch once. Garbage collection during evaluation remains included. Each side selects its minimum sample mean, with the mean process CPU time from that sample. The worker JSON in CI logs includes every measured pair and averaging count; the HTML report shows the selected with-credential mean. Registry disposal completes outside the timer before the next evaluation, preventing cleanup and retained registries from accumulating. Warm-up retains no matcher memo | +| Timing | Ten unmeasured pairs warm each workload with the same evaluation count as measured pairs. Scaling inputs share one group: every warm-up and measured round evaluates both sizes adjacently and alternates which size goes first, limiting drift between sizes. Five measured pairs alternate baseline-first and matcher-first order; each evaluation builds a fresh registry, document, and matcher instance and times evaluation only. A single-document sample averages twenty evaluations, or forty for the half-sized input of a scaling pair, so both sizes process the same total keys or characters per sample; a 5,000-message sample evaluates the batch once. Garbage collection during evaluation remains included. Each side selects its minimum sample mean, with the mean process CPU time from that sample. The worker JSON in CI logs includes every measured pair and averaging count; the HTML report shows the selected with-credential mean. Registry disposal completes outside the timer before the next evaluation, preventing cleanup and retained registries from accumulating. Warm-up retains no matcher memo | | Allocation | A separate process with `--expose-gc` and a fixed semi-space larger than any evaluation; after warm-up and GC, the matcher alone answers every query once and the young-generation growth is taken; GC event timestamps confirm no GC ran inside the interval | | Assertions | Without credentials: absolute budgets and a cap on the with/without time ratio; with credentials: absolute budgets and the time ratio when the key count doubles; adversarial: absolute budgets and doubling ratios; allocation: a floor plus caps per credential, per line break inside masks, and per masked character | | Excluded | Cold code compilation, React rendering, browser paint and layout; allocation results are asserted and printed to the console, not added to the HTML report | @@ -54,6 +54,7 @@ The reference constants are calibrated for minima of five single evaluations. Mi ## Alternatives considered +- **Finishing one scaling size before measuring the other**: separate phases compare different load and V8 tiering conditions. Identical code measured JWT doubling at 1.91× in one CI run and 2.70× in another; a local Node 24 run also exceeded the unchanged 2.5× limit on a different input. Adjacent, alternating size rounds retain the existing sample counts, minimum-of-five aggregation, GC inclusion, workloads, and limits. A controlled extra evaluation cost on only the 128 KiB input must still fail the doubling assertion. - **Equal evaluation counts at both scaling sizes**: the larger input allocates twice as much per sample, so its fastest sample can include a collection while the smaller input's fastest sample includes none. Equal total input per sample makes the per-evaluation means compare similar allocation volumes without excluding GC or changing the doubling limit. - **Unwarmed, separate baseline and matcher batches**: sub-millisecond baseline measurements can reach optimized code before the matcher’s newly exercised paths do, and separate batches amplify clock-speed drift. Per-workload warm-up, adjacent pairs, and fixed batches compare warmed code while limiting noise in short intervals and preserving fresh documents and matcher state. - **One quantified pattern per format, run from every query**: patterns without a hit scan to the end of the text each time, so cost grows quadratically with credentials, and length quantifiers backtrack on failure. diff --git a/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.zh.md b/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.zh.md index f081970b1c..7541efa2de 100644 --- a/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.zh.md +++ b/.agents/notes/implemented/testing/2026-10-11-user-text-credential-matching.zh.md @@ -43,7 +43,7 @@ Status: implemented | 项 | 内容 | |---|---| | 负载 | 无凭据：普通消息，以及散文、代码、base64、Markdown、日志、JSON、shell 长文本。含凭据：每条消息含一种凭据（模型密钥、GitHub 令牌、云密钥 ID、JWT、地址密码、私钥块），以及成批的 `.env` 密钥。对抗：针对每种格式的前缀、长度与分隔规则构造的重复输入，两种长度。全部由常量生成，凭据样本运行时拼接 | -| 计时 | 每个负载先用十组未计入结果的配对预热，每组的求值次数与测量配对相同。五组测量交替以基线或凭据匹配器开头；每次求值新建注册表、文档和匹配器实例，只计求值。单文档样本取二十次求值的平均值；翻倍比较中的小输入取四十次，使两种大小的每个样本处理相同总量的密钥或字符；5,000 条消息的样本则整批求值一次。求值期间的垃圾回收仍计入耗时。两侧各取样本均值的最小值，并保留对应样本的平均进程 CPU 时间。CI 日志中的 worker JSON 包含全部测量配对和求平均值的次数，HTML 报告展示选中的带凭据匹配器均值。每次求值在计时结束后等待注册表清理完成，再开始下一次，避免清理工作和未释放注册表积累。预热不保留匹配器记忆 | +| 计时 | 每个负载先用十组未计入结果的配对预热，每组的求值次数与测量配对相同。翻倍比较的两个输入属于同一组：每轮预热和测量相邻求值两个尺寸，并交替先测的尺寸，减少尺寸之间的漂移。五组测量交替以基线或凭据匹配器开头；每次求值新建注册表、文档和匹配器实例，只计求值。单文档样本取二十次求值的平均值；翻倍比较中的小输入取四十次，使两种大小的每个样本处理相同总量的密钥或字符；5,000 条消息的样本则整批求值一次。求值期间的垃圾回收仍计入耗时。两侧各取样本均值的最小值，并保留对应样本的平均进程 CPU 时间。CI 日志中的 worker JSON 包含全部测量配对和求平均值的次数，HTML 报告展示选中的带凭据匹配器均值。每次求值在计时结束后等待注册表清理完成，再开始下一次，避免清理工作和未释放注册表积累。预热不保留匹配器记忆 | | 分配 | 单独进程，`--expose-gc`，semi-space 固定为大于任何一次求值的大小；预热后 GC，再单独驱动匹配器回答全部查询一遍，取新生代增量；用 GC 事件的时间戳确认区间内没有 GC | | 断言 | 无凭据：绝对预算，以及"有/无凭据匹配器"的耗时比上限；含凭据：绝对预算，密钥数翻倍时的耗时比；对抗：绝对预算与翻倍耗时比；分配：底噪加每个凭据、每个遮挡内换行和每个遮挡字符的上限 | | 排除 | 冷代码编译、React 渲染、浏览器绘制与布局；分配结果只用于断言并输出到控制台，不进 HTML 报告 | @@ -54,6 +54,7 @@ Status: implemented ## 考虑过的替代方案 +- **测完一个翻倍尺寸后再测另一个**：两个阶段比较的负载和 V8 编译层级状态不同。同一份代码的 JWT 翻倍比在两轮 CI 中分别为 1.91 倍和 2.70 倍；本地 Node 24 也在另一个输入上超过既有 2.5 倍上限。相邻、交替的尺寸轮次保留既有样本数、五组取最小值的汇总方式、GC 计入规则、负载与上限。仅给 128 KiB 输入增加受控求值开销时，翻倍断言仍须失败。 - **两种大小使用相同求值次数**：大输入每个样本的分配量翻倍，因而其最快样本可能包含一次垃圾回收，而小输入的最快样本没有。让每个样本的输入总量相等，使单次求值均值比较相近的分配量，无需排除垃圾回收或修改翻倍上限。 - **不预热、分批测量基线和匹配器**：亚毫秒基线测量可能先进入优化后的代码，而匹配器新触及的路径还未完成优化；分批测量也会放大时钟频率漂移。逐负载预热、相邻配对和固定批次比较预热后的代码，降低短区间测量的噪声，同时保持文档和匹配器状态全新。 - **每次查询对每个格式各跑一个带量词的正则**：没有命中的正则每次都扫到文末，凭据多时平方增长；长度量词在失败时回溯。 diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml index 380a20a91f..a541d181e6 100644 --- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml +++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml @@ -12,17 +12,17 @@ en: 34e5bde1535a2bb1 zh: 559deb25b2ec50ba /agent-note-domain-kv-storage-capability-seam-and-the-workspace-entity/proposal/dsh-storage-the-storage-hub: - en: 191afc01a150e4a0 - zh: da3fbc33875a4f60 + en: 5eb0b18c2adf5111 + zh: 856ee7b1464b8bfc /agent-note-domain-kv-storage-capability-seam-and-the-workspace-entity/proposal/dsh-storage-json: en: a18ec1e534a5488b zh: 2f5beb445e30554b /agent-note-domain-kv-storage-capability-seam-and-the-workspace-entity/proposal/dsh-storage-sqlite: - en: 6a26dd7ef357db74 - zh: 951b31136e2415f9 + en: 1a4bebbbf52db7a2 + zh: 425c32b0dc17b49e /agent-note-domain-kv-storage-capability-seam-and-the-workspace-entity/proposal/dsh-domain-the-domain-data-form: - en: 2ee24f36cd93f7dd - zh: 45c83bd745de41f9 + en: b99e07359dc78dc8 + zh: 4af881d0b6d5b628 /agent-note-domain-kv-storage-capability-seam-and-the-workspace-entity/proposal/future-work-session-side-deletion-design-settled-not-implemented-this-phase: en: a3824326587b6539 zh: 9736e3060bd57651 diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md index 950345b57f..0908177c71 100644 --- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md +++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md @@ -44,9 +44,9 @@ A backend is one **medium owner** (a file-tree root / one db file) exposing prim The backend contract (asserted clause by clause by the shared conformance suite, one suite for both backends): 1. `open` creates when the medium holds nothing (lazy materialization allowed: may defer to the first write, but `loadAll` must immediately serve empty tables); loads when the medium exists. -2. A stored version ≠ descriptor.version → `StorageError('version-mismatch')`; no migration, no rebuild. +2. Unit-wide checks accept `descriptor.version` and the owner's `compatibleVersions`; other stamps reject with `StorageError('version-mismatch')`. Ordinary compatible reads preserve saved stamps and values. [Domain versioning](../../../../docs/subsystems/storage.md#domain-versioning) defines write stamping and JSON per-record exceptions. 3. Durability: after a write primitive resolves, a process crash followed by a re-open must observe the write in `loadAll`. -4. The backend does not promise write ordering within a unit — **the caller serializes**; the backend only guarantees each single call is atomic (JSON whole-file replace / SQLite single statement). +4. The backend does not promise write ordering within a unit — **the caller serializes**; whole-unit mutations atomically publish their data and current stamp (JSON whole-file replacement / SQLite transaction for batch deletion or advancing the stamp); per-record batches can be partially applied if interrupted before resolution. 5. `deleteRecord` is idempotent; `putRecord` overwrites. 6. Any string key / any JSON value is safe (keys never reach file paths, a structural property). 7. `close` is idempotent; any operation after close → `StorageError('closed')`. @@ -88,8 +88,8 @@ CREATE TABLE IF NOT EXISTS "u__" ( key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT; -- value = record JSON document ``` -- Unit versions live in `units` rows; a descriptor mismatch → `version-mismatch`. Row granularity is document-per-row, preserving precise per-key durable updates (the path left open for high-frequency point-update tables like the session sidecar); when query needs appear, JSON1 reads the value column directly. -- Write primitives are single statements and thus atomic; no cross-statement transactions needed (the domain layer has no cross-table transactions, see the out-of-scope list). +- Unit versions live in `units` rows; an unaccepted version rejects with `version-mismatch`. Row granularity is document-per-row, preserving precise per-key durable updates (the path left open for high-frequency point-update tables like the session sidecar); when query needs appear, JSON1 reads the value column directly. +- Current-version single-record writes use single statements. Batch deletes and the first mutation of an accepted older unit use one transaction; the first mutation commits its data and current stamp together. This does not add cross-table domain transactions. ### `dsh-domain`: the domain data form @@ -117,6 +117,7 @@ export interface DomainTableSpec { readonly valueSchema: Zo export interface DomainSpec { readonly name: string // ^[a-z][a-z0-9_]*$ readonly version: number + readonly compatibleVersions?: readonly number[] readonly global?: DomainGlobalSpec readonly tables: Record> } @@ -157,8 +158,8 @@ Rules: - **Single-level mapping**: key → record, no nested tables; hierarchical needs use composite keys or fields inside the value. The two backends stay isomorphic as a result (one JSON object level ↔ one SQLite row). - **Records are plain data**: immutable, directly JSON-serializable POJOs; values returned by `get`/`entries` must not be mutated in place (TypeScript readonly projection, no runtime freezing). Behavior-carrying domain objects belong to consumer packages. -- **Serialized writes**: one promise chain per domain; `put`/`delete`/`update`/`global.set` all queue on it; `update`'s fn runs on the chain, so concurrency cannot interleave. No active-record (pulling out a mutable object that auto-persists — uncontrollable persist timing, in conflict with the whole-unit atomic-rewrite model). -- **Version fails loud**: a stored version differing from the spec throws outright; no migration, no rebuild (the data is not regenerable; pre-release rejects old formats). +- **Serialized writes**: one promise chain per domain; `put`/`delete`/`deleteMany`/`update`/`global.set` all queue on it; `update`'s fn runs on the chain, so concurrency cannot interleave. No active-record (pulling out a mutable object that auto-persists — uncontrollable persist timing, in conflict with the whole-unit atomic-rewrite model). +- **Version compatibility**: the domain owner declares readable older versions through `compatibleVersions` and decodes historical values with its current schemas. Storage does not convert record values; [domain versioning](../../../../docs/subsystems/storage.md#domain-versioning) defines stamp publication and mixed-generation requirements. - **Change events**: after each write's durability resolves, emit `domain/changed` (`@mode emit`), one per record, no old value (matching the repository's "new snapshot + operation discriminant" convention, template `goal/changed`); the payload `DomainChanged` is a put/deleted discriminated union — domain + table + key (both `''` for global changes) + operation, with the put branch carrying the new snapshot value and the deleted branch carrying none (`packages/storage/storage-domain/src/events.ts`). This is next phase's RPC push-frame event source. The error vocabulary is `DomainError`, codes: `already-open` / `facet-unsupported` / `invalid-record` (with `{ table, key }`) / `missing-key` / `closed`. ### Future work: session-side deletion (design settled, not implemented this phase) diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md index a44086a0d6..51dcc0362a 100644 --- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md +++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md @@ -44,9 +44,9 @@ host 侧唯一的持久化面是 session 事件日志（`packages/session/sessio 后端约定（共享约定测试逐条断言，两后端同套件）： 1. `open` 对不存在的介质创建（懒物化允许：可延迟到首写，但 `loadAll` 立即可用返回空表）；对已存在介质载入。 -2. 介质上版本 ≠ descriptor.version → `StorageError('version-mismatch')`，不迁移不重建。 +2. 单元级检查接受 `descriptor.version` 和拥有方声明的 `compatibleVersions`；其他版本戳以 `StorageError('version-mismatch')` 拒绝。普通兼容读取保留已存版本戳和值。[领域版本](../../../../docs/subsystems/storage.zh.md#domain-versioning)定义写入盖戳和 JSON 逐记录例外。 3. 持久性：写原语 resolve 后进程崩溃再 open，`loadAll` 必须反映该写入。 -4. 后端不承诺 unit 内写并发序——**调用方负责串行**；后端只保证单次调用原子（JSON 整文件替换 / SQLite 单语句）。 +4. 后端不承诺 unit 内写并发序——**调用方负责串行**；整单元修改原子发布其数据和当前版本戳（JSON 整文件替换 / SQLite 在批量删除或推进版本戳时使用事务）；逐记录批次在完成前中断时可能只应用一部分。 5. `deleteRecord` 幂等；`putRecord` 覆写。 6. 任意字符串 key / 任意 JSON 值安全（key 不进文件路径，结构性质）。 7. `close` 幂等；close 后任何操作 → `StorageError('closed')`。 @@ -88,8 +88,8 @@ CREATE TABLE IF NOT EXISTS "u__
" ( key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT; -- value = record JSON document ``` -- unit 版本存 `units` 行，descriptor 不符 → `version-mismatch`。行粒度 document-per-row，保住按 key 精确落盘更新（为 session sidecar 这类高频点更新大表留路）；查询需求出现时 JSON1 直查 value 列。 -- 写原语单语句即原子，无跨语句事务需求（domain 层无跨表事务，见不做清单）。 +- unit 版本存 `units` 行，未接受的版本以 `version-mismatch` 拒绝。行粒度 document-per-row，保住按 key 精确落盘更新（为 session sidecar 这类高频点更新大表留路）；查询需求出现时 JSON1 直查 value 列。 +- 当前版本的单记录写入使用单条语句。批量删除和对已接受旧单元的首次修改使用一个事务；首次修改一同提交数据和当前版本戳。这不增加跨表领域事务。 ### `dsh-domain`：领域数据形式 @@ -117,6 +117,7 @@ export interface DomainTableSpec { readonly valueSchema: Zo export interface DomainSpec { readonly name: string // ^[a-z][a-z0-9_]*$ readonly version: number + readonly compatibleVersions?: readonly number[] readonly global?: DomainGlobalSpec readonly tables: Record> } @@ -157,8 +158,8 @@ export interface KvTable { - **一级 mapping**：key → 记录，不做嵌套表；层级需求用复合 key 或值内字段。两后端因此同构（JSON object 一层 ↔ SQLite 一行）。 - **记录是纯数据**：可直接 JSON 序列化的不可变 POJO；`get`/`entries` 返回值不得原地改（TypeScript readonly 投影，不做运行时冻结）。带行为的领域对象属于消费方包。 -- **写串行**：域内一条 promise 链，`put`/`delete`/`update`/`global.set` 全排队；`update` 的 fn 在链上执行，并发不交错。不做 active-record（取出可变对象自动落盘——落盘时机不可控，与整域原子覆写冲突）。 -- **版本 fail loud**：盘上版本与 spec 不符直接报错，不迁移不重建（数据不可再生，pre-release 拒绝旧格式）。 +- **写串行**：域内一条 promise 链，`put`/`delete`/`deleteMany`/`update`/`global.set` 全排队；`update` 的 fn 在链上执行，并发不交错。不做 active-record（取出可变对象自动落盘——落盘时机不可控，与整域原子覆写冲突）。 +- **版本兼容**：领域拥有方通过 `compatibleVersions` 声明可读的旧版本，并用当前 schema 解码历史值。Storage 不转换记录值；[领域版本](../../../../docs/subsystems/storage.zh.md#domain-versioning)定义版本戳发布和混合代际要求。 - **变更事件**：每次写落盘 resolve 后 emit `domain/changed`（`@mode emit`），逐条发、不带旧值（对齐仓库"新快照 + 操作判别"惯例，范本 `goal/changed`）；payload `DomainChanged` 是 put/deleted 判别联合——域名 + 表名 + key（global 变更两者为 `''`）+ operation，put 支带新快照 value、deleted 支无 value（`packages/storage/storage-domain/src/events.ts`）。此为下期 RPC 推帧的事件源。错误词汇 `DomainError`，码表：`already-open` / `facet-unsupported` / `invalid-record`（带 `{ table, key }`）/ `missing-key` / `closed`。 ### Future work：session 侧删除（设计定案，本期不实施） diff --git a/.agents/skills/dsh-client-ui-ux/SKILL.md b/.agents/skills/dsh-client-ui-ux/SKILL.md index 6d293a5f86..0b8b72de99 100644 --- a/.agents/skills/dsh-client-ui-ux/SKILL.md +++ b/.agents/skills/dsh-client-ui-ux/SKILL.md @@ -67,6 +67,10 @@ Use [dsh-responsive-ui](../dsh-responsive-ui/SKILL.md) for responsive layouts, m - Review every changed region for gaps: nothing sits flush against its neighbour without an intentional gap, and adjacent icons and elements keep the region's established spacing. - Prefer symmetry for parallel elements; an unexplained one-off gap or offset usually signals a missed shared value. +- **For complex pages and containers, establish shared horizontal and vertical alignment axes before adjusting local spacing.** Consider hover, selected, and expanded/collapsed states, as well as the overall relationship with adjacent panels and other page elements. Choose from the following references according to layout similarity: + - **Sidebar:** align corresponding text starts and leading icons across vertically stacked rows. Align hover and selected row backgrounds with the buttons above the list to maintain visual balance. + - **Plugins page:** keep content left-aligned along a shared edge. List-row hover backgrounds may extend beyond that edge while the content stays in place. + - **Conversation and right-sidebar headers:** align the first header rows across both panels and match their heights. Apply the same rule to the second rows, and align corresponding underlines and dividers on shared horizontal baselines. ## Design review escalation diff --git a/.agents/skills/dsh-session-projection/SKILL.md b/.agents/skills/dsh-session-projection/SKILL.md index 90d483f4ac..f2820d7454 100644 --- a/.agents/skills/dsh-session-projection/SKILL.md +++ b/.agents/skills/dsh-session-projection/SKILL.md @@ -13,6 +13,8 @@ Keep recoverable session facts in Projection and expose them through their ownin 2. Do not expose projection definitions or handles as production read APIs. Keep the ready handle private; consumers use the owning service's domain methods. A handle is a process-local reader, recreated during activation. Require `sessionProjections` when the service depends on it; optional registration is only for optional contributions. Do not hide a missing required dependency with another recovery path. + A runtime that needs several projected states receives one typed object of callbacks created with `handle.readerFor(session)`. Add properties instead of a constructor parameter or feature-specific reader for each state. Each callback has type `() => S`; single-purpose collaborators receive it directly. These host-state readers are separate from wire snapshots and live Cordis Context; they own no registration, disposal, cache or I/O. Registration, Session preparation and handle lifetimes stay with their owners. Rule 9 defines synchronous API compatibility. + 3. State recovery through `init` and `apply` is synchronous and deterministic. Do not perform I/O or trigger Cordis hooks, models, or tools. Runtime hooks own those effects. Replay must not repeat them. Return the same state reference for unrelated events. Keep views synchronous and preserve their references when visible values do not change. 4. Persist JSON state that its schema accepts. Follow the README's state-version and checkpoint-watermark rules. Restoring a checkpoint and replaying its suffix must match full replay. Change the version when state fields or recovery semantics change. diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md index a16f8294e9..1fa60fcb4f 100644 --- a/.agents/skills/record-browser-gif/SKILL.md +++ b/.agents/skills/record-browser-gif/SKILL.md @@ -1,6 +1,6 @@ --- name: record-browser-gif -description: Record browser or Web UI interaction demos as optimized GIFs using the available browser-control workflow, optional Playwright Videos for higher capture frame rates, and deterministic encoding, then attach the GIF to a pull request with `gh --attach`, falling back to a dedicated assets branch where attach cannot apply. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include a GIF recorded from the pull request's real server and model flow. +description: Record browser or Web UI interaction demos as optimized GIFs using the available browser-control workflow, optional Playwright Videos for higher capture frame rates, and deterministic encoding, then attach the GIF to a pull request with `gh --attach`; publication requires gh v2.99.0 or later, and a GIF over 5 MiB is split into parts. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include a GIF recorded from the pull request's real server and model flow. --- # Record Browser GIF @@ -17,8 +17,8 @@ The recording itself is part of the evidence: use a real server booted from that ## Keep recording separate from publication -- Recording produces local video or screenshots and one `.gif` artifact only; it never mutates remote state. -- Publication — attaching the GIF to a pull request body with `gh --attach`, or pushing it to an assets branch and embedding its URL where attach cannot apply — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch. +- Recording produces local video or screenshots; encoding produces one `.gif` artifact, or its [numbered parts](#attach-with-gh) when it exceeds the 5 MiB limit. Neither mutates remote state. +- Publication — attaching the GIF to a pull request body with `gh --attach` — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never commits to any branch. - Preserve the requested recording conditions. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture. - Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt. @@ -117,13 +117,15 @@ Encoder maintenance: run `python3 -m unittest discover -s "$GIF_SKILL_DIR/script Perform this step only when the task includes attaching the GIF to a pull request. -Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. Prefer `gh --attach`, which uploads the GIF to GitHub and rewrites the body reference in one command, so no branch carries the media. +Never commit a GIF to the pull request's own branch or any other branch: every default clone and full-history fetch of the repository downloads media committed to any branch. Publish only with `gh --attach`, which uploads the GIF to GitHub and rewrites the body reference in one command, so no branch carries the media. ### Attach with gh -`gh --attach` requires `gh` v2.99.0 or later (`gh --version`), a repository on github.com — GitHub Enterprise Server is not supported — write access to the repository, and a GIF at or below 10 MB. Confirm the verified artifact fits that limit; when it does not, shrink it with `--max-width`, then `--colors` or `--fps`, before attaching. +Before attaching, check `gh --version`. `gh --attach` requires `gh` v2.99.0 or later, a repository on github.com — GitHub Enterprise Server is not supported — and write access to the repository. When `gh` is older than v2.99.0, stop and tell the developer to upgrade `gh` to v2.99.0 or later; keep the verified GIF for the retry, and do not install or upgrade `gh` without authorization. When any other requirement is unmet or the attach fails — authentication, write access, a repository outside github.com, or an upload error — stop and report it to the developer. Never publish the GIF any other way. -Write the GIF into the body file as an ordinary local-path reference, using the same path passed to `--attach`; `gh` rewrites the reference in place to the uploaded URL, keeping its position and alt text: +Publish GIFs at or below 5 MiB, the encoder's default `--max-bytes`. When the encoder rejects the output for size, shrink it with `--max-width`, then `--colors` or `--fps`. When the GIF still exceeds 5 MiB at readable text quality, split it instead: encode consecutive, non-overlapping intervals of the same evidence run into numbered parts that each pass the encoder's size check — `--start` and `--end` over the one video, or consecutive screenshot subsets selected with `--pattern` — and verify every part as an artifact. Beside each embed, state its position (such as `2/3`) and its source interval or frames. + +Write each GIF into the body file as an ordinary local-path reference, using the same path passed to `--attach`; `gh` rewrites each reference in place to its uploaded URL, keeping its position and alt text, so the order of references in the body sets the display order of split parts: ```markdown ![]() @@ -138,35 +140,8 @@ gh pr create --body-file --attach # new pull re gh pr edit --body-file --attach # existing pull request ``` -`--attach` is repeatable but refuses the same file twice. A GIF the body does not reference is appended at the end, where alt text set on the flag (`--attach '#'`) applies; a rewritten reference keeps the body's alt text. After attaching, re-read the demonstrated live head and require it to remain at that recorded commit. Re-read the live body and confirm the reference now points at the uploaded URL, render the body through GitHub's Markdown API and confirm the expected ``, and fetch the uploaded URL once to confirm `200` and `image/gif`. +`--attach` is repeatable but refuses the same file twice. Publish split parts in one `gh pr create` or `gh pr edit` with one `--attach` per part, so a single pair of live-head checks covers every part. A GIF the body does not reference is appended at the end, where alt text set on the flag (`--attach '#'`) applies; a rewritten reference keeps the body's alt text. After attaching, re-read the demonstrated live head and require it to remain at that recorded commit. Re-read the live body and confirm the reference now points at the uploaded URL, render the body through GitHub's Markdown API and confirm the expected ``, and fetch the uploaded URL once to confirm `200` and `image/gif`. -### Fall back to an assets branch +### Existing assets branches -Use the assets-branch workflow only when `gh --attach` cannot apply: the GIF still exceeds 10 MB, `gh` is older than v2.99.0, or the repository is not on github.com. GIFs then live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (named `-assets`; list existing ones with `git ls-remote --heads origin '*assets*'`). - -Before either workflow below pushes, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact. - -For an existing assets branch, work in a shallow single-branch scratch clone so the publication cannot touch your working tree: - -```sh -git clone --branch --single-branch --depth 1 /tmp/assets-checkout -cp /absolute/path/to/demo.gif /tmp/assets-checkout/.gif -cd /tmp/assets-checkout -git add .gif -git commit -m "assets: gif (#)" -git push origin -``` - -For a new series, make a fresh shallow scratch clone (`git clone --depth 1 /tmp/assets-checkout`), create the orphan branch with `git switch --orphan `, then add the GIF, commit, and push the same way. - -After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability. - -Immediately before editing the pull-request body, re-read the demonstrated pull request's live head and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. After the edit, re-read the demonstrated live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `` is present. - -Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image: - -```markdown -![](https://github.com///blob//.gif?raw=true) -``` - -Never delete or rewrite an assets branch, and never force-push it: merged pull request bodies reference its URLs forever. Append new commits only. +Earlier pull request bodies embed GIFs from orphan `*-assets` branches in this repository. Never add to, delete, rewrite, or force-push them: merged pull request bodies reference their URLs. diff --git a/.gitattributes b/.gitattributes index e878c9db19..2bead994d2 100644 --- a/.gitattributes +++ b/.gitattributes @@ -13,3 +13,6 @@ docs/persistence-schema.json linguist-generated=true docs/persistence-changes/*.schema.json linguist-generated=true docs/persistence-changes/releases/*.schema.json linguist-generated=true docs/persistence-changes/historical-formats/*.schema.json linguist-generated=true + +# Unified patch blank context lines require their leading space. +patches/*.patch whitespace=-blank-at-eol diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 35f0103169..bde3142e27 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -4,4 +4,6 @@ Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. Native Win The manual [Windows packaging workflow](workflows/windows-package.yml) uses the dedicated self-hosted Windows x64 label `dsh-win-package-trial` under native `pwsh`; preserve this routing separately from the automatic CI lanes. +The merge checks run from three workflows named `Policy`, which run on `pull_request_target` so their definitions come from master, and call the `deepseek-harness-check` action directly: `pr-check-on-head-branch.yml` on pull-request updates gives `Policy / Master Change` and `Policy / Pre-Merge Check`, `pr-check-after-approve.yml` on pull-request updates and submitted or dismissed reviews gives `Policy / Approve Check` and `Policy / Reviewer Evaluate`, and `pr-check-on-base-branch.yml` on master pushes re-runs the head-branch checks as `Policy / Recheck`. Branch rules require those check names, so keep the job names and the workflow name. Each check reads its mode from a repository variable: `MERGE_POLICY_MASTER_DIFF`, `MERGE_POLICY_PRE_MERGE`, `MERGE_POLICY_HEAD_DIFF`, and `MERGE_POLICY_REVIEW`, each `off` (skip), `report` (run without failing the job), or `block` (fail the job); a missing value or an unknown one counts as `report`. `Policy / Pre-Merge Check` merges the commit `Policy / Master Change` reports, so it runs only after that job and stays off while `MERGE_POLICY_MASTER_DIFF` is `off`; a merge it cannot do and a build that fails both follow its own mode, so `report` warns and skips the build while `block` fails the job. `Policy / Pre-Merge Check` runs `scripts/pre-merge-check.ts` under plain Node and knows nothing else about the merged tree: that script checks the released manifests against the root version, installs, and builds the Host and Client contracts, so change it in one pull request together with the build it orchestrates. + The manual Desktop publication workflow selects a successful package run and attempt, then routes each retained build through `DESKTOP_PUBLISH_RUNNERS` to its original machine's unique label. Keep Windows run steps on native PowerShell and Mac run steps on the default POSIX shell; shared entrypoints are Node scripts. Test and production jobs use separate `desktop-test` and `desktop-production` approval Environments after a credential-free preparation job. diff --git a/.github/workflows/build-exe-for-python-sdk.yml b/.github/workflows/build-exe-for-python-sdk.yml index 6bcdbee5ac..35f5a33df1 100644 --- a/.github/workflows/build-exe-for-python-sdk.yml +++ b/.github/workflows/build-exe-for-python-sdk.yml @@ -337,7 +337,8 @@ jobs: smoke_python="$venv/bin/python" "$smoke_python" -m pip install \ "dist-python/$SDK_WHEEL" \ - "dist-python/$RUNTIME_WHEEL" + "dist-python/$RUNTIME_WHEEL" \ + 'pytest>=8.0' echo "python=$smoke_python" >> "$GITHUB_OUTPUT" - name: Install local SDK and runtime wheels into a clean venv (Windows) @@ -351,7 +352,7 @@ jobs: $venv = (& python -c 'import tempfile; print(tempfile.mkdtemp(prefix="dsh-sdk-smoke-"))').Trim() python -m venv $venv $smokePython = Join-Path $venv 'Scripts\python.exe' - & $smokePython -m pip install "dist-python/$env:SDK_WHEEL" "dist-python/$env:RUNTIME_WHEEL" + & $smokePython -m pip install "dist-python/$env:SDK_WHEEL" "dist-python/$env:RUNTIME_WHEEL" 'pytest>=8.0' if ($LASTEXITCODE -ne 0) { throw "Wheel installation failed with exit code $LASTEXITCODE" } "python=$smokePython" >> $env:GITHUB_OUTPUT @@ -382,6 +383,19 @@ jobs: Pop-Location } + - name: Run installed-wheel native command tests (POSIX) + if: runner.os != 'Windows' + run: >- + "${{ steps.smoke-venv-posix.outputs.python }}" -I + "$GITHUB_WORKSPACE/python/sdk/tests/run_installed_commands.py" + + - name: Run installed-wheel native command tests (Windows) + if: runner.os == 'Windows' + shell: pwsh + run: | + & "${{ steps.smoke-venv-windows.outputs.python }}" -I "$env:GITHUB_WORKSPACE\python\sdk\tests\run_installed_commands.py" + if ($LASTEXITCODE -ne 0) { throw "Installed-wheel native command tests failed with exit code $LASTEXITCODE" } + - name: Preflight installed-wheel real API test (POSIX) if: >- inputs.ci diff --git a/.github/workflows/ci-master.yml b/.github/workflows/ci-master.yml index 5620e6af63..d69a860098 100644 --- a/.github/workflows/ci-master.yml +++ b/.github/workflows/ci-master.yml @@ -14,6 +14,7 @@ on: - larger-runner-benchmark - consolidated-runner-benchmark - ssh-helper + - wine # New master pushes and manual runs replace obsolete checks in this workflow/ref. # Standby drills share cancellation; use completed runs as readiness evidence. @@ -49,9 +50,9 @@ jobs: secrets: DEEPSEEK_API_KEY_EXTERNAL: ${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }} - # Wine runs once here, independently of the native serial standby aggregates. + # Wine runs on master pushes or an explicit suite=wine dispatch, independently of native standbys. windows: - if: github.event_name == 'push' && github.ref == 'refs/heads/master' + if: (github.event_name == 'push' && github.ref == 'refs/heads/master') || (github.event_name == 'workflow_dispatch' && inputs.suite == 'wine') runs-on: ubuntu-latest name: windows node 24 / wine timeout-minutes: 15 diff --git a/.github/workflows/cua-helper-package.yml b/.github/workflows/cua-helper-package.yml new file mode 100644 index 0000000000..20ecb7526f --- /dev/null +++ b/.github/workflows/cua-helper-package.yml @@ -0,0 +1,83 @@ +name: Package CUA helper · macOS + +on: + workflow_dispatch: + inputs: + source_ref: + description: '同仓库可信源码分支或 dsh-v* tag' + type: string + default: master + required: true + preset: + description: '机器上的签名配置' + type: choice + options: [test, production] + default: test + required: true + workflow_call: + inputs: + source_ref: + type: string + required: true + preset: + type: string + default: production + outputs: + artifact: + description: '包含两个架构的已签名、公证 helper 归档' + value: ${{ jobs.package.outputs.artifact }} + +permissions: + contents: read + +# Desktop uses the same keychain search list and optional system proxy transaction. +concurrency: + group: macos-desktop-package + cancel-in-progress: false + +jobs: + package: + runs-on: [self-hosted, macOS, ARM64, dsh-mac-package-trial] + timeout-minutes: 60 + outputs: + artifact: ${{ steps.artifact.outputs.name }} + env: + DSH_PACKAGING_PRESET: ${{ inputs.preset }} + DSH_TELEMETRY_DISABLED: '1' + PACKAGE_SOURCE_REF: ${{ inputs.source_ref }} + steps: + - uses: actions/checkout@v7.0.1 + with: + ref: ${{ inputs.source_ref }} + persist-credentials: false + clean: true + - name: Validate source selection + run: | + node -e 'const cp=require("node:child_process"); const fs=require("node:fs"); const ref=process.env.PACKAGE_SOURCE_REF; + if(ref.startsWith("refs/pull/") || /^[a-f0-9]{40}$/i.test(ref)) throw Error("Select a trusted repository branch or release tag"); + const tag=ref.replace(/^refs\/tags\//, ""); + if(tag.startsWith("dsh-v") && tag!=="dsh-v"+JSON.parse(fs.readFileSync("package.json","utf8")).version) throw Error("Release tag must match product version"); + if(!["test","production"].includes(process.env.DSH_PACKAGING_PRESET)) throw Error("Invalid preset");' + - uses: pnpm/action-setup@v5.0.0 + with: + dest: ${{ runner.temp }}/setup-pnpm-cua-${{ github.run_id }}-${{ github.run_attempt }} + - uses: actions/setup-node@v7.0.0 + with: + node-version: '24' + package-manager-cache: false + - name: Install locked dependencies + run: pnpm install --frozen-lockfile + - name: Build and verify notarized applications + run: | + mkdir -p dist + pnpm exec tsx scripts/cua-helper/package.ts --out dist/cua-helper + - name: Name retained artifact + id: artifact + run: echo "name=cua-helper-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT" + - uses: actions/upload-artifact@v7.0.1 + with: + name: ${{ steps.artifact.outputs.name }} + path: dist/cua-helper/* + if-no-files-found: error + compression-level: 0 + retention-days: 14 diff --git a/.github/workflows/macos-intel-package.yml b/.github/workflows/macos-intel-package.yml new file mode 100644 index 0000000000..cc835b8933 --- /dev/null +++ b/.github/workflows/macos-intel-package.yml @@ -0,0 +1,161 @@ +name: Package Desktop · macOS · Intel + +on: + workflow_dispatch: + inputs: + source_ref: + description: '打包源码：test 支持仓库内分支或 dsh-v* tag；production 仅支持 master 或 dsh-v* tag；源码须包含 CI 适配脚本' + type: string + default: master + required: true + preset: + description: '打包环境：选择机器上的 test 或 production 配置；同时决定后续发布环境' + type: choice + options: [test, production] + default: test + required: true + update_channel: + description: '升级通道：nightly 或 latest（须为稳定版本）；自动更新不会切换通道' + type: choice + options: [nightly, latest] + default: nightly + required: true + version_mode: + description: '版本模式：default 为 test 自动编号、production 跟随产品；product 保留原版本，auto 自动编号，manual 手填' + type: choice + options: [default, product, auto, manual] + default: default + required: true + build_version: + description: '手动版本号：仅 manual 时填写完整版本；须为产品原版本或受支持的预发布后缀' + type: string + default: '' + required: false + test_release_id: + description: '测试 release ID：32 位小写十六进制随机前缀（非鉴权）；留空使用机器默认值，连续升级测试须保持相同值' + type: string + default: '' + required: false + compression_level: + description: 'ZIP 压缩等级：只影响 ZIP 和自动升级下载，不影响 DMG；3 打包较快，7 压缩更强' + type: choice + options: ['3', '7'] + default: '3' + required: true + skip_notarization: + description: '跳过公证和 stapling：仅限内部调试，禁止发布到 test / production 或用于自动更新；需要发布请勿勾选' + type: boolean + default: false + required: true + +permissions: + contents: read + +concurrency: + group: macos-desktop-package + cancel-in-progress: false + +jobs: + package: + runs-on: [self-hosted, macOS, ARM64, dsh-mac-package-trial] + timeout-minutes: 180 + defaults: + run: + shell: bash + env: + DSH_DESKTOP_TARGET_PLATFORM: darwin + DSH_DESKTOP_TARGET_ARCH: x64 + PACKAGE_MACOS_ZIP_COMPRESSION_LEVEL: ${{ inputs.compression_level }} + PACKAGE_SKIP_NOTARIZATION: ${{ inputs.skip_notarization }} + PACKAGE_SOURCE_REF: ${{ inputs.source_ref }} + PACKAGE_VERSION_MODE: ${{ inputs.version_mode }} + DSH_DESKTOP_UPDATE_CHANNEL: ${{ inputs.update_channel }} + DSH_TELEMETRY_DISABLED: '1' + DSH_PACKAGING_PRESET: ${{ inputs.preset }} + PACKAGE_TEST_RELEASE_ID: ${{ inputs.test_release_id }} + steps: + - uses: actions/checkout@v7.0.1 + id: checkout + with: + persist-credentials: false + clean: true + ref: ${{ inputs.source_ref }} + - name: Validate selected source and adapter support + run: >- + node -e "const fs=require('node:fs'); const ref=process.env.PACKAGE_SOURCE_REF; + const cp=require('node:child_process'); const preset=process.env.DSH_PACKAGING_PRESET; + if(!['test','production'].includes(preset)) throw Error('Unknown packaging preset'); + const tag=/^dsh-v[0-9][0-9A-Za-z.-]*$/.test(ref); + if(preset==='production' && ref!=='master' && !tag) throw Error('Production source must be master or dsh-v*'); + if(tag) { + const v=JSON.parse(fs.readFileSync('package.json','utf8')).version; + if(ref!=='dsh-v'+v) throw Error('Source tag must match product version'); + const tagged=cp.execFileSync('git',['rev-parse','--verify','refs/tags/'+ref+'^{commit}'],{encoding:'utf8'}).trim(); + const head=cp.execFileSync('git',['rev-parse','HEAD'],{encoding:'utf8'}).trim(); + if(tagged!==head) throw Error('Checkout does not match source tag'); + } else { + const branch=cp.execFileSync('git',['rev-parse','--abbrev-ref','HEAD'],{encoding:'utf8'}).trim(); + if(branch==='HEAD' || branch!==ref || ref.startsWith('refs/')) throw Error('Select a branch in this repository, not a SHA or PR ref'); + } + if(!fs.readFileSync('apps/desktop/scripts/prepare-macos-ci.mjs','utf8').includes('resolveDesktopBuildTarget')) throw Error('Source lacks Intel macOS CI support; select a newer source'); + if(!fs.readFileSync('apps/desktop/scripts/desktop-ci-version.mjs','utf8').includes('PACKAGE_VERSION_MODE')) throw Error('Source lacks Desktop channel/version CI support; select a newer release');" + - uses: pnpm/action-setup@v5.0.0 + with: + dest: ${{ runner.temp }}/setup-pnpm-${{ github.run_id }}-${{ github.run_attempt }} + - uses: actions/setup-node@v7.0.0 + with: + node-version: '24' + - name: Configure persistent package caches + env: + DSH_DESKTOP_PACKAGE_CACHE_DIR: ${{ runner.tool_cache }}/dsh-desktop-package-cache + run: | + echo "DSH_DESKTOP_PACKAGE_CACHE_DIR=$DSH_DESKTOP_PACKAGE_CACHE_DIR" >> "$GITHUB_ENV" + echo "PNPM_CONFIG_STORE_DIR=$DSH_DESKTOP_PACKAGE_CACHE_DIR/workspace-pnpm-store" >> "$GITHUB_ENV" + - name: Check Rosetta execution + run: arch -x86_64 /usr/bin/true + - name: Install locked dependencies + run: pnpm install --frozen-lockfile + - name: Validate preset and resolve build version + id: settings + env: + PACKAGE_BUILD_VERSION: ${{ inputs.build_version }} + run: node apps/desktop/scripts/prepare-macos-ci.mjs + - name: Check packaging configuration and toolchain + env: + PACKAGE_VERSION: ${{ steps.settings.outputs.version }} + run: | + args=() + if [[ "$PACKAGE_SKIP_NOTARIZATION" = true ]]; then args+=(--skip-notarization); fi + pnpm run package:desktop:mac:x64 --check --build-version "$PACKAGE_VERSION" "${args[@]}" + - name: Build signed installers + env: + PACKAGE_VERSION: ${{ steps.settings.outputs.version }} + run: | + args=() + if [[ "$PACKAGE_SKIP_NOTARIZATION" = true ]]; then args+=(--skip-notarization); fi + pnpm run package:desktop:mac:x64 --build-version "$PACKAGE_VERSION" "${args[@]}" + - name: Retain complete package outside the checkout + id: retained + env: + PACKAGE_SOURCE_SHA: ${{ steps.checkout.outputs.commit }} + PACKAGE_VERSION: ${{ steps.settings.outputs.version }} + run: node --import tsx apps/desktop/scripts/retain-desktop-ci.ts + - name: Retain packaging diagnostics + if: always() && steps.checkout.outcome == 'success' + uses: actions/upload-artifact@v7.0.1 + with: + name: macos-x64-package-logs-${{ github.run_id }}-${{ github.run_attempt }} + include-hidden-files: true + path: apps/desktop/.desktop-build/packaging-runs/ + if-no-files-found: warn + retention-days: 14 + - name: Retain installers for the selected mode + if: success() + uses: actions/upload-artifact@v7.0.1 + with: + name: macos-x64-${{ steps.settings.outputs.mode }}-${{ steps.settings.outputs.version }}-${{ github.run_id }}-${{ github.run_attempt }} + include-hidden-files: true + path: ${{ steps.retained.outputs.directory }}/* + compression-level: 0 + if-no-files-found: error + retention-days: 14 diff --git a/.github/workflows/macos-package.yml b/.github/workflows/macos-package.yml index eeb451266e..073f1e9541 100644 --- a/.github/workflows/macos-package.yml +++ b/.github/workflows/macos-package.yml @@ -1,35 +1,19 @@ -name: Package Desktop · macOS +name: Package Desktop · macOS · Apple Silicon on: workflow_dispatch: inputs: + source_ref: + description: '打包源码：test 支持仓库内分支或 dsh-v* tag；production 仅支持 master 或 dsh-v* tag；源码须包含 CI 适配脚本' + type: string + default: master + required: true preset: description: '打包环境：选择机器上的 test 或 production 配置；同时决定后续发布环境' type: choice options: [test, production] default: test required: true - zip_compression_level: - description: 'ZIP 压缩等级：只影响 ZIP 和自动升级下载，不影响 DMG；3 打包较快，7 压缩更强' - type: choice - options: ['3', '7'] - default: '3' - required: true - skip_notarization: - description: '跳过公证和 stapling：仅限内部调试，禁止发布到 test / production 或用于自动更新；需要发布请勿勾选' - type: boolean - default: false - required: true - test_release_id: - description: '测试 release ID：32 位小写十六进制随机前缀（非鉴权）；留空使用机器默认值，连续升级测试须保持相同值' - type: string - default: '' - required: false - source_ref: - description: '打包源码：test 支持仓库内分支或 dsh-v* tag；production 仅支持 master 或 dsh-v* tag；源码须包含 CI 适配脚本' - type: string - default: master - required: true update_channel: description: '升级通道：nightly 或 latest（须为稳定版本）；自动更新不会切换通道' type: choice @@ -47,6 +31,22 @@ on: type: string default: '' required: false + test_release_id: + description: '测试 release ID：32 位小写十六进制随机前缀（非鉴权）；留空使用机器默认值，连续升级测试须保持相同值' + type: string + default: '' + required: false + compression_level: + description: 'ZIP 压缩等级：只影响 ZIP 和自动升级下载，不影响 DMG；3 打包较快，7 压缩更强' + type: choice + options: ['3', '7'] + default: '3' + required: true + skip_notarization: + description: '跳过公证和 stapling：仅限内部调试，禁止发布到 test / production 或用于自动更新；需要发布请勿勾选' + type: boolean + default: false + required: true permissions: contents: read @@ -63,7 +63,9 @@ jobs: run: shell: bash env: - PACKAGE_MACOS_ZIP_COMPRESSION_LEVEL: ${{ inputs.zip_compression_level }} + DSH_DESKTOP_TARGET_PLATFORM: darwin + DSH_DESKTOP_TARGET_ARCH: arm64 + PACKAGE_MACOS_ZIP_COMPRESSION_LEVEL: ${{ inputs.compression_level }} PACKAGE_SKIP_NOTARIZATION: ${{ inputs.skip_notarization }} PACKAGE_SOURCE_REF: ${{ inputs.source_ref }} PACKAGE_VERSION_MODE: ${{ inputs.version_mode }} diff --git a/.github/workflows/pr-check-after-approve.yml b/.github/workflows/pr-check-after-approve.yml new file mode 100644 index 0000000000..1255ae9373 --- /dev/null +++ b/.github/workflows/pr-check-after-approve.yml @@ -0,0 +1,94 @@ +name: Policy +on: + pull_request_target: + branches: [master] + types: [opened, synchronize, reopened, ready_for_review] + pull_request_review: + types: [submitted, dismissed] +permissions: + contents: read + pull-requests: read +concurrency: + group: pr-check-after-approve-${{ github.event.pull_request.number }} + cancel-in-progress: true +jobs: + approve: + name: Approve Check + # Each check runs only while its repository variable is neither empty nor `off`; otherwise the job is skipped. + if: ${{ vars.MERGE_POLICY_HEAD_DIFF != '' && vars.MERGE_POLICY_HEAD_DIFF != 'off' }} + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + pull-requests: read + steps: + # The head checkout is only the Git repository the check fetches into; it needs no files and runs no code. + - uses: actions/checkout@v7.0.1 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 1 + filter: blob:none + sparse-checkout: README.md + sparse-checkout-cone-mode: false + + - uses: actions/setup-node@v7.0.0 + with: + node-version: '24' + package-manager-cache: false + + - uses: deepseek-harness/deepseek-harness-check@master + env: + CHECK_MODE: ${{ vars.MERGE_POLICY_HEAD_DIFF }} + with: + check: head-diff + base-branch: ${{ github.event.pull_request.base.ref }} + head-sha: ${{ github.event.pull_request.head.sha }} + pr-number: ${{ github.event.pull_request.number }} + pr-author: ${{ github.event.pull_request.user.login }} + + review: + name: Reviewer Evaluate + if: ${{ vars.MERGE_POLICY_REVIEW != '' && vars.MERGE_POLICY_REVIEW != 'off' }} + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + pull-requests: read + # The check posts its verdict as a check run of its own. + checks: write + steps: + # The head checkout is only the Git repository the check fetches into; it needs no files and runs no code. + - uses: actions/checkout@v7.0.1 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 1 + filter: blob:none + sparse-checkout: README.md + sparse-checkout-cone-mode: false + + - uses: actions/setup-node@v7.0.0 + with: + node-version: '24' + package-manager-cache: false + + # The check app's token makes the review check run its own row instead of joining this workflow's suite. + - id: token + continue-on-error: true + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 + with: + client-id: ${{ vars.DSH_APPROVAL_APP_CLIENT_ID }} + private-key: ${{ secrets.DSH_APPROVAL_APP_PRIVATE_KEY }} + owner: deepseek-harness + repositories: deepseek-harness + permission-checks: write + + - uses: deepseek-harness/deepseek-harness-check@master + env: + CHECK_MODE: ${{ vars.MERGE_POLICY_REVIEW }} + CHECK_TOKEN: ${{ steps.token.outputs.token }} + with: + check: review + base-branch: ${{ github.event.pull_request.base.ref }} + head-sha: ${{ github.event.pull_request.head.sha }} + pr-number: ${{ github.event.pull_request.number }} + pr-author: ${{ github.event.pull_request.user.login }} diff --git a/.github/workflows/pr-check-on-base-branch.yml b/.github/workflows/pr-check-on-base-branch.yml new file mode 100644 index 0000000000..32d4d46165 --- /dev/null +++ b/.github/workflows/pr-check-on-base-branch.yml @@ -0,0 +1,30 @@ +name: Policy +on: + push: + branches: [master] + workflow_dispatch: +permissions: {} +concurrency: + group: pr-check-on-base-branch-${{ github.ref_name }} +jobs: + recheck: + name: Recheck + # Re-runs the head-branch checks, so it follows their variables. + if: ${{ vars.MERGE_POLICY_MASTER_DIFF != '' && vars.MERGE_POLICY_MASTER_DIFF != 'off' || vars.MERGE_POLICY_PRE_MERGE != '' && vars.MERGE_POLICY_PRE_MERGE != 'off' }} + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + actions: write + contents: read + pull-requests: read + steps: + - uses: actions/setup-node@v7.0.0 + with: + node-version: '24' + package-manager-cache: false + + - uses: deepseek-harness/deepseek-harness-check@master + with: + check: recheck + base-branch: ${{ github.ref_name }} + recheck-label-token: ${{ secrets.DSH_RECHECK_LABEL_TOKEN }} diff --git a/.github/workflows/pr-check-on-head-branch.yml b/.github/workflows/pr-check-on-head-branch.yml new file mode 100644 index 0000000000..adb884d62c --- /dev/null +++ b/.github/workflows/pr-check-on-head-branch.yml @@ -0,0 +1,129 @@ +name: Policy +on: + pull_request_target: + branches: [master] + types: [opened, synchronize, reopened, ready_for_review, review_requested, auto_merge_enabled, labeled] +permissions: + contents: read +concurrency: + group: pr-check-on-head-branch-${{ github.event.pull_request.number }} + cancel-in-progress: true +jobs: + master: + name: Master Change + # Each check runs only while its repository variable is neither empty nor `off`; otherwise the job is skipped. + if: ${{ vars.MERGE_POLICY_MASTER_DIFF != '' && vars.MERGE_POLICY_MASTER_DIFF != 'off' && !github.event.pull_request.draft }} + runs-on: ubuntu-latest + timeout-minutes: 15 + outputs: + base_sha: ${{ steps.check.outputs.base_sha }} + since: ${{ steps.check.outputs.since }} + steps: + # The head checkout is only the Git repository the check fetches into; it needs no files and runs no code. + - uses: actions/checkout@v7.0.1 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 1 + filter: blob:none + sparse-checkout: README.md + sparse-checkout-cone-mode: false + + - uses: actions/setup-node@v7.0.0 + with: + node-version: '24' + package-manager-cache: false + + - id: check + uses: deepseek-harness/deepseek-harness-check@master + env: + CHECK_MODE: ${{ vars.MERGE_POLICY_MASTER_DIFF }} + with: + check: master-diff + base-branch: ${{ github.event.pull_request.base.ref }} + head-sha: ${{ github.event.pull_request.head.sha }} + + pre-merge: + name: Pre-Merge Check + needs: master + if: ${{ vars.MERGE_POLICY_PRE_MERGE != '' && vars.MERGE_POLICY_PRE_MERGE != 'off' && needs.master.result == 'success' }} + runs-on: blacksmith-4vcpu-ubuntu-2404 + timeout-minutes: 60 + # This job installs and compiles the pull request: it reads contents only and receives no secret. + permissions: + contents: read + steps: + - uses: actions/checkout@v7.0.1 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 1 + + # Merging is the precondition of the build below, so a failure here warns and skips it in `report` mode and fails + # in `block` mode. + - id: merge + name: Merge the checked base-branch commit + env: + CHECK_MODE: ${{ vars.MERGE_POLICY_PRE_MERGE }} + BASE_SHA: ${{ needs.master.outputs.base_sha }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + SINCE: ${{ needs.master.outputs.since }} + run: | + stop() { + if [ "$CHECK_MODE" = block ]; then + echo "::error title=Pre-Merge Check::$1" + exit 1 + fi + echo "::warning title=Pre-Merge Check::$1" + exit 0 + } + if [[ ! "$BASE_SHA" =~ ^[0-9a-f]{40}$ || ! "$SINCE" =~ ^[0-9]+$ ]]; then + stop "the master diff check reported no base commit, so nothing was merged or compiled" + fi + # A shallow fetch starts a background maintenance run that rewrites .git/shallow, and the second shallow fetch + # below then fails with "shallow file has changed since we read it". + fetch() { + git -c maintenance.auto=false -c gc.auto=0 fetch --no-tags --no-write-fetch-head "$@" origin "$HEAD_SHA" "$BASE_SHA" + } + fetch --shallow-since="$SINCE" || + stop "the base commit $BASE_SHA could not be fetched, so nothing was merged or compiled" + # A time window records a merge commit itself as shallow when one of its parents predates the window, which + # drops the other, in-window parent too; a depth bound keeps both parents of every commit it covers. + if ! git merge-base "$HEAD_SHA" "$BASE_SHA" >/dev/null; then + fetch --depth=20 --filter=blob:none || + stop "the base commit $BASE_SHA could not be fetched, so nothing was merged or compiled" + fi + git -c user.name=pr-check -c user.email=pr-check@users.noreply.github.com merge --no-ff --no-edit -m "Merge $BASE_SHA into $HEAD_SHA" "$BASE_SHA" || + stop "the pull request cannot merge $BASE_SHA; merge master into it and push, then this check runs again" + echo "merged=true" >> "$GITHUB_OUTPUT" + + - uses: pnpm/action-setup@v5.0.0 + if: steps.merge.outputs.merged == 'true' + + - uses: actions/setup-node@v7.0.0 + if: steps.merge.outputs.merged == 'true' + with: + node-version: '24' + package-manager-cache: false + + - name: Run the tree's pre-merge check + if: steps.merge.outputs.merged == 'true' + env: + CHECK_MODE: ${{ vars.MERGE_POLICY_PRE_MERGE }} + run: | + # The check names one file and knows nothing else about how the merged tree builds itself. + if [ ! -f scripts/pre-merge-check.ts ]; then + if [ "$CHECK_MODE" = block ]; then + echo "::error title=Pre-Merge Check::this tree has no scripts/pre-merge-check.ts, so nothing was installed, compiled, or checked" + exit 1 + fi + echo "::warning title=Pre-Merge Check::this tree has no scripts/pre-merge-check.ts, so nothing was installed, compiled, or checked" + exit 0 + fi + if node scripts/pre-merge-check.ts; then + exit 0 + fi + # A check that crashes reports nothing, so the step reports its exit the way the mode asks. + if [ "$CHECK_MODE" = block ]; then + echo "::error title=Pre-Merge Check::scripts/pre-merge-check.ts exited without reporting, so the merged tree is unchecked" + exit 1 + fi + echo "::warning title=Pre-Merge Check::scripts/pre-merge-check.ts exited without reporting, so the merged tree is unchecked" diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml index ec03a117de..eb7e3a5eef 100644 --- a/.github/workflows/release-publish.yml +++ b/.github/workflows/release-publish.yml @@ -1,12 +1,28 @@ # Publish the dsh release sequence to npm. This workflow is manual-only # (workflow_dispatch) and intentionally does not listen to pull_request or push: -# publication must always be an explicit, reviewed act from a dsh-v* tag, and it -# must never appear as a PR check. It repacks the current tree before publishing +# publication is an explicit, reviewed act; dsh-v* tag validation is enabled by +# default and may be skipped through the dispatch input. It never appears as a PR check. It repacks the current tree before publishing # so the bytes uploaded are exactly what this dispatch produced. name: Release publish (dsh) on: workflow_dispatch: + inputs: + cua_run_id: + description: '已有 CUA 打包 run ID：留空重新打包；填写时复用同一源码和版本的已验证产物' + type: string + required: false + default: '' + cua_run_attempt: + description: 'CUA 打包 attempt：仅与 run ID 一起使用；留空选择最新一次，不回退到更早的成功构建' + type: string + required: false + default: '' + skip-tag-check: + description: Skip release tag validation for the selected ref; other publication checks still apply. + type: boolean + required: false + default: false permissions: contents: read @@ -16,9 +32,23 @@ env: DSH_TELEMETRY_DISABLED: '1' jobs: + cua-helper: + if: (startsWith(github.ref, 'refs/tags/dsh-v') || inputs.skip-tag-check) && inputs.cua_run_id == '' && inputs.cua_run_attempt == '' + uses: ./.github/workflows/cua-helper-package.yml + with: + source_ref: ${{ github.ref }} + preset: production + pack: name: Pack npm tarballs + needs: cua-helper + if: >- + ${{ !cancelled() && (needs.cua-helper.result == 'success' + || (needs.cua-helper.result == 'skipped' && (inputs.cua_run_id != '' || inputs.cua_run_attempt != ''))) }} runs-on: ubuntu-24.04 + permissions: + contents: read + actions: read steps: # Complete history: the release scripts read tags. - uses: actions/checkout@v7.0.1 @@ -55,10 +85,50 @@ jobs: - name: Verify release version env: RELEASE_PUBLISH: 'true' - run: pnpm run release:verify --family dsh + run: pnpm run release:verify --family dsh ${{ inputs.skip-tag-check && '--skip-tag-check' || '' }} + + - name: Select retained CUA helper + if: inputs.cua_run_id != '' || inputs.cua_run_attempt != '' + id: retained-cua + env: + GH_TOKEN: ${{ github.token }} + run: pnpm exec tsx scripts/cua-helper/select-artifact.ts + + - name: Download retained CUA helper + if: inputs.cua_run_id != '' || inputs.cua_run_attempt != '' + uses: actions/download-artifact@v8.0.1 + with: + artifact-ids: ${{ steps.retained-cua.outputs.artifact-id }} + run-id: ${{ inputs.cua_run_id }} + github-token: ${{ github.token }} + path: dist/cua-helper - name: Build - run: pnpm run build:official + run: pnpm run build:official --serial + + - name: Download freshly built CUA helper + if: inputs.cua_run_id == '' && inputs.cua_run_attempt == '' + uses: actions/download-artifact@v8.0.1 + with: + name: ${{ needs.cua-helper.outputs.artifact }} + path: dist/cua-helper + + - name: Stage verified native helper applications + run: | + mkdir dist/cua-helper/extracted + tar -xzf dist/cua-helper/cua-helper.tgz -C dist/cua-helper/extracted + pnpm exec tsx scripts/cua-helper/stage.ts --from dist/cua-helper/extracted + + - name: Record CUA source and publication retry instructions + env: + CUA_RUN_ID: ${{ inputs.cua_run_id || github.run_id }} + CUA_RUN_ATTEMPT: ${{ steps.retained-cua.outputs.attempt || github.run_attempt }} + run: | + { + printf 'CUA helper: run `%s`, attempt `%s`.\n\n' "$CUA_RUN_ID" "$CUA_RUN_ATTEMPT" + printf '%s\n\n' 'npm 部分发布失败时，只重跑 Publish to npm job，复用原 dsh-npm-tarballs；不要重跑全部 job。' + printf '若需新建发布运行，填写 `cua_run_id=%s`、`cua_run_attempt=%s`，并使用相同源码 commit 和版本。\n' "$CUA_RUN_ID" "$CUA_RUN_ATTEMPT" + } >> "$GITHUB_STEP_SUMMARY" - name: Pack release tarballs run: pnpm run release:pack --family dsh --out dist/npm diff --git a/.github/workflows/windows-package.yml b/.github/workflows/windows-package.yml index c38fd7d5a0..29229605de 100644 --- a/.github/workflows/windows-package.yml +++ b/.github/workflows/windows-package.yml @@ -1,30 +1,19 @@ -name: Package Desktop · Windows +name: Package Desktop · Windows · x64 on: workflow_dispatch: inputs: + source_ref: + description: '打包源码：test 支持仓库内分支或 dsh-v* tag；production 仅支持 master 或 dsh-v* tag；源码须包含 CI 适配脚本' + type: string + default: master + required: true preset: description: '打包环境：选择机器上的 test 或 production 配置；同时决定后续发布环境' type: choice options: [test, production] default: test required: true - signing: - description: '签名方式：unsigned 仅限内部调试，禁止发布到 test / production 或用于自动更新；需要发布请选择 signed（EV 硬件令牌）' - type: choice - options: [signed, unsigned] - default: signed - required: true - test_release_id: - description: '测试 release ID：32 位小写十六进制随机前缀（非鉴权）；留空使用机器默认值，连续升级测试须保持相同值' - type: string - default: '' - required: false - source_ref: - description: '打包源码：test 支持仓库内分支或 dsh-v* tag；production 仅支持 master 或 dsh-v* tag；源码须包含 CI 适配脚本' - type: string - default: master - required: true update_channel: description: '升级通道：nightly 或 latest（须为稳定版本）；自动更新不会切换通道' type: choice @@ -42,13 +31,8 @@ on: type: string default: '' required: false - cache_namespace: - description: '缓存测量命名空间：留空使用共享缓存；新名称用于冷缓存，再次使用同名测热缓存，不清除现有缓存' - type: string - default: '' - required: false - build_root: - description: '独立构建根目录：填写绝对路径，每次任务创建独立源码副本；留空使用 runner 工作区' + test_release_id: + description: '测试 release ID：32 位小写十六进制随机前缀（非鉴权）；留空使用机器默认值，连续升级测试须保持相同值' type: string default: '' required: false @@ -58,6 +42,17 @@ on: options: ['3', '7'] default: '3' required: true + signing: + description: '签名方式：unsigned 仅限内部调试，禁止发布到 test / production 或用于自动更新；需要发布请选择 signed（EV 硬件令牌）' + type: choice + options: [signed, unsigned] + default: signed + required: true + cache_namespace: + description: '缓存测量命名空间：留空使用共享缓存；新名称用于冷缓存，再次使用同名测热缓存，不清除现有缓存' + type: string + default: '' + required: false permissions: contents: read @@ -82,7 +77,6 @@ jobs: PACKAGE_TEST_RELEASE_ID: ${{ inputs.test_release_id }} PACKAGE_SIGNING: ${{ inputs.signing }} PACKAGE_CACHE_NAMESPACE: ${{ inputs.cache_namespace }} - PACKAGE_BUILD_ROOT: ${{ inputs.build_root }} PACKAGE_WINDOWS_COMPRESSION_LEVEL: ${{ inputs.compression_level }} steps: - name: Reset packaging checkout @@ -106,7 +100,7 @@ jobs: run: | $helpers = Join-Path $env:RUNNER_TEMP "packaging-helpers-$env:GITHUB_RUN_ID-$env:GITHUB_RUN_ATTEMPT" New-Item -ItemType Directory -Path $helpers -ErrorAction Stop | Out-Null - foreach ($name in @('windows-packaging-priority.ps1', 'windows-build-workspace.mjs')) { + foreach ($name in @('windows-packaging-priority.ps1')) { Copy-Item -LiteralPath (Join-Path 'apps/desktop/scripts' $name) -Destination $helpers -ErrorAction Stop } "PACKAGE_CI_HELPERS=$helpers" >> $env:GITHUB_ENV @@ -140,17 +134,6 @@ jobs: - uses: actions/setup-node@v7.0.0 with: node-version: '24' - - name: Select packaging workspace - id: build_workspace - env: - PACKAGE_SOURCE_SHA: ${{ steps.checkout.outputs.commit }} - run: | - if (!$env:PACKAGE_BUILD_ROOT) { - "directory=$env:GITHUB_WORKSPACE" >> $env:GITHUB_OUTPUT - } else { - node "$env:PACKAGE_CI_HELPERS/windows-build-workspace.mjs" - exit $LASTEXITCODE - } - name: Configure persistent pnpm store # PNPM_HOME belongs to this run; keep downloaded packages outside its temporary directory. env: @@ -167,7 +150,6 @@ jobs: "DSH_DESKTOP_PACKAGE_CACHE_DIR=$env:DSH_DESKTOP_PACKAGE_CACHE_DIR" >> $env:GITHUB_ENV "PNPM_CONFIG_STORE_DIR=$storeRoot" >> $env:GITHUB_ENV - name: Install locked dependencies - working-directory: ${{ steps.build_workspace.outputs.directory }} run: | & "$env:PACKAGE_CI_HELPERS/windows-packaging-priority.ps1" -BestEffort node -e "const os=require('node:os'); console.log(JSON.stringify({node:process.version,availableParallelism:os.availableParallelism(),logicalCpus:os.cpus().length,totalMemoryBytes:os.totalmem(),freeMemoryBytes:os.freemem()}))" @@ -178,12 +160,10 @@ jobs: exit $LASTEXITCODE - name: Validate preset and resolve build version id: settings - working-directory: ${{ steps.build_workspace.outputs.directory }} env: PACKAGE_BUILD_VERSION: ${{ inputs.build_version }} run: node apps/desktop/scripts/prepare-windows-ci.mjs - name: Check packaging configuration and toolchain - working-directory: ${{ steps.build_workspace.outputs.directory }} env: PACKAGE_VERSION: ${{ steps.settings.outputs.version }} run: | @@ -192,23 +172,16 @@ jobs: pnpm @packageArgs exit $LASTEXITCODE - name: Build installer and verify packaged runtime - working-directory: ${{ steps.build_workspace.outputs.directory }} env: PACKAGE_VERSION: ${{ steps.settings.outputs.version }} - PACKAGE_BUILD_TEMP: ${{ steps.build_workspace.outputs.temporaryDirectory }} run: | & "$env:PACKAGE_CI_HELPERS/windows-packaging-priority.ps1" -BestEffort - if ($env:PACKAGE_BUILD_TEMP) { - $env:TEMP = $env:PACKAGE_BUILD_TEMP - $env:TMP = $env:PACKAGE_BUILD_TEMP - } $packageArgs = @('run', 'package:desktop:win:x64', '--build-version', $env:PACKAGE_VERSION) if ($env:PACKAGE_SIGNING -eq 'unsigned') { $packageArgs += '--unsigned' } pnpm @packageArgs exit $LASTEXITCODE - name: Retain complete package outside the checkout id: retained - working-directory: ${{ steps.build_workspace.outputs.directory }} env: PACKAGE_SOURCE_SHA: ${{ steps.checkout.outputs.commit }} PACKAGE_VERSION: ${{ steps.settings.outputs.version }} @@ -219,7 +192,7 @@ jobs: with: name: windows-package-logs-${{ github.run_id }}-${{ github.run_attempt }} include-hidden-files: true - path: ${{ steps.build_workspace.outputs.directory || github.workspace }}/apps/desktop/.desktop-build/packaging-runs/ + path: ${{ github.workspace }}/apps/desktop/.desktop-build/packaging-runs/ if-no-files-found: warn retention-days: 14 - name: Retain verified unsigned installer @@ -242,8 +215,3 @@ jobs: path: ${{ steps.retained.outputs.directory }}/* if-no-files-found: error retention-days: 14 - - name: Remove isolated packaging workspace - if: success() && inputs.build_root != '' - env: - PACKAGE_SOURCE_SHA: ${{ steps.checkout.outputs.commit }} - run: node "$env:PACKAGE_CI_HELPERS/windows-build-workspace.mjs" --remove diff --git a/.gitignore b/.gitignore index 3cb86ce87d..4d52487a06 100644 --- a/.gitignore +++ b/.gitignore @@ -47,3 +47,6 @@ worktrees/ .agents/worktrees/ .typert-*/ native/system/test/bin/ + +# Generated company-signed CUA release record. +/packages/experimental/cua-macos/cua-helper.json diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 34f5886c04..a1a13b2200 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -75,6 +75,7 @@ External packages installed for runtime use or embedded in distributed Host or b | [`@xterm/xterm`](https://github.com/xtermjs/xterm.js) | MIT | | [`@yarnpkg/parsers`](https://github.com/yarnpkg/berry) | BSD-2-Clause | | [`acorn`](https://github.com/acornjs/acorn) | MIT | +| [`acorn-walk`](https://github.com/acornjs/acorn) | MIT | | [`ajv`](https://github.com/ajv-validator/ajv) | MIT | | [`anser`](https://github.com/IonicaBizau/anser) | MIT | | [`big.js`](https://github.com/MikeMcl/big.js) | MIT | @@ -133,6 +134,7 @@ External packages installed for runtime use or embedded in distributed Host or b | [`semver`](https://github.com/npm/node-semver) | ISC | | [`serve-static`](https://github.com/expressjs/serve-static) | MIT | | [`sharp`](https://github.com/lovell/sharp) | Apache-2.0 | +| [`shell-quote`](http://github.com/ljharb/shell-quote) | MIT | | [`sherpa-onnx-node`](https://github.com/csukuangfj/sherpa-onnx) | Apache-2.0 | | [`shiki`](https://github.com/shikijs/shiki) | MIT | | [`simple-icons`](https://github.com/simple-icons/simple-icons) | CC0-1.0 | @@ -162,6 +164,8 @@ pnpm applies local patches to the following packages at install time, so shipped - `app-builder-lib@26.17.0` — [`patches/app-builder-lib@26.17.0.patch`](patches/app-builder-lib@26.17.0.patch) - `exceljs@4.4.0` — [`patches/exceljs@4.4.0.patch`](patches/exceljs@4.4.0.patch) - `lexical@0.49.0` — [`patches/lexical@0.49.0.patch`](patches/lexical@0.49.0.patch) +- `mdast-util-gfm-autolink-literal@2.0.1` — [`patches/mdast-util-gfm-autolink-literal@2.0.1.patch`](patches/mdast-util-gfm-autolink-literal@2.0.1.patch) +- `micromark-extension-gfm-autolink-literal@2.1.0` — [`patches/micromark-extension-gfm-autolink-literal@2.1.0.patch`](patches/micromark-extension-gfm-autolink-literal@2.1.0.patch) - `node-pty@1.2.0-beta.15` — [`patches/node-pty@1.2.0-beta.15.patch`](patches/node-pty@1.2.0-beta.15.patch) ## Chrome DevTools frontend @@ -266,6 +270,7 @@ External packages **directly declared** for development, tests, types, or toolin | [`selfsigned`](https://github.com/jfromaniello/selfsigned) | MIT | | [`smol-toml`](https://github.com/squirrelchat/smol-toml) | BSD-3-Clause | | [`spdx-expression-parse`](https://github.com/jslicense/spdx-expression-parse.js) | MIT | +| [`tencentcloud-sdk-nodejs-teo`](https://github.com/tencentcloud/tencentcloud-sdk-nodejs) | Apache-2.0 | | [`tsdown`](https://github.com/rolldown/tsdown) | MIT | | [`typescript-language-server`](https://github.com/typescript-language-server/typescript-language-server) | Apache-2.0 | | [`vite`](https://github.com/vitejs/vite) | MIT | diff --git a/apps/cli/package.json b/apps/cli/package.json index 6c58839839..a2ef697f64 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh", "description": "dsh CLI: profile launch, plugin management, and configuration inspection", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -105,11 +105,12 @@ "@deepseek-ai/dsh-experimental-ralph-bundle": "workspace:*", "@deepseek-ai/dsh-experimental-session-titles-bundle": "workspace:*", "@deepseek-ai/dsh-experimental-terminal-bundle": "workspace:*", + "@deepseek-ai/dsh-experimental-liveshare": "workspace:*", "@deepseek-ai/dsh-experimental-session-search": "workspace:*", "@deepseek-ai/dsh-experimental-tool-worktree": "workspace:*", - "@deepseek-ai/dsh-cua-bundle": "workspace:*", "@deepseek-ai/dsh-experimental-plugin-market-bundle": "workspace:*", - "@deepseek-ai/dsh-personalized-recommendations": "workspace:*" + "@deepseek-ai/dsh-personalized-recommendations": "workspace:*", + "@deepseek-ai/dsh-experimental-forge-bundle": "workspace:*" }, "devDependencies": { "@deepseek-ai/dsh-skill-badge": "workspace:*", diff --git a/apps/cli/tests/desktop-host.e2e.ts b/apps/cli/tests/desktop-host.e2e.ts index 615270aae0..c1f42d812d 100644 --- a/apps/cli/tests/desktop-host.e2e.ts +++ b/apps/cli/tests/desktop-host.e2e.ts @@ -29,6 +29,7 @@ it.each([false, true])('settles startup after parent IPC disconnect (boot failur writeFileSync(join(root, 'package.json'), '{"type":"module"}') writeFileSync(join(modules, 'dsh-app-boot', 'package.json'), '{"type":"module","exports":"./index.js"}') writeFileSync(join(modules, 'dsh-app-boot', 'index.js'), ` + export class StartupError extends Error {} export const loadProfileDirectory = () => ({ skippedBundles: [] }); export const reportSkippedBundles = () => {}; export const loadLayeredEnv = () => ({}); @@ -64,7 +65,11 @@ it.each([false, true])('settles startup after parent IPC disconnect (boot failur const boot = await new Promise<{ packageManager: { command: string; args: string[]; env: Record } }>((resolve, reject) => { - child.once('message', resolve) + child.on('message', (message) => { + if (typeof message === 'object' && message !== null && 'type' in message && message.type === 'booting' && 'packageManager' in message) { + resolve(message as { packageManager: { command: string; args: string[]; env: Record } }) + } + }) child.once('error', reject) child.once('exit', (code) => { reject(new Error(`Host exited before booting: ${String(code)} ${stderr}`)) }) }) diff --git a/apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts b/apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts new file mode 100644 index 0000000000..480ffe2032 --- /dev/null +++ b/apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts @@ -0,0 +1,162 @@ +/** + * Keyless comparison of actual SDK and Desktop/Web step-admitted tool sets. + * Keep intentional differences in tool-parity.ts; unused exceptions fail. + * Team mode is excluded while its known composition mismatch is tracked in #7172. + * SDK minimal, Creator-only tools, graphical context and optional runtime payloads + * are outside this fixed standard/PTC, top-level-session comparison. + */ +import { createServer } from 'node:http' +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { execa } from 'execa' +import { z } from 'zod' +import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client' +import { expect, it, type TestContext } from 'vitest' +import { profileEnvironment } from './fixtures/profile-environment.ts' +import { messagesResponse } from './fixtures/messages-response.ts' +import { assertToolParity, type ToolMode } from './tool-parity.ts' + +const repo = fileURLToPath(new URL('../../../../../', import.meta.url)) +const observer = new URL('./fixtures/tool-parity.mjs', import.meta.url).href +const probe = new URL('./fixtures/parity-probe.mjs', import.meta.url).href +const inventorySchema = z.object({ names: z.array(z.string()).min(1), hmr: z.boolean() }) +type Inventory = z.infer + +async function fixture(test: TestContext) { + const root = await mkdtemp(join(tmpdir(), 'sdk-desktop-tools-')) + const requests: { tools: { name: string }[] }[] = [] + const server = createServer((request, response) => { + let body = '' + request.setEncoding('utf8') + request.on('data', (chunk: string) => { body += chunk }) + request.on('end', () => { + requests.push(JSON.parse(body) as { tools: { name: string }[] }) + response.writeHead(200, { 'content-type': 'text/event-stream' }) + response.end(messagesResponse({ type: 'text', text: 'tools inspected' }, 'end_turn')) + }) + }) + test.onTestFinished(async () => { + try { + await new Promise((resolve, reject) => server.close((error) => { + if (error === undefined) resolve() + else reject(error) + })) + } + finally { await rm(root, { recursive: true, force: true }) } + }) + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)) + const address = server.address() + if (address === null || typeof address === 'string') throw new Error('model fixture has no TCP address') + const env = profileEnvironment(root, `http://127.0.0.1:${address.port}`) + + async function collect(side: 'sdk' | 'desktop', mode: ToolMode, mutations: object[] = []): Promise { + const cwd = await mkdtemp(join(root, `${side}-${mode}-`)) + const output = join(cwd, 'tools.json') + const patch = join(cwd, 'observer.patch.yml') + await writeFile(patch, JSON.stringify([ + { id: 'session-title-llm', disabled: true }, + { insert: [{ id: 'tool-parity-observer', name: observer, + config: { output, cwd, ...(side === 'desktop' ? { preset: mode } : {}) } }] }, + ...mutations, + ])) + const before = requests.length + let inventory: Inventory + if (side === 'sdk') { + const harness = new DeepSeekHarness({ + cwd, processCwd: cwd, dshHome: join(cwd, 'home'), env, model: 'deepseek-v4-pro', + patches: [...mode === 'ptc' ? [join(repo, 'apps/cli/config/examples/ptc.yml')] : [], patch], + }) + const abort = (): void => { void harness.close() } + test.signal.addEventListener('abort', abort, { once: true }) + try { + const result = await harness.session('tool-parity').run('Inspect tools') + expect(result.finalResponse).toBe('tools inspected') + inventory = inventorySchema.parse(JSON.parse(await readFile(output, 'utf8'))) + } finally { + await harness.close() + test.signal.removeEventListener('abort', abort) + } + expect(inventory.hmr).toBe(false) + } else { + const child = execa(process.execPath, [join(repo, 'apps/cli/lib/bin.js'), '--profile', 'web', + '--patch', patch, '--host', '127.0.0.1', '--port', '0', '--no-open'], { + cwd, env: { ...env, DSH_HOME: join(cwd, 'home') }, extendEnv: false, + ipc: true, stdin: 'ignore', reject: false, cancelSignal: test.signal, forceKillAfterDelay: 10_000, + }) + let stdout = '' + let stderr = '' + const ready = Promise.withResolvers() + child.stdout.on('data', (chunk: Buffer) => { + stdout += chunk.toString() + if (stdout.includes('dsh web: http://')) ready.resolve(true) + }) + child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() }) + void child.then((result) => { ready.reject(new Error(`Web exited: ${result.exitCode}\n${stderr}`)) }) + try { + await ready.promise + const reply = child.getOneMessage() + await child.sendMessage('collect-tool-parity') + const message = z.object({ result: inventorySchema.optional(), error: z.string().optional() }).parse(await reply) + if (message.error !== undefined) throw new Error(message.error) + inventory = inventorySchema.parse(message.result) + } catch (error) { + throw new Error(`Web collection failed\n${stdout}\n${stderr}`, { cause: error }) + } finally { + // Ask the CLI to drain on Windows too, where an OS signal kills immediately. + const watchdog = setTimeout(() => { child.kill('SIGKILL') }, 10_000) + try { + try { await child.sendMessage('stop-tool-parity') } + catch (_closedChannel: unknown) { + // A closed IPC channel cannot request graceful shutdown; fall back to the OS signal. + child.kill('SIGTERM') + } + const result = await child + expect(result.exitCode, result.stderr).toBe(0) + expect(result.signal, result.stderr).toBeUndefined() + } finally { clearTimeout(watchdog) } + } + expect(inventory.hmr).toBe(true) + } + expect(requests.length).toBeGreaterThan(before) + const presented = requests[before]!.tools.map(tool => tool.name).sort() + if (mode === 'ptc') expect(presented).toEqual(['run_code']) + else expect(presented).toEqual(inventory.names) + return inventory + } + return collect +} + +it.for(['standard', 'ptc'] as const)('compares the shipped %s tool sets and permits explicit opt-out', async (mode, test) => { + const collect = await fixture(test) + const sdk = await collect('sdk', mode) + const desktop = await collect('desktop', mode) + assertToolParity(mode, sdk.names, desktop.names) + expect(sdk.names).toContain('plugin_manager') + const optOut = await collect('sdk', mode, [{ id: 'tool-plugin-manager', disabled: true }]) + expect(optOut.names).not.toContain('plugin_manager') + expect(() => { assertToolParity(mode, optOut.names, desktop.names) }).toThrow( + mode === 'ptc' ? 'Stale exceptions: sdk:plugin_manager' : 'Missing from SDK: plugin_manager') +}) + +it.for(['standard', 'ptc'] as const)('detects missing shared tools in %s', async (mode, test) => { + const collect = await fixture(test) + const desktop = await collect('desktop', mode) + for (const [id, tool] of [['present', 'present'], ['tool-ask-user', 'ask_user_question'], ['tool-schedule', 'schedule_create']]) { + const missing = await collect('sdk', mode, [{ id, disabled: true }]) + expect(() => { assertToolParity(mode, missing.names, desktop.names) }).toThrow(new RegExp(`Missing from SDK:.*${tool}`)) + } +}) + +it.for(['standard', 'ptc'] as const)('detects one-sided additions in %s', async (mode, test) => { + const collect = await fixture(test) + const sdk = await collect('sdk', mode) + const desktop = await collect('desktop', mode) + const addition = [{ insert: [{ id: 'parity-probe', name: probe }] }] + const desktopExtra = await collect('desktop', mode, addition) + expect(() => { assertToolParity(mode, sdk.names, desktopExtra.names) }).toThrow('Missing from SDK: parity_probe') + const sdkExtra = await collect('sdk', mode, addition) + expect(() => { assertToolParity(mode, sdkExtra.names, desktop.names) }).toThrow('Only in SDK: parity_probe') + assertToolParity(mode, sdkExtra.names, desktopExtra.names) +}) diff --git a/apps/cli/tests/profiles/sdk/fixtures/parity-probe.mjs b/apps/cli/tests/profiles/sdk/fixtures/parity-probe.mjs new file mode 100644 index 0000000000..03596ae9bc --- /dev/null +++ b/apps/cli/tests/profiles/sdk/fixtures/parity-probe.mjs @@ -0,0 +1,12 @@ +/** A real extra registration used to detect one-sided profile additions. */ +import { defineTool } from '@deepseek-ai/dsh-tools' + +export const inject = ['tools'] + +export function apply(ctx) { + ctx.tools.register(defineTool({ + name: 'parity_probe', description: 'Test profile addition.', parameters: {}, + output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] }, + async execute() { return 'probe' }, + })) +} diff --git a/apps/cli/tests/profiles/sdk/fixtures/profile-environment.ts b/apps/cli/tests/profiles/sdk/fixtures/profile-environment.ts new file mode 100644 index 0000000000..c520b3c0ff --- /dev/null +++ b/apps/cli/tests/profiles/sdk/fixtures/profile-environment.ts @@ -0,0 +1,15 @@ +import { join } from 'node:path' +import { clearAmbientProxyEnv } from '../../../../../../scripts/test-proxy-environment.ts' + +/** Isolate SDK profile processes from ambient profile, runtime and Node loader settings. */ +export function profileEnvironment(root: string, baseUrl: string): NodeJS.ProcessEnv { + const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('DSH_'))) + Object.assign(env, { + DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1', + DSH_AGENTS_HOME: join(root, 'agents'), DSH_PRIMARY_RUNTIME: '', + DEEPSEEK_API_KEY: 'keyless-profile-test', DEEPSEEK_BASE_URL: baseUrl, + NODE_OPTIONS: '', NODE_PATH: '', + }) + clearAmbientProxyEnv(env) + return env +} diff --git a/apps/cli/tests/profiles/sdk/fixtures/tool-parity.mjs b/apps/cli/tests/profiles/sdk/fixtures/tool-parity.mjs new file mode 100644 index 0000000000..69e1fbde57 --- /dev/null +++ b/apps/cli/tests/profiles/sdk/fixtures/tool-parity.mjs @@ -0,0 +1,54 @@ +/** Observe step-admitted capabilities without changing either shipped tool executor. */ +import { writeFile } from 'node:fs/promises' +import { createUserMessage } from '@deepseek-ai/dsh-llm' + +export const inject = ['tools', 'agents', 'loader'] + +export function apply(ctx, config) { + let observed + ctx.on('system-prompt/assemble', async (_assembly, context, next) => { + if (context.toolSet !== undefined) { + observed = { + names: ctx.tools.definitions(context.scope, context.toolSet).map(tool => tool.name).sort(), + hmr: ctx.get('hmr') !== undefined, + } + await writeFile(config.output, JSON.stringify(observed)) + } + return next() + }) + if (config.preset === undefined) return + const receive = message => { + if (message === 'stop-tool-parity') { + // Run the CLI shutdown handler: Windows OS signals terminate before its cleanup. + process.emit('SIGTERM') + return + } + if (message !== 'collect-tool-parity') return + void collect().then( + result => process.send({ result }), + error => process.send({ error: String(error.stack ?? error) }), + ) + } + ctx.effect(() => { + process.on('message', receive) + return () => process.off('message', receive) + }) + async function collect() { + await ctx.loader.await() + const presets = ctx.get('agentPresets') + if (presets === undefined) throw new Error('Web tool parity requires the shipped presets') + const handle = await ctx.agents.create({ + sessionId: 'tool-parity', cwd: config.cwd, + agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-pro' }, + setup: scope => presets.mount(scope, config.preset).then(() => undefined), + }) + try { + handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Inspect tools' }], source: { kind: 'user' } })) + await handle.agent.whenIdle() + if (observed === undefined) throw new Error('Web did not assemble a model step') + return observed + } finally { + await handle.dispose() + } + } +} diff --git a/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts b/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts index 6f8add8c49..bee0a10775 100644 --- a/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts +++ b/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts @@ -174,7 +174,7 @@ describe('Python SDK dsh profile keyless smoke', () => { expect(modelRequests[0]?.output_config).toEqual({ effort: 'max' }) expect(modelRequests[0]?.max_tokens).toBe(1234) const expectedTools = ['read', 'write', 'edit', 'web_fetch', 'web_search', 'subagent', 'subagent_fork', - 'present', 'ask_user_question', 'schedule_create', 'schedule_delete', 'schedule_list', 'schedule_update'] + 'present', 'ask_user_question', 'schedule_create', 'schedule_delete', 'schedule_list', 'schedule_update', 'plugin_manager'] const requestText = JSON.stringify(modelRequests[0]) if (ptc) { expect(toolNames).toEqual(['run_code']) diff --git a/apps/cli/tests/profiles/sdk/plugin-manager.expected.e2e.ts b/apps/cli/tests/profiles/sdk/plugin-manager.expected.e2e.ts new file mode 100644 index 0000000000..e27881ded0 --- /dev/null +++ b/apps/cli/tests/profiles/sdk/plugin-manager.expected.e2e.ts @@ -0,0 +1,176 @@ +/** SDK plugin management persists changes while the live stdio process keeps its original composition. */ +import { createServer } from 'node:http' +import { mkdtemp, readFile, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client' +import { expect, it } from 'vitest' +import { z } from 'zod' +import { profileEnvironment } from './fixtures/profile-environment.ts' +import { messagesResponse } from './fixtures/messages-response.ts' + +it.for(['standard', 'ptc'] as const)('keeps %s plugin changes pending until the SDK runtime restarts', async (mode, test) => { + const root = await mkdtemp(join(tmpdir(), 'sdk-plugin-manager-')) + const requests: Record[] = [] + let phase: 'list' | 'set' | 'done' = 'list' + let changedAt = 0 + let fixtureError: unknown + const listPage = z.object({ + entries: z.array(z.object({ entryId: z.string(), moduleName: z.string() })), nextOffset: z.number().nullable(), + }) + const server = createServer((request, response) => { + let body = '' + request.setEncoding('utf8') + request.on('data', (chunk: string) => { body += chunk }) + request.on('end', () => { + let args: Record | undefined + try { + const current = JSON.parse(body) as Record + requests.push(current) + if (requests.length === 1) args = { action: 'list_plugins', limit: 100 } + else if (phase === 'list') { + const messages = current.messages as { content: { type: string; content?: { text: string }[] }[] }[] + const result = messages.flatMap(message => message.content).findLast(block => block.type === 'tool_result') + const page = listPage.parse(JSON.parse(result!.content![0]!.text)) + const row = page.entries.find(entry => entry.moduleName === '@deepseek-ai/dsh-tool-web') + if (row !== undefined) { + args = { action: 'set_plugin', target: row.entryId, enabled: false } + phase = 'set' + } else if (page.nextOffset !== null) args = { action: 'list_plugins', offset: page.nextOffset, limit: 100 } + else throw new Error('SDK plugin inventory omitted tool-web') + } else if (phase === 'set') { + changedAt = requests.length - 1 + phase = 'done' + } + } catch (error) { fixtureError = error } + const call = mode === 'ptc' + ? { type: 'tool_use', id: `manage-${requests.length}`, name: 'run_code', input: { + code: `return await tools.plugin_manager(${JSON.stringify(args)});`, description: 'Disable web tools after restart', + } } + : { type: 'tool_use', id: `manage-${requests.length}`, name: 'plugin_manager', input: args } + response.writeHead(200, { 'content-type': 'text/event-stream' }) + response.end(messagesResponse(args !== undefined ? call : { type: 'text', text: 'done' }, + args !== undefined ? 'tool_use' : 'end_turn')) + }) + }) + test.onTestFinished(async () => { + try { + await new Promise((resolve, reject) => server.close((error) => { + if (error === undefined) resolve() + else reject(error) + })) + } + finally { await rm(root, { recursive: true, force: true }) } + }) + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)) + const address = server.address() + if (address === null || typeof address === 'string') throw new Error('model fixture has no TCP address') + const env = profileEnvironment(root, `http://127.0.0.1:${address.port}`) + const options = { + cwd: root, processCwd: root, dshHome: join(root, 'home'), env, model: 'deepseek-v4-pro', + patches: mode === 'ptc' ? [fileURLToPath(new URL('../../../config/examples/ptc.yml', import.meta.url))] : [], + } + async function run(restarted: boolean): Promise { + const harness = new DeepSeekHarness(options) + const abort = (): void => { void harness.close() } + test.signal.addEventListener('abort', abort, { once: true }) + try { + const session = harness.session(restarted ? 'restarted' : 'original') + expect((await session.run('Disable web tools after restart')).finalResponse).toBe('done') + if (!restarted) { + expect((await session.run('Continue on the same connection')).finalResponse).toBe('done') + } + } finally { + await harness.close() + test.signal.removeEventListener('abort', abort) + } + } + const advertises = (request: Record, name: string): boolean => mode === 'ptc' + ? JSON.stringify(request.system).includes(`${name}:`) + : (request.tools as { name: string }[]).some(tool => tool.name === name) + await run(false) + expect(fixtureError).toBeUndefined() + expect(changedAt).toBeGreaterThan(0) + expect(advertises(requests[0]!, 'plugin_manager')).toBe(true) + expect(JSON.stringify(requests[changedAt]!.messages)).toContain('restart-required') + expect(JSON.stringify(requests[changedAt]!.messages)).toContain('no-hmr') + expect(JSON.stringify(requests[changedAt]!.messages)).toContain('restart DSH') + expect(advertises(requests.at(-1)!, 'web_fetch')).toBe(true) + const saved = await readFile(join(root, 'home/profiles/sdk/cordis.patch.yml'), 'utf8') + expect(saved).toContain('tool-web') + expect(saved).toContain('disabled: true') + await run(true) + expect(advertises(requests.at(-1)!, 'web_fetch')).toBe(false) + expect(advertises(requests.at(-1)!, 'plugin_manager')).toBe(true) +}) + +it.for(['unavailable', 'approved', 'missing-pnpm'] as const)('reports the %s plugin-management prerequisite', async (scenario, test) => { + const root = await mkdtemp(join(tmpdir(), 'sdk-plugin-prerequisite-')) + const requests: Record[] = [] + let fixtureError: unknown + const server = createServer((request, response) => { + let body = '' + request.setEncoding('utf8') + request.on('data', (chunk: string) => { body += chunk }) + request.on('end', () => { + try { requests.push(JSON.parse(body) as Record) } + catch (error) { fixtureError = error } + const args = scenario === 'missing-pnpm' + ? { action: 'install_bundle', target: '@deepseek-ai/dsh-subagent-codex' } + : { action: 'list_plugins', limit: 1 } + const call = { type: 'tool_use', id: 'prerequisite', name: 'plugin_manager', input: args } + response.writeHead(200, { 'content-type': 'text/event-stream' }) + response.end(messagesResponse(requests.length === 1 ? call : { type: 'text', text: 'done' }, + requests.length === 1 ? 'tool_use' : 'end_turn')) + }) + }) + test.onTestFinished(async () => { + try { await new Promise((resolve, reject) => server.close((error) => { if (error) reject(error); else resolve() })) } + finally { await rm(root, { recursive: true, force: true }) } + }) + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)) + const address = server.address() + if (address === null || typeof address === 'string') throw new Error('model fixture has no TCP address') + const env = profileEnvironment(root, `http://127.0.0.1:${address.port}`) + env.DSH_PERMISSION_MODE = scenario === 'missing-pnpm' ? 'danger-full-access' : 'workspace-write' + if (scenario === 'missing-pnpm') { + for (const key of Object.keys(env)) if (key.toLowerCase() === 'path') Reflect.deleteProperty(env, key) + env.PATH = root + } + const harness = new DeepSeekHarness({ cwd: root, processCwd: root, dshHome: join(root, 'home'), + env, model: 'deepseek-v4-pro', approvalRequests: scenario === 'approved' }) + let approvals = 0 + const abort = (): void => { void harness.close() } + test.signal.addEventListener('abort', abort, { once: true }) + try { + harness.client.start() + harness.client.onRequest(async (method) => { + expect(method).toBe('approval/request') + approvals++ + return { outcome: 'allowed-once' } + }) + expect((await harness.run('Check plugin prerequisites')).finalResponse).toBe('done') + expect(fixtureError).toBeUndefined() + const result = JSON.stringify(requests.at(-1)?.messages) + if (scenario === 'unavailable') expect(result).toContain('unavailable') + else if (scenario === 'missing-pnpm') { + const messages = requests.at(-1)!.messages as { content: { type: string; content?: { text: string }[] }[] }[] + const toolResult = messages.flatMap(message => message.content).findLast(block => block.type === 'tool_result') + const failure = z.object({ + changed: z.literal(false), application: z.literal('failed'), + packageResult: z.object({ exitCode: z.number(), output: z.string().min(1) }), + error: z.object({ code: z.literal('operation-error'), diagnostic: z.string().min(1) }), + }).parse(JSON.parse(toolResult!.content![0]!.text)) + // cmd.exe reports 1 for a missing command; POSIX spawn reports 127. + expect(failure.packageResult.exitCode).toBe(process.platform === 'win32' ? 1 : 127) + expect(failure.error.diagnostic).toContain('pnpm') + expect(failure.packageResult.output).toContain(failure.error.diagnostic) + } else { expect(approvals).toBe(1); expect(result).toContain('entries') } + const manifest = JSON.parse(await readFile(join(root, 'home/profiles/sdk/package.json'), 'utf8')) as { dependencies: object } + expect(Object.keys(manifest.dependencies ?? {})).toEqual([]) + } finally { + await harness.close() + test.signal.removeEventListener('abort', abort) + } +}) diff --git a/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts b/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts index f3efcf6dd1..d031001f95 100644 --- a/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts +++ b/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts @@ -56,7 +56,7 @@ it('delivers an overdue reminder with the SDK route and lets the client resume t model: 'deepseek-v4-pro', maxTokens: 5678, initializeTimeoutMs: 30_000, env: { ...env, DSH_TEST_SCHEDULE_NOW: String(Date.parse('2030-01-01T00:00:00Z')) } }) clients.push(first) - expect((await first.session('saved').run('Set a reminder')).finalResponse).toBe('ready') + expect(await first.session('saved').run('Set a reminder')).toMatchObject({ finalResponse: 'ready' }) expect(requests).toHaveLength(2) await first.close() restarting = true @@ -68,5 +68,5 @@ it('delivers an overdue reminder with the SDK route and lets the client resume t await vi.waitFor(() => { expect(restored).toHaveLength(1) }, { timeout: 30_000 }) expect(restored[0]).toMatchObject({ model: 'deepseek-v4-flash', max_tokens: 1234 }) const session = await second.resumeSession('saved') - expect((await session.run('Continue after the reminder')).finalResponse).toBe('ready') + expect(await session.run('Continue after the reminder')).toMatchObject({ finalResponse: 'ready' }) }) diff --git a/apps/cli/tests/profiles/sdk/tool-parity.spec.ts b/apps/cli/tests/profiles/sdk/tool-parity.spec.ts new file mode 100644 index 0000000000..7e3e5a8585 --- /dev/null +++ b/apps/cli/tests/profiles/sdk/tool-parity.spec.ts @@ -0,0 +1,26 @@ +/** Diagnostics and exact exception consumption for cross-profile tool comparison. */ +import { expect, it } from 'vitest' +import { assertToolParity } from './tool-parity.ts' + +it('accepts an exact directional exception and rejects it after the profiles converge', () => { + const exceptions = [{ tool: 'desktop_only', side: 'desktop' as const, reason: 'Requires a graphical client.' }] + expect(() => { assertToolParity('standard', ['read'], ['read', 'desktop_only'], exceptions) }).not.toThrow() + expect(() => { assertToolParity('standard', ['read'], ['read'], exceptions) }).toThrow('Stale exceptions: desktop:desktop_only') + expect(() => { assertToolParity('standard', ['read', 'desktop_only'], ['read'], exceptions) }).toThrow('Only in SDK: desktop_only') +}) + +it('reports unexpected differences in both directions without hiding shared additions', () => { + expect(() => { assertToolParity('standard', ['read', 'new_shared'], ['new_shared', 'read'], []) }).not.toThrow() + expect(() => { assertToolParity('ptc', ['read', 'sdk_extra'], ['read', 'present'], []) }).toThrow( + 'Missing from SDK: present\nOnly in SDK: sdk_extra', + ) +}) + +it('rejects empty observations, undocumented exceptions and duplicate exceptions', () => { + expect(() => { assertToolParity('standard', [], [], []) }).toThrow('Empty tool inventory') + expect(() => { assertToolParity('standard', ['read'], ['read'], [ + { tool: 'extra', side: 'sdk', reason: ' ' }, + ]) }).toThrow('requires a reason') + const exception = { tool: 'extra', side: 'sdk' as const, reason: 'Intentional.' } + expect(() => { assertToolParity('standard', ['read', 'extra'], ['read'], [exception, exception]) }).toThrow('Stale exceptions: sdk:extra') +}) diff --git a/apps/cli/tests/profiles/sdk/tool-parity.ts b/apps/cli/tests/profiles/sdk/tool-parity.ts new file mode 100644 index 0000000000..fce089fc02 --- /dev/null +++ b/apps/cli/tests/profiles/sdk/tool-parity.ts @@ -0,0 +1,53 @@ +/** Exact, directional exceptions to the shipped SDK/Desktop capability comparison. */ +export type ToolMode = 'standard' | 'ptc' + +interface Exception { + tool: string + side: 'sdk' | 'desktop' + reason: string +} + +/** Intentional product differences; obsolete entries fail alongside undeclared differences. */ +export const toolParityExceptions: Record = { + standard: [{ tool: 'list_subagent_models', side: 'desktop', + reason: 'Desktop enables subagent model discovery; SDK delegation inherits the caller model by default.' }], + ptc: [ + { tool: 'list_subagent_models', side: 'desktop', + reason: 'Desktop enables subagent model discovery; SDK delegation inherits the caller model by default.' }, + { tool: 'plugin_manager', side: 'sdk', + reason: 'SDK PTC changes are persisted for restart without replacing active bindings because HMR is disabled; Desktop PTC excludes management in its HMR-enabled preset.' }, + { tool: 'workflow', side: 'sdk', + reason: 'The SDK PTC overlay changes only the executor so existing base workflow callers keep working; Desktop PTC uses run_code orchestration and omits the separate workflow surface.' }, + ], +} + +/** + * Compare actual step-admitted sets, rejecting both drift and unused exceptions. + * @param mode - matching SDK executor and Desktop preset. + * @param sdk - SDK capability names. + * @param desktop - Desktop capability names. + * @param exceptions - exact one-sided product differences with their rationale. + */ +export function assertToolParity( + mode: ToolMode, sdk: readonly string[], desktop: readonly string[], + exceptions = toolParityExceptions[mode], +): void { + if (sdk.length === 0 || desktop.length === 0) throw new Error(`Empty tool inventory: ${mode}`) + const only = { + sdk: new Set(sdk.filter(name => !desktop.includes(name))), + desktop: new Set(desktop.filter(name => !sdk.includes(name))), + } + const stale: string[] = [] + for (const exception of exceptions) { + if (!exception.reason.trim()) throw new Error(`Tool exception requires a reason: ${exception.tool}`) + if (!only[exception.side].delete(exception.tool)) stale.push(`${exception.side}:${exception.tool}`) + } + if (only.sdk.size || only.desktop.size || stale.length) { + throw new Error([ + `SDK/Desktop tool mismatch: ${mode}`, + `Missing from SDK: ${[...only.desktop].sort().join(', ') || '(none)'}`, + `Only in SDK: ${[...only.sdk].sort().join(', ') || '(none)'}`, + `Stale exceptions: ${stale.sort().join(', ') || '(none)'}`, + ].join('\n')) + } +} diff --git a/apps/cli/tests/profiles/subagent-preset-switch.overlay.yml b/apps/cli/tests/profiles/subagent-preset-switch.overlay.yml new file mode 100644 index 0000000000..0222357267 --- /dev/null +++ b/apps/cli/tests/profiles/subagent-preset-switch.overlay.yml @@ -0,0 +1,27 @@ +- insert: + - id: preset-delegate-a + name: '@deepseek-ai/dsh-agent-preset' + config: + id: delegate-a + plugins: + - name: '@deepseek-ai/dsh-tool-subagent' + config: + provider: spawn + allowedAgentPresets: [standard, ptc, minimal] + - name: '@deepseek-ai/dsh-tool-subagent' + config: + provider: fork + toolName: subagent_fork + - id: preset-delegate-b + name: '@deepseek-ai/dsh-agent-preset' + config: + id: delegate-b + plugins: + - name: '@deepseek-ai/dsh-tool-subagent' + config: + provider: spawn + allowedAgentPresets: [standard, ptc, minimal] + - name: '@deepseek-ai/dsh-tool-subagent' + config: + provider: fork + toolName: subagent_fork diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts index f0ee02276e..16db2d0614 100644 --- a/apps/cli/tests/web-agent-presets.e2e.ts +++ b/apps/cli/tests/web-agent-presets.e2e.ts @@ -355,6 +355,49 @@ describe('the shipped Web composition', () => { } }) + it.each(['standard', 'ptc'] as const)('retains delegation tools after repeated preset round trips ending in %s', async (target) => { + const adapter = new MinimalCompactionAdapter() + const unregister = ctx.llm.registerAdapter(['preset-round-trip'], adapter) + onTestFinished(unregister) + const direct = await ctx.agents.create({ + sessionId: SessionId(`preset-direct-${target}-${randomUUID()}`), + agentOptions: { provider: 'preset-round-trip', model: 'preset-round-trip' }, + setup: agentCtx => ctx.agentPresets.mount(agentCtx, target).then(() => undefined), + }) + onTestFinished(() => direct.dispose()) + const handle = await ctx.agents.create({ + sessionId: SessionId(`preset-round-trip-${target}-${randomUUID()}`), + agentOptions: { provider: 'preset-round-trip', model: 'preset-round-trip' }, + setup: agentCtx => ctx.agentPresets.mount(agentCtx, target).then(() => undefined), + }) + onTestFinished(() => handle.dispose()) + const { agent } = handle + const other = target === 'standard' ? 'ptc' : 'standard' + for (const preset of [other, target, other, target]) { + await ctx.agentPresets.select(agent, preset) + expect(toolNames(ctx, agent)).toEqual(expect.arrayContaining(['subagent', 'subagent_fork'])) + } + expect(ctx.tools.schemas(agent)).toEqual(ctx.tools.schemas(direct.agent)) + const assembly = await ctx.systemPrompt.assemble({ scope: agent }) + if (target === 'ptc') { + const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? '' + expect(sdk).toContain('subagent:') + expect(sdk).toContain('subagent_fork:') + } + direct.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Reply with Ready.' }], source: { kind: 'user' } })) + await direct.agent.whenIdle() + const directRequest = adapter.requests.find(request => request.purpose === undefined) + expect(directRequest).toBeDefined() + adapter.requests.length = 0 + agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Reply with Ready.' }], source: { kind: 'user' } })) + await agent.whenIdle() + const request = adapter.requests.find(request => request.purpose === undefined) + expect(request).toBeDefined() + expect(request?.tools).toEqual(directRequest?.tools) + const header = agent.session.snapshotEvents().find(event => event.type === 'request/header') + expect(header?.data.header.tools).toEqual(request?.tools) + }) + it('composes the exact RL prompt and persistent shell from `minimal`', async () => { const handle = await ctx.agents.create({ sessionId: SessionId('preset-minimal'), @@ -683,6 +726,41 @@ describe('the shipped Web composition', () => { }) }) +describe('preset-selected delegation through the Web Loader', () => { + it('exposes configured delegation tools when each preset switch resolves', async () => { + const root = await mkdtemp(join(tmpdir(), 'dsh-delegation-switch-')) + try { + const configured = await bootWeb(root, loadOverlayPatches('delegation-switch', + join(REPO_ROOT, 'apps/cli/tests/profiles/subagent-preset-switch.overlay.yml'))) + try { + const adapter = new MinimalCompactionAdapter() + configured.llm.registerAdapter(['preset-switch'], adapter) + const { agent } = await configured.agents.create({ + sessionId: SessionId(`configured-switch-${randomUUID()}`), + agentOptions: { provider: 'preset-switch', model: 'preset-switch' }, + setup: owner => configured.agentPresets.mount(owner, 'delegate-a').then(() => undefined), + }) + const views: Array<{ preset: string; names: string[] }> = [] + for (const preset of ['delegate-b', 'delegate-a', 'delegate-b', 'delegate-a', 'ptc', 'standard', 'delegate-a']) { + await configured.agentPresets.select(agent, preset) + views.push({ preset, names: toolNames(configured, agent) }) + } + agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Reply with Ready.' }], source: { kind: 'user' } })) + await agent.whenIdle() + for (const { preset, names } of views) { + expect(names, `tools after selecting ${preset}`).toEqual(expect.arrayContaining(['subagent', 'subagent_fork'])) + } + const request = adapter.requests.find(request => request.purpose === undefined) + expect(request?.tools?.map(tool => tool.name)).toEqual(expect.arrayContaining(['subagent', 'subagent_fork'])) + expect(request?.tools?.find(tool => tool.name === 'subagent')) + .toHaveProperty('parameters.properties.agent_preset.enum', ['standard', 'ptc', 'minimal']) + const header = agent.session.snapshotEvents().find(event => event.type === 'request/header') + expect(header?.data.header.tools).toEqual(request?.tools) + } finally { await configured.fiber.dispose() } + } finally { await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) } + }) +}) + describe.each(['web', 'desktop'] as const)('%s native subagent bundles', (surface) => { const products = ['codex', 'claude-code'] as const type Product = typeof products[number] diff --git a/apps/desktop-host/package.json b/apps/desktop-host/package.json index 161391bbb2..93469b15f2 100644 --- a/apps/desktop-host/package.json +++ b/apps/desktop-host/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-desktop-host", "description": "Private Node-mode host process for the Electron desktop application", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "private": true, "license": "MIT", "type": "module", @@ -25,7 +25,8 @@ "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:*", "@deepseek-ai/dsh-skill-office": "workspace:*", "@deepseek-ai/dsh-deepseek-account": "workspace:*", - "@deepseek-ai/dsh-workspace": "workspace:*" + "@deepseek-ai/dsh-workspace": "workspace:*", + "@deepseek-ai/dsh-plugin-manager": "workspace:*" }, "devDependencies": { "@deepseek-ai/cordis-plugin-loader": "workspace:~", diff --git a/apps/desktop-host/src/fatal-diagnostic.ts b/apps/desktop-host/src/fatal-diagnostic.ts new file mode 100644 index 0000000000..e72533dae0 --- /dev/null +++ b/apps/desktop-host/src/fatal-diagnostic.ts @@ -0,0 +1,59 @@ +/** Bounded Host failure details sent to the Desktop crash reporter. */ + +import { inspect } from 'node:util' +import { StartupError } from '@deepseek-ai/dsh-app-boot' + +/** Maximum characters carried by one fatal diagnostic, including its truncation notice. */ +export const MAX_FATAL_DIAGNOSTIC_CHARS = 64 * 1024 + +/** Original-error budget when startup metadata needs space in the same report. */ +const MAX_ORIGINAL_ERROR_CHARS = 8 * 1024 + +/** Startup entry details leave room for composition and provider observations. */ +const MAX_STARTUP_ENTRY_CHARS = 8 * 1024 + +/** + * Render the original error and explicitly selected startup metadata. + * Selected metadata excludes configuration values and arbitrary startup logger arguments. + * @param error - Failure received by the Host entry point. + * @returns Bounded text with an explicit notice when the report is shortened. + */ +export function formatFatalDiagnostic(error: unknown): string { + const original = inspect(error, { depth: 4, maxArrayLength: 50 }) + const sections: string[] = [] + const seen = new Set() + function visit(value: unknown): void { + if (!(value instanceof Error) || seen.has(value)) return + seen.add(value) + if (value instanceof StartupError) { + if (value.startup !== undefined) { + sections.push(`Configuration file: ${value.startup.configurationPath}`) + } + const entries = inspect(value.entries, { depth: 6, maxArrayLength: null, maxStringLength: 4096 }) + sections.push('--- startup entries ---', entries.length <= MAX_STARTUP_ENTRY_CHARS ? entries + : `${entries.slice(0, MAX_STARTUP_ENTRY_CHARS).replace(/[\uD800-\uDBFF]$/u, '')}\n… (startup entries truncated at ${MAX_STARTUP_ENTRY_CHARS} characters)`) + if (value.composition !== undefined) { + const { plugins, services, omittedPlugins, omittedServices } = value.composition + const sources = [...new Set(plugins.map(plugin => plugin.source))] + sections.push('--- startup composition ---', + 'Provider lists contain observed registrations only; an empty list means the provider is unknown.', + 'Source identifies the Loader tree, not necessarily the overriding patch.', + `Omitted plugin rows: ${omittedPlugins}; omitted missing-service observations: ${omittedServices}.`, + '--- missing services ---', ...services.map(service => JSON.stringify(service)), + '--- plugin sources (sourceIndex) ---', ...sources.map((source, index) => JSON.stringify({ index, source })), + '--- plugins (inactive first) ---', ...plugins.map(({ source, ...plugin }) => JSON.stringify({ ...plugin, sourceIndex: sources.indexOf(source) }))) + } else { + sections.push('Startup composition diagnostic unavailable.') + } + } + visit(value.cause) + if (value instanceof AggregateError) value.errors.forEach(visit) + } + visit(error) + sections.unshift(sections.length === 0 || original.length <= MAX_ORIGINAL_ERROR_CHARS ? original + : `${original.slice(0, MAX_ORIGINAL_ERROR_CHARS).replace(/[\uD800-\uDBFF]$/u, '')}\n… (original error truncated at ${MAX_ORIGINAL_ERROR_CHARS} characters)`) + const text = sections.join('\n') + if (text.length <= MAX_FATAL_DIAGNOSTIC_CHARS) return text + const notice = `\n… (Host diagnostic truncated at ${MAX_FATAL_DIAGNOSTIC_CHARS} characters)` + return text.slice(0, MAX_FATAL_DIAGNOSTIC_CHARS - notice.length).replace(/[\uD800-\uDBFF]$/u, '') + notice +} diff --git a/apps/desktop-host/src/index.ts b/apps/desktop-host/src/index.ts index 3109537b63..31bbbffe15 100644 --- a/apps/desktop-host/src/index.ts +++ b/apps/desktop-host/src/index.ts @@ -1,7 +1,9 @@ /** Launch the Desktop profile through the Web application and report its URL to Electron. */ import { delimiter, join } from 'node:path' -import { inspect } from 'node:util' +import { randomUUID } from 'node:crypto' +import type { PluginOperationRunId } from '@deepseek-ai/dsh-plugin-manager/diagnostic' +import { formatFatalDiagnostic } from './fatal-diagnostic.ts' import { loadLayeredEnv, loadProfileDirectory, reportSkippedBundles } from '@deepseek-ai/dsh-app-boot' import { runProfile } from '@deepseek-ai/dsh/profile-boot' import type {} from '@deepseek-ai/dsh-client-connection' @@ -15,8 +17,11 @@ import { installDesktopUpdateTaskControl } from './update-tasks.ts' import { installDesktopQuitInspection } from './quit-inspection.ts' import { installPlatformSessionPublisher } from './platform-session.ts' import { installOfficeEngineResolution } from './office-engine.ts' +import { installOperationDiagnostics } from './operation-diagnostics.ts' async function main(): Promise { + const runId = randomUUID() as PluginOperationRunId + if (process.connected) process.send?.({ type: 'starting', runId }, (error) => { if (error !== null) console.error(error) }) const runtimeDir = process.argv[2] as string const projectDir = process.argv[3] as string installOfficeEngineResolution(runtimeDir) @@ -123,6 +128,7 @@ async function main(): Promise { }) process.once('disconnect', () => { void stop() }) const { ctx } = await application + installOperationDiagnostics(ctx, record => send({ type: 'plugin-operation', record }), 32, runId) control.updateTasks = installDesktopUpdateTaskControl(ctx) control.quitInspection = installDesktopQuitInspection(ctx) await ctx.plugin(desktopOffice, { @@ -137,16 +143,13 @@ async function main(): Promise { if (process.connected) process.send?.({ type: 'ready', url, injections: ctx.webServer.collectIndexInjections(ctx.connection.browserPeer) }, (error) => { if (error !== null) console.error(error) }) } -/** Upper bound of the startup diagnostic carried over IPC; the head holds the message and stack. */ -const MAX_FATAL_DIAGNOSTIC_CHARS = 64 * 1024 - if (import.meta.main) { main().catch((error: unknown) => { const message = error instanceof Error ? error.message : String(error) // The shell receives the complete inspected error here, not through stderr: // stderr bytes and this IPC message race, and the shell reports the first // failure it sees. - const diagnostic = inspect(error, { depth: 4, maxArrayLength: 50 }).slice(0, MAX_FATAL_DIAGNOSTIC_CHARS) + const diagnostic = formatFatalDiagnostic(error) if (process.connected) process.send?.({ type: 'fatal', message, diagnostic }, (error) => { if (error !== null) console.error(error) }) console.error(error) process.exitCode = 1 diff --git a/apps/desktop-host/src/operation-diagnostics.ts b/apps/desktop-host/src/operation-diagnostics.ts new file mode 100644 index 0000000000..3d29e97bc0 --- /dev/null +++ b/apps/desktop-host/src/operation-diagnostics.ts @@ -0,0 +1,34 @@ +/** Bounded delivery of management facts to the shell which owns durable diagnostics. */ +import type { Context } from '@deepseek-ai/cordis' +import { parsePluginOperationRecord, type PluginOperationRecord, type PluginOperationRunId } from '@deepseek-ai/dsh-plugin-manager/diagnostic' + +/** + * Observe manager operations after Host startup, with bounded concurrent IPC deliveries. + * @param ctx - Context owning the subscription and its pending deliveries. + * @param send - IPC transport promise which settles when delivery succeeds or fails. + * @param maxPending - Maximum number of outstanding deliveries; excess events are counted and omitted. + * @param runId - Host lifetime identity announced before profile startup. + */ +export function installOperationDiagnostics( + ctx: Context, send: (record: PluginOperationRecord) => Promise, maxPending: number, runId: PluginOperationRunId, +): void { + if (!Number.isSafeInteger(maxPending) || maxPending < 1) throw new RangeError('Invalid diagnostic delivery budget') + const pending = new Set>() + let dropped = 0 + let closed = false + ctx.on('plugin-manager/operation', (operation) => { + if (closed || pending.size >= maxPending) { dropped++; return } + const record = parsePluginOperationRecord({ runId, operation, transportDropped: dropped }) + if (record === undefined) { dropped++; return } + const delivery = Promise.resolve().then(async () => { + try { await send(record) } + catch (_error) { dropped++ /* IPC failure does not change the management operation. */ } + }) + pending.add(delivery) + void delivery.then(() => { pending.delete(delivery) }) + }) + ctx.effect(() => async () => { + closed = true + await Promise.allSettled(pending) + }) +} diff --git a/apps/desktop-host/tests/fatal-diagnostic.spec.ts b/apps/desktop-host/tests/fatal-diagnostic.spec.ts new file mode 100644 index 0000000000..1f41358300 --- /dev/null +++ b/apps/desktop-host/tests/fatal-diagnostic.spec.ts @@ -0,0 +1,105 @@ +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it, onTestFinished } from 'vitest' +import { boot, StartupError } from '@deepseek-ai/dsh-app-boot' +import { formatFatalDiagnostic, MAX_FATAL_DIAGNOSTIC_CHARS } from '../src/fatal-diagnostic.ts' +import { renderCrashReport } from '../../desktop/src/crash-report.ts' + +it.each([ + ['import', 'throw new Error("qualification-import-failure")'], + ['initialize', 'export function apply() { throw new Error("qualification-initialize-failure", { cause: new Error("qualification-root-cause") }) }'], +])('retains real plugin %s failure evidence in the Desktop report after Loader disposal', async (stage, source) => { + const directory = await mkdtemp(join(tmpdir(), 'desktop-plugin-failure-')) + onTestFinished(async () => { await rm(directory, { recursive: true, force: true }) }) + await writeFile(join(directory, 'failure.mjs'), source + '\n') + const config = join(directory, 'cordis.yml') + await writeFile(config, '- id: agent-loop\n name: ./failure.mjs\n') + const failure: unknown = await boot('diagnostic-test', config).then(async (ctx) => { + await ctx.fiber.dispose() + throw new Error('Expected fixture plugin to fail startup') + }, (error: unknown) => error) + expect(failure).toBeInstanceOf(StartupError) + const diagnostic = formatFatalDiagnostic(failure) + const report = renderCrashReport({ source: 'host', phase: 'startup', error: failure, + hostDiagnostic: diagnostic, rendererConsole: [], operationHistoryPlanned: true, + time: new Date('2026-10-19T00:00:00Z'), + app: { name: 'qualification', version: 'test', platform: 'win32', arch: 'x64', electron: 'test', node: process.version, locale: 'zh-CN' }, + }) + expect(report).toContain(`qualification-${stage}-failure`) + expect(report).toContain('./failure.mjs') + expect(report).toContain('--- startup composition ---') + if (stage === 'initialize') expect(report).toContain('qualification-root-cause') +}) + +it('includes non-enumerable startup entries without copying arbitrary startup logger arguments', () => { + const error = new StartupError('required plugin did not activate', [{ + id: 'agent-loop', module: '@deepseek-ai/dsh-agent-loop', required: true, fiberState: undefined, + outcome: { kind: 'pending', missing: ['agents', 'sessions'] }, + }]) + error.startup = { configurationPath: '/profile/cordis.yml', messages: [{ + ts: 1, name: 'plugin', type: 'warn', args: ['private-plugin-output'], + }] } + const report = formatFatalDiagnostic(new Error('Host startup failed', { cause: error })) + expect(report).toContain('--- startup entries ---') + expect(report).toContain('@deepseek-ai/dsh-agent-loop') + expect(report).toContain("missing: [ 'agents', 'sessions' ]") + expect(report).toContain('Configuration file: /profile/cordis.yml') + expect(report).not.toContain('private-plugin-output') +}) + +it('marks truncation within the complete IPC budget and preserves Unicode', () => { + const error = new Error('😀'.repeat(MAX_FATAL_DIAGNOSTIC_CHARS)) + const report = formatFatalDiagnostic(error) + expect(report.length).toBeLessThanOrEqual(MAX_FATAL_DIAGNOSTIC_CHARS) + expect(report).toContain('Host diagnostic truncated at 65536 characters') + expect(report.isWellFormed()).toBe(true) +}) + +it('keeps missing-service evidence ahead of a truncated plugin inventory', () => { + const error = new StartupError('failure '.repeat(2000), [{ + id: 'waiting-entry', module: './waiting.mjs', required: true, fiberState: undefined, + outcome: { kind: 'pending', missing: ['agents'] }, + }]) + error.startup = { configurationPath: '/profile/critical-cordis.yml', messages: [] } + error.composition = { + services: [{ consumer: 'agent-loop', service: 'agents', providers: [] }], + plugins: Array.from({ length: 256 }, (_, index) => ({ + id: `plugin-${index}`, module: 'long-package-name'.repeat(30), version: '1.0.0', + state: 'disabled', source: '/profile/cordis.yml', missing: [], + })), + omittedPlugins: 3, omittedServices: 2, + } + const report = formatFatalDiagnostic(error) + expect(report).toContain('original error truncated at 8192 characters') + expect(report).toContain('Configuration file: /profile/critical-cordis.yml') + expect(report).toContain('waiting-entry') + expect(report).toContain('"service":"agents","providers":[]') + expect(report).toContain('Omitted plugin rows: 3; omitted missing-service observations: 2.') + expect(report).toContain('"source":"/profile/cordis.yml"') + expect(report).toContain('Host diagnostic truncated at 65536 characters') + expect(report.length).toBeLessThanOrEqual(MAX_FATAL_DIAGNOSTIC_CHARS) +}) + +it('terminates traversal through cyclic and aggregate causes', () => { + const error = new AggregateError([], 'cycle') + error.errors.push(error) + error.cause = error + expect(formatFatalDiagnostic(error)).toContain('cycle') +}) + +it.each(['many entries', 'long stack'])('retains composition evidence after %s', (scenario) => { + const failure = new Error('startup failure') + failure.stack = 'x'.repeat(70000) + const error = new StartupError('startup failed', scenario === 'long stack' + ? [{ id: 'failed', module: './failed.mjs', required: true, fiberState: undefined, outcome: { kind: 'failed', error: failure } }] + : Array.from({ length: 256 }, (_, index) => ({ id: `pending-${index}`, module: 'module'.repeat(60), required: true, fiberState: undefined, outcome: { kind: 'pending' as const, missing: ['agents'] } }))) + error.startup = { configurationPath: '/profile/cordis.yml', messages: [] } + error.composition = { plugins: [{ id: 'provider', module: 'example', version: '1.0.0', state: 'active', source: '/profile/cordis.yml', missing: [] }], services: [{ consumer: 'consumer', service: 'agents', providers: [] }], omittedPlugins: 0, omittedServices: 0 } + const report = formatFatalDiagnostic(error) + expect(report).toContain('Configuration file: /profile/cordis.yml') + expect(report).toContain('startup entries truncated') + expect(report).toContain('"service":"agents"') + expect(report).toContain('"version":"1.0.0"') + expect(report.length).toBeLessThanOrEqual(65536) +}) diff --git a/apps/desktop-host/tests/operation-diagnostics.spec.ts b/apps/desktop-host/tests/operation-diagnostics.spec.ts new file mode 100644 index 0000000000..fbf8f038f4 --- /dev/null +++ b/apps/desktop-host/tests/operation-diagnostics.spec.ts @@ -0,0 +1,41 @@ +import { Context } from '@deepseek-ai/cordis' +import type { PluginOperation } from '@deepseek-ai/dsh-plugin-manager/types' +import type { PluginOperationRunId } from '@deepseek-ai/dsh-plugin-manager/diagnostic' +import { expect, it, onTestFinished, vi } from 'vitest' +import { installOperationDiagnostics } from '../src/operation-diagnostics.ts' + +const operation: PluginOperation = { + id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9' as PluginOperation['id'], + time: '2026-10-19T00:00:00.000Z', reason: 'plugin', phase: 'started', target: 'managed', stage: 'enable', +} +const runId = 'c254ab28-97c9-4382-95e6-2db9c66f98c8' as PluginOperationRunId + +it('bounds outstanding deliveries and drains them on context disposal', async () => { + const ctx = new Context() + const entered = Promise.withResolvers() + const release = Promise.withResolvers() + onTestFinished(async () => { release.resolve(undefined); await ctx.fiber.dispose() }) + const send = vi.fn(async () => { entered.resolve(undefined); await release.promise }) + installOperationDiagnostics(ctx, send, 1, runId) + ctx.emit('plugin-manager/operation', operation) + await entered.promise + for (let i = 0; i < 1000; i++) ctx.emit('plugin-manager/operation', operation) + expect(send).toHaveBeenCalledTimes(1) + expect(send).toHaveBeenCalledWith(expect.objectContaining({ runId })) + let stopped = false + const stopping = ctx.fiber.dispose().then(() => { stopped = true }) + await Promise.resolve(undefined) + expect(stopped).toBe(false) + release.resolve(undefined) + await stopping + ctx.emit('plugin-manager/operation', operation) + expect(send).toHaveBeenCalledTimes(1) +}) + +it('contains transport rejections during teardown', async () => { + const ctx = new Context() + onTestFinished(async () => { await ctx.fiber.dispose() }) + installOperationDiagnostics(ctx, async () => { throw new Error('disconnected') }, 1, runId) + ctx.emit('plugin-manager/operation', operation) + await expect(ctx.fiber.dispose()).resolves.toBeUndefined() +}) diff --git a/apps/desktop-host/tsconfig.json b/apps/desktop-host/tsconfig.json index 58eaa722db..7b88b7a2e8 100644 --- a/apps/desktop-host/tsconfig.json +++ b/apps/desktop-host/tsconfig.json @@ -31,6 +31,9 @@ { "path": "../../packages/credentials/deepseek-account" }, + { + "path": "../../packages/boot/plugin-manager" + }, { "path": "../../packages/fs/fs" }, diff --git a/apps/desktop/.env.macos.example b/apps/desktop/.env.macos.example index cc3d21f3e8..7d2336d546 100644 --- a/apps/desktop/.env.macos.example +++ b/apps/desktop/.env.macos.example @@ -56,3 +56,7 @@ APPLE_API_ISSUER= # DOWNLOAD_PROD_COS_BUCKET= # DOWNLOAD_PROD_COS_SECRET_ID= # DOWNLOAD_PROD_COS_SECRET_KEY= + +# Production fixed downloads require teo:CreatePurgeTask permission on the COS identity. +# Required for upload:latest:* and purge:latest; configure the download domain's EO zone. +# DOWNLOAD_PROD_EO_ZONE_ID= diff --git a/apps/desktop/.env.windows.example b/apps/desktop/.env.windows.example index 9d1a976d5d..fd45f0cb32 100644 --- a/apps/desktop/.env.windows.example +++ b/apps/desktop/.env.windows.example @@ -41,3 +41,7 @@ DSH_DESKTOP_WINDOWS_COMPRESSION_LEVEL=3 # DOWNLOAD_PROD_COS_BUCKET= # DOWNLOAD_PROD_COS_SECRET_ID= # DOWNLOAD_PROD_COS_SECRET_KEY= + +# Production fixed downloads require teo:CreatePurgeTask permission on the COS identity. +# Required for upload:latest:* and purge:latest; configure the download domain's EO zone. +# DOWNLOAD_PROD_EO_ZONE_ID= diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml index 01b1154394..3dfceaccd1 100644 --- a/apps/desktop/README.i18n.yaml +++ b/apps/desktop/README.i18n.yaml @@ -12,11 +12,11 @@ en: 7bc8bf30de693222 zh: e85993d8852b6cab /deepseek-harness-desktop/table-of-contents: - en: 05fd227f99ee535a - zh: 60d7d62bc0026973 + en: 127ea90553cb6af7 + zh: 7b1c5aec8558c684 /deepseek-harness-desktop/application-overview: - en: e9b22f232837e131 - zh: fc5f3834b969d2d2 + en: 1667e3d6ffddea4a + zh: 4661a42b9ef4f673 /deepseek-harness-desktop/terminal-command: en: 5f2d25a1d8472647 zh: 2acb5c5d7d1917e2 @@ -36,8 +36,8 @@ en: 160b500cdcd6a39a zh: 6c267f1762ec3689 /deepseek-harness-desktop/installation-ownership/runtime-and-plugin-activation: - en: a1a47b09f4a72ba4 - zh: 7b1cf27f0b72cf31 + en: 4951cd3ee659eb33 + zh: 96bdd6358dad587a /deepseek-harness-desktop/installation-ownership/host-environment: en: 98cf848762482d48 zh: 74f9100a39ec8c2f @@ -66,8 +66,8 @@ en: 182a9c6705213e13 zh: 681762f83490f4c6 /deepseek-harness-desktop/updates/local-updater-qualification: - en: 68ec2f8bd5763ea6 - zh: 23b932dfe8503602 + en: db5e898140a73d53 + zh: 80a9d58c74b4bb24 /deepseek-harness-desktop/low-level-development-overrides: en: 8264b135871e8978 zh: 0939aafb1b2961fc diff --git a/apps/desktop/README.md b/apps/desktop/README.md index 1d5292c68b..fe24b24568 100644 --- a/apps/desktop/README.md +++ b/apps/desktop/README.md @@ -18,6 +18,7 @@ Desktop runs the Harness workspace in a native application. This reference cover - [Key technical decisions](#key-technical-decisions) - [Bundled command runtime](#bundled-command-runtime) - [Installation ownership](#installation-ownership) +- [Recovery and diagnostics](docs/diagnostics/README.md) - [Develop](#develop) - [Package](#package) - [Windows installer interface](#windows-installer-interface) @@ -30,6 +31,8 @@ Desktop runs the Harness workspace in a native application. This reference cover ## Application overview +Electron caches the last confirmed UI language in `userData/desktop/locale-cache` so startup recovery dialogs can use it before Host settings are available. Missing, invalid, or unreadable caches fall back to the system language; cache write failures do not block startup. A successful Host startup or a UI language change refreshes the cache. Until then, a changed system language may differ from the cached language. + Desktop analytics follows the [product collection policy](../../packages/client/product-analytics/README.md), including its live application setting. Web usage is excluded. Update installation waits for its local analytics intake before locking API admission and stopping the Host. Intake has a one-second deadline; failure does not prevent installation, and collector delivery is not awaited. The desktop application is an Electron shell around the complete dsh Web application. An Electron RunAsNode child starts the shared profile runner, and Electron immediately loads the packaged Web entry at `dsh-app://app/`. Its shared loading page waits for Host boot injections, then starts the client without navigating to another document. Electron forwards application HTTP requests to the authenticated Web Host, dropping connection-level response headers (`transfer-encoding`, `connection`, `keep-alive`) that describe the Node fetch rather than the resource, and marking plugin bundle responses `no-store` because their per-launch revisions would only accumulate in Chromium's disk cache; WebSocket streams connect to that Host with credentials attached only for the owned application window. Node IPC carries boot injections, readiness, and shutdown. Desktop listens on an OS-assigned port by default, so it cannot collide with Web’s `3080` or a reserved port; a `webserver.config.port` patch can override it. @@ -40,7 +43,7 @@ The first application-menu command, **About DeepSeek Harness**, opens Electron's Desktop’s local native directory flow opens an Electron folder dialog attached to the application window, restoring, showing, and focusing that window first. Concurrent requests share one dialog; cancellation returns no path and failures remain retryable. Ordinary Web uses the Host chooser. Browse mode lists Host directories. On Linux without zenity or kdialog, automatic selection uses browse instead of the Electron dialog. -Desktop ships one pnpm distribution at `resources/runtime/primary-runtime/dependencies/pnpm`. Build-time production installation, the installed `dsh` CLI, Creator and the Web Plugin Manager execute its `bin/pnpm.mjs` with Electron Node mode; package operations do not require pnpm on PATH. The private Node launcher environment applies only to package operations. Agent workspace dependencies copy the same self-contained primary-runtime payload into the Harness home and execute pnpm with its standalone Node. +Desktop ships one pnpm distribution at `resources/runtime/primary-runtime/dependencies/pnpm`, without the native packages of other targets. Build-time production installation, the installed `dsh` CLI, Creator and the Web Plugin Manager execute its `bin/pnpm.mjs` with Electron Node mode; package operations do not require pnpm on PATH. The private Node launcher environment applies only to package operations. Agent workspace dependencies copy the same self-contained primary-runtime payload into the Harness home and execute pnpm with its standalone Node. Embedded Platform documents use a persistent WebContentsView partition keyed by a hash of the Platform origin and stable account ID. localStorage preferences, including dismissed notices, survive view closure and application restart; different accounts and origins use separate storage. The Host supplies the account ID from its latest successful profile read; while no ID is known, the document opens in a disposable partition that keeps no preference across opens. Opening a persistent partition clears cookies, filesystem, IndexedDB, Cache Storage, the HTTP and shader caches, service workers, and HTTP authentication before the document loads; a disposable partition clears all of its storage. Closing a view destroys the document, removes its request interceptors, and schedules the same cleanup, so authentication left by an unclean exit is cleared before the next document loads. The next open and application shutdown await that cleanup, and an update install waits for it before the installer takes over the exit. A failed cleanup rejects that open and blocks the same account until a later cleanup succeeds; other accounts keep opening. Sign-out destroys the document but retains account-scoped preferences for the next sign-in. A document already open in a disposable partition stays mounted when the account ID arrives for the same credential; the next open uses the account-scoped partition. The [storage decision](../../.agents/notes/implemented/architecture/2026-09-22-platform-browser-storage.md) describes the retention policy. Host sends account credentials through private Node IPC; account RPC and the Harness renderer receive no token. Before page scripts execute, the Platform preload performs one synchronous IPC to read the prepared main-process credential. It exposes displayMode, synchronous getAuthToken() and getLocale() getters, and onLocaleChange(listener), which returns an unsubscribe function. Both getters read preload memory without further IPC. The bootstrap includes the resolved Desktop language (`zh_CN` or `en_US`); Settings language changes update the preload cache and notify the open Platform document without reloading. Platform applies this language before its first render and does not persist it as a browser preference. The main-process handler performs only sender validation and an in-memory read; it never waits for Host, disk, or network. Trusted-page initialization failures retain embedded mode and make the getter throw, preventing browser-credential fallback. Only the owned Platform main frame on the configured issuer origin can initialize. Sign-out, credential replacement, Host shutdown, and view closure destroy the document. Cross-origin document navigation is blocked. HTTPS links requesting a new window open in the system browser without the embedded session or token; other schemes and URL credentials are rejected. Native views occupy the viewport below the Account feature’s return bar. @@ -50,7 +53,7 @@ A server-expired account credential returns to Welcome when no official API key Desktop microphone access is restricted to audio requests from the primary `dsh-app://app` frame. macOS uses system microphone authorization, a packaged usage description, and `com.apple.security.device.audio-input` in the main application and Helper signatures. -Press F12 (Fn+F12 on media-key keyboards), Command+Option+I on macOS, or Ctrl+Shift+I on Windows to toggle DevTools for the focused application page, including in packaged builds. These native shortcuts use hidden application-menu items. Update overlays and packaged embedded browser guests disable DevTools. +Press F12 (Fn+F12 on media-key keyboards), Command+Option+I on macOS, or Ctrl+Shift+I on Windows to toggle DevTools for the focused application page, including in packaged builds. The application menu shows a localized “Developer tools” command in a separate group before Hide and Quit (before Exit on Windows). Windows exposes it in the titlebar application popup; its hidden native application menu registers the shortcuts. macOS and Linux keep a hidden F12 shortcut alias in their application menus. Update overlays and packaged embedded browser guests disable DevTools. @@ -172,13 +175,7 @@ The signed `resources/app.asar/dsh/desktop-runtime.json` binds the shell version The [Web plugin UI](../../packages/client/ui-plugin-manager/README.md) owns the management interface. Desktop profile initialization and recovery preserve installed plugin files. -Fatal main-window creation, main-document loading, preload, renderer, Web initialization, or backend failures open one native recovery dialog per application process. It shows a bounded tail of the first error, notes any truncation, and offers Exit, Restart, and Disable third-party plugins, back up profile patch, and restart. Startup failures retain the Web loading page and spinner; runtime failures retain the current page. Expected shutdowns, cancelled navigation, and ordinary requests do not trigger recovery. The shared Web plugin manager reports package-operation errors; Host startup failures after plugin changes enter native recovery. There is no startup timeout heuristic. A listener failure containing `listen EADDRINUSE` replaces the diagnostics and reinstall advice with guidance to quit other running DSH instances, and offers only Exit and Restart. - -Native dialog details include at most 1,200 UTF-16 code units and eight diagnostic lines, plus the path of the crash report described below when one was written. Host error diagnostics retain only the last 64 Ki characters written to stderr. Earlier output is discarded so a long-running Host does not grow the shell’s diagnostic buffer indefinitely. - -Before the first fatal dialog opens, Electron writes a crash report to the platform logs directory (`app.getPath('logs')`: `~/Library/Logs/DeepSeek Harness` on macOS, `logs` under the application’s `userData` directory on Windows and Linux), waiting at most one second for the write; a slow or failed write shows the dialog without a path. The file `crash--.log` records the source (`host` for a Host exit, `web-boot` for a renderer boot failure, `renderer` for a renderer or document failure, `main` for a shell error), whether the backend had reached ready, application and runtime versions, the error with its enumerable properties and cause chain (cut at 256 KiB), the Host’s own inspected error (at most 64 KiB) when the Host reported a startup failure over IPC before exiting, and the primary window’s recent error-level console output (at most 64 KiB). A Host exit report therefore contains the retained stderr tail, which may include plugin output. A fatal failure during shutdown writes a report without opening a dialog. Files are owner-only where the platform supports it; startup keeps the ten newest reports and removes older ones without touching other files in the directory. - -Recovery waits for Host shutdown before changing plugin activation. The native recovery action calls the shared app-boot recovery function under the profile transaction lock. It disables third-party bundles and renames the profile’s `cordis.patch.yml` to `cordis.patch.yml.bak-` (with an ordinal on collisions) without parsing it; the next startup creates an empty patch. Installed packages and earlier backups remain. The home-level patch is unchanged. The Electron console records the backup path (or its absence) and the unchanged home-level patch. Invalid profile data, rename failures, or write failures are reported as recovery-operation errors; completed changes remain, and Desktop does not restart as though recovery succeeded. Desktop has no profile-reset action or emergency HTML document. +Desktop fatal failures use native recovery with Exit, Restart, Disable third-party plugins, back up profile patch, and restart, and Get diagnostic report. See [recovery and diagnostics](docs/diagnostics/README.md) for triggers, report locations and contents, recent operation records, and shutdown limits. ### Host environment @@ -356,6 +353,8 @@ The command builds the Desktop shell and runs its coordinator with real Electron The downloaded bytes are inert, and the installation call is recorded rather than executed. The test substitutes browser opening and clipboard writing to avoid external navigation and clipboard changes. It does not boot the full product workspace, qualify a real installer or restart, verify publisher signatures, or exercise differential updates or macOS. Stalled policy requests, feed requests, and payload transfers exercise real deadlines and recovery. The actual ordinary dialog verifies isolated preload loading, card geometry, an unfiltered parent page, cancellation, task-warning choices, and explicit installation approval; account-row component tests provide separate evidence. The [local qualification decision](../../.agents/notes/implemented/testing/2026-09-10-desktop-local-updater-qualification.md) and [verification record](tests/README.md) preserve these limits; production release requirements remain unchanged. +Native original-file operations accept only the trusted application frame. Completion returns the destination path to that frame; revealing it uses the existing Host path-opening API without a separate reveal IPC or saved-file history. Downloads use Chromium’s URL download and native save-dialog APIs; `DSH_DESKTOP_FILE_DOWNLOAD_TIMEOUT_MS` bounds startup until Chromium creates the download (300000 ms); the native save dialog has no application deadline. Clipboard-only remote image reads omit credentials, validate every redirect, reject the application Host and its loopback aliases, stop on main-frame navigation, and use `DSH_DESKTOP_IMAGE_READ_TIMEOUT_MS` (30000 ms) and `DSH_DESKTOP_IMAGE_READ_MAX_BYTES` (67108864 bytes). Image copying uses the renderer Clipboard API after PNG conversion. Other reachable HTTP(S) destinations follow deployment network isolation. [File actions](../../packages/client/ui-file-actions/README.md) defines saving and clipboard behavior. + ## Low-level development overrides diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md index c2078e9d30..933e329ce1 100644 --- a/apps/desktop/README.zh.md +++ b/apps/desktop/README.zh.md @@ -18,6 +18,7 @@ Desktop 在原生应用中运行 Harness 工作区。本参考文档说明应用 - [关键技术决策](#key-technical-decisions) - [内置命令运行时](#bundled-command-runtime) - [安装归属](#installation-ownership) +- [故障恢复与诊断](docs/diagnostics/README.zh.md) - [开发](#develop) - [打包](#package) - [Windows 安装界面](#windows-installer-interface) @@ -30,6 +31,8 @@ Desktop 在原生应用中运行 Harness 工作区。本参考文档说明应用 ## 应用概览 +Electron 在 `userData/desktop/locale-cache` 缓存最近确认的界面语言，使启动恢复弹窗在 Host 设置尚不可用时也能使用该语言。缓存缺失、无效或不可读时回退到系统语言；缓存写入失败不阻断启动。Host 成功启动或界面语言变更时会刷新缓存；在此之前，变更后的系统语言可能与缓存语言不同。 + 桌面埋点遵循[产品采集策略](../../packages/client/product-analytics/README.zh.md)及其动态应用配置，不包含 Web 使用情况。安装更新会等待该操作的本地埋点接收请求结束，再锁定 API 准入并停止 Host。接收请求的时限为一秒，失败不会阻止安装，也不等待收集端完成发送。 桌面应用是完整 dsh Web 应用外的一层 Electron 壳。Electron RunAsNode 子进程启动共享 profile runner，Electron 立即从 `dsh-app://app/` 加载打包内的 Web 入口。共享加载页等待 Host 启动注入，然后在同一文档中启动客户端。Electron 将应用 HTTP 请求转发给已认证的 Web Host，转发时丢弃描述 Node fetch 连接而非资源本身的响应头（`transfer-encoding`、`connection`、`keep-alive`），并把插件 bundle 响应标记为 `no-store`，因为其每次启动都变化的 revision 只会在 Chromium 磁盘缓存中累积；WebSocket 流连接到该 Host，仅为归属的应用窗口附加凭据。Node IPC 承载启动注入、就绪与关闭。Desktop 默认监听系统分配的端口，因此不会与 Web 的 `3080` 或系统保留端口冲突；可通过 `webserver.config.port` patch 覆盖。 @@ -40,7 +43,7 @@ Desktop 绑定 `127.0.0.1`，即 Electron 为就绪 URL 与 WebSocket 凭据过 Desktop 的本地原生目录流程打开绑定应用窗口的 Electron 文件夹对话框，并先恢复、显示和聚焦该窗口。并发请求共用一个对话框；取消不返回路径，失败后可以重试。普通 Web 使用 Host 选择器。浏览模式列出 Host 目录。Linux 缺少 zenity 或 kdialog 时，自动选择使用浏览模式，不使用 Electron 对话框。 -Desktop 在 `resources/runtime/primary-runtime/dependencies/pnpm` 中携带一份 pnpm 分发包。构建时的生产依赖安装、安装版 `dsh` CLI、Creator 和 Web 插件管理器通过 Electron Node 模式执行其中的 `bin/pnpm.mjs`；包操作不要求 PATH 上存在 pnpm。私有 Node 启动器环境仅用于包操作。agent（智能体）的工作区依赖将同一份完整 primary-runtime 复制到 Harness 主目录，并使用其中的独立 Node 执行 pnpm。 +Desktop 在 `resources/runtime/primary-runtime/dependencies/pnpm` 中携带一份 pnpm 分发包，不含其他目标平台的原生包。构建时的生产依赖安装、安装版 `dsh` CLI、Creator 和 Web 插件管理器通过 Electron Node 模式执行其中的 `bin/pnpm.mjs`；包操作不要求 PATH 上存在 pnpm。私有 Node 启动器环境仅用于包操作。agent（智能体）的工作区依赖将同一份完整 primary-runtime 复制到 Harness 主目录，并使用其中的独立 Node 执行 pnpm。 Platform 内嵌文档使用持久化 WebContentsView 分区，分区名由 Platform 来源和稳定账号 ID 的哈希决定。localStorage 中的页面偏好（包括已关闭的通知）在关闭视图和重启应用后保留；不同账号和来源使用独立存储。账号 ID 来自 Host 最近一次成功的资料读取；尚无该 ID 时，文档在一次性分区中打开，该分区不跨次保留偏好。打开持久分区会先清理 Cookie、文件系统、IndexedDB、Cache Storage、HTTP 与着色器缓存、Service Worker 及 HTTP 认证状态；一次性分区则清理其全部存储。关闭视图会销毁文档、移除请求拦截器并安排相同的清理，因此异常退出遗留的认证会在下一个文档加载前被清除。下次打开和应用退出都会等待该清理完成，更新安装也会在安装器接管退出前等待。清理失败会使该次打开失败，并在后续清理成功前阻止同一账号打开；其他账号不受影响。退出登录会销毁文档，但保留账号偏好供下次登录使用。同一凭证下账号 ID 迟到时，已以一次性分区打开的文档保持挂载；下次打开使用账号分区。[存储决策](../../.agents/notes/implemented/architecture/2026-09-22-platform-browser-storage.zh.md)说明保留策略。Host 通过私有 Node IPC 发送账号凭证；账号 RPC 和 Harness 渲染进程不接收 token。Platform preload 在页面脚本执行前通过一次同步 IPC 读取主进程中已准备的凭证。它暴露 displayMode、同步的 getAuthToken() 和 getLocale() getter，以及返回取消订阅函数的 onLocaleChange(listener)。两个 getter 都只读取 preload 内存，不再调用 IPC。bootstrap 包含 Desktop 已解析的语言（`zh_CN` 或 `en_US`）；Settings 语言变更会更新 preload 缓存并通知已打开的 Platform 文档，无需重载。Platform 在首屏渲染前应用该语言，且不将其持久化为浏览器偏好。主进程处理器仅校验调用来源并读取内存，不等待 Host、磁盘或网络。可信页面初始化失败时保留内嵌模式，由 getter 抛错，避免回退到浏览器凭证。只有受控 Platform 页面中、位于所配置签发来源的主 frame 能完成初始化。退登、凭证替换、Host 关闭及视图关闭都会销毁文档。跨来源文档导航被阻止。请求新窗口的 HTTPS 链接在系统浏览器中打开，不携带内嵌会话或 token；其他协议及带 URL 凭证的链接被拒绝。原生视图占据 Account 功能返回栏下方的视口。 @@ -50,7 +53,7 @@ Desktop Host 的 Platform API 请求与更新策略请求用相同的 Platform 桌面麦克风访问仅允许主 `dsh-app://app` 页面发起的音频请求。macOS 使用系统麦克风授权、随包用途说明，以及主应用与 Helper 签名中的 `com.apple.security.device.audio-input` 权限。 -按 F12（多媒体功能键键盘上为 Fn+F12）、macOS 的 Command+Option+I 或 Windows 的 Ctrl+Shift+I，可切换当前获得焦点的应用页面的 DevTools，打包版本同样支持。这些原生快捷键通过隐藏的应用菜单项注册。更新遮罩和打包版本的内嵌浏览器禁用 DevTools。 +按 F12（多媒体功能键键盘上为 Fn+F12）、macOS 的 Command+Option+I 或 Windows 的 Ctrl+Shift+I，可切换当前获得焦点的应用页面的 DevTools，打包版本同样支持。应用菜单在隐藏和退出命令之前的独立分组中显示本地化的“开发者工具”命令。Windows 在标题栏的应用弹出菜单中显示开关，通过隐藏的原生应用菜单注册快捷键；macOS 和 Linux 的应用菜单保留隐藏的 F12 快捷键别名。更新遮罩和打包版本的内嵌浏览器禁用 DevTools。 @@ -172,13 +175,7 @@ macOS 上自定义菜单保留 Electron 的标准 Window 菜单及应用隐藏 [Web 插件 UI](../../packages/client/ui-plugin-manager/README.zh.md)负责管理界面。Desktop profile 初始化和恢复保留已安装插件文件。 -主窗口创建、主文档加载、preload、渲染器、Web 初始化或后端的致命失败，会在每个应用进程中打开一次原生恢复对话框。对话框显示首次错误末尾的限长摘要，标明截断情况，并提供退出、重启、禁用第三方插件、备份 profile patch 并重启。启动失败保留 Web 加载页和动画；运行中失败保留当前页面。预期关闭、取消导航和普通请求错误不会触发恢复。共享 Web 插件管理器报告包操作错误；插件变更后的 Host 启动失败会进入原生恢复。不通过启动超时推断故障。 包含 `listen EADDRINUSE` 的监听失败以退出其他正在运行的 DSH 实例的提示替代诊断和重装建议，仅提供退出和重启。 - -原生弹窗详情最多包含 1,200 个 UTF-16 代码单元和八行诊断，若已写入下述崩溃报告则附上其路径。Host 错误诊断仅保留 stderr 输出的最后 64 Ki 个字符。更早的输出会被丢弃，避免长期运行的 Host 使壳的诊断缓冲区无限增长。 - -首个致命弹窗打开前，Electron 会向平台日志目录（`app.getPath('logs')`：macOS 为 `~/Library/Logs/DeepSeek Harness`，Windows 与 Linux 为应用 `userData` 目录下的 `logs`）写入一份崩溃报告，最多等待写入一秒；写入缓慢或失败时弹窗不带路径。文件 `crash--.log` 记录来源（`host` 为 Host 退出、`web-boot` 为渲染进程启动失败、`renderer` 为渲染进程或文档失败、`main` 为壳自身错误）、后端是否已就绪、应用与运行时版本、包含可枚举属性与 cause 链的错误（截至 256 KiB）、Host 在退出前通过 IPC 报告启动失败时自己的 inspect 错误（最多 64 KiB），以及主窗口最近的 error 级 console 输出（最多 64 KiB）。因此 Host 退出报告包含保留的 stderr 尾部，其中可能含有插件输出。关闭过程中的致命失败只写报告、不弹窗。平台支持时文件仅所有者可读；启动时保留最新十份报告并删除更早的，不触碰目录中的其他文件。 - -恢复操作等待 Host 关闭后才修改插件启用状态。原生恢复操作在 profile 事务锁内调用共享 app-boot 恢复函数。它禁用第三方 bundle，并将 profile 的 `cordis.patch.yml` 重命名为 `cordis.patch.yml.bak-`（重名时追加序号），无需解析；下次启动创建空 patch。已安装包和已有备份保留。home 级 patch 不变。Electron 控制台记录备份路径（或原文件不存在）以及 home 级 patch 未修改。profile 数据无效、重命名失败或写入失败会作为恢复操作错误报告；已完成的修改保留，Desktop 不会假装恢复成功后重启。Desktop 不提供 profile 重置操作或应急 HTML 文档。 +Desktop 的致命故障通过原生恢复对话框提供退出、重启、禁用第三方插件并备份 profile patch 后重启，以及获取诊断报告。触发范围、报告位置与内容、近期操作记录和退出限制见[故障恢复与诊断](docs/diagnostics/README.zh.md)。 ### Host 环境 @@ -356,6 +353,8 @@ node apps/desktop/node_modules/pnpm/bin/pnpm.mjs --dir apps/desktop run test:upd 下载内容是不可执行的测试字节，安装调用仅记录而不执行。测试替换浏览器打开与剪贴板写入，避免外部导航和剪贴板修改。它不启动完整产品工作区，不验证真实安装器或重启，不验证发布者签名，也不覆盖差分更新或 macOS。停滞的策略请求、清单请求和负载传输会执行真实截止时间及恢复。真实常规弹窗验证隔离预加载、卡片尺寸、未施加模糊的父页面、取消、任务警告选项与显式安装批准；账户行组件测试另行提供证据。[本地验证决策](../../.agents/notes/implemented/testing/2026-09-10-desktop-local-updater-qualification.zh.md)和[验证记录](tests/README.zh.md)保留这些限制；生产发布要求保持不变。 +原生原始文件操作仅接受可信应用页面。完成后向该页面返回目标路径；显示位置复用现有 Host 路径打开 API，不提供独立 reveal IPC，也不保留已保存文件历史。下载使用 Chromium URL 下载和原生保存对话框 API；`DSH_DESKTOP_FILE_DOWNLOAD_TIMEOUT_MS` 限定 Chromium 创建下载前的启动期限（300000 毫秒），不限制原生保存对话框的停留时间。仅剪贴板使用的远程图片读取不携带凭据，逐次校验重定向，拒绝应用 Host 及其回环别名，在主框架导航时终止，并使用 `DSH_DESKTOP_IMAGE_READ_TIMEOUT_MS`（30000 毫秒）与 `DSH_DESKTOP_IMAGE_READ_MAX_BYTES`（67108864 字节）。图片复制在转换为 PNG 后使用渲染进程的 Clipboard API。其他可达的 HTTP(S) 目标遵循部署侧网络隔离。[文件操作](../../packages/client/ui-file-actions/README.zh.md) 定义保存和剪贴板行为。 + ## 底层开发覆盖项 diff --git a/apps/desktop/config/publishing/macos/production.json.example b/apps/desktop/config/publishing/macos/production.json.example new file mode 100644 index 0000000000..cb7f67a0a4 --- /dev/null +++ b/apps/desktop/config/publishing/macos/production.json.example @@ -0,0 +1,13 @@ +{ + "bucket": "replace-with-bucket-1250000000", + "origin": "https://download.deepseek.com", + "credentialsFile": "/absolute/path/to/packaging/secrets/cos-production.json", + "macOS": { + "signingIdentity": "REPLACE_WITH_DEVELOPER_ID_APPLICATION_IDENTITY", + "teamId": "XXXXXXXXXX" + }, + "githubApp": { + "clientId": "REPLACE_WITH_GITHUB_APP_CLIENT_ID", + "privateKeyFile": "/absolute/path/to/packaging/publishing/keys/desktop-release-tagger.pem" + } +} diff --git a/apps/desktop/config/publishing/macos/test.json.example b/apps/desktop/config/publishing/macos/test.json.example new file mode 100644 index 0000000000..6981a88c6b --- /dev/null +++ b/apps/desktop/config/publishing/macos/test.json.example @@ -0,0 +1,9 @@ +{ + "bucket": "replace-with-bucket-1250000000", + "origin": "https://download-test.example.com", + "credentialsFile": "/absolute/path/to/packaging/secrets/cos-test.json", + "macOS": { + "signingIdentity": "REPLACE_WITH_DEVELOPER_ID_APPLICATION_IDENTITY", + "teamId": "XXXXXXXXXX" + } +} diff --git a/apps/desktop/config/publishing/windows/production.json.example b/apps/desktop/config/publishing/windows/production.json.example new file mode 100644 index 0000000000..9a2a743227 --- /dev/null +++ b/apps/desktop/config/publishing/windows/production.json.example @@ -0,0 +1,12 @@ +{ + "bucket": "replace-with-bucket-1250000000", + "origin": "https://download.deepseek.com", + "credentialsFile": "C:/absolute/path/to/packaging/secrets/cos-production.json", + "windows": { + "certificateThumbprint": "0000000000000000000000000000000000000000" + }, + "githubApp": { + "clientId": "REPLACE_WITH_GITHUB_APP_CLIENT_ID", + "privateKeyFile": "C:/absolute/path/to/packaging/publishing/keys/desktop-release-tagger.pem" + } +} diff --git a/apps/desktop/config/publishing/windows/test.json.example b/apps/desktop/config/publishing/windows/test.json.example new file mode 100644 index 0000000000..cf3e1a40a1 --- /dev/null +++ b/apps/desktop/config/publishing/windows/test.json.example @@ -0,0 +1,8 @@ +{ + "bucket": "replace-with-bucket-1250000000", + "origin": "https://download-test.example.com", + "credentialsFile": "C:/absolute/path/to/packaging/secrets/cos-test.json", + "windows": { + "certificateThumbprint": "0000000000000000000000000000000000000000" + } +} diff --git a/apps/desktop/docs/diagnostics/README.i18n.yaml b/apps/desktop/docs/diagnostics/README.i18n.yaml new file mode 100644 index 0000000000..44994b4b1e --- /dev/null +++ b/apps/desktop/docs/diagnostics/README.i18n.yaml @@ -0,0 +1,28 @@ +# Bilingual-pair consistency record for README.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 apps/desktop/docs/diagnostics/README.md +/: + en: 29d76ee1849cd8fd + zh: a2b8cbabe79557f9 +/desktop-recovery-and-diagnostics: + en: 4d4fd8a92047e5c6 + zh: 15ec51d703ccd70b +/desktop-recovery-and-diagnostics/summary: + en: e61d0f55e426aa6f + zh: dc13c7e054eac9d1 +/desktop-recovery-and-diagnostics/table-of-contents: + en: 8f3a2a84eaf575af + zh: 3087306f10e7c2cf +/desktop-recovery-and-diagnostics/recover-from-a-failure: + en: 9d0645dba352979d + zh: e1556207a04d9a71 +/desktop-recovery-and-diagnostics/report-contents: + en: 1a2eb71ac2dccf63 + zh: 5cf59639d3e49591 +/desktop-recovery-and-diagnostics/recent-operation-records: + en: f1c19c1516a51ab6 + zh: b350f7c18086d274 +/desktop-recovery-and-diagnostics/collection-and-shutdown: + en: bac4a49f63d4aaf8 + zh: df1ae908ee2148e1 diff --git a/apps/desktop/docs/diagnostics/README.md b/apps/desktop/docs/diagnostics/README.md new file mode 100644 index 0000000000..e0e72c3f1e --- /dev/null +++ b/apps/desktop/docs/diagnostics/README.md @@ -0,0 +1,76 @@ +--- +description: "Use this reference when recovering Desktop failures or collecting reports; it explains report contents, operation history, and shutdown limits." +--- + +# Desktop recovery and diagnostics + +English | [中文](README.zh.md) + +## Summary + +This reference describes Desktop native failure recovery, diagnostic reports, recent plugin operation records, and collection and shutdown limits. + +## Table of Contents + +- [Recover from a failure](#recovery) +- [Report contents](#report-contents) +- [Recent operation records](#operation-records) +- [Collection and shutdown](#collection-and-shutdown) + + + +## Recover from a failure + +Fatal main-window creation, main-document loading, preload, renderer, Web initialization, or backend failures open one native recovery dialog per application process. It shows a bounded tail of the first error, notes any truncation, and offers “Exit”, “Restart”, “Disable third-party plugins, back up profile patch, and restart”, and “Get diagnostic report” while report writing is pending or after it succeeds. Startup failures retain the Web loading page and spinner; runtime failures retain the current page. Expected shutdowns, cancelled navigation, and ordinary requests do not trigger recovery. The shared Web plugin manager reports package-operation errors; Host startup failures after plugin changes enter native recovery. There is no startup timeout heuristic. A listener failure containing `listen EADDRINUSE` replaces the diagnostics and reinstall advice with guidance to quit other running DSH instances, and offers “Exit”, “Restart”, and “Get diagnostic report” while report writing is pending or after it succeeds. + +Recovery uses the last confirmed Desktop language from the local cache before Host settings are available; an absent or invalid cache falls back to system languages. + +Recovery waits for Host shutdown before changing plugin activation. The native recovery action calls the shared app-boot recovery function under the profile transaction lock. It disables third-party bundles and renames the profile’s `cordis.patch.yml` to `cordis.patch.yml.bak-` (with an ordinal on collisions) without parsing it; the next startup creates an empty patch. Installed packages and earlier backups remain. The home-level patch is unchanged. The Electron console records the backup path (or its absence) and the unchanged home-level patch. Invalid profile data, rename failures, or write failures are reported as recovery-operation errors; completed changes remain, and Desktop does not restart as though recovery succeeded. Desktop has no profile-reset action or emergency HTML document. + + + +## Report contents + +Native dialog details include at most 1,200 UTF-16 code units and eight diagnostic lines, plus the crash report path or its pending/unavailable status. Retrieving a pending or unavailable report preserves any recovery-operation failure headline and details. Configuration paths and startup entries precede the composition inventory so plugin rows cannot displace them when output is truncated. Host error diagnostics retain only the last 64 Ki characters written to stderr. Earlier output is discarded so a long-running Host does not grow the shell’s diagnostic buffer indefinitely. + +Before the first fatal dialog opens, Electron writes a crash report to the platform logs directory (`app.getPath('logs')`: `~/Library/Logs/DeepSeek Harness` on macOS, `logs` under the application’s `userData` directory on Windows and Linux), waiting at most one second for the write; a slow or failed write shows the dialog with an explicit pending or unavailable status. Get diagnostic report checks the same write and reveals a saved file in the system file manager without restarting or stopping the Host; a write that completes after the initial deadline remains available. The user attaches that file to a support ticket. The attachment contains the original failure; later recovery-operation errors remain in the dialog and require a separate screenshot. Retrieving a saved report shows its sharing or reveal-failure heading while retaining the recovery error details. If writing fails, the dialog hides Get diagnostic report and suggests providing a screenshot. + +The file `crash--.log` records the source (`host` for a Host exit, `web-boot` for a renderer boot failure, `renderer` for a renderer or document failure, `main` for a shell error), whether the backend had reached ready, application and runtime versions, the error with its enumerable properties and cause chain (cut at 256 KiB), the Host’s own error and explicitly selected startup metadata (at most 64 Ki characters, including a truncation notice; startup errors reserve space for metadata by limiting the original error and startup-entry details to 8 Ki characters each, with explicit truncation notices) when the Host reported a startup failure over IPC before exiting, and the primary window’s recent error-level console output (at most 64 KiB). + +A Host exit report therefore contains the retained stderr tail, which may include plugin output. A fatal failure during shutdown writes a report without opening a dialog. Files are owner-only where the platform supports it; startup keeps the ten newest reports and removes older ones without touching other files in the directory. + + + +## Recent operation records + +Operation records and the application single-instance lock are isolated by `userData`; the shared platform logs directory does not store operation records. The reader only reads the two operation files under `userData/plugin-operations`. Repairing an unfinished append preserves complete lines in the current segment and the previous segment. + +Version-exemption changes reuse the bundle enable/disable record fields. When the exemption and installed versions match, the record cannot distinguish an exemption change from a bundle toggle. + +Host `transportDropped` is a lower bound as of the last successful delivery; Desktop rejects malformed or mismatched-run records without adding them to that counter. + +The journal retains two 256 KiB segments, accepts records up to 4 KiB, and bounds queued writes to 64 KiB. + +Exit, recovery restart and installer preparation wait at most 500 ms for queued writes; a timeout disables further writes and later drains return immediately without another wait, while an already-issued OS request may still settle. + +Records cover manager operations observed after Host startup, not direct CLI commands or manual file changes. Package-manager output remains in its existing detailed logs and is not copied into this summary. Missing records, a start without an end, and damaged history do not establish a successful operation. This collection does not diagnose kernel hangs, OOM or native crashes. + +Persistence failures also disable the writer for the rest of this shell lifetime, including after recovery or installer failure. This bounds repeated failing I/O and avoids appending behind an uncertain partial write. Restarting the application creates a new writer. Omission and repair counters cover only the current shell lifetime. Retained segments provide a larger local troubleshooting window than the deliberately smaller report attachment. + + + +## Collection and shutdown + +After saving the basic report, the shell attempts to append recent plugin-management records in an isolated Worker packaged as `lib/operation-report-worker.js` inside `app.asar`. The completion marker and omission counters distinguish a finished collection from missing or partial material. + +The Host announces its run ID before profile loading; reported Host errors carry that ID as `hostRunId`, matching operation records from the same lifetime. Failure before this announcement leaves the run identity unknown. Recent operations are context, not proof of cause. + +Collection reads only two owned files under `userData/plugin-operations`, at most 64 KiB and 100 records; the complete appended section is limited to 64 KiB. + +The 500 ms collection budget reserves its final 100 ms for cooperative cancellation before requesting forced Worker termination; completion waits for its exit. Application exit, recovery exit or restart, and confirmed update installation also cancel collection and wait at most 500 ms for Worker exit. A rejected shutdown cleanup is logged without skipping the remaining cleanup waits. Shutdown prevents late basic-report saves from starting another collector. An update installation failure permits future collection again. + +Worker messages interrupt collection between bounded records; an in-flight file open, stat, read or close must settle, and synchronous parsing cannot be preempted within one record. The final append uses an abort signal but can leave partial bytes. Forced termination remains the fallback when cooperative cleanup does not finish. + +The basic report remains available independently. Only one collector runs at a time; concurrent reports keep their basic content without an auxiliary section. A rejected termination request does not release that slot until exit is observed. Get diagnostic report can reveal the basic file before the append finishes. The completion marker confirms only that collection ended, not that all operations were captured; queued bytes and omission counters describe missing material. + +See [local verification](../../tests/README.md#verification-diagnostics) for fault setup and acceptance steps, and the [Desktop README](../../README.md) for the application overview and development entry points. diff --git a/apps/desktop/docs/diagnostics/README.zh.md b/apps/desktop/docs/diagnostics/README.zh.md new file mode 100644 index 0000000000..8e25e9721a --- /dev/null +++ b/apps/desktop/docs/diagnostics/README.zh.md @@ -0,0 +1,76 @@ +--- +description: "排查 Desktop 故障或收集报告时阅读，了解恢复操作、报告内容、操作历史和退出限制。" +--- + +# Desktop 故障恢复与诊断 + +[English](README.md) | 中文 + +## 概述 + +本参考文档说明 Desktop 的原生故障恢复、诊断报告、近期插件操作记录，以及采集和退出时的限制。 + +## 目录 + +- [遇到故障怎么办](#recovery) +- [报告包含什么](#report-contents) +- [近期操作记录](#operation-records) +- [采集与退出行为](#collection-and-shutdown) + + + +## 遇到故障怎么办 + +主窗口创建、主文档加载、preload、渲染器、Web 初始化或后端的致命失败，会在每个应用进程中打开一次原生恢复对话框。对话框显示首次错误末尾的限长摘要，标明截断情况，并提供“退出”“重启”“禁用第三方插件、备份 profile patch 并重启”，以及报告仍在保存或已保存时的“获取诊断报告”。启动失败保留 Web 加载页和动画；运行中失败保留当前页面。预期关闭、取消导航和普通请求错误不会触发恢复。共享 Web 插件管理器报告包操作错误；插件变更后的 Host 启动失败会进入原生恢复。不通过启动超时推断故障。包含 `listen EADDRINUSE` 的监听失败以退出其他正在运行的 DSH 实例的提示替代诊断和重装建议，提供“退出”“重启”，以及报告仍在保存或已保存时的“获取诊断报告”。 + +Host 设置可用前，恢复对话框使用本地缓存中最后确认的 Desktop 语言；缓存不存在或无效时回退到系统语言。 + +恢复操作等待 Host 关闭后才修改插件启用状态。原生恢复操作在 profile 事务锁内调用共享 app-boot 恢复函数。它禁用第三方 bundle，并将 profile 的 `cordis.patch.yml` 重命名为 `cordis.patch.yml.bak-`（重名时追加序号），无需解析；下次启动创建空 patch。已安装包和已有备份保留。home 级 patch 不变。Electron 控制台记录备份路径（或原文件不存在）以及 home 级 patch 未修改。profile 数据无效、重命名失败或写入失败会作为恢复操作错误报告；已完成的修改保留，Desktop 不会假装恢复成功后重启。Desktop 不提供 profile 重置操作或应急 HTML 文档。 + + + +## 报告包含什么 + +原生弹窗详情最多包含 1,200 个 UTF-16 代码单元和八行诊断，并附上崩溃报告路径或仍在保存、无法保存的状态。获取仍在保存或无法保存的报告时，保留恢复操作失败的标题和详情。配置路径和启动条目排在组合清单之前，避免输出截断时被插件记录挤掉。Host 错误诊断仅保留 stderr 输出的最后 64 Ki 个字符。更早的输出会被丢弃，避免长期运行的 Host 使壳的诊断缓冲区无限增长。 + +首个致命弹窗打开前，Electron 会向平台日志目录（`app.getPath('logs')`：macOS 为 `~/Library/Logs/DeepSeek Harness`，Windows 与 Linux 为应用 `userData` 目录下的 `logs`）写入一份崩溃报告，最多等待写入一秒；写入缓慢或失败时明确显示仍在保存或无法保存。“获取诊断报告”检查同一次写入，并在系统文件管理器中定位已保存的文件，不停止 Host 或重启；超过首次等待期限后写入完成的文件仍可获取。用户可将文件作为工单附件。附件只包含最初的故障；后续恢复操作错误保留在对话框中，需要另行截图。获取已保存报告会显示分享或打开失败的标题，同时保留恢复错误详情。写入失败时隐藏获取报告按钮，并提示提供窗口截图。 + +文件 `crash--.log` 记录来源（`host` 为 Host 退出、`web-boot` 为渲染进程启动失败、`renderer` 为渲染进程或文档失败、`main` 为壳自身错误）、后端是否已就绪、应用与运行时版本、包含可枚举属性与 cause 链的错误（截至 256 KiB）、Host 在退出前通过 IPC 报告启动失败时的错误及显式选择的启动元数据（最多 64 Ki 个字符，包含截断提示；启动错误的原始错误文本和启动条目详情分别限制为 8 Ki 个字符，并明确标注截断，为结构化元数据保留空间），以及主窗口最近的 error 级 console 输出（最多 64 KiB）。 + +因此 Host 退出报告包含保留的 stderr 尾部，其中可能含有插件输出。关闭过程中的致命失败只写报告、不弹窗。平台支持时文件仅所有者可读；启动时保留最新十份报告并删除更早的，不触碰目录中的其他文件。 + + + +## 近期操作记录 + +操作记录目录与应用单实例锁均按 `userData` 隔离；共享平台日志目录不用于保存操作记录。读取器只读取 `userData/plugin-operations` 下的两个操作记录文件。修复未写完的尾行时保留当前段的完整行与上一段。 + +版本豁免变更复用 bundle 启停记录字段。豁免版本与安装版本相同时，记录无法区分豁免变更与 bundle 开关。 + +Host 的 `transportDropped` 只表示最近一次成功发送时的计数下界；Desktop 拒绝的非法或运行 ID 不匹配记录不计入该值。 + +操作历史保留两个 256 KiB 文件段，单条记录不超过 4 KiB，排队写入不超过 64 KiB。 + +退出、恢复重启和安装准备最多等待排队写入 500 ms；超时会停用后续写入，此后的排空调用立即返回，不会再次等待；但已经发出的操作系统请求仍可能随后结束。 + +记录覆盖 Host 启动后观察到的管理器操作，不包含直接执行的 CLI 命令或手工文件修改。包管理器输出保留在原有详细日志中，不复制到摘要。缺失记录、只有开始没有结束的操作以及损坏的历史，都不能说明操作已成功。此收集不诊断内核卡死、OOM 或原生崩溃。 + +持久化失败也会在本次壳生命周期内停用写入，包括恢复或安装器失败后继续运行的情况，以限制重复失败的 I/O，并避免在可能残缺的写入后追加记录。重启应用会创建新写入器。遗漏和修复计数仅覆盖当前壳生命周期。保留文件段提供比报告附件更大的本地排障历史窗口。 + + + +## 采集与退出行为 + +基本报告保存后，壳会尝试通过独立 Worker 追加近期插件管理记录；该 Worker 以 `lib/operation-report-worker.js` 打包在 `app.asar` 中。完成标记和遗漏计数用于区分已完成收集与缺失或不完整的材料。 + +Host 在加载 profile 前报告运行 ID；Host 错误中的 `hostRunId` 与该次运行的操作记录使用同一标识。在此通知之前发生的失败，其运行标识仍为未知。近期操作只是上下文，不是因果证据。 + +收集只读取 `userData/plugin-operations` 下归其管理的两个文件，最多读取 64 KiB 和 100 条记录；完整追加内容不超过 64 KiB。 + +500 ms 收集预算中的最后 100 ms 用于协作取消，随后才请求强制终止 Worker；只有 Worker 退出后才确认收集结束。应用退出、恢复退出或重启、确认安装更新也会取消收集，并最多等待 500 ms 确认 Worker 退出。退出清理中的拒绝会被记录，但不会跳过其他清理等待。退出过程中，延迟保存完成的基本报告不会再启动收集器。更新安装失败后可再次收集。 + +Worker 在有界记录之间处理取消消息；已经发出的文件打开、状态读取、读取或关闭操作必须等待完成，单条记录的同步解析不能被抢占。最后的追加写入传入取消信号，但仍可能留下部分字节。协作清理未及时完成时仍需强制终止。 + +基本报告独立可用。同时只运行一个收集器；并发报告保留基本内容，不追加辅助部分。终止请求被拒绝时，必须观察到退出才能释放该名额。“获取诊断报告”可能在追加完成前定位基本文件。完成标记仅表示收集结束，不表示捕获了全部操作；排队字节数和遗漏计数说明缺失材料。 + +故障构造与验收步骤见[本地验证](../../tests/README.zh.md#verification-diagnostics)；应用概览与开发入口见 [Desktop README](../../README.zh.md)。 diff --git a/apps/desktop/package.json b/apps/desktop/package.json index f8c411c367..40bdfefe27 100644 --- a/apps/desktop/package.json +++ b/apps/desktop/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-desktop", "description": "Electron desktop shell for a bundled dsh runtime and external plugins", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "private": true, "license": "MIT", "author": { @@ -43,7 +43,8 @@ "upload:win:x64": "tsx scripts/upload-target.ts win-x64", "upload:latest:mac:arm64": "tsx scripts/upload-target.ts mac-arm64 --latest", "upload:latest:mac:x64": "tsx scripts/upload-target.ts mac-x64 --latest", - "upload:latest:win:x64": "tsx scripts/upload-target.ts win-x64 --latest" + "upload:latest:win:x64": "tsx scripts/upload-target.ts win-x64 --latest", + "purge:latest": "tsx scripts/upload-target.ts --latest --purge-only" }, "dependencies": { "electron-updater": "^6.8.9", @@ -84,6 +85,10 @@ "@deepseek-ai/dsh-client-shortcuts": "workspace:*", "@deepseek-ai/dsh-atomic-write": "workspace:*", "@deepseek-ai/dsh-client-product-analytics": "workspace:*", - "@deepseek-ai/dsh-util-file-drag": "workspace:*" + "@deepseek-ai/dsh-plugin-manager": "workspace:*", + "zod": "4.4.3", + "@deepseek-ai/dsh-util-file-drag": "workspace:*", + "@deepseek-ai/dsh-client-ui-file-actions": "workspace:*", + "tencentcloud-sdk-nodejs-teo": "4.1.330" } } diff --git a/apps/desktop/packaging/README.i18n.yaml b/apps/desktop/packaging/README.i18n.yaml index 7a9ff55492..c39bb71bc3 100644 --- a/apps/desktop/packaging/README.i18n.yaml +++ b/apps/desktop/packaging/README.i18n.yaml @@ -24,11 +24,11 @@ en: 5b4f0f80a117f202 zh: ff05be196c181087 /desktop-packaging/windows-actions-packaging: - en: 364223725374d9ac - zh: c4d4cc58d7cbafbd + en: 253e17998951931c + zh: b582b377391d2ec2 /desktop-packaging/macos-self-hosted-packaging: - en: bb1dcdfef3f3a113 - zh: 9c151800a61e2505 + en: f4cc5209bdaeefba + zh: 1db959d1ed345fcc /desktop-packaging/unsigned-windows-test-installer: en: f429bc0c280e2dfa zh: 4adbcc9e906bdf80 diff --git a/apps/desktop/packaging/README.md b/apps/desktop/packaging/README.md index 14c1eac90b..28aa9ff9c7 100644 --- a/apps/desktop/packaging/README.md +++ b/apps/desktop/packaging/README.md @@ -109,17 +109,15 @@ Each target owns its packed package inputs, prepared runtime, package set, dsh t For supervised runner startup and recovery, follow [Windows runner machine setup](../windows-signing/README.md#machine-setup). -The `Package Desktop · Windows` [manual workflow](../../../.github/workflows/windows-package.yml) selects the dedicated Windows x64 runner label `dsh-win-package-trial` and the machine preset `test` or `production`. Choose `signed` (default) or `unsigned`; signed mode uses the existing EV token preflight, signature cache and failure interlock. It does not publish or upload a release. `build_version` defaults to `auto`, using the CI identifier in [Release versions](#release-versions); an explicit value may be the checkout's product version or an extended build version such as `0.2.1-alpha.1.20261009.1` for product `0.2.1-alpha.1`. The version prefix must match the selected checkout; validation errors show its current example. Manifests remain unchanged. +The `Package Desktop · Windows · x64` [manual workflow](../../../.github/workflows/windows-package.yml) selects the dedicated Windows x64 runner label `dsh-win-package-trial` and the machine preset `test` or `production`. Choose `signed` (default) or `unsigned`; signed mode uses the existing EV token preflight, signature cache and failure interlock. It does not publish or upload a release. `build_version` defaults to `auto`, using the CI identifier in [Release versions](#release-versions); an explicit value may be the checkout's product version or an extended build version such as `0.2.1-alpha.1.20261009.1` for product `0.2.1-alpha.1`. The version prefix must match the selected checkout; validation errors show its current example. Manifests remain unchanged. Select the workflow in Actions, choose the source branch, preset, signing mode and version, then click Run workflow. Before merging input changes, test the pushed branch with `gh workflow run windows-package.yml --ref -f preset=test -f signing=unsigned -f build_version=auto`; verify the web form after merging. There is no push or PR trigger. Logs and successful EXEs are retained for 14 days. Inspect the retained logs and installer before relying on packaging; installation is separate. Before checkout, Node removes the runner-owned source directory without following dependency junctions; the workflow validates its location and rejects linked ancestors. Never point it at a development checkout. Runs share one concurrency group without cancelling an active build; only one run remains pending, and a newer dispatch replaces it. Diagnostics upload requires a successful clean checkout. Machine settings stay outside the checkout and are never uploaded as artifacts. Open the completed run in Actions and download its Artifacts. `windows-x64-signed---` and `windows-x64-unsigned---` contain the corresponding EXE; `windows-package-logs--` contains packaging diagnostics. The upload steps are `Retain verified signed installer`, `Retain verified unsigned installer`, and `Retain packaging diagnostics`; their step durations and timestamped logs show upload time. These artifacts are not a Release or download-site publication. -For path-sensitive Windows build measurements, `build_root` optionally selects an absolute directory outside existing Git checkouts. Each run clones the validated source commit into a new `windows-package--/source` directory; ignored files and previous build outputs are not copied. Only the packaging process uses a sibling run-owned `temp` directory through `TEMP` and `TMP`; Actions steps and post-job hooks retain their original temporary directories. Dependency and signing caches retain their existing locations. Successful runs remove only their owned checkout after artifact uploads, retrying transient filesystem failures up to three times with 100 ms increasing delays; persistent cleanup errors fail the Job and may leave a partially removed directory. Failed builds retain their checkout for inspection. Leave the input empty to build in the original Actions checkout. Include checkout creation and cleanup in the complete Job timing. - For cache measurements, `cache_namespace` selects a retained subdirectory for both dependency stores and upstream downloads; leave it empty for normal shared caches. Use a new name for a cold sample and repeat that name for warm samples. Names contain 1–64 lowercase letters, digits or hyphens, start with a letter or digit, and cannot be Windows device names. This does not reset the separate signature cache or OS file cache; report those states and Job start-to-completion time alongside phase timings and artifact size. Before dependency installation, the workflow records the Node version, available CPU parallelism, logical CPU count, and total/free memory. -The dependency-install and packaging steps normalize their own shell to normal CPU, I/O and memory priority before launching children. Priority and isolated-workspace helpers are copied from the exact workflow commit into a run-specific temporary directory, independently of the selected product source. Missing helpers stop CI setup; unavailable priority adjustment emits a warning and marks scheduling unsuitable for performance comparison, but does not stop packaging. This does not modify the runner task or other processes. Version, preset and retained-artifact adapters remain tied to product source and its formats. +The dependency-install and packaging steps normalize their own shell to normal CPU, I/O and memory priority before launching children. The priority helper is copied from the exact workflow commit into a run-specific temporary directory, independently of the selected product source. A missing helper stops CI setup; unavailable priority adjustment emits a warning and marks scheduling unsuitable for performance comparison, but does not stop packaging. This does not modify the runner task or other processes. Version, preset and retained-artifact adapters remain tied to product source and its formats. Installer uploads store the already-compressed release files without ZIP recompression; this preserves installer bytes and signatures. Diagnostic uploads retain their ordinary compression. @@ -127,13 +125,14 @@ Installer uploads store the already-compressed release files without ZIP recompr ## macOS self-hosted packaging -The `Package Desktop · macOS` [manual workflow](../../../.github/workflows/macos-package.yml) targets an Apple Silicon runner labeled `dsh-mac-package-trial`. It selects `test` or `production`, resolves `build_version=auto` from the UTC date, run number and attempt, and uses the existing signing, notarization and packaged-runtime checks. Installer upload disables redundant ZIP compression; diagnostic logs retain normal compression. Successful DMG/ZIP files and diagnostic logs are retained for 14 days; this workflow does not publish a release. The operator must register the runner and verify a complete Actions run before relying on it. The `zip_compression_level` dropdown defaults to `3` and also offers `7`; it overrides the machine preset for this run and affects only the ZIP and automatic-update downloads, not the DMG. +The [Apple Silicon workflow](../../../.github/workflows/macos-package.yml) and [Intel workflow](../../../.github/workflows/macos-intel-package.yml) produce separate arm64 and x64 packages on the Apple Silicon runner labeled `dsh-mac-package-trial`. Both share one concurrency group. The Intel workflow checks Rosetta execution before dependency installation; its selected source must include the target-aware macOS CI adapter. Both select `test` or `production` and use the existing signing, notarization and packaged-runtime checks. Successful DMG/ZIP files and diagnostic logs are retained for 14 days without publishing a release. Installer uploads disable redundant ZIP compression. The operator must verify a complete Actions run and installation on the target architecture before release qualification. The `compression_level` dropdown defaults to `3` and also offers `7`; it overrides the machine preset for this run and affects only ZIP and automatic-update downloads, not DMG. + +All three platform forms put source, environment, update channel, version mode, manual version, test release ID and compression level first, with matching defaults. macOS notarization and Windows signing and cache measurement options follow these common fields. Run `node apps/desktop/scripts/setup-macos-packaging.mjs "$HOME/dsh-ci"` to prepare private `runner/`, `packaging/{presets,secrets,certificates}` and `cache/macos-signatures` directories without overwriting existing files; append `--check` to inspect them. Fill the [preset](../config/macos-packaging/test.env.example) and [signing](../config/macos-packaging/macos-signing.env.example) templates outside the checkout. Set secret and certificate files to mode `0600`. `DSH_PACKAGING_CONFIG_DIR` selects the absolute `packaging` directory and `DSH_PACKAGING_PRESET` selects its preset; missing files fail without falling back to `.env.macos`. Signed and preparation-only Mac builds read `secrets/macos-signing.env`; relative credential paths resolve beside that file. Public presets reject signing credentials, and signing files cannot override public settings. Local unsigned Mac builds retain their configuration-free behavior. Run `bash apps/desktop/scripts/start-macos-packaging-runner.sh "$HOME/dsh-ci/runner" "$HOME/dsh-ci/packaging" --check` to check the host tools and configuration files. The script selects the active Xcode and its macOS SDK together and compiles a small linker probe. After registration, omit `--check` to run in the foreground with a cleared inherited environment and prevent idle sleep while the runner is alive. Stop it with Ctrl-C before installing the service below. The runner owns its `_work` checkout, separate from daily development. The account can read its signing files, so run only trusted code. The existing notarization proxy restoration rules apply; after forced termination, inspect retained recovery records before another build. New setup templates set `DSH_DESKTOP_MACOS_SIGNATURE_CACHE_DIR` to the absolute `cache/macos-signatures` directory outside checkout. For existing installations, rerun setup and add that field to each preset; existing files are preserved. This retains signatures across clean checkouts; cache verification and limits are described under [macOS signing](#macos-release-signing). - ZIP compression uses the same configured level with or without notarization; the App is assembled once, then DMG and ZIP are built separately so the ZIP setting does not change DMG compression. The `skip_notarization` workflow option defaults to `false`; the equivalent CLI flag is `--skip-notarization`. It retains Developer ID signing, DMG signature verification and packaged-runtime verification, but omits Apple notarization and stapling and does not require Apple notarization credentials. DMG/ZIP filenames carry `-unnotarized`, are stored under `.desktop-build/targets//unnotarized-artifacts/`, and are uploaded with an `unnotarized-debug` label. These artifacts are for internal debugging only: Gatekeeper may block downloaded copies, and they are not qualified for distribution or update publishing. No release completion record is written. The flag rejects unsigned, Windows and preparation-only builds. Install the user service from the checkout as the same account that registered the runner, without `sudo`: diff --git a/apps/desktop/packaging/README.zh.md b/apps/desktop/packaging/README.zh.md index 0f059c74a4..2e87933826 100644 --- a/apps/desktop/packaging/README.zh.md +++ b/apps/desktop/packaging/README.zh.md @@ -109,17 +109,15 @@ macOS 正式发布和本地未签名 DMG 都通过 [electron-builder 配置](../ runner 的受监督启动和恢复见 [Windows runner 机器准备](../windows-signing/README.zh.md#machine-setup)。 -`Package Desktop · Windows` [手动工作流](../../../.github/workflows/windows-package.yml) 选择专用 Windows x64 runner 标签 `dsh-win-package-trial`，并使用机器 preset `test` 或 `production`。选择 `signed`（默认）或 `unsigned`；签名模式复用现有 EV token 预检、签名缓存与失败 interlock，不发布或上传 release。`build_version` 默认为 `auto`，使用[发布版本](#release-versions)中的 CI 标识；显式值可以是源码产品版本，或扩展构建版本，例如产品 `0.2.1-alpha.1` 对应 `0.2.1-alpha.1.20261009.1`。版本前缀必须匹配所选源码；校验错误显示其当前示例。manifest 保持不变。 +`Package Desktop · Windows · x64` [手动工作流](../../../.github/workflows/windows-package.yml) 选择专用 Windows x64 runner 标签 `dsh-win-package-trial`，并使用机器 preset `test` 或 `production`。选择 `signed`（默认）或 `unsigned`；签名模式复用现有 EV token 预检、签名缓存与失败 interlock，不发布或上传 release。`build_version` 默认为 `auto`，使用[发布版本](#release-versions)中的 CI 标识；显式值可以是源码产品版本，或扩展构建版本，例如产品 `0.2.1-alpha.1` 对应 `0.2.1-alpha.1.20261009.1`。版本前缀必须匹配所选源码；校验错误显示其当前示例。manifest 保持不变。 在 Actions 选择工作流、源码分支、preset、签名模式和版本，再点击 Run workflow。输入变更合并前，用 `gh workflow run windows-package.yml --ref -f preset=test -f signing=unsigned -f build_version=auto` 测试已推送分支；合并后验证网页表单。它不监听 push 或 PR。日志和成功生成的 EXE 保留 14 天。依赖打包流程前检查日志和安装包；安装是独立操作。检出前，Node 删除 runner 专用源码目录，不跟随依赖 junction；工作流校验目标位置并拒绝链接祖先目录。不得指向日常开发目录。运行共享一个并发组，不取消正在进行的构建；最多保留一个待运行任务，新触发会替换它。仅在成功完成干净检出后上传诊断。机器配置位于 checkout 之外，不作为产物上传。 在 Actions 打开完成的运行并下载 Artifacts。`windows-x64-signed---` 与 `windows-x64-unsigned---` 包含对应 EXE；`windows-package-logs--` 包含打包诊断。上传步骤名为 `Retain verified signed installer`、`Retain verified unsigned installer` 和 `Retain packaging diagnostics`；步骤耗时与带时间戳的日志显示上传用时。这些产物不等于发布 Release 或下载站内容。 -测量 Windows 构建路径对性能的影响时，可用 `build_root` 指定现有 Git checkout 之外的绝对目录。每轮任务将已验证的源码提交克隆到新的 `windows-package--/source` 目录；不会复制忽略文件或此前的构建输出。仅打包进程通过 `TEMP` 和 `TMP` 使用同轮所属的同级 `temp` 目录；Actions 步骤及 Job 后置钩子保留原临时目录。依赖缓存和签名缓存沿用原有位置。成功任务在产物上传后仅删除本轮所属的 checkout，临时文件系统错误最多重试三次，等待时间按 100 ms 递增；持续清理失败会使 Job 失败，并可能留下部分删除的目录。构建失败时保留 checkout 供检查。输入留空时使用原 Actions checkout。完整 Job 耗时须包含 checkout 创建和清理。 - 测量缓存时，`cache_namespace` 为两个依赖 store 和上游下载选择保留的子目录；留空使用正常共享缓存。新名称用于冷缓存采样，再次使用同名用于热缓存采样。名称由 1–64 个小写字母、数字或连字符组成，以字母或数字开头，且不能为 Windows 设备名。这不会重置独立的签名缓存或操作系统文件缓存；应将其状态、Job 开始至完成的总耗时与阶段耗时和产物体积一并报告。workflow 在依赖安装前记录 Node 版本、可用 CPU 并行数、逻辑 CPU 数及总内存和空闲内存。 -依赖安装和打包步骤在启动子进程前，将自身 shell 的 CPU、I/O 和内存优先级调整为普通值。优先级及独立构建目录辅助脚本从 workflow 的精确提交复制到本轮临时目录，与选中的产品源码分离。缺失辅助脚本会终止 CI 准备；无法调整优先级时明确告警并标记调度条件不适合性能对比，但继续打包。这不会修改 runner 任务或其他进程。版本、preset 和产物留存适配器仍跟随产品源码及其格式。 +依赖安装和打包步骤在启动子进程前，将自身 shell 的 CPU、I/O 和内存优先级调整为普通值。优先级辅助脚本从 workflow 的精确提交复制到本轮临时目录，与选中的产品源码分离。缺失辅助脚本会终止 CI 准备；无法调整优先级时明确告警并标记调度条件不适合性能对比，但继续打包。这不会修改 runner 任务或其他进程。版本、preset 和产物留存适配器仍跟随产品源码及其格式。 安装器上传直接存储已经压缩的发布文件，不再进行 ZIP 二次压缩；安装器字节和签名保持不变。诊断日志上传保留通常的压缩方式。 @@ -127,13 +125,14 @@ runner 的受监督启动和恢复见 [Windows runner 机器准备](../windows-s ## macOS 自托管打包 -`Package Desktop · macOS` [手动工作流](../../../.github/workflows/macos-package.yml) 使用带有 `dsh-mac-package-trial` 标签的 Apple Silicon runner。它选择 `test` 或 `production`，以 UTC 日期、运行编号和重试次数解析 `build_version=auto`，并复用现有签名、公证和打包运行时检查。安装包上传关闭重复 ZIP 压缩；诊断日志保留普通压缩。成功的 DMG／ZIP 与诊断日志保留 14 天；工作流不发布 release。操作人员须注册 runner，并验收完整 Actions 运行后再依赖该流程。 `zip_compression_level` 下拉选项默认为 `3`，也可选择 `7`；本次运行以该选项覆盖机器预设，只影响 ZIP 和自动升级下载，不影响 DMG。 +[Apple Silicon 工作流](../../../.github/workflows/macos-package.yml)与 [Intel 工作流](../../../.github/workflows/macos-intel-package.yml)在带有 `dsh-mac-package-trial` 标签的 Apple Silicon runner 上分别生成 arm64 和 x64 安装包，两者共用一个并发组。Intel 工作流在安装依赖前检查 Rosetta 能否执行；所选源码必须包含按目标架构校验的 macOS CI 适配脚本。两者均选择 `test` 或 `production`，并复用现有签名、公证和打包运行时检查。成功的 DMG／ZIP 与诊断日志保留 14 天，不发布 release；安装包上传关闭重复 ZIP 压缩。操作人员须验收完整 Actions 运行及目标架构上的安装，才能确认可交付。`compression_level` 下拉选项默认为 `3`，也可选择 `7`；本次运行以该选项覆盖机器预设，只影响 ZIP 和自动升级下载，不影响 DMG。 + +三个平台的表单均依次展示源码、环境、升级通道、版本模式、手动版本号、测试 release ID 和压缩等级，默认值一致。macOS 公证选项和 Windows 签名、缓存测量选项位于公共字段之后。 运行 `node apps/desktop/scripts/setup-macos-packaging.mjs "$HOME/dsh-ci"` 创建私有 `runner/`、`packaging/{presets,secrets,certificates}` 和 `cache/macos-signatures` 目录，不覆盖已有文件；追加 `--check` 仅检查。在 checkout 外填写 [preset](../config/macos-packaging/test.env.example) 和[签名](../config/macos-packaging/macos-signing.env.example)模板，将秘密和证书文件权限设为 `0600`。`DSH_PACKAGING_CONFIG_DIR` 指定 `packaging` 的绝对目录，`DSH_PACKAGING_PRESET` 选择其中的 preset；缺少文件立即失败，不回退到 `.env.macos`。Mac 签名和仅准备构建读取 `secrets/macos-signing.env`，相对凭据路径以该文件所在目录为基准。公开 preset 拒绝签名凭据，签名文件不能覆盖公开配置。本地未签名 Mac 构建保留无需配置的行为。 运行 `bash apps/desktop/scripts/start-macos-packaging-runner.sh "$HOME/dsh-ci/runner" "$HOME/dsh-ci/packaging" --check` 检查宿主工具和配置文件。脚本同时选择当前 Xcode 及其 macOS SDK，并编译小型链接探针。注册后省略 `--check`，清理继承环境并在前台启动 runner，存活期间阻止空闲睡眠。安装下方服务前，先用 Ctrl-C 停止。runner 拥有 `_work` 下的源码目录，与日常开发分开。该账户可读取签名文件，因此只执行可信代码。沿用现有公证代理恢复规则；强制终止后，先检查保留的恢复记录再构建。新建模板将 `DSH_DESKTOP_MACOS_SIGNATURE_CACHE_DIR` 设为 checkout 外 `cache/macos-signatures` 的绝对路径。已有部署重新运行 setup 后，在各 preset 中补上该字段；已有文件保持不变。这样可跨干净检出保留签名；缓存验证和容量限制见 [macOS 签名](#macos-release-signing)。 - 无论是否公证，ZIP 都使用同一压缩配置；App 只组装一次，再分别生成 DMG 和 ZIP，确保 ZIP 设置不改变 DMG 压缩。工作流选项 `skip_notarization` 默认为 `false`；对应 CLI 参数是 `--skip-notarization`。该模式保留 Developer ID 签名、DMG 签名验证和打包运行时验证，跳过 Apple 公证和 stapling，不要求 Apple 公证凭据。DMG／ZIP 文件名带 `-unnotarized`，存放于 `.desktop-build/targets//unnotarized-artifacts/`，上传产物标为 `unnotarized-debug`。这些产物仅供内部调试：Gatekeeper 可能阻止下载副本运行，不能视为可分发包或用于更新发布。该模式不写入发布完成记录，不能与未签名、Windows 或仅准备构建组合。 在 checkout 中，以注册 runner 的同一账户安装用户服务，不使用 `sudo`： diff --git a/apps/desktop/publishing/README.i18n.yaml b/apps/desktop/publishing/README.i18n.yaml index 9483eaff54..99b4b44aef 100644 --- a/apps/desktop/publishing/README.i18n.yaml +++ b/apps/desktop/publishing/README.i18n.yaml @@ -18,17 +18,17 @@ en: b407de63118c9bf9 zh: de19f1ba9feacbbf /desktop-publication/deployment-and-test-release-identity: - en: 405588e021bcfb60 - zh: d9f9700b0b6db6f8 + en: eed7c4ed0d4e2758 + zh: 026fe6076e11018e /desktop-publication/publish-installers-and-update-feeds: en: 3c3e3a09573c4386 zh: c851ae6a94f2284a /desktop-publication/fixed-installer-downloads: - en: 38054a5f89590cfa - zh: 9e115f9bdeeab213 + en: ce8296f8f1ee881e + zh: 749ab63bd6ed4248 /desktop-publication/upload-credentials: - en: 1c5689525753b08d - zh: 93089de765806733 + en: 47442fb912fa4d5d + zh: a21a0d67cd01724b /desktop-publication/upload-audit-and-recovery: en: ec85f43ece09a5e3 zh: 2de5bf801c9c9e39 diff --git a/apps/desktop/publishing/README.md b/apps/desktop/publishing/README.md index 71c52c1d75..b9bb98af2b 100644 --- a/apps/desktop/publishing/README.md +++ b/apps/desktop/publishing/README.md @@ -33,7 +33,7 @@ Publication requires completed release artifacts and explicit operator authoriza `DSH_DESKTOP_AUTO_UPDATE_ENV` selects `test` or `production` for both the URL embedded during packaging and the later COS upload; an absent value selects `test`. Test packaging requires its HTTPS origin in `DOWNLOAD_TEST_ORIGIN`; production uses `https://download.deepseek.com`. Upload requires the selected bucket in `DOWNLOAD_TEST_COS_BUCKET` or `DOWNLOAD_PROD_COS_BUCKET`. Production feeds use `dsh-desk/feeds//` and binaries use `dsh-desk/bin//`. Test releases require `DOWNLOAD_TEST_RELEASE_ID`: 32 lowercase hexadecimal characters inserted as `dsh-desk//feeds//` and `dsh-desk//bin//`. YAML references, stable-channel aliases, and blockmaps stay inside that release directory. Targets are `mac-arm64`, `mac-x64`, and `win-x64`. -The update destination and upload credentials follow the selected deployment: +The update destination and upload credentials follow the selected deployment; production fixed downloads also require the [EdgeOne settings](#fixed-downloads): | Environment | Public origin | COS bucket | COS credentials | |---|---|---|---| @@ -69,13 +69,17 @@ Windows NSIS uploads require the generated, nonempty `.exe.blockmap` beside the ## Fixed installer downloads -Fixed installer downloads use `pnpm run upload:latest:mac:arm64`, `pnpm run upload:latest:mac:x64`, or `pnpm run upload:latest:win:x64` from the repository root. They upload the completed target's DMG or EXE to `desktop/dsh-latest-macos-arm64.dmg`, `desktop/dsh-latest-macos-x64.dmg`, or `desktop/dsh-latest-windows-x64.exe`. Production URLs start with `https://download.deepseek.com/`; test URLs use `DOWNLOAD_TEST_ORIGIN`. Both deployments reuse the target dotenv's deployment, bucket, and credentials, all normal release validation, and the upload audit below. Each command replaces one fixed object without publishing feeds, blockmaps, or release tags. Test fixed downloads are shared across release IDs in the test bucket; the packaged update URL still requires its original release ID. Publication is explicit, including prerelease versions. Deployment infrastructure must configure revalidation or purge cached fixed downloads after replacement. Local loopback tests cover the upload; release operators own real COS and CDN acceptance. +Fixed installer downloads use `pnpm run upload:latest:mac:arm64`, `pnpm run upload:latest:mac:x64`, or `pnpm run upload:latest:win:x64` from the repository root. They upload the completed target's DMG or EXE to `desktop/dsh-latest-macos-arm64.dmg`, `desktop/dsh-latest-macos-x64.dmg`, or `desktop/dsh-latest-windows-x64.exe`. Production URLs start with `https://download.deepseek.com/`; test URLs use `DOWNLOAD_TEST_ORIGIN`. Both deployments reuse the target dotenv's deployment, bucket, and credentials, all normal release validation, and the upload audit below. Each command replaces one fixed object without publishing feeds, blockmaps, or release tags. Test fixed downloads are shared across release IDs in the test bucket; the packaged update URL still requires its original release ID. Publication is explicit, including prerelease versions. Production commands then submit one EdgeOne URL purge and report its task ID; they do not query or wait for cache completion. Test uploads retain deployment-managed cache policy. Local loopback tests cover the upload; release operators own real COS and CDN acceptance. + +Production fixed downloads require `DOWNLOAD_PROD_EO_ZONE_ID` in the target dotenv and `teo:CreatePurgeTask` permission for that zone on the existing `DOWNLOAD_PROD_COS_SECRET_ID` / `DOWNLOAD_PROD_COS_SECRET_KEY` identity. The release operator must confirm that permission before use; no additional CI Secret is required. Required settings are resolved before uploading. The submission has a 30-second request timeout and is never retried automatically. + +The command reports submission acceptance, not completed cache invalidation. EO results go to the console without separate purge record files; the existing upload audit records only COS writes. A rejected or unconfirmed submission exits unsuccessfully; the uploaded installer stays published. Check EO task history before submitting again after a connection loss or missing response. To submit a purge without uploading, use `pnpm run purge:latest ` with production settings and credentials; no local installer is needed. DPAPI users reuse the original credential launcher and add `-PurgeOnly` to their `-Upload -Latest` invocation. Serialize uploads and cache-only submissions per target. The CI publisher does not publish fixed downloads or run this refresh. ## Upload credentials -Windows operators can keep a CLIXML object with DPAPI-encrypted `SecretId` and `SecretKey` SecureString fields outside the repository. The [credential launcher](../scripts/upload-with-credentials.ps1) requires an explicit `-CredentialFile` and `-Environment production` or `test`; without `-Upload`, it only verifies decryption and injection into a local Node child, with no network request. It requires Node on `PATH` and the Windows user and machine that encrypted the file. Plaintext, empty, and whitespace-only fields fail. The parent environment is unchanged; the child receives only the selected COS pair after unrelated secrets and Node preload options are removed. Raw child stderr is suppressed and credential values in stdout are redacted. This check does not prove COS authorization. An explicit upload additionally requires `-Upload -Target -Bucket ` and the normal completed-release prerequisites below; actual cloud upload remains release-operator qualification. Add `-Latest` to that upload invocation to replace the fixed installer without publishing update feeds or a release tag. This launcher supports permanent keys, not STS credentials. An explicit upload requires the selected deployment and bucket to match the target dotenv and completed package record before network writes; it uses the DPAPI credential pair even if the dotenv contains other COS keys. +Windows operators can keep a CLIXML object with DPAPI-encrypted `SecretId` and `SecretKey` SecureString fields outside the repository. The [credential launcher](../scripts/upload-with-credentials.ps1) requires an explicit `-CredentialFile` and `-Environment production` or `test`; without `-Upload`, it only verifies decryption and injection into a local Node child, with no network request. It requires Node on `PATH` and the Windows user and machine that encrypted the file. Plaintext, empty, and whitespace-only fields fail. The parent environment is unchanged; the child receives only the selected COS pair after unrelated secrets and Node preload options are removed. Raw child stderr is suppressed and credential values in stdout are redacted. This check does not prove COS authorization. An explicit upload additionally requires `-Upload -Target -Bucket ` and the normal completed-release prerequisites below; actual cloud upload remains release-operator qualification. Add `-Latest` to that upload invocation to replace the fixed installer without publishing update feeds or a release tag. For a cache-only submission, add `-PurgeOnly` to `-Upload -Latest -Environment production`. Deployment and bucket must still match the dotenv, while package artifacts are not read. This launcher supports permanent keys, not STS credentials. An explicit upload requires the selected deployment and bucket to match the target dotenv and completed package record before network writes; it uses the DPAPI credential pair even if the dotenv contains other COS keys. diff --git a/apps/desktop/publishing/README.zh.md b/apps/desktop/publishing/README.zh.md index 22952efae4..0f64fb31ee 100644 --- a/apps/desktop/publishing/README.zh.md +++ b/apps/desktop/publishing/README.zh.md @@ -33,7 +33,7 @@ description: "将完整 Desktop 安装包与更新清单发布到选定下载服 `DSH_DESKTOP_AUTO_UPDATE_ENV` 同时选择打包写入的 URL 与后续 COS 上传环境，可取 `test` 或 `production`；缺省为 `test`。测试打包通过 `DOWNLOAD_TEST_ORIGIN` 提供 HTTPS origin；生产使用 `https://download.deepseek.com`。上传通过 `DOWNLOAD_TEST_COS_BUCKET` 或 `DOWNLOAD_PROD_COS_BUCKET` 提供所选 bucket。生产清单位于 `dsh-desk/feeds//`，安装包位于 `dsh-desk/bin//`。测试发布必须配置 `DOWNLOAD_TEST_RELEASE_ID`：32 位小写十六进制字符，分别插入路径 `dsh-desk//feeds//` 和 `dsh-desk//bin//`。YAML 引用、稳定通道别名和 blockmap 都位于该发布目录内。目标为 `mac-arm64`、`mac-x64` 和 `win-x64`。 -更新目标与上传凭据都与所选环境对应： +更新目标与上传凭据都与所选环境对应；生产固定下载还需配置 [EdgeOne 设置](#fixed-downloads)： | 环境 | 公开 origin | COS bucket | COS 凭据 | |---|---|---|---| @@ -69,13 +69,17 @@ Windows NSIS 上传要求安装包旁存在生成的非空 `.exe.blockmap`。blo ## 固定安装包下载 -固定安装包下载在仓库根目录使用 `pnpm run upload:latest:mac:arm64`、`pnpm run upload:latest:mac:x64` 或 `pnpm run upload:latest:win:x64`。它们把已完成目标的 DMG 或 EXE 上传到 `desktop/dsh-latest-macos-arm64.dmg`、`desktop/dsh-latest-macos-x64.dmg` 或 `desktop/dsh-latest-windows-x64.exe`。生产 URL 以 `https://download.deepseek.com/` 开头；测试 URL 使用 `DOWNLOAD_TEST_ORIGIN`。两个部署环境均复用目标 dotenv 中的部署、bucket 和凭据、全部常规发布校验以及下述上传审计。每个命令覆盖一个固定对象，不发布更新清单、blockmap 或发布标签。测试固定下载在测试 bucket 中跨发布 ID 共享；包内更新 URL 仍要求原有发布 ID。发布由操作人员显式执行，也允许预发布版本。部署基础设施必须配置重新验证，或在覆盖后清除固定下载的缓存。本地回环测试覆盖上传行为；真实 COS 和 CDN 验收由发布操作人员负责。 +固定安装包下载在仓库根目录使用 `pnpm run upload:latest:mac:arm64`、`pnpm run upload:latest:mac:x64` 或 `pnpm run upload:latest:win:x64`。它们把已完成目标的 DMG 或 EXE 上传到 `desktop/dsh-latest-macos-arm64.dmg`、`desktop/dsh-latest-macos-x64.dmg` 或 `desktop/dsh-latest-windows-x64.exe`。生产 URL 以 `https://download.deepseek.com/` 开头；测试 URL 使用 `DOWNLOAD_TEST_ORIGIN`。两个部署环境均复用目标 dotenv 中的部署、bucket 和凭据、全部常规发布校验以及下述上传审计。每个命令覆盖一个固定对象，不发布更新清单、blockmap 或发布标签。测试固定下载在测试 bucket 中跨发布 ID 共享；包内更新 URL 仍要求原有发布 ID。发布由操作人员显式执行，也允许预发布版本。生产命令随后提交一次 EdgeOne URL 缓存清除任务并报告任务 ID，不查询或等待缓存清除完成。测试上传仍由部署基础设施管理缓存策略。本地回环测试覆盖上传行为；真实 COS 和 CDN 验收由发布操作人员负责。 + +生产固定下载要求在目标 dotenv 中配置 `DOWNLOAD_PROD_EO_ZONE_ID`，且既有 `DOWNLOAD_PROD_COS_SECRET_ID` / `DOWNLOAD_PROD_COS_SECRET_KEY` 身份具备对应站点的 `teo:CreatePurgeTask` 权限。发布操作人员须在使用前确认该权限；无需新增 CI Secret。上传前解析必需配置。提交请求超时为 30 秒，不自动重试。 + +命令报告提交已接受，不代表缓存清除已完成。EO 结果输出到控制台，不另建刷新记录文件；既有上传审计仅记录 COS 写入。提交被拒绝或未确认时，命令以失败状态退出，已上传安装包保持发布。连接中断或未收到响应时，先检查 EO 任务历史再重新提交。使用 `pnpm run purge:latest ` 可只提交刷新，无需上传；需要生产配置和凭据，无需本地安装包。DPAPI 用户复用原凭据启动器，在 `-Upload -Latest` 命令上添加 `-PurgeOnly`。按目标串行执行上传和单独刷新。CI 发布器不发布固定下载，也不执行此刷新。 ## 上传凭据 -Windows 操作人员可以在仓库外保存 CLIXML 对象，其中 `SecretId` 和 `SecretKey` 是经 DPAPI 加密的 SecureString 字段。[凭据启动器](../scripts/upload-with-credentials.ps1)要求显式提供 `-CredentialFile` 和 `-Environment production` 或 `test`；不指定 `-Upload` 时，只验证解密以及向本地 Node 子进程注入凭据，不发起网络请求。它要求 `PATH` 中有 Node，并使用加密该文件时的 Windows 用户和机器。明文、空字段及纯空白字段都会失败。父进程环境保持不变；子进程先清除无关密钥与 Node 预加载选项，再仅接收所选 COS 凭据对。原始子进程 stderr 不会显示，stdout 中的凭据值会被遮盖。此检查不能证明 COS 授权有效。显式上传还要求 `-Upload -Target -Bucket ` 及下述常规发布完成前提；真实云端上传仍需发布操作人员验收。在该上传调用中添加 `-Latest`，即可替换固定安装包，而不发布更新清单或发布标签。此启动器支持长期密钥，不支持 STS 凭据。显式上传要求所选部署环境和 bucket 与目标 dotenv 文件及已完成的打包记录一致，才会发起网络写入；即使 dotenv 文件含有其他 COS 密钥，也使用 DPAPI 凭据对。 +Windows 操作人员可以在仓库外保存 CLIXML 对象，其中 `SecretId` 和 `SecretKey` 是经 DPAPI 加密的 SecureString 字段。[凭据启动器](../scripts/upload-with-credentials.ps1)要求显式提供 `-CredentialFile` 和 `-Environment production` 或 `test`；不指定 `-Upload` 时，只验证解密以及向本地 Node 子进程注入凭据，不发起网络请求。它要求 `PATH` 中有 Node，并使用加密该文件时的 Windows 用户和机器。明文、空字段及纯空白字段都会失败。父进程环境保持不变；子进程先清除无关密钥与 Node 预加载选项，再仅接收所选 COS 凭据对。原始子进程 stderr 不会显示，stdout 中的凭据值会被遮盖。此检查不能证明 COS 授权有效。显式上传还要求 `-Upload -Target -Bucket ` 及下述常规发布完成前提；真实云端上传仍需发布操作人员验收。在该上传调用中添加 `-Latest`，即可替换固定安装包，而不发布更新清单或发布标签。仅提交缓存刷新时，在 `-Upload -Latest -Environment production` 上添加 `-PurgeOnly`。部署环境和 bucket 仍须匹配 dotenv，但不读取安装包产物。此启动器支持长期密钥，不支持 STS 凭据。显式上传要求所选部署环境和 bucket 与目标 dotenv 文件及已完成的打包记录一致，才会发起网络写入；即使 dotenv 文件含有其他 COS 密钥，也使用 DPAPI 凭据对。 diff --git a/apps/desktop/publishing/ci/README.i18n.yaml b/apps/desktop/publishing/ci/README.i18n.yaml index eec80bdac1..14ef478ed7 100644 --- a/apps/desktop/publishing/ci/README.i18n.yaml +++ b/apps/desktop/publishing/ci/README.i18n.yaml @@ -21,14 +21,14 @@ en: 0478d8e35f9a3d55 zh: 0aa3fd828bc02691 /desktop-ci-publication/machine-setup: - en: f80388c2b1ffef4c - zh: f242ab2316bf38a1 + en: 0f43f2e193e95043 + zh: 1c1efb062c06f7b8 /desktop-ci-publication/package-and-publish: en: f7c12d343891e547 zh: da596ee1366c2046 /desktop-ci-publication/recovery-and-records: - en: 2e1e6b16d0d6bd41 - zh: 6ff4ad5a8f1f57b4 + en: b62a7484929f9941 + zh: c9dd06c77098e6ef /desktop-ci-publication/restore-a-channel: en: d82e2ccf70cce397 zh: d93dcb77cc4b463e diff --git a/apps/desktop/publishing/ci/README.md b/apps/desktop/publishing/ci/README.md index 9835027926..5009bf87e7 100644 --- a/apps/desktop/publishing/ci/README.md +++ b/apps/desktop/publishing/ci/README.md @@ -54,9 +54,11 @@ For a queued job, compare the job page's requested labels with **Settings → Ac Keep `DSH_PACKAGING_CONFIG_DIR` pointed at the existing machine packaging directory. Completed attempts are copied to its sibling `releases///`; `DSH_DESKTOP_RELEASES_DIR` overrides that root with an absolute path. The inventory includes installers, update archives, blockmaps, completion metadata and a credential-free manifest. Debug packages are retained but cannot publish. Copies are checked before the attempt directory becomes visible, and an existing attempt cannot be replaced. GitHub retains the same file inventory for 14 days. Local files remain until an operator removes them; do not delete an attempt while it is being verified or published. -Create `publishing/test.json` and, when authorized, `publishing/production.json` below the configuration directory. Each declares `bucket`, HTTPS `origin` without a path, and an absolute `credentialsFile`. The credential file contains only `secretId` and `secretKey`. macOS also requires `macOS.signingIdentity` and `macOS.teamId`; Windows requires `windows.certificateThumbprint`. Production requires the exact origin `https://download.deepseek.com` and `githubApp.clientId` plus an absolute `githubApp.privateKeyFile`. These files stay outside Git. The uploader supports permanent COS credentials, not STS session credentials. Administrators must keep test and production buckets unversioned (neither enabled nor suspended). Publication assumes this deployment prerequisite and does not call `GetBucketVersioning` or require its permission. Immutable binary PUTs retain `x-cos-forbid-overwrite`; their protection depends on administrators maintaining the bucket configuration. +Start from the [macOS test](../../config/publishing/macos/test.json.example), [macOS production](../../config/publishing/macos/production.json.example), [Windows test](../../config/publishing/windows/test.json.example), or [Windows production](../../config/publishing/windows/production.json.example) template. Create the `publishing/` directory and copy the selected file to `publishing/.json` below `DSH_PACKAGING_CONFIG_DIR`. Replace the example bucket, test origin, absolute paths, macOS signing identity and team ID or Windows certificate thumbprint, and production App client ID with the machine settings; keep the fixed production origin. Templates contain no credentials and do not grant COS, GitHub, or signing permissions. Store referenced secrets outside Git with access restricted to the publishing account. macOS uses the same configuration for arm64 and x64; the retained package determines the target. -Set the repository variable `DESKTOP_PUBLISH_RUNNERS` to a JSON mapping of registered runner names to unique labels and targets, for example `{"mini":{"label":"dsh-mini-publish","target":"mac-arm64"}}`. Assign that label to exactly that runner. Windows uses target `win-x64`. The routing job checks the original successful job, and the publisher checks its own runner name against the recorded name. Machines need no shared filesystem or LAN connection to each other. +Each configuration declares `bucket`, HTTPS `origin` without a path, and an absolute `credentialsFile`. The credential file contains only `secretId` and `secretKey`. macOS also requires `macOS.signingIdentity` and `macOS.teamId`; Windows requires `windows.certificateThumbprint`. Production requires the exact origin `https://download.deepseek.com` and `githubApp.clientId` plus an absolute `githubApp.privateKeyFile`. The uploader supports permanent COS credentials, not STS session credentials. Administrators must keep test and production buckets unversioned (neither enabled nor suspended). Publication assumes this deployment prerequisite and does not call `GetBucketVersioning` or require its permission. Immutable binary PUTs retain `x-cos-forbid-overwrite`; their protection depends on administrators maintaining the bucket configuration. + +Set the repository variable `DESKTOP_PUBLISH_RUNNERS` to a JSON mapping of registered runner names to unique labels and targets, for example `{"mini":{"label":"dsh-mini-publish","target":["mac-arm64","mac-x64"]}}`. Assign that label to exactly that runner. A target may be a single name or a nonempty list; the Mac entry above authorizes both packaging workflows on the same machine. Windows uses target `win-x64`. The retained target must match the selected packaging workflow. The routing job checks the original successful job, and the publisher checks its own runner name against the recorded name. Machines need no shared filesystem or LAN connection to each other. An administrator must create `desktop-test` and `desktop-production`, each with required reviewers and an allowed `master` deployment branch. The workflow checks reviewers for either deployment. Test can allow self-approval. The GitHub App needs installation access to this repository and Contents write permission, plus permission under the `desktop-v*` tag ruleset to create release tags. Reviewer approval does not transfer the reviewer's tag permissions to the App. Missing configuration stops publication; there is no personal-token fallback. The App action creates and later revokes a short-lived token. Protect the local private key and COS credential files with the publishing account's filesystem permissions. The token action accepts key contents, so the masked PEM also passes through the runner's temporary `GITHUB_OUTPUT` file during the job; masking hides logs, not local file access. @@ -82,7 +84,7 @@ After resolving a failure, re-run the failed publishing job to keep its prepared The sibling `upload-records/` directory retains an operation identity, newline-delimited events and terminal result. Feed-write intents retain both previous and requested YAML. Failures record their stage, safe error classification and diagnostic; COS failures also identify `GetObject` or `PutObject`, plus a validated HTTP status and request ID when available. Access-denied reports name the permission to inspect. Raw provider responses and credentials are excluded. Audit initialization becomes visible only after its files are complete; abandoned `.initializing-*` directories are not scanned for completed publication. Writes and readback are recorded before proceeding; missing terminal results mean interruption, not success. Actions also keeps its operation record as a diagnostic artifact for 30 days. These local records are not tamper-proof. COS readback verifies storage bytes, not public CDN behavior; public download acceptance is separate. -If the feed completed but tagging failed, the result is `published-tag-pending` and the job fails visibly. On retry, durable feed-completion evidence permits only tag recovery, even if a later release has advanced the channel. It never re-publishes old YAML. An existing conflicting tag requires administrator investigation and is never moved automatically. +If the feed completed but tagging failed, the result is `published-tag-pending` and the job fails visibly. On retry, durable feed-completion evidence permits only tag recovery, even if a later release has advanced the channel. It never re-publishes old YAML. An existing conflicting tag requires administrator investigation and is never moved automatically. A rejected tag creation retains its HTTP status and validated GitHub request ID; a follow-up lookup does not replace that failure with a missing-tag error. A repository-rule rejection directs the operator to the matching rulesets without logging the raw response. Normal publication and manual restoration acquire the same local channel lock. A crash can leave a lock directory under the sibling `publish-locks/`; verify no writer is running before manually removing it. A runner label alone does not coordinate writers on other machines. Keep one publishing machine per channel and preserve its records when migrating. diff --git a/apps/desktop/publishing/ci/README.zh.md b/apps/desktop/publishing/ci/README.zh.md index f8c41b6d95..151032eed9 100644 --- a/apps/desktop/publishing/ci/README.zh.md +++ b/apps/desktop/publishing/ci/README.zh.md @@ -54,9 +54,11 @@ job 排队时，先对照 job 页面请求的标签与 **Settings → Actions 保持 `DSH_PACKAGING_CONFIG_DIR` 指向现有机器打包目录。完成的构建复制到其同级 `releases///`；`DSH_DESKTOP_RELEASES_DIR` 可用绝对路径覆盖该根目录。文件清单包含安装包、更新归档、blockmap、完成记录和不含凭据的 manifest。调试包会留存，但不能发布。复制内容通过校验后才开放 attempt 目录，已有 attempt 不能被替换。GitHub 保留相同文件清单 14 天。本地文件保留到操作员删除；校验或发布期间不要删除对应 attempt。 -在配置目录下创建 `publishing/test.json`，获得授权后再创建 `publishing/production.json`。每份配置声明 `bucket`、不带路径的 HTTPS `origin` 和绝对路径 `credentialsFile`。凭据文件只包含 `secretId` 和 `secretKey`。macOS 还需 `macOS.signingIdentity` 和 `macOS.teamId`；Windows 需要 `windows.certificateThumbprint`。production 必须使用 origin `https://download.deepseek.com`，并提供 `githubApp.clientId` 和绝对路径 `githubApp.privateKeyFile`。这些文件不进入 Git。上传器支持长期 COS 凭据，不支持 STS 会话凭据。管理员必须维持 test 和 production bucket 未启用版本控制（不能是已启用或已暂停状态）。发布流程以此为部署前提，不调用 `GetBucketVersioning`，也不要求该权限。二进制 PUT 仍携带 `x-cos-forbid-overwrite`；防覆盖保证依赖管理员维持桶配置。 +从 [macOS test](../../config/publishing/macos/test.json.example)、[macOS production](../../config/publishing/macos/production.json.example)、[Windows test](../../config/publishing/windows/test.json.example) 或 [Windows production](../../config/publishing/windows/production.json.example) 模板开始，创建 `publishing/` 目录，将所选文件复制到 `DSH_PACKAGING_CONFIG_DIR` 下的 `publishing/.json`。用机器实际配置替换示例 bucket、test origin、绝对路径、macOS 签名身份和 Team ID 或 Windows 证书指纹，以及 production App client ID；保留固定的 production origin。模板不含凭据，也不授予 COS、GitHub 或签名权限。引用的秘密文件保存在 Git 之外，只允许发布账户访问。macOS 的 arm64 和 x64 共用配置，目标由留存包决定。 -将仓库变量 `DESKTOP_PUBLISH_RUNNERS` 配置为已注册 runner 名称到唯一标签和目标的 JSON 映射，例如 `{"mini":{"label":"dsh-mini-publish","target":"mac-arm64"}}`。该标签只能分配给这台 runner。Windows 使用目标 `win-x64`。路由 job 检查原构建成功的 job，发布器再检查自身 runner 名称与记录一致。机器之间不需要共享文件系统或局域网连接。 +每份配置声明 `bucket`、不带路径的 HTTPS `origin` 和绝对路径 `credentialsFile`。凭据文件只包含 `secretId` 和 `secretKey`。macOS 还需 `macOS.signingIdentity` 和 `macOS.teamId`；Windows 需要 `windows.certificateThumbprint`。production 必须使用 origin `https://download.deepseek.com`，并提供 `githubApp.clientId` 和绝对路径 `githubApp.privateKeyFile`。上传器支持长期 COS 凭据，不支持 STS 会话凭据。管理员必须维持 test 和 production bucket 未启用版本控制（不能是已启用或已暂停状态）。发布流程以此为部署前提，不调用 `GetBucketVersioning`，也不要求该权限。二进制 PUT 仍携带 `x-cos-forbid-overwrite`；防覆盖保证依赖管理员维持桶配置。 + +将仓库变量 `DESKTOP_PUBLISH_RUNNERS` 配置为已注册 runner 名称到唯一标签和目标的 JSON 映射，例如 `{"mini":{"label":"dsh-mini-publish","target":["mac-arm64","mac-x64"]}}`。该标签只能分配给这台 runner。目标可为单个名称或非空列表；上述 Mac 条目允许同一台机器处理两种架构的打包工作流。Windows 使用目标 `win-x64`。留存包的目标必须与所选打包工作流一致。路由 job 检查原构建成功的 job，发布器再检查自身 runner 名称与记录一致。机器之间不需要共享文件系统或局域网连接。 管理员必须创建 `desktop-test` 和 `desktop-production`，分别设置必需审批人并允许 `master` 部署分支。工作流会检查两种环境的审批人配置。test 可允许发起者自行审批。GitHub App 需要安装到本仓库、具有 Contents write 权限，并获准在 `desktop-v*` tag ruleset 下创建发布 tag。审批不会把审批人的 tag 权限传给 App。缺少配置会停止发布，不回退到个人 token。App action 创建短期 token，并在结束后撤销。使用发布账户的文件系统权限保护本机私钥及 COS 凭据文件。token action 需要密钥内容，因此已屏蔽日志的 PEM 在 job 期间也会经过 runner 临时 `GITHUB_OUTPUT` 文件；日志屏蔽不限制本地文件访问。 @@ -82,7 +84,7 @@ Environment 审批限制此工作流，不限制同一机器账户运行的任 同级 `upload-records/` 目录保留操作标识、逐行事件和最终结果。频道写入意图同时记录先前和目标 YAML。失败记录阶段、安全错误分类与诊断；COS 失败还标明 `GetObject` 或 `PutObject`，并在可用时记录经过校验的 HTTP 状态码和 request ID。访问拒绝提示会指出需检查的权限。不保存原始服务响应或凭据。审计初始化在文件完整后才可见；遗留的 `.initializing-*` 目录不参与已完成发布的扫描。写入和回读在继续操作前落盘；没有最终结果代表中断，不代表成功。Actions 还将操作记录保存为诊断 artifact，保留 30 天。这些本地记录不防篡改。COS 回读验证存储字节，不代表公开 CDN 行为；公开下载需单独验收。 -频道更新完成但 tag 失败时，结果为 `published-tag-pending`，job 明确失败。重试时，已落盘的频道完成证据只允许恢复 tag，即使后来发布已推进频道，也不会重新发布旧 YAML。已有冲突 tag 需要管理员调查，不会自动移动。 +频道更新完成但 tag 失败时，结果为 `published-tag-pending`，job 明确失败。重试时，已落盘的频道完成证据只允许恢复 tag，即使后来发布已推进频道，也不会重新发布旧 YAML。已有冲突 tag 需要管理员调查，不会自动移动。tag 创建被拒绝时保留其 HTTP 状态及经过校验的 GitHub request ID，后续查询不会用 tag 不存在的错误替换创建失败。仓库规则拒绝会提示操作人员检查匹配的 ruleset，不记录原始响应。 正常发布和手动恢复获取同一把本地频道锁。崩溃可能在同级 `publish-locks/` 下留下锁目录；手动删除前确认没有写入任务运行。runner 标签本身不能协调其他机器的写入。每个频道保持单一发布机器，迁移时保留记录。 diff --git a/apps/desktop/scripts/desktop-auto-update-environment.d.mts b/apps/desktop/scripts/desktop-auto-update-environment.d.mts index f656f9baaf..4d42b3dd1e 100644 --- a/apps/desktop/scripts/desktop-auto-update-environment.d.mts +++ b/apps/desktop/scripts/desktop-auto-update-environment.d.mts @@ -7,6 +7,13 @@ export type DesktopAutoUpdateEnvironment = 'test' | 'production' /** Directory name of one supported Desktop release target. */ export type DesktopAutoUpdateTarget = 'mac-arm64' | 'mac-x64' | 'win-x64' +/** + * Name the fixed installer object shared by uploading and cache refresh. + * @param target Supported Desktop target. + * @returns Fixed download filename. + */ +export function desktopLatestInstallerFilename(target: DesktopAutoUpdateTarget): string + /** Public updater URL and object prefixes for one release target. */ export interface DesktopAutoUpdateConfig { readonly environment: DesktopAutoUpdateEnvironment @@ -98,3 +105,11 @@ export function resolveDesktopUploadConfig( * @returns Validated channel. */ export function resolveDesktopUpdateChannel(env: NodeJS.ProcessEnv): 'nightly' | 'latest' + +/** + * Read a required nonempty deployment setting. + * @param env Packaging or upload settings. + * @param name Setting name included in missing-value diagnostics. + * @returns Trimmed setting value. + */ +export function requiredEnvironmentValue(env: NodeJS.ProcessEnv, name: string): string diff --git a/apps/desktop/scripts/desktop-auto-update-environment.mjs b/apps/desktop/scripts/desktop-auto-update-environment.mjs index a1973a9c64..835beadd6d 100644 --- a/apps/desktop/scripts/desktop-auto-update-environment.mjs +++ b/apps/desktop/scripts/desktop-auto-update-environment.mjs @@ -35,6 +35,17 @@ const UPDATE_ENVIRONMENTS = { const UPDATE_TARGETS = new Set(['mac-arm64', 'mac-x64', 'win-x64']) +/** + * Name the fixed installer object shared by uploading and cache refresh. + * @param {'mac-arm64' | 'mac-x64' | 'win-x64'} target Supported Desktop target. + * @returns {string} Fixed download filename. + */ +export function desktopLatestInstallerFilename(target) { + if (!UPDATE_TARGETS.has(target)) throw new Error(`desktop upload: unsupported target ${target}`) + const windows = target === 'win-x64' + return `dsh-latest-${windows ? 'windows' : 'macos'}-${target === 'mac-arm64' ? 'arm64' : 'x64'}.${windows ? 'exe' : 'dmg'}` +} + /** * Resolve the update deployment, defaulting local release work to test. * @param {NodeJS.ProcessEnv} env - Packaging or upload environment. @@ -99,7 +110,7 @@ export function desktopUpdateMetadataFilename(version, platform, channel = 'nigh * @param {string} name - Environment variable to read. * @returns {string} Trimmed setting. */ -function requiredEnvironmentValue(env, name) { +export function requiredEnvironmentValue(env, name) { const value = env[name]?.trim() if (value === undefined || value === '') { throw new Error(`desktop auto-update: ${name} must be set to a non-empty value`) diff --git a/apps/desktop/scripts/desktop-build-paths.mjs b/apps/desktop/scripts/desktop-build-paths.mjs index bf2361a695..edfd9cdf78 100644 --- a/apps/desktop/scripts/desktop-build-paths.mjs +++ b/apps/desktop/scripts/desktop-build-paths.mjs @@ -75,10 +75,12 @@ export function desktopTargetBuildPaths(target, environment = process.env) { */ export function desktopTargetPlatform(target) { assertSupportedTarget(target) - return { - platform: /** @type {'darwin' | 'win32'} */ (target === 'win-x64' ? 'win32' : 'darwin'), - arch: /** @type {'arm64' | 'x64'} */ (target === 'mac-arm64' ? 'arm64' : 'x64'), - } + const targets = /** @type {const} */ ({ + 'mac-arm64': { platform: 'darwin', arch: 'arm64' }, + 'mac-x64': { platform: 'darwin', arch: 'x64' }, + 'win-x64': { platform: 'win32', arch: 'x64' }, + }) + return targets[target] } /** diff --git a/apps/desktop/scripts/desktop-edgeone.ts b/apps/desktop/scripts/desktop-edgeone.ts new file mode 100644 index 0000000000..e2faf122a0 --- /dev/null +++ b/apps/desktop/scripts/desktop-edgeone.ts @@ -0,0 +1,73 @@ +/** Submit one production fixed-installer cache purge to EdgeOne. */ +import type { teo } from 'tencentcloud-sdk-nodejs-teo' +import type { DesktopPackageTargetName } from './package-target.ts' +import { desktopLatestInstallerFilename, requiredEnvironmentValue, resolveDesktopAutoUpdateEnvironment, resolveDesktopUploadConfig } from './desktop-auto-update-environment.mjs' +import { desktopTargetPlatform } from './desktop-build-paths.mjs' + +/** Validated production destination and credentials; never serialize this value. */ +export interface DesktopPurgeConfig { + readonly zoneId: string + readonly publicUrl: string + readonly secretId: string + readonly secretKey: string +} + +/** The single SDK operation needed to submit a purge. */ +export type DesktopPurgeClient = Pick, 'CreatePurgeTask'> + +/** + * Resolve production purge settings before uploading. + * @param env Target dotenv settings, including any credential-launcher replacement. + * @param target Fixed installer selected by the operator. + * @param publicUrl Uploaded object URL; omitted derives the URL for a cache-only submission. + * @returns Validated destination and credentials. + */ +export function resolveDesktopPurgeConfig( + env: NodeJS.ProcessEnv, target: DesktopPackageTargetName, publicUrl?: string, +): DesktopPurgeConfig { + if (resolveDesktopAutoUpdateEnvironment(env) !== 'production') throw new DesktopPurgeError('desktop purge: production is required') + const { platform, arch } = desktopTargetPlatform(target) + const update = resolveDesktopUploadConfig(env, platform, arch) + const zoneId = requiredEnvironmentValue(env, 'DOWNLOAD_PROD_EO_ZONE_ID') + if (!/^zone-[a-z0-9]+$/u.test(zoneId)) throw new DesktopPurgeError('desktop purge: DOWNLOAD_PROD_EO_ZONE_ID must name one EO zone') + return { + zoneId, publicUrl: publicUrl ?? `${update.origin}/desktop/${desktopLatestInstallerFilename(target)}`, + secretId: requiredEnvironmentValue(env, update.secretIdEnvName), secretKey: requiredEnvironmentValue(env, update.secretKeyEnvName), + } +} + +/** A purge submission failure containing only safe CLI diagnostics. */ +export class DesktopPurgeError extends Error {} + +function safeField(value: unknown, config: DesktopPurgeConfig): string | undefined { + if (typeof value !== 'string' || !/^[\w.-]{1,128}$/u.test(value) + || value.includes(config.secretId) || value.includes(config.secretKey)) return undefined + return value +} + +/** + * Submit once and report the accepted task ID, without querying cache completion. + * @param config Validated production destination and credentials. + * @param client Optional caller-owned SDK client; omitted lazily creates one with a 30-second request timeout. + * @returns Resolves when EO accepts the submission; this does not confirm cache completion. + * @throws DesktopPurgeError on rejection or an unconfirmed submission; never retries or changes uploaded bytes. + */ +export async function purgeDesktopInstaller(config: DesktopPurgeConfig, client?: DesktopPurgeClient): Promise { + let response: Awaited> + try { + client ??= new (await import('tencentcloud-sdk-nodejs-teo')).teo.v20220901.Client({ + credential: { secretId: config.secretId, secretKey: config.secretKey }, region: '', + profile: { httpProfile: { endpoint: 'teo.tencentcloudapi.com', reqTimeout: 30 } }, + }) + response = await client.CreatePurgeTask({ ZoneId: config.zoneId, Type: 'purge_url', Targets: [config.publicUrl] }) + } catch (error) { + const code = safeField(typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined, config) + throw new DesktopPurgeError(`desktop purge: submission not confirmed (${code ?? 'request failed'}); check EO task history and teo:CreatePurgeTask permission before submitting again.`) + } + if ((response.FailedList?.length ?? 0) > 0) { + throw new DesktopPurgeError('desktop purge: EO rejected the URL; inspect EO before submitting again.') + } + const jobId = safeField(response.JobId, config) + if (!jobId) throw new DesktopPurgeError('desktop purge: EO returned no task ID; check EO task history before submitting again.') + process.stdout.write(`desktop purge: submitted ${config.publicUrl}; task ${jobId}. Cache completion is not checked.\n`) +} diff --git a/apps/desktop/scripts/desktop-package-environment.mjs b/apps/desktop/scripts/desktop-package-environment.mjs index 9877b25d09..27a7f92c7f 100644 --- a/apps/desktop/scripts/desktop-package-environment.mjs +++ b/apps/desktop/scripts/desktop-package-environment.mjs @@ -15,7 +15,7 @@ import { resolveWindowsPackageSettings } from './windows-package-settings.mjs' import { resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs' const APP_ROOT = fileURLToPath(new URL('..', import.meta.url)) -const SHARED_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|NPM_REGISTRY|MANDATORY_UPDATE_(?:CONFIG|(?:TEST|PROD)_ORIGIN))|DOWNLOAD_TEST_RELEASE_ID|DOWNLOAD_(?:TEST|PROD)_(?:ORIGIN|COS_BUCKET|COS_SECRET_ID|COS_SECRET_KEY))$/u +const SHARED_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|NPM_REGISTRY|MANDATORY_UPDATE_(?:CONFIG|(?:TEST|PROD)_ORIGIN))|DOWNLOAD_TEST_RELEASE_ID|DOWNLOAD_PROD_EO_ZONE_ID|DOWNLOAD_(?:TEST|PROD)_(?:ORIGIN|COS_BUCKET|COS_SECRET_ID|COS_SECRET_KEY))$/u const WINDOWS_SETTING = /^DSH_DESKTOP_WINDOWS_(?:CER_FILE|SIGNTOOL|KEY_CONTAINER|TOKEN_PIN|SIGNATURE_CACHE_DIR|SIGNATURE_CACHE_CONCURRENCY|PACK_CONCURRENCY|COMPRESSION_LEVEL)$/u const MACOS_SETTING = /^(?:DSH_DESKTOP_MACOS_(?:SIGNING_IDENTITY|TEAM_ID|SIGNATURE_CACHE_DIR|PACK_CONCURRENCY|ZIP_COMPRESSION_LEVEL|DOWNLOAD_PROXY|NOTARIZATION_PROXY)|APPLE_(?:API_KEY|API_KEY_ID|API_ISSUER|ID|APP_SPECIFIC_PASSWORD|TEAM_ID|KEYCHAIN|KEYCHAIN_PROFILE)|CSC_(?:LINK|KEY_PASSWORD))$/u const AMBIENT_RELEASE_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|MANDATORY_UPDATE_.*|WINDOWS_.*|MACOS_.*)|APPLE_.*|(?:WIN_)?CSC_.*|DOWNLOAD_(?:TEST|PROD)_.*)$/iu diff --git a/apps/desktop/scripts/desktop-publish-route.ts b/apps/desktop/scripts/desktop-publish-route.ts index 303c447040..9b6fedfa42 100644 --- a/apps/desktop/scripts/desktop-publish-route.ts +++ b/apps/desktop/scripts/desktop-publish-route.ts @@ -1,5 +1,6 @@ /** Validate a completed packaging attempt and route publication back to its original runner. */ import { z } from 'zod' +import { desktopPublishRunnersSchema, desktopPackageWorkflows } from './desktop-publish-targets.ts' import { desktopPublishQualificationError } from './desktop-publish-qualification.mjs' const positive = z.number().int().positive() @@ -12,12 +13,11 @@ const requestSchema = z.object({ source: z.object({ repository: z.string(), runId: z.string(), attempt: z.string(), commit: z.string().regex(/^[a-f0-9]{40}$/u), workflowCommit: z.string(), sourceRef: z.string().min(1), channel: z.enum(['nightly', 'latest']), - runnerName: z.string(), target: z.enum(['mac-arm64', 'win-x64']), preset: z.enum(['test', 'production']), + runnerName: z.string(), target: z.enum(['mac-arm64', 'mac-x64', 'win-x64']), preset: z.enum(['test', 'production']), qualification: z.enum(['signed', 'notarized', 'unsigned', 'unnotarized']), }).refine(source => source.preset === 'test' || /^(?:master|dsh-v[0-9][0-9A-Za-z.-]*)$/u.test(source.sourceRef), 'Production source must be master or dsh-v*') }) const jobsSchema = z.array(z.object({ name: z.string(), runner_name: z.string().nullable(), conclusion: z.string().nullable() })) -const routesSchema = z.record(z.string(), z.object({ label: z.string().regex(/^dsh-[a-z0-9-]+$/u), target: z.enum(['mac-arm64', 'win-x64']) })) /** Validated values handed to the privileged publisher; no caller-selected shell fragments. */ export interface DesktopPublishRoute { @@ -28,7 +28,7 @@ export interface DesktopPublishRoute { readonly channel: 'nightly' | 'latest' readonly runnerName: string readonly runnerLabel: string - readonly target: 'mac-arm64' | 'win-x64' + readonly target: 'mac-arm64' | 'mac-x64' | 'win-x64' readonly preset: 'test' | 'production' } @@ -49,8 +49,8 @@ export function resolveDesktopPublishRoute( const diagnostic = desktopPublishQualificationError(source.qualification) if (diagnostic) throw new Error(diagnostic) const jobs = jobsSchema.parse(jobsValue) - const routes = routesSchema.parse(routesValue) - const workflow = source.target === 'win-x64' ? '.github/workflows/windows-package.yml' : '.github/workflows/macos-package.yml' + const routes = desktopPublishRunnersSchema.parse(routesValue) + const workflow = desktopPackageWorkflows[source.target] if (run.repository.full_name !== repository || source.repository !== repository || run.path !== workflow || source.runId !== String(run.id) || source.attempt !== String(run.run_attempt) || source.workflowCommit !== run.head_sha @@ -58,7 +58,7 @@ export function resolveDesktopPublishRoute( throw new Error('desktop publish: request does not match the successful packaging attempt') } const route = routes[source.runnerName] - if (!route || route.target !== source.target) throw new Error('desktop publish: original machine has no configured publishing route') + if (!route || !route.target.includes(source.target)) throw new Error('desktop publish: original machine has no configured publishing route') if (new Set(Object.values(routes).map(value => value.label)).size !== Object.keys(routes).length) { throw new Error('desktop publish: each configured machine needs its own unique runner label') } diff --git a/apps/desktop/scripts/desktop-publish-tag.ts b/apps/desktop/scripts/desktop-publish-tag.ts index f47cc698a6..de60c03e84 100644 --- a/apps/desktop/scripts/desktop-publish-tag.ts +++ b/apps/desktop/scripts/desktop-publish-tag.ts @@ -40,8 +40,32 @@ export async function publishDesktopTag( body: JSON.stringify({ ref: `refs/tags/${tag}`, sha: commit }), redirect: 'error', signal: AbortSignal.timeout(30_000), }) if (response.status === 201) { await matches(response); return 'created' } - // A parallel platform release may have created the same version tag after our first read. - if (response.status === 422) { await response.body?.cancel(); await matches(await get()); return 'present' } + const requestId = response.headers.get('x-github-request-id') + const identity = requestId !== null && /^[A-Fa-f0-9:]{1,128}$/u.test(requestId) ? `; GitHub request ${requestId}` : '' + const failure = `desktop tag: creation failed (HTTP ${response.status}${identity})` + // A 422 can reject repository rules as well as report a concurrent tag creation. + if (response.status === 422) { + let detail: unknown + try { detail = await response.json() } catch (error) { + // Non-JSON error responses still retain the original HTTP status and request ID. + } + const rulesRejected = typeof detail === 'object' && detail !== null && 'message' in detail + && typeof detail.message === 'string' && detail.message.startsWith('Repository rule violations found') + const guidance = rulesRejected ? 'repository rules rejected tag creation; inspect the matching tag rulesets' + : 'inspect repository rule insights and App permissions before retrying' + let reconciled: Response + try { reconciled = await get() } catch (cause) { + throw new Error(`${failure}; follow-up tag lookup failed; ${guidance}`, { cause }) + } + if (!reconciled.ok) { + await reconciled.body?.cancel() + throw new Error(`${failure}; follow-up tag lookup returned HTTP ${reconciled.status}; ${guidance}`) + } + try { await matches(reconciled) } catch (cause) { + throw new Error(`${failure}; follow-up tag verification failed; inspect the existing tag before retrying`, { cause }) + } + return 'present' + } await response.body?.cancel() - throw new Error(`desktop tag: creation failed (HTTP ${response.status}); reconcile the tag before retrying`) + throw new Error(`${failure}; reconcile the tag before retrying`) } diff --git a/apps/desktop/scripts/desktop-publish-targets.ts b/apps/desktop/scripts/desktop-publish-targets.ts new file mode 100644 index 0000000000..3270b99b25 --- /dev/null +++ b/apps/desktop/scripts/desktop-publish-targets.ts @@ -0,0 +1,18 @@ +/** Approved packaging workflows and machine publication targets. */ +import { z } from 'zod' + +/** Each target is produced by its own manually dispatched workflow. */ +export const desktopPackageWorkflows = { + 'mac-arm64': '.github/workflows/macos-package.yml', + 'mac-x64': '.github/workflows/macos-intel-package.yml', + 'win-x64': '.github/workflows/windows-package.yml', +} as const + +const targetSchema = z.enum(['mac-arm64', 'mac-x64', 'win-x64']) + +/** Machine labels are unique; a scalar target is shorthand for a one-element target list. */ +export const desktopPublishRunnersSchema = z.record(z.string(), z.object({ + label: z.string().regex(/^dsh-[a-z0-9-]+$/u), + target: z.union([targetSchema, z.array(targetSchema).min(1)]) + .transform(value => typeof value === 'string' ? [value] : value), +})) diff --git a/apps/desktop/scripts/desktop-upload-plan.ts b/apps/desktop/scripts/desktop-upload-plan.ts index aa05966c4a..1461444fc6 100644 --- a/apps/desktop/scripts/desktop-upload-plan.ts +++ b/apps/desktop/scripts/desktop-upload-plan.ts @@ -8,6 +8,7 @@ import { dump, load } from 'js-yaml' import type { DesktopPackageTargetName } from './package-target.ts' import { desktopBuildRecordFilename, + desktopLatestInstallerFilename, desktopUpdateMetadataFilename, resolveDesktopUploadConfig, } from './desktop-auto-update-environment.mjs' @@ -277,7 +278,7 @@ export async function createDesktopUploadPlan( contents: dump(published), } artifacts.push(channelArtifact) - const latestFilename = `dsh-latest-${target.platform === 'darwin' ? 'macos' : 'windows'}-${target.arch}.${target.platform === 'darwin' ? 'dmg' : 'exe'}` + const latestFilename = desktopLatestInstallerFilename(targetName) const latestKey = `desktop/${latestFilename}` return { environment: update.environment, diff --git a/apps/desktop/scripts/electron-builder-config.mjs b/apps/desktop/scripts/electron-builder-config.mjs index 1acb813253..cf0c19e895 100644 --- a/apps/desktop/scripts/electron-builder-config.mjs +++ b/apps/desktop/scripts/electron-builder-config.mjs @@ -139,6 +139,7 @@ export function createElectronBuilderConfig( }, files: [ 'lib/main.js', + 'lib/operation-report-worker.js', 'lib/welcome/**/*', 'lib/preload-app.cjs', 'lib/preload-mandatory.cjs', diff --git a/apps/desktop/scripts/preflight-desktop-publish.mjs b/apps/desktop/scripts/preflight-desktop-publish.mjs index 3d9624b20f..dfc1dcb4a6 100644 --- a/apps/desktop/scripts/preflight-desktop-publish.mjs +++ b/apps/desktop/scripts/preflight-desktop-publish.mjs @@ -29,7 +29,7 @@ export function preflightDesktopPublish(repository, inputs, api) { for (const { name } of pages.flatMap(page => page.artifacts)) { if (!name.endsWith(`-${inputs.package_run_id}-${attempt}`)) continue const qualification = name.startsWith('windows-x64-unsigned-') ? 'unsigned' - : name.startsWith('macos-arm64-unnotarized-debug-') ? 'unnotarized' : '' + : /^macos-(?:arm64|x64)-unnotarized-debug-/u.test(name) ? 'unnotarized' : '' const diagnostic = desktopPublishQualificationError(qualification) if (diagnostic) throw new Error(diagnostic) } diff --git a/apps/desktop/scripts/prepare-macos-ci.mjs b/apps/desktop/scripts/prepare-macos-ci.mjs index fb7d6b4747..6484a038fc 100644 --- a/apps/desktop/scripts/prepare-macos-ci.mjs +++ b/apps/desktop/scripts/prepare-macos-ci.mjs @@ -2,9 +2,12 @@ import { appendFileSync, readFileSync } from 'node:fs' import { resolve } from 'node:path' import { execFileSync } from 'node:child_process' +import { desktopTargetPlatform, resolveDesktopBuildTarget } from './desktop-build-paths.mjs' import { desktopCiVersion } from './desktop-ci-version.mjs' import { loadDesktopPackageEnvironment, validateDesktopPackageEnvironment } from './desktop-package-environment.mjs' +const target = desktopTargetPlatform(resolveDesktopBuildTarget(process.env)) +if (target.platform !== 'darwin') throw new Error('macOS CI requires a macOS target') const appRoot = resolve(import.meta.dirname, '..') const product = JSON.parse(readFileSync(resolve(appRoot, 'package.json'), 'utf8')) const version = desktopCiVersion(process.env, product.version) @@ -18,8 +21,8 @@ for (const [name, value] of Object.entries(environment)) { process.stdout.write(`::add-mask::${escaped}\n`) } } -validateDesktopPackageEnvironment(environment, { platform: 'darwin', arch: 'arm64' }, { skipNotarization }) +validateDesktopPackageEnvironment(environment, target, { skipNotarization }) if (!process.env.GITHUB_OUTPUT || !process.env.GITHUB_STEP_SUMMARY) throw new Error('Run this adapter from GitHub Actions') appendFileSync(process.env.GITHUB_OUTPUT, `version=${version}\nartifacts=${skipNotarization ? 'unnotarized-artifacts' : 'artifacts'}\nmode=${skipNotarization ? 'unnotarized-debug' : 'signed'}\n`) -appendFileSync(process.env.GITHUB_STEP_SUMMARY, `macOS arm64 signed installer\n\nVersion: ${version}\n\nCommit: ${execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim()}\n\nChannel: ${process.env.DSH_DESKTOP_UPDATE_CHANNEL}\n\nSource: ${process.env.PACKAGE_SOURCE_REF}\n\nPreset: ${process.env.DSH_PACKAGING_PRESET}\n`) +appendFileSync(process.env.GITHUB_STEP_SUMMARY, `macOS ${target.arch} signed installer\n\nVersion: ${version}\n\nCommit: ${execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim()}\n\nChannel: ${process.env.DSH_DESKTOP_UPDATE_CHANNEL}\n\nSource: ${process.env.PACKAGE_SOURCE_REF}\n\nPreset: ${process.env.DSH_PACKAGING_PRESET}\n`) if (skipNotarization) appendFileSync(process.env.GITHUB_STEP_SUMMARY, '\nWARNING: signed but NOT notarized or stapled. Internal debugging only; Gatekeeper may block downloaded copies. Not qualified for distribution or update publishing.\n') diff --git a/apps/desktop/scripts/publish-desktop-ci.ts b/apps/desktop/scripts/publish-desktop-ci.ts index 4b9c3e77d1..f9348ec2eb 100644 --- a/apps/desktop/scripts/publish-desktop-ci.ts +++ b/apps/desktop/scripts/publish-desktop-ci.ts @@ -18,7 +18,7 @@ import { desktopPublishQualificationError } from './desktop-publish-qualificatio const routeSchema = z.object({ runId: z.string(), attempt: z.string(), commit: z.string(), runnerName: z.string(), sourceRef: z.string(), channel: z.enum(['nightly', 'latest']), - target: z.enum(['mac-arm64', 'win-x64']), preset: z.enum(['test', 'production']) }) + target: z.enum(['mac-arm64', 'mac-x64', 'win-x64']), preset: z.enum(['test', 'production']) }) /** * Check retained bytes, original machine, destination and signatures before reading any upload secret. diff --git a/apps/desktop/scripts/resolve-desktop-publish-ci.ts b/apps/desktop/scripts/resolve-desktop-publish-ci.ts index ce39bc32bc..152369c49b 100644 --- a/apps/desktop/scripts/resolve-desktop-publish-ci.ts +++ b/apps/desktop/scripts/resolve-desktop-publish-ci.ts @@ -3,17 +3,17 @@ import { execFileSync } from 'node:child_process' import { appendFile, readFile } from 'node:fs/promises' import { resolve } from 'node:path' import { z } from 'zod' +import { desktopPublishRunnersSchema, desktopPackageWorkflows } from './desktop-publish-targets.ts' const positiveId = z.string().regex(/^[1-9]\d*$/u) const inputsSchema = z.object({ package_run_id: positiveId, package_run_attempt: z.union([positiveId, z.literal('')]).optional() }) const runSchema = z.object({ id: z.number().int().positive(), run_attempt: z.number().int().positive(), head_sha: z.string().regex(/^[a-f0-9]{40}$/u), status: z.literal('completed'), conclusion: z.literal('success'), - event: z.literal('workflow_dispatch'), path: z.enum(['.github/workflows/macos-package.yml', '.github/workflows/windows-package.yml']), + event: z.literal('workflow_dispatch'), path: z.enum(Object.values(desktopPackageWorkflows)), repository: z.object({ full_name: z.string() }) }) const jobsSchema = z.object({ jobs: z.array(z.object({ name: z.string(), runner_name: z.string().nullable(), conclusion: z.string().nullable(), })) }) -const routesSchema = z.record(z.string(), z.object({ label: z.string().regex(/^dsh-[a-z0-9-]+$/u), target: z.enum(['mac-arm64', 'win-x64']) })) /** * Read GitHub evidence for one explicit attempt, or the latest attempt without falling back after failure. @@ -37,10 +37,11 @@ export function selectDesktopPackage(repository: string, inputsValue: unknown, r const packages = jobs.filter(job => job.name === 'package' && job.conclusion === 'success' && job.runner_name) if (packages.length !== 1) throw new Error('desktop publish: expected one successful package job') const runnerName = packages[0]!.runner_name! - const routes = routesSchema.parse(routesValue) + const routes = desktopPublishRunnersSchema.parse(routesValue) const route = routes[runnerName] - const target = run.path.endsWith('/macos-package.yml') ? 'mac-arm64' : 'win-x64' - if (!route || route.target !== target) throw new Error('desktop publish: original machine has no configured publishing route') + const target = (Object.keys(desktopPackageWorkflows) as Array) + .find(name => desktopPackageWorkflows[name] === run.path)! + if (!route || !route.target.includes(target)) throw new Error('desktop publish: original machine has no configured publishing route') if (new Set(Object.values(routes).map(value => value.label)).size !== Object.keys(routes).length) { throw new Error('desktop publish: each configured machine needs its own unique runner label') } diff --git a/apps/desktop/scripts/runtime-patch-policy.ts b/apps/desktop/scripts/runtime-patch-policy.ts index d285f9bab8..a56dc95e45 100644 --- a/apps/desktop/scripts/runtime-patch-policy.ts +++ b/apps/desktop/scripts/runtime-patch-policy.ts @@ -17,6 +17,8 @@ export const DESKTOP_RUNTIME_PATCHES: Readonly(['mac-arm64', 'mac-x64', 'win-x64']) function targetName(value: string): DesktopPackageTargetName { if (!SUPPORTED_TARGETS.has(value as DesktopPackageTargetName)) { - throw new Error(`desktop upload: unsupported target ${JSON.stringify(value)}; expected ${[...SUPPORTED_TARGETS].join(', ')}`) + throw new DesktopUploadUsageError(`desktop upload: unsupported target ${JSON.stringify(value)}; expected ${[...SUPPORTED_TARGETS].join(', ')}`) } return value as DesktopPackageTargetName } -function requiredEnvironmentValue(environment: NodeJS.ProcessEnv, name: string): string { - const value = environment[name]?.trim() - if (value === undefined || value === '') { - throw new Error(`desktop upload: ${name} must be set to a non-empty value`) - } - return value -} +/** Invalid command arguments or release configuration, reported before network writes. */ +class DesktopUploadUsageError extends Error {} /** * Use the credential launcher's selected deployment only when it matches the packaged release destination. @@ -41,15 +38,14 @@ export function resolveCredentialUploadEnvironment( selected: 'test' | 'production', bucket: string, target: DesktopPackageTargetName, ): NodeJS.ProcessEnv { - const platform = target === 'win-x64' ? 'win32' : 'darwin' - const arch = target === 'mac-arm64' ? 'arm64' : 'x64' + const { platform, arch } = desktopTargetPlatform(target) const destination = resolveDesktopUploadConfig(fileEnvironment, platform, arch) if (destination.environment !== selected || destination.bucket !== bucket) { - throw new Error('desktop upload: credential launcher deployment or bucket differs from the packaged release destination') + throw new DesktopUploadUsageError('desktop upload: credential launcher deployment or bucket differs from the packaged release destination') } if (injectedEnvironment.DSH_DESKTOP_AUTO_UPDATE_ENV !== selected || injectedEnvironment[`${selected === 'test' ? 'DOWNLOAD_TEST' : 'DOWNLOAD_PROD'}_COS_BUCKET`] !== bucket) { - throw new Error('desktop upload: credential launcher environment differs from its explicit arguments') + throw new DesktopUploadUsageError('desktop upload: credential launcher environment differs from its explicit arguments') } return { ...fileEnvironment, @@ -58,40 +54,74 @@ export function resolveCredentialUploadEnvironment( } } +function purgeConfig(environment: NodeJS.ProcessEnv, target: DesktopPackageTargetName, publicUrl?: string) { + try { + return resolveDesktopPurgeConfig(environment, target, publicUrl) + } catch (error) { + if (error instanceof DesktopPurgeError) throw error + throw new DesktopUploadUsageError('Invalid production purge settings; check DOWNLOAD_PROD_COS_BUCKET, DOWNLOAD_PROD_COS_SECRET_ID, DOWNLOAD_PROD_COS_SECRET_KEY and DOWNLOAD_PROD_EO_ZONE_ID in the target dotenv.') + } +} + /** - * Upload the selected target and record a release tag only for production update uploads. + * Upload the selected target, refresh production fixed downloads, or submit only their cache purge. * @param args Target and upload options from the command line. - * @returns Resolves after upload and any release-tag attempt complete. + * @returns Resolves after upload, any required EO submission, and any release-tag attempt complete. + * @throws DesktopPurgeError when purge submission fails; a completed upload is not repeated or rolled back. */ export async function uploadDesktopTarget(args: string[]): Promise { const { positionals, values } = parseArgs({ args, allowPositionals: true, options: { latest: { type: 'boolean' }, + 'purge-only': { type: 'boolean' }, 'credential-launcher': { type: 'boolean' }, environment: { type: 'string' }, bucket: { type: 'string' }, } }) const target = positionals[0] if (target === undefined || positionals.length !== 1) { - throw new Error('desktop upload: expected exactly one target') + throw new DesktopUploadUsageError('desktop upload: expected exactly one target') } const name = targetName(target) - const fileEnvironment = loadDesktopPackageEnvironment(name === 'win-x64' ? 'win32' : 'darwin') + if (values['purge-only'] && !values.latest) { + throw new DesktopUploadUsageError('desktop upload: --purge-only requires --latest') + } + let fileEnvironment: NodeJS.ProcessEnv + try { + fileEnvironment = loadDesktopPackageEnvironment(desktopTargetPlatform(name).platform) + } catch (error) { + throw new DesktopUploadUsageError('Cannot load target dotenv; check the target dotenv file and release settings.') + } const launcher = values['credential-launcher'] === true if (launcher ? values.environment === undefined || values.bucket === undefined : values.environment !== undefined || values.bucket !== undefined) { - throw new Error('desktop upload: credential launcher requires an explicit environment and bucket') + throw new DesktopUploadUsageError('desktop upload: credential launcher requires an explicit environment and bucket') } if (values.environment !== undefined && values.environment !== 'test' && values.environment !== 'production') { - throw new Error('desktop upload: credential launcher environment must be test or production') + throw new DesktopUploadUsageError('desktop upload: credential launcher environment must be test or production') } const environment = launcher ? resolveCredentialUploadEnvironment(fileEnvironment, process.env, values.environment as 'test' | 'production', values.bucket!, name) : fileEnvironment + try { + resolveDesktopAutoUpdateEnvironment(environment) + } catch (error) { + throw new DesktopUploadUsageError('DSH_DESKTOP_AUTO_UPDATE_ENV must be "test" or "production".') + } + const recordsRoot = resolve(import.meta.dirname, '../.desktop-build/upload-records') + if (values['purge-only']) { + await purgeDesktopInstaller(purgeConfig(environment, name)) + return + } const plan = await createDesktopUploadPlan(name, { environment, latest: values.latest === true }) + const purge = plan.environment === 'production' && values.latest ? purgeConfig(environment, name, plan.publicUrl) : undefined const cos = createDesktopCos({ secretId: requiredEnvironmentValue(environment, plan.secretIdEnvName), secretKey: requiredEnvironmentValue(environment, plan.secretKeyEnvName), }) process.stdout.write(`desktop upload: ${plan.target} ${plan.version} -> ${plan.publicUrl}\n`) - await uploadDesktopRelease(plan, cos, resolve(import.meta.dirname, '../.desktop-build/upload-records')) + await uploadDesktopRelease(plan, cos, recordsRoot) + if (purge !== undefined) { + process.stdout.write('desktop upload: installer uploaded; submitting cache purge.\n') + await purgeDesktopInstaller(purge) + } if (plan.environment === 'production' && !values.latest) recordProductionRelease(plan) } @@ -121,9 +151,27 @@ function recordProductionRelease(plan: DesktopUploadPlan): void { process.stdout.write(`desktop upload: ${result.tag} ${result.status === 'created' ? 'records' : 'already recorded'} ${plan.commit}\n`) } -if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) { - uploadDesktopTarget(process.argv.slice(2)).catch(() => { - process.stderr.write('desktop upload: failed; inspect the printed record directory if allocated. No automatic retry; reconcile remote state before another upload.\n') +/** + * Report command failures without exposing raw storage or SDK exceptions. + * @param args Target and options forwarded by the package command or credential launcher. + * @returns Resolves after reporting any failure and setting the process exit status. + */ +export async function runDesktopUploadCommand(args: string[]): Promise { + try { + await uploadDesktopTarget(args) + } catch (error) { + const usage = error instanceof DesktopUploadUsageError + || (error instanceof Error && 'code' in error && typeof error.code === 'string' && error.code.startsWith('ERR_PARSE_ARGS_')) + const message = error instanceof DesktopPurgeError ? error.message + : usage ? `desktop upload/purge: ${error instanceof DesktopUploadUsageError ? error.message : 'invalid arguments'}. Usage: upload-target.ts [--latest [--purge-only]]; targets: mac-arm64, mac-x64, win-x64.` + : 'desktop upload: failed; inspect the printed record directory if allocated. No automatic retry; reconcile remote state before another upload.' + // The DPAPI launcher suppresses raw stderr; these diagnostics contain no SDK details. + const output = args.includes('--credential-launcher') ? process.stdout : process.stderr + output.write(`${message}\n`) process.exitCode = 1 - }) + } +} + +if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) { + void runDesktopUploadCommand(process.argv.slice(2)) } diff --git a/apps/desktop/scripts/upload-with-credentials.ps1 b/apps/desktop/scripts/upload-with-credentials.ps1 index 4f146d59b8..e6cde5f27e 100644 --- a/apps/desktop/scripts/upload-with-credentials.ps1 +++ b/apps/desktop/scripts/upload-with-credentials.ps1 @@ -18,6 +18,8 @@ COS bucket for an explicit upload. Not needed for the local credential check. Publish only the installer at its fixed download URL. Requires Upload. .PARAMETER Upload Authorize the existing target upload entry. Omit to check credentials locally. +.PARAMETER PurgeOnly +Submit a purge for the production fixed download without uploading. Requires Upload and Latest. #> [CmdletBinding(DefaultParameterSetName = 'Check')] param( @@ -36,7 +38,9 @@ param( [Parameter(ParameterSetName = 'Publish', Mandatory = $true)] [switch]$Upload, [Parameter(ParameterSetName = 'Publish')] - [switch]$Latest + [switch]$Latest, + [Parameter(ParameterSetName = 'Publish')] + [switch]$PurgeOnly ) $ErrorActionPreference = 'Stop' @@ -49,6 +53,11 @@ $credentials = $null $startInfo = $null $stage = 'decrypt-file' +if ($PurgeOnly -and (-not $Latest -or $Environment -ne 'production')) { + Write-Output 'desktop credentials: invalid arguments; PurgeOnly requires Latest and production.' + exit 1 +} + try { if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) { throw 'Windows DPAPI is required.' @@ -92,7 +101,12 @@ try { $startInfo.EnvironmentVariables["${prefix}_BUCKET"] = $Bucket $startInfo.Arguments = "--import tsx/esm apps/desktop/scripts/upload-target.ts $Target --credential-launcher --environment $Environment --bucket $Bucket" if ($Latest) { $startInfo.Arguments += " --latest" } - Write-Output "desktop credentials: uploading $Target to $Environment; release validation runs before network writes." + if ($PurgeOnly) { $startInfo.Arguments += " --purge-only" } + if ($PurgeOnly) { + Write-Output "desktop credentials: submitting a cache purge for $Target in $Environment; no installer upload." + } else { + Write-Output "desktop credentials: uploading $Target to $Environment; release validation runs before network writes." + } } else { $probe = "const id=process.env.${prefix}_SECRET_ID;const key=process.env.${prefix}_SECRET_KEY;process.exit(id?.trim()&&key?.trim()?0:1)" $startInfo.Arguments = "-e `"$probe`"" diff --git a/apps/desktop/scripts/windows-build-workspace.d.mts b/apps/desktop/scripts/windows-build-workspace.d.mts deleted file mode 100644 index 92f3a3c704..0000000000 --- a/apps/desktop/scripts/windows-build-workspace.d.mts +++ /dev/null @@ -1,19 +0,0 @@ -/** Identity of a Windows packaging run and its independent build root. */ -export interface WindowsBuildWorkspaceOptions { - sourceDirectory: string - buildRoot: string - runId: string - runAttempt: string - sourceSha: string -} -/** - * Clone the clean selected commit into a new run-owned directory. - * @param options - Original checkout and Actions run identity. - * @returns Checkout and temporary directory owned by this run. - */ -export function prepareWindowsBuildWorkspace(options: WindowsBuildWorkspaceOptions): { directory: string; temporaryDirectory: string } -/** - * Remove the directory only when its ownership record matches the run. - * @param options - Original checkout and Actions run identity. - */ -export function removeWindowsBuildWorkspace(options: WindowsBuildWorkspaceOptions): void diff --git a/apps/desktop/scripts/windows-build-workspace.mjs b/apps/desktop/scripts/windows-build-workspace.mjs deleted file mode 100644 index 977dda6618..0000000000 --- a/apps/desktop/scripts/windows-build-workspace.mjs +++ /dev/null @@ -1,96 +0,0 @@ -/** Create and remove a run-owned checkout for Windows packaging. */ -import { execFileSync } from 'node:child_process' -import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs' -import { dirname, isAbsolute, join, parse, resolve } from 'node:path' -import { pathToFileURL } from 'node:url' - -function assertUnlinkedAncestors(directory) { - for (let current = directory; ; current = dirname(current)) { - if (existsSync(current) && lstatSync(current).isSymbolicLink()) { - throw new Error('Packaging workspace ancestors must not be links') - } - if (dirname(current) === current) break - } -} - -function locations(options) { - const { buildRoot, runId, runAttempt, sourceSha } = options - if (!buildRoot || !isAbsolute(buildRoot) || /[\r\n\0]/.test(buildRoot)) { - throw new Error('Packaging build root must be a nonempty absolute directory') - } - const root = resolve(buildRoot) - if (root === parse(root).root) throw new Error('Packaging build root must not be a volume root') - if (!/^[1-9]\d*$/.test(runId) || !/^[1-9]\d*$/.test(runAttempt) || !/^[a-f0-9]{40}$/.test(sourceSha)) { - throw new Error('Packaging workspace requires a run identity and exact commit') - } - assertUnlinkedAncestors(root) - for (let current = root; ; current = dirname(current)) { - if (existsSync(join(current, '.git'))) throw new Error('Packaging build root must be outside existing Git checkouts') - if (dirname(current) === current) break - } - const owner = join(root, `windows-package-${runId}-${runAttempt}`) - assertUnlinkedAncestors(owner) - return { root, owner, directory: join(owner, 'source'), temporaryDirectory: join(owner, 'temp') } -} - -function git(directory, args) { - return execFileSync('git', args, { cwd: directory, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim() -} - -function ownership(options, paths) { - return JSON.stringify({ version: 1, root: paths.root, source: resolve(options.sourceDirectory), runId: options.runId, runAttempt: options.runAttempt, sourceSha: options.sourceSha }) -} - -/** - * Clone the validated commit into a new run-owned checkout; failures retain diagnostics. - * @param {{sourceDirectory: string, buildRoot: string, runId: string, runAttempt: string, sourceSha: string}} options - Source and run identity. - * @returns {{directory: string, temporaryDirectory: string}} Checkout and temporary directory owned by this run. - */ -export function prepareWindowsBuildWorkspace(options) { - const paths = locations(options) - if (git(options.sourceDirectory, ['rev-parse', 'HEAD']) !== options.sourceSha || git(options.sourceDirectory, ['status', '--porcelain'])) { - throw new Error('Packaging source must be clean and match the selected commit') - } - mkdirSync(paths.root, { recursive: true }) - mkdirSync(paths.owner) - writeFileSync(join(paths.owner, 'owner.json'), ownership(options, paths), { flag: 'wx' }) - mkdirSync(paths.temporaryDirectory) - git(paths.owner, ['clone', '--no-hardlinks', '--no-checkout', resolve(options.sourceDirectory), paths.directory]) - git(paths.directory, ['checkout', '--detach', options.sourceSha]) - if (git(paths.directory, ['rev-parse', 'HEAD']) !== options.sourceSha || git(paths.directory, ['status', '--porcelain'])) { - throw new Error('Isolated packaging checkout does not match the selected commit') - } - return { directory: paths.directory, temporaryDirectory: paths.temporaryDirectory } -} - -/** - * Remove only the matching run-owned directory after successful artifact upload. - * Transient filesystem failures retry up to three times; persistent failures propagate. - * @param {{sourceDirectory: string, buildRoot: string, runId: string, runAttempt: string, sourceSha: string}} options - Original source and run identity. - * @returns {void} - */ -export function removeWindowsBuildWorkspace(options) { - const paths = locations(options) - const marker = join(paths.owner, 'owner.json') - const stat = lstatSync(marker) - if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8192 || readFileSync(marker, 'utf8') !== ownership(options, paths)) { - throw new Error('Packaging workspace ownership does not match this run') - } - rmSync(paths.owner, { recursive: true, maxRetries: 3, retryDelay: 100 }) -} - -if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { - const options = { - sourceDirectory: process.env.GITHUB_WORKSPACE ?? '', - buildRoot: process.env.PACKAGE_BUILD_ROOT ?? '', - runId: process.env.GITHUB_RUN_ID ?? '', - runAttempt: process.env.GITHUB_RUN_ATTEMPT ?? '', - sourceSha: process.env.PACKAGE_SOURCE_SHA ?? '', - } - if (process.argv[2] === '--remove') removeWindowsBuildWorkspace(options) - else { - if (process.argv.length !== 2 || !process.env.GITHUB_OUTPUT) throw new Error('Expected Actions output file and no arguments') - const result = prepareWindowsBuildWorkspace(options) - appendFileSync(process.env.GITHUB_OUTPUT, `directory=${result.directory}\ntemporaryDirectory=${result.temporaryDirectory}\n`) - } -} diff --git a/apps/desktop/src/crash-report.ts b/apps/desktop/src/crash-report.ts index 9c6d9ed793..b4c0140848 100644 --- a/apps/desktop/src/crash-report.ts +++ b/apps/desktop/src/crash-report.ts @@ -29,6 +29,8 @@ export interface CrashReportApp { /** Inputs of {@link renderCrashReport} and {@link writeCrashReport}. */ export interface CrashReportInput { + /** The shell will attempt an independently bounded operation-history append after saving this report. */ + readonly operationHistoryPlanned?: boolean readonly source: CrashReportSource readonly phase: CrashReportPhase readonly error: unknown @@ -125,6 +127,9 @@ export function renderCrashReport(input: CrashReportInput): string { ...(input.hostDiagnostic === undefined ? [] : ['--- host diagnostic (as reported by the Host process) ---', input.hostDiagnostic, '']), '--- renderer console (error level, oldest first) ---', consoleSection, + ...(input.operationHistoryPlanned === true ? ['', '--- auxiliary diagnostics ---', + 'Operation history is best effort. Without its completion marker below, it is unavailable or incomplete.', + 'Recent operations are context only. Missing records do not establish that no changes occurred.'] : []), '', ].join('\n') } diff --git a/apps/desktop/src/fatal-recovery.ts b/apps/desktop/src/fatal-recovery.ts index 5a739b1288..8bfe76ab37 100644 --- a/apps/desktop/src/fatal-recovery.ts +++ b/apps/desktop/src/fatal-recovery.ts @@ -12,10 +12,14 @@ interface RecoveryOperations { disablePlugins(): Promise exit(): void restart(): void + /** Reveal an existing report in the system file manager; reject if it is no longer available. */ + revealReport(path: string): Promise /** Persist the complete diagnostic; resolves with the file path, or `undefined` when nothing was written. */ writeReport(error: unknown, source: CrashReportSource): Promise } +type ReportState = { kind: 'pending' } | { kind: 'failed' } | { kind: 'ready'; path: string } + /** Upper bound on waiting for the crash report before the dialog opens. */ export const CRASH_REPORT_WAIT_MS = 1_000 @@ -25,28 +29,28 @@ const DETAIL_BUDGET = 1200 /** Tail lines of the error kept in the dialog; the report file holds the rest. */ const DETAIL_TAIL_LINES = 8 -/** - * Compose the dialog detail: the error's last lines (prefixed by the - * shortening notice when they are not the whole error), then the report path - * when one was written, then the reinstall advice. The report line does not - * depend on shortening: a short error that was persisted names its file too. +/** At most eight error-tail lines; status, advice and truncation notice share the detail character budget. + * The message heading has its own field. */ -function dialogDetail(error: string, messages: DesktopMessages, reportPath: string | undefined): string { +function dialogDetail(error: string, messages: DesktopMessages, reportState: ReportState): string { const advice = `\n\n${messages.startupReinstallAdvice}` - const report = reportLine(messages, reportPath) + const report = reportLine(messages, reportState) const tail = error.split(/\r\n|[\n\r\u2028\u2029]/u).slice(-DETAIL_TAIL_LINES).join('\n') const budget = DETAIL_BUDGET - advice.length - report.length - messages.diagnosticTruncated.length - 1 const shortened = tail.slice(-budget).replace(/^[\uDC00-\uDFFF]/u, '') return `${shortened === error ? error : `${messages.diagnosticTruncated}\n${shortened}`}${report}${advice}` } -function reportLine(messages: DesktopMessages, reportPath: string | undefined): string { - return reportPath === undefined ? '' : `\n${formatDesktopMessage(messages.reportWrittenTo, { path: reportPath })}` +function reportLine(messages: DesktopMessages, state: ReportState): string { + if (state.kind === 'pending') return `\n${messages.reportPending}` + if (state.kind === 'failed') return `\n${messages.reportUnavailable}` + return `\n${formatDesktopMessage(messages.reportWrittenTo, { path: state.path })}` } /** Deduplicates fatal reports while keeping explicit recovery-operation failures actionable. */ export class DesktopFatalRecovery { private reported = false + private reportState: ReportState = { kind: 'pending' } /** @param operations - Native presentation, report persistence, and application-owned shutdown operations. */ constructor(private readonly operations: RecoveryOperations) {} @@ -57,7 +61,7 @@ export class DesktopFatalRecovery { /** * Show the first fatal error; later reports cannot replace it or open another dialog. * The crash report is written first, bounded by {@link CRASH_REPORT_WAIT_MS}, so the dialog can name it; - * a slow or failed write shows the dialog without a path. + * a slow or failed write shows its status. Retrieving a report rechecks the same write. * @param error - Fatal failure, including nested diagnostic causes. * @param source - Where the failure surfaced, recorded in the report. * @returns Completion of the user's recovery action; duplicate reports resolve immediately. @@ -66,25 +70,42 @@ export class DesktopFatalRecovery { if (this.reported) return this.reported = true const messages = this.operations.messages() - const reportPath = await this.persist(error, source) + const report = this.persist(error, source) + await this.waitForReport(report) let detail = desktopErrorState(error).message let message = messages.fatalSummary for (;;) { const addressInUse = /\blisten EADDRINUSE\b/u.test(detail) + const buttons = addressInUse + ? [messages.exitApplication, messages.restartApplication] + : [messages.exitApplication, messages.restartApplication, messages.disableThirdPartyPlugins] + const reportButton = this.reportState.kind === 'failed' ? undefined : buttons.length + if (reportButton !== undefined) buttons.push(messages.getDiagnosticReport) const { response } = await this.operations.show({ type: 'error', title: messages.startupFailed, message, detail: addressInUse - ? `${messages.startupAddressInUse}${reportLine(messages, reportPath)}` - : dialogDetail(detail, messages, reportPath), - buttons: addressInUse - ? [messages.exitApplication, messages.restartApplication] - : [messages.exitApplication, messages.restartApplication, messages.disableThirdPartyPlugins], + ? `${messages.startupAddressInUse}${reportLine(messages, this.reportState)}` + : dialogDetail(detail, messages, this.reportState), + buttons, defaultId: 1, cancelId: 0, noLink: true, }) + if (response === reportButton) { + await this.waitForReport(report) + if (this.reportState.kind === 'ready') { + try { + await this.operations.revealReport(this.reportState.path) + message = messages.reportShareHint + } catch (failure) { + console.error('dsh desktop: could not reveal crash report', failure) + message = messages.reportRevealFailed + } + } + continue + } if (response === 0) { try { await this.operations.stop() } catch (failure) { console.error(failure) } this.operations.exit() @@ -103,16 +124,23 @@ export class DesktopFatalRecovery { } } - private async persist(error: unknown, source: CrashReportSource): Promise { - let timer: ReturnType | undefined + private async persist(error: unknown, source: CrashReportSource): Promise { try { - return await Promise.race([ - this.operations.writeReport(error, source), - new Promise((resolve) => { timer = setTimeout(() => { resolve(undefined) }, CRASH_REPORT_WAIT_MS) }), - ]) + const path = await this.operations.writeReport(error, source) + this.reportState = path === undefined ? { kind: 'failed' } : { kind: 'ready', path } } catch (failure) { console.error('dsh desktop: crash report failed', failure) - return undefined + this.reportState = { kind: 'failed' } + } + } + + private async waitForReport(report: Promise): Promise { + let timer: ReturnType | undefined + try { + await Promise.race([ + report, + new Promise((resolve) => { timer = setTimeout(resolve, CRASH_REPORT_WAIT_MS) }), + ]) } finally { clearTimeout(timer) } diff --git a/apps/desktop/src/file-actions.ts b/apps/desktop/src/file-actions.ts new file mode 100644 index 0000000000..45c4a25fc1 --- /dev/null +++ b/apps/desktop/src/file-actions.ts @@ -0,0 +1,192 @@ +/** Trusted-window Chromium downloads and clipboard fallback reads. */ +import { app, ipcMain, session } from 'electron' +import type { BrowserWindow, IpcMainInvokeEvent } from 'electron' +import { closeSync, openSync, rmSync } from 'node:fs' +import { extname, join } from 'node:path' +import { resolveDragFileName } from '@deepseek-ai/dsh-util-file-drag' +import { randomUUID } from 'node:crypto' +import type { FileSaveResult } from '@deepseek-ai/dsh-client-ui-file-actions/types' +import { DESKTOP_IPC } from './ipc.ts' +import { resolveDurationMs } from './duration-env.ts' + +/** @param value - untrusted IPC input. @returns captured URL and destination policy. */ +function saveRequest(value: unknown): { url: URL; name?: string; mediaType?: string; mode: 'download' | 'saveAs' } { + if (typeof value !== 'object' || value === null + || !('url' in value) || typeof value.url !== 'string' + || ('name' in value && typeof value.name !== 'string') + || ('mediaType' in value && typeof value.mediaType !== 'string') + || !('mode' in value) || (value.mode !== 'download' && value.mode !== 'saveAs')) throw new Error('Invalid file save request') + const url = new URL(value.url) + if (!['https:', 'http:', 'blob:', 'data:'].includes(url.protocol) || url.username || url.password) throw new Error('Unsupported file source') + return { url, mode: value.mode, + ...'name' in value ? { name: value.name as string } : {}, + ...'mediaType' in value ? { mediaType: value.mediaType as string } : {}, + } +} + +/** + * Install trusted-window original-file operations. + * @param assertOwner - rejects shell pages, subframes, and unowned windows. + * @param hostUrl - current application Host excluded from image reads. + */ +export function installFileActions( + assertOwner: (event: IpcMainInvokeEvent) => BrowserWindow, hostUrl: () => string | undefined = () => undefined, +): void { + const timeoutMs = resolveDurationMs(process.env, 'DSH_DESKTOP_IMAGE_READ_TIMEOUT_MS', 30_000) + const maxBytes = Number(process.env.DSH_DESKTOP_IMAGE_READ_MAX_BYTES ?? 64 * 1024 * 1024) + if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('DSH_DESKTOP_IMAGE_READ_MAX_BYTES must be a positive integer') + const pending = new Map + finish: (result: FileSaveResult | Error) => void + started: () => void + item?: Electron.DownloadItem + }>() + session.defaultSession.on('will-download', (_event, item, contents) => { + const url = item.getURLChain()[0] + if (url === undefined || !new URL(url).hash.startsWith('#dsh-download=')) return + const entry = pending.get(url) + if (entry === undefined || entry.owner.webContents !== contents) { item.cancel(); return } + entry.started() + entry.item = item + let reserved: string | undefined + try { + assertOwner(entry.event) + const name = resolveDragFileName({ + name: entry.request.name ?? item.getFilename(), + mediaType: item.getMimeType() || entry.request.mediaType || '', + }) + let destination = join(app.getPath('downloads'), name) + if (entry.request.mode === 'saveAs') { + item.setSaveDialogOptions({ defaultPath: destination, properties: ['showOverwriteConfirmation', 'createDirectory'] }) + } else { + const extension = extname(destination) + const stem = destination.slice(0, destination.length - extension.length) + for (let index = 0; ; index++) { + destination = index === 0 ? `${stem}${extension}` : `${stem} (${index})${extension}` + try { closeSync(openSync(destination, 'wx')); break } + catch (error) { + if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST') continue + throw error + } + } + reserved = destination + item.setSavePath(destination) + } + item.once('done', (_event, state) => { + try { + if (state !== 'completed') { + if (reserved !== undefined) rmSync(reserved, { force: true }) + entry.finish(state === 'cancelled' ? { status: 'cancelled' } : new Error('File download interrupted')) + return + } + if (!pending.has(url)) return + assertOwner(entry.event) + entry.finish({ status: 'saved', path: item.getSavePath() }) + } catch (error) { entry.finish(error instanceof Error ? error : new Error('File download unavailable')) } + }) + } catch (error) { + item.cancel() + try { if (reserved !== undefined) rmSync(reserved, { force: true }) } + catch (cleanupError) { + entry.finish(new AggregateError([error, cleanupError], 'File download failed and its partial file could not be removed')) + return + } + entry.finish(error instanceof Error ? error : new Error('File download unavailable')) + } + }) + const downloadTimeoutMs = resolveDurationMs(process.env, 'DSH_DESKTOP_FILE_DOWNLOAD_TIMEOUT_MS', 300_000) + ipcMain.handle(DESKTOP_IPC.fileSave, (event, value: unknown): Promise => { + const owner = assertOwner(event) + const request = saveRequest(value) + // Fragments do not change the fetched resource; each native request has its own completion identity. + request.url.hash = `dsh-download=${randomUUID()}` + const url = request.url.href + return new Promise((resolve, reject) => { + const contents = owner.webContents + const finish = (result: FileSaveResult | Error): void => { + if (!pending.delete(url)) return + clearTimeout(timer) + owner.removeListener('closed', cancel) + contents.removeListener('did-start-navigation', navigate) + if (result instanceof Error) reject(result) + else resolve(result) + } + const cancel = (): void => { + const item = pending.get(url)?.item + finish({ status: 'cancelled' }) + item?.cancel() + } + const navigate = (_event: Electron.Event, _url: string, inPlace: boolean, mainFrame: boolean): void => { + if (mainFrame && !inPlace) cancel() + } + const timer = setTimeout(() => { + const item = pending.get(url)?.item + finish(new Error('File download timed out')) + item?.cancel() + }, downloadTimeoutMs) + pending.set(url, { event, owner, request, finish, started: () => { clearTimeout(timer) } }) + owner.once('closed', cancel) + contents.on('did-start-navigation', navigate) + try { contents.downloadURL(url) } + catch (error) { finish(error instanceof Error ? error : new Error('File download unavailable')) } + }) + }) + ipcMain.handle(DESKTOP_IPC.clipboardImageRead, async (event, value: unknown) => { + const owner = assertOwner(event) + if (typeof value !== 'string') throw new Error('Invalid image URL') + const checkedUrl = (value: string): URL => { + const url = new URL(value) + const host = hostUrl() + const application = host === undefined ? undefined : new URL(host) + if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password + || application !== undefined && url.port === application.port + && (url.hostname === application.hostname || ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) { + throw new Error('Invalid image URL') + } + return url + } + let url = checkedUrl(value) + const contents = owner.webContents + const lifetime = new AbortController() + const abort = (): void => { lifetime.abort() } + owner.once('closed', abort) + const navigate = (_event: Electron.Event, _url: string, inPlace: boolean, mainFrame: boolean): void => { + if (mainFrame && !inPlace) abort() + } + contents.on('did-start-navigation', navigate) + try { + const signal = AbortSignal.any([lifetime.signal, AbortSignal.timeout(timeoutMs)]) + let response: Response + for (let redirects = 0; ; redirects++) { + response = await fetch(url, { signal, redirect: 'manual', credentials: 'omit', referrerPolicy: 'no-referrer' }) + if (![301, 302, 303, 307, 308].includes(response.status)) break + await response.body?.cancel() + const location = response.headers.get('location') + if (redirects >= 20 || location === null) throw new Error('Invalid image redirect') + url = checkedUrl(new URL(location, url).href) + } + if (!response.ok) throw new Error('Original image unavailable') + const reader = response.body?.getReader() + if (reader === undefined) throw new Error('Original image unavailable') + const chunks: Uint8Array[] = [] + let size = 0 + try { + for (;;) { + const chunk = await reader.read() + if (chunk.done) break + size += chunk.value.byteLength + if (size > maxBytes) throw new Error('Original image exceeds the download limit') + chunks.push(chunk.value) + } + } finally { await reader.cancel(); reader.releaseLock() } + assertOwner(event) + lifetime.signal.throwIfAborted() + return { bytes: new Uint8Array(Buffer.concat(chunks)), mediaType: response.headers.get('content-type') ?? '' } + } finally { + owner.removeListener('closed', abort) + contents.removeListener('did-start-navigation', navigate) + } + }) +} diff --git a/apps/desktop/src/host-process.ts b/apps/desktop/src/host-process.ts index 6dbb908c10..338f93bda4 100644 --- a/apps/desktop/src/host-process.ts +++ b/apps/desktop/src/host-process.ts @@ -2,8 +2,10 @@ import { spawn, type ChildProcess } from 'node:child_process' import { join } from 'node:path' +import { z } from 'zod' import type { PlatformSession } from '@deepseek-ai/dsh-deepseek-account' import { desktopNodeEnvironment } from './node-environment.ts' +import { parsePluginOperationRecord, type PluginOperationRecord, type PluginOperationRunId } from '@deepseek-ai/dsh-plugin-manager/diagnostic' interface ReadyEvent { readonly type: 'ready' @@ -23,7 +25,10 @@ interface PlatformSessionEvent { readonly session: PlatformSession | null } -type DesktopHostEvent = ReadyEvent | FatalEvent | PlatformSessionEvent | { readonly type: 'shutdown-complete' } | { +type DesktopHostEvent = ReadyEvent | FatalEvent | PlatformSessionEvent | { + readonly type: 'starting' + readonly runId: PluginOperationRunId +} | { readonly type: 'shutdown-complete' } | { readonly type: 'file-drag-resource' readonly requestId: number readonly resource: { readonly path: string; readonly sha256: string; readonly size: number } | null @@ -54,11 +59,14 @@ export interface DesktopQuitInspection { export const QUIT_INSPECTION_DEADLINE_MS = 2_000 const MAX_HOST_DIAGNOSTIC_CHARS = 64 * 1024 +const runIdSchema = z.uuid() function isDesktopHostEvent(message: unknown): message is DesktopHostEvent { if (typeof message !== 'object' || message === null || !('type' in message)) return false const candidate = message as Record switch (candidate.type) { + case 'starting': + return runIdSchema.safeParse(candidate.runId).success case 'shutdown-complete': return true case 'ready': @@ -148,6 +156,7 @@ export class DesktopHostFatalError extends Error { /** One Web backend running under the Electron executable in Node mode. */ export class DesktopHostProcess { + private runId: PluginOperationRunId | undefined private child: ChildProcess | undefined private readyResolve!: (ready: DesktopHostReady) => void private readyReject!: (error: Error) => void @@ -177,6 +186,7 @@ export class DesktopHostProcess { * `office-skills` resources fail Host startup. * @param packageManager - Bundled pnpm entry and Node launcher directory, scoped to package operations. * @param onPlatformSession - Private credential updates for embedded Platform views. + * @param onPluginOperation - Optional diagnostic sink; malformed records are ignored without failing the Host. */ constructor( private readonly node: string, @@ -189,6 +199,7 @@ export class DesktopHostProcess { private readonly packageManager?: { readonly pnpm: string; readonly nodeBin: string }, private readonly onPlatformSession?: (session: PlatformSession | null) => void, + private readonly onPluginOperation?: (record: PluginOperationRecord) => void, ) {} /** @@ -216,12 +227,24 @@ export class DesktopHostProcess { child.stderr?.on('data', (chunk: string) => { this.stderr = (this.stderr + chunk).slice(-MAX_HOST_DIAGNOSTIC_CHARS) }) child.stdout?.pipe(process.stdout) child.on('message', (message: unknown) => { + if (typeof message === 'object' && message !== null && 'type' in message && message.type === 'plugin-operation') { + const record = 'record' in message ? parsePluginOperationRecord(message.record) : undefined + if (record !== undefined && record.runId === this.runId) { + try { this.onPluginOperation?.(record) } + catch (_error) { + // Diagnostic persistence cannot invalidate the Host's business IPC channel. + console.error('desktop plugin operation diagnostic sink failed') + } + } + return + } if (!isDesktopHostEvent(message)) { this.fail(new Error('dsh desktop host sent an invalid IPC event')) child.kill('SIGTERM') return } - if (message.type === 'ready') this.readyResolve({ url: message.url, injections: message.injections }) + if (message.type === 'starting') this.runId = message.runId + else if (message.type === 'ready') this.readyResolve({ url: message.url, injections: message.injections }) else if (message.type === 'platform-session') this.onPlatformSession?.(message.session) else if (message.type === 'shutdown-complete') { if (this.stopping) this.shutdownCompleted = true @@ -344,6 +367,7 @@ export class DesktopHostProcess { } private fail(error: Error): void { + if (this.runId !== undefined) Object.assign(error, { hostRunId: this.runId }) this.onPlatformSession?.(null) this.readyReject(error) for (const request of this.controlRequests.values()) request.reject(error) diff --git a/apps/desktop/src/ipc.ts b/apps/desktop/src/ipc.ts index e62a84f0a1..a3c5f5d935 100644 --- a/apps/desktop/src/ipc.ts +++ b/apps/desktop/src/ipc.ts @@ -1,3 +1,4 @@ +import type { DesktopFileActions } from '@deepseek-ai/dsh-client-ui-file-actions/types' /** Typed preload operations exposed only by the Electron shell. */ import type { DesktopKeyboardApi, DesktopShortcutsApi } from '@deepseek-ai/dsh-client-shortcuts/protocol' @@ -7,6 +8,8 @@ import type { DesktopFileDrag } from '@deepseek-ai/dsh-util-file-drag' /** IPC channel names kept private to the desktop application bundle. */ export const DESKTOP_IPC = { + fileSave: 'dsh-desktop:file-save', + clipboardImageRead: 'dsh-desktop:clipboard-image-read', shortcutsInput: 'dsh-desktop:shortcuts-input', shortcutsCloseWindow: 'dsh-desktop:shortcuts-close-window', shortcutsGet: 'dsh-desktop:shortcuts-get', @@ -76,6 +79,7 @@ export interface DesktopUpdatePresentation { /** Product documents cannot supply update versions, package URLs, or installation authorization. */ export interface DshDesktopProductApi { + readonly fileActions: DesktopFileActions readonly protocolVersion: 1 readonly browser: DesktopBrowserBridge readonly fileDrag: DesktopFileDrag diff --git a/apps/desktop/src/locale-cache.ts b/apps/desktop/src/locale-cache.ts new file mode 100644 index 0000000000..d09ee4da24 --- /dev/null +++ b/apps/desktop/src/locale-cache.ts @@ -0,0 +1,38 @@ +/** Last confirmed shell language, available even when the Host cannot start. */ +import { mkdirSync, readFileSync, writeFileSync } from 'node:fs' +import { join } from 'node:path' +import { resolveDesktopLocale, type DesktopLocale } from './locale.ts' + +/** + * Read the last confirmed language without requiring Host settings. + * @param userData - Electron userData directory. + * @returns Cached language, or undefined when missing, invalid or unreadable. + */ +export function readDesktopLocaleCache(userData: string): DesktopLocale['id'] | undefined { + try { + const value = readFileSync(join(userData, 'desktop', 'locale-cache'), 'utf8').trim() + const locale = resolveDesktopLocale(value) + if (locale.id === value) return locale.id + throw new Error('expected a canonical Desktop locale id') + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { + console.warn('desktop locale cache: using system language because the cache could not be read', error) + } + return undefined + } +} + +/** + * Remember a confirmed language; write failure leaves the active language unchanged. + * @param userData - Electron userData directory. + * @param locale - Language confirmed by Host settings or the owned renderer. + */ +export function writeDesktopLocaleCache(userData: string, locale: DesktopLocale['id']): void { + try { + const directory = join(userData, 'desktop') + mkdirSync(directory, { recursive: true, mode: 0o700 }) + writeFileSync(join(directory, 'locale-cache'), `${locale}\n`, { mode: 0o600 }) + } catch (error) { + console.warn('desktop locale cache: language could not be saved for the next startup', error) + } +} diff --git a/apps/desktop/src/locale.ts b/apps/desktop/src/locale.ts index e5dcec40c8..f5d30b82ba 100644 --- a/apps/desktop/src/locale.ts +++ b/apps/desktop/src/locale.ts @@ -61,6 +61,11 @@ export const en = { startupAddressInUse: 'Another DSH instance (such as dsh web or the desktop app) is running. They cannot start at the same time. Quit the other running DSH instance, then restart.', diagnosticTruncated: '… Error details shortened.', reportWrittenTo: 'Diagnostic report: {path}', + getDiagnosticReport: 'Get diagnostic report', + reportPending: 'The diagnostic report is still being saved. Choose Get diagnostic report to check again.', + reportUnavailable: 'The diagnostic report could not be saved. You can provide a screenshot of this dialog when requesting support.', + reportShareHint: 'The report location has been opened. Attach the selected file to your support ticket.', + reportRevealFailed: 'The report location could not be opened. Use the path below to find the file.', startupReinstallAdvice: 'If application files are missing or damaged, close the application and reinstall it. Your tasks are stored separately.', exitApplication: 'Exit', restartApplication: 'Restart', @@ -99,6 +104,7 @@ export const en = { welcomeContinueFailed: 'Could not open the workspace. Please try again.', checkUpdatesMenu: 'Check for Updates…', reloadPageMenu: 'Reload Page', + toggleDevToolsMenu: 'Developer tools', restartAppHostMenu: 'Restart App and Host', updateCheckFailedTitle: 'Update Check Failed', updateCheckFailed: 'Could not check for updates. Please try again later.', @@ -235,6 +241,11 @@ export const zh = { startupAddressInUse: '有其他正在运行的 DSH（如其他 dsh web、桌面端），无法同时启动，请退出其他正在运行的 DSH 后重启。', diagnosticTruncated: '… 错误详情已截短。', reportWrittenTo: '诊断报告：{path}', + getDiagnosticReport: '获取诊断报告', + reportPending: '诊断报告仍在保存，可点击“获取诊断报告”再次检查。', + reportUnavailable: '诊断报告未能保存，反馈问题时可提供此窗口的截图。', + reportShareHint: '已打开报告位置，请将选中的文件附在支持工单中。', + reportRevealFailed: '无法打开报告位置，请通过下方路径查找文件。', startupReinstallAdvice: '如果应用文件缺失或损坏，请关闭应用并重新安装。任务数据存储在独立位置。', exitApplication: '退出', restartApplication: '重启', @@ -273,6 +284,7 @@ export const zh = { welcomeContinueFailed: '无法打开工作区，请重试。', checkUpdatesMenu: '检查更新…', reloadPageMenu: '刷新页面', + toggleDevToolsMenu: '开发者工具', restartAppHostMenu: '重启应用与 Host', updateCheckFailedTitle: '更新检查失败', updateCheckFailed: '检查更新失败，请稍后重试。', @@ -407,6 +419,11 @@ export const ja = { startupAddressInUse: '別の DSH インスタンス (dsh web やデスクトップアプリなど) が実行中です。同時に起動することはできません。実行中の他の DSH インスタンスを終了してから再起動してください。', diagnosticTruncated: '… エラー詳細は省略されています。', reportWrittenTo: '診断レポート: {path}', + getDiagnosticReport: '診断レポートを取得', + reportPending: '診断レポートを保存中です。「診断レポートを取得」を選択して再度確認してください。', + reportUnavailable: '診断レポートを保存できませんでした。サポートへのお問い合わせ時に、このダイアログのスクリーンショットを提供できます。', + reportShareHint: 'レポートの保存場所を開きました。選択されたファイルをサポートチケットに添付してください。', + reportRevealFailed: 'レポートの保存場所を開けませんでした。以下のパスからファイルを探してください。', startupReinstallAdvice: 'アプリケーションファイルが見つからないか破損している場合は、アプリケーションを閉じて再インストールしてください。タスクは別途保存されています。', exitApplication: '終了', restartApplication: '再起動', @@ -445,6 +462,7 @@ export const ja = { welcomeContinueFailed: 'ワークスペースを開けませんでした。もう一度お試しください。', checkUpdatesMenu: 'アップデートを確認…', reloadPageMenu: 'ページを再読み込み', + toggleDevToolsMenu: '開発者ツール', restartAppHostMenu: 'アプリとホストを再起動', updateCheckFailedTitle: 'アップデートの確認に失敗しました', updateCheckFailed: 'アップデートを確認できませんでした。後でもう一度お試しください。', @@ -579,6 +597,11 @@ export const es = { startupAddressInUse: 'Se está ejecutando otra instancia de DSH (como la web de dsh o la aplicación de escritorio). No pueden empezar al mismo tiempo. Salga de la otra instancia DSH en ejecución y luego reinicie.', diagnosticTruncated: '… Detalles del error acortados.', reportWrittenTo: 'Informe de diagnóstico: {path}', + getDiagnosticReport: 'Obtener informe de diagnóstico', + reportPending: 'El informe de diagnóstico se está guardando. Seleccione Obtener informe de diagnóstico para volver a comprobarlo.', + reportUnavailable: 'No se pudo guardar el informe de diagnóstico. Puede proporcionar una captura de pantalla de este diálogo al solicitar asistencia.', + reportShareHint: 'Se ha abierto la ubicación del informe. Adjunte el archivo seleccionado a su solicitud de asistencia.', + reportRevealFailed: 'No se pudo abrir la ubicación del informe. Use la ruta que aparece a continuación para encontrar el archivo.', startupReinstallAdvice: 'Si faltan archivos de la aplicación o están dañados, ciérrela y vuelva a instalarla. Sus tareas se almacenan por separado.', exitApplication: 'Salir', restartApplication: 'Reiniciar', @@ -617,6 +640,7 @@ export const es = { welcomeContinueFailed: 'No se pudo abrir el espacio de trabajo. Por favor inténtalo de nuevo.', checkUpdatesMenu: 'Buscar actualizaciones...', reloadPageMenu: 'Recargar página', + toggleDevToolsMenu: 'Herramientas de desarrollo', restartAppHostMenu: 'Reiniciar la aplicación y el host', updateCheckFailedTitle: 'Error en la comprobación de actualización', updateCheckFailed: 'No se pudo buscar actualizaciones. Inténtelo de nuevo más tarde.', @@ -751,6 +775,11 @@ export const fr = { startupAddressInUse: "Une autre instance DSH (telle que le Web dsh ou l'application de bureau) est en cours d'exécution. Ils ne peuvent pas démarrer en même temps. Quittez l'autre instance DSH en cours d'exécution, puis redémarrez.", diagnosticTruncated: '… Détails de l’erreur raccourcis.', reportWrittenTo: 'Rapport de diagnostic : {path}', + getDiagnosticReport: 'Obtenir le rapport de diagnostic', + reportPending: 'Le rapport de diagnostic est en cours d’enregistrement. Sélectionnez Obtenir le rapport de diagnostic pour vérifier à nouveau.', + reportUnavailable: 'Le rapport de diagnostic n’a pas pu être enregistré. Vous pouvez fournir une capture d’écran de cette boîte de dialogue lorsque vous contactez l’assistance.', + reportShareHint: 'L’emplacement du rapport a été ouvert. Joignez le fichier sélectionné à votre demande d’assistance.', + reportRevealFailed: 'L’emplacement du rapport n’a pas pu être ouvert. Utilisez le chemin ci-dessous pour trouver le fichier.', startupReinstallAdvice: "Si les fichiers de l'application sont manquants ou endommagés, fermez l'application et réinstallez-la. Vos tâches sont stockées séparément.", exitApplication: 'Quitter', restartApplication: 'Redémarrer', @@ -789,6 +818,7 @@ export const fr = { welcomeContinueFailed: "Impossible d'ouvrir l'espace de travail. Veuillez réessayer.", checkUpdatesMenu: 'Vérifiez les mises à jour…', reloadPageMenu: 'Recharger la page', + toggleDevToolsMenu: 'Outils de développement', restartAppHostMenu: "Redémarrez l'application et l'hôte", updateCheckFailedTitle: 'Échec de la vérification de la mise à jour', updateCheckFailed: 'Impossible de vérifier les mises à jour. Veuillez réessayer plus tard.', @@ -923,6 +953,11 @@ export const de = { startupAddressInUse: 'Eine andere DSH-Instanz (z. B. dsh Web oder die Desktop-App) wird ausgeführt. Sie können nicht gleichzeitig starten. Beenden Sie die andere laufende DSH-Instanz und starten Sie sie neu.', diagnosticTruncated: '… Fehlerdetails gekürzt.', reportWrittenTo: 'Diagnosebericht: {path}', + getDiagnosticReport: 'Diagnosebericht abrufen', + reportPending: 'Der Diagnosebericht wird noch gespeichert. Wählen Sie „Diagnosebericht abrufen“, um ihn erneut zu prüfen.', + reportUnavailable: 'Der Diagnosebericht konnte nicht gespeichert werden. Sie können bei einer Supportanfrage einen Screenshot dieses Dialogs bereitstellen.', + reportShareHint: 'Der Speicherort des Berichts wurde geöffnet. Fügen Sie die ausgewählte Datei Ihrer Supportanfrage bei.', + reportRevealFailed: 'Der Speicherort des Berichts konnte nicht geöffnet werden. Verwenden Sie den folgenden Pfad, um die Datei zu finden.', startupReinstallAdvice: 'Wenn Anwendungsdateien fehlen oder beschädigt sind, schließen Sie die Anwendung und installieren Sie sie erneut. Ihre Aufgaben werden separat gespeichert.', exitApplication: 'Beenden', restartApplication: 'Neustart', @@ -961,6 +996,7 @@ export const de = { welcomeContinueFailed: 'Der Arbeitsbereich konnte nicht geöffnet werden. Bitte versuchen Sie es erneut.', checkUpdatesMenu: 'Nach Updates suchen…', reloadPageMenu: 'Seite neu laden', + toggleDevToolsMenu: 'Entwicklertools', restartAppHostMenu: 'Anwendung und Host neu starten', updateCheckFailedTitle: 'Update-Überprüfung fehlgeschlagen', updateCheckFailed: 'Es konnte nicht nach Updates gesucht werden. Bitte versuchen Sie es später noch einmal.', @@ -1095,6 +1131,11 @@ export const ru = { startupAddressInUse: 'Другой экземпляр DSH (например, веб-приложение dsh или настольное приложение) запущен. Они не могут начаться одновременно. Закройте другой работающий экземпляр DSH, а затем перезапустите.', diagnosticTruncated: '… Подробности об ошибках сокращены.', reportWrittenTo: 'Диагностический отчет: {path}', + getDiagnosticReport: 'Получить диагностический отчет', + reportPending: 'Диагностический отчет еще сохраняется. Выберите «Получить диагностический отчет», чтобы проверить еще раз.', + reportUnavailable: 'Не удалось сохранить диагностический отчет. При обращении в службу поддержки можно приложить снимок экрана этого диалогового окна.', + reportShareHint: 'Открыта папка с отчетом. Прикрепите выбранный файл к обращению в службу поддержки.', + reportRevealFailed: 'Не удалось открыть папку с отчетом. Найдите файл по указанному ниже пути.', startupReinstallAdvice: 'Если файлы приложения отсутствуют или повреждены, закройте приложение и переустановите его. Ваши задачи хранятся отдельно.', exitApplication: 'Выход', restartApplication: 'Перезапустить', @@ -1133,6 +1174,7 @@ export const ru = { welcomeContinueFailed: 'Не удалось открыть рабочую область. Пожалуйста, попробуйте еще раз.', checkUpdatesMenu: 'Проверить наличие обновлений…', reloadPageMenu: 'Обновить страницу', + toggleDevToolsMenu: 'Инструменты разработчика', restartAppHostMenu: 'Перезапустите приложение и хост.', updateCheckFailedTitle: 'Проверка обновления не удалась', updateCheckFailed: 'Не удалось проверить наличие обновлений. Пожалуйста, повторите попытку позже.', @@ -1267,6 +1309,11 @@ export const pt = { startupAddressInUse: 'Outra instância DSH (como dsh web ou aplicativo de desktop) está em execução. Eles não podem começar ao mesmo tempo. Saia da outra instância DSH em execução e reinicie.', diagnosticTruncated: '… Detalhes do erro reduzidos.', reportWrittenTo: 'Relatório de diagnóstico: {path}', + getDiagnosticReport: 'Obter relatório de diagnóstico', + reportPending: 'O relatório de diagnóstico ainda está sendo salvo. Selecione Obter relatório de diagnóstico para verificar novamente.', + reportUnavailable: 'Não foi possível salvar o relatório de diagnóstico. Você pode fornecer uma captura de tela desta caixa de diálogo ao solicitar suporte.', + reportShareHint: 'O local do relatório foi aberto. Anexe o arquivo selecionado à sua solicitação de suporte.', + reportRevealFailed: 'Não foi possível abrir o local do relatório. Use o caminho abaixo para encontrar o arquivo.', startupReinstallAdvice: 'Se os arquivos do aplicativo estiverem ausentes ou danificados, feche o aplicativo e reinstale-o. Suas tarefas são armazenadas separadamente.', exitApplication: 'Sair', restartApplication: 'Reiniciar', @@ -1305,6 +1352,7 @@ export const pt = { welcomeContinueFailed: 'Não foi possível abrir o espaço de trabalho. Por favor, tente novamente.', checkUpdatesMenu: 'Verifique se há atualizações…', reloadPageMenu: 'Recarregar página', + toggleDevToolsMenu: 'Ferramentas do desenvolvedor', restartAppHostMenu: 'Reinicie o aplicativo e o host', updateCheckFailedTitle: 'Falha na verificação de atualização', updateCheckFailed: 'Não foi possível verificar se há atualizações. Por favor, tente novamente mais tarde.', diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts index fb938dec84..d8d0e30c4c 100644 --- a/apps/desktop/src/main.ts +++ b/apps/desktop/src/main.ts @@ -1,8 +1,9 @@ +import { installFileActions } from './file-actions.ts' import type { ProductEventMap, ProductEvent } from '@deepseek-ai/dsh-client-product-analytics/types' import { WINDOWS_TITLEBAR_HEIGHT } from './windows-layout.ts' /** Electron shell: desktop project ownership, custom protocol, windows, and lifecycle. */ -import { readFile, writeFile } from 'node:fs/promises' +import { access, readFile, writeFile } from 'node:fs/promises' import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { @@ -41,6 +42,8 @@ import { DesktopCommandManager } from './command-management.ts' import { serveWebDocument, authenticateWebHost, forwardWebRequest } from './web-document.ts' import { DesktopFatalRecovery } from './fatal-recovery.ts' import { pruneCrashReports, RendererConsoleTail, writeCrashReport, type CrashReportSource } from './crash-report.ts' +import { OperationJournal } from './operation-journal.ts' +import { runOperationReportJob, type OperationReportJobResult } from './operation-report-job.ts' import { openWelcomeWindow } from './welcome-window.ts' import { WELCOME_IPC, needsWelcome, type WelcomeNotice } from './welcome-api.ts' import { connectDesktopWelcome, type DesktopWelcomeBackend } from './welcome-backend.ts' @@ -55,6 +58,7 @@ import { desktopClientMetadata, desktopClientVersion } from './client-metadata.t import { DesktopMandatoryUpdateWindow } from './mandatory-update-window.ts' import { DesktopPolicyTestAuth } from './policy-test-auth.ts' import { readDesktopSettings } from './settings.ts' +import { readDesktopLocaleCache, writeDesktopLocaleCache } from './locale-cache.ts' import { DesktopUpdateDialog, type UpdateDialogOptions } from './update-dialog.ts' import { readDesktopRuntime } from './runtime-tree.ts' import { DesktopBrowserGuests } from './browser-guests.ts' @@ -65,14 +69,14 @@ import { DesktopTray } from './tray.ts' import { DesktopBackgroundNotice } from './background-notice.ts' let focusPrimaryWindow = (): void => {} -let stopForRecovery = async (): Promise => {} +let stopForRecovery = async (): Promise => { await stopOperationReports() } let shuttingDown = false /** * Set by quit entries that must not ask: crash recovery exit and restart, and the * development restart command. The installer handoff has its own before-quit branch. */ let skipQuitConfirmation = false -let windowsLanguage: string | undefined +let windowsLanguage: string | undefined = readDesktopLocaleCache(app.getPath('userData')) /** * Whether the backend has reached ready: false until the first ready, back to * false when a restart returns it to starting, frozen during shutdown so a @@ -106,10 +110,39 @@ const recovery = new DesktopFatalRecovery({ exit: () => { quitWithoutConfirmation() }, restart: () => { app.relaunch(); quitWithoutConfirmation() }, writeReport: (error, source) => persistCrashReport(error, source), + revealReport: async (path) => { await access(path); shell.showItemInFolder(path) }, }) +let operationJournal: OperationJournal | undefined +let operationReportJob: Promise | undefined +let operationReportAbort: AbortController | undefined +let operationReportsStopping = false +let operationReportStop: Promise | undefined + +/** Bound application shutdown waiting without claiming that an unresponsive Worker has exited. */ +function stopOperationReports(): Promise { + operationReportStop ??= waitForOperationReports() + return operationReportStop +} + +async function waitForOperationReports(): Promise { + operationReportsStopping = true + operationReportAbort?.abort() + const job = operationReportJob + if (job === undefined) return + let timer: ReturnType | undefined + try { + const exited = await Promise.race([job.then(() => true), new Promise((resolve) => { + timer = setTimeout(() => { resolve(false) }, 500) + })]) + if (!exited) console.error('dsh desktop: operation report Worker has not exited; continuing shutdown') + } finally { clearTimeout(timer) } +} + function persistCrashReport(error: unknown, source: CrashReportSource): Promise { - return writeCrashReport(app.getPath('logs'), { + const directory = app.getPath('logs') + const report = writeCrashReport(directory, { + operationHistoryPlanned: !shuttingDown && !operationReportsStopping, source, phase: backendReady ? 'running' : 'startup', error, @@ -121,6 +154,17 @@ function persistCrashReport(error: unknown, source: CrashReportSource): Promise< }, time: new Date(), }) + void report.then((path) => { + if (path !== undefined && operationReportJob === undefined && !shuttingDown && !operationReportsStopping) { + operationReportAbort = new AbortController() + operationReportJob = runOperationReportJob({ reportPath: path, directory: join(app.getPath('userData'), 'plugin-operations'), + limits: { bytes: 64 * 1024, recordBytes: 4096, records: 100, outputBytes: 64 * 1024 }, + journal: operationJournal?.status() ?? null, + }, { timeoutMs: 500, cancellationGraceMs: 100 }, operationReportAbort.signal) + void operationReportJob.finally(() => { operationReportJob = undefined; operationReportAbort = undefined }) + } + }).catch((_error: unknown) => { /* Basic persistence failure is owned by fatal recovery. */ }) + return report } function reportFatal(error: unknown, source: CrashReportSource): void { @@ -130,7 +174,12 @@ function reportFatal(error: unknown, source: CrashReportSource): void { void persistCrashReport(error, source) return } - void recovery.report(error, source).catch((failure: unknown) => { console.error(failure); app.exit(1) }) + void recovery.report(error, source).catch(async (failure: unknown) => { + console.error(failure) + shuttingDown = true + await stopOperationReports() + app.exit(1) + }) } protocol.registerSchemesAsPrivileged([{ @@ -374,7 +423,8 @@ async function main(): Promise { let updateStopFailure: DesktopHostUncleanExitError | undefined let updateState: DesktopUpdateState = { phase: 'idle' } const systemLanguages = app.getPreferredSystemLanguages() - let locale = resolveDesktopStartupLocale(null, systemLanguages) + let locale = windowsLanguage === undefined + ? resolveDesktopStartupLocale(null, systemLanguages) : resolveDesktopLocale(windowsLanguage) windowsLanguage = locale.id let mandatoryPolicy: DesktopMandatoryUpdatePolicy | undefined let mandatoryUI: DesktopMandatoryUpdateWindow | undefined @@ -470,7 +520,12 @@ async function main(): Promise { const host = new DesktopHostProcess(resources.node, resources.dsh, activeProject, hostInspectPort, { ...hostEnvironment, DSH_CLIENT_VERSION: desktopClientVersion() }, onFailure, primaryRuntime, - resources, (next) => { platformView.setSession(next) }) + resources, (next) => { platformView.setSession(next) }, (record) => { + operationJournal ??= new OperationJournal(join(app.getPath('userData'), 'plugin-operations'), { + segmentBytes: 256 * 1024, recordBytes: 4096, queuedBytes: 64 * 1024, + }) + operationJournal.enqueue(JSON.stringify(record)) + }) return { start: async () => { const ready = await host.start() @@ -565,6 +620,10 @@ async function main(): Promise { fileDragStopped = false } const restoreHost = state.failedOperation === 'install' && updateStoppedHost && !quitting + if (state.failedOperation === 'install' && !quitting) { + operationReportsStopping = shuttingDown + operationReportStop = undefined + } shellInstallerOwnsQuit = false updateStoppedHost = false if (restoreHost) { @@ -593,7 +652,11 @@ async function main(): Promise { if (backend.host === undefined || welcomeBackend === undefined) throw new Error('desktop welcome: backend unavailable') return welcomeBackend.read() } - stopForRecovery = () => backend.close() + stopForRecovery = async () => { + const reports = stopOperationReports() + try { await backend.close() } + finally { await Promise.all([operationJournal?.drain(500), reports]) } + } const reconcileBackend = (): Promise => { startup ??= (async () => { @@ -651,14 +714,17 @@ async function main(): Promise { await disposeFileDrag().catch((error: unknown) => { console.error(error) }) requireCleanStop = true updateStopFailure = undefined - await backend.stop() + await Promise.all([backend.stop(), stopOperationReports()]) updateStoppedHost = true // The backend's async cleanup callback can assign this after the reset above. const stopFailure = updateStopFailure as DesktopHostUncleanExitError | undefined if (stopFailure !== undefined) throw new DesktopUpdatePreparationError('stop-failed', locale.messages.updateStopFailed, stopFailure.message) + await operationJournal?.drain(500) updateJournal?.action('install-confirmed') shellInstallerOwnsQuit = true } catch (error) { + operationReportsStopping = shuttingDown + operationReportStop = undefined if (!updateStoppedHost) await host.updateTasks('unlock').catch((unlockError: unknown) => { console.error(unlockError) }) throw error } finally { @@ -761,6 +827,7 @@ async function main(): Promise { || !event.senderFrame.url.startsWith('dsh-app://app/')) throw new Error('Rejected Platform command') return owner } + installFileActions(assertMainApplication, () => hostUrl) ipcMain.on(PLATFORM_IPC.bootstrap, (event) => { try { event.returnValue = platformView.bootstrap(event) } catch { event.returnValue = null } @@ -793,6 +860,7 @@ async function main(): Promise { if (window === undefined || event.sender !== window.webContents || event.senderFrame !== window.webContents.mainFrame || typeof next !== 'string') return const current = resolveDesktopStartupLocale(next, systemLanguages) + writeDesktopLocaleCache(app.getPath('userData'), current.id) if (current.id === locale.id) return locale = current platformView.notifyLocaleChanged() @@ -992,8 +1060,8 @@ async function main(): Promise { { label: currentDesktopLocale().messages.checkUpdatesMenu, click: () => { void openUpdatePrompt(true) } }, ...process.platform === 'darwin' || process.platform === 'win32' ? [{ label: currentDesktopLocale().messages.cliCommandMenu, click: () => { void commandManager.show() } }] : [], + { type: 'separator' }, ...development ? [ - { type: 'separator' as const }, { label: currentDesktopLocale().messages.reloadPageMenu, role: 'reload' as const }, { label: currentDesktopLocale().messages.restartAppHostMenu, click: () => { if (quitting) return @@ -1001,20 +1069,23 @@ async function main(): Promise { quitWithoutConfirmation() } }, ] : [], + { role: 'toggleDevTools', label: currentDesktopLocale().messages.toggleDevToolsMenu }, { type: 'separator' }, ...hideCommands, { role: 'quit', ...(darwin ? { label: currentDesktopLocale().messages.quitApplication } : process.platform === 'win32' ? { label: currentDesktopLocale().messages.exitApplication } : {}) }, ] - const devToolsItems: MenuItemConstructorOptions[] = [ + const devToolsF12Shortcut: MenuItemConstructorOptions = { role: 'toggleDevTools', visible: false, accelerator: 'F12' } + const windowsDevToolsShortcuts: MenuItemConstructorOptions[] = [ { role: 'toggleDevTools', visible: false }, - { role: 'toggleDevTools', visible: false, accelerator: 'F12' }, + devToolsF12Shortcut, ] const refreshApplicationMenu = (): void => { - Menu.setApplicationMenu(Menu.buildFromTemplate(process.platform === 'win32' ? devToolsItems : [{ - label: darwin ? app.name : currentDesktopLocale().messages.application, - submenu: [...applicationItems(), ...devToolsItems], - }, ...platformMenus()])) + Menu.setApplicationMenu(Menu.buildFromTemplate(process.platform === 'win32' + ? windowsDevToolsShortcuts : [{ + label: darwin ? app.name : currentDesktopLocale().messages.application, + submenu: [...applicationItems(), devToolsF12Shortcut], + }, ...platformMenus()])) tray?.relabel() } refreshApplicationMenu() @@ -1076,13 +1147,11 @@ async function main(): Promise { Menu.buildFromTemplate(items).popup({ window, x: Math.round(x * zoom), y: Math.round(y * zoom), callback: resolve }) }) }) - ipcMain.on(DESKTOP_IPC.windowsAppearance, (event, language: unknown, color: unknown, symbolColor: unknown) => { + ipcMain.on(DESKTOP_IPC.windowsAppearance, (event, _language: unknown, color: unknown, symbolColor: unknown) => { if (mainWindow === undefined || event.sender !== mainWindow.webContents || event.senderFrame !== mainWindow.webContents.mainFrame) return if (!event.senderFrame.url.startsWith(`${SCHEME}://app/`)) return - if (typeof language === 'string' && /^[a-zA-Z]+(?:-[a-zA-Z0-9]+)*$/u.test(language)) { - windowsLanguage = language - } + // Document lang starts as English before Host locale bootstrap; only localeChanged owns shell language. // Empty colors precede client stylesheet installation; only CSS color values cross IPC. const validColor = (value: unknown): value is string => typeof value === 'string' && /^(?:#[\da-f]{3,8}|rgba?\([\d.,%\s]+\))$/iu.test(value) @@ -1236,6 +1305,7 @@ async function main(): Promise { const state = await readWelcomeState() if (isQuitting() || backend.state.phase !== 'ready') return locale = resolveDesktopStartupLocale(state.localePreference, systemLanguages) + writeDesktopLocaleCache(app.getPath('userData'), locale.id) windowsLanguage = locale.id refreshApplicationMenu() if (!enteredWorkspace && needsWelcome({ loggedIn: state.loggedIn, hasApiKey: state.hasApiKey })) { @@ -1288,11 +1358,15 @@ async function main(): Promise { updateSchedule.dispose() updateDialog.dispose() mandatoryUI?.dispose() - void Promise.all([Promise.resolve(mandatoryPolicy?.dispose()).then(() => policyAuth?.dispose()), backend.close(), - // A Platform cleanup failure is logged without cutting the remaining Host shutdown short. - platformView.dispose().catch((error: unknown) => { console.error(error) }), - disposeFileDrag().catch((error: unknown) => { console.error(error) })]) - .catch((error: unknown) => { console.error(error) }).finally(() => { app.quit() }) + void Promise.all([stopOperationReports(), Promise.resolve(mandatoryPolicy?.dispose()).then(() => policyAuth?.dispose()), + backend.close().then(async () => { await operationJournal?.drain(500) }, async (error: unknown) => { + await operationJournal?.drain(500) + throw error + }), + platformView.dispose(), + disposeFileDrag(), + ].map(cleanup => cleanup.catch((error: unknown) => { console.error(error) }))) + .then(() => { app.quit() }) } app.on('before-quit', (event) => { if (shellInstallerOwnsQuit) { @@ -1381,7 +1455,9 @@ if (ownsDesktopInstance) void app.whenReady().then(main).catch(async (error: unk await writeFile(diagnosticFile, `${error instanceof Error ? error.stack ?? message : message}\n`).catch(() => undefined) } reportFatal(error, 'main') -}).catch((error: unknown) => { +}).catch(async (error: unknown) => { console.error(error) + shuttingDown = true + await stopOperationReports() app.exit(1) }) diff --git a/apps/desktop/src/operation-history.ts b/apps/desktop/src/operation-history.ts new file mode 100644 index 0000000000..ca9584f79f --- /dev/null +++ b/apps/desktop/src/operation-history.ts @@ -0,0 +1,120 @@ +/** Bounded, cancellable reads of Desktop-owned plugin operation history. */ +import { open } from 'node:fs/promises' +import { join } from 'node:path' +import { setImmediate } from 'node:timers/promises' +import { parsePluginOperationRecord, type PluginOperationRecord } from '@deepseek-ai/dsh-plugin-manager/diagnostic' + +/** Resource budgets for auxiliary history collection, independent of basic crash report writing. */ +export interface OperationHistoryReadLimits { + readonly bytes: number + readonly recordBytes: number + readonly records: number +} + +/** Collection facts; incomplete history must not be interpreted as absence of plugin changes. */ +export interface OperationHistoryReadResult { + readonly records: readonly PluginOperationRecord[] + readonly bytesRead: number + /** Distinct files from which at least one byte was read. */ + readonly filesRead: number + readonly truncated: boolean + readonly invalidRecords: number + readonly unavailableFiles: number + readonly cancelled: boolean +} + +/** + * Read only the bounded tails of the two owned history files, newest segment first. + * Cancellation is observed between bounded records after yielding to Worker messages and stops subsequent I/O and parsing. + * An already-issued OS read must settle before its handle closes. + * @param directory - Desktop's operation history directory; unrelated files are never enumerated. + * @param limits - Positive byte, record-size and record-count budgets. + * @param signal - Caller-owned collection deadline or shutdown cancellation. + * @returns Partial records and explicit omissions; filesystem failures never reject the collection. + */ +export async function readOperationHistory( + directory: string, + limits: OperationHistoryReadLimits, + signal: AbortSignal, +): Promise { + if (![limits.bytes, limits.recordBytes, limits.records].every(value => Number.isSafeInteger(value) && value > 0)) { + throw new RangeError('Operation history budgets must be positive safe integers') + } + await setImmediate() + const cancelled = (): boolean => signal.aborted + const records: PluginOperationRecord[] = [] + let bytesRead = 0 + const seenFiles = new Set() + let truncated = false + let invalidRecords = 0 + let unavailableFiles = 0 + for (const name of ['operations.jsonl', 'operations.previous.jsonl']) { + if (cancelled()) break + try { + await using handle = await open(join(directory, name), 'r') + if (cancelled()) break + const fileStat = await handle.stat() + if (cancelled()) break + if (!fileStat.isFile()) { + unavailableFiles++ + continue + } + const identity = `${String(fileStat.dev)}:${String(fileStat.ino)}` + if (seenFiles.has(identity)) { + truncated = true + continue + } + if (fileStat.size > 0 && (bytesRead >= limits.bytes || records.length >= limits.records)) { + truncated = true + break + } + + const readLength = Math.min(fileStat.size, limits.bytes - bytesRead) + const readStart = fileStat.size - readLength + const buffer = Buffer.alloc(readLength) + let readOffset = 0 + while (readOffset < readLength && !cancelled()) { + const read = await handle.read(buffer, readOffset, Math.min(16 * 1024, readLength - readOffset), readStart + readOffset) + bytesRead += read.bytesRead + if (read.bytesRead === 0) break + readOffset += read.bytesRead + } + if (readOffset > 0) seenFiles.add(identity) + if (cancelled()) break + truncated ||= readStart > 0 || readOffset < readLength + + // An unterminated last record can still be in flight; never parse it as a committed record. + if (readOffset === 0) continue + let lineEnd = buffer.lastIndexOf(10, readOffset - 1) + if (lineEnd !== readOffset - 1) truncated = true + while (lineEnd >= 0 && records.length < limits.records && !cancelled()) { + await setImmediate() + if (cancelled()) break + const previousLineEnd = lineEnd === 0 ? -1 : buffer.lastIndexOf(10, lineEnd - 1) + if (previousLineEnd < 0 && readStart > 0) { + truncated = true + break + } + const recordBytes = lineEnd - previousLineEnd - 1 + if (recordBytes > limits.recordBytes) { + invalidRecords++ + } else if (recordBytes > 0) { + try { + const value: unknown = JSON.parse(buffer.subarray(previousLineEnd + 1, lineEnd).toString('utf8')) + const record = parsePluginOperationRecord(value) + if (record === undefined) invalidRecords++ + else records.push(record) + } catch (_error) { + // A corrupt record does not invalidate independently delimited older records. + invalidRecords++ + } + } + lineEnd = previousLineEnd + } + if (lineEnd >= 0) truncated = true + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') unavailableFiles++ + } + } + return { records, bytesRead, filesRead: seenFiles.size, truncated, invalidRecords, unavailableFiles, cancelled: cancelled() } +} diff --git a/apps/desktop/src/operation-journal.ts b/apps/desktop/src/operation-journal.ts new file mode 100644 index 0000000000..b72cc6baac --- /dev/null +++ b/apps/desktop/src/operation-journal.ts @@ -0,0 +1,208 @@ +/** Single-shell, bounded persistence for already-projected operation diagnostics. */ +import { mkdir, open, rename, stat, writeFile } from 'node:fs/promises' +import { join } from 'node:path' + +/** Budgets include serialized JSON and its line delimiter. */ +export interface OperationJournalLimits { + readonly segmentBytes: number + readonly recordBytes: number + readonly queuedBytes: number +} + +/** In-memory omissions for the current shell lifetime; missing records never imply no operations occurred. */ +export interface OperationJournalStatus { + readonly dropped: number + readonly failed: number + readonly queuedBytes: number + readonly disabled: boolean + /** Damaged or oversized segments repaired; their lost record count is unknown. */ + readonly repairedSegments: number +} + +/** Owns two known files and one serial writer; the owning shell must exclude other writers. */ +export class OperationJournal { + private readonly queue: string[] = [] + private queuedBytes = 0 + private dropped = 0 + private failed = 0 + private repairedSegments = 0 + private disabled = false + private closed = false + private writing: Promise | undefined + private initialized = false + private readonly abort = new AbortController() + + /** + * @param directory - Directory reserved for the shell's operation journal. + * @param limits - Positive byte budgets, with recordBytes no greater than either other budget. + */ + constructor( + private readonly directory: string, + private readonly limits: OperationJournalLimits, + ) { + if (![limits.segmentBytes, limits.recordBytes, limits.queuedBytes].every(value => Number.isSafeInteger(value) && value > 0) + || limits.recordBytes > limits.segmentBytes || limits.recordBytes > limits.queuedBytes) { + throw new RangeError('Invalid operation journal budgets') + } + } + + /** + * Queue one prevalidated, whitelisted JSON record without awaiting disk I/O. + * @param record - An already serialized JSON object without literal line delimiters. + * @returns Whether the record was accepted; disk failures are reported separately by status(). + */ + enqueue(record: string): boolean { + const line = record + '\n' + const bytes = Buffer.byteLength(line) + if (this.closed || this.disabled || bytes > this.limits.recordBytes + || bytes + this.queuedBytes > this.limits.queuedBytes || /[\r\n]/u.test(record)) { + this.dropped++ + return false + } + this.queue.push(line) + this.queuedBytes += bytes + this.startWriter() + return true + } + + /** @returns Current queue occupancy and omission counters. */ + status(): OperationJournalStatus { + return { + dropped: this.dropped, + failed: this.failed, + queuedBytes: this.queuedBytes, + disabled: this.disabled, + repairedSegments: this.repairedSegments, + } + } + + /** Stop accepting records and await completion of the owned writer. */ + async close(): Promise { + this.closed = true + while (this.writing !== undefined) await this.writing + } + + /** + * Wait for queued records during shutdown or installer handoff without holding the application indefinitely. + * @param timeoutMs - Waiting budget before disabling the writer and cancelling subsequent I/O. + * @returns True after the queue settles successfully; false immediately when disabled, or on failure or deadline. + * False does not confirm that an issued OS request has settled. + */ + async drain(timeoutMs: number): Promise { + if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new RangeError('Invalid journal drain deadline') + if (this.disabled) return false + let timer: ReturnType | undefined + try { + return await Promise.race([ + (async () => { + while (this.writing !== undefined) await this.writing + return !this.disabled + })(), + new Promise((resolve) => { + timer = setTimeout(() => { + this.disabled = true + this.abort.abort() + resolve(false) + }, timeoutMs) + }), + ]) + } finally { + clearTimeout(timer) + } + } + + private startWriter(): void { + this.writing ??= this.writeQueue().finally(() => { + this.writing = undefined + if (this.queue.length > 0) this.startWriter() + }) + } + + private async writeQueue(): Promise { + try { + await mkdir(this.directory, { recursive: true, mode: 0o700 }) + this.abort.signal.throwIfAborted() + const current = join(this.directory, 'operations.jsonl') + const previous = join(this.directory, 'operations.previous.jsonl') + if (!this.initialized) { + await this.prepareSegments(current, previous) + this.initialized = true + } + for (let line = this.queue[0]; line !== undefined; line = this.queue[0]) { + this.abort.signal.throwIfAborted() + const bytes = Buffer.byteLength(line) + let size = 0 + try { + size = (await stat(current)).size + } + catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error + } + this.abort.signal.throwIfAborted() + if (size > this.limits.segmentBytes) { + // An oversized pre-existing segment is not copied into the bounded retained history. + await writeFile(current, '', { mode: 0o600 }) + this.repairedSegments++ + } else if (size + bytes > this.limits.segmentBytes) { + await rename(current, previous) + } + this.abort.signal.throwIfAborted() + await writeFile(current, line, { flag: 'a', mode: 0o600, signal: this.abort.signal }) + this.queue.shift() + this.queuedBytes -= bytes + } + } catch (_error) { + // A failed append may have written a partial line; disable this writer rather than concatenate another record. + this.disabled = true + this.failed += this.queue.length + this.queue.length = 0 + this.queuedBytes = 0 + } + } + + private async prepareSegments(current: string, previous: string): Promise { + try { + const size = (await stat(previous)).size + this.abort.signal.throwIfAborted() + if (size > this.limits.segmentBytes) { + await writeFile(previous, '', { mode: 0o600 }) + this.repairedSegments++ + } + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error + } + this.abort.signal.throwIfAborted() + { + await using handle = await open(current, 'r+').catch((error: unknown) => { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error + this.abort.signal.throwIfAborted() + return open(current, 'wx+', 0o600) + }) + this.abort.signal.throwIfAborted() + const size = (await handle.stat()).size + this.abort.signal.throwIfAborted() + if (size > this.limits.segmentBytes) { + await handle.truncate(0) + this.repairedSegments++ + } else if (size > 0) { + const byte = Buffer.alloc(1) + const read = await handle.read(byte, 0, 1, size - 1) + if (read.bytesRead !== 1 || byte[0] !== 10) { + const buffer = Buffer.alloc(size) + let offset = 0 + while (offset < size) { + this.abort.signal.throwIfAborted() + const chunk = await handle.read(buffer, offset, size - offset, offset) + if (chunk.bytesRead === 0) break + offset += chunk.bytesRead + } + this.abort.signal.throwIfAborted() + // Keep committed lines in both segments; only the unfinished append is discarded. + await handle.truncate(buffer.subarray(0, offset).lastIndexOf(10) + 1) + this.repairedSegments++ + } + } + } + this.abort.signal.throwIfAborted() + } +} diff --git a/apps/desktop/src/operation-report-job.ts b/apps/desktop/src/operation-report-job.ts new file mode 100644 index 0000000000..b78259df78 --- /dev/null +++ b/apps/desktop/src/operation-report-job.ts @@ -0,0 +1,106 @@ +/** Worker lifetime for an auxiliary report; completion includes worker exit. */ +import { Worker } from 'node:worker_threads' +import type { OperationReportLimits } from './operation-report.ts' +import type { OperationJournalStatus } from './operation-journal.ts' + +/** Facts passed to the isolated collector after the basic report is saved. */ +export interface OperationReportJobInput { + readonly reportPath: string + readonly directory: string + readonly limits: OperationReportLimits + readonly journal: OperationJournalStatus | null +} + +/** Collection and cooperative shutdown share one total budget. */ +export interface OperationReportJobOptions { + /** Deadline for requesting forced termination, including Worker startup. */ + readonly timeoutMs: number + /** Reserved part of timeoutMs for cancellation and resource cleanup. */ + readonly cancellationGraceMs: number +} + +/** Cancellation can leave a partial append; the independently saved basic report remains valid. */ +export interface OperationReportJobResult { + readonly appended: boolean + readonly timedOut: boolean + readonly cancelled: boolean +} + +/** + * Collect history, request cooperative cancellation, then force termination if cleanup exceeds its budget. + * @param input - Bounded collection request for an existing basic report. + * @param options - Total deadline and the cleanup window reserved within it. + * @param signal - Application shutdown or recovery cancellation; an already-aborted signal prevents startup. + * @returns Append outcome only after Worker exit; cancellation or termination requests alone do not confirm exit. + */ +export async function runOperationReportJob( + input: OperationReportJobInput, + options: OperationReportJobOptions, + signal: AbortSignal, +): Promise { + const { timeoutMs, cancellationGraceMs } = options + if (!Number.isSafeInteger(timeoutMs) || !Number.isSafeInteger(cancellationGraceMs) + || cancellationGraceMs < 1 || timeoutMs <= cancellationGraceMs) throw new RangeError('Invalid operation report deadlines') + if (signal.aborted) return { appended: false, timedOut: false, cancelled: true } + const terminationDeadline = performance.now() + timeoutMs + let worker: Worker + try { + worker = new Worker(new URL('./operation-report-worker.js', import.meta.url), { + workerData: input, + resourceLimits: { + maxOldGenerationSizeMb: 32, + maxYoungGenerationSizeMb: 8, + stackSizeMb: 2, + }, + }) + } + catch (_error) { + return { appended: false, timedOut: false, cancelled: false } + } + return new Promise((resolve) => { + let appended = false + let failed = false + let timedOut = false + let cancelled = false + let terminationTimer: ReturnType | undefined + + const terminateWorker = (): void => { + void worker.terminate().catch(() => { + failed = true + }) + } + + const requestCancellation = (): void => { + if (cancelled) return + cancelled = true + clearTimeout(collectionTimer) + try { + worker.postMessage('cancel') + } + catch (_error) { + failed = true + } + terminationTimer = setTimeout(terminateWorker, Math.max(0, Math.min(cancellationGraceMs, terminationDeadline - performance.now()))) + } + + const collectionTimer = setTimeout(() => { + timedOut = true + requestCancellation() + }, Math.max(0, terminationDeadline - performance.now() - cancellationGraceMs)) + + signal.addEventListener('abort', requestCancellation, { once: true }) + worker.on('message', (message: unknown) => { + appended = message === true + }) + worker.once('error', () => { + failed = true + }) + worker.once('exit', (code) => { + clearTimeout(collectionTimer) + clearTimeout(terminationTimer) + signal.removeEventListener('abort', requestCancellation) + resolve({ appended: appended && code === 0 && !failed && !cancelled, timedOut, cancelled }) + }) + if (signal.aborted) requestCancellation() + }) +} diff --git a/apps/desktop/src/operation-report-worker.ts b/apps/desktop/src/operation-report-worker.ts new file mode 100644 index 0000000000..c7ee527b77 --- /dev/null +++ b/apps/desktop/src/operation-report-worker.ts @@ -0,0 +1,36 @@ +/** Isolated auxiliary-report I/O; the shell owns termination and observes worker exit. */ +import { parentPort, workerData } from 'node:worker_threads' +import { z } from 'zod' +import { appendOperationReport } from './operation-report.ts' + +const positive = z.number().int().positive().max(Number.MAX_SAFE_INTEGER) +const input = z.object({ + reportPath: z.string(), + directory: z.string(), + limits: z.object({ + bytes: positive, + recordBytes: positive, + records: positive, + outputBytes: positive, + }), + journal: z.object({ + dropped: z.number().int().nonnegative(), + failed: z.number().int().nonnegative(), + repairedSegments: z.number().int().nonnegative(), + queuedBytes: z.number().int().nonnegative(), + disabled: z.boolean(), + }).nullable(), +}).parse(workerData) + +const cancellation = new AbortController() +const cancel = (message: unknown): void => { + if (message === 'cancel') cancellation.abort() +} +parentPort?.on('message', cancel) +try { + const appended = await appendOperationReport(input.reportPath, input.directory, input.limits, cancellation.signal, input.journal) + parentPort?.postMessage(appended) +} finally { + parentPort?.off('message', cancel) + parentPort?.close() +} diff --git a/apps/desktop/src/operation-report.ts b/apps/desktop/src/operation-report.ts new file mode 100644 index 0000000000..2c023abf82 --- /dev/null +++ b/apps/desktop/src/operation-report.ts @@ -0,0 +1,62 @@ +/** Best-effort operation history appended only after the independent basic report exists. */ +import { writeFile } from 'node:fs/promises' +import { setImmediate } from 'node:timers/promises' +import { readOperationHistory, type OperationHistoryReadLimits } from './operation-history.ts' +import type { OperationJournalStatus } from './operation-journal.ts' + +/** Read budgets and the complete appended section's UTF-8 byte budget. */ +export interface OperationReportLimits extends OperationHistoryReadLimits { + readonly outputBytes: number +} + +/** + * Append a bounded summary without rewriting the basic report's bytes. + * A missing completion marker means the auxiliary section is unavailable or incomplete. + * @param reportPath - Successfully saved basic report. + * @param directory - Owned operation history directory. + * @param limits - Read and parse budgets. + * @param signal - Collection deadline or shutdown cancellation; already-issued OS I/O must settle. + * @param journal - Current writer status, or null when this shell has not received operation records. + * @returns Whether the complete auxiliary section was appended. + */ +export async function appendOperationReport( + reportPath: string, + directory: string, + limits: OperationReportLimits, + signal: AbortSignal, + journal: OperationJournalStatus | null, +): Promise { + try { + if (!Number.isSafeInteger(limits.outputBytes) || limits.outputBytes < 1) return false + const cancelled = (): boolean => signal.aborted + const history = await readOperationHistory(directory, limits, signal) + if (cancelled()) return false + + const { records, ...facts } = history + const renderHeader = (omitted: number): string => '\n--- recent plugin operations (context, not proof of cause) ---\n' + + JSON.stringify({ journal, ...facts, outputRecordsOmitted: omitted }).slice(0, -1) + ',"records":[' + const completionFooter = ']}\n--- operation history collection complete; consult omission counters above ---\n' + let outputBytes = Buffer.byteLength(renderHeader(records.length) + completionFooter) + if (outputBytes > limits.outputBytes) return false + + const encodedRecords: string[] = [] + for (const record of records) { + await setImmediate() + if (cancelled()) return false + const encodedRecord = JSON.stringify(record) + const additionalBytes = Buffer.byteLength(encodedRecord) + (encodedRecords.length === 0 ? 0 : 1) + if (outputBytes + additionalBytes > limits.outputBytes) break + encodedRecords.push(encodedRecord) + outputBytes += additionalBytes + } + + const reportSection = renderHeader(records.length - encodedRecords.length) + encodedRecords.join(',') + completionFooter + await setImmediate() + if (cancelled()) return false + await writeFile(reportPath, reportSection, { flag: 'a', signal }) + return true + } catch (_error) { + // The independently written basic report remains usable, including after a partial append. + return false + } +} diff --git a/apps/desktop/src/preload-app.ts b/apps/desktop/src/preload-app.ts index c9937a301e..26266b4f1c 100644 --- a/apps/desktop/src/preload-app.ts +++ b/apps/desktop/src/preload-app.ts @@ -1,3 +1,4 @@ +import type { FileSaveResult } from '@deepseek-ai/dsh-client-ui-file-actions/types' /** Origin-scoped boot, native directory selection, host paths of picked files, and update presentation with native confirmation actions. */ import type { DesktopShortcutInput, ShortcutConfigSnapshot, ShortcutSaveResult } from '@deepseek-ai/dsh-client-shortcuts/protocol' @@ -14,6 +15,11 @@ import type { FileDragHandle } from '@deepseek-ai/dsh-util-file-drag' function createProductApi(): DshDesktopProductApi { return { protocolVersion: 1, + fileActions: { + save: request => ipcRenderer.invoke(DESKTOP_IPC.fileSave, request) as Promise, + readClipboardImage: url => ipcRenderer.invoke(DESKTOP_IPC.clipboardImageRead, url) as + Promise<{ bytes: Uint8Array; mediaType: string }>, + }, browser: createDesktopBrowserBridge(), fileDrag: { prepare: (source, requestId) => ipcRenderer.invoke(DESKTOP_IPC.fileDragPrepare, source, requestId) as diff --git a/apps/desktop/tests/README.i18n.yaml b/apps/desktop/tests/README.i18n.yaml index fbb1c7d3e9..97e9812489 100644 --- a/apps/desktop/tests/README.i18n.yaml +++ b/apps/desktop/tests/README.i18n.yaml @@ -2,27 +2,30 @@ # 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 apps/desktop/tests/README.md -/desktop-local-update-verification: - en: 194f1f0f1ca90743 - zh: 773ca28e04c8911f -/desktop-local-update-verification/summary: +/desktop-local-verification: + en: 5056a9b4d24c1880 + zh: 4d0c9d8e5f69d153 +/desktop-local-verification/summary: en: 94559f431b0b2151 zh: 1a22166a2bc59686 -/desktop-local-update-verification/table-of-contents: - en: 86afdf78fa613876 - zh: 66fad143d99e999f -/desktop-local-update-verification/update-dialog-themes: +/desktop-local-verification/table-of-contents: + en: fa9e3048995c0e3c + zh: ef30232afa4ba125 +/desktop-local-verification/fault-report-verification: + en: a418eb04ce93b1ee + zh: 1ec04872a66ce1b7 +/desktop-local-verification/update-dialog-themes: en: d086c3b38ce623f1 zh: 8327c31092f5f174 -/desktop-local-update-verification/native-overlay-visibility: +/desktop-local-verification/native-overlay-visibility: en: 6f4de4503748f3e2 zh: 648370375f16e463 -/desktop-local-update-verification/manual-walkthrough: +/desktop-local-verification/manual-walkthrough: en: c4b4ee8763d8464a zh: ee2159bc08966592 -/desktop-local-update-verification/evidence: +/desktop-local-verification/evidence: en: dcb2473264c825d4 zh: cebb2832efa15974 -/desktop-local-update-verification/open-verification: +/desktop-local-verification/open-verification: en: 20e9ea47acb1ff50 zh: acce24b56d57e12c diff --git a/apps/desktop/tests/README.md b/apps/desktop/tests/README.md index 400bfb0c00..cda4533699 100644 --- a/apps/desktop/tests/README.md +++ b/apps/desktop/tests/README.md @@ -1,4 +1,4 @@ -# Desktop local update verification +# Desktop local verification English | [中文](README.zh.md) @@ -10,12 +10,26 @@ Installed qualification can opt into `DSH_DESKTOP_UPDATE_JOURNAL_DIR`, an absolu ## Table of Contents +- [Fault-report verification](#verification-diagnostics) - [Update dialog themes](#verification-theme) - [Native overlay visibility](#verification-overlay) - [Evidence](#verification-evidence) - [Manual walkthrough](#verification-interactive) - [Open verification](#verification-open) + + +## Fault-report verification + +See [recovery and diagnostics](../docs/diagnostics/README.md) for product behavior and limitations. + +Use a disposable profile and separate Electron `userData` with the actual packaged client. Construct a minimal local bundle with `package.json`, `dsh.bundle.patch` pointing to `cordis.patch.yml`, and an optional plugin module; archive it as a local `.tgz`. These packages deliberately break the application and must not be published or installed in a daily profile. + +Exercise import and plugin-initialization exceptions, an asynchronous exception after `appReady`, and a nonzero Host exit. A patch disabling the `agent`, `session`, `llm`, and `tools` providers exercises missing-service diagnostics. To check cross-restart history, select that bundle through `pluginManager`, then restart the same profile. Runtime scenarios require observing actual client readiness; `appReady` alone does not establish that the window is visible. + +Check the original error and cause or exit code, operation and Host run IDs across restart, report-collection completion and omissions, file retrieval from the native dialog, and startup after plugin recovery. Record the package version and source commit; successful package generation or a management result alone does not establish client functionality. Restore protocol associations and stop test processes afterward. + +For resource checks, use large sparse history files, unrelated files, dense records, and malformed or unfinished lines. Measure setup separately from collection in fresh processes, recording actual bytes read, output size, time, and peak memory. To check Worker cancellation, a test-only module hook can hold an asynchronous file open after writing an entry marker. Confirm that marker, observe Worker exit after the deadline, and compare the basic report bytes. This does not reproduce a kernel-hung system call or establish packaged-client behavior. ## Update dialog themes diff --git a/apps/desktop/tests/README.zh.md b/apps/desktop/tests/README.zh.md index b52cf6309e..6cca69e8ac 100644 --- a/apps/desktop/tests/README.zh.md +++ b/apps/desktop/tests/README.zh.md @@ -1,4 +1,4 @@ -# Desktop 本地更新验证 +# Desktop 本地验证 [English](README.md) | 中文 @@ -10,12 +10,26 @@ ## 目录 +- [故障报告验证](#verification-diagnostics) - [更新弹窗主题](#verification-theme) - [原生浮层可见性](#verification-overlay) - [验证证据](#verification-evidence) - [手动演练](#verification-interactive) - [待验证事项](#verification-open) + + +## 故障报告验证 + +产品行为与限制见[故障恢复与诊断](../docs/diagnostics/README.zh.md)。 + +使用可丢弃的 profile、独立的 Electron `userData` 和实际打包客户端。构造最小本地组合包：`package.json` 的 `dsh.bundle.patch` 指向 `cordis.patch.yml`，需要执行代码时再加入插件模块，然后打成可本地安装的 `.tgz`。这些包会故意使应用出错，不得发布或安装到日常 profile。 + +分别构造模块导入异常、插件初始化异常、`appReady` 后的异步异常，以及 Host 非零退出。用 patch 禁用 `agent`、`session`、`llm`、`tools` 提供者，检查服务缺失诊断。跨重启场景通过 `pluginManager` 选入该组合包，再重启同一 profile。运行期场景须实际观察客户端就绪；`appReady` 不代表窗口已经显示。 + +检查原始错误与 cause 或退出码、跨重启的操作 ID 和 Host 运行 ID、报告收集完成标记与遗漏信息、原生弹窗中的文件获取，以及禁用插件恢复后的启动。记录安装包版本和源码提交；生成测试包成功或管理操作返回成功，都不能代替客户端功能验证。测试后恢复协议关联并退出测试进程。 + +资源验证可构造大型稀疏历史文件、大量无关文件、密集记录，以及损坏行和未完成行。在独立新进程中测量，分开记录数据构造与收集开销，并核对实际读取量、输出大小、耗时和峰值内存。验证 Worker 取消时，可用仅测试加载的模块钩子在写入进入标记后挂起异步文件打开操作；先确认标记，再观察期限到达后的 Worker 退出，并逐字节核对基本报告。该方法不模拟内核系统调用卡死，也不代替打包客户端验证。 ## 更新弹窗主题 diff --git a/apps/desktop/tests/cua-optional-package.spec.ts b/apps/desktop/tests/cua-optional-package.spec.ts index 3f3f7ad572..85ef15f0ee 100644 --- a/apps/desktop/tests/cua-optional-package.spec.ts +++ b/apps/desktop/tests/cua-optional-package.spec.ts @@ -1,4 +1,4 @@ -/** Cold pnpm requests exercise shipped CUA dependency/platform metadata with inert package contents. */ +/** Cold pnpm requests exercise on-demand CUA dependency/platform metadata with inert package contents. */ import { createHash } from 'node:crypto' import { createServer } from 'node:http' import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' @@ -37,18 +37,20 @@ it('fetches the macOS optional tarball only for Darwin, with an empty cache for const cli = await readManifest('apps/cli') const bundle = await readManifest('packages/experimental/cua-bundle') const native = await readManifest('packages/experimental/cua-macos') - expect(cli.dependencies).toHaveProperty(bundleName) + expect(cli.dependencies).not.toHaveProperty(bundleName) expect(bundle.dependencies).not.toHaveProperty(providerName) expect(bundle.optionalDependencies).toEqual({ [providerName]: 'workspace:*' }) expect(native.os).toEqual(['darwin']) const version = '1.0.0' const bundleDependencies = Object.fromEntries(Object.keys(bundle.dependencies as Record).map(name => [name, version])) const manifests = [ - { name: cli.name, version, dependencies: { [bundleName]: version } }, + { name: cli.name, version }, { name: bundleName, version, dependencies: bundleDependencies, optionalDependencies: { [providerName]: version } }, ...Object.keys(bundleDependencies).map(name => ({ name, version })), { name: providerName, version, os: native.os, files: native.files }, ] + const generation = 'a'.repeat(64) + const nativePayload = `native/bin/darwin-arm64/${generation}/DSH Computer Use.app/Contents/MacOS/dsh-cua-native` const packages = new Map; bytes: Buffer }>() for (const manifest of manifests) { const name = String(manifest.name) @@ -56,18 +58,20 @@ it('fetches the macOS optional tarball only for Darwin, with an empty cache for await mkdir(directory) await writeFile(join(directory, 'package.json'), JSON.stringify(manifest)) if (name === providerName) { - await mkdir(join(directory, 'native/bin/darwin-arm64'), { recursive: true }) + await mkdir(join(directory, nativePayload, '..'), { recursive: true }) for (const file of ['.gitignore', '.npmignore']) { await writeFile(join(directory, 'native', file), await readFile(join(repository, 'packages/experimental/cua-macos/native', file))) } - await writeFile(join(directory, 'native/bin/darwin-arm64/dsh-cua-native'), 'inert native payload') + await writeFile(join(directory, 'native/bin/darwin-arm64/current.json'), JSON.stringify({ bundle: generation })) + await writeFile(join(directory, nativePayload), 'inert native payload') } await command(['pack', '--out', 'package.tgz'], directory) const bytes = await readFile(join(directory, 'package.tgz')) packages.set(name, { manifest, bytes }) if (name === providerName) { const result = await execa('tar', ['-tzf', join(directory, 'package.tgz')]) - expect(result.stdout).toContain('package/native/bin/darwin-arm64/dsh-cua-native') + expect(result.stdout).toContain('package/native/bin/darwin-arm64/current.json') + expect(result.stdout).toContain(`package/${nativePayload}`) } } const requests: string[] = [] @@ -98,13 +102,13 @@ it('fetches the macOS optional tarball only for Darwin, with an empty cache for await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve) }) const address = server.address() if (!address || typeof address === 'string') throw new Error('fixture registry has no TCP address') - for (const target of ['darwin', 'win32', 'linux', 'linux-unrestricted']) { + for (const target of ['darwin-base', 'darwin', 'win32', 'linux', 'linux-unrestricted']) { unrestricted = target === 'linux-unrestricted' const project = join(root, target) await mkdir(project) - await writeFile(join(project, 'package.json'), JSON.stringify({ private: true, dependencies: { [String(cli.name)]: version } })) + await writeFile(join(project, 'package.json'), JSON.stringify({ private: true, dependencies: { [target === 'darwin-base' ? String(cli.name) : bundleName]: version } })) await writeFile(join(project, 'pnpm-workspace.yaml'), [ - 'autoInstallPeers: false', 'supportedArchitectures:', ` os: [${unrestricted ? 'linux' : target}]`, + 'autoInstallPeers: false', 'supportedArchitectures:', ` os: [${unrestricted ? 'linux' : target === 'darwin-base' ? 'darwin' : target}]`, ' cpu: [arm64]', 'minimumReleaseAge: 0', '', ].join('\n')) requests.length = 0 @@ -113,8 +117,8 @@ it('fetches the macOS optional tarball only for Darwin, with an empty cache for `--config.registry=http://127.0.0.1:${address.port}/`, `--config.store-dir=${join(project, 'store')}`, `--config.cache-dir=${join(project, 'cache')}`, `--config.state-dir=${join(project, 'state')}`, ], project) - expect(requests).toContain(`/${bundleName}.tgz`) - expect(requests).toContain('/@deepseek-ai/dsh-cua.tgz') + expect(requests.includes(`/${bundleName}.tgz`)).toBe(target !== 'darwin-base') + expect(requests.includes('/@deepseek-ai/dsh-cua.tgz')).toBe(target !== 'darwin-base') expect(requests.includes(`/${providerName}.tgz`), `${target}: ${JSON.stringify(requests)}\n${output}`) .toBe(target === 'darwin' || unrestricted) } diff --git a/apps/desktop/tests/desktop-edgeone.spec.ts b/apps/desktop/tests/desktop-edgeone.spec.ts new file mode 100644 index 0000000000..cada969378 --- /dev/null +++ b/apps/desktop/tests/desktop-edgeone.spec.ts @@ -0,0 +1,79 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { teo } from 'tencentcloud-sdk-nodejs-teo' +import { purgeDesktopInstaller, resolveDesktopPurgeConfig } from '../scripts/desktop-edgeone.ts' + +const environment = { + DSH_DESKTOP_AUTO_UPDATE_ENV: 'production', DOWNLOAD_PROD_COS_BUCKET: 'fixture-bucket', + DOWNLOAD_PROD_COS_SECRET_ID: 'fixture-secret-id', DOWNLOAD_PROD_COS_SECRET_KEY: 'fixture-secret-key', + DOWNLOAD_PROD_EO_ZONE_ID: 'zone-fixture', +} +const config = resolveDesktopPurgeConfig(environment, 'mac-arm64') + +afterEach(() => vi.restoreAllMocks()) + +describe('production EdgeOne configuration', () => { + it.each([ + [{ DSH_DESKTOP_AUTO_UPDATE_ENV: 'test' }, /production is required/u], + [{ DSH_DESKTOP_AUTO_UPDATE_ENV: 'prod' }, /must be "test" or "production"/u], + [{ DOWNLOAD_PROD_EO_ZONE_ID: '' }, /DOWNLOAD_PROD_EO_ZONE_ID/u], + [{ DOWNLOAD_PROD_EO_ZONE_ID: 'invalid' }, /must name one EO zone/u], + [{ DOWNLOAD_PROD_COS_SECRET_KEY: '' }, /DOWNLOAD_PROD_COS_SECRET_KEY/u], + ] as const)('rejects invalid settings %j', (patch, message) => { + expect(() => resolveDesktopPurgeConfig({ ...environment, ...patch }, 'mac-arm64')).toThrow(message) + }) + + it('uses the upload plan URL verbatim and derives only cache-only destinations', () => { + const url = 'https://download.deepseek.com/changed/installer.dmg' + expect(resolveDesktopPurgeConfig(environment, 'mac-arm64', url).publicUrl).toBe(url) + expect(resolveDesktopPurgeConfig(environment, 'win-x64').publicUrl).toBe('https://download.deepseek.com/desktop/dsh-latest-windows-x64.exe') + expect(resolveDesktopPurgeConfig(environment, 'mac-x64').publicUrl).toBe('https://download.deepseek.com/desktop/dsh-latest-macos-x64.dmg') + }) +}) + +describe('EdgeOne purge submission', () => { + it('submits once with the pinned SDK and reports acceptance without querying completion', async () => { + const output = vi.spyOn(process.stdout, 'write').mockReturnValue(true) + const submit = vi.spyOn(teo.v20220901.Client.prototype, 'CreatePurgeTask') + .mockImplementation(async function (this: InstanceType) { + expect(this.profile.httpProfile).toMatchObject({ reqMethod: 'POST', protocol: 'https://', reqTimeout: 30 }) + return { JobId: 'job-1' } + }) + const query = vi.spyOn(teo.v20220901.Client.prototype, 'DescribePurgeTasks').mockRejectedValue(new Error('must not query')) + + await purgeDesktopInstaller(config) + + expect(submit).toHaveBeenCalledExactlyOnceWith({ ZoneId: config.zoneId, Type: 'purge_url', Targets: [config.publicUrl] }) + expect(query).not.toHaveBeenCalled() + expect(output).toHaveBeenCalledExactlyOnceWith( + `desktop purge: submitted ${config.publicUrl}; task job-1. Cache completion is not checked.\n`, + ) + }) + + it('reports a rejected URL without printing the raw response or claiming acceptance', async () => { + const output = vi.spyOn(process.stdout, 'write').mockReturnValue(true) + const submit = vi.fn().mockResolvedValue({ JobId: 'job-1', FailedList: [{ Targets: [config.publicUrl], Reason: config.secretKey }] }) + await expect(purgeDesktopInstaller(config, { CreatePurgeTask: submit })).rejects.toThrow( + 'desktop purge: EO rejected the URL; inspect EO before submitting again.', + ) + expect(submit).toHaveBeenCalledOnce() + expect(output).not.toHaveBeenCalled() + }) + + it.each(['ECONNRESET', 'UnauthorizedOperation', undefined, config.secretKey])('does not retry or expose SDK errors (%s)', async (code) => { + const submit = vi.fn().mockRejectedValue(Object.assign(new Error(config.secretKey), { code })) + await expect(purgeDesktopInstaller(config, { CreatePurgeTask: submit })).rejects.toThrow( + `desktop purge: submission not confirmed (${code === undefined || code === config.secretKey ? 'request failed' : code}); check EO task history and teo:CreatePurgeTask permission before submitting again.`, + ) + expect(submit).toHaveBeenCalledOnce() + }) + + it.each([undefined, 'unsafe value', config.secretId])('reports an unconfirmed submission without a usable task ID (%s)', async (jobId) => { + const output = vi.spyOn(process.stdout, 'write').mockReturnValue(true) + const submit = vi.fn().mockResolvedValue({ JobId: jobId }) + await expect(purgeDesktopInstaller(config, { CreatePurgeTask: submit })).rejects.toThrow( + 'desktop purge: EO returned no task ID; check EO task history before submitting again.', + ) + expect(submit).toHaveBeenCalledOnce() + expect(output).not.toHaveBeenCalled() + }) +}) diff --git a/apps/desktop/tests/desktop-package-selection.spec.ts b/apps/desktop/tests/desktop-package-selection.spec.ts index fa6a042775..1da8dde6e8 100644 --- a/apps/desktop/tests/desktop-package-selection.spec.ts +++ b/apps/desktop/tests/desktop-package-selection.spec.ts @@ -121,3 +121,17 @@ it('resolves an old locally retained package with publishRequested=false without await expect(resolveRetainedDesktopPublication(env, api)).rejects.toThrow() } finally { await rm(root, { recursive: true, force: true }) } }) + +it('routes both Mac architectures to one machine without authorizing an unlisted target', () => { + const f = fixture() + const routes = { mini: { label: 'dsh-mini', target: ['mac-arm64', 'mac-x64'] } } + for (const path of ['macos-package.yml', 'macos-intel-package.yml']) { + f.run.path = `.github/workflows/${path}` + expect(selectDesktopPackage('owner/repo', { package_run_id: '42' }, routes, f.api)) + .toMatchObject({ runnerName: 'mini', runnerLabel: 'dsh-mini' }) + } + expect(() => selectDesktopPackage('owner/repo', { package_run_id: '42' }, f.routes, f.api)).toThrow(/no configured/u) + for (const target of [[], ['mac-x64', 'linux-x64']]) { + expect(() => selectDesktopPackage('owner/repo', { package_run_id: '42' }, { mini: { label: 'dsh-mini', target } }, f.api)).toThrow() + } +}) diff --git a/apps/desktop/tests/desktop-publish-preflight.spec.ts b/apps/desktop/tests/desktop-publish-preflight.spec.ts index 2af6f288b1..f6c99ae280 100644 --- a/apps/desktop/tests/desktop-publish-preflight.spec.ts +++ b/apps/desktop/tests/desktop-publish-preflight.spec.ts @@ -2,6 +2,7 @@ import { expect, it } from 'vitest' import { preflightDesktopPublish } from '../scripts/preflight-desktop-publish.mjs' it.each([ + ['macos-x64-unnotarized-debug-1.0.0-42-2', '跳过了公证'], ['macos-arm64-unnotarized-debug-1.0.0-42-2', '跳过了公证'], ['windows-x64-unsigned-1.0.0-42-2', '未签名'], ])('rejects %s from paginated artifact metadata with rebuilding instructions', (name, reason) => { diff --git a/apps/desktop/tests/desktop-publish-route.spec.ts b/apps/desktop/tests/desktop-publish-route.spec.ts index 37258e26ed..4e3acc79f3 100644 --- a/apps/desktop/tests/desktop-publish-route.spec.ts +++ b/apps/desktop/tests/desktop-publish-route.spec.ts @@ -75,3 +75,16 @@ it('allows repository branch packages for test but rejects them for production', f.source.preset = 'production' expect(() => resolveDesktopPublishRoute('owner/repo', f.run, { source: f.source }, f.jobs, f.routes)).toThrow(/Production source/u) }) + +it('matches Intel artifacts to the Intel workflow on a machine serving both architectures', () => { + const f = fixture() + f.source.target = 'mac-x64' + const routes = { mini: { label: 'dsh-mini', target: ['mac-arm64', 'mac-x64'] } } + expect(() => resolveDesktopPublishRoute('owner/repo', f.run, { source: f.source }, f.jobs, routes)).toThrow(/does not match/u) + f.run.path = '.github/workflows/macos-intel-package.yml' + expect(resolveDesktopPublishRoute('owner/repo', f.run, { source: f.source }, f.jobs, routes)) + .toMatchObject({ target: 'mac-x64', runnerLabel: 'dsh-mini' }) + expect(() => resolveDesktopPublishRoute('owner/repo', f.run, { source: f.source }, f.jobs, f.routes)).toThrow(/no configured/u) + f.source.target = 'mac-arm64' + expect(() => resolveDesktopPublishRoute('owner/repo', f.run, { source: f.source }, f.jobs, routes)).toThrow(/does not match/u) +}) diff --git a/apps/desktop/tests/desktop-publish-tag.spec.ts b/apps/desktop/tests/desktop-publish-tag.spec.ts index 7a13daba54..06894f7504 100644 --- a/apps/desktop/tests/desktop-publish-tag.spec.ts +++ b/apps/desktop/tests/desktop-publish-tag.spec.ts @@ -3,13 +3,13 @@ import { publishDesktopTag } from '../scripts/desktop-publish-tag.ts' const commit = 'a'.repeat(40) const tag = (sha = commit) => ({ object: { type: 'commit', sha } }) -function transport(replies: Array<{ status: number; body?: object }>) { +function transport(replies: Array<{ status: number; body?: object; rawBody?: string; headers?: Record }>) { const calls: Array<{ url: string; init: RequestInit | undefined }> = [] const request: typeof fetch = async (url, init) => { calls.push({ url: typeof url === 'string' ? url : url instanceof URL ? url.href : url.url, init }) const reply = replies.shift() if (!reply) throw new Error('unexpected HTTP request') - return new Response(JSON.stringify(reply.body ?? {}), { status: reply.status }) + return new Response(reply.rawBody ?? JSON.stringify(reply.body ?? {}), { status: reply.status, headers: reply.headers ?? {} }) } return { calls, request } } @@ -57,3 +57,36 @@ it('explains an existing annotated tag without replacing it', async () => { await expect(publishDesktopTag('owner/repo', '1.2.3', commit, 'fixture-token', http.request)).rejects.toThrow(/not a lightweight commit tag/u) expect(http.calls).toHaveLength(1) }) + +it('keeps the creation status and safe rule diagnostic when no competing tag exists', async () => { + const http = transport([{ status: 404 }, { status: 422, + headers: { 'x-github-request-id': 'ABCD:1234' }, + body: { message: 'Repository rule violations found for refs/tags/desktop-v1.2.3', errors: ['secret-value'] } }, { status: 404 }]) + const failure = publishDesktopTag('owner/repo', '1.2.3', commit, 'fixture-token', http.request) + await expect(failure).rejects.toThrow('creation failed (HTTP 422; GitHub request ABCD:1234); follow-up tag lookup returned HTTP 404; repository rules rejected') + await expect(failure).rejects.not.toThrow('secret-value') + expect(http.calls.map(call => call.init?.method ?? 'GET')).toEqual(['GET', 'POST', 'GET']) +}) + +it('does not echo arbitrary GitHub response text or unrecognized request IDs', async () => { + const http = transport([{ status: 404 }, { status: 422, + headers: { 'x-github-request-id': 'fixture-token' }, body: { message: 'fixture-token' } }, { status: 403 }]) + const failure = publishDesktopTag('owner/repo', '1.2.3', commit, 'fixture-token', http.request) + await expect(failure).rejects.toThrow('creation failed (HTTP 422); follow-up tag lookup returned HTTP 403') + await expect(failure).rejects.not.toThrow('fixture-token') +}) + +it('still rejects a competing tag on a different commit', async () => { + const http = transport([{ status: 404 }, { status: 422 }, { status: 200, body: tag('b'.repeat(40)) }]) + await expect(publishDesktopTag('owner/repo', '1.2.3', commit, 'fixture-token', http.request)).rejects.toThrow('creation failed (HTTP 422)') +}) + +it('retains creation context for a non-JSON rejection', async () => { + const http = transport([{ status: 404 }, { status: 422, rawBody: 'not JSON', headers: { 'x-github-request-id': 'ABCD:1234' } }, { status: 404 }]) + await expect(publishDesktopTag('owner/repo', '1.2.3', commit, 'fixture-token', http.request)).rejects.toThrow('creation failed (HTTP 422; GitHub request ABCD:1234)') +}) + +it('retains creation context when the follow-up request fails', async () => { + const http = transport([{ status: 404 }, { status: 422, headers: { 'x-github-request-id': 'ABCD:1234' } }]) + await expect(publishDesktopTag('owner/repo', '1.2.3', commit, 'fixture-token', http.request)).rejects.toThrow('creation failed (HTTP 422; GitHub request ABCD:1234); follow-up tag lookup failed') +}) diff --git a/apps/desktop/tests/desktop-publish-templates.spec.ts b/apps/desktop/tests/desktop-publish-templates.spec.ts new file mode 100644 index 0000000000..0ead9a11ab --- /dev/null +++ b/apps/desktop/tests/desktop-publish-templates.spec.ts @@ -0,0 +1,35 @@ +import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join, posix, win32 } from 'node:path' +import { fileURLToPath } from 'node:url' +import { expect, it } from 'vitest' +import { readDesktopPublishConfig, type DesktopPublishConfig } from '../scripts/desktop-publish-config.ts' + +for (const platform of ['macos', 'windows'] as const) { + for (const preset of ['test', 'production'] as const) { + it(`accepts the ${platform} ${preset} template after machine paths are supplied`, async () => { + const path = fileURLToPath(new URL(`../config/publishing/${platform}/${preset}.json.example`, import.meta.url)) + const template = JSON.parse(await readFile(path, 'utf8')) as DesktopPublishConfig + const paths = platform === 'windows' ? win32 : posix + expect(paths.isAbsolute(template.credentialsFile)).toBe(true) + expect(template[platform === 'macos' ? 'macOS' : 'windows']).toBeDefined() + expect(Object.hasOwn(template, 'secretId')).toBe(false) + expect(Object.hasOwn(template, 'secretKey')).toBe(false) + if (preset === 'production') expect(paths.isAbsolute(template.githubApp?.privateKeyFile ?? '')).toBe(true) + const root = await mkdtemp(join(tmpdir(), 'publish-template-')) + try { + await mkdir(join(root, 'publishing')) + // The parser uses the current host's path syntax; examples retain their target platform's paths. + const config = { ...template, credentialsFile: join(root, 'absent-credentials.json'), + ...(template.githubApp ? { githubApp: { ...template.githubApp, privateKeyFile: join(root, 'absent-key.pem') } } : {}) } + const output = join(root, 'publishing', `${preset}.json`) + await writeFile(output, JSON.stringify(config)) + await expect(readDesktopPublishConfig(root, preset)).resolves.toEqual(config) + await writeFile(output, JSON.stringify({ ...config, bucket: undefined })) + const failure = readDesktopPublishConfig(root, preset) + await expect(failure).rejects.toHaveProperty('name', 'ZodError') + await expect(failure).rejects.toHaveProperty('issues.0.path', ['bucket']) + } finally { await rm(root, { recursive: true, force: true }) } + }) + } +} diff --git a/apps/desktop/tests/expected/application-menu-en-US.json b/apps/desktop/tests/expected/application-menu-en-US.json index 4e3c981919..71b281c6b2 100644 --- a/apps/desktop/tests/expected/application-menu-en-US.json +++ b/apps/desktop/tests/expected/application-menu-en-US.json @@ -1,10 +1,27 @@ [ + { + "label": "About DeepSeek Harness", + "role": "about" + }, + { + "type": "separator" + }, { "label": "Check for Updates…" }, { "label": "Manage dsh Command…" }, + { + "type": "separator" + }, + { + "role": "toggleDevTools", + "label": "Developer tools" + }, + { + "type": "separator" + }, { "role": "hide", "label": "Hide DeepSeek Harness" @@ -17,6 +34,9 @@ "role": "unhide", "label": "Show All" }, + { + "type": "separator" + }, { "role": "quit", "label": "Quit DeepSeek Harness" diff --git a/apps/desktop/tests/expected/application-menu-zh-CN.json b/apps/desktop/tests/expected/application-menu-zh-CN.json index f39b2d88ae..472aa48a8e 100644 --- a/apps/desktop/tests/expected/application-menu-zh-CN.json +++ b/apps/desktop/tests/expected/application-menu-zh-CN.json @@ -1,10 +1,27 @@ [ + { + "label": "关于 DeepSeek Harness", + "role": "about" + }, + { + "type": "separator" + }, { "label": "检查更新…" }, { "label": "管理 dsh 命令…" }, + { + "type": "separator" + }, + { + "role": "toggleDevTools", + "label": "开发者工具" + }, + { + "type": "separator" + }, { "role": "hide", "label": "隐藏 DeepSeek Harness" @@ -17,6 +34,9 @@ "role": "unhide", "label": "显示全部" }, + { + "type": "separator" + }, { "role": "quit", "label": "退出 DeepSeek Harness" diff --git a/apps/desktop/tests/expected/fatal-address-in-use-en.txt b/apps/desktop/tests/expected/fatal-address-in-use-en.txt index 1e9a9b62d0..fff3b98aec 100644 --- a/apps/desktop/tests/expected/fatal-address-in-use-en.txt +++ b/apps/desktop/tests/expected/fatal-address-in-use-en.txt @@ -1,5 +1,6 @@ DeepSeek Harness is unavailable The application could not start or stopped unexpectedly. Another DSH instance (such as dsh web or the desktop app) is running. They cannot start at the same time. Quit the other running DSH instance, then restart. +The diagnostic report could not be saved. You can provide a screenshot of this dialog when requesting support. Exit Restart diff --git a/apps/desktop/tests/expected/fatal-address-in-use-zh-CN.txt b/apps/desktop/tests/expected/fatal-address-in-use-zh-CN.txt index 30cad3d061..7c6e3dbc61 100644 --- a/apps/desktop/tests/expected/fatal-address-in-use-zh-CN.txt +++ b/apps/desktop/tests/expected/fatal-address-in-use-zh-CN.txt @@ -1,5 +1,6 @@ DeepSeek Harness 无法使用 应用无法启动或已意外停止。 有其他正在运行的 DSH（如其他 dsh web、桌面端），无法同时启动，请退出其他正在运行的 DSH 后重启。 +诊断报告未能保存，反馈问题时可提供此窗口的截图。 退出 重启 diff --git a/apps/desktop/tests/expected/fatal-dialog-en.txt b/apps/desktop/tests/expected/fatal-dialog-en.txt index 0dd0a62eb3..72cc858a1c 100644 --- a/apps/desktop/tests/expected/fatal-dialog-en.txt +++ b/apps/desktop/tests/expected/fatal-dialog-en.txt @@ -2,6 +2,7 @@ DeepSeek Harness is unavailable The application could not start or stopped unexpectedly. Desktop Host failed Plugin initialization failed +The diagnostic report could not be saved. You can provide a screenshot of this dialog when requesting support. If application files are missing or damaged, close the application and reinstall it. Your tasks are stored separately. Exit diff --git a/apps/desktop/tests/expected/fatal-dialog-with-report-en.txt b/apps/desktop/tests/expected/fatal-dialog-with-report-en.txt index aaa637ca1a..89745ea803 100644 --- a/apps/desktop/tests/expected/fatal-dialog-with-report-en.txt +++ b/apps/desktop/tests/expected/fatal-dialog-with-report-en.txt @@ -8,3 +8,4 @@ If application files are missing or damaged, close the application and reinstall Exit Restart Disable third-party plugins, back up profile patch, and restart +Get diagnostic report diff --git a/apps/desktop/tests/expected/fatal-dialog-with-report-zh-CN.txt b/apps/desktop/tests/expected/fatal-dialog-with-report-zh-CN.txt index 353b59f4a4..610b96c509 100644 --- a/apps/desktop/tests/expected/fatal-dialog-with-report-zh-CN.txt +++ b/apps/desktop/tests/expected/fatal-dialog-with-report-zh-CN.txt @@ -8,3 +8,4 @@ Plugin initialization failed 退出 重启 禁用第三方插件、备份 profile patch 并重启 +获取诊断报告 diff --git a/apps/desktop/tests/expected/fatal-dialog-zh-CN.txt b/apps/desktop/tests/expected/fatal-dialog-zh-CN.txt index 6c40644c09..c8db153ae1 100644 --- a/apps/desktop/tests/expected/fatal-dialog-zh-CN.txt +++ b/apps/desktop/tests/expected/fatal-dialog-zh-CN.txt @@ -2,6 +2,7 @@ DeepSeek Harness 无法使用 应用无法启动或已意外停止。 Desktop Host failed Plugin initialization failed +诊断报告未能保存，反馈问题时可提供此窗口的截图。 如果应用文件缺失或损坏，请关闭应用并重新安装。任务数据存储在独立位置。 退出 diff --git a/apps/desktop/tests/expected/operation-history.txt b/apps/desktop/tests/expected/operation-history.txt new file mode 100644 index 0000000000..7ce5170211 --- /dev/null +++ b/apps/desktop/tests/expected/operation-history.txt @@ -0,0 +1,4 @@ + +--- recent plugin operations (context, not proof of cause) --- +{"journal":null,"bytesRead":260,"filesRead":1,"truncated":false,"invalidRecords":0,"unavailableFiles":0,"cancelled":false,"outputRecordsOmitted":0,"records":[{"runId":"c254ab28-97c9-4382-95e6-2db9c66f98c8","operation":{"id":"c254ab28-97c9-4382-95e6-2db9c66f98c9","time":"2026-10-19T00:00:00.000Z","reason":"bundle","target":"test-bundle","stage":"enable","phase":"started"},"transportDropped":0}]} +--- operation history collection complete; consult omission counters above --- diff --git a/apps/desktop/tests/fatal-recovery.spec.ts b/apps/desktop/tests/fatal-recovery.spec.ts index 7ab4efd68a..80f75c2cef 100644 --- a/apps/desktop/tests/fatal-recovery.spec.ts +++ b/apps/desktop/tests/fatal-recovery.spec.ts @@ -17,6 +17,7 @@ function fixture( disablePlugins: vi.fn(async () => {}), exit: vi.fn(), restart: vi.fn(), + revealReport: vi.fn(async (_path: string) => {}), writeReport: vi.fn(writeReport), } return { operations, choice, stopped, recovery: new DesktopFatalRecovery(operations) } @@ -31,14 +32,16 @@ const REPORT_PATH = 'C:\\Users\\someone\\AppData\\Roaming\\DeepSeek Harness\\log afterEach(() => { vi.restoreAllMocks() }) -it.each(['en', 'zh-CN'])('offers only exit and restart for a listener conflict in %s', async (locale) => { +it.each(['en', 'zh-CN'])('offers exit and restart for a listener conflict without a saved report in %s', async (locale) => { const { operations, choice, stopped, recovery } = fixture(locale) const pending = recovery.report(new AggregateError([ new Error('webserver (@deepseek-ai/dsh-host-webserver): Error: listen EADDRINUSE: address already in use 127.0.0.1:19387'), ], 'required startup failure'), 'host') await shown(operations) const options = operations.show.mock.calls[0]![0] - expect(options.buttons).toEqual([operations.messages().exitApplication, operations.messages().restartApplication]) + expect(options.buttons).toEqual([ + operations.messages().exitApplication, operations.messages().restartApplication, + ]) await expect([options.title, options.message, options.detail, ...options.buttons!].join('\n') + '\n') .toMatchFileSnapshot(`expected/fatal-address-in-use-${locale}.txt`) choice.resolve({ response: 1, checkboxChecked: false }) @@ -56,7 +59,7 @@ it.each(['win32', 'darwin', 'linux'] as const)('offers the same listener conflic expect(operations.show.mock.calls[0]![0].buttons).toEqual([ operations.messages().exitApplication, operations.messages().restartApplication, ]) - expect(operations.show.mock.calls[0]![0].detail).toBe(operations.messages().startupAddressInUse) + expect(operations.show.mock.calls[0]![0].detail).toBe(`${operations.messages().startupAddressInUse}\n${operations.messages().reportUnavailable}`) choice.resolve({ response: 0, checkboxChecked: false }) stopped.resolve(undefined) await pending @@ -188,7 +191,7 @@ it('names the report file in the listener-conflict dialog too', async () => { await shown(operations) await vi.waitFor(() => { expect(operations.show).toHaveBeenCalledOnce() }) const options = operations.show.mock.calls[0]![0] - expect(options.buttons).toHaveLength(2) + expect(options.buttons).toHaveLength(3) expect(options.detail).toBe(`${operations.messages().startupAddressInUse}\n${operations.messages().reportWrittenTo.replace('{path}', REPORT_PATH)}`) choice.resolve({ response: 0, checkboxChecked: false }) stopped.resolve(undefined) @@ -202,7 +205,7 @@ it('shows the dialog without a path when the report write fails or returns nothi const pending = recovery.report(new Error('fatal'), 'main') await shown(operations) await vi.waitFor(() => { expect(operations.show).toHaveBeenCalledOnce() }) - expect(operations.show.mock.calls[0]![0].detail).toBe(`fatal\n\n${operations.messages().startupReinstallAdvice}`) + expect(operations.show.mock.calls[0]![0].detail).toBe(`fatal\n${operations.messages().reportUnavailable}\n\n${operations.messages().startupReinstallAdvice}`) choice.resolve({ response: 0, checkboxChecked: false }) stopped.resolve(undefined) await pending @@ -239,3 +242,110 @@ it('writes the report once for the first fatal failure and not for the recovery- expect(operations.writeReport).toHaveBeenCalledOnce() expect(operations.show.mock.calls[1]![0].detail).toContain(REPORT_PATH) }) + +it('reveals the saved report without stopping the Host or restarting', async () => { + const { operations, stopped, recovery } = fixture('en', async () => REPORT_PATH) + operations.show.mockResolvedValueOnce({ response: 3, checkboxChecked: false }) + .mockImplementationOnce(async () => { + expect(operations.revealReport).toHaveBeenCalledWith(REPORT_PATH) + expect(operations.stop).not.toHaveBeenCalled() + expect(operations.restart).not.toHaveBeenCalled() + return { response: 0, checkboxChecked: false } + }) + stopped.resolve(undefined) + await recovery.report(new Error('fatal'), 'host') + expect(operations.writeReport).toHaveBeenCalledOnce() + expect(operations.show.mock.calls[1]![0].message).toBe(operations.messages().reportShareHint) +}) + +it('keeps the original failure and report path when revealing the file fails', async () => { + vi.spyOn(console, 'error').mockImplementation(() => {}) + const { operations, stopped, recovery } = fixture('en', async () => REPORT_PATH) + operations.revealReport.mockRejectedValueOnce(new Error('file removed')) + operations.show.mockResolvedValueOnce({ response: 3, checkboxChecked: false }) + .mockResolvedValueOnce({ response: 0, checkboxChecked: false }) + stopped.resolve(undefined) + await recovery.report(new Error('original startup failure'), 'host') + expect(operations.show.mock.calls[1]![0]).toMatchObject({ message: operations.messages().reportRevealFailed }) + expect(operations.show.mock.calls[1]![0].detail).toContain('original startup failure') + expect(operations.show.mock.calls[1]![0].detail).toContain(REPORT_PATH) +}) + +it('makes a report that finishes after the initial deadline available without rewriting it', async () => { + vi.useFakeTimers() + try { + const write = Promise.withResolvers() + const { operations, choice, stopped, recovery } = fixture('en', () => write.promise) + const pending = recovery.report(new Error('fatal'), 'host') + await vi.advanceTimersByTimeAsync(CRASH_REPORT_WAIT_MS) + expect(operations.show.mock.calls[0]![0].detail).toContain(operations.messages().reportPending) + operations.show.mockResolvedValueOnce({ response: 0, checkboxChecked: false }) + write.resolve(REPORT_PATH) + choice.resolve({ response: 3, checkboxChecked: false }) + stopped.resolve(undefined) + await pending + expect(operations.revealReport).toHaveBeenCalledWith(REPORT_PATH) + expect(operations.writeReport).toHaveBeenCalledOnce() + } finally { + vi.useRealTimers() + } +}) + +it('does not attempt to reveal an unavailable report', async () => { + const { operations, stopped, recovery } = fixture() + operations.show.mockResolvedValueOnce({ response: 0, checkboxChecked: false }) + stopped.resolve(undefined) + await recovery.report(new Error('fatal'), 'host') + expect(operations.revealReport).not.toHaveBeenCalled() + expect(operations.show.mock.calls[0]![0].buttons).not.toContain(operations.messages().getDiagnosticReport) + expect(operations.show.mock.calls[0]![0].detail).toContain(operations.messages().reportUnavailable) +}) + +it.each(['pending', 'failed'] as const)('keeps the recovery failure visible when fetching a %s report', async (state) => { + vi.useFakeTimers() + vi.spyOn(console, 'error').mockImplementation(() => {}) + const write = Promise.withResolvers() + try { + const { operations, stopped, recovery } = fixture('en', () => write.promise) + stopped.resolve(undefined) + operations.disablePlugins.mockRejectedValueOnce(new Error('profile is read-only')) + operations.show.mockResolvedValueOnce({ response: 2, checkboxChecked: false }) + .mockImplementationOnce(async () => { + if (state === 'failed') write.resolve(undefined) + return { response: 3, checkboxChecked: false } + }) + .mockResolvedValueOnce({ response: 0, checkboxChecked: false }) + const pending = recovery.report(new Error('original startup failure'), 'host') + await vi.runAllTimersAsync() + await pending + expect(operations.show).toHaveBeenCalledTimes(3) + const last = operations.show.mock.calls[2]![0] + expect(last.message).toBe(operations.messages().recoveryOperationFailed) + expect(last.detail).toContain('profile is read-only') + if (state === 'failed') expect(last.buttons).not.toContain(operations.messages().getDiagnosticReport) + expect(last.detail).toContain(state === 'pending' ? operations.messages().reportPending : operations.messages().reportUnavailable) + expect(operations.revealReport).not.toHaveBeenCalled() + expect(operations.writeReport).toHaveBeenCalledOnce() + } finally { + write.resolve(undefined) + vi.useRealTimers() + } +}) + +it.each([false, true])('keeps the original attachment when revealing after a recovery failure (reveal fails=%s)', async (revealFails) => { + vi.spyOn(console, 'error').mockImplementation(() => {}) + const { operations, stopped, recovery } = fixture('en', async () => REPORT_PATH) + const original = new Error('original startup failure') + stopped.resolve(undefined) + operations.disablePlugins.mockRejectedValueOnce(new Error('profile is read-only')) + if (revealFails) operations.revealReport.mockRejectedValueOnce(new Error('file manager unavailable')) + operations.show.mockResolvedValueOnce({ response: 2, checkboxChecked: false }) + .mockResolvedValueOnce({ response: 3, checkboxChecked: false }) + .mockResolvedValueOnce({ response: 0, checkboxChecked: false }) + await recovery.report(original, 'host') + const last = operations.show.mock.calls[2]![0] + expect(last.message).toBe(revealFails ? operations.messages().reportRevealFailed : operations.messages().reportShareHint) + expect(last.detail).toContain('profile is read-only') + expect(operations.writeReport).toHaveBeenCalledExactlyOnceWith(original, 'host') + expect(operations.revealReport).toHaveBeenCalledExactlyOnceWith(REPORT_PATH) +}) diff --git a/apps/desktop/tests/file-actions.spec.ts b/apps/desktop/tests/file-actions.spec.ts new file mode 100644 index 0000000000..972f64e7ee --- /dev/null +++ b/apps/desktop/tests/file-actions.spec.ts @@ -0,0 +1,213 @@ +/** Native original-byte saves and window-scoped IPC ownership. */ +import { EventEmitter } from 'node:events' +import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import type { IpcMainInvokeEvent } from 'electron' +import { afterEach, expect, it, vi } from 'vitest' +import { installFileActions } from '../src/file-actions.ts' +import { DESKTOP_IPC } from '../src/ipc.ts' + +const electron = vi.hoisted(() => ({ + app: { getPath: vi.fn() }, ipcMain: { handle: vi.fn() }, session: { defaultSession: { on: vi.fn() } }, +})) +vi.mock('electron', () => electron) +const roots: string[] = [] +const owners: EventEmitter[] = [] +afterEach(async () => { + for (const owner of owners.splice(0)) owner.emit('closed') + vi.useRealTimers(); vi.unstubAllEnvs() + await Promise.all(roots.splice(0).map(path => rm(path, { recursive: true, force: true }))); vi.clearAllMocks(); vi.unstubAllGlobals() +}) +async function directory() { const path = await mkdtemp(join(tmpdir(), 'dsh-file-actions-')); roots.push(path); return path } + +function harness(root: string) { + const owner = Object.assign(new EventEmitter(), { + webContents: Object.assign(new EventEmitter(), { downloadURL: vi.fn<(url: string) => void>() }), isDestroyed: () => false, + }) + owners.push(owner) + const assertOwner = vi.fn(() => owner as never) + electron.app.getPath.mockReturnValue(root) + installFileActions(assertOwner) + const event = {} as IpcMainInvokeEvent + const invoke = async (channel: string, value: unknown): Promise => { + const handler = electron.ipcMain.handle.mock.calls.find(([name]) => name === channel)?.[1] as + (event: IpcMainInvokeEvent, value: unknown) => Promise + return handler(event, value) + } + const item = (mime = 'image/gif', url = owner.webContents.downloadURL.mock.lastCall![0]) => { + let destination = '' + const download = Object.assign(new EventEmitter(), { + getURLChain: () => [url], + getFilename: () => 'original.gif', getMimeType: () => mime, getSavePath: () => destination, + setSavePath: vi.fn((path: string) => { destination = path }), + setSaveDialogOptions: vi.fn(), cancel: vi.fn(), + }) + const willDownload = electron.session.defaultSession.on.mock.calls[0]![1] as + (event: object, item: object, contents: object) => void + willDownload({}, download, owner.webContents) + return download + } + const save = async (mode: 'download' | 'saveAs' = 'download') => { + const pending = invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/original.gif', name: 'image.gif', mode }) + const download = item() + if (mode === 'download') await writeFile(download.getSavePath(), new Uint8Array([0, 128, 255])) + download.emit('done', {}, 'completed') + return pending + } + return { owner, assertOwner, invoke, item, save } +} + +it('returns the completed destination and releases download listeners', async () => { + const root = await directory(), f = harness(root) + await expect(f.save()).resolves.toEqual({ status: 'saved', path: join(root, 'image.gif') }) + expect(f.owner.listenerCount('closed')).toBe(0) + expect(f.owner.webContents.listenerCount('did-start-navigation')).toBe(0) +}) + +it.each(['file:///private/data', 'dsh-app://app/api/private', 'javascript:alert(1)'])('rejects unsupported URL %s', async (url) => { + const root = await directory(), f = harness(root) + await expect(f.invoke(DESKTOP_IPC.fileSave, { url, mode: 'download' })).rejects.toThrow('Unsupported') + expect(await readdir(root)).toEqual([]) +}) + +it('retains original downloads and reserves distinct paths until Chromium finishes', async () => { + const root = await directory(), f = harness(root) + await writeFile(join(root, 'image.gif'), 'previous') + await f.save() + expect(await readFile(join(root, 'image.gif'), 'utf8')).toBe('previous') + expect(await readFile(join(root, 'image (1).gif'))).toEqual(Buffer.from([0, 128, 255])) +}) + +it.each(['cancelled', 'interrupted'] as const)('reports native %s without a completed path', async (state) => { + const root = await directory(), f = harness(root) + const pending = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', name: 'wrong.png', mode: 'download' }) + const download = f.item('image/webp') + expect(download.setSavePath).toHaveBeenCalledWith(join(root, 'wrong.webp')) + download.emit('done', {}, state) + if (state === 'cancelled') await expect(pending).resolves.toEqual({ status: 'cancelled' }) + else await expect(pending).rejects.toThrow('interrupted') + expect(await readdir(root)).toEqual([]) +}) + +it('uses the native save dialog and waits for completion before reporting success', async () => { + const root = await directory(), f = harness(root) + const pending = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', name: 'photo.png', mode: 'saveAs' }) + const download = f.item('image/jpeg') + expect(download.setSavePath).not.toHaveBeenCalled() + expect(download.setSaveDialogOptions).toHaveBeenCalledWith({ defaultPath: join(root, 'photo.jpg'), properties: ['showOverwriteConfirmation', 'createDirectory'] }) + download.emit('done', {}, 'cancelled') + await expect(pending).resolves.toEqual({ status: 'cancelled' }) + f.assertOwner.mockImplementation(() => { throw new Error('Rejected owner') }) + await expect(f.invoke(DESKTOP_IPC.fileSave, {})).rejects.toThrow('Rejected owner') +}) + +it('cancels pending downloads when the owning document changes', async () => { + const f = harness(await directory()) + const pending = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', mode: 'download' }) + const download = f.item() + f.owner.webContents.emit('did-start-navigation', {}, 'dsh-app://app/', false, true) + await expect(pending).resolves.toEqual({ status: 'cancelled' }) + expect(download.cancel).toHaveBeenCalledOnce() + download.emit('done', {}, 'cancelled') + expect(f.owner.listenerCount('closed')).toBe(0) +}) + +it('matches overlapping downloads of the same source to their captured requests', async () => { + const root = await directory(), f = harness(root) + const first = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', name: 'first.gif', mode: 'download' }) + const firstUrl = f.owner.webContents.downloadURL.mock.lastCall![0] + const second = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', name: 'second.gif', mode: 'saveAs' }) + const secondItem = f.item() + const firstItem = f.item('image/gif', firstUrl) + expect(firstItem.setSavePath).toHaveBeenCalledWith(join(root, 'first.gif')) + expect(secondItem.setSaveDialogOptions.mock.lastCall?.[0]).toMatchObject({ defaultPath: join(root, 'second.gif') }) + secondItem.emit('done', {}, 'cancelled') + firstItem.emit('done', {}, 'completed') + await expect(first).resolves.toMatchObject({ status: 'saved' }) + await expect(second).resolves.toEqual({ status: 'cancelled' }) +}) + +it('retires timed-out downloads and cancels items arriving after their window closes', async () => { + vi.useFakeTimers(); vi.stubEnv('DSH_DESKTOP_FILE_DOWNLOAD_TIMEOUT_MS', '1000') + const root = await directory(), f = harness(root) + const pending = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', mode: 'download' }) + const rejected = expect(pending).rejects.toThrow('timed out') + await vi.advanceTimersByTimeAsync(1000) + await rejected + const download = f.item() + expect(download.cancel).toHaveBeenCalledOnce() + download.emit('done', {}, 'cancelled') + expect(await readdir(root)).toEqual([]) + expect(f.owner.listenerCount('closed')).toBe(0) + expect(f.owner.webContents.listenerCount('did-start-navigation')).toBe(0) + + const late = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', mode: 'download' }) + f.owner.emit('closed') + await expect(late).resolves.toEqual({ status: 'cancelled' }) + const stale = f.item() + expect(stale.cancel).toHaveBeenCalledOnce() + expect(stale.setSavePath).not.toHaveBeenCalled() +}) + +it('allows the native save dialog to remain open beyond the download startup deadline', async () => { + vi.useFakeTimers(); vi.stubEnv('DSH_DESKTOP_FILE_DOWNLOAD_TIMEOUT_MS', '1000') + const f = harness(await directory()) + const pending = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', mode: 'saveAs' }) + const download = f.item() + await vi.advanceTimersByTimeAsync(2000) + expect(download.cancel).not.toHaveBeenCalled() + download.emit('done', {}, 'completed') + await expect(pending).resolves.toMatchObject({ status: 'saved' }) +}) + +it('reports a synchronous Chromium launch failure and releases pending listeners', async () => { + const f = harness(await directory()) + f.owner.webContents.downloadURL.mockImplementation(() => { throw new Error('Download unavailable') }) + await expect(f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', mode: 'download' })).rejects.toThrow('Download unavailable') + expect(f.owner.listenerCount('closed')).toBe(0) + expect(f.owner.webContents.listenerCount('did-start-navigation')).toBe(0) +}) + +it('aborts original-image reads on window navigation and releases lifecycle listeners', async () => { + const f = harness(await directory()) + let signal!: AbortSignal + vi.stubGlobal('fetch', vi.fn((_url: URL, options: RequestInit) => new Promise((_resolve, reject) => { + signal = options.signal! + signal.addEventListener('abort', () => { reject(new DOMException('Aborted', 'AbortError')) }, { once: true }) + }))) + const reading = f.invoke(DESKTOP_IPC.clipboardImageRead, 'https://images.example/original.gif') + f.owner.webContents.emit('did-start-navigation', {}, 'dsh-app://app/', false, true) + await expect(reading).rejects.toThrow('Aborted') + expect(signal.aborted).toBe(true) + expect(f.owner.listenerCount('closed')).toBe(0) + expect(f.owner.webContents.listenerCount('did-start-navigation')).toBe(0) +}) + +it('preserves pending downloads across iframe and same-document navigation', async () => { + const root = await directory(), f = harness(root) + const pending = f.invoke(DESKTOP_IPC.fileSave, { url: 'https://images.example/a', mode: 'saveAs' }) + const download = f.item() + f.owner.webContents.emit('did-start-navigation', {}, 'https://example.org', false, false) + f.owner.webContents.emit('did-start-navigation', {}, 'dsh-app://app/#tab', true, true) + download.setSavePath(join(root, 'chosen.gif')) + download.emit('done', {}, 'completed') + await expect(pending).resolves.toEqual({ status: 'saved', path: join(root, 'chosen.gif') }) + expect(download.cancel).not.toHaveBeenCalled() +}) + +it('rejects redirects to the application Host', async () => { + const root = await directory() + const owner = Object.assign(new EventEmitter(), { + webContents: Object.assign(new EventEmitter(), { downloadURL: vi.fn<(url: string) => void>() }), isDestroyed: () => false, + }) + installFileActions(() => owner as never, () => 'http://127.0.0.1:19321') + const handler = (name: string) => electron.ipcMain.handle.mock.calls.find(([channel]) => channel === name)![1] as + (event: IpcMainInvokeEvent, value: unknown) => Promise + const fetchImage = vi.fn(async () => new Response(null, { status: 302, headers: { location: 'http://localhost:19321/api/private' } })) + vi.stubGlobal('fetch', fetchImage) + const event = {} as IpcMainInvokeEvent + await expect(handler(DESKTOP_IPC.clipboardImageRead)(event, 'https://images.example/photo')).rejects.toThrow('Invalid image URL') + expect(fetchImage).toHaveBeenCalledOnce() + expect(await readdir(root)).toEqual([]) +}) diff --git a/apps/desktop/tests/host-process.spec.ts b/apps/desktop/tests/host-process.spec.ts index 93b5f9bce2..9a72fd2925 100644 --- a/apps/desktop/tests/host-process.spec.ts +++ b/apps/desktop/tests/host-process.spec.ts @@ -1,8 +1,11 @@ import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { afterEach, describe, expect, it, vi } from 'vitest' +import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest' import { DesktopHostFatalError, DesktopHostProcess, DesktopHostUncleanExitError, QUIT_INSPECTION_DEADLINE_MS } from '../src/host-process.ts' +import { OperationJournal } from '../src/operation-journal.ts' +import { readOperationHistory } from '../src/operation-history.ts' +import { renderCrashReport } from '../src/crash-report.ts' const roots: string[] = [] const hosts: DesktopHostProcess[] = [] @@ -88,6 +91,85 @@ afterEach(async () => { }) describe('desktop host process', () => { + it('retains the announced run identity when startup fails before readiness', async () => { + const runtime = projectWithHost(` +process.send({ type: 'starting', runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8' }) +process.send({ type: 'fatal', message: 'profile startup failed', diagnostic: 'required plugin failed' }, () => process.disconnect()) +`) + const host = hostProcess(runtime) + const failure: unknown = await host.start().catch((error: unknown) => error) + await host.stop() + expect(failure).toBeInstanceOf(DesktopHostFatalError) + expect(failure).toHaveProperty('hostRunId', 'c254ab28-97c9-4382-95e6-2db9c66f98c8') + }) + + it.each([ + ['exception', 'queueMicrotask(() => { throw new Error("qualification-exception", { cause: new Error("qualification-runtime-cause") }) })'], + ['rejection', 'Promise.reject(new Error("qualification-rejection"))'], + ['exit', 'process.stderr.write("qualification-exit", () => process.exit(7))'], + ])('retains real child %s evidence in the final report after readiness', async (kind, trigger) => { + const failed = Promise.withResolvers() + const runtime = projectWithHost(` +process.send({ type: 'starting', runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8' }) +process.send({ type: 'ready', url: 'http://127.0.0.1:3080/' }, () => { ${trigger} }) +`) + const host = hostProcess(runtime, runtime, failed.resolve) + await host.start() + const failure = await failed.promise + await host.stop() + const report = renderCrashReport({ source: 'host', phase: 'running', error: failure, + rendererConsole: [], operationHistoryPlanned: true, time: new Date('2026-10-19T00:00:00Z'), + app: { name: 'qualification', version: 'test', platform: process.platform, arch: process.arch, + electron: 'not-running', node: process.version, locale: 'zh-CN' }, + }) + expect(report).toContain(`qualification-${kind}`) + expect(report).toContain('phase: running') + expect(report).toContain("hostRunId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8'") + if (kind === 'exception') expect(report).toContain('qualification-runtime-cause') + if (kind === 'exit') expect(report).toContain('7') + }) + + it('persists validated operation IPC across Host lifetimes and isolates a failing diagnostic sink', async () => { + const record = { + runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-19T00:00:00.000Z', + reason: 'bundle', phase: 'started', target: 'test-bundle', stage: 'enable' }, + secret: 'not-persisted', + } + const runtime = projectWithHost(` +process.send({ type: 'starting', runId: ${JSON.stringify(record.runId)} }) +process.send({ type: 'plugin-operation', record: { invalid: true } }) +process.send({ type: 'plugin-operation', record: { ...${JSON.stringify(record)}, runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c0' } }) +process.send({ type: 'plugin-operation', record: ${JSON.stringify(record)} }) +${HTTP_HOST}`) + const directory = join(runtime, 'operation-history') + const journal = new OperationJournal(directory, { recordBytes: 4096, segmentBytes: 8192, queuedBytes: 8192 }) + onTestFinished(async () => { await journal.close() }) + const sink = vi.fn(value => journal.enqueue(JSON.stringify(value))) + const first = new DesktopHostProcess(process.execPath, runtime, runtime, undefined, process.env, + undefined, undefined, undefined, undefined, sink) + hosts.push(first) + await first.start() + await first.stop() + await journal.close() + expect(sink).toHaveBeenCalledTimes(1) + const saved = await readOperationHistory(directory, { bytes: 8192, recordBytes: 4096, records: 10 }, new AbortController().signal) + expect(saved.records).toEqual([{ runId: record.runId, transportDropped: 0, operation: record.operation }]) + + const warning = vi.spyOn(console, 'error').mockImplementation(() => {}) + try { + const failure = vi.fn() + const second = new DesktopHostProcess(process.execPath, runtime, runtime, undefined, process.env, + failure, undefined, undefined, undefined, () => { throw new Error('sink unavailable') }) + hosts.push(second) + await second.start() + expect(await second.updateTasks('inspect')).toBe(false) + await second.stop() + expect(failure).not.toHaveBeenCalled() + expect(warning).toHaveBeenCalledWith('desktop plugin operation diagnostic sink failed') + } finally { warning.mockRestore() } + }) + it('correlates authorized file resources and rejects Host denial over private IPC', async () => { const host = hostProcess(projectWithHost()) await host.start() diff --git a/apps/desktop/tests/locale-cache.spec.ts b/apps/desktop/tests/locale-cache.spec.ts new file mode 100644 index 0000000000..fdfeb4d557 --- /dev/null +++ b/apps/desktop/tests/locale-cache.spec.ts @@ -0,0 +1,62 @@ +import { SHIPPED_LOCALE_IDS } from '../../../scripts/shipped-locales.ts' +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it, onTestFinished, vi } from 'vitest' +import { readDesktopLocaleCache, writeDesktopLocaleCache } from '../src/locale-cache.ts' +import { resolveDesktopLocale, resolveDesktopStartupLocale } from '../src/locale.ts' + +function fixture() { + const directory = mkdtempSync(join(tmpdir(), 'desktop-locale-')) + onTestFinished(() => { rmSync(directory, { recursive: true, force: true }) }) + return directory +} + +it('uses the confirmed Chinese language for recovery before Host settings are available', () => { + const directory = fixture() + expect(readDesktopLocaleCache(directory)).toBeUndefined() + writeDesktopLocaleCache(directory, 'zh-CN') + const cached = readDesktopLocaleCache(directory) + const locale = cached === undefined ? resolveDesktopStartupLocale(null, ['en-US']) : resolveDesktopLocale(cached) + expect(locale.messages.fatalSummary).toBe('应用无法启动或已意外停止。') + writeDesktopLocaleCache(directory, 'en') + expect(readDesktopLocaleCache(directory)).toBe('en') +}) + +it('uses the confirmed Japanese language for recovery before Host settings are available', () => { + const directory = fixture() + writeDesktopLocaleCache(directory, 'ja') + const cached = readDesktopLocaleCache(directory) + const locale = cached === undefined ? resolveDesktopStartupLocale(null, ['en-US']) : resolveDesktopLocale(cached) + expect(locale.id).toBe('ja') + expect(locale.messages.getDiagnosticReport).toBe('診断レポートを取得') +}) + +it.each(SHIPPED_LOCALE_IDS)('restores the confirmed shipped language %s before Host settings are available', (id) => { + const directory = fixture() + const selected = resolveDesktopLocale(id) + writeDesktopLocaleCache(directory, selected.id) + const cached = readDesktopLocaleCache(directory) + expect(cached).toBe(selected.id) + expect(resolveDesktopLocale(cached!).messages.getDiagnosticReport).toBe(selected.messages.getDiagnosticReport) +}) + +it.each(['', 'it', '{invalid'])('falls back to system language for an invalid cache: %s', (value) => { + const directory = fixture() + writeDesktopLocaleCache(directory, 'en') + writeFileSync(join(directory, 'desktop', 'locale-cache'), value) + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + onTestFinished(() => { warn.mockRestore() }) + expect(readDesktopLocaleCache(directory)).toBeUndefined() + expect(warn).toHaveBeenCalled() +}) + +it('keeps read and write failures from blocking recovery', () => { + const directory = fixture() + writeFileSync(join(directory, 'desktop'), 'not a directory') + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + onTestFinished(() => { warn.mockRestore() }) + expect(() => { writeDesktopLocaleCache(directory, 'zh-CN') }).not.toThrow() + expect(readDesktopLocaleCache(directory)).toBeUndefined() + expect(warn).toHaveBeenCalled() +}) diff --git a/apps/desktop/tests/macos-package-preset.spec.ts b/apps/desktop/tests/macos-package-preset.spec.ts index a4ab457ec0..a864b9b9bb 100644 --- a/apps/desktop/tests/macos-package-preset.spec.ts +++ b/apps/desktop/tests/macos-package-preset.spec.ts @@ -60,7 +60,7 @@ it.skipIf(process.platform !== 'darwin')('prepares private machine directories w } }) -it('records debugging artifact paths only for an explicit CI selection without notarization credentials', async () => { +it.each(['arm64', 'x64'])('records %s debugging artifact paths only for an explicit CI selection without notarization credentials', async (arch) => { const root = await mkdtemp(join(tmpdir(), 'macos-ci-settings-')) try { await mkdir(join(root, 'presets')) @@ -81,6 +81,7 @@ it('records debugging artifact paths only for an explicit CI selection without n const run = (skip: string) => spawnSync(process.execPath, [join(import.meta.dirname, '../scripts/prepare-macos-ci.mjs')], { encoding: 'utf8', env: { ...process.env, DSH_PACKAGING_CONFIG_DIR: root, DSH_PACKAGING_PRESET: 'test', + DSH_DESKTOP_TARGET_PLATFORM: 'darwin', DSH_DESKTOP_TARGET_ARCH: arch, PACKAGE_SKIP_NOTARIZATION: skip, PACKAGE_BUILD_VERSION: 'auto', GITHUB_RUN_NUMBER: '1', GITHUB_RUN_ATTEMPT: '1', GITHUB_OUTPUT: output, GITHUB_STEP_SUMMARY: summary, } }) @@ -91,10 +92,13 @@ it('records debugging artifact paths only for an explicit CI selection without n expect(invalidSelection.status).toBe(1) expect(invalidSelection.stderr).toContain('Invalid skip notarization selection') const debugging = run('true') + expect(debugging.error).toBeUndefined() + expect(debugging.signal).toBeNull() expect(debugging.stderr).toBe('') expect(debugging.status).toBe(0) expect(await readFile(output, 'utf8')).toContain('artifacts=unnotarized-artifacts\nmode=unnotarized-debug\n') expect(await readFile(summary, 'utf8')).toContain('Internal debugging only') + expect(await readFile(summary, 'utf8')).toContain(`macOS ${arch} signed installer`) } finally { await rm(root, { recursive: true, force: true }) } diff --git a/apps/desktop/tests/main-startup.spec.ts b/apps/desktop/tests/main-startup.spec.ts index b2d925af6c..3b1e63e00c 100644 --- a/apps/desktop/tests/main-startup.spec.ts +++ b/apps/desktop/tests/main-startup.spec.ts @@ -1,9 +1,11 @@ +import { parsePluginOperationRecord } from '@deepseek-ai/dsh-plugin-manager/diagnostic' +import type { DesktopHostProcess } from '../src/host-process.ts' import type { AccountView } from '@deepseek-ai/dsh-deepseek-account/types' import { WINDOWS_TITLEBAR_HEIGHT } from '../src/windows-layout.ts' import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from 'vitest' import type { IpcMainInvokeEvent } from 'electron' import { join } from 'node:path' -import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs' +import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import type { MenuItemConstructorOptions, MessageBoxOptions } from 'electron' import { DESKTOP_IPC, type DesktopUpdateState } from '../src/ipc.ts' @@ -12,6 +14,7 @@ import { DesktopHostFatalError, DesktopHostUncleanExitError } from '../src/host- import { en, zh } from '../src/locale.ts' import { DesktopUpdatePreparationError } from '../src/update-error.ts' import { writeCrashReport } from '../src/crash-report.ts' +import { runOperationReportJob } from '../src/operation-report-job.ts' type InvokeEvent = { sender?: unknown; senderFrame: { url: string } } type InvokeHandler = (event: InvokeEvent, ...args: unknown[]) => unknown @@ -20,11 +23,12 @@ const fileDrag = vi.hoisted(() => ({ dispose: vi.fn<() => Promise>(), inst vi.mock('../src/file-drag.ts', () => ({ installDesktopFileDrag: () => { fileDrag.install(); return fileDrag.dispose } })) vi.mock('../src/web-document.ts', () => ({ authenticateWebHost: async () => 'test-cookie', serveWebDocument: vi.fn(), forwardWebRequest: vi.fn() })) +vi.mock('../src/operation-report-job.ts', () => ({ runOperationReportJob: vi.fn(async () => ({ appended: false, timedOut: false, cancelled: false })) })) // Report persistence has its own unit tests; here it resolves within microtasks so the fatal // dialog never outlives the test that triggered it. vi.mock('../src/crash-report.ts', async importOriginal => ({ ...await importOriginal(), - writeCrashReport: vi.fn(async () => 'desktop-test-logs/crash-test.log'), + writeCrashReport: vi.fn<(...args: unknown[]) => Promise>(), pruneCrashReports: vi.fn(async () => {}), })) @@ -164,6 +168,8 @@ const harness = await vi.hoisted(async () => { readonly inspectPort?: number, readonly environment?: NodeJS.ProcessEnv, readonly onFailure?: (error: Error) => void, readonly primaryRuntime?: string, readonly packageManager?: { pnpm: string; nodeBin: string }, + readonly onPlatformSession?: ConstructorParameters[8], + readonly onPluginOperation?: ConstructorParameters[9], ) { hosts.push(this) } } const app = Object.assign(new EventEmitter(), { @@ -311,6 +317,7 @@ vi.mock('electron', () => ({ }, Menu: { setApplicationMenu: harness.menu.setApplicationMenu, buildFromTemplate: harness.menu }, session: { defaultSession: { + on: vi.fn(), setPermissionCheckHandler: vi.fn(), setPermissionRequestHandler: vi.fn(), webRequest: { onBeforeSendHeaders: harness.socketHeaders }, } }, protocol: { registerSchemesAsPrivileged: vi.fn(), handle: harness.protocolHandle }, @@ -427,9 +434,10 @@ beforeEach(() => { harness.reset() const userData = mkdtempSync(join(tmpdir(), 'dsh-main-user-data-')) onTestFinished(() => { rmSync(userData, { recursive: true, force: true }) }) - harness.app.getPath.mockImplementation(name => name === 'userData' ? userData : `desktop-test-${name}`) + harness.app.getPath.mockImplementation(name => name === 'userData' ? userData : join(userData, `desktop-test-${name}`)) + vi.mocked(writeCrashReport).mockResolvedValue(join(harness.app.getPath('logs'), 'crash-test.log')) harness.dialog.showMessageBox.mockImplementation((options: { title?: string }) => { - if (options.title !== en.startupFailed) return Promise.resolve({ response: 1 }) + if (options.title !== en.startupFailed && options.title !== zh.startupFailed) return Promise.resolve({ response: 1 }) harness.dialogShown.resolve() return new Promise(() => {}) }) @@ -542,12 +550,49 @@ describe('desktop main startup', () => { expect((await handler(new Request('dsh-app://unknown/update-dialog.html'))).status).toBe(404) }) - it('installs hidden native DevTools shortcuts in the macOS application menu', async () => { - vi.stubGlobal('process', { ...process, platform: 'darwin' }) + it.each(([ + ['darwin', 'en'], ['darwin', 'zh-CN'], ['win32', 'en'], ['win32', 'zh-CN'], ['linux', 'en'], ['linux', 'zh-CN'], + ] as const).flatMap(([platform, locale]) => [ + [platform, locale, true] as const, [platform, locale, false] as const, + ]))('groups localized DevTools before quit on %s (%s, packaged=%s)', async (platform, locale, packaged) => { + vi.stubGlobal('process', { ...process, platform }) + harness.app.isPackaged = packaged + vi.spyOn(harness.app, 'getPreferredSystemLanguages').mockReturnValue([locale]) await readyForUpdate() - expect(applicationMenuItems().slice(-2)).toEqual([ - { role: 'toggleDevTools', visible: false }, - { role: 'toggleDevTools', visible: false, accelerator: 'F12' }, + const messages = locale === 'en' ? en : zh + const menu = applicationMenuItems() + const visible = menu.filter(item => item.visible !== false) + expect(visible.map(item => item.role === 'quit' ? 'quit' : item.label ?? item.type)).toEqual([ + messages.aboutMenu, 'separator', messages.checkUpdatesMenu, + ...platform === 'linux' ? [] : [messages.cliCommandMenu], + 'separator', ...packaged ? [] : [messages.reloadPageMenu, messages.restartAppHostMenu], + messages.toggleDevToolsMenu, 'separator', + ...platform === 'darwin' ? [messages.hideApplication, messages.hideOtherApplications, messages.showAllApplications, 'separator'] : [], + 'quit', + ]) + expect(visible.filter(item => item.role === 'toggleDevTools')).toEqual([ + { role: 'toggleDevTools', label: messages.toggleDevToolsMenu }, + ]) + if (platform === 'win32') { + expect(harness.menu.mock.calls[0]![0]).toEqual([ + { role: 'toggleDevTools', visible: false }, + { role: 'toggleDevTools', visible: false, accelerator: 'F12' }, + ]) + expect(menu.every(item => item.visible !== false)).toBe(true) + } else { + expect(menu.filter(item => item.visible === false)).toEqual([ + { role: 'toggleDevTools', visible: false, accelerator: 'F12' }, + ]) + } + const sender = harness.windows[0]!.webContents + const nextLocale = locale === 'en' ? 'zh' : 'en' + harness.ipcOn.mock.calls.find(([channel]) => channel === DESKTOP_IPC.localeChanged)![1]( + { sender, senderFrame: sender.mainFrame }, nextLocale, + ) + const refreshed = platform === 'win32' ? applicationMenuItems() + : harness.menu.mock.lastCall![0][0]!.submenu as MenuItemConstructorOptions[] + expect(refreshed.filter(item => item.role === 'toggleDevTools' && item.visible !== false)).toEqual([ + { role: 'toggleDevTools', label: nextLocale === 'en' ? en.toggleDevToolsMenu : zh.toggleDevToolsMenu }, ]) expect(harness.windows[0]!.options).toMatchObject({ webPreferences: { devTools: true } }) }) @@ -954,7 +999,7 @@ describe('desktop main startup', () => { expect(window.setBackgroundColor).not.toHaveBeenCalled() }) - it('follows the Windows primary document language and palette without trusting other frames', async () => { + it('follows confirmed language and primary document palette without trusting other frames', async () => { vi.spyOn(process, 'platform', 'get').mockReturnValue('win32') await import('../src/main.ts') await harness.preparing.promise @@ -963,10 +1008,12 @@ describe('desktop main startup', () => { const event = { sender: window.webContents, senderFrame: window.webContents.mainFrame } listener({ ...event, senderFrame: { url: 'dsh-app://app/' } }, 'zh-CN', '#ffffff', '#000000') expect(window.setTitleBarOverlay).not.toHaveBeenCalled() + harness.ipcOn.mock.calls.find(([channel]) => channel === DESKTOP_IPC.localeChanged)![1](event, 'zh') listener(event, 'zh-CN', 'rgb(249, 250, 251)', '#0f1115') expect(window.setTitleBarOverlay).toHaveBeenCalledWith({ color: 'rgb(249, 250, 251)', symbolColor: '#0f1115' }) window.webContents.emit('context-menu', {}, { isEditable: false, selectionText: 'text', editFlags: { canCopy: true } }) expect(harness.menu.buildFromTemplate).toHaveBeenLastCalledWith([{ role: 'copy', enabled: true, label: '复制', accelerator: '' }]) + harness.ipcOn.mock.calls.find(([channel]) => channel === DESKTOP_IPC.localeChanged)![1](event, 'en') listener(event, 'en', '#1b1b1c', '#f9fafb') window.webContents.emit('context-menu', {}, { isEditable: false, selectionText: 'text', editFlags: { canCopy: true } }) expect(harness.menu.buildFromTemplate).toHaveBeenLastCalledWith([{ role: 'copy', enabled: true, label: 'Copy', accelerator: '' }]) @@ -979,7 +1026,30 @@ describe('desktop main startup', () => { window.webContents.mainFrame.url = 'dsh-app://unowned/index.html' listener(event, 'zh-CN', '#fff', '#000') expect(window.setTitleBarOverlay).not.toHaveBeenCalled() - expect(harness.menu.setApplicationMenu).toHaveBeenCalledOnce() + expect(harness.menu.setApplicationMenu).toHaveBeenCalledTimes(3) + }) + + it('retains cached Chinese for a Host startup crash after the loading page reports English', async () => { + vi.spyOn(process, 'platform', 'get').mockReturnValue('win32') + const directory = join(harness.app.getPath('userData'), 'desktop') + mkdirSync(directory, { recursive: true }) + writeFileSync(join(directory, 'locale-cache'), 'zh-CN\n') + await import('../src/main.ts') + await harness.preparing.promise + const window = harness.windows[0]! + const appearance = harness.ipcOn.mock.calls.find(([channel]) => channel === DESKTOP_IPC.windowsAppearance)![1] + appearance({ sender: window.webContents, senderFrame: window.webContents.mainFrame }, 'en', '#fff', '#000') + harness.prepared.resolve() + await harness.hostStarted.promise + const host = harness.hosts[0]! + const failure = new DesktopHostFatalError('test plugin failed', 'missing required services') + host.onFailure!(failure) + host.ready.reject(failure) + await host.stopping.promise + host.exited.resolve() + await harness.dialogShown.promise + expect(vi.mocked(writeCrashReport).mock.calls[0]![1].app.locale).toBe('zh-CN') + expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).message).toBe(zh.fatalSummary) }) it('maps Windows caption menus to localized native commands and rejects foreign popup requests', async () => { @@ -989,6 +1059,7 @@ describe('desktop main startup', () => { const window = harness.windows[0]! const event = { sender: window.webContents, senderFrame: window.webContents.mainFrame } const appearance = harness.ipcOn.mock.calls.find(([channel]) => channel === DESKTOP_IPC.windowsAppearance)![1] + harness.ipcOn.mock.calls.find(([channel]) => channel === DESKTOP_IPC.localeChanged)![1](event, 'zh') appearance(event, 'zh-CN', '#fff', '#000') const handler = harness.handlers.get(DESKTOP_IPC.windowsMenu)! const foreignEvent = { ...event, sender: {} } @@ -997,7 +1068,7 @@ describe('desktop main startup', () => { expect(() => handler(event, 'application', NaN, 34)).toThrow('invalid popup request') const application = handler(event, 'application', 48, 34) expect(harness.menu.buildFromTemplate.mock.lastCall![0].map(item => item.label ?? item.type)).toEqual([ - '关于 DeepSeek Harness', 'separator', '检查更新…', '管理 dsh 命令…', 'separator', '退出', + '关于 DeepSeek Harness', 'separator', '检查更新…', '管理 dsh 命令…', 'separator', zh.toggleDevToolsMenu, 'separator', '退出', ]) expect(harness.popup.mock.lastCall![0]).toMatchObject({ window, x: 48, y: 34 }) expect(harness.popup.mock.lastCall![0].callback).toBeTypeOf('function') @@ -1034,8 +1105,8 @@ describe('desktop main startup', () => { : ['Application', 'editMenu']) const application = template[0]!.submenu as MenuItemConstructorOptions[] expect(application.filter(item => item.visible !== false).map(describeItem)).toEqual(platform === 'darwin' - ? ['about', 'separator', en.checkUpdatesMenu, en.cliCommandMenu, 'separator', 'hide', 'hideOthers', 'unhide', 'separator', 'quit'] - : ['about', 'separator', en.checkUpdatesMenu, 'separator', 'quit']) + ? ['about', 'separator', en.checkUpdatesMenu, en.cliCommandMenu, 'separator', 'toggleDevTools', 'separator', 'hide', 'hideOthers', 'unhide', 'separator', 'quit'] + : ['about', 'separator', en.checkUpdatesMenu, 'separator', 'toggleDevTools', 'separator', 'quit']) expect(harness.menu.setApplicationMenu).toHaveBeenCalledOnce() }) @@ -1048,10 +1119,7 @@ describe('desktop main startup', () => { try { await import('../src/main.ts') await harness.preparing.promise - const commands = applicationMenuItems().filter(item => - item.role === 'hide' || item.role === 'hideOthers' || item.role === 'unhide' || item.role === 'quit' - || item.label === en.checkUpdatesMenu || item.label === zh.checkUpdatesMenu - || item.label === en.cliCommandMenu || item.label === zh.cliCommandMenu) + const commands = applicationMenuItems().filter(item => item.visible !== false) await expect(JSON.stringify(commands, null, 2) + '\n') .toMatchFileSnapshot(`./expected/application-menu-${locale}.json`) expect(harness.app.name).toBe('@deepseek-ai/dsh-desktop') @@ -2206,8 +2274,8 @@ describe('desktop main startup', () => { handler(event, 'client mount failed') await harness.dialogShown.promise expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).detail).toContain('client mount failed') - expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).detail).toContain('desktop-test-logs/crash-test.log') - expect(writeCrashReport).toHaveBeenCalledWith('desktop-test-logs', expect.objectContaining({ source: 'web-boot', phase: 'startup' })) + expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).detail).toContain(join(harness.app.getPath('logs'), 'crash-test.log')) + expect(writeCrashReport).toHaveBeenCalledWith(harness.app.getPath('logs'), expect.objectContaining({ source: 'web-boot', phase: 'startup' })) expect(window.urls).toEqual(['dsh-app://app/']) }) @@ -2221,7 +2289,7 @@ describe('desktop main startup', () => { window.webContents.emit('did-fail-load', {}, -2, 'failed', 'dsh-app://app/', true) await harness.dialogShown.promise expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).detail).toContain('Desktop page failed to load') - expect(writeCrashReport).toHaveBeenCalledWith('desktop-test-logs', expect.objectContaining({ source: 'renderer' })) + expect(writeCrashReport).toHaveBeenCalledWith(harness.app.getPath('logs'), expect.objectContaining({ source: 'renderer' })) }) it('offers all recovery choices when resources fail before the Host starts', async () => { @@ -2230,7 +2298,7 @@ describe('desktop main startup', () => { harness.prepared.reject(new Error('runtime resources missing')) await harness.dialogShown.promise expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).detail).toContain('runtime resources missing') - expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).buttons).toEqual(['Exit', 'Restart', 'Disable third-party plugins, back up profile patch, and restart']) + expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).buttons).toEqual(['Exit', 'Restart', 'Disable third-party plugins, back up profile patch, and restart', 'Get diagnostic report']) expect(harness.windows[0]!.urls).toEqual(['dsh-app://app/']) }) @@ -2270,6 +2338,20 @@ describe('desktop main startup', () => { expect(harness.hosts).toHaveLength(0) }) + it('writes operation history under the instance userData instead of the shared logs directory', async () => { + await import('../src/main.ts') + await harness.preparing.promise + harness.prepared.resolve() + await harness.hostStarted.promise + const record = parsePluginOperationRecord({ runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-20T00:00:00.000Z', + reason: 'bundle', phase: 'started', target: 'test', stage: 'enable' } })! + harness.hosts[0]!.onPluginOperation!(record) + const file = join(harness.app.getPath('userData'), 'plugin-operations', 'operations.jsonl') + await vi.waitFor(() => { expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual(record) }) + expect(existsSync(join(harness.app.getPath('logs'), 'plugin-operations'))).toBe(false) + }) + it('writes the Host\'s own diagnostic into a startup-phase crash report when the Host reports a fatal error before ready', async () => { await import('../src/main.ts') await harness.preparing.promise @@ -2285,11 +2367,15 @@ describe('desktop main startup', () => { host.exited.resolve() await harness.dialogShown.promise const [directory, report] = vi.mocked(writeCrashReport).mock.calls[0]! - expect(directory).toBe('desktop-test-logs') + expect(directory).toBe(harness.app.getPath('logs')) expect(report.source).toBe('host') expect(report.phase).toBe('startup') expect(report.error).toBeInstanceOf(DesktopHostFatalError) expect(report.hostDiagnostic).toBe(diagnostic) + expect(runOperationReportJob).toHaveBeenCalledWith({ + reportPath: join(harness.app.getPath('logs'), 'crash-test.log'), directory: join(harness.app.getPath('userData'), 'plugin-operations'), + limits: { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 }, journal: null, + }, { timeoutMs: 500, cancellationGraceMs: 100 }, expect.any(AbortSignal)) expect((harness.dialog.showMessageBox.mock.calls[0]![0] as MessageBoxOptions).detail).toContain('profile has no cordis.yml') }) @@ -2312,7 +2398,7 @@ describe('desktop main startup', () => { await host.stopping.promise expect(writeCrashReport).toHaveBeenCalledOnce() const [directory, report] = vi.mocked(writeCrashReport).mock.calls[0]! - expect(directory).toBe('desktop-test-logs') + expect(directory).toBe(harness.app.getPath('logs')) expect(report.source).toBe('host') expect(report.phase).toBe('running') expect(report.error).toBeInstanceOf(Error) @@ -2324,7 +2410,76 @@ describe('desktop main startup', () => { await harness.quitCompleted.promise }) - it.each([0, 1, 2])('waits for Host exit before recovery action %s', async (response) => { + it.each([{ rejectCleanup: false, stuck: false }, { rejectCleanup: true, stuck: false }, + { rejectCleanup: true, stuck: true }])('waits for the diagnostic Worker (policy rejects=$rejectCleanup, stuck=$stuck)', async ({ rejectCleanup, stuck }) => { + harness.embeddedPolicy = { origin: 'https://policy.example.com', authentication: 'feishu-test', + allowedAuthOrigins: ['https://login.example.com'], allowedPageOrigins: ['https://downloads.example.com'] } + vi.stubGlobal('fetch', vi.fn().mockImplementation(async () => + Response.json({ error: { code: 'UNAUTHENTICATED' } }, { status: 401 }))) + let finishReport!: () => void + let reportSignal: AbortSignal | undefined + let workerExited = false + const report = new Promise<{ appended: boolean; timedOut: boolean; cancelled: boolean }>((resolve) => { + finishReport = () => { workerExited = true; resolve({ appended: false, timedOut: false, cancelled: true }) } + }) + vi.mocked(runOperationReportJob).mockImplementationOnce((_input, _options, signal) => { + reportSignal = signal + return report + }) + let finishPolicy!: () => void + let failPolicy!: (error: Error) => void + const policy = new Promise((resolve, reject) => { finishPolicy = resolve; failPolicy = reject }) + testAuth.dispose.mockImplementationOnce(() => policy) + const failure = new Error('policy Session storage cleanup failed') + const host = await readyForUpdate() + let quitCompleted = false + void harness.quitCompleted.promise.then(() => { quitCompleted = true }) + try { + const window = harness.windows[0]! + window.webContents.emit('render-process-gone', {}, { reason: 'crashed' }) + await harness.dialogShown.promise + expect(runOperationReportJob).toHaveBeenCalledOnce() + host.exited.resolve() + window.emit('session-end', { reasons: ['shutdown'] }) + harness.app.quit() + await vi.advanceTimersByTimeAsync(0) + expect(testAuth.dispose).toHaveBeenCalledOnce() + expect(reportSignal?.aborted).toBe(true) + expect(quitCompleted).toBe(false) + if (rejectCleanup) failPolicy(failure) + else finishPolicy() + await vi.advanceTimersByTimeAsync(0) + if (rejectCleanup) expect(console.error).toHaveBeenCalledWith(failure) + expect(workerExited).toBe(false) + expect(quitCompleted).toBe(false) + if (stuck) { + await vi.advanceTimersByTimeAsync(499) + expect(quitCompleted).toBe(false) + await vi.advanceTimersByTimeAsync(1) + expect(workerExited).toBe(false) + expect(console.error).toHaveBeenCalledWith('dsh desktop: operation report Worker has not exited; continuing shutdown') + } else { + finishReport() + await vi.advanceTimersByTimeAsync(0) + } + expect(quitCompleted).toBe(true) + } finally { + finishPolicy() + finishReport() + host.exited.resolve() + await vi.advanceTimersByTimeAsync(0) + await harness.quitCompleted.promise + } + }) + + it.each([{ response: 0, stuck: false }, { response: 1, stuck: false }, { response: 2, stuck: false }, + { response: 0, stuck: true }])('waits for Host exit and bounds Worker cleanup for recovery $response (stuck=$stuck)', async ({ response, stuck }) => { + let finishReport!: (result: { appended: boolean; timedOut: boolean; cancelled: boolean }) => void + let reportSignal: AbortSignal | undefined + vi.mocked(runOperationReportJob).mockImplementationOnce(async (_input, _options, signal) => { + reportSignal = signal + return new Promise((resolve) => { finishReport = resolve }) + }) harness.dialog.showMessageBox.mockResolvedValue({ response, checkboxChecked: false }) await import('../src/main.ts') await harness.preparing.promise @@ -2338,7 +2493,16 @@ describe('desktop main startup', () => { expect(harness.app.relaunch).not.toHaveBeenCalled() expect(harness.disableAllPlugins).not.toHaveBeenCalled() host.exited.resolve() + await vi.advanceTimersByTimeAsync(0) + expect(reportSignal?.aborted).toBe(true) + expect(harness.app.quit).not.toHaveBeenCalled() + if (stuck) await vi.advanceTimersByTimeAsync(500) + else finishReport({ appended: false, timedOut: false, cancelled: true }) await harness.quitCompleted.promise + if (stuck) { + expect(console.error).toHaveBeenCalledWith('dsh desktop: operation report Worker has not exited; continuing shutdown') + finishReport({ appended: false, timedOut: false, cancelled: true }) + } expect(harness.app.relaunch).toHaveBeenCalledTimes(response === 0 ? 0 : 1) expect(harness.disableAllPlugins).toHaveBeenCalledTimes(response === 2 ? 1 : 0) if (response === 2) { diff --git a/apps/desktop/tests/operation-history.spec.ts b/apps/desktop/tests/operation-history.spec.ts new file mode 100644 index 0000000000..237287d5b0 --- /dev/null +++ b/apps/desktop/tests/operation-history.spec.ts @@ -0,0 +1,172 @@ +import { mkdtemp, mkdir, open, rename, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it, onTestFinished, vi } from 'vitest' +import { readOperationHistory } from '../src/operation-history.ts' + +vi.mock('node:fs/promises', async (importOriginal) => { + const actual = await importOriginal() + return { ...actual, open: vi.fn(actual.open) } +}) + +const limits = { bytes: 64 * 1024, recordBytes: 2048, records: 100 } +function record(id: string | number) { + return { runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-19T00:00:00.000Z', + reason: 'plugin', phase: 'started', target: String(id), stage: 'enable' } } +} +function line(id: string | number) { return JSON.stringify(record(id)) + '\n' } + +async function fixture() { + const path = await mkdtemp(join(tmpdir(), 'desktop-operation-history-')) + onTestFinished(async () => { await rm(path, { recursive: true, force: true }) }) + return path +} + +it('collects recent complete records and reports malformed and incomplete entries', async () => { + const path = await fixture() + await writeFile(join(path, 'operations.jsonl'), line(1) + '{broken}\n' + line(2) + '{"incomplete":') + await writeFile(join(path, 'operations.previous.jsonl'), line(0)) + const result = await readOperationHistory(path, limits, new AbortController().signal) + expect(result.records).toEqual([record(2), record(1), record(0)]) + expect(result).toMatchObject({ invalidRecords: 1, truncated: true, cancelled: false, unavailableFiles: 0 }) +}) + +it('reads no more than its byte budget from a two GiB file and ignores unrelated history', async () => { + const path = await fixture() + await using large = await open(join(path, 'operations.jsonl'), 'w') + const size = 2 * 1024 * 1024 * 1024 + await large.truncate(size) + const tail = Buffer.from('\n' + line('last')) + await large.write(tail, 0, tail.length, size - tail.length) + await writeFile(join(path, 'pnpm.log'), 'unrelated output') + const result = await readOperationHistory(path, limits, new AbortController().signal) + expect(result.records).toEqual([record('last')]) + expect(result.bytesRead).toBe(limits.bytes) + expect(result.truncated).toBe(true) +}) + +it('bounds parsed record size and output count independently', async () => { + const path = await fixture() + await writeFile(join(path, 'operations.jsonl'), line(1) + '{"large":"' + 'x'.repeat(4096) + '"}\n' + line(2)) + const result = await readOperationHistory(path, { ...limits, records: 2 }, new AbortController().signal) + expect(result.records).toEqual([record(2), record(1)]) + expect(result.invalidRecords).toBe(1) +}) + +it('returns immediately without I/O when already cancelled', async () => { + const result = await readOperationHistory('not-a-directory', limits, AbortSignal.abort()) + expect(result).toMatchObject({ records: [], bytesRead: 0, cancelled: true, unavailableFiles: 0 }) +}) + +it('reports unreadable segments without failing the whole collection', async () => { + const path = await fixture() + await mkdir(join(path, 'operations.jsonl')) + await writeFile(join(path, 'operations.previous.jsonl'), line(1)) + const result = await readOperationHistory(path, limits, new AbortController().signal) + expect(result.records).toEqual([record(1)]) + expect(result.unavailableFiles).toBe(1) +}) + +it('awaits an in-flight read before closing and schedules no further reads after cancellation', async () => { + const path = await fixture() + const filename = join(path, 'operations.jsonl') + await writeFile(filename, ' '.repeat(limits.bytes)) + const handle = await open(filename, 'r') + onTestFinished(async () => { await handle.close() }) + const started = Promise.withResolvers() + const release = Promise.withResolvers() + const opener = vi.mocked(open).mockClear().mockResolvedValueOnce(handle) + const reader = vi.spyOn(handle, 'read').mockImplementationOnce(async () => { + started.resolve(undefined) + await release.promise + return { bytesRead: 1, buffer: Buffer.alloc(1) } + }) + const controller = new AbortController() + let settled = false + const collecting = readOperationHistory(path, limits, controller.signal) + .then((result) => { settled = true; return result }) + try { + await started.promise + controller.abort() + await Promise.resolve(undefined) + expect(settled).toBe(false) + expect(handle.fd).not.toBe(-1) + release.resolve(undefined) + expect(await collecting).toMatchObject({ cancelled: true, bytesRead: 1, records: [] }) + expect(handle.fd).toBe(-1) + expect(reader).toHaveBeenCalledTimes(1) + expect(opener).toHaveBeenCalledTimes(1) + } finally { + release.resolve(undefined) + await collecting + reader.mockRestore() + opener.mockClear() + await handle.close() + } +}) + +it('contains truncation between stat and read and still collects the previous segment', async () => { + const path = await fixture() + const filename = join(path, 'operations.jsonl') + await writeFile(filename, line(2)) + await writeFile(join(path, 'operations.previous.jsonl'), line(1)) + const handle = await open(filename, 'r+') + onTestFinished(async () => { await handle.close() }) + const originalStat = await handle.stat() + const stat = vi.spyOn(handle, 'stat').mockImplementationOnce(async () => { + await handle.truncate(0) + return originalStat + }) + const opener = vi.mocked(open).mockClear().mockResolvedValueOnce(handle) + try { + const result = await readOperationHistory(path, limits, new AbortController().signal) + expect(result).toMatchObject({ records: [record(1)], truncated: true, unavailableFiles: 0 }) + expect(handle.fd).toBe(-1) + } finally { + stat.mockRestore() + opener.mockClear() + await handle.close() + } +}) + +it('rejects invalid resource budgets before opening a file', async () => { + for (const bytes of [0, -1, 0.5, Infinity, Number.MAX_SAFE_INTEGER + 1]) { + await expect(readOperationHistory('not-a-directory', { ...limits, bytes }, new AbortController().signal)) + .rejects.toThrow(RangeError) + } +}) + +it('does not collect the same open segment twice when it rotates during collection', async () => { + const path = await fixture() + const current = join(path, 'operations.jsonl') + await writeFile(current, line(1)) + const handle = await open(current, 'r') + onTestFinished(async () => { await handle.close() }) + const opener = vi.mocked(open).mockImplementationOnce(async () => { + await rename(current, join(path, 'operations.previous.jsonl')) + await writeFile(current, line(2)) + return handle + }) + try { + const result = await readOperationHistory(path, limits, new AbortController().signal) + expect(result.records).toEqual([record(1)]) + expect(result).toMatchObject({ filesRead: 1, truncated: true }) + expect(handle.fd).toBe(-1) + } finally { + opener.mockClear() + await handle.close() + } +}) + +it.each(['absent', 'empty', 'nonempty'])('reports omitted bytes at an exact budget: previous segment %s', async (previous) => { + const path = await fixture() + const current = line(1) + await writeFile(join(path, 'operations.jsonl'), current) + if (previous !== 'absent') await writeFile(join(path, 'operations.previous.jsonl'), previous === 'empty' ? '' : line(0)) + const result = await readOperationHistory(path, + { ...limits, bytes: Buffer.byteLength(current), records: 1 }, new AbortController().signal) + expect(result.records).toEqual([record(1)]) + expect(result.truncated).toBe(previous === 'nonempty') + expect(result.filesRead).toBe(1) +}) diff --git a/apps/desktop/tests/operation-journal.spec.ts b/apps/desktop/tests/operation-journal.spec.ts new file mode 100644 index 0000000000..98e97d36a5 --- /dev/null +++ b/apps/desktop/tests/operation-journal.spec.ts @@ -0,0 +1,115 @@ +import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it, onTestFinished, vi } from 'vitest' +import { OperationJournal } from '../src/operation-journal.ts' + +vi.mock('node:fs/promises', async (importOriginal) => { + const actual = await importOriginal() + return { ...actual, mkdir: vi.fn(actual.mkdir) } +}) + +async function fixture() { + const directory = await mkdtemp(join(tmpdir(), 'desktop-operation-journal-')) + onTestFinished(async () => { await rm(directory, { recursive: true, force: true }) }) + return directory +} + +it('retains two bounded segments after dense operations across 50 plugins', async () => { + const directory = await fixture() + const journal = new OperationJournal(directory, { recordBytes: 128, segmentBytes: 1024, queuedBytes: 128 * 1000 }) + onTestFinished(async () => { await journal.close() }) + for (let i = 0; i < 1000; i++) expect(journal.enqueue(JSON.stringify({ plugin: i % 50, operation: i }))).toBe(true) + await journal.close() + expect((await readdir(directory)).sort()).toEqual(['operations.jsonl', 'operations.previous.jsonl']) + for (const name of await readdir(directory)) { + expect((await stat(join(directory, name))).size).toBeLessThanOrEqual(1024) + for (const line of (await readFile(join(directory, name), 'utf8')).trim().split('\n')) expect(() => { JSON.parse(line) }).not.toThrow() + } + expect(await readFile(join(directory, 'operations.jsonl'), 'utf8')).toContain('"operation":999') + expect(journal.status()).toEqual({ dropped: 0, failed: 0, queuedBytes: 0, disabled: false, repairedSegments: 0 }) +}) + +it('bounds the queue and encoded record bytes including multibyte characters and newline', async () => { + const directory = await fixture() + const journal = new OperationJournal(directory, { recordBytes: 8, segmentBytes: 32, queuedBytes: 16 }) + onTestFinished(async () => { await journal.close() }) + expect(journal.enqueue('{"中":1}')).toBe(false) + expect(journal.enqueue('{"a":1}')).toBe(true) + expect(journal.enqueue('{"a":2}')).toBe(true) + expect(journal.enqueue('{"a":3}')).toBe(false) + expect(journal.status()).toMatchObject({ queuedBytes: 16, dropped: 2 }) + await journal.close() + expect(await readFile(join(directory, 'operations.jsonl'), 'utf8')).toBe('{"a":1}\n{"a":2}\n') + expect(journal.enqueue('{}')).toBe(false) +}) + +it('disables persistence after a write failure without rejecting producers or close', async () => { + const directory = await fixture() + const blocked = join(directory, 'file') + await writeFile(blocked, 'untouched') + const journal = new OperationJournal(blocked, { recordBytes: 32, segmentBytes: 64, queuedBytes: 64 }) + expect(journal.enqueue('{"operation":1}')).toBe(true) + await expect(journal.close()).resolves.toBeUndefined() + expect(journal.status()).toEqual({ dropped: 0, failed: 1, queuedBytes: 0, disabled: true, repairedSegments: 0 }) + expect(await readFile(blocked, 'utf8')).toBe('untouched') +}) + +it.each(['', '{"old":1}\n'])('preserves both segments when repairing a partial append after %j', async (prefix) => { + const directory = await fixture() + const previous = '{"previous":0}\n' + await writeFile(join(directory, 'operations.previous.jsonl'), previous) + await writeFile(join(directory, 'operations.jsonl'), prefix + '{"partial":') + const journal = new OperationJournal(directory, { recordBytes: 32, segmentBytes: 64, queuedBytes: 64 }) + expect(journal.enqueue('{"new":2}')).toBe(true) + await journal.close() + expect(await readFile(join(directory, 'operations.jsonl'), 'utf8')).toBe(prefix + '{"new":2}\n') + expect(await readFile(join(directory, 'operations.previous.jsonl'), 'utf8')).toBe(previous) + expect(journal.status()).toMatchObject({ repairedSegments: 1, disabled: false }) +}) + +it('bounds both pre-existing oversized segments before writing new records', async () => { + const directory = await fixture() + for (const name of ['operations.jsonl', 'operations.previous.jsonl']) await writeFile(join(directory, name), 'x'.repeat(1000)) + const journal = new OperationJournal(directory, { recordBytes: 32, segmentBytes: 64, queuedBytes: 64 }) + journal.enqueue('{"new":2}') + await journal.close() + for (const name of await readdir(directory)) expect((await stat(join(directory, name))).size).toBeLessThanOrEqual(64) + expect(journal.status()).toMatchObject({ repairedSegments: 2, disabled: false }) +}) + +it('stops scheduling writes after a drain deadline without claiming the in-flight request ended', async () => { + const directory = await fixture() + const entered = Promise.withResolvers() + const release = Promise.withResolvers() + vi.mocked(mkdir).mockImplementationOnce(async () => { entered.resolve(undefined); await release.promise; return undefined }) + const journal = new OperationJournal(directory, { recordBytes: 32, segmentBytes: 64, queuedBytes: 64 }) + onTestFinished(async () => { release.resolve(undefined); await journal.close(); vi.useRealTimers() }) + journal.enqueue('{"operation":1}') + await entered.promise + vi.useFakeTimers() + const draining = journal.drain(500) + await vi.advanceTimersByTimeAsync(500) + expect(await draining).toBe(false) + expect(journal.status()).toMatchObject({ disabled: true, queuedBytes: 16 }) + expect(journal.enqueue('{"operation":2}')).toBe(false) + let repeated: boolean | undefined + void journal.drain(500).then((result) => { repeated = result }) + await vi.advanceTimersByTimeAsync(0) + expect(repeated).toBe(false) + release.resolve(undefined) + await journal.close() + expect(await readdir(directory)).toEqual([]) + expect(journal.status()).toMatchObject({ failed: 1, queuedBytes: 0 }) +}) + +it('can keep recording after successful installer preparation when the installer later fails', async () => { + const directory = await fixture() + const journal = new OperationJournal(directory, { recordBytes: 32, segmentBytes: 64, queuedBytes: 64 }) + onTestFinished(async () => { await journal.close() }) + journal.enqueue('{"operation":1}') + expect(await journal.drain(1000)).toBe(true) + expect(journal.enqueue('{"operation":2}')).toBe(true) + await journal.close() + expect(await readFile(join(directory, 'operations.jsonl'), 'utf8')).toBe('{"operation":1}\n{"operation":2}\n') +}) diff --git a/apps/desktop/tests/operation-report-job.spec.ts b/apps/desktop/tests/operation-report-job.spec.ts new file mode 100644 index 0000000000..82ea02fcd8 --- /dev/null +++ b/apps/desktop/tests/operation-report-job.spec.ts @@ -0,0 +1,103 @@ +import { EventEmitter } from 'node:events' +import { afterEach, expect, it, vi } from 'vitest' +import { runOperationReportJob } from '../src/operation-report-job.ts' + +const create = vi.hoisted(() => vi.fn<(...args: unknown[]) => EventEmitter>()) +vi.mock('node:worker_threads', () => ({ Worker: function (...args: unknown[]) { return create(...args) } })) +afterEach(() => { vi.useRealTimers(); create.mockReset() }) +const input = { reportPath: 'saved.log', directory: 'history', + limits: { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 }, journal: null } + +it('does not report cancellation complete until the terminated worker exits', async () => { + vi.useFakeTimers() + const worker = Object.assign(new EventEmitter(), { postMessage: vi.fn(), terminate: vi.fn(async () => 1) }) + create.mockReturnValue(worker) + let settled = false + const result = runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, new AbortController().signal).then((value) => { + settled = true + return value + }) + await vi.advanceTimersByTimeAsync(500) + expect(worker.terminate).toHaveBeenCalledTimes(1) + expect(settled).toBe(false) + worker.emit('exit', 1) + expect(await result).toEqual({ appended: false, timedOut: true, cancelled: true }) + expect(vi.getTimerCount()).toBe(0) +}) + +it('requires successful worker exit after the complete append message', async () => { + vi.useFakeTimers() + const worker = new EventEmitter() + create.mockReturnValue(worker) + const result = runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, new AbortController().signal) + worker.emit('message', true) + worker.emit('exit', 0) + expect(await result).toEqual({ appended: true, timedOut: false, cancelled: false }) + expect(vi.getTimerCount()).toBe(0) +}) + +it('contains startup and runtime worker failures', async () => { + create.mockImplementationOnce(() => { throw new Error('worker unavailable') }) + expect(await runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, new AbortController().signal)) + .toEqual({ appended: false, timedOut: false, cancelled: false }) + const worker = new EventEmitter() + create.mockReturnValue(worker) + const result = runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, new AbortController().signal) + worker.emit('error', new Error('collector failed')) + worker.emit('exit', 1) + expect(await result).toEqual({ appended: false, timedOut: false, cancelled: false }) +}) + +it('retains ownership after termination rejects until the worker actually exits', async () => { + vi.useFakeTimers() + const worker = Object.assign(new EventEmitter(), { postMessage: vi.fn(), terminate: vi.fn(async () => { throw new Error('termination failed') }) }) + create.mockReturnValue(worker) + let settled = false + const result = runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, new AbortController().signal).then((value) => { + settled = true + return value + }) + await vi.advanceTimersByTimeAsync(500) + expect(worker.terminate).toHaveBeenCalledTimes(1) + expect(settled).toBe(false) + worker.emit('exit', 1) + expect(await result).toEqual({ appended: false, timedOut: true, cancelled: true }) + expect(vi.getTimerCount()).toBe(0) +}) + + +it('allows cooperative exit during the reserved cleanup window', async () => { + vi.useFakeTimers() + const worker = Object.assign(new EventEmitter(), { postMessage: vi.fn(), terminate: vi.fn() }) + create.mockReturnValue(worker) + const result = runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, new AbortController().signal) + await vi.advanceTimersByTimeAsync(400) + expect(worker.postMessage).toHaveBeenCalledExactlyOnceWith('cancel') + expect(worker.terminate).not.toHaveBeenCalled() + worker.emit('exit', 0) + expect(await result).toEqual({ appended: false, timedOut: true, cancelled: true }) + expect(vi.getTimerCount()).toBe(0) +}) + +it('cancels on application shutdown without extending the cleanup window', async () => { + vi.useFakeTimers() + const worker = Object.assign(new EventEmitter(), { postMessage: vi.fn(), terminate: vi.fn(async () => 1) }) + create.mockReturnValue(worker) + const controller = new AbortController() + const result = runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, controller.signal) + await vi.advanceTimersByTimeAsync(200) + controller.abort() + controller.abort() + expect(worker.postMessage).toHaveBeenCalledExactlyOnceWith('cancel') + await vi.advanceTimersByTimeAsync(100) + expect(worker.terminate).toHaveBeenCalledTimes(1) + worker.emit('exit', 1) + expect(await result).toEqual({ appended: false, timedOut: false, cancelled: true }) + expect(vi.getTimerCount()).toBe(0) +}) + +it('does not start a collector after shutdown was requested', async () => { + expect(await runOperationReportJob(input, { timeoutMs: 500, cancellationGraceMs: 100 }, AbortSignal.abort())) + .toEqual({ appended: false, timedOut: false, cancelled: true }) + expect(create).not.toHaveBeenCalled() +}) diff --git a/apps/desktop/tests/operation-report-worker.e2e.ts b/apps/desktop/tests/operation-report-worker.e2e.ts new file mode 100644 index 0000000000..fd89dd11da --- /dev/null +++ b/apps/desktop/tests/operation-report-worker.e2e.ts @@ -0,0 +1,81 @@ +/** Built job and packaged Worker acceptance without provider credentials. */ +import { existsSync } from 'node:fs' +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' +import { execa } from 'execa' +import { expect, it, onTestFinished } from 'vitest' + +const job = new URL('../lib/types/operation-report-job.js', import.meta.url) +const worker = new URL('../lib/operation-report-worker.js', import.meta.url) + +it.skipIf(!existsSync(new URL('../lib/types/', import.meta.url)))('appends operation history through the built job and packaged Worker', async () => { + expect(existsSync(job), 'built report job').toBe(true) + expect(existsSync(worker), 'packaged report Worker').toBe(true) + const directory = await mkdtemp(join(tmpdir(), 'desktop-operation-worker-')) + onTestFinished(async () => { await rm(directory, { recursive: true, force: true }) }) + const record = { runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-19T00:00:00.000Z', + reason: 'bundle', phase: 'started', target: 'real-worker-test', stage: 'enable' } } + await writeFile(join(directory, 'operations.jsonl'), JSON.stringify(record) + '\n') + for (const mode of ['job', 'packaged']) { + const reportPath = join(directory, mode + '.log') + await writeFile(reportPath, 'basic report\n') + const input = { reportPath, directory, journal: null, + limits: { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 } } + const script = join(directory, mode + '.mjs') + await writeFile(script, mode === 'job' + ? `import { runOperationReportJob } from ${JSON.stringify(job.href)};\nconsole.log(JSON.stringify(await runOperationReportJob(${JSON.stringify(input)}, { timeoutMs: 10000, cancellationGraceMs: 100 }, new AbortController().signal)));\n` + : `import { Worker } from 'node:worker_threads';\nconst worker = new Worker(${JSON.stringify(fileURLToPath(worker))}, { workerData: ${JSON.stringify(input)} });\nworker.on('error', error => { throw error });\nworker.on('exit', code => { if (code !== 0) process.exitCode = 1 });\n`) + const result = await execa(process.execPath, [script], { timeout: 30000, reject: false }) + expect(result.timedOut).toBe(false) + expect(result.signal).toBeUndefined() + expect(result.exitCode, result.stderr).toBe(0) + if (mode === 'job') expect(JSON.parse(result.stdout)).toEqual({ appended: true, timedOut: false, cancelled: false }) + const report = await readFile(reportPath, 'utf8') + expect(report.startsWith('basic report\n')).toBe(true) + const summary = JSON.parse(report.split('\n').find(line => line.startsWith('{'))!) as { records: unknown[] } + expect(summary.records).toEqual([record]) + expect(report).toContain('operation history collection complete') + } +}) + +it.skipIf(!existsSync(new URL('../lib/types/', import.meta.url)))('cancels the packaged Worker after an in-flight open settles', async () => { + const directory = await mkdtemp(join(tmpdir(), 'desktop-operation-cancel-')) + onTestFinished(async () => { await rm(directory, { recursive: true, force: true }) }) + const reportPath = join(directory, 'report.log') + await writeFile(reportPath, 'basic report\n') + await writeFile(join(directory, 'operations.jsonl'), '{}\n') + const hook = join(directory, 'hook.mjs') + await writeFile(hook, `import fs from 'node:fs/promises'; +import { syncBuiltinESMExports } from 'node:module'; +import { parentPort } from 'node:worker_threads'; +const original = fs.open; +fs.open = async (...args) => { + const handle = await original(...args); + parentPort.postMessage('opened'); + await new Promise(resolve => parentPort.once('message', resolve)); + return handle; +}; +syncBuiltinESMExports(); +`) + const input = { reportPath, directory, journal: null, + limits: { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 } } + const script = join(directory, 'cancel.mjs') + await writeFile(script, `import { Worker } from 'node:worker_threads'; +const worker = new Worker(${JSON.stringify(fileURLToPath(worker))}, { + workerData: ${JSON.stringify(input)}, execArgv: ['--import', ${JSON.stringify(pathToFileURL(hook).href)}] +}); +worker.on('message', message => { + if (message === 'opened') worker.postMessage('cancel'); + else console.log(JSON.stringify(message)); +}); +worker.on('error', error => { throw error }); +worker.on('exit', code => { process.exitCode = code }); +`) + const result = await execa(process.execPath, [script], { timeout: 30000, reject: false }) + expect(result.exitCode, result.stderr).toBe(0) + expect(result.stdout).toBe('false') + expect(await readFile(reportPath, 'utf8')).toBe('basic report\n') +}) diff --git a/apps/desktop/tests/operation-report.spec.ts b/apps/desktop/tests/operation-report.spec.ts new file mode 100644 index 0000000000..46e6f6a27f --- /dev/null +++ b/apps/desktop/tests/operation-report.spec.ts @@ -0,0 +1,73 @@ +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it, onTestFinished } from 'vitest' +import { appendOperationReport } from '../src/operation-report.ts' +import { writeCrashReport, type CrashReportInput } from '../src/crash-report.ts' + +const input: CrashReportInput = { + operationHistoryPlanned: true, source: 'host', phase: 'startup', error: new Error('startup failed'), + rendererConsole: [], time: new Date('2026-10-19T00:00:00Z'), + app: { name: 'test', version: '1', platform: 'win32', arch: 'x64', electron: '44', node: '24', locale: 'zh-CN' }, +} +const limits = { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 } +async function fixture() { + const directory = await mkdtemp(join(tmpdir(), 'desktop-operation-report-')) + onTestFinished(async () => { await rm(directory, { recursive: true, force: true }) }) + const report = await writeCrashReport(directory, input) + if (report === undefined) throw new Error('Basic report fixture was not saved') + return { directory, report, basic: await readFile(report, 'utf8') } +} + +it('preserves the independently saved basic report and appends whitelisted recent history', async () => { + const { directory, report, basic } = await fixture() + const record = { runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-19T00:00:00.000Z', + reason: 'bundle', phase: 'started', target: 'test-bundle', stage: 'enable', diagnostic: 'secret' } } + await writeFile(join(directory, 'operations.jsonl'), JSON.stringify(record) + '\n') + expect(await appendOperationReport(report, directory, limits, new AbortController().signal, null)).toBe(true) + const combined = await readFile(report, 'utf8') + expect(combined.startsWith(basic)).toBe(true) + expect(combined).toContain('test-bundle') + expect(combined).not.toContain('secret') + expect(combined).toContain('operation history collection complete') + await expect(combined.slice(basic.length)).toMatchFileSnapshot('./expected/operation-history.txt') +}) + +it('leaves basic bytes unchanged when collection is cancelled or fails before append', async () => { + const { directory, report, basic } = await fixture() + expect(await appendOperationReport(report, directory, limits, AbortSignal.abort(), null)).toBe(false) + expect(await appendOperationReport(report, directory, { ...limits, bytes: 0 }, new AbortController().signal, null)).toBe(false) + expect(await readFile(report, 'utf8')).toBe(basic) + expect(basic).toContain('unavailable or incomplete') +}) + +it('bounds the entire appended section and refuses a budget smaller than its metadata', async () => { + const { directory, report, basic } = await fixture() + expect(await appendOperationReport(report, directory, { ...limits, outputBytes: 1 }, new AbortController().signal, null)).toBe(false) + expect(await readFile(report, 'utf8')).toBe(basic) + expect(await appendOperationReport(report, directory, { ...limits, outputBytes: 512 }, new AbortController().signal, null)).toBe(true) + const summary = (await readFile(report, 'utf8')).slice(basic.length) + expect(Buffer.byteLength(summary)).toBeLessThanOrEqual(512) + expect(summary).toContain('"outputRecordsOmitted":0') +}) + +it('omits oldest records to fit the output budget, counting UTF-8 bytes and all metadata', async () => { + const { directory, report, basic } = await fixture() + const records = Array.from({ length: 20 }, (_, index) => ({ + runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-19T00:00:00.000Z', + reason: 'bundle', phase: 'started', target: `测试插件-${index}`, stage: 'enable' }, + })) + await writeFile(join(directory, 'operations.jsonl'), records.map(record => JSON.stringify(record)).join('\n') + '\n') + expect(await appendOperationReport(report, directory, { ...limits, outputBytes: 1024 }, new AbortController().signal, null)).toBe(true) + const section = (await readFile(report, 'utf8')).slice(basic.length) + expect(Buffer.byteLength(section)).toBeLessThanOrEqual(1024) + const summary = JSON.parse(section.split('\n').find(line => line.startsWith('{'))!) as { + outputRecordsOmitted: number + records: { operation: { target: string } }[] + } + expect(summary.outputRecordsOmitted).toBeGreaterThan(0) + expect(summary.records.length + summary.outputRecordsOmitted).toBe(20) + expect(summary.records[0]?.operation.target).toBe('测试插件-19') +}) diff --git a/apps/desktop/tests/preload-app.spec.ts b/apps/desktop/tests/preload-app.spec.ts index af9a9f226a..8001ae6fc2 100644 --- a/apps/desktop/tests/preload-app.spec.ts +++ b/apps/desktop/tests/preload-app.spec.ts @@ -38,6 +38,19 @@ it('exposes onboarding size activation to the application document', async () => expect(electron.ipcRenderer.send.mock.calls).toEqual([[DESKTOP_IPC.onboardingActive, true], [DESKTOP_IPC.onboardingActive, false]]) }) +it('routes original-file requests through the trusted application bridge', async () => { + vi.stubGlobal('location', new URL('dsh-app://app/')) + await import('../src/preload-app.ts') + const api = electron.contextBridge.exposeInMainWorld.mock.calls.find(([name]) => name === 'dshDesktop')?.[1] as DshDesktopProductApi + const request = { url: 'https://images.example/original.gif', name: 'image.gif', mode: 'download' as const } + await api.fileActions.save(request) + await api.fileActions.readClipboardImage('https://images.example/original.gif') + expect(electron.ipcRenderer.invoke.mock.calls).toEqual([ + [DESKTOP_IPC.fileSave, request], + [DESKTOP_IPC.clipboardImageRead, 'https://images.example/original.gif'], + ]) +}) + it('limits product documents to update status and a native confirmation action', async () => { vi.stubGlobal('location', new URL('dsh-app://app/index.html')) await import('../src/preload-app.ts') diff --git a/apps/desktop/tests/prepare-runtime-patches.spec.ts b/apps/desktop/tests/prepare-runtime-patches.spec.ts index d7b7dca895..5ff1d2896f 100644 --- a/apps/desktop/tests/prepare-runtime-patches.spec.ts +++ b/apps/desktop/tests/prepare-runtime-patches.spec.ts @@ -43,7 +43,7 @@ it('classifies the current workspace and shares only runtime patch bytes', () => const before = readFileSync(join(repository, 'pnpm-lock.yaml')) const plan = prepareRuntimePatches(project, repository) expect(plan.patches.map(entry => entry.spec)).toEqual(['@earendil-works/pi-ai@1.3.0', 'node-pty@1.2.0-beta.15']) - expect(plan.workspaceOnly).toHaveLength(8) + expect(plan.workspaceOnly).toHaveLength(10) expect(plan.workspaceOnly).toContain('@botiverse/oar') expect(plan.workspaceOnly).toContain('lexical') const settings = yaml.load(readFileSync(join(project, 'pnpm-workspace.yaml'), 'utf8')) as { overrides: Record } diff --git a/apps/desktop/tests/purge-command.spec.ts b/apps/desktop/tests/purge-command.spec.ts new file mode 100644 index 0000000000..a690db7a35 --- /dev/null +++ b/apps/desktop/tests/purge-command.spec.ts @@ -0,0 +1,63 @@ +import { execFile } from 'node:child_process' +import { copyFile, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { promisify } from 'node:util' +import { z } from 'zod' +import { afterEach, expect, it } from 'vitest' + +const execute = promisify(execFile) +const root = fileURLToPath(new URL('../../..', import.meta.url)) +const roots: string[] = [] + +afterEach(async () => { + await Promise.all(roots.splice(0).map(path => rm(path, { recursive: true, force: true }))) +}) + +it('forwards the documented pnpm purge command through both package scripts to the real argument parser', async () => { + const directory = await mkdtemp(join(tmpdir(), 'desktop-purge-command-')) + roots.push(directory) + const scripts = join(directory, 'apps/desktop/scripts') + await mkdir(scripts, { recursive: true }) + const manifest = z.object({ name: z.string(), scripts: z.object({ 'purge:latest': z.string() }) }) + const repository = manifest.parse(JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))) + const desktop = manifest.parse(JSON.parse(await readFile(join(root, 'apps/desktop/package.json'), 'utf8'))) + await writeFile(join(directory, 'package.json'), JSON.stringify({ private: true, type: 'module', scripts: { 'purge:latest': repository.scripts['purge:latest'] } })) + await writeFile(join(directory, 'pnpm-workspace.yaml'), 'packages:\n - apps/desktop\n') + await writeFile(join(directory, 'apps/desktop/package.json'), JSON.stringify({ name: desktop.name, type: 'module', scripts: { 'purge:latest': desktop.scripts['purge:latest'] } })) + await mkdir(join(directory, 'node_modules')) + for (const dependency of ['.bin', 'pnpm', 'tsx', 'semver']) { + await symlink(join(root, 'node_modules', dependency), join(directory, 'node_modules', dependency), 'junction') + } + await copyFile(join(root, 'apps/desktop/scripts/upload-target.ts'), join(scripts, 'upload-target.ts')) + for (const filename of ['desktop-auto-update-environment.mjs', 'desktop-build-paths.mjs']) { + await copyFile(join(root, 'apps/desktop/scripts', filename), join(scripts, filename)) + } + // Only command forwarding and parsing are under test; all external work fails closed. + const stubs = { + 'desktop-package-environment.mjs': "export const loadDesktopPackageEnvironment = () => ({ DSH_DESKTOP_AUTO_UPDATE_ENV: 'production' })", + 'desktop-cos.ts': "export const createDesktopCos = () => { throw new Error('unexpected COS') }", + 'desktop-upload-plan.ts': "export const createDesktopUploadPlan = () => { throw new Error('unexpected installer read') }", + 'desktop-upload-run.ts': "export const uploadDesktopRelease = () => { throw new Error('unexpected upload') }", + 'desktop-release-tag.ts': "export const desktopReleaseTag = () => { throw new Error('unexpected tag') }; export const tagDesktopRelease = desktopReleaseTag", + 'desktop-edgeone.ts': ` + import assert from 'node:assert/strict' + export class DesktopPurgeError extends Error {} + export const resolveDesktopPurgeConfig = (_env, target) => ({ target }) + export const purgeDesktopInstaller = async (config) => { + assert.equal(config.target, 'mac-arm64') + console.log('purge-submit: mac-arm64') + } + `, + } + await Promise.all(Object.entries(stubs).map(([name, contents]) => writeFile(join(scripts, name), contents))) + const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => + !/KEY|SECRET|TOKEN|PASSWORD|^NODE_OPTIONS$|^DSH_|^DOWNLOAD_|^PACKAGE_/iu.test(name))) + const args = [join(root, 'node_modules/pnpm/bin/pnpm.mjs'), 'run', 'purge:latest', 'mac-arm64'] + const result = await execute(process.execPath, args, { cwd: directory, env, timeout: 30_000 }).catch((error: unknown) => { + expect(error).not.toMatchObject({ killed: true }) + throw error + }) + expect(result.stdout).toContain('purge-submit: mac-arm64') +}) diff --git a/apps/desktop/tests/retain-desktop-ci.spec.ts b/apps/desktop/tests/retain-desktop-ci.spec.ts index abe3565e93..f83592fa4a 100644 --- a/apps/desktop/tests/retain-desktop-ci.spec.ts +++ b/apps/desktop/tests/retain-desktop-ci.spec.ts @@ -10,7 +10,7 @@ const roots: string[] = [] afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))) }) it.each([ - ['mac-arm64', 'notarized'], ['win-x64', 'signed'], ['mac-arm64', 'unnotarized'], ['win-x64', 'unsigned'], + ['mac-arm64', 'notarized'], ['mac-x64', 'notarized'], ['mac-x64', 'unnotarized'], ['win-x64', 'signed'], ['mac-arm64', 'unnotarized'], ['win-x64', 'unsigned'], ] as const)('retains the complete %s %s release without signing or upload credentials', async (target, qualification) => { const root = await mkdtemp(join(tmpdir(), 'retain-ci-')) roots.push(root) @@ -23,13 +23,13 @@ it.each([ await writeFile(join(appRoot, 'package.json'), '{"version":"1.0.0"}') await writeFile(join(config, 'presets/test.env'), `DSH_DESKTOP_AUTO_UPDATE_ENV=test\nDOWNLOAD_TEST_RELEASE_ID=${'a'.repeat(32)}\n`) const names = debug ? (target === 'win-x64' ? [`deepseek-harness-1.0.0-win-x64-${qualification}.exe`] - : [`deepseek-harness-1.0.0-mac-arm64-${qualification}.dmg`, `deepseek-harness-1.0.0-mac-arm64-${qualification}.zip`]) : target === 'win-x64' + : [`deepseek-harness-1.0.0-${target}-${qualification}.dmg`, `deepseek-harness-1.0.0-${target}-${qualification}.zip`]) : target === 'win-x64' ? ['deepseek-harness-1.0.0-win-x64.exe', 'deepseek-harness-1.0.0-win-x64.exe.blockmap', 'win-x64-release.json', 'nightly.yml'] - : ['deepseek-harness-1.0.0-mac-arm64.dmg', 'deepseek-harness-1.0.0-mac-arm64.zip', 'deepseek-harness-1.0.0-mac-arm64.zip.blockmap', 'mac-arm64-release.json', 'nightly-mac.yml'] + : [`deepseek-harness-1.0.0-${target}.dmg`, `deepseek-harness-1.0.0-${target}.zip`, `deepseek-harness-1.0.0-${target}.zip.blockmap`, `${target}-release.json`, 'nightly-mac.yml'] await Promise.all(names.map(name => writeFile(join(artifacts, name), 'fixture'))) const env = { DSH_PACKAGING_CONFIG_DIR: config, DSH_PACKAGING_PRESET: 'test', DSH_DESKTOP_TARGET_PLATFORM: target === 'win-x64' ? 'win32' : 'darwin', - DSH_DESKTOP_TARGET_ARCH: target === 'win-x64' ? 'x64' : 'arm64', PACKAGE_SOURCE_REF: 'master', PACKAGE_SOURCE_SHA: 'b'.repeat(40), PACKAGE_VERSION: '1.0.0', + DSH_DESKTOP_TARGET_ARCH: target === 'mac-arm64' ? 'arm64' : 'x64', PACKAGE_SOURCE_REF: 'master', PACKAGE_SOURCE_SHA: 'b'.repeat(40), PACKAGE_VERSION: '1.0.0', PACKAGE_SIGNING: qualification === 'unsigned' ? 'unsigned' : 'signed', PACKAGE_SKIP_NOTARIZATION: qualification === 'unnotarized' ? 'true' : 'false', GITHUB_RUN_ID: '123', GITHUB_RUN_ATTEMPT: '2', GITHUB_STEP_SUMMARY: join(root, 'summary.md'), GITHUB_REPOSITORY: 'owner/repository', GITHUB_SHA: 'b'.repeat(40), RUNNER_NAME: 'dedicated', diff --git a/apps/desktop/tests/upload-target.spec.ts b/apps/desktop/tests/upload-target.spec.ts index 860d7867c2..94e9aa5b4f 100644 --- a/apps/desktop/tests/upload-target.spec.ts +++ b/apps/desktop/tests/upload-target.spec.ts @@ -1,9 +1,15 @@ -import { afterEach, describe, expect, it, vi } from 'vitest' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { DesktopPurgeError, purgeDesktopInstaller } from '../scripts/desktop-edgeone.ts' import { createDesktopUploadPlan, type DesktopUploadPlan } from '../scripts/desktop-upload-plan.ts' import { loadDesktopPackageEnvironment } from '../scripts/desktop-package-environment.mjs' import { tagDesktopRelease } from '../scripts/desktop-release-tag.ts' import { uploadDesktopRelease } from '../scripts/desktop-upload-run.ts' -import { uploadDesktopTarget } from '../scripts/upload-target.ts' +import { runDesktopUploadCommand, uploadDesktopTarget } from '../scripts/upload-target.ts' + +vi.mock('../scripts/desktop-edgeone.ts', async importOriginal => ({ + ...await importOriginal(), + purgeDesktopInstaller: vi.fn(), +})) vi.mock('../scripts/desktop-package-environment.mjs', () => ({ loadDesktopPackageEnvironment: vi.fn() })) vi.mock('../scripts/desktop-upload-plan.ts', () => ({ createDesktopUploadPlan: vi.fn() })) @@ -27,7 +33,7 @@ describe('desktop upload command', () => { { environment: 'test', latest: false, tagged: false }, ] as const)('uploads $environment latest=$latest with tagged=$tagged', async ({ environment, latest, tagged }) => { vi.spyOn(process.stdout, 'write').mockReturnValue(true) - const credentials = { DOWNLOAD_TEST_COS_SECRET_ID: 'fixture-id', DOWNLOAD_TEST_COS_SECRET_KEY: 'fixture-key' } + const credentials = { ...productionEnvironment, DSH_DESKTOP_AUTO_UPDATE_ENV: environment, DOWNLOAD_TEST_COS_SECRET_ID: 'fixture-id', DOWNLOAD_TEST_COS_SECRET_KEY: 'fixture-key' } const plan: DesktopUploadPlan = { environment, target: 'win-x64', version: '1.2.3-alpha.4', publicUrl: 'https://desktop-updates.example.com/desktop/dsh-latest-windows-x64.exe', @@ -44,6 +50,15 @@ describe('desktop upload command', () => { expect(createDesktopUploadPlan).toHaveBeenCalledWith('win-x64', { environment: credentials, latest }) expect(uploadDesktopRelease).toHaveBeenCalledOnce() expect(vi.mocked(uploadDesktopRelease).mock.calls[0]![0]).toBe(plan) + if (environment === 'production' && latest) { + expect(purgeDesktopInstaller).toHaveBeenCalledWith( + expect.objectContaining({ publicUrl: plan.publicUrl }), + ) + expect(vi.mocked(purgeDesktopInstaller).mock.invocationCallOrder[0]) + .toBeGreaterThan(vi.mocked(uploadDesktopRelease).mock.invocationCallOrder[0]!) + } else { + expect(purgeDesktopInstaller).not.toHaveBeenCalled() + } if (tagged) { expect(tagDesktopRelease).toHaveBeenCalledWith(expect.objectContaining({ version: plan.version, commit: plan.commit })) expect(vi.mocked(tagDesktopRelease).mock.invocationCallOrder[0]) @@ -54,3 +69,77 @@ describe('desktop upload command', () => { } }) }) + +const productionEnvironment = { + DSH_DESKTOP_AUTO_UPDATE_ENV: 'production', DOWNLOAD_PROD_COS_BUCKET: 'fixture-bucket', + DOWNLOAD_PROD_COS_SECRET_ID: 'fixture-id', DOWNLOAD_PROD_COS_SECRET_KEY: 'fixture-key', DOWNLOAD_PROD_EO_ZONE_ID: 'zone-fixture', +} + +describe('cache-only submission command', () => { + beforeEach(() => { + vi.mocked(loadDesktopPackageEnvironment).mockReturnValue(productionEnvironment) + }) + + it('submits a purge without reading or uploading an installer', async () => { + await uploadDesktopTarget(['--latest', '--purge-only', 'mac-arm64']) + expect(createDesktopUploadPlan).not.toHaveBeenCalled() + expect(uploadDesktopRelease).not.toHaveBeenCalled() + expect(tagDesktopRelease).not.toHaveBeenCalled() + expect(purgeDesktopInstaller).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ + publicUrl: 'https://download.deepseek.com/desktop/dsh-latest-macos-arm64.dmg', + })) + }) + + it.each([[], ['win-x64', '--purge-only'], ['win-x64', '--latest', '--purge-only', '--job-id', 'job-1'], ['win-x64', '--latest', '--', '--purge-only']])('rejects invalid arguments %j before uploading', async (...args) => { + await expect(uploadDesktopTarget(args)).rejects.toThrow() + expect(uploadDesktopRelease).not.toHaveBeenCalled() + expect(purgeDesktopInstaller).not.toHaveBeenCalled() + }) + + it('reports a completed upload when refresh fails, without tagging or repeating the upload', async () => { + const output = vi.spyOn(process.stdout, 'write').mockReturnValue(true) + vi.mocked(createDesktopUploadPlan).mockResolvedValue({ + environment: 'production', target: 'mac-arm64', version: '1.2.3', publicUrl: 'https://example.com/new-prefix/installer.dmg', + bucket: 'fixture-bucket', secretIdEnvName: 'DOWNLOAD_PROD_COS_SECRET_ID', secretKeyEnvName: 'DOWNLOAD_PROD_COS_SECRET_KEY', artifacts: [], + }) + vi.mocked(purgeDesktopInstaller).mockRejectedValue(new DesktopPurgeError('desktop purge: submission not confirmed')) + await expect(uploadDesktopTarget(['mac-arm64', '--latest'])).rejects.toThrow('desktop purge: submission not confirmed') + expect(output).toHaveBeenCalledWith('desktop upload: installer uploaded; submitting cache purge.\n') + expect(uploadDesktopRelease).toHaveBeenCalledOnce() + expect(purgeDesktopInstaller).toHaveBeenCalledOnce() + expect(tagDesktopRelease).not.toHaveBeenCalled() + }) + + it.each([false, true])('reports safe purge diagnostics to the launcher-visible stream: launcher=%s', async (launcher) => { + const previousExitCode = process.exitCode + const stdout = vi.spyOn(process.stdout, 'write').mockReturnValue(true) + const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true) + vi.stubEnv('DSH_DESKTOP_AUTO_UPDATE_ENV', 'production') + vi.stubEnv('DOWNLOAD_PROD_COS_BUCKET', 'fixture-bucket') + vi.stubEnv('DOWNLOAD_PROD_COS_SECRET_ID', 'injected-id') + vi.stubEnv('DOWNLOAD_PROD_COS_SECRET_KEY', 'injected-key') + try { + vi.mocked(purgeDesktopInstaller).mockRejectedValue(new DesktopPurgeError('desktop purge: safe recovery message')) + await runDesktopUploadCommand(['mac-arm64', '--latest', '--purge-only', ...launcher ? ['--credential-launcher', '--environment', 'production', '--bucket', 'fixture-bucket'] : []]) + expect(launcher ? stdout : stderr).toHaveBeenCalledExactlyOnceWith('desktop purge: safe recovery message\n') + expect(launcher ? stderr : stdout).not.toHaveBeenCalled() + expect(process.exitCode).toBe(1) + expect(purgeDesktopInstaller).toHaveBeenCalledWith(expect.objectContaining({ secretId: launcher ? 'injected-id' : 'fixture-id' })) + } finally { + process.exitCode = previousExitCode + vi.unstubAllEnvs() + } + }) + + it('shows usage without referring to a nonexistent record for invalid arguments', async () => { + const previousExitCode = process.exitCode + const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true) + try { + await runDesktopUploadCommand([]) + expect(stderr).toHaveBeenCalledWith(expect.stringContaining('Usage:')) + expect(stderr).not.toHaveBeenCalledWith(expect.stringContaining('record directory')) + } finally { + process.exitCode = previousExitCode + } + }) +}) diff --git a/apps/desktop/tests/upload-with-credentials.spec.ts b/apps/desktop/tests/upload-with-credentials.spec.ts index 8951f4a01b..4bd2bb1336 100644 --- a/apps/desktop/tests/upload-with-credentials.spec.ts +++ b/apps/desktop/tests/upload-with-credentials.spec.ts @@ -12,13 +12,13 @@ const launcher = fileURLToPath(new URL('../scripts/upload-with-credentials.ps1', const roots: string[] = [] const quote = (value: string): string => `'${value.replaceAll("'", "''")}'` -async function check(mode: 'valid' | 'plaintext' | 'blank' | 'missing' | 'upload' | 'upload-latest' | 'upload-failure', deployment = 'production') { +async function check(mode: 'valid' | 'plaintext' | 'blank' | 'missing' | 'upload' | 'upload-latest' | 'upload-failure' | 'upload-purge' | 'invalid-purge', deployment = 'production') { const root = await mkdtemp(join(tmpdir(), 'desktop-credentials-')) roots.push(root) const credentialPath = join(root, 'credential.clixml') let entry = launcher let uploadArguments = '' - if (mode === 'upload' || mode === 'upload-latest' || mode === 'upload-failure') { + if (mode === 'upload' || mode === 'upload-latest' || mode === 'upload-failure' || mode === 'upload-purge' || mode === 'invalid-purge') { const scripts = join(root, 'apps/desktop/scripts') await mkdir(scripts, { recursive: true }) entry = join(scripts, 'upload-with-credentials.ps1') @@ -34,12 +34,12 @@ async function check(mode: 'valid' | 'plaintext' | 'blank' | 'missing' | 'upload assert.equal(process.env.DSH_DESKTOP_WINDOWS_TOKEN_PIN, undefined) assert.equal(process.env.NODE_OPTIONS, undefined) assert.equal(process.argv[2], 'win-x64') - assert.deepEqual(process.argv.slice(3), ['--credential-launcher', '--environment', 'production', '--bucket', 'fixture-bucket'${mode === 'upload-latest' ? ", '--latest'" : ''}]) + assert.deepEqual(process.argv.slice(3), ['--credential-launcher', '--environment', 'production', '--bucket', 'fixture-bucket'${mode === 'upload-purge' ? ", '--latest', '--purge-only'" : mode === 'upload-latest' ? ", '--latest'" : ''}]) console.log('fixture-id fixture-secret') console.error('private service details fixture-secret') process.exit(${mode === 'upload-failure' ? 17 : 0}) `) - uploadArguments = ` -Upload -Target win-x64 -Bucket fixture-bucket${mode === 'upload-latest' ? ' -Latest' : ''}` + uploadArguments = ` -Upload -Target win-x64 -Bucket fixture-bucket${mode === 'upload-purge' ? ' -Latest -PurgeOnly' : mode === 'invalid-purge' ? ' -PurgeOnly' : mode === 'upload-latest' ? ' -Latest' : ''}` } const setup = mode === 'missing' ? '' : ` [pscustomobject]@{ @@ -134,7 +134,14 @@ describe.skipIf(process.platform !== 'win32')('Windows upload credentials', () = expect(result.output).not.toContain('child environment verified') }) - it.each(['upload', 'upload-latest', 'upload-failure'] as const)('isolates the %s child and sanitizes both output streams', async (mode) => { + it('reports invalid purge arguments before decrypting credentials', async () => { + const result = await check('invalid-purge') + expect(result.code).toBe(1) + expect(result.output).toContain('invalid arguments; PurgeOnly requires Latest and production') + expect(result.output).not.toContain('stage=decrypt-file') + }) + + it.each(['upload', 'upload-latest', 'upload-failure', 'upload-purge'] as const)('isolates the %s child and sanitizes both output streams', async (mode) => { const result = await check(mode) expect(result.code, result.output).toBe(mode === 'upload-failure' ? 1 : 0) expect(result.output).toContain('[REDACTED] [REDACTED]') diff --git a/apps/desktop/tests/welcome-startup.spec.ts b/apps/desktop/tests/welcome-startup.spec.ts index 7915248243..4ae8743e2e 100644 --- a/apps/desktop/tests/welcome-startup.spec.ts +++ b/apps/desktop/tests/welcome-startup.spec.ts @@ -87,6 +87,7 @@ vi.mock('electron', () => ({ net: { fetch: vi.fn() }, nativeTheme: state.nativeTheme, session: { defaultSession: { + on: vi.fn(), setPermissionCheckHandler: vi.fn(), setPermissionRequestHandler: vi.fn(), webRequest: { onBeforeSendHeaders: vi.fn() }, } }, protocol: { registerSchemesAsPrivileged: vi.fn(), handle: vi.fn() }, diff --git a/apps/desktop/tests/windows-asar-unpack.spec.ts b/apps/desktop/tests/windows-asar-unpack.spec.ts index 2fe4b3aaf2..ba417ebce3 100644 --- a/apps/desktop/tests/windows-asar-unpack.spec.ts +++ b/apps/desktop/tests/windows-asar-unpack.spec.ts @@ -125,6 +125,42 @@ async function packageFixture(input: Awaited>) { }).pack([{ src: mapping.from, destination: join(destination, 'dsh'), files, metadata }]) } +it('includes the diagnostic worker in the archive selected by the shipping file rules', async () => { + const root = await mkdtemp(join(tmpdir(), 'diagnostic-worker-asar-')) + roots.push(root) + const appDir = join(root, 'app') + const resources = join(root, 'resources') + const destination = join(resources, 'app') + await mkdir(join(appDir, 'lib'), { recursive: true }) + await mkdir(resources) + const worker = join(appDir, 'lib', 'operation-report-worker.js') + const excluded = join(appDir, 'lib', 'not-shipped.js') + await writeFile(worker, 'export {}') + await writeFile(excluded, 'export {}') + const config = unsignedWindowsConfig('com.example.diagnostics', join(root, 'dsh')) + const filesConfig = config.files.map(entry => typeof entry === 'string' ? entry : { ...entry, filter: [...entry.filter] }) + const matchers = getFileMatchers({ files: filesConfig }, 'files', destination, { + defaultSrc: appDir, globalOutDir: root, customBuildOptions: {}, macroExpander: value => value, + })! + const matcher = matchers.find(entry => entry.from === appDir)! + const filter = matcher.createFilter() + const files: string[] = [] + const metadata = new Map() + for (const file of [worker, excluded]) { + const stat = await lstat(file) + if (filter(file, stat)) { + files.push(file) + metadata.set(file, stat) + } + } + await new AsarPackager({ info: { getWorkspaceRoot: async () => root } }, { + defaultDestination: destination, resourcePath: resources, options: {}, unpackPattern: () => false, + }).pack([{ src: appDir, destination, files, metadata }]) + const archive = await readAsar(join(resources, 'app.asar')) + expect(archive.getFile('lib/operation-report-worker.js').size).toBe(Buffer.byteLength('export {}')) + expect(() => archive.getFile('lib/not-shipped.js')).toThrow() +}) + it.each([false, true])('unpacks PE files through builder source patterns (external=%s)', async (external) => { const input = await fixture(external) const files = await prepareWindowsAsarUnpack(input.context, input.source) diff --git a/apps/desktop/tsconfig.client.json b/apps/desktop/tsconfig.client.json index 3de33f06dd..eb17ebe087 100644 --- a/apps/desktop/tsconfig.client.json +++ b/apps/desktop/tsconfig.client.json @@ -18,6 +18,9 @@ }, { "path": "../../packages/client/product-analytics/tsconfig.client.json" + }, + { + "path": "../../packages/client/ui-file-actions" } ] } diff --git a/apps/desktop/tsconfig.host.json b/apps/desktop/tsconfig.host.json index b0bcc315f0..7078ac8198 100644 --- a/apps/desktop/tsconfig.host.json +++ b/apps/desktop/tsconfig.host.json @@ -35,8 +35,14 @@ { "path": "../../packages/client/product-analytics/tsconfig.host.json" }, + { + "path": "../../packages/boot/plugin-manager" + }, { "path": "../../packages/util/file-drag" + }, + { + "path": "../../packages/client/ui-file-actions" } ], "exclude": [ diff --git a/apps/desktop/tsdown.config.ts b/apps/desktop/tsdown.config.ts index d4f034252d..40ed1a0316 100644 --- a/apps/desktop/tsdown.config.ts +++ b/apps/desktop/tsdown.config.ts @@ -33,6 +33,12 @@ if (clientVersion === undefined) throw new Error('desktop build: the client envi const clientVersionDefine = { 'process.env.DSH_CLIENT_VERSION': JSON.stringify(clientVersion) } export default defineConfig([ + { + entry: ['lib/types/operation-report-worker.js'], + plugins: [packagedImportsPlugin({ packages: new Set(), nodeBuiltins: true })], + outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024', + fixedExtension: false, dts: false, clean: false, codeSplitting: false, + }, { entry: ['lib/types/command-manager-entry.js'], plugins: [packagedImportsPlugin({ packages: new Set(), nodeBuiltins: true })], diff --git a/apps/plugin-market-generator/package.json b/apps/plugin-market-generator/package.json index b9b31d1912..a426b81646 100644 --- a/apps/plugin-market-generator/package.json +++ b/apps/plugin-market-generator/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-plugin-market-generator", "description": "Reference generator of plugin market index files from a list of npm packages and Git repositories", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "private": true, "type": "module", "scripts": { diff --git a/apps/web/package.json b/apps/web/package.json index b967ed8b39..51ecc68787 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-web-frontend", "description": "Web application entry: vite build over the @deepseek-ai/dsh-client-web shell library; dist/ served by apps/cli's dsh web", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -72,7 +72,8 @@ "@deepseek-ai/dsh-experimental-voice-input-bundle": "workspace:*", "@deepseek-ai/dsh-experimental-cot-translation-bundle": "workspace:*", "@deepseek-ai/dsh-experimental-worktree": "workspace:*", - "@deepseek-ai/dsh-experimental-plugin-market-bundle": "workspace:*" + "@deepseek-ai/dsh-experimental-plugin-market-bundle": "workspace:*", + "@deepseek-ai/dsh-experimental-forge-bundle": "workspace:*" }, "dependencies": { "@deepseek-ai/dsh-message-quotes": "workspace:*" diff --git a/apps/web/tests/assembled-remote.ts b/apps/web/tests/assembled-remote.ts index 86dd1c4a50..2c19ce6177 100644 --- a/apps/web/tests/assembled-remote.ts +++ b/apps/web/tests/assembled-remote.ts @@ -287,8 +287,11 @@ export function createAssembledRemote(options: AssembledRemoteOptions = {}): Ass }) mock.unary('session/attachment', (request: unknown) => { request = recordValue(request, 'request') - const attachmentId = recordString(request, 'attachmentId') - return attachments.get(attachmentId) ?? { + const attachment = recordValue(request, 'attachment') + const attachmentId = recordString(attachment, 'attachmentId') + const stored = attachments.get(attachmentId) + if (stored !== undefined) return ok({ attachment, data: recordString(recordValue(stored, 'value'), 'data') }) + return { ok: false, error: { code: 'session/attachment-invalid', diff --git a/apps/web/tests/autolink-cjk-punctuation.e2e.ts b/apps/web/tests/autolink-cjk-punctuation.e2e.ts new file mode 100644 index 0000000000..a9e4e37de9 --- /dev/null +++ b/apps/web/tests/autolink-cjk-punctuation.e2e.ts @@ -0,0 +1,50 @@ +/** A bare URL in a settled CJK reply ends before the following full-width punctuation. */ +import { readFile } from 'node:fs/promises' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { chromium, type Browser, type Page } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { + assertFixtureInventory, compareOrRefreshGolden, + launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { newEnglishPage, saveFailureShot } from './support.ts' + +const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/autolink-cjk-punctuation', import.meta.url)) +const MODE = webSnapshotMode() +const URL_TEXT = 'http://127.0.0.1:8790/' + +describe('web e2e: bare URL before CJK punctuation', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + + beforeAll(async () => { + scaffold = await launchWebScaffold({}) + await seedSession(scaffold, await readFile(join(SNAPSHOT_DIR, 'session.v4.jsonl'), 'utf8'), 'autolink-cjk-punctuation') + browser = await chromium.launch() + page = await newEnglishPage(browser) + tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.locator('[role="treeitem"]').first().click() + await page.locator('[role="treeitem"]').nth(1).click() + await page.getByRole('link', { name: URL_TEXT, exact: true }).waitFor() + }, 120_000) + + afterAll(async () => { + await browser?.close() + await scaffold?.close() + }) + + it('links only the URL and renders the following sentence as text', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-autolink-cjk-punctuation')) + const link = page.getByRole('link', { name: URL_TEXT, exact: true }) + expect(await link.getAttribute('href')).toBe(URL_TEXT) + const prose = await link.locator('..').ariaSnapshot() + await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'reply.expected.md'), prose, MODE) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + await assertFixtureInventory(SNAPSHOT_DIR, ['session.v4.jsonl', 'reply.expected.md']) + }) +}) diff --git a/apps/web/tests/caption-overlays.e2e.ts b/apps/web/tests/caption-overlays.e2e.ts index 2a86277843..d336b64950 100644 --- a/apps/web/tests/caption-overlays.e2e.ts +++ b/apps/web/tests/caption-overlays.e2e.ts @@ -21,8 +21,9 @@ it('keeps settings and expanded plugin dialogs clear of the Windows caption acro document.documentElement.setAttribute('data-windows-titlebar', '') document.documentElement.style.setProperty('--dsh-windows-titlebar-height', '40px') }) - const reopenSidebar = page.getByRole('button', { name: '打开侧边栏', exact: true }) - if (await reopenSidebar.isVisible()) await reopenSidebar.click() + await page.setViewportSize({ width: 521, height: 600 }) + await page.locator('[data-sidebar-drawer]').waitFor({ state: 'detached' }) + const reopenSidebar = page.locator('[data-shell-leading]').getByRole('button', { name: '打开侧边栏', exact: true }) await openSettings(page, 'zh') const settings = page.getByRole('dialog', { name: '设置', exact: true }) const settingsMask = settings.locator('..').locator(':scope > [aria-hidden="true"]') @@ -51,7 +52,7 @@ it('keeps settings and expanded plugin dialogs clear of the Windows caption acro await menu.waitFor({ state: 'hidden' }) expect(await settings.isVisible()).toBe(true) await settings.getByRole('button', { name: '关闭', exact: true }).click() - if (await reopenSidebar.isVisible()) await reopenSidebar.click() + if (await page.locator('[data-sidebar-drawer][data-sidebar-collapsed]').count() > 0) await reopenSidebar.click() await page.getByRole('navigation', { name: '全局面板' }).getByRole('button', { name: '插件', exact: true }).click() await page.locator('[data-plugin-panel]').getByRole('button', { name: '添加插件', exact: true }).click() const plugin = page.getByRole('dialog', { name: '添加插件', exact: true }) @@ -88,7 +89,9 @@ it('keeps settings and expanded plugin dialogs clear of the Windows caption acro if (value === 'darwin') document.documentElement.setAttribute('data-platform', value) else document.documentElement.removeAttribute('data-platform') }, platform) - if (await reopenSidebar.isVisible()) await reopenSidebar.click() + // Publish the synthetic platform change through the frame's size observer. + await page.setViewportSize({ width: platform === 'darwin' ? 520 : 521, height: 600 }) + await page.locator('[data-sidebar-drawer]').waitFor() await openSettings(page, 'zh') await expect.poll(async () => (await settings.boundingBox())?.y).toBe(platform === 'darwin' ? 68 : 0) expect((await settingsMask.boundingBox())?.y).toBe(0) diff --git a/apps/web/tests/chat-fold-opened-group.e2e.ts b/apps/web/tests/chat-fold-opened-group.e2e.ts index 184255f48a..1b92611d27 100644 --- a/apps/web/tests/chat-fold-opened-group.e2e.ts +++ b/apps/web/tests/chat-fold-opened-group.e2e.ts @@ -1,19 +1,19 @@ /** * Scroll continuity when "On next message" folds a process group the reader opened. The latest Turn has * one Step; the reader opened its group and expanded the reasoning inside, so the group body is capped and - * scrollable, then sends the next message from the floor. A held prompt keeps the new Turn from starting - * until the fold settles, so only the fold moves the view while the scrollport is sampled on every - * animation frame. + * scrollable, then sends the next message from the floor. Agent maintenance keeps the accepted message in + * the inbox, so its echo folds the group before the new Turn starts, and only the fold moves the view while + * the scrollport is sampled on every animation frame. * * - A long answer leaves the folded group above the viewport. The scroll position changes in one direction * only: the fold never scrolls the view away and then snaps it back. - * - A short answer leaves fold room below the tail. Growth fills that room without scrolling, so the running - * status keeps its entrance slide when the new Step's first row appears instead of moving in one frame. + * - A short answer leaves fold room below the tail. The new Turn's growth fills that room without scrolling + * through Turn end, the room never grows back, and the running status only moves down. */ import { mkdtemp, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' -import type { Browser, Page, Route } from 'playwright' +import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import type { StreamChunk } from '@deepseek-ai/dsh-llm' @@ -26,7 +26,7 @@ import { newEnglishPage, openSettings } from './support.ts' declare global { interface Window { - openFoldTrace?: { readonly frames: TraceFrame[]; readonly slides: number[]; stop(): void } + openFoldTrace?: { readonly frames: TraceFrame[]; stop(): void } } } @@ -43,8 +43,6 @@ interface TraceFrame { readonly floor: number /** Height of the fold room below the transcript. */ readonly spacer: number - /** The column marks the tail as pinned, which runs the status slide at zero duration. */ - readonly pinned: boolean /** The running status's top relative to the scrollport, when it is mounted. */ readonly status: number | null readonly folding: boolean @@ -162,17 +160,13 @@ async function openLatestGroup(page: Page): Promise { await page.mouse.move(0, 0) } -/** - * Sample the scrollport on every animation frame, and record the duration of every status entrance slide - * that a flow change starts. - */ +/** Sample the scrollport on every animation frame. */ async function startTrace(page: Page): Promise { await page.evaluate((selector) => { const host = document.querySelector(selector)! const column = host.querySelector('[data-chat-flow]')! const spacer = host.querySelector('[data-chat-turn-spacer]')! const frames: TraceFrame[] = [] - const slides: number[] = [] let frame = 0 const tick = (): void => { const status = host.querySelector('[data-chat-running]') @@ -180,32 +174,18 @@ async function startTrace(page: Page): Promise { top: host.scrollTop, floor: Math.max(0, host.scrollHeight - host.clientHeight), spacer: spacer.getBoundingClientRect().height, - pinned: column.hasAttribute('data-chat-tail-pinned'), status: status === null ? null : status.getBoundingClientRect().top - host.getBoundingClientRect().top, folding: column.hasAttribute('data-input-fold') || host.querySelector('[data-chat-motion="collapse"]') !== null, }) frame = requestAnimationFrame(tick) } - // The slide starts at the style update after the flow change; reading animations there sees its duration. - const observer = new MutationObserver(() => { - const status = host.querySelector('[data-chat-running]') - for (const animation of status?.getAnimations() ?? []) { - if (animation instanceof CSSAnimation && animation.animationName.includes('running-follows-output')) { - slides.push(Number(animation.effect?.getComputedTiming().duration ?? 0)) - } - } - }) - observer.observe(column, { childList: true, subtree: true }) - window.openFoldTrace = { frames, slides, stop: () => { cancelAnimationFrame(frame); observer.disconnect() } } + window.openFoldTrace = { frames, stop: () => { cancelAnimationFrame(frame) } } frame = requestAnimationFrame(tick) }, ROOT) } -async function readTrace(page: Page): Promise<{ frames: TraceFrame[]; slides: number[] }> { - return page.evaluate(() => { - const trace = window.openFoldTrace! - return { frames: [...trace.frames], slides: [...trace.slides] } - }) +async function readTrace(page: Page): Promise<{ frames: TraceFrame[] }> { + return page.evaluate(() => ({ frames: [...window.openFoldTrace!.frames] })) } /** Per-frame scroll movements larger than subpixel rounding. */ @@ -223,8 +203,8 @@ interface World { readonly page: Page readonly session: SessionId readonly tripwire: ReturnType - /** Releases the held prompt; the new Turn starts after this. */ - readonly releasePrompt: () => void + /** Ends the Agent maintenance that keeps the accepted message in the inbox; the new Turn starts after this. */ + readonly releaseTurn: () => void /** Releases the held model stream; the new Step's output arrives after this. */ readonly releaseModel: () => void readonly ended: Promise @@ -232,8 +212,8 @@ interface World { } /** - * Seed and open the case, open the latest group, and send the next message from the floor with the prompt - * and the model stream held. + * Seed and open the case, open the latest group, and send the next message from the floor with the new Turn + * and its model stream held. */ async function sendFromOpenedGroup(browser: Browser, id: string, answerParagraphs: number): Promise { const replayDir = await mkdtemp(join(tmpdir(), 'dsh-open-fold-')) @@ -249,17 +229,15 @@ async function sendFromOpenedGroup(browser: Browser, id: string, answerParagraph await model.promise for await (const chunk of next()) yield chunk }) - const prompt = Promise.withResolvers() - const holdPrompt = async (route: Route): Promise => { - await prompt.promise - await route.continue() - } + const turn = Promise.withResolvers() + let maintenance: Promise = Promise.resolve(undefined) const page = await newEnglishPage(browser, 826) const close = async (): Promise => { - prompt.resolve(undefined) + turn.resolve(undefined) model.resolve(undefined) disposeHold() const failures: unknown[] = [] + await maintenance.catch((error: unknown) => failures.push(error)) await page.context().close().catch((error: unknown) => failures.push(error)) await scaffold.close().catch((error: unknown) => failures.push(error)) await rm(replayDir, { recursive: true, force: true }).catch((error: unknown) => failures.push(error)) @@ -280,7 +258,9 @@ async function sendFromOpenedGroup(browser: Browser, id: string, answerParagraph await toBottom(page) await openLatestGroup(page) await toBottom(page) - await page.route('**/api/session/prompt', holdPrompt) + const resolved = await scaffold.ctx.sessionController.resolveAgent(session) + if ('error' in resolved) throw resolved.error + maintenance = resolved.agent.runMaintenance(() => turn.promise) const ended = new Promise((resolveEnded, reject) => { const timer = setTimeout(() => { off(); reject(new Error(`${id}: no turn/end within 60000ms`)) }, 60_000) const off = scaffold.ctx.on('session/event', (owner: { id: SessionId }, event: SessionEvent) => { @@ -299,7 +279,7 @@ async function sendFromOpenedGroup(browser: Browser, id: string, answerParagraph await stableScroll(page) return { scaffold, page, session, tripwire, ended, close, - releasePrompt: () => { prompt.resolve(undefined) }, + releaseTurn: () => { turn.resolve(undefined) }, releaseModel: () => { model.resolve(undefined) }, } } catch (error) { @@ -330,7 +310,7 @@ describe.skipIf(MODE === 'record')('web e2e: next-message fold of an opened proc expect.soft(reversals, `scroll direction changes; per-frame movements ${JSON.stringify(steps)}`).toBe(0) const settled = frames.at(-1)! expect.soft(settled.floor - settled.top, 'distance from the floor after the fold').toBeLessThanOrEqual(1) - world.releasePrompt() + world.releaseTurn() world.releaseModel() await world.ended expect(world.tripwire.pageErrors).toEqual([]) @@ -339,26 +319,28 @@ describe.skipIf(MODE === 'record')('web e2e: next-message fold of an opened proc } }) - it('keeps the running status slide while fold room below a short answer takes the new Step', async () => { + it('keeps the view still while fold room below a short answer takes the new Turn', async () => { const world = await sendFromOpenedGroup(browser, 'short', 2) try { - const folded = (await readTrace(world.page)).frames.at(-1)! + const foldedFrames = (await readTrace(world.page)).frames + const folded = foldedFrames.at(-1)! expect.soft(folded.spacer, 'fold room below the short answer').toBeGreaterThan(0) - expect.soft(folded.pinned, 'tail pin while fold room remains').toBe(false) - world.releasePrompt() + world.releaseTurn() // The running Step's group row is the first row after the user message; output stays held until then. await world.page.locator(`${ROOT} [data-chat-group-key][data-chat-turn="${String(TURNS + 1)}"]`).waitFor({ timeout: 30_000 }) await world.page.locator(`${ROOT} [data-chat-running]`).waitFor() - await world.page.waitForTimeout(300) - const { frames, slides } = await readTrace(world.page) - const statusSteps = movements(frames.map(frame => ({ ...frame, top: frame.status ?? Number.NaN }))) - .filter(step => Number.isFinite(step)) - // The fold runs status moves at zero duration on its own, so only settled frames show the pin's effect. - const pinnedOverRoom = frames.filter(frame => !frame.folding && frame.pinned && frame.spacer > 0) - expect.soft(pinnedOverRoom, 'settled frames pinned over fold room').toEqual([]) - expect.soft(slides.some(duration => duration > 0), `status slide durations ${JSON.stringify(slides)}; status movements ${JSON.stringify(statusSteps)}`).toBe(true) world.releaseModel() await world.ended + await stableScroll(world.page) + // Frames from the settled fold through Turn end. + const after = (await readTrace(world.page)).frames.slice(foldedFrames.length - 1) + const roomed = after.filter(frame => frame.spacer > 0) + const regrowth = roomed.some((frame, index) => index > 0 && frame.spacer > roomed[index - 1]!.spacer + 1) + const statusSteps = movements(after.map(frame => ({ ...frame, top: frame.status ?? Number.NaN }))) + .filter(step => Number.isFinite(step)) + expect.soft(movements(roomed), 'scroll movements while fold room remains').toEqual([]) + expect.soft(regrowth, `fold room grows back; spacer ${JSON.stringify(roomed.map(frame => Math.round(frame.spacer)))}`).toBe(false) + expect.soft(statusSteps.every(step => step > 0), `running status movements ${JSON.stringify(statusSteps)}`).toBe(true) expect(world.tripwire.pageErrors).toEqual([]) } finally { await world.close() diff --git a/apps/web/tests/chat-scroll-contract.e2e.ts b/apps/web/tests/chat-scroll-contract.e2e.ts index 49675a473a..fd5f778c1e 100644 --- a/apps/web/tests/chat-scroll-contract.e2e.ts +++ b/apps/web/tests/chat-scroll-contract.e2e.ts @@ -6,7 +6,7 @@ import { access, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' -import type { Browser, Page, Route } from 'playwright' +import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import type { StreamChunk } from '@deepseek-ai/dsh-llm' @@ -309,6 +309,9 @@ async function loadedFlowRows(page: Page): Promise { } async function openSeed(page: Page, fixture: ChatScrollFixture, tailMarker?: string): Promise { + if (await page.locator('[data-sidebar-drawer][data-sidebar-collapsed]').count() > 0) { + await page.locator('[data-shell-leading]').getByRole('button', { name: 'Open sidebar', exact: true }).click() + } // Search collapsed into a header action; expand it before filling. const searchButton = page.getByRole('button', { name: 'Search sessions' }) if (await searchButton.getAttribute('aria-expanded') !== 'true') await searchButton.click() @@ -679,14 +682,11 @@ describe('web e2e: long Chat scroll contract', () => { yield chunk } }) + const resolved = await world.scaffold.ctx.sessionController.resolveAgent(SessionId(`visible-fold-${scenario.name}`)) + if ('error' in resolved) throw resolved.error + // Maintenance keeps the accepted message in the inbox, so its echo folds the earlier work before the Turn starts. const promptGate = Promise.withResolvers() - const promptBlocked = Promise.withResolvers() - const holdPrompt = async (route: Route): Promise => { - promptBlocked.resolve(undefined) - await promptGate.promise - await route.continue() - } - await page.route('**/api/session/prompt', holdPrompt) + const maintenance = resolved.agent.runMaintenance(() => promptGate.promise) const trace = page.evaluate(({ marker, race }) => new Promise((resolveTrace) => { const host = document.querySelector('[data-conversation-scroll]')! const column = host.querySelector('[data-chat-flow]:has(> [data-slot="conversation.chat.flow"])')! @@ -781,7 +781,7 @@ describe('web e2e: long Chat scroll contract', () => { await page.clock.resume() } } else await page.getByRole('button', { name: 'Send message', exact: true }).click() - await promptBlocked.promise + await expect.poll(() => page.locator('[data-composer-input]').last().textContent()).toBe('') await page.getByText(input, { exact: true }).waitFor() await expect.poll(() => page.locator('[data-chat-motion="collapse"]').count()).toBe(0) if (scenario.name !== 'cancel-all-during-fold') await expectBottom(page) @@ -801,6 +801,7 @@ describe('web e2e: long Chat scroll contract', () => { }) await page.locator('[data-conversation-scroll]').evaluate(host => host.dispatchEvent(new Event('dsh-test-fold-growth'))) promptGate.resolve(undefined) + await maintenance release() await finishBlocked.promise await page.getByText('VISIBLE_FOLD_DONE', { exact: false }).waitFor() @@ -808,8 +809,8 @@ describe('web e2e: long Chat scroll contract', () => { await nextPaint(page) } finally { promptGate.resolve(undefined) + await maintenance release() - await page.unroute('**/api/session/prompt', holdPrompt) await page.locator('[data-conversation-scroll]').evaluate(host => host.dispatchEvent(new Event('dsh-test-fold-stop'))) samples = await trace finishGate.resolve(undefined) @@ -1702,9 +1703,6 @@ describe('web e2e: long Chat scroll contract', () => { await world.page.getByRole('tab', { name: 'Trajectory', exact: true }).click() await world.page.getByLabel('Trajectory timeline').waitFor({ timeout: 30_000 }) await world.page.setViewportSize({ width: 700, height: 900 }) - // The narrow breakpoint auto-collapses the sidebar. Re-open it because - // this scenario switches sessions while pinning the narrow Chat scroll owner. - await world.page.getByRole('button', { name: 'Open sidebar', exact: true }).click() await world.page.getByRole('tab', { name: 'Chat', exact: true }).click() await nextPaint(world.page) await expectSameFlowTop(world.page, sessionAnchor, RESPONSIVE_REFLOW_TOLERANCE) diff --git a/apps/web/tests/client-plugin-live.e2e.ts b/apps/web/tests/client-plugin-live.e2e.ts index 21ad5a1182..72a389f9c8 100644 --- a/apps/web/tests/client-plugin-live.e2e.ts +++ b/apps/web/tests/client-plugin-live.e2e.ts @@ -26,7 +26,7 @@ async function openInventory(page: Page, url: string) { return dialog } -it('places dynamic Session menu rows by order among the shipped ones and removes them with their fiber', async () => { +it('keeps ordered legacy Session menu rows before Archive and removes them with their fiber', async () => { const scaffold = await launchWebScaffold({ extraInstallAnchors: [join(FIXTURE, 'package.json')] }) onTestFinished(() => scaffold.close()) const workspace = await scaffold.ctx.workspaceRegistry.create(scaffold.workspaceCwd) @@ -46,12 +46,13 @@ it('places dynamic Session menu rows by order among the shipped ones and removes const trailing = row.locator('[data-session-trailing]') const observations: { stage: string; icons: string[]; time: boolean; pinned: boolean; actions: boolean }[] = [] - const observe = async (stage: string, iconsVisible: boolean, actionsVisible: boolean, target = row): Promise => { + const observe = async (stage: string, iconsVisible: boolean, actionsVisible: boolean, target = row, + timeVisible = iconsVisible): Promise => { const icons = target.locator('[data-session-trailing]') const actions = target.getByRole('button', { name: `Session actions for ${SESSION_TITLE}` }) const time = target.locator('[class*="time"]') await expect.poll(() => icons.first().isVisible()).toBe(iconsVisible) - await expect.poll(() => time.isVisible()).toBe(iconsVisible) + await expect.poll(() => time.isVisible()).toBe(timeVisible) await expect.poll(() => actions.isVisible()).toBe(actionsVisible) observations.push({ stage, @@ -94,14 +95,16 @@ it('places dynamic Session menu rows by order among the shipped ones and removes await observe('menu-open', false, true) const menu = page.getByRole('menu') await menu.waitFor() - expect(await menu.getByRole('separator').count()).toBe(1) + expect(await menu.getByRole('separator').count()).toBe(3) + const exportRow = menu.getByRole('menuitem', { name: 'Export session', exact: true }) + expect(await exportRow.locator('..').getByRole('separator').isVisible()).toBe(true) await compareOrRefreshGolden( SESSION_ACTION_EXPECTED, await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd), webSnapshotMode(), ) - await menu.getByRole('menuitem', { name: 'Export session' }).press('Enter') + await exportRow.press('Enter') await expect.poll(() => menu.count()).toBe(0) expect(await page.evaluate(() => ({ action: document.documentElement.dataset.sessionAction, @@ -113,7 +116,7 @@ it('places dynamic Session menu rows by order among the shipped ones and removes await page.mouse.move(0, 0) await observe('blur', true, false) await page.setViewportSize({ width: 390, height: 844 }) - await page.getByRole('button', { name: 'Open sidebar', exact: true }).first().click() + await page.locator('[data-shell-leading]').getByRole('button', { name: 'Open sidebar', exact: true }).click() await page.mouse.move(0, 0) await observe('narrow', true, false) const bounds = await row.evaluate((element) => { @@ -133,23 +136,23 @@ it('places dynamic Session menu rows by order among the shipped ones and removes try { const touchConsole = watchConsole(touchPage) await touchPage.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) - await touchPage.getByRole('button', { name: 'Open sidebar', exact: true }).first().click() + await touchPage.locator('[data-shell-leading]').getByRole('button', { name: 'Open sidebar', exact: true }).click() const touchRow = touchPage.getByRole('treeitem').filter({ has: touchPage.getByText(SESSION_TITLE, { exact: true }) }) const touchTrigger = touchRow.getByRole('button', { name: `Session actions for ${SESSION_TITLE}` }) await touchTrigger.waitFor() expect(await touchPage.evaluate(() => matchMedia('(hover: hover)').matches)).toBe(false) - await observe('touch', true, true, touchRow) + await observe('touch', true, true, touchRow, false) expect(await touchRow.getByRole('button', { name: 'Archive session', exact: true }).isVisible()).toBe(false) expect(await touchRow.getByRole('button', { name: 'Pin session', exact: true }).isVisible()).toBe(false) await touchTrigger.tap() await touchPage.getByRole('menu').waitFor() - await observe('touch-menu-open', true, true, touchRow) + await observe('touch-menu-open', true, true, touchRow, false) await touchPage.keyboard.press('Escape') - await observe('touch-menu-closed', true, true, touchRow) + await observe('touch-menu-closed', true, true, touchRow, false) await touchTrigger.tap() await touchPage.getByRole('menuitem', { name: 'Pin session', exact: true }).tap() - await touchRow.getByRole('img', { name: 'Pinned', exact: true }).waitFor() - await observe('touch-pinned', true, true, touchRow) + await touchRow.getByRole('button', { name: 'Unpin session', exact: true }).waitFor() + await observe('touch-pinned', true, true, touchRow, false) const touchBounds = await touchRow.evaluate((element) => { const title = element.querySelector('[class*="title"]')!.getBoundingClientRect() const resting = element.querySelector('[class*="rowResting"]')!.getBoundingClientRect() @@ -173,7 +176,7 @@ it('places dynamic Session menu rows by order among the shipped ones and removes expect(await row.evaluate(element => element === document.activeElement)).toBe(true) await observe('clicked-archived-row', true, false) await scaffold.ctx.workspaceRegistry.unarchiveSession(sessionId) - await observe('touch-unarchived', true, true, touchRow) + await observe('touch-unarchived', true, true, touchRow, false) expect(touchConsole.pageErrors).toEqual([]) } finally { await touchPage.close() @@ -193,13 +196,13 @@ it('places dynamic Session menu rows by order among the shipped ones and removes await row.hover() await trigger.click() await menu.waitFor() - const remainingNames = ['Pin session', 'Rename', 'Fork session', 'Archive session', 'Copy Session ID'] + const remainingNames = ['Pin session', 'Rename', 'Fork session', 'Copy Session ID', 'Archive session'] const remainingItems = menu.getByRole('menuitem') expect(await remainingItems.count()).toBe(remainingNames.length) for (const [index, name] of remainingNames.entries()) { expect(await remainingItems.nth(index).and(menu.getByRole('menuitem', { name, exact: true })).count()).toBe(1) } - expect(await menu.getByRole('separator').count()).toBe(0) + expect(await menu.getByRole('separator').count()).toBe(2) await page.context().grantPermissions(['clipboard-read', 'clipboard-write']) await menu.getByRole('menuitem', { name: 'Copy Session ID', exact: true }).click() await expect.poll(() => menu.count()).toBe(0) diff --git a/apps/web/tests/client-ui-stats-panel.e2e.ts b/apps/web/tests/client-ui-stats-panel.e2e.ts new file mode 100644 index 0000000000..fc0a51b3b5 --- /dev/null +++ b/apps/web/tests/client-ui-stats-panel.e2e.ts @@ -0,0 +1,160 @@ +// Keyless assembled-browser coverage for the opt-in Statistics view: the +// experimental client plugin is mounted only by the test overlay, so this Web +// composition is the package's user-visible evidence outside the jsdom lane. +import { fileURLToPath } from 'node:url' +import { join } from 'node:path' +import { readFileSync } from 'node:fs' +import type { Browser, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import * as yaml from 'js-yaml' +import { entryListSchema } from '@deepseek-ai/cordis-plugin-include' +import { + createAssistantMessage, createMessage, createUserMessage, ToolCallId, + type AssistantStreamRecord, type TokenUsage, +} from '@deepseek-ai/dsh-llm' +import { + assertFixtureInventory, captureStableAria, compareOrRefreshGolden, + launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { + connectFreshWorkspace, newEnglishPage, pinBrowserClock, pinHostClock, saveFailureShot, +} from './support.ts' + +const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/client-ui-stats-panel', import.meta.url)) +const PANEL_EXPECTED = join(SNAPSHOT_DIR, 'panel.expected.md') +const OVERLAY = fileURLToPath(new URL('./client-ui-stats-panel.overlay.yml', import.meta.url)) +const INSTALL_ANCHORS = [ + fileURLToPath(new URL('../../../packages/experimental/client-ui-stats/package.json', import.meta.url)), +] +const MODE = webSnapshotMode() + +/** Overlay layer entries, for the composition guard below. */ +function profileEntries(path: string): unknown[] { + const parsed = yaml.load(readFileSync(path, 'utf8'), { schema: entryListSchema }) + if (!Array.isArray(parsed)) throw new Error(`profile layer at ${path} must be a list`) + return parsed +} + +/** Usage one fixture assistant round reports. */ +const USAGE: TokenUsage = { + inputTokens: 1_200, + outputTokens: 240, + cacheReadTokens: 3_600, + cacheWriteTokens: 400, +} + +/** Compact stream whose first token arrives at the absolute Session time `firstTokenAt`. */ +function stream(firstTokenAt: number): AssistantStreamRecord[] { + return [{ type: 'text-chunks', time0: firstTokenAt, index: 0, dt: [200], texts: ['Ready.'] }] +} + +describe('Statistics view overlay', () => { + it('mounts the experimental client plugin over the shipped Web surface', () => { + expect(profileEntries(OVERLAY)).toEqual([{ + insert: [{ id: 'ui-client-ui-stats', name: '@deepseek-ai/dsh-experimental-client-ui-stats' }], + }]) + }) +}) + +describe('web e2e: Statistics view', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + let clock: ReturnType + + beforeAll(async () => { + clock = pinHostClock() + scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY, extraInstallAnchors: INSTALL_ANCHORS }) + browser = await chromium.launch() + page = await newEnglishPage(browser) + await pinBrowserClock(page) + tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + await connectFreshWorkspace(page, scaffold.workspaceCwd) + const agent = scaffold.ctx.agents.list()[0] + if (agent === undefined) throw new Error('connected workspace did not create an Agent') + agent.session.append('turn/start', { turn: 1 }) + agent.session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'Show the measured round.' }], + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + agent.session.append('step/start', { turn: 1, step: 1 }) + await new Promise((resolve) => { setTimeout(resolve, 60) }) + // Real timestamps: the compact stream's time0 is an absolute Session time, + // so the measured first token must sit between this step's start and the + // settled message, exactly as a live round records them. + const firstTokenAt = Date.now() - 10 + agent.session.append('assistant/message', { + turn: 1, + step: 1, + message: createAssistantMessage({ + content: [{ type: 'text', text: 'Ready.' }], + source: { provider: 'fixture', model: 'fixture' }, + }), + stream: stream(firstTokenAt), + usage: USAGE, + }, { surfaceOp: 'append' }) + agent.session.append('tool/call', { + turn: 1, + step: 1, + callId: ToolCallId('call-1'), + name: 'read', + arguments: JSON.stringify({ file_path: '/work/notes.md' }), + }) + agent.session.append('tool/result', { + turn: 1, + step: 1, + message: createMessage({ + role: 'tool', + content: [{ type: 'text', text: 'one\ntwo' }], + source: { kind: 'tool', callId: ToolCallId('call-1') }, + toolCallId: ToolCallId('call-1'), + }), + }, { surfaceOp: 'append' }) + agent.session.append('step/end', { turn: 1, step: 1 }) + agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + await scaffold.ctx.sessions.flush(agent.session) + await page.getByText('Ready.').waitFor({ timeout: 10_000 }) + }, 120_000) + + afterAll(async () => { + await browser?.close() + clock?.mockRestore() + await scaffold?.close() + }) + + it('renders the measured context, timing, cache, and tool columns', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-client-ui-stats-panel')) + await page.getByRole('tab', { name: 'Statistics', exact: true }).click() + const table = page.locator('table[aria-label="Statistics"]') + await table.waitFor({ timeout: 10_000 }) + expect(await table.getByRole('columnheader', { name: 'Context', exact: true }).count()).toBe(1) + expect(await table.getByRole('columnheader', { name: 'Output', exact: true }).count()).toBe(1) + expect(await table.getByRole('columnheader', { name: 'Cache hit', exact: true }).count()).toBe(1) + expect(await table.getByText('Turn 1', { exact: false }).count()).toBeGreaterThan(0) + expect(await table.getByText('Step 1', { exact: false }).count()).toBeGreaterThan(0) + expect(await table.getByText('read ×1', { exact: false }).count()).toBeGreaterThan(0) + // The measured columns carry the fixture's real accounting, and the timing + // columns are measured rather than the dash placeholder. Durations and the + // derived throughput/clock vary with the run, so the golden tokenizes them. + const cells = await table.locator('tbody tr').first().locator('td').allInnerTexts() + expect(cells[3]).toBe('5.2K') + expect(cells[4]).toBe('0.24K') + expect(cells[5]).toBe('69.23%') + expect(cells[6]).not.toBe('—') + expect(cells[8]).not.toBe('—') + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + const snapshot = await captureStableAria(page, 'table[aria-label="Statistics"]', scaffold.workspaceCwd, { + replacements: [[cells[6]!, '{{ttft}}'], [cells[8]!, '{{tps}}']], + }) + await compareOrRefreshGolden(PANEL_EXPECTED, snapshot, MODE) + }, 60_000) + + it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => { + await assertFixtureInventory(SNAPSHOT_DIR, ['panel.expected.md']) + }) +}) diff --git a/apps/web/tests/client-ui-stats-panel.overlay.yml b/apps/web/tests/client-ui-stats-panel.overlay.yml new file mode 100644 index 0000000000..7f55221244 --- /dev/null +++ b/apps/web/tests/client-ui-stats-panel.overlay.yml @@ -0,0 +1,7 @@ +# Test-only composition: mount the experimental @@STATSORMANCE@@ view beside Chat +# and Trajectory over the shipped Web surface. No shipped profile mounts this +# package (default-product isolation forbids it), so this overlay is the only +# real-Web composition that can render it. +- insert: + - id: ui-client-ui-stats + name: '@deepseek-ai/dsh-experimental-client-ui-stats' diff --git a/apps/web/tests/code-language.snapshot.ts b/apps/web/tests/code-language.snapshot.ts index 54abf83a52..038608a011 100644 --- a/apps/web/tests/code-language.snapshot.ts +++ b/apps/web/tests/code-language.snapshot.ts @@ -55,7 +55,7 @@ it('replays highlighted Python stubs, PowerShell and CSV reads with their docume await expandTurnProcesses(page) await page.locator('[data-sidebar-right-expand]').click() await page.locator('[data-sidebar-right-guide-entry="files"]').click() - const filesTab = page.locator('[data-dockkit-tab]').filter({ has: page.getByText('Files', { exact: true }) }) + const toggle = page.locator('[data-files-navigator-toggle]:visible') const preview = page.locator('[data-textpreview-url]') const snapshots: string[] = [] for (const file of FILES) { @@ -66,8 +66,10 @@ it('replays highlighted Python stubs, PowerShell and CSV reads with their docume await expect.poll(() => read.locator('[data-read] span[style*="color:"]').count()).toBeGreaterThan(0) expect(await read.getByText(file.lang, { exact: true }).count()).toBe(1) snapshots.push(`## Read ${file.name}\n\n${await captureStableAria(page, readSelector, scaffold.workspaceCwd)}`) - await filesTab.click() - await page.locator('[data-files-entry="file"]').getByRole('button', { name: file.name, exact: true }).click() + // The first file replaces the files page; later ones open from the pane's navigator. + // The files page always shows its tree and draws no toggle. + if (await toggle.count() > 0 && await toggle.getAttribute('aria-expanded') !== 'true') await toggle.click() + await page.locator('[data-files-navigator]:visible [data-files-entry="file"]').getByRole('button', { name: file.name, exact: true }).click() const viewer = preview.locator('[data-document-viewer-menu]') if (file.name === 'table.csv') { await expect.poll(() => viewer.innerText()).toBe('Spreadsheet') diff --git a/apps/web/tests/collapse-timing.e2e.ts b/apps/web/tests/collapse-timing.e2e.ts index a19b71192b..7d363a8dc4 100644 --- a/apps/web/tests/collapse-timing.e2e.ts +++ b/apps/web/tests/collapse-timing.e2e.ts @@ -3,7 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { basename, join } from 'node:path' import { fileURLToPath } from 'node:url' -import type { Browser, Page, Route } from 'playwright' +import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' import { deriveReplayScript } from '@deepseek-ai/dsh-llm-replay' @@ -146,34 +146,23 @@ describe.skipIf(MODE === 'record')('web e2e: recorded collapse timing', () => { const input = page.locator('[data-composer-input]').last() await writeComposerDraft(page, input, prompt) await expectProcess(1, true) + const resolved = await scaffold.ctx.sessionController.resolveAgent(SessionId(SEED_ID)) + if ('error' in resolved) throw resolved.error + // Maintenance keeps the accepted message in the inbox, so its echo stays before the Turn starts. const release = Promise.withResolvers() - const promptBlocked = Promise.withResolvers() - const holdPrompt = async (route: Route): Promise => { - promptBlocked.resolve(undefined) - await release.promise - await route.continue() - } - await page.route('**/api/session/prompt', holdPrompt) + const maintenance = resolved.agent.runMaintenance(() => release.promise) try { await page.getByRole('button', { name: 'Send message', exact: true }).click() - const blockedTimeout = setTimeout(() => { - promptBlocked.reject(new Error('session prompt did not reach the route barrier')) - }, UI_WAIT.timeout) - try { - await promptBlocked.promise - } finally { - clearTimeout(blockedTimeout) - } await expect.poll(() => page.locator('[data-submission-echo]').count(), UI_WAIT).toBe(1) await expectProcess(1, false) expect(await page.locator('[data-turn-process="2"]').count()).toBe(0) await capture('input-pending.expected.md') const settled = scaffold.whenTurnSettled() release.resolve(undefined) + await maintenance expect(await settled).toBe(SEED_ID) } finally { release.resolve(undefined) - await page.unrouteAll({ behavior: 'wait' }) } await expect.poll(() => page.getByText('DONE', { exact: true }).count(), UI_WAIT).toBe(2) await expect.poll(() => page.locator('[data-streaming="true"]').count(), UI_WAIT).toBe(0) diff --git a/apps/web/tests/context-menus.e2e.ts b/apps/web/tests/context-menus.e2e.ts new file mode 100644 index 0000000000..0cc7a7abf8 --- /dev/null +++ b/apps/web/tests/context-menus.e2e.ts @@ -0,0 +1,406 @@ +/** Context gestures against built plugins, seeded Sessions, and original files. */ +import { mkdir, readFile, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { chromium, type Browser, type Locator, type Page } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed, vi } from 'vitest' +import { createLaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment' +import { createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm' +import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session' +import type {} from '@deepseek-ai/dsh-session-title' +import { launchWebScaffold, seedSession, watchConsole, type WebScaffold } from './scaffold.ts' +import { saveFailureShot } from './support.ts' + +const GIF = Buffer.from('R0lGODdhMAAgAIEAAEtu5gAAAAAAAAAAACwAAAAAMAAgAEAIQQABCBxIsKDBgwgTKlzIsKHDhxAjSpxIsaLFixgzatzIsaPHjyBDihxJsqTJkyhTqlzJsqXLlzBjypxJs6bNmQEBADs=', 'base64') +async function menuLabels(menu: Locator): Promise { + return menu.getByRole('menuitem').evaluateAll(items => items.map((item) => { + const copy = item.cloneNode(true) as HTMLElement + for (const decoration of copy.querySelectorAll('[aria-hidden="true"]')) decoration.remove() + return copy.textContent ?? '' + })) +} +function fixture(title: string): string { + const session = Session.create(SessionId('context-menus-source')) + session.append('turn/start', { turn: 1 }) + const user = session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'Show the output.' }], source: { kind: 'user' } }), { surfaceOp: 'append' }) + session.append('session/title', { title, messageSeqs: [user.seq], source: { kind: 'fallback' } }) + session.append('step/start', { turn: 1, step: 1 }) + session.append('assistant/message', { stream: [], turn: 1, step: 1, message: createAssistantMessage({ + content: [{ type: 'text', text: '[First file](first.txt#L2) [Second file](second.txt) [Website](https://example.com/path?q=1#fragment)\n\n![Original](original.gif) ![Remote](https://images.example/original.gif)\n\nCONTEXT_MENU_READY' }], + source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' }, + }) }, { surfaceOp: 'append' }) + session.append('step/end', { turn: 1, step: 1 }) + session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + return [JSON.stringify({ type: 'session', version: SESSION_FORMAT_VERSION, id: '{{sessionId}}', createdAt: 0, cwd: '{{cwd}}', isSeeded: false, delegationDepth: 0 }), + ...session.snapshotEvents().map(event => JSON.stringify({ ...event, time: 1_000 + event.seq * 1_000 })), ''].join('\n') +} + +describe.each(['MacIntel', 'Win32', 'Linux x86_64'])('web context menus on %s', (platform) => { + let scaffold: WebScaffold, browser: Browser, page: Page + let tripwire: ReturnType + beforeAll(async () => { + scaffold = await launchWebScaffold({ openInAppEnvironment: createLaunchEnvironmentSnapshot([{ source: 'process', values: { SSH_CONNECTION: '10.0.0.2 55000 10.0.0.9 22' } }]) }) + await mkdir(join(scaffold.workspaceCwd, 'folder')) + await scaffold.ctx.workspaceRegistry.create(join(scaffold.workspaceCwd, 'folder'), 'Menu workspace') + await writeFile(join(scaffold.workspaceCwd, 'first.txt'), 'FIRST\nSECOND\nTHIRD\n') + await writeFile(join(scaffold.workspaceCwd, 'second.txt'), 'SECOND FILE\n') + await writeFile(join(scaffold.workspaceCwd, 'original.gif'), GIF) + await seedSession(scaffold, fixture('Menu foreground'), 'context-menu-first') + await seedSession(scaffold, fixture('Menu background'), 'context-menu-other') + browser = await chromium.launch() + const context = await browser.newContext({ viewport: { width: 1680, height: 1000 }, locale: 'en-US', timezoneId: 'Asia/Shanghai' }) + await context.addInitScript((value) => { Object.defineProperty(navigator, 'platform', { value }) }, platform) + page = await context.newPage() + await page.setViewportSize({ width: 1291, height: 768 }) + tripwire = watchConsole(page) + await page.route('https://images.example/original.gif', route => route.fulfill({ body: GIF, contentType: 'image/gif', headers: { 'access-control-allow-origin': '*' } })) + await page.context().grantPermissions(['clipboard-read', 'clipboard-write']) + await page.goto(scaffold.authenticatedUrl) + await page.locator('[data-row-key^="workspace:"]').filter({ hasText: 'Ungrouped' }).click() + await page.locator('[data-row-key="session:context-menu-other"]').click() + await page.locator('[data-row-key="session:context-menu-other"]').getByText('Menu background', { exact: true }).waitFor() + await page.locator('[data-row-key="session:context-menu-first"]').click() + await page.getByText('CONTEXT_MENU_READY', { exact: true }).waitFor() + }) + afterAll(async () => { await browser?.close(); await scaffold?.close() }) + + it('shares Session entries without selecting the background Session, and dismisses at viewport edges', async () => { + onTestFailed(() => saveFailureShot(page, 'context-menus-session')) + const background = page.locator('[data-row-key="session:context-menu-other"]') + await background.click({ button: 'right' }) + const menu = page.getByRole('menu') + await menu.getByRole('menuitem', { name: /Copy.*[Ii][Dd]/ }).waitFor() + const names = await menuLabels(menu) + expect(names.slice(0, 5)).toEqual(['Pin session', 'Rename', 'Fork session', 'Copy Session ID', 'Show in folder']) + expect(names.at(-1)).toBe('Archive session') + expect(await menu.getByRole('menuitem').evaluateAll(rows => rows.every(row => row.querySelector('svg[data-icon]')))).toBe(true) + expect(await menu.getByRole('separator').count()).toBe(2) + expect(await menu.getByRole('menuitem', { name: 'Archive session', exact: true }).evaluate(row => + getComputedStyle(row.parentElement!.parentElement!).borderTopWidth)).toBe('0px') + const alignedSeparators = async () => { + const bounds = await menu.evaluate((node) => { + const row = node.querySelector('[role="menuitem"]')! + const rect = row.getBoundingClientRect() + const style = getComputedStyle(row) + return { + left: rect.left + Number.parseFloat(style.paddingLeft), + right: rect.right - Number.parseFloat(style.paddingRight), + lines: [...node.querySelectorAll('[role="separator"]')].map((line) => { + const rect = line.getBoundingClientRect() + return { left: rect.left, right: rect.right } + }), + } + }) + for (const line of bounds.lines) { + expect(line.left).toBeCloseTo(bounds.left, 1) + expect(line.right).toBeCloseTo(bounds.right, 1) + } + } + await alignedSeparators() + await expect(names.join('\n') + '\n').toMatchFileSnapshot(join(import.meta.dirname, 'expected/context-menus/session.txt')) + expect(names.some(name => name.includes('Rename'))).toBe(true) + expect(await background.getAttribute('aria-selected')).toBe('false') + await page.keyboard.press('Escape') + await background.getByRole('button', { name: /actions/i }).click() + await menu.getByRole('menuitem', { name: /Copy.*[Ii][Dd]/ }).waitFor() + expect(await menuLabels(menu)).toEqual(names) + await alignedSeparators() + await background.getByRole('button', { name: /actions/i }).click() + expect(await menu.count()).toBe(0) + expect(await background.getAttribute('aria-selected')).toBe('false') + }) + + it('updates an open Session menu from another window’s shortcut preferences and still renames the captured row', async () => { + onTestFailed(() => saveFailureShot(page, 'context-menus-live-shortcuts')) + const other = await page.context().newPage() + const key = 'dsh.keybindings.v1' + const original = await page.evaluate(key => localStorage.getItem(key), key) + try { + await other.goto(scaffold.authenticatedUrl) + await other.getByRole('button', { name: 'Search sessions', exact: true }).waitFor() + const background = page.locator('[data-row-key="session:context-menu-other"]') + await background.click({ button: 'right' }) + const item = page.getByRole('menuitem', { name: 'Rename', exact: true }) + await item.waitFor() + const popup = await page.getByRole('menu').elementHandle() + const initial = await item.getAttribute('aria-keyshortcuts') + await other.evaluate((key) => { + localStorage.setItem(key, JSON.stringify({ schemaVersion: 2, profiles: { + 'web:macos': { 'session.rename': { code: 'Comma', modifiers: ['primary', 'shift'] } }, + 'web:windows': { 'session.rename': { code: 'Comma', modifiers: ['primary', 'shift'] } }, + 'web:linux': { 'session.rename': { code: 'Comma', modifiers: ['primary', 'shift'] } }, + } })) + }, key) + await expect.poll(() => item.getAttribute('aria-keyshortcuts')).toBe(platform === 'MacIntel' ? 'Shift+Meta+,' : 'Control+Shift+,') + expect(await item.getAttribute('aria-keyshortcuts')).not.toBe(initial) + expect(await popup!.evaluate(element => element.isConnected)).toBe(true) + expect(await background.getAttribute('aria-selected')).toBe('false') + await item.click() + const rename = page.getByRole('dialog', { name: 'Rename session', exact: true }) + expect(await rename.getByLabel('Session name').inputValue()).toBe('Menu background') + await rename.getByRole('button', { name: 'Cancel', exact: true }).click() + expect(await background.getAttribute('aria-selected')).toBe('false') + await background.click({ button: 'right' }) + await item.waitFor() + await other.evaluate((key) => { + localStorage.setItem(key, JSON.stringify({ schemaVersion: 2, profiles: { + 'web:macos': { 'session.rename': null }, 'web:windows': { 'session.rename': null }, 'web:linux': { 'session.rename': null }, + } })) + }, key) + await expect.poll(() => item.getAttribute('aria-keyshortcuts')).toBeNull() + await other.evaluate(({ key, original }) => { + if (original === null) localStorage.removeItem(key) + else localStorage.setItem(key, original) + }, { key, original }) + await expect.poll(() => item.getAttribute('aria-keyshortcuts')).toBe(initial) + await page.keyboard.press('Escape') + } finally { + const cancel = page.getByRole('dialog', { name: 'Rename session', exact: true }).getByRole('button', { name: 'Cancel', exact: true }) + if (await cancel.isVisible()) await cancel.click() + await page.keyboard.press('Escape') + await other.evaluate(({ key, original }) => { + if (original === null) localStorage.removeItem(key) + else localStorage.setItem(key, original) + }, { key, original }) + await other.close() + } + }) + + it('shares Workspace menus and keeps folder gestures independent from expansion', async () => { + onTestFailed(() => saveFailureShot(page, 'context-menus-workspace')) + const workspace = page.locator('[data-row-key^="workspace:"]').filter({ hasText: 'Menu workspace' }) + const expanded = await workspace.getAttribute('aria-expanded') + await workspace.click({ button: 'right' }) + const menu = page.getByRole('menu') + await menu.getByRole('menuitem', { name: 'Rename', exact: true }).waitFor() + const names = await menuLabels(menu) + expect(names).toEqual(['Rename', 'Show in folder', 'Delete workspace']) + expect(await menu.locator('svg[data-icon]').count()).toBe(3) + expect(await workspace.getAttribute('aria-expanded')).toBe(expanded) + await page.keyboard.press('Escape') + await workspace.getByRole('button', { name: /actions/i }).click() + await menu.getByRole('menuitem', { name: 'Rename', exact: true }).waitFor() + expect(await menuLabels(menu)).toEqual(names) + await menu.getByRole('menuitem', { name: 'Rename', exact: true }).click() + await page.getByRole('dialog').waitFor() + await page.getByRole('button', { name: 'Cancel', exact: true }).click() + await workspace.click({ button: 'right' }) + await menu.getByRole('menuitem', { name: 'Delete workspace', exact: true }).click() + await page.getByRole('dialog', { name: 'Delete workspace', exact: true }).waitFor() + await page.getByRole('button', { name: 'Cancel', exact: true }).click() + await page.locator('[data-sidebar-right-expand]').click() + await page.locator('[data-sidebar-right-guide-entry="files"]').click() + await page.locator('[data-files-state="tree"]').waitFor() + const folder = page.locator('[data-files-entry="directory"]').filter({ hasText: 'folder' }).getByRole('button').first() + await folder.click({ button: 'right' }) + await menu.getByRole('menuitem', { name: 'Copy folder path', exact: true }).waitFor() + expect(await menuLabels(menu)).toEqual(['Show in folder', 'Copy folder path']) + expect(await folder.getAttribute('aria-expanded')).toBe('false') + await menu.getByRole('menuitem', { name: 'Copy folder path', exact: true }).click() + expect(await page.evaluate(() => navigator.clipboard.readText())).toBe(join(scaffold.workspaceCwd, 'folder')) + await page.getByText('Copied', { exact: true }).waitFor() + await expect(names.join('\n') + '\n').toMatchFileSnapshot(join(import.meta.dirname, 'expected/context-menus/workspace.txt')) + }) + + it('prepares complete menus, anchors above the frame inset, and treats repeated gestures as separate occurrences', async () => { + onTestFailed(() => saveFailureShot(page, 'context-menus-gestures')) + const file = page.getByRole('button', { name: 'First file', exact: true }) + await file.focus() + await page.keyboard.press('Shift+F10') + await page.getByRole('menuitem', { name: 'Copy file path', exact: true }).waitFor() + await page.keyboard.press('End') + expect(await page.getByRole('menuitem', { name: 'Save as…', exact: true }).count()).toBe(0) + expect(await page.getByRole('menuitem', { name: 'Download', exact: true }).evaluate(element => element === document.activeElement)).toBe(true) + await page.keyboard.press('ArrowUp') + expect(await page.getByRole('menuitem', { name: 'Copy file path', exact: true }).evaluate(element => element === document.activeElement)).toBe(true) + await page.keyboard.press('Enter') + await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe(join(scaffold.workspaceCwd, 'first.txt')) + expect(await file.evaluate(element => element === document.activeElement)).toBe(true) + await page.evaluate(() => { + document.documentElement.style.setProperty('--dsh-frame-overlay-top', '100px') + const frames: number[] = [] + const observer = new MutationObserver(() => { + for (const menu of document.querySelectorAll('[role="menu"]')) frames.push(menu.querySelectorAll('[role="menuitem"]').length) + }) + observer.observe(document.body, { subtree: true, childList: true }) + Object.assign(window, { menuObservation: { frames, observer } }) + }) + const header = page.locator('[data-session-title]').first() + const target = await header.count() > 0 ? header : page.getByText('Menu foreground', { exact: true }).last() + const box = (await target.boundingBox())! + const point = { x: box.x + box.width / 2, y: box.y + box.height / 2 } + await page.mouse.click(point.x, point.y, { button: 'right' }) + await page.getByRole('menuitem', { name: /Copy.*[Ii][Dd]/ }).waitFor() + expect((await page.getByRole('menu').boundingBox())!.y).toBeLessThan(100) + await page.mouse.click(point.x + 1, point.y, { button: 'right' }) + expect(await page.getByRole('menu').count()).toBe(0) + await file.click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Copy file path', exact: true }).waitFor() + const previous = await page.getByRole('menu').elementHandle() + await page.getByRole('link', { name: 'Website', exact: true }).click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Copy link address', exact: true }).waitFor() + expect(await previous!.evaluate(element => element.isConnected)).toBe(false) + await page.keyboard.press('Escape') + const counts = await page.evaluate(() => { + const observed = (window as Window & { menuObservation?: { frames: number[]; observer: MutationObserver } }).menuObservation + if (observed === undefined) throw new Error('Menu observer not installed') + observed.observer.disconnect() + document.documentElement.style.removeProperty('--dsh-frame-overlay-top') + return observed.frames + }) + expect(counts.length).toBeGreaterThan(0) + expect(counts.every(count => count > 0)).toBe(true) + }) + + it('preserves file line navigation, URL text, image format, and existing tab close actions', async () => { + onTestFailed(() => saveFailureShot(page, 'context-menus-content')) + const file = page.getByRole('button', { name: 'First file', exact: true }) + await file.click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Download', exact: true }).waitFor() + expect(await page.getByRole('menuitem', { name: 'Save as…', exact: true }).count()).toBe(0) + const fileDownloadPromise = page.waitForEvent('download') + await page.getByRole('menuitem', { name: 'Download', exact: true }).click() + const fileDownload = await fileDownloadPromise + expect(fileDownload.suggestedFilename()).toBe('first.txt') + expect(await readFile(await fileDownload.path(), 'utf8')).toBe('FIRST\nSECOND\nTHIRD\n') + const started = page.getByRole('alert').filter({ hasText: 'Download started' }) + await started.waitFor() + expect(await started.getByRole('button', { name: /Show in/ }).count()).toBe(0) + await file.click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Open in sidebar', exact: true }).click() + await page.locator('[data-document-preview]').getByText('SECOND', { exact: true }).waitFor() + // The same link moves that tab into a floating panel and back, delivering its line each time. + const floating = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]') + const dockedFirst = page.locator('[data-rightbar-col] [data-dockkit-pane] [data-dockkit-tab]', { hasText: 'first.txt' }) + await file.click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Open in floating panel', exact: true }).click() + await expect.poll(() => floating.count()).toBe(1) + await floating.locator('[data-textpreview-target="2"]', { hasText: 'SECOND' }).waitFor() + await expect.poll(() => dockedFirst.count()).toBe(0) + // The new panel covers the link, so the keyboard raises its menu. + await file.focus() + await page.keyboard.press('Shift+F10') + await page.getByRole('menuitem', { name: 'Open in floating panel', exact: true }).click() + await floating.locator('[data-textpreview-target="2"]').waitFor() + expect(await floating.count()).toBe(1) + await file.focus() + await page.keyboard.press('Shift+F10') + await page.getByRole('menuitem', { name: 'Open in sidebar', exact: true }).click() + await expect.poll(() => floating.count()).toBe(0) + await expect.poll(() => dockedFirst.count()).toBe(1) + await page.locator('[data-rightbar-col] [data-textpreview-target="2"]').waitFor() + await page.getByRole('link', { name: 'Website', exact: true }).click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Copy link address', exact: true }).click() + expect(await page.evaluate(() => navigator.clipboard.readText())).toBe('https://example.com/path?q=1#fragment') + await page.getByRole('img', { name: 'Original', exact: true }).click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Download', exact: true }).waitFor() + await expect((await menuLabels(page.getByRole('menu'))).join('\n') + '\n') + .toMatchFileSnapshot(join(import.meta.dirname, 'expected/context-menus/image.txt')) + expect(await page.getByRole('menuitem', { name: 'Show in folder', exact: true }).count()).toBe(1) + const downloadPromise = page.waitForEvent('download') + await page.getByRole('menuitem', { name: 'Download', exact: true }).click() + const download = await downloadPromise + expect(download.suggestedFilename().endsWith('.gif')).toBe(true) + await page.getByRole('alert').filter({ hasText: 'Download started' }).waitFor() + const path = await download.path() + expect(path).not.toBeNull() + if (path === null) throw new Error('Browser download unavailable') + expect(await readFile(path)).toEqual(GIF) + await page.getByRole('img', { name: 'Original', exact: true }).click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Copy image', exact: true }).click() + await page.getByText('Copied', { exact: true }).waitFor() + expect(await page.evaluate(async () => (await navigator.clipboard.read()).some(item => item.types.includes('image/png')))).toBe(true) + await page.getByRole('img', { name: 'Remote', exact: true }).click({ button: 'right' }) + expect(await page.getByRole('menuitem', { name: 'Show in folder', exact: true }).isDisabled()).toBe(true) + const remoteDownloadPromise = page.waitForEvent('download') + await page.getByRole('menuitem', { name: 'Download', exact: true }).click() + const remoteDownload = await remoteDownloadPromise + expect(await readFile((await remoteDownload.path()))).toEqual(GIF) + await page.getByRole('img', { name: 'Remote', exact: true }).click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Copy image', exact: true }).click() + await page.getByText('Copied', { exact: true }).waitFor() + expect(await page.evaluate(async () => (await navigator.clipboard.read()).some(item => item.types.includes('image/png')))).toBe(true) + await page.getByRole('button', { name: 'Second file', exact: true }).click() + await page.locator('[data-document-preview]').getByText('SECOND FILE', { exact: true }).waitFor() + const firstTab = page.locator('[role="tab"]').filter({ hasText: 'first.txt' }).first() + await firstTab.click({ button: 'right' }) + await page.getByRole('menuitem', { name: 'Close', exact: true }).waitFor() + expect(await page.getByRole('menuitem', { name: 'Close', exact: true }).locator('svg[data-icon]').count()).toBe(1) + await page.getByRole('menuitem', { name: 'Close', exact: true }).click() + expect(await firstTab.count()).toBe(0) + expect(await page.locator('[data-document-preview]').getByText('SECOND FILE', { exact: true }).count()).toBe(1) + expect(tripwire.pageErrors).toEqual([]) + }) + it('keeps original preview open when dismissing its menu and fits both themes at the viewport edge', async () => { + onTestFailed(() => saveFailureShot(page, 'context-menus-preview')) + await page.getByRole('button', { name: 'View full image: Original', exact: true }).click() + const preview = page.getByRole('dialog') + await preview.waitFor() + for (const colorScheme of ['light', 'dark'] as const) { + await page.emulateMedia({ colorScheme }) + await preview.getByRole('img').evaluate(element => element.dispatchEvent(new MouseEvent('contextmenu', { clientX: 1270, clientY: 735, bubbles: true }))) + const menu = page.getByRole('menu') + await menu.getByRole('menuitem', { name: 'Copy image', exact: true }).waitFor() + expect(await menu.getByRole('menuitem').evaluateAll(rows => rows.every(row => row.querySelector('svg[data-icon]')))).toBe(true) + const box = await menu.boundingBox() + expect(box).not.toBeNull() + expect(box!.x).toBeGreaterThan(1000) + expect(box!.y).toBeGreaterThan(500) + expect(box!.x + box!.width).toBeLessThanOrEqual(1291) + expect(box!.y + box!.height).toBeLessThanOrEqual(768) + await saveFailureShot(page, `context-menus-${colorScheme}`) + await page.keyboard.press('Escape') + expect(await menu.count()).toBe(0) + expect(await preview.count()).toBe(1) + } + await page.keyboard.press('Escape') + expect(await preview.count()).toBe(0) + expect(tripwire.pageErrors).toEqual([]) + }) + + it('offers completed Desktop destinations as toast text actions without enabling remote-image menu reveal', async () => { + const native = await browser.newPage({ viewport: { width: 1291, height: 768 }, locale: 'en-US' }) + const opened = vi.spyOn(scaffold.ctx.sessionController, 'openWorkspacePath').mockResolvedValue({ opened: true }) + try { + const destinations = { download: join(scaffold.workspaceCwd, 'downloaded.gif'), saveAs: join(scaffold.workspaceCwd, 'saved.txt') } + await native.addInitScript(({ platform, destinations }) => { + Object.defineProperty(navigator, 'platform', { value: platform }) + Object.defineProperty(globalThis, 'dshDesktop', { value: { protocolVersion: 1, fileActions: { + save: async ({ mode }: { mode: 'download' | 'saveAs' }) => ({ status: 'saved', path: destinations[mode] }), + } } }) + }, { platform, destinations }) + await native.route('https://images.example/original.gif', route => route.fulfill({ body: GIF, contentType: 'image/gif' })) + await native.goto(scaffold.authenticatedUrl) + await native.evaluate((platform) => { + document.documentElement.dataset.platform = platform === 'MacIntel' ? 'darwin' : platform === 'Win32' ? 'win32' : 'linux' + }, platform) + const group = native.locator('[data-row-key^="workspace:"]').filter({ hasText: 'Ungrouped' }) + if (await group.getAttribute('aria-expanded') !== 'true') await group.click() + await native.locator('[data-row-key="session:context-menu-first"]').click() + await native.getByText('CONTEXT_MENU_READY', { exact: true }).waitFor() + for (const [mode, label, text, theme] of [ + ['download', 'Download', 'Download complete', 'light'], + ['saveAs', 'Save as…', 'Saved', 'dark'], + ] as const) { + await native.emulateMedia({ colorScheme: theme }) + const trigger = mode === 'download' + ? native.getByRole('img', { name: 'Remote', exact: true }) + : native.getByRole('button', { name: 'First file', exact: true }) + await trigger.click({ button: 'right' }) + await native.getByRole('menuitem', { name: label, exact: true }).click() + const notice = native.getByRole('alert').filter({ hasText: text }) + const action = notice.getByRole('button', { name: platform === 'MacIntel' ? 'Show in Finder' : 'Show in folder', exact: true }) + await action.click() + await notice.waitFor({ state: 'hidden' }) + await expect.poll(() => opened.mock.calls.at(-1)?.[0]).toEqual({ path: destinations[mode], action: 'reveal' }) + } + expect(opened).toHaveBeenCalledTimes(2) + await native.getByRole('img', { name: 'Remote', exact: true }).click({ button: 'right' }) + const reveal = native.getByRole('menuitem', { name: 'Show in folder', exact: true }) + await reveal.waitFor() + expect(await reveal.isDisabled()).toBe(true) + } finally { + await native.close() + opened.mockRestore() + } + }) +}) diff --git a/apps/web/tests/cot-translation-paid.e2e.ts b/apps/web/tests/cot-translation-paid.e2e.ts index f8afb08a67..37c2199298 100644 --- a/apps/web/tests/cot-translation-paid.e2e.ts +++ b/apps/web/tests/cot-translation-paid.e2e.ts @@ -196,7 +196,7 @@ it.skipIf(MODE === 'record')('reuses saved native Account Flash translations acr await panel.getByText(`v${bundleVersion}`, { exact: true }).waitFor() await panel.getByText(bundleVersion, { exact: true }).waitFor() // The bundle's detail document is shown between its components and its source. - await panel.locator('[data-detail-document]').getByRole('heading', { name: '使用方法', exact: true }).waitFor() + await panel.locator('[data-detail-document]').getByRole('img', { name: '展开的思考行从英文翻译成中文，并显示“查看原文”按钮', exact: true }).waitFor() await compareOrRefreshGolden(join(EXPECTED, 'paid-choices.expected.md'), await captureStableAria(settings, '[data-plugin-panel]', scaffold.workspaceCwd, { replacements: [[BUNDLE, '{{bundle}}'], [bundleVersion, '{{version}}']], diff --git a/apps/web/tests/cot-translation.e2e.ts b/apps/web/tests/cot-translation.e2e.ts index cf10562c90..c4db45b575 100644 --- a/apps/web/tests/cot-translation.e2e.ts +++ b/apps/web/tests/cot-translation.e2e.ts @@ -213,7 +213,7 @@ it.skipIf(MODE === 'record')('persists Bing reasoning translation across reopen await panel.getByText(`v${bundleVersion}`, { exact: true }).waitFor() await panel.getByText(bundleVersion, { exact: true }).waitFor() // The bundle's detail document is shown between its components and its source. - await panel.locator('[data-detail-document]').getByRole('heading', { name: '使用方法', exact: true }).waitFor() + await panel.locator('[data-detail-document]').getByRole('img', { name: '展开的思考行从英文翻译成中文，并显示“查看原文”按钮', exact: true }).waitFor() await compareOrRefreshGolden(join(EXPECTED, 'preferences.expected.md'), await captureStableAria(settings, '[data-plugin-panel]', scaffold.workspaceCwd, { replacements: [[BUNDLE, '{{bundle}}'], [bundleVersion, '{{version}}']], diff --git a/apps/web/tests/cua-optin.e2e.ts b/apps/web/tests/cua-optin.e2e.ts index 879864eaf7..d1962da38b 100644 --- a/apps/web/tests/cua-optin.e2e.ts +++ b/apps/web/tests/cua-optin.e2e.ts @@ -1,5 +1,5 @@ -/** Optional CUA uses existing plugin activation and offers a separate persistent PTC action. */ -import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +/** CUA follows PTC Agent scopes and changes the default only from its detail page. */ +import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' @@ -8,45 +8,46 @@ import { readProfileManifest } from '@deepseek-ai/dsh-app-boot' import { SessionId } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-ptc-runtime' import type {} from '@deepseek-ai/dsh-agent-preset-registry' +import { load } from 'js-yaml' import { expect, it, vi } from 'vitest' import { captureStableAria, compareOrRefreshGolden, launchWebScaffold, webSnapshotMode, type WebScaffold } from './scaffold.ts' import { connectFreshWorkspaceZh, ZH_BROWSER_LOCALE } from './support.ts' // The shipped bundle admits only macOS Hosts; unsupported Hosts are exercised in bundle-platform.e2e.ts. -it.skipIf(process.platform !== 'darwin').each([undefined, 'minimal'] as const)('adds CUA to PTC sessions while preserving default %s until the explicit persistent-runtime action', async (selectedDefault) => { +it.skipIf(process.platform !== 'darwin').each([ + { selectedDefault: undefined, codingTools: false, script: false }, + { selectedDefault: undefined, codingTools: true, script: false }, + { selectedDefault: 'minimal', codingTools: true, script: false }, + { selectedDefault: undefined, codingTools: true, script: true }, +] as const)('preserves Coding Tools=$codingTools and default=$selectedDefault and Script=$script across CUA toggles', async ({ selectedDefault, codingTools, script }) => { const directory = await mkdtemp(join(tmpdir(), 'cua-optin-web-')) let ownedScaffold: WebScaffold | undefined let browser: Browser | undefined try { const patch = join(directory, 'native-fixture.yml') - // The executable cannot answer native permission queries, so setup must offer retry in the detail page. - await writeFile(patch, JSON.stringify([{ id: 'cua', disabled: false, config: { helperPath: process.execPath } }])) - // Install the test provider explicitly so the helper override also exercises session wiring on Linux. + // Permission inspection fails against this non-helper executable; activation still permits dismissing setup. + await writeFile(patch, JSON.stringify([{ id: 'cua', config: { helperPath: process.execPath } }])) + const defaults = join(directory, 'script-defaults') + if (script) { + await mkdir(defaults) + await writeFile(join(defaults, 'package.json'), JSON.stringify({ name: 'cua-script-defaults', version: '1.0.0', dsh: { bundle: { patch: 'cordis.patch.yml' } } })) + await writeFile(join(defaults, 'cordis.patch.yml'), '- id: ptc-runtime\n config:\n executionMode: vm-script\n scriptPersistence: false\n') + } + const harnessHome = join(directory, 'home') const scaffold = ownedScaffold = await launchWebScaffold({ - profile: { packages: [{ dir: fileURLToPath(new URL('../../../packages/experimental/cua-macos', import.meta.url)), enabled: false }] }, - harnessHome: join(directory, 'home'), extraOverlayPath: [ + profile: { packages: script ? [{ dir: defaults, enabled: true }] : [] }, + harnessHome, extraOverlayPath: [ fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), patch, ] }) const initialDefault = selectedDefault ?? 'standard' if (selectedDefault !== undefined) await scaffold.ctx.settings.update('agent-preset-registry', { selectedDefault }) + await scaffold.ctx.settings.update('ui-settings', { enabled: codingTools }) + const settingsPath = join(harnessHome, 'profiles/scaffold/cordis.patch.yml') + const beforeEnable = await readFile(settingsPath, 'utf8') browser = await chromium.launch() const page = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE }) - await page.goto(scaffold.authenticatedUrl) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) await connectFreshWorkspaceZh(page, scaffold.workspaceCwd) - const originalAgent = scaffold.ctx.agents.list()[0]! - const ptcAgent = (await scaffold.ctx.agents.create({ sessionId: SessionId('cua-existing-ptc'), - setup: async (ctx) => { await scaffold.ctx.agentPresets.mount(ctx, 'ptc') }, - })).agent - const runtimeFiber = () => [...scaffold.ctx.loader.entries()].find(entry => entry.options.id === 'ptc-runtime')?.fiber - const originalRuntime = scaffold.ctx.ptcRuntime - const originalRuntimeFiber = runtimeFiber() - expect(originalRuntimeFiber).toBeDefined() - expect(scaffold.ctx.ptcRuntime.programFormat).toBe('function-body') - const settingsPath = join(scaffold.harnessHome, 'profiles/scaffold/cordis.patch.yml') - const before = await readFile(settingsPath, 'utf8') - const profileManifest = () => readProfileManifest('scaffold', join(scaffold.harnessHome, 'profiles/scaffold')) - const selected = () => profileManifest().dsh?.profile?.bundles - const dependencies = profileManifest().dependencies await page.getByRole('navigation', { name: '全局面板' }).getByRole('button', { name: '插件', exact: true }).click() const plugins = page.locator('[data-plugin-panel]') await plugins.getByRole('button', { name: '更多', exact: true }).waitFor() @@ -62,13 +63,31 @@ it.skipIf(process.platform !== 'darwin').each([undefined, 'minimal'] as const)(' const dialog = page.getByRole('dialog', { name: '添加插件', exact: true }) await dialog.getByRole('textbox', { name: '包名或地址', exact: true }).fill('@deepseek-ai/dsh-cua-bundle') await dialog.getByRole('button', { name: '安装', exact: true }).click() - const ready = page.getByRole('dialog', { name: '插件已随 DSH 提供', exact: true }) + const ready = page.getByRole('dialog', { name: '已安装', exact: true }) await ready.waitFor() - expect(await ready.getByText('无需下载，启用即可使用', { exact: true }).count()).toBe(1) + expect(await ready.getByText('无需下载，启用即可使用', { exact: true }).count()).toBe(0) return ready.getByRole('button', { name: '立即启用', exact: true }) } const enableNow = await offerCua() - const toggle = card.getByRole('switch', { name: '启用 Computer Use', exact: true }) + let toggle = card.getByRole('switch', { name: '启用 Computer Use', exact: true }) + const originalAgent = scaffold.ctx.agents.list()[0]! + const ptcAgent = (await scaffold.ctx.agents.create({ + sessionId: SessionId('cua-existing-ptc'), + setup: async (ctx) => { await scaffold.ctx.agentPresets.mount(ctx, 'ptc') }, + })).agent + expect(scaffold.ctx.tools.schemas(ptcAgent).some(tool => tool.name === 'cua')).toBe(false) + const runtimeFiber = () => [...scaffold.ctx.loader.entries()].find(entry => entry.options.id === 'ptc-runtime')?.fiber + const originalRuntimeFiber = runtimeFiber() + expect(originalRuntimeFiber).toBeDefined() + const originalRuntime = scaffold.ctx.ptcRuntime + expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) + expect(originalRuntime.programFormat).toBe(script ? 'script' : 'function-body') + expect(scaffold.ctx.get('computerUse')).toBeUndefined() + const profileManifest = () => readProfileManifest('scaffold', join(scaffold.harnessHome, 'profiles/scaffold')) + const selected = () => profileManifest().dsh?.profile?.bundles + const dependencies = profileManifest().dependencies + expect(selected()).not.toContain('@deepseek-ai/dsh-cua-bundle') + const enabling = Promise.withResolvers() const setEnabled = scaffold.ctx.pluginManager.setBundleEnabled.bind(scaffold.ctx.pluginManager) let applying: ReturnType | undefined @@ -95,76 +114,148 @@ it.skipIf(process.platform !== 'darwin').each([undefined, 'minimal'] as const)(' const setup = page.getByRole('dialog', { name: '使用 Computer Use 前需要设置', exact: true }) await setup.waitFor() expect(await setup.getByText('Computer Use 插件已开启，但暂时无法检测系统权限。请前往插件详情页查看原因并重试。', { exact: true }).count()).toBe(1) - await setup.getByRole('button', { name: '稍后', exact: true }).click() + await compareOrRefreshGolden(fileURLToPath(new URL('./expected/cua-permissions/setup.expected.md', import.meta.url)), + await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd), webSnapshotMode()) + expect(await setup.getByRole('button', { name: '设为 PTC', exact: true }).count()).toBe(0) + expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) expect(selected()).toContain('@deepseek-ai/dsh-cua-bundle') expect(profileManifest().dependencies).toEqual(dependencies) expect(await card.getByText('实验性', { exact: true }).count()).toBe(1) + expect(await card.textContent()).not.toContain('将 PTC 模式改为可持久化') expect(await card.textContent()).toContain('请切换到 PTC 模式') - expect(await readFile(settingsPath, 'utf8')).toBe(before) - expect(runtimeFiber() === originalRuntimeFiber).toBe(true) - expect(scaffold.ctx.ptcRuntime.programFormat).toBe('function-body') - expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) + expect(await card.textContent()).toContain('Windows 支持正在开发中') + expect(await card.textContent()).not.toContain('Swift') + const description = await card.getByRole('button', { name: '查看 Computer Use', exact: true }).evaluate((button) => { + const element = document.getElementById(button.getAttribute('aria-describedby')!)! + const style = getComputedStyle(element) + return { lines: style.webkitLineClamp, height: element.getBoundingClientRect().height, + lineHeight: Number.parseFloat(style.lineHeight) } + }) + expect(description.lines).toBe('1') + expect(description.height).toBeLessThanOrEqual(description.lineHeight + 1) + expect(scaffold.ctx.get('computerUse')).toBeDefined() expect(scaffold.ctx.agents.get(originalAgent.id) === originalAgent).toBe(true) + expect(scaffold.ctx.agents.get(ptcAgent.id) === ptcAgent).toBe(true) + expect(scaffold.ctx.agentPresets.composedPreset(originalAgent.ctx)).toBe(initialDefault) expect(scaffold.ctx.tools.schemas(originalAgent).some(tool => tool.name === 'cua')).toBe(false) expect(scaffold.ctx.tools.schemas(ptcAgent).some(tool => tool.name === 'cua')).toBe(true) expect((await scaffold.ctx.systemPrompt.assemble({ scope: ptcAgent })).tools.map(tool => tool.name)).toEqual(['run_code']) - const fresh = await scaffold.ctx.agents.create({ sessionId: SessionId('cua-new-ptc'), - setup: async (ctx) => { await scaffold.ctx.agentPresets.mount(ctx, 'ptc') }, + for (const preset of ['ptc', 'standard', 'ptc', initialDefault]) { + await scaffold.ctx.agentPresets.select(originalAgent, preset) + expect(scaffold.ctx.tools.schemas(originalAgent).some(tool => tool.name === 'cua')).toBe(preset === 'ptc') + } + const child = await scaffold.ctx.agents.create({ + sessionId: SessionId('cua-child'), + setup: (ctx) => { scaffold.ctx.agentPresets.composeFrom(ctx, ptcAgent.ctx) }, }) - expect(scaffold.ctx.tools.schemas(fresh.agent).some(tool => tool.name === 'cua')).toBe(true) - await toggle.click() - await card.waitFor({ state: 'hidden' }) - expect(scaffold.ctx.get('computerUse')).toBeUndefined() - for (const agent of [ptcAgent, fresh.agent]) expect(scaffold.ctx.tools.schemas(agent).some(tool => tool.name === 'cua')).toBe(false) + expect(scaffold.ctx.tools.schemas(child.agent).some(tool => tool.name === 'cua')).toBe(true) + await child.dispose() + expect(scaffold.ctx.tools.schemas(child.agent).some(tool => tool.name === 'cua')).toBe(false) + expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) expect(runtimeFiber() === originalRuntimeFiber).toBe(true) - expect(scaffold.ctx.ptcRuntime.programFormat).toBe('function-body') - expect(await readFile(settingsPath, 'utf8')).toBe(before) - await (await offerCua()).click() + expect(scaffold.ctx.ptcRuntime.programFormat).toBe(script ? 'script' : 'function-body') + await setup.waitFor() + expect(await setup.getByText('Computer Use 插件已开启，但暂时无法检测系统权限。请前往插件详情页查看原因并重试。', { exact: true }).count()).toBe(1) await setup.getByRole('button', { name: '稍后', exact: true }).click() + await setup.waitFor({ state: 'hidden' }) + let saved = await readFile(settingsPath, 'utf8') + expect(saved).toBe(beforeEnable) + expect(scaffold.ctx.settings.describe().find(row => row.ns === 'ui-settings')?.value).toMatchObject({ enabled: codingTools }) + expect(saved).not.toContain('executionMode:') + if (selectedDefault === undefined) { + expect(load(saved)).not.toEqual(expect.arrayContaining([expect.objectContaining({ id: 'agent-preset-registry' })])) + } else { + expect(load(saved)).toEqual(expect.arrayContaining([ + expect.objectContaining({ id: 'agent-preset-registry', config: { default: 'standard', selectedDefault } }), + ])) + } + const freshDefault = (await scaffold.ctx.agents.create({ + sessionId: SessionId('cua-new-default'), + setup: async (ctx) => { await scaffold.ctx.agentPresets.mount(ctx) }, + })).agent + expect(scaffold.ctx.agentPresets.composedPreset(freshDefault.ctx)).toBe(initialDefault) + expect(scaffold.ctx.tools.schemas(freshDefault).some(tool => tool.name === 'cua')).toBe(false) + const fresh = (await scaffold.ctx.agents.create({ + sessionId: SessionId('cua-new-ptc'), + setup: async (ctx) => { await scaffold.ctx.agentPresets.mount(ctx, 'ptc') }, + })).agent + expect(scaffold.ctx.agentPresets.composedPreset(fresh.ctx)).toBe('ptc') + expect(scaffold.ctx.tools.schemas(fresh).some(tool => tool.name === 'cua')).toBe(true) await card.getByRole('button', { name: '查看 Computer Use', exact: true }).click() - const detailToggle = page.locator('[data-plugin-panel]').getByRole('switch', { name: '启用 Computer Use', exact: true }) - await detailToggle.and(page.locator('[aria-checked="true"]')).waitFor({ state: 'visible' }) - const panel = page.locator('[data-cua-settings]') - await panel.waitFor() - const defaultSetting = panel.getByRole('group', { name: '新会话默认模式', exact: true }) + toggle = page.locator('[data-plugin-panel]').getByRole('switch', { name: '启用 Computer Use', exact: true }) + const persistent = page.getByRole('group', { name: 'PTC 执行方式', exact: true }) + const beforePersistent = scaffold.ctx.ptcRuntime + await persistent.getByRole('button', { name: '设为持久化', exact: true }).click() + await persistent.getByRole('button', { name: '已设为持久化', exact: true }).waitFor() + expect(scaffold.ctx.ptcRuntime.programFormat).toBe(script ? 'script' : 'repl') + expect(scaffold.ctx.ptcRuntime.retainsState).toBe(true) + expect(scaffold.ctx.ptcRuntime === beforePersistent).toBe(false) + saved = await readFile(settingsPath, 'utf8') + expect(saved).toContain(`executionMode: ${script ? 'vm-script' : 'persistent-in-memory'}`) + expect(saved).toContain(`scriptPersistence: ${script}`) + const runtime = scaffold.ctx.ptcRuntime + const persistentRuntimeFiber = runtimeFiber() + const owner = {} + const program = 'globalThis.counter = (globalThis.counter ?? 0) + 1' + expect((await runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))).value).toBe(1) + await toggle.click() + await toggle.and(page.locator('[aria-checked="false"]')).waitFor({ state: 'visible' }) + expect(scaffold.ctx.get('computerUse')).toBeUndefined() + expect(runtimeFiber() === persistentRuntimeFiber).toBe(true) + expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) + expect(scaffold.ctx.agents.get(ptcAgent.id) === ptcAgent).toBe(true) + for (const agent of [ptcAgent, fresh]) { + expect(scaffold.ctx.tools.schemas(agent).some(tool => tool.name === 'cua')).toBe(false) + expect((await scaffold.ctx.systemPrompt.assemble({ scope: agent })).tools.map(tool => tool.name)).toEqual(['run_code']) + } + expect((await runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))).value).toBe(2) + expect(await readFile(settingsPath, 'utf8')).toBe(saved) + await toggle.click() + await toggle.and(page.locator('[aria-checked="true"]')).waitFor({ state: 'visible' }) + await setup.waitFor() + expect(await setup.getByText('Computer Use 插件已开启，但暂时无法检测系统权限。请前往插件详情页查看原因并重试。', { exact: true }).count()).toBe(1) + expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) + await setup.getByRole('button', { name: '前往设置', exact: true }).click() + await setup.waitFor({ state: 'hidden' }) + await page.getByRole('region', { name: '给 Computer Use 授权', exact: true }).getByRole('alert').waitFor() + if (!codingTools) { + expect(await readFile(settingsPath, 'utf8')).toBe(saved) + expect(scaffold.ctx.settings.describe().find(row => row.ns === 'ui-settings')?.value).toMatchObject({ enabled: false }) + expect(scaffold.ctx.agentPresets.defaultId).toBe(initialDefault) + expect((await runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))).value).toBe(3) + await runtime.release(owner) + return + } + const defaultSetting = page.getByRole('group', { name: '新会话默认模式', exact: true }) await expect.poll(() => defaultSetting.getByRole('button', { name: '设为 PTC', exact: true }).isEnabled()).toBe(true) + await compareOrRefreshGolden(fileURLToPath(new URL('./expected/cua-permissions/default-mode.expected.md', import.meta.url)), + await captureStableAria(page, '[role="group"][aria-label="新会话默认模式"]', scaffold.workspaceCwd), webSnapshotMode()) await defaultSetting.getByRole('button', { name: '设为 PTC', exact: true }).click() await expect.poll(() => scaffold.ctx.agentPresets.defaultId).toBe('ptc') expect(scaffold.ctx.agentPresets.composedPreset(originalAgent.ctx)).toBe(initialDefault) - expect(runtimeFiber() === originalRuntimeFiber).toBe(true) - expect(scaffold.ctx.ptcRuntime.programFormat).toBe('function-body') - const confirmed = await scaffold.ctx.agents.create({ sessionId: SessionId('cua-confirmed-default'), + expect(scaffold.ctx.agentPresets.composedPreset(freshDefault.ctx)).toBe(initialDefault) + const confirmed = (await scaffold.ctx.agents.create({ + sessionId: SessionId('cua-confirmed-default'), setup: async (ctx) => { await scaffold.ctx.agentPresets.mount(ctx) }, - }) - expect(scaffold.ctx.tools.schemas(confirmed.agent).some(tool => tool.name === 'cua')).toBe(true) - const saved = await readFile(settingsPath, 'utf8') - expect(saved).toContain('selectedDefault: ptc') - expect(saved).not.toContain('executionMode:') - const persistent = panel.getByRole('group', { name: 'PTC 执行方式', exact: true }) - await persistent.getByRole('button', { name: '设为持久化', exact: true }).click() - await persistent.getByRole('button', { name: '已设为持久化', exact: true }).waitFor() - expect(scaffold.ctx.ptcRuntime.programFormat).toBe('repl') - expect(scaffold.ctx.ptcRuntime === originalRuntime).toBe(false) - const persistentRuntimeFiber = runtimeFiber() - const runtime = scaffold.ctx.ptcRuntime, owner = {} - const program = 'globalThis.counter = (globalThis.counter ?? 0) + 1' - expect((await runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))).value).toBe(1) - const configured = await readFile(settingsPath, 'utf8') - expect(configured).toContain('executionMode: persistent-in-memory') - expect(scaffold.ctx.agentPresets.defaultId).toBe('ptc') - expect(scaffold.ctx.agentPresets.composedPreset(originalAgent.ctx)).toBe(initialDefault) - await detailToggle.click() - await panel.waitFor({ state: 'hidden' }) - await card.waitFor({ state: 'hidden' }) - expect(await readFile(settingsPath, 'utf8')).toBe(configured) - expect(runtimeFiber() === persistentRuntimeFiber).toBe(true) - expect((await runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))).value).toBe(2) - await (await offerCua()).click() - await panel.waitFor({ state: 'visible' }) - await detailToggle.and(page.locator('[aria-checked="true"]')).waitFor({ state: 'visible' }) - expect(await readFile(settingsPath, 'utf8')).toBe(configured) + })).agent + expect(scaffold.ctx.agentPresets.composedPreset(confirmed.ctx)).toBe('ptc') + expect(scaffold.ctx.tools.schemas(confirmed).some(tool => tool.name === 'cua')).toBe(true) expect(runtimeFiber() === persistentRuntimeFiber).toBe(true) + expect(scaffold.ctx.tools.schemas(ptcAgent).some(tool => tool.name === 'cua')).toBe(true) expect((await runtime.run(runtime.resolve({ program, bindings: [], stateOwner: owner }))).value).toBe(3) + const confirmedSettings = await readFile(settingsPath, 'utf8') + expect(load(confirmedSettings)).toEqual(expect.arrayContaining([ + expect.objectContaining({ id: 'agent-preset-registry', config: { default: 'standard', selectedDefault: 'ptc' } }), + ])) + await toggle.click() + await toggle.and(page.locator('[aria-checked="false"]')).waitFor({ state: 'visible' }) + await toggle.click() + await toggle.and(page.locator('[aria-checked="true"]')).waitFor({ state: 'visible' }) + await setup.waitFor() + expect(await setup.getByText('Computer Use 插件已开启，但暂时无法检测系统权限。请前往插件详情页查看原因并重试。', { exact: true }).count()).toBe(1) + expect(await setup.getByRole('button', { name: '设为 PTC', exact: true }).count()).toBe(0) + expect(await readFile(settingsPath, 'utf8')).toBe(confirmedSettings) + expect(scaffold.ctx.settings.describe().find(row => row.ns === 'ui-settings')?.value).toMatchObject({ enabled: codingTools }) await runtime.release(owner) } finally { try { await browser?.close() } finally { diff --git a/apps/web/tests/cua-permissions.e2e.ts b/apps/web/tests/cua-permissions.e2e.ts index 0be5d4ec0e..72afb6648d 100644 --- a/apps/web/tests/cua-permissions.e2e.ts +++ b/apps/web/tests/cua-permissions.e2e.ts @@ -1,5 +1,5 @@ /** Built permission UI talks to the real provider; the isolated helper substitutes only macOS privilege observations. */ -import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' @@ -29,23 +29,20 @@ it.skipIf(process.platform !== 'darwin')('keeps system requests pending until fr const helper = await installNativeFixture(root) resources.closeFixture = await startFixtureHost(helper) const state = join(root, 'permissions.json'), audit = join(root, 'helper-events.jsonl') - const launchApplication = { name: 'Visual Studio Code.app', path: '/Applications/Visual Studio Code.app', + const launchApplication = { name: 'DSH Computer Use.app', path: '/Applications/DSH Computer Use.app', icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAADElEQVQImWNgZGIGAAAOAAeCcsnOAAAAAElFTkSuQmCC' } await writeFile(state, JSON.stringify({ accessibility: false, screenRecording: false, launchApplication })) await writeFile(join(root, 'observe-helper'), '') - const fixtureBundle = join(root, 'fixture-bundle') - await mkdir(fixtureBundle) - await writeFile(join(fixtureBundle, 'package.json'), JSON.stringify({ name: 'cua-permission-fixture', version: '1.0.0', - dsh: { bundle: { patch: 'cordis.patch.yml' } } })) - await writeFile(join(fixtureBundle, 'cordis.patch.yml'), `- id: cua\n config: ${JSON.stringify({ helperPath: helper })}\n`) + const fixturePatch = join(root, 'native-fixture.yml') + // Keep the external helper override above bundle order changes when CUA is re-enabled. + await writeFile(fixturePatch, JSON.stringify([{ id: 'cua', config: { helperPath: helper } }])) const scaffold = await launchWebScaffold({ - profile: { packages: [{ dir: bundle, enabled: true }, { dir: fixtureBundle, enabled: true }] }, + profile: { packages: [{ dir: bundle, enabled: true }] }, + extraOverlayPath: fixturePatch, }) resources.scaffold = scaffold expect((await scaffold.ctx.pluginManager.listBundles()).find(bundle => bundle.name === '@deepseek-ai/dsh-cua-bundle')) .toMatchObject({ listedByDefault: false, enabled: true, installed: true }) - await scaffold.ctx.settings.mutate('cua', [{ op: 'set', path: ['allowedApps'], - value: [{ id: 'a'.repeat(64), name: 'Fixture', executablePath: '/Applications/Fixture.app' }] }]) const browser = await chromium.launch() resources.browser = browser const page = await newEnglishPage(browser), tripwire = watchConsole(page) @@ -55,7 +52,6 @@ it.skipIf(process.platform !== 'darwin')('keeps system requests pending until fr const agent = scaffold.ctx.agents.list()[0]! await scaffold.ctx.agentPresets.select(agent, 'ptc') scaffold.ctx.approval.setPolicy(agent, 'never') - await scaffold.ctx.settings.mutate('cua', [{ op: 'set', path: ['allowedApps'], value: [] }]) // Application consent remains independent of the session's tool-approval policy. const grant = scaffold.ctx.tools.execute({ agent, signal: new AbortController().signal, calls: [{ type: 'tool-call', id: ToolCallId('cua-app-approval'), name: 'run_code', @@ -93,10 +89,10 @@ it.skipIf(process.platform !== 'darwin')('keeps system requests pending until fr expect(await panel.getByRole('region', { name: 'Manage applications computer use can access', exact: true }).count()).toBe(1) await expect.poll(() => panel.locator('li img').evaluate((image: HTMLImageElement) => image.naturalWidth)).toBe(1) expect(await panel.getByText('/fixture/app', { exact: true }).count()).toBe(0) - expect(await accessibility.getByText('Visual Studio Code.app', { exact: true }).count()).toBe(1) + expect(await accessibility.getByText('DSH Computer Use.app', { exact: true }).count()).toBe(1) expect(await accessibility.textContent()).toContain('In System Settings, allow') expect(await accessibility.textContent()).toContain('to read interface controls, click, and type.') - expect(await panel.getByRole('group', { name: 'Screen Recording', exact: true }).getByText('Visual Studio Code.app', { exact: true }).count()).toBe(1) + expect(await panel.getByRole('group', { name: 'Screen Recording', exact: true }).getByText('DSH Computer Use.app', { exact: true }).count()).toBe(1) await expect.poll(() => accessibility.locator('img').evaluate((image: HTMLImageElement) => image.naturalWidth)).toBe(1) await expect.poll(() => panel.getAttribute('aria-busy')).toBe('false') await compareOrRefreshGolden(expected, await captureStableAria(page, '[data-cua-settings]', scaffold.workspaceCwd), webSnapshotMode()) @@ -147,7 +143,10 @@ it.skipIf(process.platform !== 'darwin')('keeps system requests pending until fr await panel.getByRole('button', { name: 'Allow asking again', exact: true }).click() await panel.getByText('Fixture', { exact: true }).waitFor({ state: 'hidden' }) const saved = await readFile(join(scaffold.harnessHome, 'profiles/scaffold/cordis.patch.yml'), 'utf8') - expect(saved).toContain('allowedApps: []') + expect(saved).not.toContain('allowedApps:') + const files = await readdir(join(scaffold.workspaceCwd, '.dsh-storages')) + expect(files.some(file => file.startsWith('cua_permissions_') && file.endsWith('.json'))).toBe(true) + expect((await scaffold.ctx.cuaAccess.applications()).allowedApps).toEqual([]) const events = (await readFile(audit, 'utf8')).trim().split('\n').map(line => JSON.parse(line) as { event: string; method: string; params: object }) .filter(record => record.event === 'call').map(({ method, params }) => ({ method, params })) expect(events).toContainEqual({ method: 'requestPermission', params: { permission: 'accessibility' } }) @@ -203,6 +202,8 @@ it.skipIf(process.platform !== 'darwin')('keeps system requests pending until fr await expect.poll(() => toggle.isEnabled(), { timeout: PLUGIN_TOGGLE_SETTLE_MS }).toBe(true) await toggle.click() await expect.poll(() => toggle.getAttribute('aria-checked'), { timeout: PLUGIN_TOGGLE_SETTLE_MS }).toBe('true') + const setup = page.getByRole('dialog', { name: 'Set up computer use before use', exact: true }) + await setup.getByRole('button', { name: 'Later', exact: true }).click() await expect.poll(() => panel.getAttribute('aria-busy'), { timeout: PLUGIN_TOGGLE_SETTLE_MS }).toBe('false') expect(await trace.evaluate(value => value.errors)).toEqual([]) } diff --git a/apps/web/tests/deepseek-model-label-1017.e2e.ts b/apps/web/tests/deepseek-model-label-1017.e2e.ts deleted file mode 100644 index f732f2f7a9..0000000000 --- a/apps/web/tests/deepseek-model-label-1017.e2e.ts +++ /dev/null @@ -1,107 +0,0 @@ -/** The shipped browser plugin decorates both DeepSeek routes without changing catalog identity. */ -import { fileURLToPath } from 'node:url' -import { chromium, type Browser, type Page } from 'playwright' -import { afterAll, beforeAll, describe, expect, it } from 'vitest' -import { - captureStableAria, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, -} from './scaffold.ts' -import { connectFreshWorkspaceZh, ZH_BROWSER_LOCALE } from './support.ts' - -const NAME = 'DeepSeek-V4.1-Flash' -const FIXTURE = fileURLToPath(new URL('./fixtures/deepseek-model-label-1017/session.v4.jsonl', import.meta.url)) -const EXPECTED = fileURLToPath(new URL('./expected/deepseek-model-label-1017/models.expected.md', import.meta.url)) -const MODE = webSnapshotMode() - -describe.skipIf(MODE === 'record')('web e2e: temporary DeepSeek release badge', () => { - let scaffold: WebScaffold - let browser: Browser - let page: Page - let tripwire: ReturnType - - beforeAll(async () => { - scaffold = await launchWebScaffold({ - extraOverlayPath: fileURLToPath(new URL('./fixtures/deepseek-model-label-1017/account.overlay.yml', import.meta.url)), - replayFixture: FIXTURE, - replayProvidersOnly: true, - replayProviders: [ - { id: 'deepseek-account', name: 'DeepSeek Account', models: [{ id: 'deepseek-flash', name: NAME }] }, - { id: 'deepseek-official', name: 'DeepSeek', models: [ - { id: 'deepseek-flash', name: NAME }, { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' }, - ] }, - { id: 'external', name: 'External', models: [{ id: 'deepseek-flash', name: NAME }] }, - ], - }) - browser = await chromium.launch() - page = await browser.newPage({ viewport: { width: 1440, height: 900 }, locale: ZH_BROWSER_LOCALE }) - tripwire = watchConsole(page) - await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) - await connectFreshWorkspaceZh(page, scaffold.workspaceCwd) - }) - - afterAll(async () => { - try { await browser?.close() } - finally { await scaffold?.close() } - }) - - it('shows the same badge in all placements while preserving the chosen provider and model id', async () => { - const trigger = page.getByRole('button', { name: /^选择模型/ }) - await trigger.getByText('1017', { exact: true }).waitFor() - expect(await trigger.textContent()).toContain(`${NAME} 1017`) - expect(await trigger.getAttribute('aria-label')).toBe(`选择模型，当前 ${NAME}`) - try { - await trigger.click() - const current = page.getByRole('menuitem', { name: /^模型/ }) - expect(await current.getByText('1017', { exact: true }).count()).toBe(1) - await current.click() - const menu = page.getByRole('menu', { name: '模型', exact: true }) - await compareOrRefreshGolden(EXPECTED, await captureStableAria(page, '[role="menu"][aria-label="模型"]', scaffold.workspaceCwd), MODE) - expect(await menu.getByText('1017', { exact: true }).count()).toBe(2) - expect(await menu.getByRole('group', { name: 'External', exact: true }).getByText('1017', { exact: true }).count()).toBe(0) - const account = menu.getByRole('group', { name: 'DeepSeek 账号', exact: true }) - await account.getByRole('menuitemradio', { name: `${NAME} 1017`, exact: true }).click() - await expect.poll(() => scaffold.ctx.agentDefaultModel.currentSelection()).toEqual({ provider: 'deepseek-account', model: 'deepseek-flash' }) - await expect.poll(() => trigger.textContent()).toContain(`${NAME} 1017`) - const catalog = await scaffold.ctx.llm.listModels('deepseek-account') - expect(catalog.map(model => ({ id: model.id, name: model.name }))).toEqual([{ id: 'deepseek-flash', name: NAME }]) - } finally { - await page.keyboard.press('Escape') - await page.keyboard.press('Escape') - } - }) - - it('keeps the release badge inside a 390px model menu and uses both theme palettes', async () => { - try { - await page.setViewportSize({ width: 390, height: 844 }) - const trigger = page.getByRole('button', { name: /^选择模型/ }) - await trigger.click() - await page.getByRole('menuitem', { name: /^模型/ }).click() - const menu = page.getByRole('menu', { name: '模型', exact: true }) - const badge = menu.getByRole('group', { name: 'DeepSeek 账号', exact: true }).getByText('1017', { exact: true }) - const box = await badge.boundingBox() - expect(box).not.toBeNull() - expect(box!.x).toBeGreaterThanOrEqual(12) - expect(box!.x + box!.width).toBeLessThanOrEqual(378) - const colors = await badge.evaluate((node) => { - const body = node.ownerDocument.body - const previous = body.getAttribute('data-ds-dark-theme') - try { - return [false, true].map((dark) => { - body.toggleAttribute('data-ds-dark-theme', dark) - const style = getComputedStyle(node) - return { color: style.color, background: style.backgroundColor } - }) - } finally { - if (previous === null) body.removeAttribute('data-ds-dark-theme') - else body.setAttribute('data-ds-dark-theme', previous) - } - }) - expect(colors[0]).not.toEqual(colors[1]) - for (const color of colors) expect(color.color).not.toBe(color.background) - } finally { - await page.keyboard.press('Escape') - await page.keyboard.press('Escape') - await page.setViewportSize({ width: 1440, height: 900 }) - } - expect(tripwire.pageErrors).toEqual([]) - }) -}) diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts index 9625333287..fa6c518add 100644 --- a/apps/web/tests/default-model.e2e.ts +++ b/apps/web/tests/default-model.e2e.ts @@ -563,7 +563,7 @@ describe('web e2e: the composer model switch is the default for later sessions', for (const palette of headingPalettes) { expect(palette.headingFills, `${palette.platform}, dark=${String(palette.dark)}`) .toEqual(['rgba(0, 0, 0, 0)']) - expect(palette.menuFill).toBe(palette.dark ? 'rgba(67, 69, 74, 0.45)' : 'rgba(248, 249, 250, 0.58)') + expect(palette.menuFill).toBe(palette.dark ? 'rgba(48, 49, 54, 0.64)' : 'rgba(252, 253, 254, 0.7)') expect(palette.searchBorder).toBe('rgba(0, 0, 0, 0)') expect(palette.positions).toEqual(['sticky']) expect(palette.headingRadii).toEqual([palette.platform === 'darwin' ? '0px' : palette.optionRadius]) diff --git a/apps/web/tests/details-session-lifecycle.e2e.ts b/apps/web/tests/details-session-lifecycle.e2e.ts index 68dd75f3d8..e73eaa5d0b 100644 --- a/apps/web/tests/details-session-lifecycle.e2e.ts +++ b/apps/web/tests/details-session-lifecycle.e2e.ts @@ -113,7 +113,7 @@ async function sidebarSnapshot(page: Page) { coversViewport: expanded && rect.x === 0 && rect.y === 0 && Math.round(rect.width) === window.innerWidth && Math.round(rect.height) === window.innerHeight, resizeHandleWidth: handle === null ? 0 : Math.round(handle.getBoundingClientRect().width), - expandedDirectories: [...panel.querySelectorAll('[data-files-entry="directory"] > button[aria-expanded="true"]')] + expandedDirectories: [...panel.querySelectorAll('[data-files-entry="directory"] button[aria-expanded="true"]')] .map(button => button.textContent?.trim()), } }) @@ -188,7 +188,7 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S await blankColumn.locator('[data-sidebar-right-toggle]').click() await blankColumn.locator('[data-dockkit-pane]').first().waitFor({ state: 'hidden' }) await page.setViewportSize({ width: 767, height: blankViewport.height }) - await expect.poll(() => columns(page)).toEqual([56, 711, 0]) + await expect.poll(() => columns(page)).toEqual([0, 767, 0]) await page.locator('[data-sidebar-right-expand]').click() // The fullscreen shell keeps its viewport box while its docked content closes. await expect.poll(() => blankColumn.locator('[data-sidebar-right-open]').count()).toBe(1) @@ -196,6 +196,14 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S .toBe('none') await expect.poll(() => blankColumn.locator('[data-sidebar-right-panel]').boundingBox()) .toEqual({ x: 0, y: 0, width: 767, height: blankViewport.height }) + // A preview the files page opened starts with its tree hidden; shown, the tree fills the viewport. + const treeToggle = blankColumn.locator('[data-files-navigator-toggle]') + await expect.poll(() => treeToggle.getAttribute('aria-expanded')).toBe('false') + await treeToggle.click() + await blankColumn.locator('[data-files-navigator]').waitFor({ state: 'visible' }) + expect(await blankColumn.locator('[data-textpreview-body]').evaluate(node => getComputedStyle(node).visibility)).toBe('hidden') + await treeToggle.click() + await expect.poll(() => treeToggle.getAttribute('aria-expanded')).toBe('false') await blankColumn.getByText('Workspace preview is available.', { exact: true }).waitFor() await blankColumn.locator('[data-sidebar-right-toggle]').click() await blankColumn.locator('[data-dockkit-pane]').first().waitFor({ state: 'hidden' }) @@ -369,7 +377,8 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S expect(await panel.getAttribute('data-sidebar-right-panel')).toBe('push') await column.locator('[data-sidebar-right-guide-entry="files"]').click() await column.locator('[data-files-state="tree"]').waitFor({ timeout: 15_000 }) - const workspaceDirectory = column.locator('[data-files-entry="directory"] > button').filter({ hasText: /^workspace$/ }) + const workspaceDirectory = column.locator('[data-files-entry="directory"] button') + .and(column.getByRole('button', { name: 'workspace', exact: true })) await workspaceDirectory.waitFor({ timeout: 15_000 }) await workspaceDirectory.click() await expect.poll(() => workspaceDirectory.getAttribute('aria-expanded')).toBe('true') @@ -425,7 +434,7 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S await expect.poll(() => columns(page)).toEqual([420, viewport.width - 420 - normalWidth, normalWidth]) await page.setViewportSize({ width: 767, height: viewport.height }) await expect.poll(() => panel.boundingBox()).toEqual({ x: 0, y: 0, width: 767, height: viewport.height }) - await expect.poll(() => columns(page)).toEqual([56, 711, 0]) + await expect.poll(() => columns(page)).toEqual([0, 767, 0]) expect(await sidebarSnapshot(page)).toMatchObject({ mode: 'fullscreen', resizeHandleWidth: 0, coversViewport: true }) await checkpoint('A automatic fullscreen at 767px') await column.locator('[data-sidebar-right-mode="push"]').click() diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts index 79a5ed4bdb..e164ae38e5 100644 --- a/apps/web/tests/document-preview.e2e.ts +++ b/apps/web/tests/document-preview.e2e.ts @@ -714,7 +714,7 @@ else process.exit(1); const initialFilesClose = await filesTab.locator('[data-dockkit-tab-close]').count() expect(initialFilesClose).toBe(1) await filesTab.click({ button: 'right' }) - expect(await page.locator('[data-dockkit-tab-menu]:visible').count()).toBe(1) + await page.locator('[data-context-menu][role="menu"]').waitFor() await page.keyboard.press('Escape') await addTab.waitFor({ state: 'visible' }) const initialAdd = await addTab.count() @@ -1563,6 +1563,62 @@ else process.exit(1); await compareOrRefreshGolden(EXPECTED, sections.join('\n\n'), MODE) await assertFixtureInventory(SNAPSHOT_DIR, ['document.expected.md', 'applications.expected.md', 'applications-no-default.expected.md', 'paging.patch.yml']) }) + + it('preserves Markdown reading position beyond the first page after automatic and manual refresh', async () => { + onTestFailed(() => saveFailureShot(page, `screenshots/0908-document-preview/refresh-scroll-${process.pid}`)) + if (await page.getByText('LIGHTHOUSE', { exact: true }).count() === 0) { + const settled = scaffold.whenTurnSettled() + const input = page.locator('[data-composer-input]').first() + await input.fill(PROMPT) + await input.press('Enter') + await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + } + const cwd = scaffold.ctx.agents.list()[0]?.session.header.cwd + if (cwd === undefined) throw new Error('Session has no workspace cwd') + const path = join(cwd, 'refresh-scroll.md') + const markdown = '# Before refresh\n\n' + Array.from({ length: PAGE_LINES * 2 }, (_, index) => `Paragraph ${index + 1}\n`).join('\n') + await writeFile(path, markdown) + const column = page.locator('[data-rightbar-col]') + const expand = page.locator('[data-sidebar-right-expand]') + if (await expand.isVisible()) await expand.click() + const filesTab = column.locator('[data-dockkit-tab]').filter({ has: page.getByText('Files', { exact: true }) }) + if (await filesTab.count() === 0) await column.locator('[data-sidebar-right-guide-entry="files"]').click() + await filesTab.click() + await column.locator('[data-files-reload]').click() + const preview = column.locator('[data-textpreview-url]') + await openPreviewFile(column, filesTab, preview, 'refresh-scroll.md') + const body = preview.locator('[data-textpreview-body]') + const heading = body.getByRole('heading', { level: 1 }) + await expect.poll(() => heading.textContent()).toBe('Before refresh') + await expect.poll(() => preview.locator('[data-textpreview-more]').isEnabled()).toBe(true) + const target = await body.evaluate(node => node.scrollHeight + 100) + await scrollForNextPage(body) + await expect.poll(() => body.evaluate(node => node.scrollHeight - node.clientHeight)).toBeGreaterThan(target) + await body.evaluate((node, top) => new Promise((resolve) => { + node.addEventListener('scroll', () => { resolve() }, { once: true }) + node.scrollTop = top + }), target) + const original = await body.evaluate(node => node.scrollTop) + expect(original).toBe(target) + // Content growing above the viewport keeps the pixel offset instead of following the content. + await heading.evaluate((node) => { node.style.paddingTop = '300px' }) + await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))) + expect(await body.evaluate(node => node.scrollTop)).toBe(original) + await heading.evaluate((node) => { node.style.paddingTop = '' }) + + await writeFile(path, markdown.replace('Before refresh', 'After refresh')) + await expect.poll(() => heading.textContent()).toBe('After refresh') + await expect.poll(() => body.evaluate((node, top) => Math.abs(node.scrollTop - top), original)).toBeLessThanOrEqual(1) + + const rendered = await heading.elementHandle() + await preview.locator('[data-textpreview-tool="reload"]').click() + await expect.poll(() => rendered!.evaluate(node => node.isConnected)).toBe(false) + await expect.poll(() => heading.textContent()).toBe('After refresh') + await expect.poll(() => body.evaluate((node, top) => Math.abs(node.scrollTop - top), original)).toBeLessThanOrEqual(1) + await rendered!.dispose() + expect(tripwire.pageErrors).toEqual([]) + }) }) describe.skipIf(MODE === 'record')('web e2e: Host Office preview', () => { diff --git a/apps/web/tests/excel-opc.e2e.ts b/apps/web/tests/excel-opc.e2e.ts index a3a49e3248..9cd298aed2 100644 --- a/apps/web/tests/excel-opc.e2e.ts +++ b/apps/web/tests/excel-opc.e2e.ts @@ -54,7 +54,7 @@ describe.skipIf(mode === 'record')('web e2e: independent-writer Excel previews', await column.locator('[data-sidebar-right-guide-entry="files"]').click() await column.locator('[data-files-state="tree"]').waitFor() await column.locator('[data-files-reload]').click() - const files = column.locator('[data-dockkit-tab]').filter({ has: page.getByText('Files', { exact: true }) }) + const toggle = column.locator('[data-files-navigator-toggle]:visible') const preview = column.locator('[data-textpreview-url]') const excel = preview.locator('[data-excel-preview]') const sheets = excel.locator('.luckysheet-sheets-item-name') @@ -62,8 +62,10 @@ describe.skipIf(mode === 'record')('web e2e: independent-writer Excel previews', const rows = ['# Independent-writer Excel previews', ''] await page.context().grantPermissions(['clipboard-read', 'clipboard-write'], { origin: new URL(page.url()).origin }) for (const name of [...excelOpcCases, ...excelOpeningCases, ...excelXmlCases]) { - await files.click() - await column.locator('[data-files-entry="file"]').getByRole('button', { name: `${name}.xlsx`, exact: true }).click() + // The first file replaces the files page; later ones open from the pane's navigator. + // The files page always shows its tree and draws no toggle. + if (await toggle.count() > 0 && await toggle.getAttribute('aria-expanded') !== 'true') await toggle.click() + await column.locator('[data-files-navigator]:visible [data-files-entry="file"]').getByRole('button', { name: `${name}.xlsx`, exact: true }).click() await expect.poll(async () => (await preview.getAttribute('data-textpreview-url'))?.endsWith(`/${name}.xlsx`)).toBe(true) await sheets.getByText('数据', { exact: true }).waitFor() await excel.locator('.fortune-sheet-overlay').click({ position: { x: 70, y: 30 } }) diff --git a/apps/web/tests/expected/additional-locales/de.expected.md b/apps/web/tests/expected/additional-locales/de.expected.md index 210ffed2fb..1f6b2b5a77 100644 --- a/apps/web/tests/expected/additional-locales/de.expected.md +++ b/apps/web/tests/expected/additional-locales/de.expected.md @@ -1,5 +1,5 @@ - listitem: - button "Siehe Automatische Autorisierungsüberprüfung": Automatische Autorisierungsüberprüfung - - text: Experimentell Fügen Sie einen Auto review-Berechtigungsmodus hinzu, der das Modell verwendet, um die Autorisierung vor jedem Toolaufruf zu bewerten. + - text: "Experimentell Fügt den Zugriffsmodus „Auto review“ hinzu: Vor jedem Tool-Aufruf prüft ein Modell den Aufruf anhand Ihrer Anforderung; zugelassene Aufrufe laufen sofort, abgelehnte Aufrufe warten auf Ihre Genehmigung." - status - switch "Aktivieren Sie Automatische Autorisierungsüberprüfung" diff --git a/apps/web/tests/expected/additional-locales/es.expected.md b/apps/web/tests/expected/additional-locales/es.expected.md index c1e0233d70..a2a434ac84 100644 --- a/apps/web/tests/expected/additional-locales/es.expected.md +++ b/apps/web/tests/expected/additional-locales/es.expected.md @@ -1,5 +1,5 @@ - listitem: - button "Ver Revisión de autorización automática": Revisión de autorización automática - - text: Experimental Agregue un modo de permiso Auto review que utilice el modelo para evaluar la autorización antes de cada llamada a la herramienta. + - text: "Experimental Añade el modo de acceso “Auto review”: antes de cada llamada a una herramienta, un modelo comprueba la llamada frente a lo que usted pidió; las llamadas permitidas se ejecutan de inmediato y las denegadas esperan su aprobación." - status - switch "Habilitar Revisión de autorización automática" diff --git a/apps/web/tests/expected/additional-locales/fr.expected.md b/apps/web/tests/expected/additional-locales/fr.expected.md index 88c6dad142..c589a1ec21 100644 --- a/apps/web/tests/expected/additional-locales/fr.expected.md +++ b/apps/web/tests/expected/additional-locales/fr.expected.md @@ -1,5 +1,5 @@ - listitem: - button "Voir Examen des autorisations automatiques": Examen des autorisations automatiques - - text: Expérimental Ajoutez un mode d'autorisation Auto review qui utilise le modèle pour évaluer l'autorisation avant chaque appel d'outil. + - text: "Expérimental Ajoute le mode d'accès « Auto review » : avant chaque appel d'outil, un modèle vérifie l'appel par rapport à ce que vous avez demandé ; les appels autorisés s'exécutent immédiatement et les appels refusés attendent votre approbation." - status - switch "Activer Examen des autorisations automatiques" diff --git a/apps/web/tests/expected/additional-locales/pt.expected.md b/apps/web/tests/expected/additional-locales/pt.expected.md index 1119ad2aa1..a9393bf830 100644 --- a/apps/web/tests/expected/additional-locales/pt.expected.md +++ b/apps/web/tests/expected/additional-locales/pt.expected.md @@ -1,5 +1,5 @@ - listitem: - button "Ver Revisão de autorização automática": Revisão de autorização automática - - text: Experimental Adicione um modo de permissão Auto review que usa o modelo para avaliar a autorização antes de cada chamada de ferramenta. + - text: "Experimental Adiciona o modo de acesso “Auto review”: antes de cada chamada de ferramenta, um modelo verifica a chamada em relação ao que você pediu; as chamadas permitidas são executadas imediatamente e as negadas aguardam sua aprovação." - status - switch "Ativar Revisão de autorização automática" diff --git a/apps/web/tests/expected/additional-locales/ru.expected.md b/apps/web/tests/expected/additional-locales/ru.expected.md index e4f02c9c69..5d48baee88 100644 --- a/apps/web/tests/expected/additional-locales/ru.expected.md +++ b/apps/web/tests/expected/additional-locales/ru.expected.md @@ -1,5 +1,5 @@ - listitem: - button "Посмотреть Проверка автоматической авторизации": Проверка автоматической авторизации - - text: Экспериментальный Добавьте режим разрешений Auto review, который использует модель для оценки авторизации перед каждым вызовом инструмента. + - text: "Экспериментальный Добавляет режим доступа «Auto review»: перед каждым вызовом инструмента модель сверяет вызов с вашей просьбой; разрешённые вызовы выполняются сразу, а отклонённые ждут вашего одобрения." - status - switch "Включить Проверка автоматической авторизации" diff --git a/apps/web/tests/expected/client-plugin-live/session-actions.expected.md b/apps/web/tests/expected/client-plugin-live/session-actions.expected.md index 51df861f77..93f241e0fc 100644 --- a/apps/web/tests/expected/client-plugin-live/session-actions.expected.md +++ b/apps/web/tests/expected/client-plugin-live/session-actions.expected.md @@ -2,8 +2,10 @@ - menuitem "Pin session" - menuitem "Rename" - menuitem "Fork session" - - menuitem "Archive session" + - separator - menuitem "Copy Session ID" - separator - menuitem "Export session" - menuitem "Copy session ID" + - separator + - menuitem "Archive session" diff --git a/apps/web/tests/expected/client-plugin-live/session-trailing.expected.json b/apps/web/tests/expected/client-plugin-live/session-trailing.expected.json index 8b5c4cb664..83f9ecd3fb 100644 --- a/apps/web/tests/expected/client-plugin-live/session-trailing.expected.json +++ b/apps/web/tests/expected/client-plugin-live/session-trailing.expected.json @@ -86,7 +86,7 @@ "Fixture badge", "Fixture section" ], - "time": true, + "time": false, "pinned": false, "actions": true }, @@ -96,7 +96,7 @@ "Fixture badge", "Fixture section" ], - "time": true, + "time": false, "pinned": false, "actions": true }, @@ -106,7 +106,7 @@ "Fixture badge", "Fixture section" ], - "time": true, + "time": false, "pinned": false, "actions": true }, @@ -116,8 +116,8 @@ "Fixture badge", "Fixture section" ], - "time": true, - "pinned": true, + "time": false, + "pinned": false, "actions": true }, { @@ -136,7 +136,7 @@ "Fixture badge", "Fixture section" ], - "time": true, + "time": false, "pinned": false, "actions": true } diff --git a/apps/web/tests/expected/context-menus/image.txt b/apps/web/tests/expected/context-menus/image.txt new file mode 100644 index 0000000000..a8090be657 --- /dev/null +++ b/apps/web/tests/expected/context-menus/image.txt @@ -0,0 +1,3 @@ +Copy image +Download +Show in folder diff --git a/apps/web/tests/expected/context-menus/session.txt b/apps/web/tests/expected/context-menus/session.txt new file mode 100644 index 0000000000..5468d20e51 --- /dev/null +++ b/apps/web/tests/expected/context-menus/session.txt @@ -0,0 +1,6 @@ +Pin session +Rename +Fork session +Copy Session ID +Show in folder +Archive session diff --git a/apps/web/tests/expected/context-menus/workspace.txt b/apps/web/tests/expected/context-menus/workspace.txt new file mode 100644 index 0000000000..93c401728b --- /dev/null +++ b/apps/web/tests/expected/context-menus/workspace.txt @@ -0,0 +1,3 @@ +Rename +Show in folder +Delete workspace diff --git a/apps/web/tests/expected/cot-translation-paid/paid-choices.expected.md b/apps/web/tests/expected/cot-translation-paid/paid-choices.expected.md index a141beff7b..dedc4bb631 100644 --- a/apps/web/tests/expected/cot-translation-paid/paid-choices.expected.md +++ b/apps/web/tests/expected/cot-translation-paid/paid-choices.expected.md @@ -6,57 +6,10 @@ - text: v{{version}} 实验性 - paragraph: - code: "@deepseek-ai/dsh-experimental-cot-translation-bundle" -- paragraph: 机器翻译展开的思考内容；原文会发送给所选服务 +- paragraph: 智能体输出时，把展开的“思考”行翻译成你选择的语言，点击“查看原文”可切换回原文。 - region "详细介绍": - paragraph: - img "展开的思考行从英文翻译成中文，并显示“查看原文”按钮" - - paragraph: - - text: 展开 - - strong: 思考 - - text: 行，即可用界面语言阅读其中的思考内容。智能体输出时会逐段翻译；最新的内容在能够翻译之前保持原文。 - - heading "使用方法" [level=2] - - list: - - listitem: - - text: 展开 - - strong: 思考 - - text: 行。点击 - - strong: 查看原文 - - text: 显示原文，点击 - - strong: 查看译文 - - text: 切换回译文。 - - listitem: - - text: 在此插件的页面中选择 - - strong: 翻译服务 - - text: 和 - - strong: 目标语言 - - text: ，然后点击 - - strong: 保存 - - text: 。 - - code: auto - - text: 表示跟随界面语言；也可以填写 - - code: zh - - text: 、 - - code: en - - text: 、 - - code: ja - - text: 等语言代码。 - - listitem: - - text: 翻译失败时，原文保持显示，并提供 - - strong: 重试 - - text: 。 - - heading "注意事项" [level=2] - - list: - - listitem: 你展开的思考内容可能包含你的代码和对话细节。 - - listitem: 默认使用 Bing，也可以选择 Google。两者都无需账号或 API key，但都不保证可用，也不保证免费额度。 - - listitem: - - text: 如果已配置 DeepSeek 账号或官方 API，还会出现 - - strong: DeepSeek Flash · 账号（付费） - - text: 和 - - strong: DeepSeek Flash · 官方 API（付费） - - text: 。此时每段没有已保存译文的内容都是一次付费请求。 - - listitem: 译文保存在会话中，重新打开时直接复用。原始思考内容和模型的输入都不会改变。 - - listitem: 折叠时显示的摘要保持原文。翻译可能改变 Markdown 格式或代码。 - - listitem: 关闭此插件会移除它的按钮并取消未完成的翻译；已保存的译文仍保留在会话中。 - paragraph: 展开的思考内容会发送给所选翻译服务，可能包含私有代码或对话细节。 - paragraph: 每个未缓存片段都会通过所选账号或官方 API 凭据单独发送一次付费的 DeepSeek Flash 请求；重新展开会复用已保存的译文，更改服务、语言、原文或请求设置可能发送新的付费请求 - text: 翻译服务 已覆盖 diff --git a/apps/web/tests/expected/cot-translation/preferences.expected.md b/apps/web/tests/expected/cot-translation/preferences.expected.md index 6404a2d8bc..c3da36d678 100644 --- a/apps/web/tests/expected/cot-translation/preferences.expected.md +++ b/apps/web/tests/expected/cot-translation/preferences.expected.md @@ -6,57 +6,10 @@ - text: v{{version}} 实验性 - paragraph: - code: "@deepseek-ai/dsh-experimental-cot-translation-bundle" -- paragraph: 机器翻译展开的思考内容；原文会发送给所选服务 +- paragraph: 智能体输出时，把展开的“思考”行翻译成你选择的语言，点击“查看原文”可切换回原文。 - region "详细介绍": - paragraph: - img "展开的思考行从英文翻译成中文，并显示“查看原文”按钮" - - paragraph: - - text: 展开 - - strong: 思考 - - text: 行，即可用界面语言阅读其中的思考内容。智能体输出时会逐段翻译；最新的内容在能够翻译之前保持原文。 - - heading "使用方法" [level=2] - - list: - - listitem: - - text: 展开 - - strong: 思考 - - text: 行。点击 - - strong: 查看原文 - - text: 显示原文，点击 - - strong: 查看译文 - - text: 切换回译文。 - - listitem: - - text: 在此插件的页面中选择 - - strong: 翻译服务 - - text: 和 - - strong: 目标语言 - - text: ，然后点击 - - strong: 保存 - - text: 。 - - code: auto - - text: 表示跟随界面语言；也可以填写 - - code: zh - - text: 、 - - code: en - - text: 、 - - code: ja - - text: 等语言代码。 - - listitem: - - text: 翻译失败时，原文保持显示，并提供 - - strong: 重试 - - text: 。 - - heading "注意事项" [level=2] - - list: - - listitem: 你展开的思考内容可能包含你的代码和对话细节。 - - listitem: 默认使用 Bing，也可以选择 Google。两者都无需账号或 API key，但都不保证可用，也不保证免费额度。 - - listitem: - - text: 如果已配置 DeepSeek 账号或官方 API，还会出现 - - strong: DeepSeek Flash · 账号（付费） - - text: 和 - - strong: DeepSeek Flash · 官方 API（付费） - - text: 。此时每段没有已保存译文的内容都是一次付费请求。 - - listitem: 译文保存在会话中，重新打开时直接复用。原始思考内容和模型的输入都不会改变。 - - listitem: 折叠时显示的摘要保持原文。翻译可能改变 Markdown 格式或代码。 - - listitem: 关闭此插件会移除它的按钮并取消未完成的翻译；已保存的译文仍保留在会话中。 - paragraph: 展开的思考内容会发送给所选翻译服务，可能包含私有代码或对话细节。 - paragraph: Bing 和 Google 翻译无需额外登录或 API key，但匿名接口可能拒绝或限制请求 - text: 翻译服务 diff --git a/apps/web/tests/expected/cua-permissions/application-approval.expected.md b/apps/web/tests/expected/cua-permissions/application-approval.expected.md index fc9007a938..74989b3ae3 100644 --- a/apps/web/tests/expected/cua-permissions/application-approval.expected.md +++ b/apps/web/tests/expected/cua-permissions/application-approval.expected.md @@ -2,7 +2,7 @@ - group "Approval details": - strong: Fixture - text: Allow computer use to launch, read, capture and control this application? - - paragraph: Session access lasts until DSH restarts or computer use is disabled. + - paragraph: Allowing or denying applies to every version and copy sharing the same application identity. Session access and denial apply only to this conversation. - button "Reject" - button "Allow for this session" - button "Always allow" diff --git a/apps/web/tests/expected/cua-permissions/default-mode.expected.md b/apps/web/tests/expected/cua-permissions/default-mode.expected.md new file mode 100644 index 0000000000..36996c4d69 --- /dev/null +++ b/apps/web/tests/expected/cua-permissions/default-mode.expected.md @@ -0,0 +1,4 @@ +- group "新会话默认模式": + - strong: 新会话默认模式 + - paragraph: Computer Use 仅在 PTC 模式中可用。 + - button "设为 PTC" diff --git a/apps/web/tests/expected/cua-permissions/missing.expected.md b/apps/web/tests/expected/cua-permissions/missing.expected.md index cb4ade57ac..3b32eb2418 100644 --- a/apps/web/tests/expected/cua-permissions/missing.expected.md +++ b/apps/web/tests/expected/cua-permissions/missing.expected.md @@ -10,11 +10,11 @@ - button "Use persistent mode" - group "Accessibility": - strong: Accessibility - - paragraph: In System Settings, allow Visual Studio Code.app to read interface controls, click, and type. + - paragraph: In System Settings, allow DSH Computer Use.app to read interface controls, click, and type. - button "Request permission" - group "Screen Recording": - strong: Screen Recording - - paragraph: In System Settings, allow Visual Studio Code.app to capture application windows. + - paragraph: In System Settings, allow DSH Computer Use.app to capture application windows. - button "Request permission" - paragraph: Manage permissions in System Settings for the application named by macOS. - region "Manage applications computer use can access": diff --git a/apps/web/tests/expected/cua-permissions/setup.expected.md b/apps/web/tests/expected/cua-permissions/setup.expected.md new file mode 100644 index 0000000000..0ee5870bf3 --- /dev/null +++ b/apps/web/tests/expected/cua-permissions/setup.expected.md @@ -0,0 +1,6 @@ +- dialog "使用 Computer Use 前需要设置": + - heading "使用 Computer Use 前需要设置" [level=2] + - button "关闭" + - paragraph: Computer Use 插件已开启，但暂时无法检测系统权限。请前往插件详情页查看原因并重试。 + - button "稍后" + - button "前往设置" diff --git a/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md b/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md index 120b33549a..08a0750772 100644 --- a/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md +++ b/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md @@ -29,20 +29,20 @@ - textbox "模型 ID 1": - /placeholder: 模型 ID - text: deepseek-flash + - button "模型选项 1" + - button "删除模型 1" - textbox "显示名称 1": - /placeholder: 显示名称 - text: DeepSeek-V4.1-Flash - - button "模型选项 1" - - button "删除模型 1" - button "调整模型顺序 2" - textbox "模型 ID 2": - /placeholder: 模型 ID - text: deepseek-v4-pro + - button "模型选项 2" + - button "删除模型 2" - textbox "显示名称 2": - /placeholder: 显示名称 - text: DeepSeek-V4-Pro - - button "模型选项 2" - - button "删除模型 2" - button "添加模型" - button "取消" - button "保存" diff --git a/apps/web/tests/expected/forge-panel/branch-details.expected.md b/apps/web/tests/expected/forge-panel/branch-details.expected.md new file mode 100644 index 0000000000..8c348d423a --- /dev/null +++ b/apps/web/tests/expected/forge-panel/branch-details.expected.md @@ -0,0 +1 @@ +- 'tooltip "Current branch: feature/a-long-current-branch-name-for-mobile-review"' diff --git a/apps/web/tests/expected/forge-panel/changes-view.expected.md b/apps/web/tests/expected/forge-panel/changes-view.expected.md new file mode 100644 index 0000000000..b6c825a833 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/changes-view.expected.md @@ -0,0 +1,71 @@ +- img "变更请求状态：需要处理" +- text: "Add the pull request panel #7" +- button "提交评审" +- button "在浏览器中打开" +- button "全部 2 个文件" +- text: +4 −2 +- button "刷新变更" +- button "全部折叠" +- button "左右对比" [pressed] +- button "自动换行" [pressed] +- region "全部 2 个文件": + - button "收起 panel.ts" [expanded] + - text: src/panel.ts +2 −2 + - button "panel.ts 的更多操作" + - button "选择第 L1 行": "1" + - text: export const n1 = 1 + - button "选择第 R1 行": "1" + - text: export const n1 = 1 + - button "选择第 L2 行": "2" + - text: export const n2 = 2 + - button "选择第 R2 行": "2" + - text: export const n2 = 'two' + - button "选择第 L3 行": "3" + - text: export const n3 = 3 + - button "选择第 R3 行": "3" + - text: export const n3 = 3 + - button "选择第 L4 行": "4" + - text: export const n4 = 4 + - button "选择第 R4 行": "4" + - text: export const n4 = 4 + - button "选择第 L5 行": "5" + - text: export const n5 = 5 + - button "选择第 R5 行": "5" + - text: export const n5 = 5 + - button "6 行未变更" + - button "选择第 L12 行": "12" + - text: export const n12 = 12 + - button "选择第 R12 行": "12" + - text: export const n12 = 12 + - button "选择第 L13 行": "13" + - text: export const n13 = 13 + - button "选择第 R13 行": "13" + - text: export const n13 = 13 + - button "选择第 L14 行": "14" + - text: export const n14 = 14 + - button "选择第 R14 行": "14" + - text: export const n14 = 14 + - button "选择第 L15 行": "15" + - text: export const n15 = 15 + - button "选择第 R15 行": "15" + - text: export const n15 = 'fifteen' + - button "选择第 L16 行": "16" + - text: export const n16 = 16 + - button "选择第 R16 行": "16" + - text: export const n16 = 16 + - button "选择第 L17 行": "17" + - text: export const n17 = 17 + - button "选择第 R17 行": "17" + - text: export const n17 = 17 + - button "选择第 L18 行": "18" + - text: export const n18 = 18 + - button "选择第 R18 行": "18" + - text: export const n18 = 18 + - button "其余未变更的行" + - button "收起 panel.md" [expanded] + - text: docs/panel.md 新文件 +2 −0 + - button "panel.md 的更多操作" + - button "选择第 R1 行": "1" + - text: "+ # Panel" + - button "选择第 R2 行": "2" + - text: + Shows the change requests of a Session. diff --git a/apps/web/tests/expected/forge-panel/file-tree-toggle.expected.md b/apps/web/tests/expected/forge-panel/file-tree-toggle.expected.md new file mode 100644 index 0000000000..5873dec5ae --- /dev/null +++ b/apps/web/tests/expected/forge-panel/file-tree-toggle.expected.md @@ -0,0 +1,77 @@ +- img "变更请求状态：需要处理" +- text: "Add the pull request panel #7" +- button "提交评审" +- button "在浏览器中打开" +- button "全部 2 个文件" +- text: +4 −2 +- button "刷新变更" +- button "全部折叠" +- button "左右对比" [pressed] +- button "自动换行" [pressed] +- button "将文件树移到右侧" [expanded] +- region "全部 2 个文件": + - button "收起 panel.ts" [expanded] + - text: src/panel.ts +2 −2 + - button "panel.ts 的更多操作" + - button "选择第 L1 行": "1" + - text: export const n1 = 1 + - button "选择第 R1 行": "1" + - text: export const n1 = 1 + - button "选择第 L2 行": "2" + - text: export const n2 = 2 + - button "选择第 R2 行": "2" + - text: export const n2 = 'two' + - button "选择第 L3 行": "3" + - text: export const n3 = 3 + - button "选择第 R3 行": "3" + - text: export const n3 = 3 + - button "选择第 L4 行": "4" + - text: export const n4 = 4 + - button "选择第 R4 行": "4" + - text: export const n4 = 4 + - button "选择第 L5 行": "5" + - text: export const n5 = 5 + - button "选择第 R5 行": "5" + - text: export const n5 = 5 + - button "6 行未变更" + - button "选择第 L12 行": "12" + - text: export const n12 = 12 + - button "选择第 R12 行": "12" + - text: export const n12 = 12 + - button "选择第 L13 行": "13" + - text: export const n13 = 13 + - button "选择第 R13 行": "13" + - text: export const n13 = 13 + - button "选择第 L14 行": "14" + - text: export const n14 = 14 + - button "选择第 R14 行": "14" + - text: export const n14 = 14 + - button "选择第 L15 行": "15" + - text: export const n15 = 15 + - button "选择第 R15 行": "15" + - text: export const n15 = 'fifteen' + - button "选择第 L16 行": "16" + - text: export const n16 = 16 + - button "选择第 R16 行": "16" + - text: export const n16 = 16 + - button "选择第 L17 行": "17" + - text: export const n17 = 17 + - button "选择第 R17 行": "17" + - text: export const n17 = 17 + - button "选择第 L18 行": "18" + - text: export const n18 = 18 + - button "选择第 R18 行": "18" + - text: export const n18 = 18 + - button "其余未变更的行" + - button "收起 panel.md" [expanded] + - text: docs/panel.md 新文件 +2 −0 + - button "panel.md 的更多操作" + - button "选择第 R1 行": "1" + - text: "+ # Panel" + - button "选择第 R2 行": "2" + - text: + Shows the change requests of a Session. +- separator "调整文件树宽度" +- navigation "全部 2 个文件": + - textbox "筛选文件…": src + - button "src" [expanded] + - button "src/panel.ts": panel.ts +2 −2 diff --git a/apps/web/tests/expected/forge-panel/filter-config-failed.expected.md b/apps/web/tests/expected/forge-panel/filter-config-failed.expected.md new file mode 100644 index 0000000000..eef3d4c6df --- /dev/null +++ b/apps/web/tests/expected/forge-panel/filter-config-failed.expected.md @@ -0,0 +1,11 @@ +- text: 与 origin/main 比较，包含未提交的修改 +- button "创建变更请求" +- button "分支" +- button "全部 0 个文件" [disabled] +- button "刷新变更" +- button "全部展开" [disabled] +- button "左右对比" [pressed] +- button "自动换行" [pressed] +- status: + - text: 无法完整读取 Git 过滤器配置，尚未执行比较。请检查 Git 配置和读取上限后重试 + - button "重试" diff --git a/apps/web/tests/expected/forge-panel/full-access.expected.md b/apps/web/tests/expected/forge-panel/full-access.expected.md new file mode 100644 index 0000000000..3f45ecb592 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/full-access.expected.md @@ -0,0 +1,4 @@ +- button "本地变更" +- text: HEAD → origin/main +- button "查看本会话的变更：1 个文件，新增 1 行，删除 0 行": +1 −0 1 个文件 +- button "创建变更请求" diff --git a/apps/web/tests/expected/forge-panel/local-card.expected.md b/apps/web/tests/expected/forge-panel/local-card.expected.md new file mode 100644 index 0000000000..24058934d3 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/local-card.expected.md @@ -0,0 +1,4 @@ +- button "Local changes" +- text: HEAD → origin/main +- 'button "View the changes of this Session: 60 files, 60 lines added, 0 lines deleted"': +60 −0 60 files +- button "Create change request" diff --git a/apps/web/tests/expected/forge-panel/merge-menu.expected.md b/apps/web/tests/expected/forge-panel/merge-menu.expected.md new file mode 100644 index 0000000000..e180c4167d --- /dev/null +++ b/apps/web/tests/expected/forge-panel/merge-menu.expected.md @@ -0,0 +1,7 @@ +- menu: + - text: "将 #9 合并到 main" + - menuitem "压缩合并 把全部提交压缩成一个提交" + - menuitem "创建合并提交 保留全部提交，并新增一个合并提交" + - menuitem "变基合并 把提交逐个变基到 main" + - separator + - menuitem "确认合并" diff --git a/apps/web/tests/expected/forge-panel/merge-stale.expected.md b/apps/web/tests/expected/forge-panel/merge-stale.expected.md new file mode 100644 index 0000000000..c7e3ec5891 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/merge-stale.expected.md @@ -0,0 +1,7 @@ +- menu: + - text: "将 #9 合并到 main" + - menuitem "压缩合并 把全部提交压缩成一个提交" + - menuitem "创建合并提交 保留全部提交，并新增一个合并提交" + - menuitem "变基合并 把提交逐个变基到 main" + - separator + - menuitem "提交已更新，请重新检查后再打开合并菜单" [disabled] diff --git a/apps/web/tests/expected/forge-panel/panel.expected.md b/apps/web/tests/expected/forge-panel/panel.expected.md new file mode 100644 index 0000000000..f71db0bd64 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/panel.expected.md @@ -0,0 +1,17 @@ +- text: dsh-{{worktree}} 工作树 · 基于 release +- button "复制工作树路径" +- heading "本会话的变更请求 · 1" [level=3] +- button "刷新状态" +- list: + - listitem: + - img "变更请求状态：需要处理" + - link "Add the pull request panel": + - /url: https://github.com/octo/demo/pull/7 + - text: "#7 feat → main" + - button "在浏览器中打开" + - button "复制变更请求链接" + - 'button "从本会话移除 #7"' + - 'button "收起 #7" [expanded]' + - button "检查 已加载 1 项检查，仍有更多" + - text: 评审 等待评审 · 1 条未解决讨论 合并 无冲突 + - 'button "查看 #7 的变更：新增 128 行，删除 14 行"': 变更 +128 −14 diff --git a/apps/web/tests/expected/forge-panel/reference.expected.md b/apps/web/tests/expected/forge-panel/reference.expected.md new file mode 100644 index 0000000000..4a34c8f7c9 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/reference.expected.md @@ -0,0 +1,12 @@ +- listitem: + - img "变更请求状态：需要处理" + - link "Add the pull request panel": + - /url: https://github.com/octo/demo/pull/7 + - text: "#7 feat → main" + - button "在浏览器中打开" + - button "复制变更请求链接" + - 'button "从本会话移除 #7"' + - 'button "收起 #7" [expanded]' + - button "检查 已加载 1 项检查，仍有更多" + - text: 评审 等待评审 · 1 条未解决讨论 合并 无冲突 + - 'button "查看 #7 的变更：新增 128 行，删除 14 行"': 变更 +128 −14 diff --git a/apps/web/tests/expected/forge-panel/review-composer.expected.md b/apps/web/tests/expected/forge-panel/review-composer.expected.md new file mode 100644 index 0000000000..d2c1d4682d --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-composer.expected.md @@ -0,0 +1,7 @@ +- region "评论 R2–4": + - text: 评论 R2–4 + - textbox "留下评论…": 请核对边界条件 + - button "取消" + - button "添加到输入框" + - button "开始评审" + - button "GitHub 评论选项" diff --git a/apps/web/tests/expected/forge-panel/review-guide.expected.md b/apps/web/tests/expected/forge-panel/review-guide.expected.md new file mode 100644 index 0000000000..a56f8cd077 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-guide.expected.md @@ -0,0 +1 @@ +- button "代码审查和变更 查看代码变更与本会话的变更请求" diff --git a/apps/web/tests/expected/forge-panel/review-message.expected.md b/apps/web/tests/expected/forge-panel/review-message.expected.md new file mode 100644 index 0000000000..c454458d69 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-message.expected.md @@ -0,0 +1,25 @@ +> ## User Comment 2 +> File: src/extra.ts +> Side: R +> Lines: 1 +> Source: Local (branch) +> Diff hunk: +> ```diff +> @@ -0,0 +1,1 @@ +> +export const extra = 1 +> ``` +> Comment: +> 请检查这项修改 + +> ## User Comment 1 +> File: src/app.ts +> Side: R +> Lines: 1 +> Source: Local (branch) +> Diff hunk: +> ```diff +> @@ -0,0 +1,1 @@ +> +export const app = 1 +> ``` +> Comment: +> 请解释这行代码 diff --git a/apps/web/tests/expected/forge-panel/review-quotes.expected.md b/apps/web/tests/expected/forge-panel/review-quotes.expected.md new file mode 100644 index 0000000000..602d647831 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-quotes.expected.md @@ -0,0 +1,6 @@ +- textbox "发消息或创建任务, / 调用指令, @ 文件或对话": + - paragraph: + - button "移除引用" + - text: "## User Comment 2 File: src/extra.ts Side: R Lines: 1 Source: Local (branch) Diff hunk: ```diff @@ -0,0 +1,1 @@ +export const extra = 1 ``` Comment: 请检查这项修改" + - button "移除引用" + - text: "## User Comment 1 File: src/app.ts Side: R Lines: 1 Source: Local (branch) Diff hunk: ```diff @@ -0,0 +1,1 @@ +export const app = 1 ``` Comment: 请解释这行代码" diff --git a/apps/web/tests/expected/forge-panel/review-record.expected.md b/apps/web/tests/expected/forge-panel/review-record.expected.md new file mode 100644 index 0000000000..3e678d6071 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-record.expected.md @@ -0,0 +1,4 @@ +- region "评论 R2–4": + - text: 你的评论 R2–4 已发布到 GitHub 请核对边界条件 + - button "添加到输入框" + - button "在 GitHub 查看" diff --git a/apps/web/tests/expected/forge-panel/review-summary-required.expected.md b/apps/web/tests/expected/forge-panel/review-summary-required.expected.md new file mode 100644 index 0000000000..3e384b28e1 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-summary-required.expected.md @@ -0,0 +1,14 @@ +- dialog "提交评审": + - heading "提交评审" [level=2] + - button "关闭" + - text: 待提交评论（1） + - textbox "评审总结…" + - status: 请求更改时，请填写评审总结 + - radio "评论" + - text: 评论 + - radio "批准" + - text: 批准 + - radio "请求更改" [checked] + - text: 请求更改 + - button "取消" + - button "提交评审" [disabled] diff --git a/apps/web/tests/expected/forge-panel/session-row-hover.expected.md b/apps/web/tests/expected/forge-panel/session-row-hover.expected.md new file mode 100644 index 0000000000..1e00472353 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/session-row-hover.expected.md @@ -0,0 +1 @@ +- text: "dsh-{{worktree}} 工作树 · 基于 release #7 Add the pull request panel 需要处理 · 检查失败" diff --git a/apps/web/tests/expected/forge-panel/submit-review.expected.md b/apps/web/tests/expected/forge-panel/submit-review.expected.md new file mode 100644 index 0000000000..0687f7ba99 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/submit-review.expected.md @@ -0,0 +1,14 @@ +- dialog "提交评审": + - heading "提交评审" [level=2] + - button "关闭" + - text: 待提交评论（1） + - textbox "评审总结…": 需要补充边界检查 + - status: 请求更改时，请填写评审总结 + - radio "评论" + - text: 评论 + - radio "批准" + - text: 批准 + - radio "请求更改" [checked] + - text: 请求更改 + - button "取消" + - button "提交评审" diff --git a/apps/web/tests/expected/forge-panel/worktree-option.expected.md b/apps/web/tests/expected/forge-panel/worktree-option.expected.md new file mode 100644 index 0000000000..c9a85b8723 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/worktree-option.expected.md @@ -0,0 +1,3 @@ +- button "当前分支：main": main +- checkbox "新建工作树" +- text: 新建工作树 diff --git a/apps/web/tests/expected/goal-bar/blocked.expected.md b/apps/web/tests/expected/goal-bar/blocked.expected.md new file mode 100644 index 0000000000..dbfcf5563b --- /dev/null +++ b/apps/web/tests/expected/goal-bar/blocked.expected.md @@ -0,0 +1,4 @@ +- text: Blocked Goal retry with the edited plan +- button "Resume goal" +- button "Edit goal" +- button "Clear goal" diff --git a/apps/web/tests/expected/japanese-plugin-metadata/card.expected.md b/apps/web/tests/expected/japanese-plugin-metadata/card.expected.md index 0fa58e0c23..df7ab7b97b 100644 --- a/apps/web/tests/expected/japanese-plugin-metadata/card.expected.md +++ b/apps/web/tests/expected/japanese-plugin-metadata/card.expected.md @@ -1,5 +1,5 @@ - listitem: - button "自動認可レビューを表示": 自動認可レビュー - - text: 実験的 各ツール呼び出しの前にモデルが認可を判断する、自動認可レビュー権限モードを提供します。 + - text: 実験的 「自動認可レビュー」アクセスモードを追加します。各ツール呼び出しの前に、モデルがその呼び出しをあなたの依頼内容と照らし合わせて確認し、許可された呼び出しは即座に実行され、拒否された呼び出しはあなたの承認を待ちます。 - status - switch "自動認可レビューを有効化" diff --git a/apps/web/tests/expected/layout-bottom/geometry.expected.md b/apps/web/tests/expected/layout-bottom/geometry.expected.md index 39188ce561..8e53379673 100644 --- a/apps/web/tests/expected/layout-bottom/geometry.expected.md +++ b/apps/web/tests/expected/layout-bottom/geometry.expected.md @@ -4,6 +4,6 @@ grown: {"bottom":{"top":440,"height":360,"bottom":800},"main":{"top":0,"height": darwin: {"bottom":{"top":440,"height":360,"bottom":800},"main":{"top":0,"height":440,"bottom":440},"sidebar":{"top":0,"height":440,"bottom":440},"rightbar":{"top":0,"height":440,"bottom":440},"overlay":{"top":0,"height":800,"bottom":800},"handles":[{"top":0,"height":440,"bottom":440}],"pageHeight":800} windows: {"bottom":{"top":440,"height":360,"bottom":800},"main":{"top":40,"height":400,"bottom":440},"sidebar":{"top":40,"height":400,"bottom":440},"rightbar":{"top":40,"height":400,"bottom":440},"overlay":{"top":0,"height":800,"bottom":800},"handles":[{"top":40,"height":400,"bottom":440}],"pageHeight":800} browser: {"bottom":{"top":440,"height":360,"bottom":800},"main":{"top":0,"height":440,"bottom":440},"sidebar":{"top":0,"height":440,"bottom":440},"rightbar":{"top":0,"height":440,"bottom":440},"overlay":{"top":0,"height":800,"bottom":800},"handles":[{"top":0,"height":440,"bottom":440}],"pageHeight":800} -narrow: {"bottom":{"top":240,"height":360,"bottom":600},"main":{"top":0,"height":240,"bottom":240},"sidebar":{"top":0,"height":240,"bottom":240},"rightbar":{"top":0,"height":240,"bottom":240},"overlay":{"top":0,"height":600,"bottom":600},"handles":[],"pageHeight":600} +narrow: {"bottom":{"top":240,"height":360,"bottom":600},"main":{"top":0,"height":240,"bottom":240},"sidebar":{"top":0,"height":600,"bottom":600},"rightbar":{"top":0,"height":240,"bottom":240},"overlay":{"top":0,"height":600,"bottom":600},"handles":[],"pageHeight":600} unregistered: {"bottom":{"top":600,"height":0,"bottom":600},"main":{"top":0,"height":600,"bottom":600},"sidebar":{"top":0,"height":600,"bottom":600},"rightbar":{"top":0,"height":600,"bottom":600},"overlay":{"top":0,"height":600,"bottom":600},"handles":[],"pageHeight":600} collapsed: {"bottom":{"top":600,"height":0,"bottom":600},"main":{"top":0,"height":600,"bottom":600},"sidebar":{"top":0,"height":600,"bottom":600},"rightbar":{"top":0,"height":600,"bottom":600},"overlay":{"top":0,"height":600,"bottom":600},"handles":[],"pageHeight":600} diff --git a/apps/web/tests/expected/markdown-colon-file-links.md b/apps/web/tests/expected/markdown-colon-file-links.md new file mode 100644 index 0000000000..fe7031c9f0 --- /dev/null +++ b/apps/web/tests/expected/markdown-colon-file-links.md @@ -0,0 +1,21 @@ +- paragraph: + - button "Relative colon:24–30" + - text: · + - button "Absolute colon:30" + - text: · + - button "Fragment:12" + - text: · + - button "Column:24:5" + - text: · + - button "Zero line" + - text: · + - button "Reversed range" + - text: · + - link "Bare URL": + - /url: index.ts:24 + - text: · Blocked script · + - link "Development server": + - /url: localhost:3000 + - text: · + - link "Mail": + - /url: mailto:10086 diff --git a/apps/web/tests/expected/menu-material/materials.expected.json b/apps/web/tests/expected/menu-material/materials.expected.json index 301564bef3..b0abc51804 100644 --- a/apps/web/tests/expected/menu-material/materials.expected.json +++ b/apps/web/tests/expected/menu-material/materials.expected.json @@ -1,24 +1,24 @@ { "web-light": { - "fill": "rgba(248, 249, 250, 0.58)", + "fill": "rgba(252, 253, 254, 0.7)", "blur": "blur(40px) saturate(1.5)", "radius": "16px", "shadow": "rgba(0, 0, 0, 0.04) 0px 0px 0px 0.5px, rgba(0, 0, 0, 0.04) 0px 3px 8px 0px, rgba(0, 0, 0, 0.05) 0px 0px 20px 0px" }, "web-dark": { - "fill": "rgba(67, 69, 74, 0.45)", + "fill": "rgba(48, 49, 54, 0.64)", "blur": "blur(40px) saturate(1.5)", "radius": "16px", "shadow": "rgba(255, 255, 255, 0.16) 0px 0px 0px 0.5px, rgba(0, 0, 0, 0.04) 0px 3px 8px 0px, rgba(0, 0, 0, 0.05) 0px 0px 20px 0px" }, "darwin-light": { - "fill": "rgba(248, 249, 250, 0.58)", + "fill": "rgba(252, 253, 254, 0.7)", "blur": "blur(40px) saturate(1.5)", "radius": "16px", "shadow": "rgba(0, 0, 0, 0.04) 0px 0px 0px 0.5px, rgba(0, 0, 0, 0.04) 0px 3px 8px 0px, rgba(0, 0, 0, 0.05) 0px 0px 20px 0px" }, "darwin-dark": { - "fill": "rgba(67, 69, 74, 0.45)", + "fill": "rgba(48, 49, 54, 0.64)", "blur": "blur(40px) saturate(1.5)", "radius": "16px", "shadow": "rgba(255, 255, 255, 0.16) 0px 0px 0px 0.5px, rgba(0, 0, 0, 0.04) 0px 3px 8px 0px, rgba(0, 0, 0, 0.05) 0px 0px 20px 0px" diff --git a/apps/web/tests/expected/menu-material/session-menu.expected.md b/apps/web/tests/expected/menu-material/session-menu.expected.md index ebb1786386..c7c535b9e4 100644 --- a/apps/web/tests/expected/menu-material/session-menu.expected.md +++ b/apps/web/tests/expected/menu-material/session-menu.expected.md @@ -2,5 +2,7 @@ - menuitem "Pin session" - menuitem "Rename" - menuitem "Fork session" - - menuitem "Archive session" + - separator - menuitem "Copy Session ID" + - separator + - menuitem "Archive session" diff --git a/apps/web/tests/expected/deepseek-model-label-1017/models.expected.md b/apps/web/tests/expected/model-badge/models.expected.md similarity index 55% rename from apps/web/tests/expected/deepseek-model-label-1017/models.expected.md rename to apps/web/tests/expected/model-badge/models.expected.md index 9f86e38326..3ac3338e57 100644 --- a/apps/web/tests/expected/deepseek-model-label-1017/models.expected.md +++ b/apps/web/tests/expected/model-badge/models.expected.md @@ -4,8 +4,10 @@ - menuitemradio "DeepSeek-V4.1-Flash 1017" - group "DeepSeek": - text: DeepSeek - - menuitemradio "DeepSeek-V4.1-Flash 1017" [checked] + - menuitemradio "DeepSeek-V4.1-Flash 新" [checked] - menuitemradio "DeepSeek-V4-Pro" + - menuitemradio "DeepSeek model with a very long release and capability description that exceeds the selector width Preview" + - menuitemradio "Invalid badge model" - group "External": - text: External - menuitemradio "DeepSeek-V4.1-Flash" diff --git a/apps/web/tests/expected/models-settings/catalog-inputs.expected.md b/apps/web/tests/expected/models-settings/catalog-inputs.expected.md index fd9cc97859..0f6c28c0f2 100644 --- a/apps/web/tests/expected/models-settings/catalog-inputs.expected.md +++ b/apps/web/tests/expected/models-settings/catalog-inputs.expected.md @@ -36,11 +36,11 @@ - textbox "模型 ID 1": - /placeholder: 模型 ID - text: gpt-6-astra + - button "模型选项 1" [expanded] + - button "删除模型 1" - textbox "显示名称 1": - /placeholder: 显示名称 - text: GPT-6 Astra - - button "模型选项 1" [expanded] - - button "删除模型 1" - text: 上下文窗口 - textbox "上下文窗口 1": - /placeholder: 1M diff --git a/apps/web/tests/expected/models-settings/declared-edit.expected.md b/apps/web/tests/expected/models-settings/declared-edit.expected.md index be77f7ceee..8fe2a7d83c 100644 --- a/apps/web/tests/expected/models-settings/declared-edit.expected.md +++ b/apps/web/tests/expected/models-settings/declared-edit.expected.md @@ -44,10 +44,10 @@ - textbox "模型 ID 1": - /placeholder: 模型 ID - text: acme-large - - textbox "显示名称 1": - - /placeholder: 显示名称 - button "模型选项 1" [expanded] - button "删除模型 1" + - textbox "显示名称 1": + - /placeholder: 显示名称 - text: 上下文窗口 - textbox "上下文窗口 1": - /placeholder: 1M diff --git a/apps/web/tests/expected/models-settings/image-only.expected.md b/apps/web/tests/expected/models-settings/image-only.expected.md index ea3046ce5b..ed9c82a0c4 100644 --- a/apps/web/tests/expected/models-settings/image-only.expected.md +++ b/apps/web/tests/expected/models-settings/image-only.expected.md @@ -44,10 +44,10 @@ - textbox "模型 ID 1": - /placeholder: 模型 ID - text: acme-large - - textbox "显示名称 1": - - /placeholder: 显示名称 - button "模型选项 1" [expanded] - button "删除模型 1" + - textbox "显示名称 1": + - /placeholder: 显示名称 - text: 上下文窗口 - textbox "上下文窗口 1": - /placeholder: 1M diff --git a/apps/web/tests/expected/models-settings/mobile-collapsed.expected.md b/apps/web/tests/expected/models-settings/mobile-collapsed.expected.md new file mode 100644 index 0000000000..46babcd11e --- /dev/null +++ b/apps/web/tests/expected/models-settings/mobile-collapsed.expected.md @@ -0,0 +1,64 @@ +- dialog "设置": + - text: 设置 + - navigation: + - button "通用设置" + - button "模型" + - button "内置插件" + - button "Agent 预设" + - button "打开配置文件" + - button "关闭" + - heading "模型" [level=2] + - paragraph: 填入各提供商的 API 密钥即可使用其模型。 + - list: + - listitem: + - text: minimax-cn + - img "API 密钥已配置" + - button "编辑 minimax-cn": 编辑 + - button "删除 minimax-cn": 删除 + - listitem: + - text: Acme 网关 自定义 + - button "编辑 Acme 网关 (acme-gateway)": 编辑 + - button "删除 Acme 网关 (acme-gateway)": 删除 + - text: Acme 网关 acme-gateway API 密钥 + - textbox "API 密钥": + - /placeholder: 输入 API 密钥 + - group: + - text: 自定义设置 显示名称 + - textbox "显示名称": + - /placeholder: acme-gateway + - text: Acme 网关 + - text: API 地址 + - textbox "API 地址": + - /placeholder: https://gateway.acme.example/v1 + - text: https://gateway.acme.example/v1 + - text: API 协议 + - combobox "API 协议": + - option "OpenAI Chat Completions" + - option "OpenAI Responses" + - option "Anthropic Messages" [selected] + - region "模型目录": + - text: 模型目录 已自定义模型目录 + - button "恢复默认模型" + - button "获取可用模型" + - button "调整模型顺序 1" + - textbox "模型 ID 1": + - /placeholder: 模型 ID + - text: order-second + - button "模型选项 1" + - button "删除模型 1" + - button "调整模型顺序 2" + - textbox "模型 ID 2": + - /placeholder: 模型 ID + - text: order-third + - button "模型选项 2" + - button "删除模型 2" + - button "调整模型顺序 3" + - textbox "模型 ID 3": + - /placeholder: 模型 ID + - text: acme-large + - button "模型选项 3" + - button "删除模型 3" + - button "添加模型" + - button "取消" + - button "保存" + - button "添加模型提供商" diff --git a/apps/web/tests/expected/models-settings/mobile-expanded.expected.md b/apps/web/tests/expected/models-settings/mobile-expanded.expected.md new file mode 100644 index 0000000000..b1f780f9b3 --- /dev/null +++ b/apps/web/tests/expected/models-settings/mobile-expanded.expected.md @@ -0,0 +1,84 @@ +- dialog "设置": + - text: 设置 + - navigation: + - button "通用设置" + - button "模型" + - button "内置插件" + - button "Agent 预设" + - button "打开配置文件" + - button "关闭" + - heading "模型" [level=2] + - paragraph: 填入各提供商的 API 密钥即可使用其模型。 + - list: + - listitem: + - text: minimax-cn + - img "API 密钥已配置" + - button "编辑 minimax-cn": 编辑 + - button "删除 minimax-cn": 删除 + - listitem: + - text: Acme 网关 自定义 + - button "编辑 Acme 网关 (acme-gateway)": 编辑 + - button "删除 Acme 网关 (acme-gateway)": 删除 + - text: Acme 网关 acme-gateway API 密钥 + - textbox "API 密钥": + - /placeholder: 输入 API 密钥 + - group: + - text: 自定义设置 显示名称 + - textbox "显示名称": + - /placeholder: acme-gateway + - text: Acme 网关 + - text: API 地址 + - textbox "API 地址": + - /placeholder: https://gateway.acme.example/v1 + - text: https://gateway.acme.example/v1 + - text: API 协议 + - combobox "API 协议": + - option "OpenAI Chat Completions" + - option "OpenAI Responses" + - option "Anthropic Messages" [selected] + - region "模型目录": + - text: 模型目录 已自定义模型目录 + - button "恢复默认模型" + - button "获取可用模型" + - button "调整模型顺序 1" + - textbox "模型 ID 1": + - /placeholder: 模型 ID + - text: order-second + - button "模型选项 1" [expanded] + - button "删除模型 1" + - text: 显示名称 + - textbox "显示名称 1": + - /placeholder: 显示名称 + - text: 手机上的完整显示名称 + - text: 上下文窗口 + - textbox "上下文窗口 1": + - /placeholder: 1M + - text: 最大输出 token 数 + - textbox "最大输出 token 数 1": + - /placeholder: 128K + - group "输入类型 1": + - text: 输入类型 + - checkbox "文本" [checked] [disabled] + - text: 文本 + - checkbox "图片" + - text: 图片 + - group "推理等级 1": + - text: 推理等级 + - button "推理等级说明": "?" + - switch "推理等级 1" + - button "调整模型顺序 2" + - textbox "模型 ID 2": + - /placeholder: 模型 ID + - text: order-third + - button "模型选项 2" + - button "删除模型 2" + - button "调整模型顺序 3" + - textbox "模型 ID 3": + - /placeholder: 模型 ID + - text: acme-large + - button "模型选项 3" + - button "删除模型 3" + - button "添加模型" + - button "取消" + - button "保存" + - button "添加模型提供商" diff --git a/apps/web/tests/expected/navigation-panes/live-result-evicted.expected.md b/apps/web/tests/expected/navigation-panes/live-result-evicted.expected.md new file mode 100644 index 0000000000..c81c4d0b19 --- /dev/null +++ b/apps/web/tests/expected/navigation-panes/live-result-evicted.expected.md @@ -0,0 +1,7 @@ +- tabpanel "Result": + - region "Raw result": + - heading "Raw result" [level=3] + - paragraph: Raw results are only available for live tool calls + - region "Rendered result": + - heading "Rendered result" [level=3] + - text: LIVE_RESULT_RENDERED diff --git a/apps/web/tests/expected/navigation-panes/live-result-running.expected.md b/apps/web/tests/expected/navigation-panes/live-result-running.expected.md new file mode 100644 index 0000000000..91844f0a86 --- /dev/null +++ b/apps/web/tests/expected/navigation-panes/live-result-running.expected.md @@ -0,0 +1,7 @@ +- tabpanel "Result": + - region "Raw result": + - heading "Raw result" [level=3] + - paragraph: Running… + - region "Rendered result": + - heading "Rendered result" [level=3] + - paragraph: Running… diff --git a/apps/web/tests/expected/navigation-panes/live-result.expected.md b/apps/web/tests/expected/navigation-panes/live-result.expected.md new file mode 100644 index 0000000000..8e37486cbb --- /dev/null +++ b/apps/web/tests/expected/navigation-panes/live-result.expected.md @@ -0,0 +1,10 @@ +- tabpanel "Result": + - region "Raw result": + - heading "Raw result" [level=3] + - text: "{" + - tree "Result JSON": + - treeitem "answer:42" + - text: "}" + - region "Rendered result": + - heading "Rendered result" [level=3] + - text: LIVE_RESULT_RENDERED diff --git a/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md b/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md index bde82cec8f..03900f109b 100644 --- a/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md +++ b/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md @@ -29,11 +29,11 @@ - textbox "模型 ID 1": - /placeholder: 模型 ID - text: deepseek-flash + - button "模型选项 1" [expanded] + - button "删除模型 1" - textbox "显示名称 1": - /placeholder: 显示名称 - text: DeepSeek-V4.1-Flash - - button "模型选项 1" [expanded] - - button "删除模型 1" - text: 上下文窗口 - textbox "上下文窗口 1": - /placeholder: 1M @@ -51,11 +51,11 @@ - textbox "模型 ID 2": - /placeholder: 模型 ID - text: deepseek-v4-pro + - button "模型选项 2" + - button "删除模型 2" - textbox "显示名称 2": - /placeholder: 显示名称 - text: DeepSeek-V4-Pro - - button "模型选项 2" - - button "删除模型 2" - button "添加模型" - button "取消" - button "保存" diff --git a/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md b/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md index 55526bebec..27ba737236 100644 --- a/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md +++ b/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md @@ -30,11 +30,11 @@ - textbox "模型 ID 1": - /placeholder: 模型 ID - text: private-preview + - button "模型选项 1" [expanded] + - button "删除模型 1" - textbox "显示名称 1": - /placeholder: 显示名称 - text: Private Preview - - button "模型选项 1" [expanded] - - button "删除模型 1" - text: 上下文窗口 - textbox "上下文窗口 1": - /placeholder: 1M diff --git a/apps/web/tests/expected/plugin-config/official.expected.md b/apps/web/tests/expected/plugin-config/official.expected.md index e893673581..8e36bea43c 100644 --- a/apps/web/tests/expected/plugin-config/official.expected.md +++ b/apps/web/tests/expected/plugin-config/official.expected.md @@ -34,14 +34,19 @@ - switch "启用 语音输入" - listitem: - button "查看 自定义插件索引": 自定义插件索引 - - text: 实验性 在插件页添加「发现」标签页，从你添加的插件索引浏览和安装插件。 + - text: 实验性 在插件页添加“发现”标签页，从你添加的插件索引中浏览和安装插件。 - status - switch "启用 自定义插件索引" - listitem: - button "查看 自动授权审查": 自动授权审查 - - text: 实验性 提供自动审查权限模式，由模型在每次工具调用前判断是否授权。 + - text: 实验性 提供“自动审查”访问模式：每次工具调用前，由模型对照你的要求检查，获准的调用立即运行，被拒绝的调用等你审批。 - status - switch "启用 自动授权审查" + - listitem: + - button "查看 变更请求与工作树": 变更请求与工作树 + - text: 实验性 跟踪每个会话的变更请求及其检查与评审，新会话也可以在 Git 工作树中开始；GitHub 通过 gh 命令行访问。 + - status + - switch "启用 变更请求与工作树" - heading "已安装插件" [level=3] - list: - listitem: diff --git a/apps/web/tests/expected/plugin-install-registry/installed.expected.md b/apps/web/tests/expected/plugin-install-registry/installed.expected.md index 2ddc96e196..d198049eca 100644 --- a/apps/web/tests/expected/plugin-install-registry/installed.expected.md +++ b/apps/web/tests/expected/plugin-install-registry/installed.expected.md @@ -15,4 +15,5 @@ - text: 已完成 $ pnpm add mirrored-package - button "复制" - text: Installed from the registry pnpm names + - paragraph: 完整日志：{{cwd}}/.dsh-home/profiles/scaffold/.plugin-manager/logs/operation-{{suffix}}/pnpm.log - button "立即启用" diff --git a/apps/web/tests/expected/plugin-install-silent-failure/failed.expected.md b/apps/web/tests/expected/plugin-install-silent-failure/failed.expected.md new file mode 100644 index 0000000000..61630bd8b2 --- /dev/null +++ b/apps/web/tests/expected/plugin-install-silent-failure/failed.expected.md @@ -0,0 +1,14 @@ +- dialog "插件安装失败": + - button "返回编辑": 编辑 + - button "关闭" + - alert: 插件安装失败 + - paragraph: 安装命令失败，原因见安装详情 + - paragraph: silent-package + - paragraph: 版本 1.0.0 + - button "收起安装详情" [expanded] + - button "重试" + - paragraph: 安装位置：{{cwd}}/.dsh-home/profiles/scaffold + - text: 失败 $ pnpm add silent-package 退出码 1 + - button "复制" + - text: "Command failed with exit code 1: {{node}} add silent-package" + - paragraph: 完整日志：{{cwd}}/.dsh-home/profiles/scaffold/.plugin-manager/logs/operation-{{suffix}}/pnpm.log diff --git a/apps/web/tests/expected/plugin-manager/header-natural-motion.expected.md b/apps/web/tests/expected/plugin-manager/header-natural-motion.expected.md index e1561e6f7c..648b1e5f3b 100644 --- a/apps/web/tests/expected/plugin-manager/header-natural-motion.expected.md +++ b/apps/web/tests/expected/plugin-manager/header-natural-motion.expected.md @@ -6,4 +6,5 @@ - Tabs / 1280px: resting title 28, actions 28, tabs 96; pinned actions 17, tabs 16, bar 66; stable range, reversible coordinates, same controls. - Tabs / 600px: resting title 28, actions 97, tabs 96; pinned actions 17, tabs 16, bar 66; stable range, reversible coordinates, same controls. - Tabs / 470px: resting title 28, actions 97, tabs 96; pinned actions 17, tabs 16, bar 66; stable range, reversible coordinates, same controls. -- Tabs / 390px: resting title 28, actions 146, tabs 96; pinned actions 66, tabs 16, bar 114; stable range, reversible coordinates, same controls. +- Tabs / 390px: resting title 28, actions 97, tabs 96; pinned actions 17, tabs 16, bar 66; stable range, reversible coordinates, same controls. +- Tabs / 320px: resting title 28, actions 146, tabs 96; pinned actions 66, tabs 16, bar 114; stable range, reversible coordinates, same controls. diff --git a/apps/web/tests/expected/plugin-manager/live-enabled.expected.md b/apps/web/tests/expected/plugin-manager/live-enabled.expected.md index ef5f479b1e..c2b51bfa59 100644 --- a/apps/web/tests/expected/plugin-manager/live-enabled.expected.md +++ b/apps/web/tests/expected/plugin-manager/live-enabled.expected.md @@ -34,14 +34,19 @@ - switch "启用 语音输入" - listitem: - button "查看 自定义插件索引": 自定义插件索引 - - text: 实验性 在插件页添加「发现」标签页，从你添加的插件索引浏览和安装插件。 + - text: 实验性 在插件页添加“发现”标签页，从你添加的插件索引中浏览和安装插件。 - status - switch "启用 自定义插件索引" - listitem: - button "查看 自动授权审查": 自动授权审查 - - text: 实验性 提供自动审查权限模式，由模型在每次工具调用前判断是否授权。 + - text: 实验性 提供“自动审查”访问模式：每次工具调用前，由模型对照你的要求检查，获准的调用立即运行，被拒绝的调用等你审批。 - status - switch "启用 自动授权审查" + - listitem: + - button "查看 变更请求与工作树": 变更请求与工作树 + - text: 实验性 跟踪每个会话的变更请求及其检查与评审，新会话也可以在 Git 工作树中开始；GitHub 通过 gh 命令行访问。 + - status + - switch "启用 变更请求与工作树" - heading "已安装插件" [level=3] - list: - listitem: diff --git a/apps/web/tests/expected/plugin-manager/manager.expected.md b/apps/web/tests/expected/plugin-manager/manager.expected.md index f76ed0ca0a..9454ad97f4 100644 --- a/apps/web/tests/expected/plugin-manager/manager.expected.md +++ b/apps/web/tests/expected/plugin-manager/manager.expected.md @@ -34,14 +34,19 @@ - switch "启用 语音输入" - listitem: - button "查看 自定义插件索引": 自定义插件索引 - - text: 实验性 在插件页添加「发现」标签页，从你添加的插件索引浏览和安装插件。 + - text: 实验性 在插件页添加“发现”标签页，从你添加的插件索引中浏览和安装插件。 - status - switch "启用 自定义插件索引" - listitem: - button "查看 自动授权审查": 自动授权审查 - - text: 实验性 提供自动审查权限模式，由模型在每次工具调用前判断是否授权。 + - text: 实验性 提供“自动审查”访问模式：每次工具调用前，由模型对照你的要求检查，获准的调用立即运行，被拒绝的调用等你审批。 - status - switch "启用 自动授权审查" + - listitem: + - button "查看 变更请求与工作树": 变更请求与工作树 + - text: 实验性 跟踪每个会话的变更请求及其检查与评审，新会话也可以在 Git 工作树中开始；GitHub 通过 gh 命令行访问。 + - status + - switch "启用 变更请求与工作树" - heading "已安装插件" [level=3] - list: - listitem: diff --git a/apps/web/tests/expected/plugin-manager/refresh.expected.md b/apps/web/tests/expected/plugin-manager/refresh.expected.md index 75dda78845..85d666fd3e 100644 --- a/apps/web/tests/expected/plugin-manager/refresh.expected.md +++ b/apps/web/tests/expected/plugin-manager/refresh.expected.md @@ -6,7 +6,7 @@ Focus at 500ms: - tooltip "刷新" failure: pending - button "刷新" [disabled] -{"busy":"true","spinners":1,"cards":11,"skeletons":0,"alerts":[],"retry":0,"toasts":[]} +{"busy":"true","spinners":1,"cards":12,"skeletons":0,"alerts":[],"retry":0,"toasts":[]} failure: settled - button "刷新" -{"busy":"false","spinners":0,"cards":11,"skeletons":0,"alerts":[],"retry":0,"toasts":["刷新失败，请重试"]} +{"busy":"false","spinners":0,"cards":12,"skeletons":0,"alerts":[],"retry":0,"toasts":["刷新失败，请重试"]} diff --git a/apps/web/tests/expected/plugin-market/toolbar-responsive.expected.md b/apps/web/tests/expected/plugin-market/toolbar-responsive.expected.md new file mode 100644 index 0000000000..fb4759ef7f --- /dev/null +++ b/apps/web/tests/expected/plugin-market/toolbar-responsive.expected.md @@ -0,0 +1,8 @@ +# Discover toolbar responsive layout + +- 390px: wrapped rows; index, search, labels, sort, and refresh are contained, reachable, and separate; no horizontal overflow; search focus retained. +- 430px: wrapped rows; index, search, labels, sort, and refresh are contained, reachable, and separate; no horizontal overflow; search focus retained. +- 768px: single row; index, search, labels, sort, and refresh are contained, reachable, and separate; no horizontal overflow; search focus retained. +- 1280px: single row; index, search, labels, sort, and refresh are contained, reachable, and separate; no horizontal overflow; search focus retained. + +At 390px, restoring the previous no-wrap layout causes horizontal overflow and fails the same layout check. Removing that override restores the controls and preserves search focus. diff --git a/apps/web/tests/expected/schedule-header.expected.md b/apps/web/tests/expected/schedule-header.expected.md index 96bff76bee..eb305c44f7 100644 --- a/apps/web/tests/expected/schedule-header.expected.md +++ b/apps/web/tests/expected/schedule-header.expected.md @@ -7,7 +7,7 @@ en 440px: title and New single-line, New beside the title; contained; New retain en 390px: title and New single-line, New beside the title; contained; New retains focus en 430px: title and New single-line, New beside the title; contained; New retains focus en 1024px: title and New single-line, New beside the title; contained; New retains focus -en 509px with sidebar expanded: title single-line; New moves below the title +en 220px page column: title single-line; New moves below the title zh 1680px: title and New single-line, New beside the title; contained; New retains focus zh 800px: title and New single-line, New beside the title; contained; New retains focus zh 520px: title and New single-line, New beside the title; contained; New retains focus diff --git a/apps/web/tests/expected/shared-inspector/metadata-en.expected.md b/apps/web/tests/expected/shared-inspector/metadata-en.expected.md index 8a700d7178..e030d3d965 100644 --- a/apps/web/tests/expected/shared-inspector/metadata-en.expected.md +++ b/apps/web/tests/expected/shared-inspector/metadata-en.expected.md @@ -1,5 +1,5 @@ - bundle: Developer tools - description: Inspect and debug raw session data, grouped chat messages, and the NodeJS backend. + description: For troubleshooting: view what DSH recorded for a session in Session log, inspect per-turn and per-step statistics in the Statistics tab, and debug the DSH backend in Chrome DevTools. - component: NodeJS inspector description: Press Ctrl/Cmd+Shift+. to open Chrome DevTools in the bottom panel for development and debugging. - component: Session log diff --git a/apps/web/tests/expected/shared-inspector/metadata-zh.expected.md b/apps/web/tests/expected/shared-inspector/metadata-zh.expected.md index ac290833d9..25e2845741 100644 --- a/apps/web/tests/expected/shared-inspector/metadata-zh.expected.md +++ b/apps/web/tests/expected/shared-inspector/metadata-zh.expected.md @@ -1,5 +1,5 @@ - bundle: 开发者工具 - description: 查看调试会话原始数据、聊天消息分组数据，以及调试 NodeJS 后端 + description: 用于排查问题：在「会话数据诊断」中查看 DSH 为会话记录的内容，在「统计」页签查看每轮/每步的上下文、耗时、缓存和工具成本，并在 Chrome DevTools 中调试 DSH 后端。 - component: NodeJS 诊断 description: 按 Ctrl/Cmd+Shift+. 在底部面板打开 Chrome DevTools 进行开发调试 - component: 会话数据诊断 diff --git a/apps/web/tests/expected/shortcuts-panels/page-actions.expected.md b/apps/web/tests/expected/shortcuts-panels/page-actions.expected.md index 63ee48e589..d3e05295e9 100644 --- a/apps/web/tests/expected/shortcuts-panels/page-actions.expected.md +++ b/apps/web/tests/expected/shortcuts-panels/page-actions.expected.md @@ -18,6 +18,7 @@ - button "Split" [disabled] - text: {{cwd}}/workspace - button "Reload" -- list: - - listitem: - - button "t6-refresh.txt" +- complementary "Workspace files": + - list: + - listitem: + - button "t6-refresh.txt" diff --git a/apps/web/tests/expected/shortcuts-panels/panels.expected.md b/apps/web/tests/expected/shortcuts-panels/panels.expected.md index 7b6537870e..5cced821c6 100644 --- a/apps/web/tests/expected/shortcuts-panels/panels.expected.md +++ b/apps/web/tests/expected/shortcuts-panels/panels.expected.md @@ -21,5 +21,6 @@ - button "Split" [disabled] - text: {{cwd}}/workspace - button "Reload" -- list: - - listitem: Empty directory +- complementary "Workspace files": + - list: + - listitem: Empty directory diff --git a/apps/web/tests/expected/shortcuts-panels/tab-menu.expected.md b/apps/web/tests/expected/shortcuts-panels/tab-menu.expected.md index c8ab6426ab..16362fff3a 100644 --- a/apps/web/tests/expected/shortcuts-panels/tab-menu.expected.md +++ b/apps/web/tests/expected/shortcuts-panels/tab-menu.expected.md @@ -1,2 +1,3 @@ - menu: - menuitem "Close" + - menuitem "Close Other Tabs" [disabled] diff --git a/apps/web/tests/expected/shortcuts-workspace/files-open.expected.md b/apps/web/tests/expected/shortcuts-workspace/files-open.expected.md index 9c7cf15731..8768d85619 100644 --- a/apps/web/tests/expected/shortcuts-workspace/files-open.expected.md +++ b/apps/web/tests/expected/shortcuts-workspace/files-open.expected.md @@ -2,5 +2,6 @@ - button "Reload" - button "Open in Finder" - button "More ways to open" -- list: - - listitem: Empty directory +- complementary "Workspace files": + - list: + - listitem: Empty directory diff --git a/apps/web/tests/expected/shortcuts-workspace/session-menu.expected.md b/apps/web/tests/expected/shortcuts-workspace/session-menu.expected.md index ebb1786386..6724e2373d 100644 --- a/apps/web/tests/expected/shortcuts-workspace/session-menu.expected.md +++ b/apps/web/tests/expected/shortcuts-workspace/session-menu.expected.md @@ -2,5 +2,8 @@ - menuitem "Pin session" - menuitem "Rename" - menuitem "Fork session" - - menuitem "Archive session" + - separator - menuitem "Copy Session ID" + - menuitem "Show in Finder" + - separator + - menuitem "Archive session" diff --git a/apps/web/tests/expected/sidebar-alignment/account-signed-in.expected.md b/apps/web/tests/expected/sidebar-alignment/account-signed-in.expected.md new file mode 100644 index 0000000000..81589bea33 --- /dev/null +++ b/apps/web/tests/expected/sidebar-alignment/account-signed-in.expected.md @@ -0,0 +1,20 @@ +{ + "wide": { + "height": 44, + "width": 260, + "footerCenterOffset": 0, + "leftOffset": -2, + "rightOffset": 2, + "paintedLeftOffset": -2, + "paintedRightOffset": 2 + }, + "rail": { + "height": 36, + "width": 36, + "footerCenterOffset": 0, + "leftOffset": -0.5, + "rightOffset": -0.5, + "paintedLeftOffset": -0.5, + "paintedRightOffset": -0.5 + } +} diff --git a/apps/web/tests/expected/sidebar-alignment/account-signed-out.expected.md b/apps/web/tests/expected/sidebar-alignment/account-signed-out.expected.md new file mode 100644 index 0000000000..3bacdca875 --- /dev/null +++ b/apps/web/tests/expected/sidebar-alignment/account-signed-out.expected.md @@ -0,0 +1,20 @@ +{ + "wide": { + "height": 32, + "width": 264, + "footerCenterOffset": 0, + "leftOffset": -4, + "rightOffset": 4, + "paintedLeftOffset": -1, + "paintedRightOffset": 1 + }, + "rail": { + "height": 36, + "width": 36, + "footerCenterOffset": 0, + "leftOffset": -0.5, + "rightOffset": -0.5, + "paintedLeftOffset": -0.5, + "paintedRightOffset": -0.5 + } +} diff --git a/apps/web/tests/expected/sidebar-alignment/geometry.expected.md b/apps/web/tests/expected/sidebar-alignment/geometry.expected.md new file mode 100644 index 0000000000..5282e0ea90 --- /dev/null +++ b/apps/web/tests/expected/sidebar-alignment/geometry.expected.md @@ -0,0 +1,7 @@ +# Sidebar alignment + +- search title is clipped: true +- unarchive hit target width: 24px +- clipped search title label gap: 6px +- clipped search title clearance from unarchive hit target: 2px +- clipped search title edge hit-tests to title: true diff --git a/apps/web/tests/expected/sidebar-drawer.expected.md b/apps/web/tests/expected/sidebar-drawer.expected.md new file mode 100644 index 0000000000..fafb1402b2 --- /dev/null +++ b/apps/web/tests/expected/sidebar-drawer.expected.md @@ -0,0 +1,24 @@ +390px: closed sidebar has no rail; main width 390px +open: main geometry retained; background inert; no resize handle +close: Session navigation, Plugins navigation, mask and Escape +retained: sidebar DOM and opener focus +768px: 56px rail; main width 712px; drawer focus transfers to the rail toggle +breakpoint motion: collapsed rail hides immediately and returns compact without crossfades; expanded sidebar and explicit toggles retain their slides +767px: hidden drawer; main width 767px; no page overflow +global panels: browser top inset 48px; macOS keeps its existing clearance +tooltips: sidebar and workspace controls escape the drawer and fit the viewport +search input: 16px on touch; 13px with a fine pointer +simulated keyboard: homepage and drawer retain 844px layout height without following the 360px visual viewport; Settings stays within the viewport +keyboard close: layout height stays 844px; sidebar search retained; Settings close remains reachable +shell coverage: drawer backing and mask cover 844px without synthetic safe-area insets +rotation: 844x390 then 390x844 restores shell height and sidebar breakpoint +folded landscape: 951px frame splits at 475.5px without a resize handle; unfolding restores 280px and search focus; portrait retains the drawer +fold transitions: sidebar controls follow the divider in both directions; reduced motion changes width without animation +drawer mask: opacity transitions from 0 to 1 on open and 1 to 0 on close +reduced motion: drawer and mask settle without transitions +Web header: only the sidebar opener remains, with 48px leading clearance +below 768px: plugin and automation pages use 20px insets; Web view tabs align at 20px, while Desktop and wider Web tabs retain 28px +touch selected Session: More remains visible; update time is hidden; pinned rows offer Unpin before More with Workspace action spacing +touch Workspace: actions appear only while expanded, including after folding the focused row +fine pointer: folded Workspace actions remain available on hover +fine pointer: selected Session actions stay hidden until hover, including at 390px diff --git a/apps/web/tests/expected/sidebar-menu-dismissal.expected.md b/apps/web/tests/expected/sidebar-menu-dismissal.expected.md new file mode 100644 index 0000000000..585e3877cd --- /dev/null +++ b/apps/web/tests/expected/sidebar-menu-dismissal.expected.md @@ -0,0 +1,2 @@ +View options and Session menus close when the sidebar becomes an inert drawer. +Focus returns to the visible sidebar opener; retained Session rows keep their DOM identity. diff --git a/apps/web/tests/file-browser-composition.e2e.ts b/apps/web/tests/file-browser-composition.e2e.ts new file mode 100644 index 0000000000..1232279de2 --- /dev/null +++ b/apps/web/tests/file-browser-composition.e2e.ts @@ -0,0 +1,63 @@ +/** + * The workspace file browser and the document preview each work without the + * other in the shipped Web composition: without the preview the files page + * lists the workspace and leaves files it cannot open unclickable; without the + * file browser a preview opens with no navigator or toggle beside it. + */ +import { mkdir, readFile, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { chromium } from 'playwright' +import { expect, it, onTestFailed, onTestFinished } from 'vitest' +import { launchWebScaffold, seedSession, watchConsole, type WebScaffold } from './scaffold.ts' +import { newEnglishPage, saveFailureShot } from './support.ts' + +/** A settled Session whose answer links `src/example.txt`, borrowed from the Markdown file links case. */ +const SEED = fileURLToPath(new URL('../../../snapshots/web/markdown-file-links/session.v3.jsonl', import.meta.url)) + +/** Boot the composition with one plugin disabled, a workspace holding `src/example.txt`, and the seeded Session open. */ +async function open(overlay: string, name: string) { + const scaffold: WebScaffold = await launchWebScaffold({ extraOverlayPath: fileURLToPath(new URL(overlay, import.meta.url)) }) + onTestFinished(() => scaffold.close()) + await mkdir(join(scaffold.workspaceCwd, 'src')) + await writeFile(join(scaffold.workspaceCwd, 'src/example.txt'), Array.from({ length: 40 }, (_, i) => `source line ${i + 1}\n`).join('')) + await seedSession(scaffold, await readFile(SEED, 'utf8'), name) + const browser = await chromium.launch() + onTestFinished(() => browser.close()) + const page = await newEnglishPage(browser) + onTestFailed(() => saveFailureShot(page, `web-e2e-${name}`)) + const errors = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.locator('[role="treeitem"]').first().click() + await page.locator('[role="treeitem"]').nth(1).click() + await page.getByRole('button', { name: 'src/example.txt:24–30', exact: true }).waitFor() + return { page, errors, column: page.locator('[data-rightbar-col]') } +} + +it('lists the workspace without the document preview, leaving files nothing can open unclickable', async () => { + const { page, errors, column } = await open('./no-sidebar-documentpreview.overlay.yml', 'composition-no-preview') + await page.locator('[data-sidebar-right-expand]').click() + await column.locator('[data-sidebar-right-guide-entry="files"]').click() + const navigator = column.locator('[data-files-navigator]') + await navigator.getByRole('button', { name: 'src', exact: true }).click() + const row = navigator.locator('[data-files-path$="/src/example.txt"]') + await row.waitFor() + expect(await row.locator('button').count()).toBe(0) + expect(await row.locator('[aria-disabled="true"]').getAttribute('title')).toBe('No viewer can open this file.') + const tabs = await column.locator('[data-dockkit-tab]').count() + await row.click() + expect(await column.locator('[data-dockkit-tab]').count()).toBe(tabs) + expect(await column.locator('[data-files-page]').count()).toBe(1) + expect(errors).toEqual({ warnings: [], pageErrors: [] }) +}, 120_000) + +it('previews a linked file without the file browser, with no navigator or toggle beside it', async () => { + const { page, errors, column } = await open('./no-sidebar-files.overlay.yml', 'composition-no-files') + await page.getByRole('button', { name: 'src/example.txt:24–30', exact: true }).click() + await expect.poll(() => column.locator('[data-textpreview-target="24"]').textContent()).toBe('source line 24\n') + expect(await column.locator('[data-files-navigator], [data-files-navigator-toggle]').count()).toBe(0) + expect(await column.locator('[data-textpreview-content] > *').evaluateAll(children => + children.map(child => child.hasAttribute('data-textpreview-body')))).toEqual([true]) + expect(await column.locator('[data-sidebar-right-guide-entry="files"]').count()).toBe(0) + expect(errors).toEqual({ warnings: [], pageErrors: [] }) +}, 120_000) diff --git a/apps/web/tests/file-browser.e2e.ts b/apps/web/tests/file-browser.e2e.ts new file mode 100644 index 0000000000..0032ed22ef --- /dev/null +++ b/apps/web/tests/file-browser.e2e.ts @@ -0,0 +1,539 @@ +/** + * The workspace file browser over the shipped Web composition, a real + * workspace and the real dock, across docked and floating panes and a + * phone-width viewport. The package README owns the behavior asserted here. + */ +import { mkdir, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { chromium, type Locator, type Page } from 'playwright' +import { expect, it, onTestFailed, onTestFinished } from 'vitest' +import { createLaunchEnvironmentSnapshot, type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment' +import { launchWebScaffold, watchConsole } from './scaffold.ts' +import { connectFreshWorkspace, saveFailureShot } from './support.ts' + +/** Press at the centre of `from`, travel in steps, and release at `to`. */ +async function drag(page: Page, from: Locator, to: { x: number; y: number }): Promise { + const box = await from.boundingBox() + if (box === null) throw new Error('drag source is not rendered') + await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2) + await page.mouse.down() + await page.mouse.move(to.x, to.y, { steps: 12 }) + await page.mouse.up() +} + +/** Resize through the hit-tested corner, rather than dispatching events through covering content. */ +async function resizeFloat(page: Page, panel: Locator, width: number, height: number): Promise { + const before = await panel.boundingBox() + const handle = panel.locator('[data-dockkit-float-resize]') + const grip = await handle.boundingBox() + if (before === null || grip === null) throw new Error('floating resize geometry is not rendered') + await expect.poll(() => handle.evaluate((node) => { + const box = node.getBoundingClientRect() + return node.contains(document.elementFromPoint(box.x + box.width / 2, box.y + box.height / 2)) + })).toBe(true) + await drag(page, handle, { + x: grip.x + grip.width / 2 + width - before.width, + y: grip.y + grip.height / 2 + height - before.height, + }) + await expect.poll(async () => { + const after = await panel.boundingBox() + return after === null ? Infinity : Math.max(Math.abs(after.width - width), Math.abs(after.height - height)) + }).toBeLessThanOrEqual(1) +} + +/** Boot the shipped Web composition into a settled Session whose workspace holds `src/{a,b,c}.txt`, `README.md`, and `focus.html`. */ +async function openWorkspace( + shot: string, + openInAppEnvironment?: LaunchEnvironmentSnapshot, +): Promise<{ page: Page; input: Locator; errors: ReturnType }> { + const scaffold = await launchWebScaffold({ + replayFixture: fileURLToPath(new URL('../../../snapshots/web/lifecycle-chrome/session.v3.jsonl', import.meta.url)), + paceMs: 5, compareReplaySession: false, ...openInAppEnvironment === undefined ? {} : { openInAppEnvironment }, + }) + onTestFinished(() => scaffold.close()) + const browser = await chromium.launch() + onTestFinished(() => browser.close()) + const page = await browser.newPage({ locale: 'en-US', viewport: { width: 1680, height: 1000 } }) + await page.addInitScript(() => { Object.defineProperty(navigator, 'platform', { value: 'Win32' }) }) + onTestFailed(() => saveFailureShot(page, shot)) + const errors = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await connectFreshWorkspace(page, scaffold.workspaceCwd, 'test workspace') + const settled = scaffold.whenTurnSettled() + const input = page.locator('[data-composer-input]').first() + await input.fill('Reply with the single word LIGHTHOUSE and stop.') + await input.press('Enter') + const session = await settled + const cwd = scaffold.ctx.agents.get(session)?.session.header.cwd + if (cwd === undefined) throw new Error('Session has no workspace') + await mkdir(join(cwd, 'src')) + const lines = (name: string): string => Array.from({ length: 300 }, (_, index) => `${name} line ${index}\n`).join('') + await writeFile(join(cwd, 'src', 'a.txt'), lines('a')) + await writeFile(join(cwd, 'src', 'b.txt'), lines('b')) + await writeFile(join(cwd, 'src', 'c.txt'), lines('c')) + await writeFile(join(cwd, 'README.md'), '# Readme\n') + await writeFile(join(cwd, 'focus.html'), '') + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + return { page, input, errors } +} + +it('browses workspace files in tabs that share one pane tree', async () => { + const { page, input, errors } = await openWorkspace('web-e2e-file-browser') + await page.locator('[data-sidebar-right-expand]').click() + const column = page.locator('[data-rightbar-col]') + const layout = await page.addStyleTag({ content: '[data-sidebar-right-panel] { width: 960px !important; }' }) + await column.locator('[data-sidebar-right-guide-entry="files"]').click() + const tabs = column.locator('[data-dockkit-tab]') + const navigator = column.locator('[data-files-navigator]:visible') + const toggle = column.locator('[data-files-navigator-toggle]:visible') + const body = column.locator('[data-textpreview-state]:visible [data-textpreview-body]') + const path = column.locator('[data-textpreview-path]:visible') + const current = navigator.locator('[aria-current="true"]') + await column.locator('[data-files-page]').waitFor() + // The page's tree fills the page and stays shown: no toggle, no resize edge, and Escape leaves it. + await navigator.waitFor() + expect(await toggle.count()).toBe(0) + expect(await navigator.getByRole('separator').count()).toBe(0) + const pageContent = await column.locator('[data-files-content]').boundingBox() + const pageTree = await navigator.boundingBox() + if (pageContent === null || pageTree === null) throw new Error('files page geometry is not rendered') + expect(Math.abs(pageTree.width - pageContent.width)).toBeLessThanOrEqual(1) + await navigator.getByRole('button', { name: 'src', exact: true }).focus() + await page.keyboard.press('Escape') + expect(await navigator.count()).toBe(1) + const pageTab = await tabs.last().getAttribute('data-dockkit-tab') + const tabCount = await tabs.count() + + // The page stays and opens the first file in a new tab after it in its pane, where the file's tree starts hidden. + await navigator.getByRole('button', { name: 'src', exact: true }).click() + await navigator.getByRole('button', { name: 'a.txt', exact: true }).click() + await expect.poll(() => path.textContent()).toContain('a.txt') + expect(await tabs.count()).toBe(tabCount + 1) + expect(await column.locator(`[data-dockkit-tab="${pageTab}"]`).count()).toBe(1) + expect(await column.locator('[data-dockkit-pane]').count()).toBe(1) + expect(await toggle.getAttribute('aria-expanded')).toBe('false') + // Picking the open file again from the page switches back to its tab, which is the visible change, so nothing glows. + const flash = column.locator('[data-sidebar-right-flash]') + await column.locator(`[data-dockkit-tab="${pageTab}"]`).click() + await navigator.getByRole('button', { name: 'a.txt', exact: true }).click() + await expect.poll(() => path.textContent()).toContain('a.txt') + expect(await flash.count()).toBe(0) + expect(await tabs.count()).toBe(tabCount + 1) + // The preview's toggle shows the pane's tree without changing the files page. + await toggle.click() + await expect.poll(() => toggle.getAttribute('aria-expanded')).toBe('true') + await expect.poll(() => current.textContent()).toBe('a.txt') + // Picking the open file again while its glow plays restarts the glow, which then lasts its whole 600ms animation. + const openFile = navigator.getByRole('button', { name: 'a.txt', exact: true }) + await openFile.click() + // A glow replaced before it starts is dropped without a cancellation, so the repeat waits until the first one plays. + await expect.poll(() => flash.evaluate(pane => pane.getAnimations({ subtree: true }) + .some(glow => Number(glow.currentTime) > 100))).toBe(true) + const first = await flash.getAttribute('data-sidebar-right-flash') + const repeat = await openFile.evaluate((button) => { + const pane = button.closest('[data-sidebar-right-flash]') + if (pane === null) throw new Error('the open file is outside the glowing pane') + const since = performance.now() + return new Promise<{ mark: string | undefined; lasted: number }>((resolve) => { + let mark: string | undefined + new MutationObserver((_, observer) => { + mark = pane.dataset.sidebarRightFlash ?? mark + if (pane.dataset.sidebarRightFlash !== undefined) return + observer.disconnect() + resolve({ mark, lasted: performance.now() - since }) + }).observe(pane, { attributes: true, attributeFilter: ['data-sidebar-right-flash'] }) + ;(button as HTMLElement).click() + }) + }) + expect(repeat.mark).toBe(first === 'odd' ? 'even' : 'odd') + expect(repeat.lasted).toBeGreaterThan(450) + + // In a wide row the tree is a card beside the preview: the body narrows by the card and its 8px margins, and still scrolls. + await column.locator('[data-files-navigator-mode="push"]:visible').waitFor() + const wideRow = await body.locator('..').boundingBox() + const wideBody = await body.boundingBox() + const wideTree = await navigator.boundingBox() + if (wideRow === null || wideBody === null || wideTree === null) throw new Error('preview row is not rendered') + expect(Math.abs(wideBody.width - (wideRow.width - wideTree.width - 16))).toBeLessThanOrEqual(1) + expect(wideTree.x).toBeGreaterThanOrEqual(wideBody.x + wideBody.width + 7) + await expect.poll(() => body.evaluate(node => node.scrollHeight > node.clientHeight)).toBe(true) + await page.mouse.move(wideBody.x + 40, wideBody.y + 80) + await page.mouse.wheel(0, 400) + await expect.poll(() => body.evaluate(node => node.scrollTop)).toBeGreaterThan(0) + // A press on the preview leaves the tree shown. + await page.mouse.click(wideBody.x + 40, wideBody.y + 80) + expect(await toggle.getAttribute('aria-expanded')).toBe('true') + + await toggle.focus() + // In dark mode the card takes the filled tree's background, with a soft white shadow. + const theme = await page.locator('body').getAttribute('data-ds-dark-theme') + try { + await page.evaluate(() => { document.body.setAttribute('data-ds-dark-theme', '') }) + const cardPaint = await navigator.evaluate(node => ({ + background: getComputedStyle(node).backgroundColor, + shadow: getComputedStyle(node).boxShadow, + })) + expect(cardPaint.shadow).toContain('color(srgb 1 1 1 / 0.08)') + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 360px !important; }' }) + await column.locator('[data-files-navigator-mode="fill"]:visible').waitFor() + expect(await navigator.evaluate(node => getComputedStyle(node).backgroundColor)).toBe(cardPaint.background) + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 960px !important; }' }) + await navigator.getByRole('separator').waitFor() + } finally { + await page.evaluate((value) => { + if (value === null) document.body.removeAttribute('data-ds-dark-theme') + else document.body.setAttribute('data-ds-dark-theme', value) + }, theme) + } + + // The reader scrolls the preview and widens the tree. + await body.evaluate((node) => { node.scrollTop = 900 }) + const edge = navigator.getByRole('separator', { name: 'Resize file tree' }) + const grip = await edge.boundingBox() + if (grip === null) throw new Error('resize edge is not rendered') + await page.mouse.move(grip.x + grip.width / 2, grip.y + 120) + await page.mouse.down() + await page.mouse.move(grip.x + grip.width / 2 - 40, grip.y + 120, { steps: 4 }) + await page.mouse.up() + await expect.poll(() => edge.getAttribute('aria-valuenow')).toBe('300') + + // The files page appends another preview; it shares the pane's tree choice and width. + await column.locator(`[data-dockkit-tab="${pageTab}"]`).click() + await navigator.getByRole('button', { name: 'b.txt', exact: true }).click() + await column.locator(`[data-dockkit-tab="${pageTab}"]`).hover() + await column.locator(`[data-dockkit-tab-close="${pageTab}"]`).click() + await expect.poll(() => path.textContent()).toContain('b.txt') + expect(await tabs.count()).toBe(tabCount + 1) + await expect.poll(() => current.textContent()).toBe('b.txt') + expect(await navigator.getByRole('button', { name: 'src', exact: true }).getAttribute('aria-expanded')).toBe('true') + expect(await edge.getAttribute('aria-valuenow')).toBe('300') + + // Clicking an open file returns to its tab, where the reader left off. + await navigator.getByRole('button', { name: 'a.txt', exact: true }).click() + await expect.poll(() => path.textContent()).toContain('a.txt') + expect(await tabs.count()).toBe(tabCount + 1) + await expect.poll(() => body.evaluate(node => node.scrollTop)).toBe(900) + await expect.poll(() => current.textContent()).toBe('a.txt') + + // Workspace navigation has one open action; the row's shared context menu does not offer a second new-tab route. + await navigator.getByRole('button', { name: 'a.txt', exact: true }).click({ button: 'right' }) + const rowMenu = page.locator('[data-context-menu][role="menu"]') + await rowMenu.waitFor() + expect(await page.getByRole('menuitem', { name: 'Open in new tab', exact: true }).count()).toBe(0) + await page.keyboard.press('Escape') + await rowMenu.waitFor({ state: 'detached' }) + + // A narrower pane floats the tree over the preview below its header; the body keeps the row's width and still scrolls. + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 460px !important; }' }) + await column.locator('[data-files-navigator-mode="overlay"]:visible').waitFor() + const header = await path.locator('..').boundingBox() + const tree = await navigator.boundingBox() + if (header === null || tree === null) throw new Error('browser geometry is not rendered') + expect(tree.y).toBeGreaterThanOrEqual(header.y + header.height - 1) + const middleRow = await body.locator('..').boundingBox() + const preview = await body.boundingBox() + if (middleRow === null || preview === null) throw new Error('preview body is not rendered') + expect(preview.width).toBeGreaterThan(middleRow.width - 1) + await body.evaluate((node) => { node.scrollTop = 0 }) + await page.mouse.move(preview.x + 20, preview.y + 80) + await page.mouse.wheel(0, 400) + await expect.poll(() => body.evaluate(node => node.scrollTop)).toBeGreaterThan(0) + await navigator.getByRole('button', { name: 'b.txt', exact: true }).click() + await expect.poll(() => current.textContent()).toBe('b.txt') + // The keyboard stays in the tree the revealed tab draws, so Escape reaches the row. + await expect.poll(() => current.evaluate(node => node === document.activeElement)).toBe(true) + await page.keyboard.press('Escape') + await expect.poll(() => toggle.getAttribute('aria-expanded')).toBe('false') + expect(await navigator.count()).toBe(0) + expect(await toggle.evaluate(node => node === document.activeElement)).toBe(true) + + // A row narrower than 400px is filled by the tree, without the resize edge; Escape still closes it. + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 360px !important; }' }) + await toggle.click() + await column.locator('[data-files-navigator-mode="fill"]:visible').waitFor() + const narrowRow = await body.locator('..').boundingBox() + const narrowTree = await navigator.boundingBox() + if (narrowRow === null || narrowTree === null) throw new Error('narrow geometry is not rendered') + expect(Math.abs(narrowTree.width - narrowRow.width)).toBeLessThanOrEqual(1) + expect(await navigator.getByRole('separator').count()).toBe(0) + expect(await body.evaluate(node => getComputedStyle(node).visibility)).toBe('hidden') + await toggle.focus() + await page.keyboard.press('Tab') + expect(await body.evaluate(node => node.contains(document.activeElement))).toBe(false) + expect(await navigator.evaluate(node => node.contains(document.activeElement))).toBe(true) + await navigator.getByRole('button', { name: 'b.txt', exact: true }).focus() + await page.keyboard.press('Escape') + await expect.poll(() => toggle.getAttribute('aria-expanded')).toBe('false') + + // A phone-width viewport fills the row below the header with the tree, without the resize edge, and opening a file hides it. + // The resize edge holding the keyboard when the viewport narrows hands it to the tree. + await layout.evaluate((node) => { node.textContent = '' }) + await toggle.click() + const resizeEdge = navigator.getByRole('separator', { name: 'Resize file tree' }) + await resizeEdge.focus() + expect(await resizeEdge.evaluate(node => node === document.activeElement)).toBe(true) + await page.setViewportSize({ width: 390, height: 844 }) + await expect.poll(() => navigator.evaluate(node => node.contains(document.activeElement) + && !document.activeElement?.hasAttribute('data-files-navigator-resize'))).toBe(true) + // The panel slides into its fullscreen place, so the geometry is read once it settles. + await expect.poll(async () => { + const row = await body.locator('..').boundingBox() + const filled = await navigator.boundingBox() + return row === null || filled === null ? Number.POSITIVE_INFINITY : Math.abs(filled.width - row.width) + }).toBeLessThanOrEqual(1) + expect(await navigator.getByRole('separator').count()).toBe(0) + await navigator.getByRole('button', { name: 'a.txt', exact: true }).click() + await expect.poll(() => path.textContent()).toContain('a.txt') + await expect.poll(() => toggle.getAttribute('aria-expanded')).toBe('false') + expect(await navigator.count()).toBe(0) + await page.setViewportSize({ width: 1680, height: 1000 }) + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 460px !important; }' }) + + // The workspace command shows the pane's tree, moves the keyboard into it, and keeps the file. + await input.focus() + await page.keyboard.press('Control+Alt+p') + await expect.poll(() => toggle.getAttribute('aria-expanded')).toBe('true') + await expect.poll(() => current.evaluate(node => node === document.activeElement)).toBe(true) + await expect.poll(() => path.textContent()).toContain('a.txt') + expect(await tabs.count()).toBe(tabCount + 1) + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 960px !important; }' }) + + await column.locator('[data-dockkit-add-tab]').click() + await column.locator('[data-sidebar-right-guide-entry="files"]').click() + const htmlFilesTab = await tabs.filter({ hasText: 'Files' }).getAttribute('data-dockkit-tab') + await navigator.getByRole('button', { name: 'focus.html', exact: true }).click() + await column.locator(`[data-dockkit-tab="${htmlFilesTab}"]`).hover() + await column.locator(`[data-dockkit-tab-close="${htmlFilesTab}"]`).click() + await expect.poll(() => path.textContent()).toContain('focus.html') + const frame = body.locator('[data-html-preview]') + await frame.waitFor() + for (const narrow of ['row', 'viewport'] as const) { + await toggle.focus() + if (narrow === 'row') await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 360px !important; }' }) + else await page.setViewportSize({ width: 390, height: 844 }) + await expect.poll(() => body.evaluate(node => getComputedStyle(node).visibility)).toBe('hidden') + await page.keyboard.press('Tab') + expect(await navigator.evaluate(node => node.contains(document.activeElement))).toBe(true) + expect(await body.evaluate(node => node.contains(document.activeElement))).toBe(false) + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 960px !important; }' }) + await page.setViewportSize({ width: 1680, height: 1000 }) + await expect.poll(() => body.evaluate(node => getComputedStyle(node).visibility)).toBe('visible') + await frame.focus() + if (narrow === 'row') await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 360px !important; }' }) + else await page.setViewportSize({ width: 390, height: 844 }) + await expect.poll(() => body.evaluate(node => getComputedStyle(node).visibility)).toBe('hidden') + expect(await toggle.getAttribute('aria-expanded')).toBe('true') + await expect.poll(() => navigator.evaluate(node => node.contains(document.activeElement))).toBe(true) + expect(await frame.evaluate(node => document.activeElement === node)).toBe(false) + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 960px !important; }' }) + await page.setViewportSize({ width: 1680, height: 1000 }) + await expect.poll(() => body.evaluate(node => getComputedStyle(node).visibility)).toBe('visible') + } + + // A preview dragged out into a floating panel keeps where the reader was in it. + await tabs.filter({ hasText: 'b.txt' }).click() + await expect.poll(() => path.textContent()).toContain('b.txt') + await body.evaluate((node) => { node.scrollTop = 600 }) + await expect.poll(() => body.evaluate(node => node.scrollTop)).toBe(600) + const surface = await page.locator('[data-dockkit-surface]').first().boundingBox() + if (surface === null) throw new Error('surface is not rendered') + await drag(page, tabs.filter({ hasText: 'b.txt' }), { x: surface.x - 240, y: surface.y + surface.height / 2 }) + const float = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]') + await expect.poll(() => float.count()).toBe(1) + const floatPath = float.locator('[data-textpreview-path]') + await floatPath.waitFor() + const floatBody = float.locator('[data-textpreview-state] [data-textpreview-body]') + await expect.poll(() => floatBody.evaluate(node => node.scrollTop)).toBe(600) + // The panel is a new pane, so its tree starts hidden; shown, it draws there too, and the panel keeps its resize handle. + const floatToggle = float.locator('[data-files-navigator-toggle]') + expect(await floatToggle.getAttribute('aria-expanded')).toBe('false') + expect(await float.locator('[data-files-navigator]').count()).toBe(0) + await floatToggle.click() + const before = await float.boundingBox() + if (before === null) throw new Error('float is not rendered') + const resize = float.locator('[data-dockkit-float-resize]') + await drag(page, resize, { x: before.x + Math.max(before.width + 80, 560), y: before.y + before.height + 60 }) + await expect.poll(async () => (await float.boundingBox())?.width ?? before.width).toBeGreaterThan(before.width) + // Wide enough that the tree does not fill the panel. + expect((await float.boundingBox())!.width).toBeGreaterThanOrEqual(440) + const floatTree = float.locator('[data-files-navigator]') + await floatTree.waitFor() + expect(await floatToggle.getAttribute('aria-expanded')).toBe('true') + // Resize while the tree is open, through both sides of its fill breakpoint. + const openBox = await float.boundingBox() + if (openBox === null) throw new Error('floating preview is not rendered') + await resizeFloat(page, float, 360, openBox.height - 20) + await float.locator('[data-files-navigator-mode="fill"]').waitFor() + await resizeFloat(page, float, 560, openBox.height) + expect(await floatTree.count()).toBe(1) + const floatPane = await float.getAttribute('data-dockkit-float') + // A file nothing shows replaces the preview in its panel, which keeps its pane and its tree. + await floatTree.getByRole('button', { name: 'README.md', exact: true }).click() + await expect.poll(() => floatPath.textContent()).toContain('README.md') + expect(await float.count()).toBe(1) + expect(await float.getAttribute('data-dockkit-float')).toBe(floatPane) + expect(await float.locator('[data-files-navigator] [aria-current="true"]').textContent()).toBe('README.md') + // Navigating to the floating preview itself exposes its file when its tree fills the row. + const previewHeight = (await float.boundingBox())!.height + await resizeFloat(page, float, 360, previewHeight) + await float.locator('[data-files-navigator-mode="fill"]').waitFor() + await floatTree.getByRole('button', { name: 'README.md', exact: true }).click() + await expect.poll(() => floatToggle.getAttribute('aria-expanded')).toBe('false') + await expect.poll(() => floatToggle.evaluate(node => node === document.activeElement)).toBe(true) + await floatToggle.click() + await floatTree.waitFor() + + // A file already shown is revealed in the column, which first shows another tab; the panel keeps its file. + // Revealing b.txt opened `src`. + const shown = column.locator('[data-dockkit-tab][aria-selected="true"]') + await column.locator('[data-dockkit-add-tab]').click() + await expect.poll(() => shown.textContent()).not.toContain('a.txt') + const guide = await shown.getAttribute('data-dockkit-tab') + const dockedTabs = await tabs.count() + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 360px !important; }' }) + const sourceFile = floatTree.getByRole('button', { name: 'a.txt', exact: true }) + await sourceFile.click() + await expect.poll(() => shown.textContent()).toContain('a.txt') + const dockPreview = column.locator('[data-dockkit-pane] [data-textpreview-state]:visible') + await expect.poll(() => dockPreview.locator('[data-files-navigator-toggle]').getAttribute('aria-expanded')).toBe('false') + expect(await dockPreview.locator('[data-textpreview-body]').evaluate(node => getComputedStyle(node).visibility)).toBe('visible') + expect(await floatToggle.getAttribute('aria-expanded')).toBe('true') + expect(await sourceFile.evaluate(node => node === document.activeElement)).toBe(true) + await layout.evaluate((node) => { node.textContent = '[data-sidebar-right-panel] { width: 960px !important; }' }) + await resizeFloat(page, float, 560, previewHeight) + expect(await tabs.count()).toBe(dockedTabs) + expect(await floatPath.textContent()).toContain('README.md') + expect(await float.count()).toBe(1) + expect(await tabs.filter({ hasText: 'a.txt' }).count()).toBe(1) + // The column offers a new tab again only once its guide closes. + await column.locator(`[data-dockkit-tab="${guide}"]`).hover() + await column.locator(`[data-dockkit-tab-close="${guide}"]`).click() + await expect.poll(() => column.locator(`[data-dockkit-tab="${guide}"]`).count()).toBe(0) + + // A floating files page stays and opens a file nothing shows in the active docked pane. + await column.locator('[data-dockkit-add-tab]').click() + await column.locator('[data-sidebar-right-guide-entry="files"]').click() + await column.locator('[data-files-page]').waitFor() + await drag(page, tabs.filter({ hasText: 'Files' }), { x: surface.x - 240, y: surface.y + 120 }) + await expect.poll(() => float.count()).toBe(2) + const pageFloat = float.filter({ has: page.locator('[data-files-page]') }) + const filePageBox = await pageFloat.boundingBox() + if (filePageBox === null) throw new Error('floating files page is not rendered') + await resizeFloat(page, pageFloat, 360, filePageBox.height - 20) + await page.setViewportSize({ width: 390, height: 844 }) + const phoneBox = await pageFloat.boundingBox() + if (phoneBox === null) throw new Error('phone-width files page is not rendered') + await resizeFloat(page, pageFloat, 340, phoneBox.height - 20) + expect(await pageFloat.locator('[data-files-navigator]').count()).toBe(1) + await page.setViewportSize({ width: 1680, height: 1000 }) + const docked = await tabs.count() + await pageFloat.getByRole('button', { name: 'src', exact: true }).click() + await pageFloat.getByRole('button', { name: 'c.txt', exact: true }).click() + await column.locator('[data-textpreview-path]:visible', { hasText: 'c.txt' }).waitFor() + expect(await pageFloat.count()).toBe(1) + expect(await float.count()).toBe(2) + expect(await column.locator('[data-dockkit-pane]').count()).toBe(1) + expect(await tabs.count()).toBe(docked + 1) + // A file already shown is revealed in the column, and the floating page stays with its tree. + await pageFloat.getByRole('button', { name: 'a.txt', exact: true }).click() + await expect.poll(() => column.locator('[data-dockkit-pane-active] [data-dockkit-tab][aria-selected="true"]').textContent()).toContain('a.txt') + expect(await pageFloat.count()).toBe(1) + expect(await pageFloat.locator('[data-files-navigator]').count()).toBe(1) + expect(await float.count()).toBe(2) + expect(await tabs.count()).toBe(docked + 1) + + // With the docked area emptied and the column collapsed, a file from the floating page gets a docked pane in the expanded column. + const dockTabs = column.locator('[data-dockkit-pane] [data-dockkit-tab]') + while (await dockTabs.count() > 0) { + const id = await dockTabs.first().getAttribute('data-dockkit-tab') + await dockTabs.first().hover() + await column.locator(`[data-dockkit-tab-close="${id}"]`).click() + await expect.poll(() => column.locator(`[data-dockkit-tab="${id}"]`).count()).toBe(0) + } + const expand = page.locator('[data-sidebar-right-expand]') + await expand.waitFor() + expect(await pageFloat.count()).toBe(1) + await pageFloat.getByRole('button', { name: 'b.txt', exact: true }).click() + await column.locator('[data-textpreview-path]:visible', { hasText: 'b.txt' }).waitFor() + // Past the column's slide, it stays open with the file's tab alone: no default page beside it. + await expect.poll(() => column.evaluate(node => node.getAnimations({ subtree: true }) + .filter(animation => animation.playState === 'running').length)).toBe(0) + expect(await expand.count()).toBe(0) + expect(await column.locator('[data-dockkit-pane]').count()).toBe(1) + expect(await dockTabs.count()).toBe(1) + expect(await dockTabs.first().textContent()).toContain('b.txt') + expect(await column.locator('[data-sidebar-right-guide-entry]').count()).toBe(0) + expect((await column.boundingBox())?.width ?? 0).toBeGreaterThan(200) + expect(errors).toEqual({ warnings: [], pageErrors: [] }) +}) + +it('moves a file between the docked column and a floating panel from the file menu, keeping its reading position', async () => { + // The file menu's open actions belong to Open In, which ordinary scenarios leave out; remote launch facts suppress native probes. + const { page, errors } = await openWorkspace('web-e2e-file-browser-destination', + createLaunchEnvironmentSnapshot([{ source: 'process', values: { SSH_CONNECTION: '10.0.0.2 55000 10.0.0.9 22' } }])) + const column = page.locator('[data-rightbar-col]') + const expand = page.locator('[data-sidebar-right-expand]') + const float = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]') + const docked = (name: string) => column.locator('[data-dockkit-pane] [data-dockkit-tab]', { hasText: name }) + const menu = page.locator('[data-context-menu][role="menu"]') + // The files page floats and the column collapses, so every later open starts from a floating source pane. + await expand.click() + await column.locator('[data-sidebar-right-guide-entry="files"]').click() + await column.locator('[data-files-page]').waitFor() + const surface = await page.locator('[data-dockkit-surface]').first().boundingBox() + if (surface === null) throw new Error('surface is not rendered') + await drag(page, column.locator('[data-dockkit-tab]', { hasText: 'Files' }), { x: surface.x - 240, y: surface.y + 120 }) + await expect.poll(() => float.count()).toBe(1) + await column.locator('[data-sidebar-right-toggle]').click() + await expand.waitFor() + const pageFloat = float.filter({ has: page.locator('[data-files-page]') }) + await pageFloat.getByRole('button', { name: 'src', exact: true }).click() + const row = pageFloat.getByRole('button', { name: 'a.txt', exact: true }) + const choose = async (item: string): Promise => { + await row.click({ button: 'right' }) + await menu.waitFor() + await menu.getByRole('menuitem', { name: item, exact: true }).click() + await menu.waitFor({ state: 'detached' }) + } + await row.click({ button: 'right' }) + await menu.getByRole('menuitem', { name: 'Open in floating panel', exact: true }).waitFor() + expect(await menu.getByRole('menuitem', { name: 'Open in sidebar', exact: true }).count()).toBe(1) + await page.keyboard.press('Escape') + await menu.waitFor({ state: 'detached' }) + + // A file nothing shows opens in its own floating panel; the collapsed column stays collapsed. + await choose('Open in floating panel') + await expect.poll(() => float.count()).toBe(2) + const fileFloat = float.filter({ has: page.locator('[data-textpreview-path]', { hasText: 'a.txt' }) }) + const floatBody = fileFloat.locator('[data-textpreview-state] [data-textpreview-body]') + await floatBody.waitFor() + expect(await expand.count()).toBe(1) + expect(await docked('a.txt').count()).toBe(0) + await expect.poll(() => floatBody.evaluate(node => node.scrollHeight > node.clientHeight)).toBe(true) + await floatBody.evaluate((node) => { node.scrollTop = 600 }) + await expect.poll(() => floatBody.evaluate(node => node.scrollTop)).toBe(600) + // Asking again reveals that panel rather than adding one. + await choose('Open in floating panel') + expect(await float.count()).toBe(2) + expect(await fileFloat.count()).toBe(1) + expect(await expand.count()).toBe(1) + + // The floating file moves into the expanded column, where the reader left off. + await choose('Open in sidebar') + await expect.poll(() => fileFloat.count()).toBe(0) + expect(await float.count()).toBe(1) + await expect.poll(() => expand.count()).toBe(0) + await expect.poll(() => docked('a.txt').count()).toBe(1) + const dockBody = column.locator('[data-dockkit-pane] [data-textpreview-state]:visible [data-textpreview-body]') + await expect.poll(() => dockBody.evaluate(node => node.scrollTop)).toBe(600) + + // And back out into a floating panel, leaving the column open and its strip without the file. + await choose('Open in floating panel') + await expect.poll(() => fileFloat.count()).toBe(1) + expect(await float.count()).toBe(2) + await expect.poll(() => docked('a.txt').count()).toBe(0) + expect(await expand.count()).toBe(0) + await expect.poll(() => floatBody.evaluate(node => node.scrollTop)).toBe(600) + expect(errors).toEqual({ warnings: [], pageErrors: [] }) +}) diff --git a/apps/web/tests/file-upload-round.e2e.ts b/apps/web/tests/file-upload-round.e2e.ts index 7ff564de92..9c5b5a7b33 100644 --- a/apps/web/tests/file-upload-round.e2e.ts +++ b/apps/web/tests/file-upload-round.e2e.ts @@ -279,17 +279,16 @@ describe('web e2e: generic file upload through the real assembly', () => { await expect.poll(() => send.isEnabled(), { timeout: 15_000 }).toBe(true) const settled = scaffold.whenTurnSettled() await send.click() - const restoreDeadline = Date.now() + 10_000 - let retainedCards = 0 - while (retainedCards === 0 - && !sessionEvents.some(event => event.type === 'turn/start') - && Date.now() < restoreDeadline) { + // The draft cards stay until the Host accepts the prompt, then leave with the cleared draft. + const acceptDeadline = Date.now() + 15_000 + let retainedCards = await rail.locator(':scope > *').count() + while (retainedCards !== 0 && Date.now() < acceptDeadline) { await page.waitForTimeout(100) retainedCards = await rail.locator(':scope > *').count() } if (retainedCards !== 0) { const feedback = await page.locator('[role="alert"], [role="status"]').allTextContents() - throw new Error(`submission retained ${String(retainedCards)} draft cards; feedback=${JSON.stringify(feedback)}; events=${sessionEvents.map(event => event.type).join(',')}`) + throw new Error(`the Host did not accept the submission; ${String(retainedCards)} draft cards remain; feedback=${JSON.stringify(feedback)}; events=${sessionEvents.map(event => event.type).join(',')}`) } const sessionId = await settled if (MODE === 'record') await recordFixture(scaffold, sessionId, FIXTURE) diff --git a/apps/web/tests/fixtures/markdown-colon-file-links/session.v3.jsonl b/apps/web/tests/fixtures/markdown-colon-file-links/session.v3.jsonl new file mode 100644 index 0000000000..7ef9426138 --- /dev/null +++ b/apps/web/tests/fixtures/markdown-colon-file-links/session.v3.jsonl @@ -0,0 +1,10 @@ +{"version":3,"isSeeded":false,"createdAt":0,"cwd":"{{cwd}}","delegationDepth":0,"type":"session","id":"{{session:1}}"} +{"type":"turn/start","data":{"turn":1}} +{"type":"step/start","data":{"turn":1,"step":1}} +{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{message:1}}"}},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Link src/example.txt using relative :24-30, absolute :30, and relative #L12 destinations, plus line/column and invalid locations, localhost:3000, index.ts:24, mailto:10086, and a blocked script link."}],"source":{"kind":"user","rpcId":"{{rpc:1}}"},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"} +{"type":"session/title","data":{"title":"Colon file references","messageSeqs":[3],"source":{"kind":"fallback"}}} +{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}","messagePrefix":["{{messagePrefix}}"]},"reason":"initial"}} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"[Relative colon:24–30](src/example.txt:24-30) · [Absolute colon:30]({{cwd}}/src/example.txt:30) · [Fragment:12](src/example.txt#L12) · [Column:24:5](src/example.txt:24:5) · [Zero line](src/example.txt:0) · [Reversed range](src/example.txt:30-24) · [Bare URL](index.ts:24) · [Blocked script](javascript:alert) · [Development server](localhost:3000) · [Mail](mailto:10086)"}],"source":{"provider":"deepseek-official","model":"deepseek-v4-flash","kind":"model"},"id":"{{message:3}}"},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["[Relative colon:24–30](src/example.txt:24-30) · [Absolute colon:30]({{cwd}}/src/example.txt:30) · [Fragment:12](src/example.txt#L12) · [Column:24:5](src/example.txt:24:5) · [Zero line](src/example.txt:0) · [Reversed range](src/example.txt:30-24) · [Bare URL](index.ts:24) · [Blocked script](javascript:alert) · [Development server](localhost:3000) · [Mail](mailto:10086)"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"[Relative colon:24–30](src/example.txt:24-30) · [Absolute colon:30]({{cwd}}/src/example.txt:30) · [Fragment:12](src/example.txt#L12) · [Column:24:5](src/example.txt:24:5) · [Zero line](src/example.txt:0) · [Reversed range](src/example.txt:30-24) · [Bare URL](index.ts:24) · [Blocked script](javascript:alert) · [Development server](localhost:3000) · [Mail](mailto:10086)"}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":1}} +{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/apps/web/tests/fixtures/deepseek-model-label-1017/account.overlay.yml b/apps/web/tests/fixtures/model-badge/account.overlay.yml similarity index 100% rename from apps/web/tests/fixtures/deepseek-model-label-1017/account.overlay.yml rename to apps/web/tests/fixtures/model-badge/account.overlay.yml diff --git a/apps/web/tests/fixtures/deepseek-model-label-1017/session.v4.jsonl b/apps/web/tests/fixtures/model-badge/session.v4.jsonl similarity index 100% rename from apps/web/tests/fixtures/deepseek-model-label-1017/session.v4.jsonl rename to apps/web/tests/fixtures/model-badge/session.v4.jsonl diff --git a/apps/web/tests/fixtures/plugin-market/toolbar.index.json b/apps/web/tests/fixtures/plugin-market/toolbar.index.json new file mode 100644 index 0000000000..b6b78db69e --- /dev/null +++ b/apps/web/tests/fixtures/plugin-market/toolbar.index.json @@ -0,0 +1,19 @@ +{ + "format": 1, + "title": { "en": "Awesome DSH Plugin", "zh": "Awesome DSH Plugin 插件精选" }, + "metadata": { + "categories": { "tools": { "title": { "en": "Tools", "zh": "工具与能力" } } }, + "labels": { "featured": { "title": { "en": "Featured", "zh": "精选" } } } + }, + "plugins": [ + { + "name": "dsh-toolbar-layout-fixture", + "title": { "en": "Toolbar layout fixture", "zh": "工具栏布局示例" }, + "description": { "en": "A local index for responsive toolbar checks.", "zh": "用于工具栏响应式检查的本地索引" }, + "metadata": { "category": "tools", "labels": ["featured"] }, + "versions": [ + { "version": "1.0.0", "publishTimestamp": 1793145600, "source": { "type": "npm" } } + ] + } + ] +} diff --git a/apps/web/tests/fixtures/plugins/fixture-live-client/client.js b/apps/web/tests/fixtures/plugins/fixture-live-client/client.js index 1c884c568f..db9eab44b9 100644 --- a/apps/web/tests/fixtures/plugins/fixture-live-client/client.js +++ b/apps/web/tests/fixtures/plugins/fixture-live-client/client.js @@ -101,8 +101,7 @@ window.__ModuleLoader__.load({ } }) ctx.slots.inject('sidebar.workspaces.session.menu.item', function* () { - // The shipped rows end at Session ID (450); these follow as one group, - // opened by the export row's hairline. + // Legacy rows form their own ordered group before the built-in Archive action. yield registerSessionAction('fixture.export-session', 500, 'exportSession', true) yield registerSessionAction('fixture.copy-session-id', 600, 'copySessionId', false) }) diff --git a/apps/web/tests/fold-blank-matrix.e2e.ts b/apps/web/tests/fold-blank-matrix.e2e.ts index 25b4e2d874..c46a62c711 100644 --- a/apps/web/tests/fold-blank-matrix.e2e.ts +++ b/apps/web/tests/fold-blank-matrix.e2e.ts @@ -10,7 +10,7 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' -import type { Browser, Page, Route } from 'playwright' +import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' import type { StreamChunk } from '@deepseek-ai/dsh-llm' @@ -695,31 +695,37 @@ async function run(world: World, scenario: Case): Promise { const disposeFailure = scenario.origin === 'error' ? scaffold.ctx.on('system-prompt/assemble', async () => { throw new Error('FOLDMX_TURN_FAILED') }) : () => undefined - // A subagent child's composer sends through the subagent continuation route. - const promptRoute = scenario.surface === 'side' ? '**/api/subagents/prompt' : '**/api/session/prompt' - const promptGate = Promise.withResolvers() - const promptHeld = Promise.withResolvers() - const holdPrompt = async (route: Route): Promise => { - promptHeld.resolve(undefined) - await promptGate.promise - await route.continue() + // The accepted message waits before its model call, so the fold settles before the Turn streams. + const turnGate = Promise.withResolvers() + let held: Promise = Promise.resolve() + let disposeHold = (): void => {} + if (scenario.surface === 'side') { + // A subagent child's composer sends through the continuation route, which resumes the cold child. + disposeHold = scaffold.ctx.on('agent/pre-step', async ({ agent }, next) => { + if (agent.id === target) await turnGate.promise + return await next() + }) + } else { + const agent = scaffold.ctx.agents.get(target) + if (agent === undefined) throw new Error(`${scenario.id}: the target Agent is not live`) + // Maintenance keeps the accepted message in the inbox without starting its Turn. + held = agent.runMaintenance(() => turnGate.promise) } - await page.route(promptRoute, holdPrompt) const ended = turnEnded(scaffold, target) try { await expandSeededSteps(page, root, scenario) await placeReader(page, root, scenario.reader) await begin() await send(world, NEXT_INPUT) - await promptHeld.promise await page.locator(`${root} [data-submission-echo]`).waitFor() afterFold = await folded() - promptGate.resolve(undefined) + turnGate.resolve(undefined) + await held await ended } finally { - promptGate.resolve(undefined) + turnGate.resolve(undefined) + disposeHold() disposeFailure() - await page.unroute(promptRoute, holdPrompt) } break } diff --git a/apps/web/tests/forge-panel.e2e.ts b/apps/web/tests/forge-panel.e2e.ts new file mode 100644 index 0000000000..6be6b70c39 --- /dev/null +++ b/apps/web/tests/forge-panel.e2e.ts @@ -0,0 +1,1376 @@ +/** Worktree Sessions and the change request panel through the real optional bundle, a Git checkout, and a scripted GitHub CLI. */ +import { execFile } from 'node:child_process' +import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { homedir, tmpdir } from 'node:os' +import { basename, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { promisify } from 'node:util' +import type {} from '@deepseek-ai/dsh-experimental-forge-session' +import { pluginRecordOf, type SessionEvent } from '@deepseek-ai/dsh-session' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import { initialShortcutConfig, type DesktopShortcutInput, type ShortcutRevision } from '@deepseek-ai/dsh-client-shortcuts/protocol' +import { abbreviateHomePath } from '@deepseek-ai/dsh-util-workspace-path' +import { chromium, type Browser, type Page } from 'playwright' +import { expect, it, onTestFailed, onTestFinished } from 'vitest' +import { + captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, launchWebScaffold, readPersistedEvents, watchConsole, + webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { connectFreshWorkspaceZh, saveFailureShot, writeComposerDraft, ZH_BROWSER_LOCALE } from './support.ts' + +declare global { + interface Window { + forgeKeyboard: { readonly revision: ShortcutRevision; deliver(input: DesktopShortcutInput): void } + } +} + +const BUNDLE = fileURLToPath(new URL('../../../packages/experimental/forge-bundle', import.meta.url)) +const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/lifecycle-chrome/session.v4.jsonl', import.meta.url)) +const EXPECTED = fileURLToPath(new URL('./expected/forge-panel', import.meta.url)) +const MODE = webSnapshotMode() +const PULL = 'https://github.com/octo/demo/pull/7' +/** A draft change request that the double lets the panel mark ready and merge. */ +const DRAFT = 'https://github.com/octo/demo/pull/9' +/** Message sent after the worktree is removed, which waits until the worktree is restored. */ +const FOLLOW_UP = 'Summarize the failed check' +/** Reply to {@link FOLLOW_UP}, a model call appended after the borrowed scenario's single one. */ +const FOLLOW_UP_REPLY = 'RESTORED' +const run = promisify(execFile) + +/** + * GitHub CLI double: signed in to github.com, with octo/demo allowing every + * merge method and the viewer's usual one squash. GraphQL serves pull request + * 7 with one failed and one passed check run, one unresolved thread, and a + * required review, and pull request 9, an approved draft whose checks passed. + * `gh pr ready 9` and the REST merge of pull request 9 change what later + * queries report, through `state.json`. `gh pr diff N` prints `pr-N.diff`, or + * fails with `pr-N.refused` on standard error when that file exists, and the raw + * contents API serves `contents.json`, keyed by `path@commit`. Every invocation + * is appended to `calls.jsonl`. + */ +const GH = `#!/usr/bin/env node +import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' +const args = process.argv.slice(2) +const here = dirname(fileURLToPath(import.meta.url)) +appendFileSync(join(here, 'calls.jsonl'), JSON.stringify(args) + '\\n') +const statePath = join(here, 'state.json') +const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : { ready: false, mergedAt: null } +const save = () => { writeFileSync(statePath, JSON.stringify(state)) } +if (args[0] === 'pr' && args[1] === 'view' && args[2] === '7') { + const fields = args[args.indexOf('--json') + 1] + process.stdout.write(JSON.stringify(fields === 'url' + ? { url: 'https://github.com/octo/demo/pull/7' } + : { number: 7, title: 'Add the pull request panel' })) + process.exit(0) +} +if (args[0] === 'pr' && args[1] === 'ready' && args[2] === '9') { + state.ready = true + save() + process.stderr.write('Pull request octo/demo#9 is marked as "ready for review"\\n') + process.exit(0) +} +if (args[0] === 'api' && args[5] === 'repos/octo/demo/pulls/9/merge') { + state.mergedAt = new Date().toISOString() + save() + process.stdout.write(JSON.stringify({ sha: 'c'.repeat(40), merged: true, message: 'Pull Request successfully merged' })) + process.exit(0) +} +if (args[0] === 'api' && args[3] === 'repos/octo/demo/pulls/7') { + process.stdout.write(JSON.stringify({ head: { sha: 'a'.repeat(40) }, state: 'open' })) + process.exit(0) +} +if (args[0] === 'api' && args[4] === 'POST' && ['repos/octo/demo/pulls/7/comments', 'repos/octo/demo/pulls/7/reviews'].includes(args[5])) { + const body = JSON.parse(readFileSync(0, 'utf8')) + appendFileSync(join(here, 'reviews.jsonl'), JSON.stringify({ endpoint: args[5], body }) + '\\n') + process.stdout.write(JSON.stringify({ html_url: 'https://github.com/octo/demo/pull/7#pullrequestreview-1' })) + process.exit(0) +} +if (args[0] === 'pr' && args[1] === 'diff') { + const refused = join(here, 'pr-' + args[2] + '.refused') + if (existsSync(refused)) { + process.stderr.write(readFileSync(refused, 'utf8')) + process.exit(1) + } + await new Promise(resolve => process.stdout.write(readFileSync(join(here, 'pr-' + args[2] + '.diff'), 'utf8'), resolve)) + process.exit(0) +} +if (args[0] === 'api' && args[3] === '-H' && args[4] === 'Accept: application/vnd.github.raw+json') { + const [resource, query] = args[5].split('?') + const path = decodeURIComponent(resource.slice('repos/octo/demo/contents/'.length)) + const text = JSON.parse(readFileSync(join(here, 'contents.json'), 'utf8'))[path + '@' + query.slice('ref='.length)] + if (text === undefined) { + process.stderr.write('gh: Not Found (HTTP 404)\\n') + process.exit(1) + } + process.stdout.write(text) + process.exit(0) +} +if (args[0] === 'auth' && args[1] === 'status') { + process.stdout.write('github.com\\n Logged in to github.com account octo\\n') + process.exit(0) +} +if (args[0] === 'api' && args[1] === 'graphql') { + const query = args.find(arg => arg.startsWith('query=')).slice('query='.length) + const check = (name, conclusion, completedAt, databaseId = 101) => ({ + __typename: 'CheckRun', id: 'check-' + databaseId, name, status: 'COMPLETED', conclusion, databaseId, + detailsUrl: 'https://github.com/octo/demo/actions/runs/1', startedAt: '2026-10-09T00:00:00Z', completedAt, + checkSuite: { app: { id: 'github-actions' }, workflowRun: { event: 'pull_request', workflow: { id: 'ci', name: 'CI' } } }, + }) + const pulls = { + 7: { + number: 7, url: 'https://github.com/octo/demo/pull/7', title: 'Add the pull request panel', state: 'OPEN', isDraft: false, + updatedAt: '2026-10-09T00:00:00Z', closedAt: null, author: { login: 'octo' }, headRefName: 'feat', headRefOid: 'a'.repeat(40), + baseRefName: 'main', additions: 128, deletions: 14, mergeable: 'MERGEABLE', mergeStateStatus: 'BLOCKED', reviewDecision: 'REVIEW_REQUIRED', + reviewThreads: { nodes: [{ isResolved: false }] }, + commits: { nodes: [{ commit: { statusCheckRollup: { id: 'rollup-7', state: 'FAILURE', contexts: { + pageInfo: { hasNextPage: true, endCursor: 'checks-100' }, + nodes: Array.from({ length: 100 }, (_, i) => check('lint', 'FAILURE', '2026-10-08T00:00:42Z', i + 1)), + } } } }] }, + }, + 9: { + number: 9, url: 'https://github.com/octo/demo/pull/9', title: 'Add the merge button', state: state.mergedAt === null ? 'OPEN' : 'MERGED', + isDraft: !state.ready, updatedAt: '2026-10-09T00:00:00Z', closedAt: state.mergedAt, author: { login: 'octo' }, + headRefName: 'feat/merge', headRefOid: state.head ?? 'b'.repeat(40), baseRefName: 'main', additions: 30, deletions: 2, mergeable: 'MERGEABLE', + mergeStateStatus: state.ready ? 'CLEAN' : 'BLOCKED', reviewDecision: 'APPROVED', reviewThreads: { nodes: [] }, + commits: { nodes: [{ commit: { statusCheckRollup: { id: 'rollup-9', state: 'SUCCESS', contexts: { + pageInfo: { hasNextPage: false, endCursor: null }, nodes: [check('lint', 'SUCCESS', '2026-10-09T00:00:42Z')], + } } } }] }, + }, + } + if (query.includes('node(id: $id)')) { + process.stdout.write(JSON.stringify({ data: { node: { contexts: { + pageInfo: { hasNextPage: false, endCursor: null }, + nodes: [check('lint', 'SUCCESS', '2026-10-09T00:00:42Z'), check('test', 'FAILURE', '2026-10-09T00:02:07Z')], + } } } })) + process.exit(0) + } + const settings = { + squashMergeAllowed: true, mergeCommitAllowed: true, rebaseMergeAllowed: true, viewerPermission: 'WRITE', viewerDefaultMergeMethod: 'SQUASH', + } + const data = {} + let repository + for (const match of query.matchAll(/(r\\d+): repository\\(|(p\\d+): pullRequest\\(number: (\\d+)\\)/g)) { + if (match[1] !== undefined) data[repository = match[1]] = { ...settings } + else data[repository][match[2]] = pulls[Number(match[3])] ?? null + } + process.stdout.write(JSON.stringify({ data })) + process.exit(0) +} +process.stderr.write('unexpected gh invocation\\n') +process.exit(1) +` + +/** Head commit of pull request 7 in the GitHub CLI double. */ +const HEAD7 = 'a'.repeat(40) + +/** What gh 2.100 prints for the diff of pull request 9 when GitHub refuses it for having over 300 files. */ +const PR9_REFUSAL = [ + 'could not find pull request diff: HTTP 406: Sorry, the diff exceeded the maximum number of files (300). Consider using \'List pull ' + + 'requests files\' API or locally cloning the repository instead. (https://api.github.com/repos/octo/demo/pulls/9)', + 'PullRequest.diff too_large', + '', +].join('\n') + +/** Line `n` of `src/panel.ts` before (`old`) or after (`new`) pull request 7, which changes lines 2 and 15 of its 20. */ +function panelLine(n: number, side: 'old' | 'new'): string { + if (n === 2) return side === 'old' ? 'export const n2 = 2' : 'export const n2 = \'two\'' + if (n === 7) return 'export const n7 = "Long unchanged context stays wrapped while switching between Sessions and reviewing the same file"' + if (n === 15) return side === 'old' ? 'export const n15 = 15' : 'export const n15 = \'fifteen\'' + return `export const n${n} = ${n}` +} + +/** Patch of pull request 7 as `gh pr diff` prints it: two hunks of `src/panel.ts` and the new `docs/panel.md`. */ +const PR7_DIFF = [ + 'diff --git a/src/panel.ts b/src/panel.ts', + 'index 1111111..2222222 100644', + '--- a/src/panel.ts', + '+++ b/src/panel.ts', + '@@ -1,5 +1,5 @@', + ` ${panelLine(1, 'new')}`, `-${panelLine(2, 'old')}`, `+${panelLine(2, 'new')}`, + ...[3, 4, 5].map(n => ` ${panelLine(n, 'new')}`), + '@@ -12,7 +12,7 @@', + ...[12, 13, 14].map(n => ` ${panelLine(n, 'new')}`), `-${panelLine(15, 'old')}`, `+${panelLine(15, 'new')}`, + ...[16, 17, 18].map(n => ` ${panelLine(n, 'new')}`), + 'diff --git a/docs/panel.md b/docs/panel.md', + 'new file mode 100644', + 'index 0000000..3333333', + '--- /dev/null', + '+++ b/docs/panel.md', + '@@ -0,0 +1,2 @@', + '+# Panel', + '+Shows the change requests of a Session.', + '', +].join('\n') + +async function git(cwd: string, ...args: string[]): Promise { + const { stdout } = await run('git', args, { cwd, env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' } }) + return stdout.trim() +} + +/** A Web scaffold with the bundle, a GitHub checkout of `main` and `release`, and the New Session screen of that workspace. */ +interface PanelLaunch { + readonly scaffold: WebScaffold + readonly page: Page + /** Temporary directory of the GitHub CLI double and its call log. */ + readonly root: string + /** The Session's workspace, a main checkout. */ + readonly project: string + readonly tripwire: ReturnType +} + +/** + * Launch the bundle against a GitHub checkout of `main` and `release` and open the New Session screen of that workspace. + * @param failureShot - name of the screenshot saved when the test fails. + * @param scenario - normal conversation, a restoration follow-up, or a numbered PR lookup. + * @param options - desktop transport, checkout branch, browser input, sandbox runner availability, and diff output limit. + * @returns the scaffold, page, and checkout. + */ +async function launchPanel(failureShot: string, scenario: 'normal' | 'follow-up' | 'reference' = 'normal', + options: { desktop?: 'darwin' | 'win32'; branch?: string; hasTouch?: boolean; missingSandbox?: boolean; maxDiffBytes?: number } = {}): Promise { + const { desktop } = options + const resources: { scaffold?: WebScaffold; browser?: Browser } = {} + const root = await mkdtemp(join(tmpdir(), 'dsh-forge-panel-')) + onTestFinished(async () => { + const failures: unknown[] = [] + await resources.browser?.close().catch((error: unknown) => failures.push(error)) + await resources.scaffold?.close().catch((error: unknown) => failures.push(error)) + await rm(root, { recursive: true, force: true }).catch((error: unknown) => failures.push(error)) + if (failures.length > 0) throw new AggregateError(failures, 'Forge panel teardown failed') + }) + const gh = join(root, 'gh') + await writeFile(gh, GH) + await chmod(gh, 0o755) + await writeFile(join(root, 'pr-7.diff'), PR7_DIFF) + await writeFile(join(root, 'pr-9.refused'), PR9_REFUSAL) + const panelText = `${Array.from({ length: 20 }, (_, index) => panelLine(index + 1, 'new')).join('\n')}\n` + await writeFile(join(root, 'contents.json'), JSON.stringify({ [`src/panel.ts@${HEAD7}`]: panelText })) + const overlay = join(root, 'forge.patch.yml') + await writeFile(overlay, `- id: forge-github\n config: ${JSON.stringify({ ghCommand: gh })}\n` + + (options.maxDiffBytes === undefined ? '' : `- id: forge-panel\n config: ${JSON.stringify({ maxDiffBytes: options.maxDiffBytes })}\n`) + + (options.missingSandbox ? `- id: sandbox\n config: ${JSON.stringify({ runnerCommand: [join(root, 'missing-sandbox')], runnerFailureSignatures: ['sandbox startup failed'] })}\n` : '')) + const override = join(root, 'replay.override.json') + // The borrowed scenario records one model call, so index 1 appends the reply to the follow-up. + if (scenario === 'follow-up') await writeFile(override, JSON.stringify({ patches: [{ at: 1, entry: { kind: 'chunks', chunks: textReply(FOLLOW_UP_REPLY) } }] })) + if (scenario === 'reference') { + const command = `PATH=${JSON.stringify(`.fixture-bin:${process.env.PATH ?? ''}`)} gh pr view 7 --repo octo/demo --json number,title 2>&1 | head -200` + const call = { type: 'tool-call', id: 'view-pr', name: 'bash', arguments: JSON.stringify({ command, description: 'View PR metadata' }) } + await writeFile(override, JSON.stringify({ patches: [ + { at: 0, entry: { kind: 'chunks', chunks: [ + { type: 'block-start', index: 0, blockType: 'tool-call' }, + { type: 'block-end', index: 0, block: call }, + { type: 'finish', reason: { kind: 'tool-calls' } }, + ] } }, + { at: 1, entry: { kind: 'chunks', chunks: textReply('Viewed PR 7.') } }, + ] })) + } + const scaffold = await launchWebScaffold({ + profile: { packages: [{ dir: BUNDLE, enabled: true }] }, + extraOverlayPath: overlay, + replayFixture: FIXTURE, + ...scenario !== 'normal' ? { replayOverride: override } : {}, + // The worktree notice, worktree records, and bindings are asserted separately from the borrowed conversation. + compareReplaySession: false, + }) + resources.scaffold = scaffold + + const project = join(scaffold.workspaceCwd, 'workspace') + await mkdir(project, { recursive: true }) + await git(project, 'init', '--quiet', '--initial-branch=main') + await git(project, 'config', 'user.name', 'Forge Panel') + await git(project, 'config', 'user.email', 'forge-panel@example.test') + await git(project, 'config', 'commit.gpgsign', 'false') + await writeFile(join(project, 'README.md'), 'demo\n') + await git(project, 'add', 'README.md') + await git(project, 'commit', '--quiet', '-m', 'init') + await git(project, 'remote', 'add', 'origin', 'https://github.com/octo/demo.git') + await git(project, 'branch', 'release') + await git(project, 'commit', '--quiet', '--allow-empty', '-m', 'main only') + if (options.branch !== undefined) await git(project, 'checkout', '--quiet', '-b', options.branch) + if (scenario === 'reference') { + // The model's confined command must own the CLI double's writable call log. + const modelBin = join(project, '.fixture-bin') + await mkdir(modelBin) + await writeFile(join(modelBin, 'gh'), GH) + await chmod(join(modelBin, 'gh'), 0o755) + } + + const browser = await chromium.launch() + resources.browser = browser + const page = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE, timezoneId: 'Asia/Shanghai', + hasTouch: options.hasTouch ?? false }) + if (desktop !== undefined) { + // Only Electron's keyboard transport is substituted; the product registry and menus remain real. + await page.addInitScript(({ device, config }) => { + const mark = () => { document.documentElement.dataset.platform = device } + if (document.documentElement === null) window.addEventListener('DOMContentLoaded', mark) + else mark() + const listeners = new Set<(input: DesktopShortcutInput) => void>() + Object.assign(window, { + forgeKeyboard: { revision: config.revision, + deliver: (input: DesktopShortcutInput) => { for (const listener of listeners) listener(input) } }, + dshDesktop: { protocolVersion: 1, + shortcuts: { get: async () => config, subscribe: () => () => {}, recording: async () => {}, edit: async () => { throw new Error('Unused preference edit') } }, + keyboard: { + subscribe: (listener: (input: DesktopShortcutInput) => void) => { + listeners.add(listener) + return () => { listeners.delete(listener) } + }, + closeWindow: async () => {}, + }, + }, + }) + }, { device: desktop, config: { ...initialShortcutConfig(), status: 'ready' as const } }) + } + const tripwire = watchConsole(page) + onTestFailed(async () => { await saveFailureShot(page, failureShot) }) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await connectFreshWorkspaceZh(page, scaffold.workspaceCwd) + return { scaffold, page, root, project, tripwire } +} + +/** Stream chunks of a model reply that is one text block. */ +function textReply(text: string): unknown[] { + return [ + { type: 'block-start', index: 0, blockType: 'text' }, + { type: 'text-delta', index: 0, text }, + { type: 'block-end', index: 0, block: { type: 'text', text } }, + { type: 'usage', usage: { inputTokens: 50, outputTokens: 2, cacheReadTokens: 0, reasoningTokens: 0 } }, + { type: 'finish', reason: { kind: 'stop' } }, + ] +} + +/** + * Launch the panel and choose the worktree option of the fresh Session from `release`. + * @param failureShot - name of the screenshot saved when the test fails. + * @param followUp - whether the replay answers a second model call. + * @returns the scaffold, page, and checkout. + */ +async function requestReleaseWorktree(failureShot: string, followUp = false): Promise { + const launched = await launchPanel(failureShot, followUp ? 'follow-up' : 'normal') + const { page } = launched + const option = page.locator('[data-forge-worktree]') + await option.waitFor({ timeout: 20_000 }) + await option.getByRole('checkbox', { name: '新建工作树', exact: true }).check() + await option.getByRole('button', { name: '基于 main', exact: true }).click() + await page.getByRole('menuitem', { name: 'release', exact: true }).click() + await option.getByRole('button', { name: '基于 release', exact: true }).waitFor() + return launched +} + +/** + * Send the first prompt of the borrowed scenario. + * @returns the prompt and the turn's settlement, which resolves to the Session id. + */ +async function sendPrompt(page: Page, scaffold: WebScaffold): Promise<{ readonly prompt: string; readonly settled: Promise }> { + const [prompt] = fixtureUserPrompts(await readFile(FIXTURE, 'utf8')) + if (prompt === undefined) throw new Error('The borrowed scenario requires a user prompt') + const settled = scaffold.whenTurnSettled() + const composer = page.locator('[data-composer-input]').first() + await writeComposerDraft(page, composer, prompt) + await composer.press('Enter') + return { prompt, settled } +} + +function worktreeRecords(events: readonly SessionEvent[]): unknown[] { + return events.flatMap((event) => { + const record = pluginRecordOf(event) + return record?.type === 'plugin:client-ui-forge/worktree' ? [record.data] : [] + }) +} + +it.skipIf(MODE === 'record')('reads local Git with full access when the sandbox runner cannot start', async () => { + const { scaffold, page, project, tripwire } = await launchPanel('web-e2e-forge-permissions', 'normal', { missingSandbox: true }) + await git(project, 'update-ref', 'refs/remotes/origin/main', 'HEAD') + await git(project, 'symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main') + await writeFile(join(project, 'README.md'), 'demo\nchanged\n') + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + await page.locator('[data-forge-header]').click() + const panel = page.locator('[data-forge-panel]') + await panel.getByText('无法读取 Git 信息', { exact: true }).waitFor({ timeout: 20_000 }) + + const permission = page.locator('button[aria-label^="访问模式"]').first() + await permission.click() + await page.getByRole('menuitem', { name: '完全权限', exact: true }).click() + const confirmation = page.getByRole('dialog', { name: '确认启用完全权限？' }) + await confirmation.getByRole('checkbox', { name: '我已了解风险，并愿意继续' }).check() + await confirmation.getByRole('button', { name: '启用完全权限' }).click() + const local = page.locator('[data-forge-local]') + await local.getByRole('button', { name: '查看本会话的变更：1 个文件，新增 1 行，删除 0 行', exact: true }).waitFor({ timeout: 20_000 }) + await compareOrRefreshGolden(join(EXPECTED, 'full-access.expected.md'), await captureStableAria(page, '[data-forge-local]', scaffold.workspaceCwd), MODE) + await local.getByRole('button', { name: '查看本会话的变更：1 个文件，新增 1 行，删除 0 行', exact: true }).click() + await page.locator('[data-forge-diff-file="README.md"]').getByText('changed', { exact: true }).waitFor() + + await permission.click() + await page.getByRole('menuitem', { name: '工作区内修改', exact: true }).click() + if (!await panel.isVisible()) await page.locator('[data-forge-header]').click() + await panel.getByText('无法读取 Git 信息', { exact: true }).waitFor({ timeout: 20_000 }) + await expect.poll(async () => (await readPersistedEvents(scaffold, sessionId)) + .filter(event => event.type === 'sandbox/mode').map(event => event.data.mode).slice(-2)) + .toEqual(['danger-full-access', 'workspace-write']) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('reports incomplete filter configuration and retries after it is corrected', async () => { + const { scaffold, page, project, tripwire } = await launchPanel('web-e2e-forge-filter-config', 'normal', { maxDiffBytes: 512 }) + await git(project, 'update-ref', 'refs/remotes/origin/main', 'HEAD') + await git(project, 'symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main') + await writeFile(join(project, 'README.md'), 'demo\nchanged\n') + const { settled } = await sendPrompt(page, scaffold) + await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + await page.locator('[data-forge-header]').click() + const openChanges = page.locator('[data-forge-local]').getByRole('button', { name: '查看本会话的变更：1 个文件，新增 1 行，删除 0 行', exact: true }) + await openChanges.waitFor({ timeout: 20_000 }) + const key = `filter.${'long'.repeat(200)}.clean` + await git(project, 'config', key, 'cat') + await openChanges.click() + const changes = page.locator('[data-forge-changes="local"]') + await changes.getByText('无法完整读取 Git 过滤器配置，尚未执行比较。请检查 Git 配置和读取上限后重试', { exact: true }).waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'filter-config-failed.expected.md'), + await captureStableAria(page, '[data-forge-changes="local"]', scaffold.workspaceCwd), MODE) + + await git(project, 'config', '--unset', key) + await changes.getByRole('button', { name: '重试', exact: true }).click() + await changes.locator('[data-forge-diff-file="README.md"]').getByText('changed', { exact: true }).waitFor() + expect(await changes.getByRole('status').count()).toBe(0) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('automatically shows a numbered PR when gh JSON omits its URL', async () => { + const { scaffold, page, project, tripwire } = await launchPanel('web-e2e-forge-numbered-reference', 'reference') + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + const events = await readPersistedEvents(scaffold, sessionId) + const toolOutput = events.flatMap(event => event.type === 'tool/result' + ? event.data.message.content.flatMap(block => block.type === 'text' ? [block.text] : []) : []).join('\n') + expect(toolOutput).toContain('Add the pull request panel') + const header = page.locator('[data-forge-header]') + await expect.poll(() => header.getAttribute('aria-label'), { timeout: 20_000 }).toBe('本会话的变更请求需要处理') + await header.click() + const change = page.locator(`[data-forge-change="${PULL}"]`) + await change.getByRole('link', { name: 'Add the pull request panel', exact: true }).waitFor({ timeout: 20_000 }) + await change.getByText('等待评审 · 1 条未解决讨论', { exact: true }).waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'reference.expected.md'), + await captureStableAria(page, `[data-forge-change="${PULL}"]`, scaffold.workspaceCwd), MODE) + expect(events.flatMap((event) => { + const record = pluginRecordOf(event) + return record?.type === 'plugin:forge-session/binding' ? [record.data] : [] + })).toEqual([{ action: 'reference', url: PULL }]) + const calls = (await readFile(join(project, '.fixture-bin', 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[]) + expect(calls).toContainEqual(['pr', 'view', '7', '--repo', 'octo/demo', '--json', 'url']) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('starts a Session in a worktree before its first message, follows its change request, and restores the removed worktree', async () => { + const { scaffold, page, root, project, tripwire } = await requestReleaseWorktree('web-e2e-forge-panel', true) + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + await page.locator('[data-forge-creation]').waitFor({ state: 'detached' }) + await page.locator('[data-forge-worktree]').waitFor({ state: 'detached' }) + + const session = scaffold.ctx.sessions.get(sessionId) + if (session === undefined) throw new Error('The worktree Session must stay loaded') + const directory = scaffold.ctx.workingDirectory.get(session) + const branch = basename(directory) + expect(directory).toBe(join(project, '.agents', 'worktrees', branch)) + expect(branch).toMatch(new RegExp(`^dsh-${sessionId.slice('session-'.length, 'session-'.length + 8)}-[0-9a-f]{4}$`)) + expect(await git(directory, 'rev-parse', '--abbrev-ref', 'HEAD')).toBe(branch) + const baseCommit = await git(project, 'rev-parse', 'release') + expect(await git(directory, 'rev-parse', 'HEAD')).toBe(baseCommit) + const events = await readPersistedEvents(scaffold, sessionId) + expect(worktreeRecords(events)).toEqual([ + { action: 'request', from: 'main' }, + { action: 'request', from: 'release' }, + { action: 'created', worktree: { path: directory, branch, from: 'release', baseCommit, repositoryRoot: project } }, + ]) + // The worktree existed before the turn, so the first model request carried its directory notice. + const created = events.findIndex((event) => { + const record = pluginRecordOf(event) + const data = record?.type === 'plugin:client-ui-forge/worktree' ? record.data : null + return typeof data === 'object' && data !== null && 'action' in data && data.action === 'created' + }) + const turn = events.findIndex(event => event.type === 'turn/start') + const notice = events.findIndex(event => event.type === 'user/message' && event.data.source.kind === 'working-directory') + expect(created).toBeLessThan(turn) + expect(notice).toBeGreaterThan(turn) + expect(notice).toBeLessThan(events.findIndex(event => event.type === 'assistant/message')) + + // A change request bound the way a `gh pr create` result binds one. + scaffold.ctx.forgeSession.track(session, PULL) + const header = page.locator('[data-forge-header]') + await expect.poll(() => header.getAttribute('aria-label'), { timeout: 20_000 }).toBe('本会话的变更请求需要处理') + expect(await header.getAttribute('aria-pressed')).toBe('false') + + // The Session row marks the worktree and its change request's state, and its hover card names both. + const row = page.locator(`[data-row-key="session:${sessionId}"]`) + await row.getByRole('img', { name: '在自己的工作树中', exact: true }).waitFor({ timeout: 20_000 }) + await row.getByRole('img', { name: '变更请求状态：需要处理 · 检查失败', exact: true }).waitFor({ timeout: 20_000 }) + // A fresh page cannot retain the previous browser source's status values. + await page.goto('about:blank') + await expect.poll(() => scaffold.ctx.storageDomain.get('forge_panel_change_requests')).toBeUndefined() + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await row.getByRole('img', { name: '变更请求状态：需要处理 · 检查失败', exact: true }).waitFor({ timeout: 20_000 }) + await row.hover() + const rowHover = page.locator('[data-forge-session-hover]') + await rowHover.getByText('#7 Add the pull request panel', { exact: true }).waitFor({ timeout: 20_000 }) + await compareOrRefreshGolden(join(EXPECTED, 'session-row-hover.expected.md'), + await captureStableAria(page, '[data-forge-session-hover]', scaffold.workspaceCwd, { replacements: [[branch, 'dsh-{{worktree}}']] }), MODE) + await page.mouse.move(0, 0) + await rowHover.waitFor({ state: 'detached' }) + await header.click() + await expect.poll(() => header.getAttribute('aria-pressed')).toBe('true') + const panel = page.locator('[data-forge-panel]') + const checkout = panel.locator('[data-forge-checkout]') + const checkoutName = checkout.getByText(branch, { exact: true }) + await checkoutName.waitFor({ timeout: 20_000 }) + await checkout.getByText('工作树 · 基于 release', { exact: true }).waitFor() + await checkoutName.hover() + await page.getByRole('tooltip').filter({ hasText: `工作树（基于 release）：${abbreviateHomePath(directory, homedir())}` }).waitFor() + await page.mouse.move(0, 0) + const change = panel.locator(`[data-forge-change="${PULL}"]`) + const title = change.getByRole('link', { name: 'Add the pull request panel', exact: true }) + await title.waitFor({ timeout: 20_000 }) + // The only open change request starts expanded. + await change.getByText('等待评审 · 1 条未解决讨论', { exact: true }).waitFor() + // The random branch suffix can read as a duration, so the branch is replaced before the capture normalizes durations. + await compareOrRefreshGolden(join(EXPECTED, 'panel.expected.md'), + await captureStableAria(page, '[data-forge-panel]', scaffold.workspaceCwd, { replacements: [[branch, 'dsh-{{worktree}}']] }), MODE) + const beforeChecks = (await readFile(join(root, 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[]) + expect(beforeChecks.some(args => args.includes('id=rollup-7'))).toBe(false) + const checksRow = change.getByRole('button', { name: /^检查/ }) + await checksRow.click() + const checks = page.getByRole('menu') + await expect.poll(() => checks.getByRole('menuitem').allTextContents()).toEqual([expect.stringMatching(/^test/), expect.stringMatching(/^lint/)]) + const afterChecks = (await readFile(join(root, 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[]) + expect(afterChecks.filter(args => args.includes('id=rollup-7'))).toHaveLength(1) + await page.keyboard.press('Escape') + await checks.waitFor({ state: 'detached' }) + expect(await checksRow.getAttribute('aria-expanded')).toBe('false') + + const bindings = async () => (await readPersistedEvents(scaffold, sessionId)).flatMap((event) => { + const record = pluginRecordOf(event) + return record?.type === 'plugin:forge-session/binding' ? [record.data] : [] + }) + await change.getByRole('button', { name: '从本会话移除 #7', exact: true }).click() + await change.waitFor({ state: 'detached' }) + await panel.getByText('本会话还没有变更请求', { exact: true }).waitFor() + await page.getByRole('alert').filter({ hasText: '已从本会话移除 #7' }).getByRole('button', { name: '撤销', exact: true }).click() + await title.waitFor({ timeout: 20_000 }) + await expect.poll(bindings).toEqual([{ action: 'track', url: PULL }, { action: 'dismiss', url: PULL }, { action: 'track', url: PULL }]) + + const calls = (await readFile(join(root, 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[]) + expect(calls).toContainEqual(['auth', 'status', '--hostname', 'github.com']) + expect(calls.some(args => args[0] === 'api' && args[1] === 'graphql' && args.includes('--hostname'))).toBe(true) + await header.click() + await expect.poll(() => header.getAttribute('aria-pressed')).toBe('false') + + // Removing the worktree outside the Session holds the next message in the inbox until the worktree is restored. + await git(project, 'worktree', 'remove', '--force', directory) + const composer = page.locator('[data-composer-input]').first() + await writeComposerDraft(page, composer, FOLLOW_UP) + const accepted = page.waitForResponse('**/api/session/prompt') + await composer.press('Enter') + const envelope = await (await accepted).json() as { readonly result: unknown } + expect(envelope.result).toMatchObject({ ok: true }) + const missing = page.locator('[data-forge-missing]') + await missing.getByText(`可以在原位置恢复分支 ${branch} 的工作树。删除前未提交的修改无法恢复`, { exact: true }).waitFor() + await missing.getByText('恢复工作树或在项目目录继续后，消息会接着发送', { exact: true }).waitFor() + await expect.poll(() => checkout.getAttribute('data-missing')).toBe('') + const turns = async (): Promise => (await readPersistedEvents(scaffold, sessionId)).filter(event => event.type === 'turn/start').length + expect(await turns()).toBe(1) + await missing.getByRole('button', { name: '恢复工作树', exact: true }).click() + await missing.waitFor({ state: 'detached', timeout: 20_000 }) + await page.getByRole('alert').filter({ hasText: '工作树已恢复' }).waitFor() + expect(await git(directory, 'rev-parse', '--abbrev-ref', 'HEAD')).toBe(branch) + expect(await git(directory, 'rev-parse', 'HEAD')).toBe(baseCommit) + await expect.poll(() => checkout.getAttribute('data-missing')).toBeNull() + // The waiting message goes on in the restored worktree. + await page.getByText(FOLLOW_UP_REPLY, { exact: true }).waitFor({ timeout: 20_000 }) + expect(await turns()).toBe(2) + expect(scaffold.ctx.workingDirectory.get(session)).toBe(directory) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('keeps the first message waiting when the worktree cannot be created, tries again, and sends it without the worktree', async () => { + const { scaffold, page, project, tripwire } = await requestReleaseWorktree('web-e2e-forge-panel-failure') + await git(project, 'branch', '--quiet', '-D', 'release') + const { settled } = await sendPrompt(page, scaffold) + const card = page.locator('[data-forge-creation="failed"]') + const failure = card.getByRole('region', { name: '创建工作树失败', exact: true }) + await failure.getByText('原因', { exact: true }).waitFor({ timeout: 20_000 }) + const attempted = await failure.getByRole('definition').first().textContent() + expect(attempted).toMatch(/^dsh-[0-9a-f]{8}-[0-9a-f]{4}$/) + await failure.getByText('消息会在工作树建好后发送', { exact: true }).waitFor() + + // Retry makes another attempt with a new branch name while the message keeps waiting. + await card.getByRole('button', { name: '重试', exact: true }).click() + await expect.poll(() => failure.getByRole('definition').first().textContent(), { timeout: 20_000 }).not.toBe(attempted) + + await card.getByRole('button', { name: '不使用工作树', exact: true }).click() + const sessionId = await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + await card.waitFor({ state: 'detached' }) + + const session = scaffold.ctx.sessions.get(sessionId) + if (session === undefined) throw new Error('The Session must stay loaded') + expect(scaffold.ctx.workingDirectory.get(session)).toBe(project) + const events = await readPersistedEvents(scaffold, sessionId) + expect(worktreeRecords(events)).toEqual([{ action: 'request', from: 'main' }, { action: 'request', from: 'release' }, { action: 'cancel' }]) + expect(events.filter(event => event.type === 'turn/start')).toHaveLength(1) + expect(events.some(event => event.type === 'user/message' && event.data.source.kind === 'working-directory')).toBe(false) + await page.locator('[data-forge-header]').click({ timeout: 20_000 }) + const checkout = page.locator('[data-forge-panel] [data-forge-checkout]') + const checkoutName = checkout.getByText('main', { exact: true }) + await checkoutName.waitFor({ timeout: 20_000 }) + await checkout.getByText('项目目录', { exact: true }).waitFor() + await checkoutName.hover() + await page.getByRole('tooltip').filter({ hasText: `项目目录：${abbreviateHomePath(project, homedir())}` }).waitFor() + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('marks a draft change request ready for review and merges it with the usual method', async () => { + const { scaffold, page, root, tripwire } = await launchPanel('web-e2e-forge-panel-merge') + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + const session = scaffold.ctx.sessions.get(sessionId) + if (session === undefined) throw new Error('The Session must stay loaded') + + scaffold.ctx.forgeSession.track(session, DRAFT) + const header = page.locator('[data-forge-header]') + await expect.poll(() => header.getAttribute('aria-label'), { timeout: 20_000 }).toBe('本会话的变更请求') + await header.click() + const change = page.locator(`[data-forge-change="${DRAFT}"]`) + await change.getByRole('link', { name: 'Add the merge button', exact: true }).waitFor({ timeout: 20_000 }) + + // The only open change request starts expanded, so its action is in view. + await change.getByRole('button', { name: '标记为可评审', exact: true }).click() + await page.getByRole('alert').filter({ hasText: '已将 #9 标记为可评审' }).waitFor() + const merge = change.getByRole('button', { name: '合并', exact: true }) + await merge.waitFor({ timeout: 20_000 }) + await merge.click() + const menu = page.getByRole('menu') + await menu.getByText('将 #9 合并到 main', { exact: true }).waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'merge-menu.expected.md'), await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd), MODE) + await writeFile(join(root, 'state.json'), JSON.stringify({ ready: true, mergedAt: null, head: 'c'.repeat(40) })) + scaffold.ctx.forge.refresh({ repository: { forge: 'github', host: 'github.com', owner: 'octo', name: 'demo' }, number: 9 }) + const stale = menu.getByRole('menuitem', { name: '提交已更新，请重新检查后再打开合并菜单', exact: true }) + await stale.waitFor() + expect(await stale.isDisabled()).toBe(true) + await compareOrRefreshGolden(join(EXPECTED, 'merge-stale.expected.md'), await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd), MODE) + await merge.click() + await merge.click() + await menu.getByRole('menuitem', { name: '确认合并', exact: true }).click() + await page.getByRole('alert').filter({ hasText: '已合并 #9' }).waitFor() + // Merged, the change request is no longer open, so its card collapses to the merge line. + await change.getByText(/^已合并到 main · /).waitFor({ timeout: 20_000 }) + + const calls = (await readFile(join(root, 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[]) + expect(calls).toContainEqual(['pr', 'ready', '9', '--repo', 'github.com/octo/demo']) + expect(calls).toContainEqual([ + 'api', '--hostname', 'github.com', '--method', 'PUT', 'repos/octo/demo/pulls/9/merge', '-f', 'merge_method=squash', '-f', `sha=${'c'.repeat(40)}`, + ]) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('shows the local changes of the Session by scope and the changes of its change requests, expanding unchanged lines', async () => { + const { scaffold, page, root, project, tripwire } = await launchPanel('web-e2e-forge-panel-changes', 'follow-up') + // origin/main stops at the twelve-line README; the branch adds a commit, a staged file, an edit, and an untracked file. + await writeFile(join(project, 'README.md'), Array.from({ length: 12 }, (_, index) => `line ${index + 1}\n`).join('')) + await git(project, 'commit', '--quiet', '-am', 'readme') + await git(project, 'update-ref', 'refs/remotes/origin/main', 'HEAD') + await git(project, 'symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main') + await mkdir(join(project, 'src')) + await writeFile(join(project, 'src', 'app.ts'), 'export const app = 1\n') + await git(project, 'add', 'src/app.ts') + await git(project, 'commit', '--quiet', '-m', 'app') + await writeFile(join(project, 'src', 'extra.ts'), 'export const extra = 1\n') + await git(project, 'add', 'src/extra.ts') + await writeFile(join(project, 'README.md'), Array.from({ length: 12 }, (_, index) => index === 9 ? 'line ten\n' : `line ${index + 1}\n`).join('')) + await writeFile(join(project, 'notes.md'), 'note\n') + + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + await page.getByText('LIGHTHOUSE', { exact: true }).waitFor() + const session = scaffold.ctx.sessions.get(sessionId) + if (session === undefined) throw new Error('The Session must stay loaded') + const header = page.locator('[data-forge-header]') + await page.getByRole('button', { name: '打开右侧边栏', exact: true }).click() + const guide = page.locator('[data-sidebar-right-guide]') + await guide.getByRole('button', { name: /^代码审查和变更/ }).waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'review-guide.expected.md'), + await captureStableAria(page, '[data-sidebar-right-guide-entry="forge-panel"]', scaffold.workspaceCwd), MODE) + await guide.getByRole('button', { name: /^代码审查和变更/ }).click() + // The New Session screen inspected the checkout before these changes, which came from outside the Session. + await page.locator('[data-forge-panel]').getByRole('button', { name: '刷新状态', exact: true }).click() + const card = page.locator('[data-forge-local]') + await card.getByText('HEAD → origin/main', { exact: true }).waitFor({ timeout: 20_000 }) + await card.getByRole('button', { name: '查看本会话的变更：4 个文件，新增 4 行，删除 1 行', exact: true }).click() + + const local = page.locator('[data-forge-changes="local"]') + await local.getByText('与 origin/main 比较，包含未提交的修改', { exact: true }).waitFor({ timeout: 20_000 }) + const files = local.locator('[data-forge-diff-file]') + await expect.poll(() => files.evaluateAll(sections => sections.map(section => section.getAttribute('data-forge-diff-file'))), { timeout: 20_000 }) + .toEqual(['README.md', 'src/app.ts', 'src/extra.ts', 'notes.md']) + await local.locator('[data-forge-diff-file="notes.md"]').getByText('新文件 · 未提交', { exact: true }).waitFor() + const readme = local.locator('[data-forge-diff-file="README.md"]') + await page.context().grantPermissions(['clipboard-read', 'clipboard-write']) + await page.evaluate(() => navigator.clipboard.writeText('unchanged')) + await readme.locator('[data-forge-file-label]').click() + await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe('unchanged') + await readme.locator('[data-forge-path-spacer]').click() + await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe('unchanged') + await readme.getByRole('button', { name: '6 行未变更', exact: true }).click() + await readme.getByText('line 1', { exact: true }).first().waitFor({ timeout: 20_000 }) + await local.getByRole('button', { name: '全部 4 个文件', exact: true }).click() + const tree = page.getByRole('menu') + await tree.getByRole('textbox', { name: '筛选文件…' }).fill('extra') + await tree.getByRole('menuitem', { name: 'src/extra.ts', exact: true }).click() + for (const [path, comment] of [['src/app.ts', '请解释这行代码'], ['src/extra.ts', '请检查这项修改']] as const) { + const section = local.locator(`[data-forge-diff-file="${path}"]`) + const lineNumber = section.getByRole('button', { name: '选择第 R1 行', exact: true }) + await lineNumber.hover() + expect(await lineNumber.evaluate(element => getComputedStyle(element).backgroundColor)).toBe('rgba(0, 0, 0, 0)') + const content = await section.locator('[data-review-code]').first().boundingBox() + const fileBox = await section.boundingBox() + if (content === null || fileBox === null) throw new Error('Added file must be visible') + expect(content.x - fileBox.x).toBeLessThan(70) + await lineNumber.click() + expect(await section.getByRole('textbox', { name: '留下评论…' }).count()).toBe(0) + await section.getByRole('button', { name: '添加评论', exact: true }).click() + await section.getByRole('textbox', { name: '留下评论…' }).fill(comment) + await section.locator('[data-forge-comment]').getByRole('button', { name: '添加到输入框', exact: true }).click() + await section.locator('[data-forge-review-thread="agent"]').getByText(comment, { exact: true }).waitFor() + } + await compareOrRefreshGolden(join(EXPECTED, 'review-quotes.expected.md'), + await captureStableAria(page, '[data-composer-input]', scaffold.workspaceCwd), MODE) + expect((await readPersistedEvents(scaffold, sessionId)).some(event => event.type === 'user/message' + && event.data.content.some(block => block.type === 'text' && block.text.includes('## User Comment')))).toBe(false) + const reviewed = scaffold.whenTurnSettled() + await page.locator('[data-composer-input]').first().press('Enter') + await reviewed + await page.getByText(FOLLOW_UP_REPLY, { exact: true }).waitFor() + const comments = (await readPersistedEvents(scaffold, sessionId)).flatMap(event => event.type === 'user/message' + ? event.data.content.flatMap(block => block.type === 'text' && block.text.includes('## User Comment') ? [block.text] : []) : []) + expect(comments).toHaveLength(1) + await compareOrRefreshGolden(join(EXPECTED, 'review-message.expected.md'), comments.join('').trimEnd(), MODE) + + await local.getByRole('button', { name: '分支', exact: true }).click() + await page.getByRole('menuitem', { name: '已暂存', exact: true }).click() + await local.getByText('暂存区与 HEAD 比较', { exact: true }).waitFor() + await expect.poll(() => files.evaluateAll(sections => sections.map(section => section.getAttribute('data-forge-diff-file'))), { timeout: 20_000 }) + .toEqual(['src/extra.ts']) + + // A change request bound the way a `gh pr create` result binds one. + scaffold.ctx.forgeSession.track(session, PULL) + await expect.poll(() => header.getAttribute('aria-pressed'), { timeout: 20_000 }).toBe('false') + await header.click() + const change = page.locator(`[data-forge-change="${PULL}"]`) + await change.getByRole('link', { name: 'Add the pull request panel', exact: true }).waitFor({ timeout: 20_000 }) + await change.getByRole('button', { name: '查看 #7 的变更：新增 128 行，删除 14 行', exact: true }).click() + const view = page.locator('[data-forge-changes="change"]') + const panelFile = view.locator('[data-forge-diff-file="src/panel.ts"]') + const title = await view.getByText('Add the pull request panel', { exact: true }).boundingBox() + const submit = await view.getByRole('button', { name: '提交评审', exact: true }).boundingBox() + if (title === null || submit === null) throw new Error('PR title and submit action must be visible') + expect(Math.abs(title.y + title.height / 2 - submit.y - submit.height / 2)).toBeLessThan(1) + + await panelFile.getByRole('button', { name: '6 行未变更', exact: true }).waitFor({ timeout: 20_000 }) + await compareOrRefreshGolden(join(EXPECTED, 'changes-view.expected.md'), + await captureStableAria(page, '[data-forge-changes="change"]', scaffold.workspaceCwd), MODE) + await page.getByRole('button', { name: '全屏', exact: true }).click() + await view.getByRole('navigation').getByRole('button', { name: 'src/panel.ts', exact: true }).waitFor() + const fileTree = view.getByRole('navigation') + const treeIsLeft = async () => { + const tree = await fileTree.boundingBox() + const diff = await view.locator('[data-forge-changes-scroll]').boundingBox() + if (tree === null || diff === null) throw new Error('Tree and diff must be visible') + return tree.x < diff.x + } + expect(await treeIsLeft()).toBe(true) + const directoryName = await fileTree.getByText('src', { exact: true }).boundingBox() + const fileName = await fileTree.getByText('panel.ts', { exact: true }).boundingBox() + if (directoryName === null || fileName === null) throw new Error('Tree entries must be visible') + expect(fileName.x).toBeGreaterThan(directoryName.x) + await fileTree.getByRole('textbox', { name: '筛选文件…' }).fill('src') + await fileTree.getByRole('textbox', { name: '筛选文件…' }).fill('') + await fileTree.getByRole('button', { name: 'src', exact: true }).click() + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + expect(await treeIsLeft()).toBe(false) + expect(await fileTree.getByRole('button', { name: 'src', exact: true }).getAttribute('aria-expanded')).toBe('false') + await page.setViewportSize({ width: 390, height: 844 }) + expect(await fileTree.isVisible()).toBe(false) + expect(await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).isVisible()).toBe(false) + await view.getByRole('button', { name: '全部 2 个文件', exact: true }).click() + await page.getByRole('menu').getByRole('textbox', { name: '筛选文件…' }).waitFor() + await page.keyboard.press('Escape') + await page.setViewportSize({ width: 1680, height: 1000 }) + expect(await treeIsLeft()).toBe(false) + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + expect(await fileTree.isVisible()).toBe(false) + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + expect(await treeIsLeft()).toBe(true) + expect(await fileTree.getByRole('button', { name: 'src', exact: true }).getAttribute('aria-expanded')).toBe('false') + await fileTree.getByRole('textbox', { name: '筛选文件…' }).fill('src') + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + expect(await fileTree.getByRole('textbox', { name: '筛选文件…' }).inputValue()).toBe('src') + await compareOrRefreshGolden(join(EXPECTED, 'file-tree-toggle.expected.md'), + await captureStableAria(page, '[data-forge-changes="change"]', scaffold.workspaceCwd), MODE) + await fileTree.getByRole('textbox', { name: '筛选文件…' }).fill('') + await fileTree.getByRole('button', { name: 'src', exact: true }).click() + const resizeTree = view.getByRole('separator', { name: '调整文件树宽度', exact: true }) + const originalWidth = Number(await resizeTree.getAttribute('aria-valuenow')) + const handle = await resizeTree.boundingBox() + if (handle === null) throw new Error('Tree resize handle must be visible') + await page.mouse.move(handle.x + handle.width / 2, handle.y + 100) + await page.mouse.down() + await page.mouse.move(handle.x + 80, handle.y + 100, { steps: 5 }) + await page.mouse.up() + expect(Number(await resizeTree.getAttribute('aria-valuenow'))).toBeGreaterThan(originalWidth) + await resizeTree.press('Home') + expect(await fileTree.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + const searchBounds = await fileTree.getByRole('textbox').boundingBox() + const treeBounds = await fileTree.boundingBox() + if (searchBounds === null || treeBounds === null) throw new Error('Tree search must be visible') + expect(searchBounds.x + searchBounds.width).toBeLessThanOrEqual(treeBounds.x + treeBounds.width) + await resizeTree.press('ArrowRight') + const resizedWidth = await resizeTree.getAttribute('aria-valuenow') + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + expect(await treeIsLeft()).toBe(false) + expect(await resizeTree.getAttribute('aria-valuenow')).toBe(resizedWidth) + await resizeTree.press('ArrowLeft') + expect(Number(await resizeTree.getAttribute('aria-valuenow'))).toBe(Number(resizedWidth) + 20) + await resizeTree.press('ArrowRight') + const rightHandle = await resizeTree.boundingBox() + if (rightHandle === null) throw new Error('Right tree resize handle must be visible') + await page.mouse.move(rightHandle.x + rightHandle.width / 2, rightHandle.y + 100) + await page.mouse.down() + await page.mouse.move(rightHandle.x - 80, rightHandle.y + 100, { steps: 5 }) + await page.mouse.up() + expect(Number(await resizeTree.getAttribute('aria-valuenow'))).toBeGreaterThan(Number(resizedWidth)) + const rightWidth = await resizeTree.getAttribute('aria-valuenow') + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + await view.getByRole('button', { name: /^(将文件树移到右侧|隐藏文件树|在左侧显示文件树)$/ }).click() + expect(await resizeTree.getAttribute('aria-valuenow')).toBe(rightWidth) + for (const side of ['old', 'new'] as const) { + const firstLine = await panelFile.locator(`[data-review-code][data-${side}-line="2"]`).boundingBox() + const lastLine = await panelFile.locator(`[data-review-code][data-${side}-line="4"]`).boundingBox() + if (firstLine === null || lastLine === null) throw new Error('Review text must be visible') + await page.mouse.move(firstLine.x + 7, firstLine.y + firstLine.height / 2) + await page.mouse.down() + await page.mouse.move(lastLine.x + 120, lastLine.y + lastLine.height / 2, { steps: 5 }) + await page.mouse.up() + await panelFile.getByRole('button', { name: '添加评论', exact: true }).waitFor() + expect(await panelFile.getByRole('textbox', { name: '留下评论…' }).count()).toBe(0) + const opposite = panelFile.locator(`[data-diff-side="${side === 'old' ? 'R' : 'L'}"]`).first() + expect(await opposite.evaluate(element => getComputedStyle(element).userSelect)).toBe('none') + await page.keyboard.press('ControlOrMeta+c') + const copied = await page.evaluate(() => navigator.clipboard.readText()) + expect(copied).toContain(side === 'old' ? 'n2 = 2' : "n2 = 'two'") + expect(copied).not.toContain(side === 'old' ? "n2 = 'two'" : 'n2 = 2') + expect(copied.match(/n3 = 3/g)).toHaveLength(1) + } + await panelFile.getByRole('button', { name: '添加评论', exact: true }).click() + await panelFile.getByRole('region', { name: '评论 R2–4', exact: true }).waitFor() + await panelFile.getByRole('textbox', { name: '留下评论…' }).fill('请核对边界条件') + await panelFile.getByRole('button', { name: 'GitHub 评论选项', exact: true }).click() + await page.getByRole('menuitem', { name: '发布单条评论', exact: true }).waitFor() + await page.keyboard.press('Escape') + await compareOrRefreshGolden(join(EXPECTED, 'review-composer.expected.md'), + await captureStableAria(page, '[data-forge-comment]', scaffold.workspaceCwd), MODE) + await page.getByRole('button', { name: '退出全屏', exact: true }).click() + const commentForm = panelFile.locator('[data-forge-comment]') + expect(await commentForm.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + await page.getByRole('button', { name: '全屏', exact: true }).click() + await page.setViewportSize({ width: 390, height: 780 }) + await commentForm.getByRole('textbox').focus() + expect(await commentForm.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + const narrowComment = await commentForm.boundingBox() + if (narrowComment === null) throw new Error('Comment form must remain visible') + expect(narrowComment.x + narrowComment.width).toBeLessThanOrEqual(390) + await page.setViewportSize({ width: 1680, height: 1000 }) + await panelFile.getByRole('button', { name: '开始评审', exact: true }).click() + await panelFile.locator('[data-forge-review-thread="pending"]').getByText('请核对边界条件', { exact: true }).waitFor() + await page.setViewportSize({ width: 1680, height: 500 }) + const changesScroll = view.locator('[data-forge-changes-scroll]') + await changesScroll.evaluate((element) => { element.scrollTop = element.scrollHeight }) + const reviewScroll = await changesScroll.evaluate(element => element.scrollTop) + expect(reviewScroll).toBeGreaterThan(0) + await view.getByRole('button', { name: '提交评审 (1)', exact: true }).click() + const reviewDialog = page.getByRole('dialog', { name: '提交评审', exact: true }) + await reviewDialog.waitFor() + expect(await reviewDialog.getByRole('textbox').count()).toBe(1) + expect(await reviewDialog.getByText('请核对边界条件', { exact: true }).count()).toBe(0) + expect(await changesScroll.evaluate(element => element.scrollTop)).toBe(reviewScroll) + await page.setViewportSize({ width: 390, height: 780 }) + expect(await reviewDialog.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + const narrowDialog = await reviewDialog.boundingBox() + if (narrowDialog === null) throw new Error('Review dialog must remain visible') + expect(narrowDialog.x + narrowDialog.width).toBeLessThanOrEqual(390) + await page.setViewportSize({ width: 1680, height: 500 }) + await page.keyboard.press('Escape') + expect(await reviewDialog.count()).toBe(0) + await view.getByRole('button', { name: '提交评审 (1)', exact: true }).click() + await reviewDialog.getByRole('radio', { name: '请求更改', exact: true }).check() + await reviewDialog.getByText('请求更改时，请填写评审总结', { exact: true }).waitFor() + expect(await reviewDialog.getByRole('button', { name: '提交评审', exact: true }).isDisabled()).toBe(true) + await compareOrRefreshGolden(join(EXPECTED, 'review-summary-required.expected.md'), + await captureStableAria(page, '[role="dialog"][aria-label="提交评审"]', scaffold.workspaceCwd), MODE) + await reviewDialog.getByRole('textbox', { name: '评审总结…', exact: true }).fill('需要补充边界检查') + await compareOrRefreshGolden(join(EXPECTED, 'submit-review.expected.md'), + await captureStableAria(page, '[role="dialog"][aria-label="提交评审"]', scaffold.workspaceCwd), MODE) + await reviewDialog.getByRole('button', { name: '提交评审', exact: true }).click() + await page.getByRole('alert').filter({ hasText: '已提交评审' }).waitFor() + await panelFile.locator('[data-forge-review-thread="published"]').getByText('请核对边界条件', { exact: true }).waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'review-record.expected.md'), await captureStableAria(page, '[data-forge-review-thread="published"]', scaffold.workspaceCwd), MODE) + const published: unknown = JSON.parse((await readFile(join(root, 'reviews.jsonl'), 'utf8')).trim()) + expect(published).toEqual({ endpoint: 'repos/octo/demo/pulls/7/reviews', body: { commit_id: HEAD7, event: 'REQUEST_CHANGES', body: '需要补充边界检查', + comments: [{ path: 'src/panel.ts', side: 'RIGHT', line: 4, start_line: 2, start_side: 'RIGHT', body: '请核对边界条件' }] } }) + await page.getByRole('button', { name: '退出全屏', exact: true }).click() + await panelFile.getByRole('button', { name: '6 行未变更', exact: true }).click() + await panelFile.getByText('export const n6 = 6', { exact: true }).first().waitFor({ timeout: 20_000 }) + await panelFile.getByRole('button', { name: '2 行未变更', exact: true }).waitFor() + await panelFile.getByRole('button', { name: 'panel.ts 的更多操作', exact: true }).click() + await page.getByRole('menuitem', { name: '复制路径', exact: true }).click() + await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe('src/panel.ts') + const docsFile = view.locator('[data-forge-diff-file="docs/panel.md"]') + await docsFile.getByRole('button', { name: '收起 panel.md', exact: true }).click() + await page.setViewportSize({ width: 1280, height: 500 }) + const scrollport = view.locator('[data-forge-changes-scroll]') + await scrollport.evaluate((element) => { element.scrollTop = 100; element.dispatchEvent(new Event('scroll')) }) + await panelFile.locator('[data-forge-file-label]').click() + const position = await scrollport.evaluate(element => element.scrollTop) + expect(position).toBeGreaterThan(0) + const originalFile = await panelFile.elementHandle() + await page.getByRole('button', { name: /^(?:New session|新.*会话)$/ }).last().click() + await expect.poll(() => view.isVisible()).toBe(false) + await page.locator(`[data-row-key="session:${sessionId}"]`).click() + await panelFile.getByText('export const n6 = 6', { exact: true }).first().waitFor({ timeout: 20_000 }) + expect(await panelFile.evaluate((element, original) => element === original, originalFile)).toBe(true) + await expect.poll(() => docsFile.getAttribute('data-expanded')).toBe(null) + await expect.poll(() => scrollport.evaluate(element => element.scrollTop)).toBe(position) + expect(await panelFile.locator('[data-forge-review-thread="published"]').count()).toBe(1) + await page.setViewportSize({ width: 1680, height: 1000 }) + await page.locator('[data-dockkit-tab]').filter({ hasText: '#7 的变更' }).locator('[data-dockkit-tab-close]').click() + await expect.poll(() => view.count()).toBe(0) + if (await header.getAttribute('aria-pressed') !== 'true') await header.click() + await change.getByRole('button', { name: '查看 #7 的变更：新增 128 行，删除 14 行', exact: true }).click() + await panelFile.getByRole('button', { name: '6 行未变更', exact: true }).waitFor() + expect(await panelFile.locator('[data-forge-review-thread]').count()).toBe(0) + await view.getByRole('button', { name: '提交评审', exact: true }).click() + await reviewDialog.waitFor() + expect(await reviewDialog.getByRole('textbox').inputValue()).toBe('') + expect(await reviewDialog.getByRole('radio', { name: '评论', exact: true }).isChecked()).toBe(true) + await page.keyboard.press('Escape') + + // GitHub refuses the diff of pull request 9 as too large, so its view offers the web page instead of a retry. + scaffold.ctx.forgeSession.track(session, DRAFT) + await expect.poll(() => header.getAttribute('aria-pressed'), { timeout: 20_000 }).toBe('false') + await header.click() + const draft = page.locator(`[data-forge-change="${DRAFT}"]`) + await draft.getByRole('button', { name: '展开 #9', exact: true }).click() + await draft.getByRole('button', { name: '查看 #9 的变更：新增 30 行，删除 2 行', exact: true }).click({ timeout: 20_000 }) + const refused = page.locator('[data-forge-changes="change"]').filter({ hasText: 'Add the merge button' }) + await refused.getByRole('status').filter({ hasText: '变更太大，无法在这里显示' }).waitFor({ timeout: 20_000 }) + await refused.getByRole('button', { name: '在浏览器中查看', exact: true }).waitFor() + expect(await refused.getByRole('button', { name: '重试', exact: true }).count()).toBe(0) + + const calls = (await readFile(join(root, 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[]) + expect(calls).toContainEqual(['pr', 'diff', '7', '--repo', 'github.com/octo/demo', '--color', 'never']) + expect(calls).toContainEqual(['pr', 'diff', '9', '--repo', 'github.com/octo/demo', '--color', 'never']) + expect(calls).toContainEqual([ + 'api', '--hostname', 'github.com', '-H', 'Accept: application/vnd.github.raw+json', `repos/octo/demo/contents/src/panel.ts?ref=${HEAD7}`, + ]) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + + +it.skipIf(MODE === 'record')('retains a wrapped code line and tree width across tab and Session switches', async () => { + const { page, scaffold, root, tripwire } = await launchPanel('web-e2e-forge-reading-position') + const paths = ['src/before-0.ts', 'src/before-1.ts', 'src/before-2.ts', 'src/server.ts', 'src/after.ts'] + const patch = paths.map(path => [ + `diff --git a/${path} b/${path}`, 'index 1111111..2222222 100644', `--- a/${path}`, `+++ b/${path}`, + '@@ -1,650 +1,650 @@', '-const oldValue = true;', '+const newValue = true;', + ...Array.from({ length: 649 }, (_, index) => ` const value_${index + 2} = "${'x'.repeat(24 + (index + 2) % 70)}";`), '', + ].join('\n')).join('\n') + await writeFile(join(root, 'pr-7.diff'), patch) + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + const session = scaffold.ctx.sessions.get(sessionId) + if (session === undefined) throw new Error('Session must stay loaded') + scaffold.ctx.forgeSession.track(session, PULL) + // Keep the file tree and the Session sidebar visible together on every platform. + await page.setViewportSize({ width: 2400, height: 700 }) + await page.locator('[data-forge-header]').click() + await page.locator(`[data-forge-change="${PULL}"]`).getByRole('button', { name: /查看 #7 的变更/ }).click() + const view = page.locator('[data-forge-changes="change"]') + const scroll = view.locator('[data-forge-changes-scroll]') + const file = view.locator('[data-forge-diff-file="src/server.ts"]') + const code = file.locator('[data-review-code][data-new-line="300"]') + const separator = view.getByRole('separator', { name: '调整文件树宽度', exact: true }) + const beforeFile = view.locator('[data-forge-diff-file="src/before-0.ts"]') + // ResizeObserver runs between rendering frames, including when an ancestor becomes hidden. + const layout = () => page.evaluate(() => new Promise((resolve) => { + requestAnimationFrame(() => { requestAnimationFrame(() => { resolve() }) }) + })) + const reading = () => file.evaluate((element) => { + const viewport = element.closest('[data-forge-changes-scroll]')! + const top = Math.max(viewport.getBoundingClientRect().top, element.firstElementChild!.getBoundingClientRect().bottom) + const line = [...element.querySelectorAll('[data-review-code][data-new-line]')] + .find(row => row.getBoundingClientRect().bottom > top + 1)! + return { path: element.getAttribute('data-forge-diff-file'), line: line.dataset.newLine, + offset: line.getBoundingClientRect().top - top, scrollTop: viewport.scrollTop } + }) + await code.waitFor() + for (const width of [240, 320]) { + if (width === 320) { + for (let step = 0; step < 4; step += 1) await separator.press('ArrowRight') + await beforeFile.getByRole('button', { name: '收起 before-0.ts', exact: true }).click() + } + await layout() + await code.evaluate((element) => { + const viewport = element.closest('[data-forge-changes-scroll]')! + const header = element.closest('[data-forge-diff-file]')!.firstElementChild! + const top = viewport.getBoundingClientRect().top + header.getBoundingClientRect().height + viewport.scrollTop += element.getBoundingClientRect().top - top + 7 + }) + await layout() + const position = await reading() + expect(position.line).toBe('300') + expect(position.offset).toBe(-7) + for (const destination of ['tab', 'session', 'tab', 'session']) { + if (destination === 'tab') await page.getByRole('tab').filter({ hasText: '变更请求' }).click() + else await page.getByRole('button', { name: '新建会话', exact: true }).last().click() + await expect.poll(() => view.isVisible()).toBe(false) + await layout() + expect(await scroll.evaluate(element => element.clientWidth)).toBe(0) + if (destination === 'tab') await page.getByRole('tab').filter({ hasText: '#7 的变更' }).click() + else await page.locator(`[data-row-key="session:${sessionId}"]`).click() + await view.waitFor() + await layout() + expect(await separator.getAttribute('aria-valuenow')).toBe(String(width)) + expect(await reading()).toEqual(position) + expect(await beforeFile.getAttribute('data-expanded')).toBe(width === 240 ? '' : null) + } + } + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('uses horizontal arrows to navigate files while preserving vertical scrolling and comment editing', async () => { + const { scaffold, page, project, tripwire } = await launchPanel('web-e2e-forge-file-keys') + await git(project, 'update-ref', 'refs/remotes/origin/main', 'HEAD') + await git(project, 'symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main') + for (const path of ['a.txt', 'b.txt', 'c.txt']) { + await writeFile(join(project, path), Array.from({ length: path === 'c.txt' ? 1 : 80 }, (_, line) => `line ${line + 1}\n`).join('')) + } + const { settled } = await sendPrompt(page, scaffold) + await settled + await page.locator('[data-forge-header]').click() + await page.locator('[data-forge-panel]').getByRole('button', { name: '刷新状态', exact: true }).click() + await page.locator('[data-forge-local]').getByRole('button', { name: /查看本会话的变更：3 个文件/ }).click() + const view = page.locator('[data-forge-changes="local"]') + const scroll = view.getByRole('region', { name: '全部 3 个文件', exact: true }) + await scroll.waitFor() + await page.getByRole('button', { name: '全屏', exact: true }).click() + await page.setViewportSize({ width: 1280, height: 500 }) + const tree = view.getByRole('navigation') + const a = view.locator('[data-forge-diff-file="a.txt"]') + const b = view.locator('[data-forge-diff-file="b.txt"]') + const c = view.locator('[data-forge-diff-file="c.txt"]') + await b.getByRole('button', { name: '收起 b.txt', exact: true }).click() + await scroll.evaluate((element) => { element.scrollTop = 0 }) + await scroll.focus() + await page.keyboard.press('ArrowLeft') + expect(await scroll.evaluate(element => element.scrollTop)).toBe(0) + expect(await scroll.evaluate(element => getComputedStyle(element).outlineStyle)).toBe('none') + await page.keyboard.press('ArrowDown') + await expect.poll(() => scroll.evaluate(element => element.scrollTop)).toBeGreaterThan(0) + await scroll.evaluate((element) => { element.scrollTop = 0 }) + await page.keyboard.press('ArrowRight') + await expect.poll(() => tree.getByRole('button', { name: 'b.txt', exact: true }).getAttribute('aria-current')).toBe('true') + expect(await b.getAttribute('data-expanded')).toBe('') + expect(await scroll.evaluate(element => document.activeElement === element)).toBe(true) + await page.keyboard.press('ArrowRight') + await expect.poll(() => tree.getByRole('button', { name: 'c.txt', exact: true }).getAttribute('aria-current')).toBe('true') + const lastPosition = await scroll.evaluate(element => element.scrollTop) + const lastBox = await c.boundingBox(), viewport = await scroll.boundingBox() + if (lastBox === null || viewport === null) throw new Error('The last file and scroll viewport must be rendered') + expect(lastBox.y).toBeGreaterThan(viewport.y) + expect(lastBox.y).toBeLessThan(viewport.y + viewport.height) + await page.keyboard.press('ArrowRight') + expect(await scroll.evaluate(element => element.scrollTop)).toBe(lastPosition) + await page.keyboard.press('ArrowLeft') + await expect.poll(() => tree.getByRole('button', { name: 'b.txt', exact: true }).getAttribute('aria-current')).toBe('true') + await page.keyboard.press('ArrowLeft') + await expect.poll(() => tree.getByRole('button', { name: 'a.txt', exact: true }).getAttribute('aria-current')).toBe('true') + await b.evaluate((element) => { + const viewport = element.closest('[data-forge-changes-scroll]')! + viewport.scrollTop += element.getBoundingClientRect().top - viewport.getBoundingClientRect().top + 100 + }) + await page.keyboard.press('ArrowRight') + await expect.poll(() => tree.getByRole('button', { name: 'c.txt', exact: true }).getAttribute('aria-current')).toBe('true') + await tree.getByRole('button', { name: 'a.txt', exact: true }).click() + await a.getByRole('button', { name: '选择第 R1 行', exact: true }).click() + await a.getByRole('button', { name: '添加评论', exact: true }).click() + const input = a.getByRole('textbox', { name: '留下评论…', exact: true }) + await input.fill('keep editing') + await input.press('ArrowLeft') + expect(await input.evaluate(element => (element as HTMLTextAreaElement).selectionStart)).toBe(11) + await input.press('ArrowRight') + expect(await input.inputValue()).toBe('keep editing') + expect(await tree.getByRole('button', { name: 'a.txt', exact: true }).getAttribute('aria-current')).toBe('true') + expect(await input.evaluate(element => document.activeElement === element)).toBe(true) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('keeps localized status columns separate and long file lists inside one vertical scroller', async () => { + const { scaffold, page, project, tripwire } = await launchPanel('web-e2e-forge-layout') + await page.locator('[data-forge-current-branch]').waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'worktree-option.expected.md'), + await captureStableAria(page, '[data-forge-worktree]', scaffold.workspaceCwd), MODE) + await page.getByRole('button', { name: '收起侧边栏', exact: true }).click() + await page.setViewportSize({ width: 390, height: 844 }) + await expect.poll(() => page.locator('[data-forge-worktree]') + .evaluate(element => element.getBoundingClientRect().right)).toBeLessThanOrEqual(390) + await page.setViewportSize({ width: 1680, height: 1000 }) + await git(project, 'update-ref', 'refs/remotes/origin/main', 'HEAD') + await git(project, 'symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main') + await mkdir(join(project, 'src')) + await Promise.all(Array.from({ length: 60 }, (_, index) => writeFile(join(project, 'src', `file-${index}.ts`), `export const value = ${index}\n`))) + const { settled } = await sendPrompt(page, scaffold) + const session = scaffold.ctx.sessions.get(await settled) + if (session === undefined) throw new Error('The Session must stay loaded') + scaffold.ctx.forgeSession.track(session, PULL) + await page.locator('[data-forge-header]').click() + const panel = page.locator('[data-forge-panel]') + await panel.getByRole('button', { name: '刷新状态', exact: true }).click() + const local = panel.locator('[data-forge-local]') + await local.locator('button[aria-expanded]').click() + await expect.poll(() => local.locator('li').count(), { timeout: 20_000 }).toBe(60) + for (const width of [1280, 390]) { + await page.setViewportSize({ width, height: 700 }) + const outerScrollers = await panel.evaluate((element) => { + const scrollers: string[] = [] + for (let ancestor = element.parentElement; ancestor !== null; ancestor = ancestor.parentElement) { + if (/auto|scroll/.test(getComputedStyle(ancestor).overflowY) && ancestor.scrollHeight > ancestor.clientHeight + 1) { + scrollers.push(ancestor.className) + } + } + return scrollers + }) + expect(outerScrollers).toEqual([]) + expect(await panel.evaluate(element => element.scrollHeight > element.clientHeight)).toBe(true) + await local.locator('li').last().scrollIntoViewIfNeeded() + expect(await local.locator('li').last().isVisible()).toBe(true) + } + await local.locator('button[aria-expanded]').click() + const change = panel.locator(`[data-forge-change="${PULL}"]`) + for (const [locale, labels] of [ + ['zh', ['检查', '评审', '合并', '变更']], + ['en', ['Checks', 'Review', 'Merge', 'Changes']], + ['de', ['Prüfungen', 'Review', 'Zusammenführen', 'Änderungen']], + ] as const) { + await scaffold.ctx.settings.update('locale', { preference: locale }) + await change.getByText(labels[0], { exact: true }).waitFor() + if (locale === 'en') { + await compareOrRefreshGolden(join(EXPECTED, 'local-card.expected.md'), + await captureStableAria(page, '[data-forge-local]', scaffold.workspaceCwd), MODE) + } + for (const width of [1280, 390]) { + await page.setViewportSize({ width, height: 700 }) + await expect.poll(() => change.evaluate(element => element.getBoundingClientRect().right)).toBeLessThanOrEqual(width) + await change.getByText(labels[3], { exact: true }).hover() + for (const label of labels) { + const geometry = await change.getByText(label, { exact: true }).evaluate((element) => { + const value = element.nextElementSibling + if (value === null) throw new Error('Status label must have a value') + const range = document.createRange() + range.selectNodeContents(element) + const name = range.getBoundingClientRect() + const content = value.getBoundingClientRect() + const row = element.parentElement! + const icon = element.previousElementSibling! + const rowRect = row.getBoundingClientRect() + return { + gap: content.left - name.right, + iconInset: icon.getBoundingClientRect().left - rowRect.left, + rowInset: rowRect.left - row.closest('[data-forge-change]')!.getBoundingClientRect().left, + labelWidth: element.getBoundingClientRect().width, + valueOffset: content.left - rowRect.left, + right: content.right, + width: document.documentElement.clientWidth, + } + }) + expect(geometry.gap).toBeGreaterThanOrEqual(8) + expect(geometry.iconInset).toBe(8) + expect(geometry.rowInset).toBeGreaterThanOrEqual(6) + expect(geometry.rowInset).toBeLessThanOrEqual(7) + if (locale === 'zh') { + expect(geometry.labelWidth).toBe(32) + expect(geometry.valueOffset).toBe(76) + } + expect(geometry.right).toBeLessThanOrEqual(geometry.width) + } + } + } + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record')('keeps long branch details accessible by touch and keyboard across the hero row breakpoints', async () => { + const branch = 'feature/a-long-current-branch-name-for-mobile-review' + const { page, scaffold, tripwire } = await launchPanel('web-e2e-forge-branch-details', 'normal', { branch, hasTouch: true }) + const option = page.locator('[data-forge-worktree]') + const chip = option.locator('[data-forge-current-branch]') + await chip.waitFor() + await page.getByRole('button', { name: '收起侧边栏', exact: true }).click() + for (const [locale, label] of [['zh', `当前分支：${branch}`], ['en', `Current branch: ${branch}`], ['de', `Aktueller Branch: ${branch}`]] as const) { + await scaffold.ctx.settings.update('locale', { preference: locale }) + await option.getByRole('button', { name: label, exact: true }).waitFor() + for (const width of [390, 600, 601, 700, 1280]) { + await page.setViewportSize({ width, height: 844 }) + await chip.scrollIntoViewIfNeeded() + await expect.poll(() => option.evaluate((element) => { + const row = element.closest('[class*="heroWorkspaceRow"]')! + const ancestors: Element[] = [] + for (let node: Element | null = row; node !== null; node = node.parentElement) ancestors.push(node) + return { + fits: element.getBoundingClientRect().right <= innerWidth, + overflow: ancestors.filter(node => node.scrollWidth > node.clientWidth + 1).map(node => node.className), + } + })).toEqual({ fits: true, overflow: [] }) + } + } + await scaffold.ctx.settings.update('locale', { preference: 'en' }) + await option.getByRole('button', { name: `Current branch: ${branch}`, exact: true }).waitFor() + await page.setViewportSize({ width: 390, height: 844 }) + expect(await chip.locator('span').evaluate(element => element.scrollWidth > element.clientWidth)).toBe(true) + const tooltip = page.getByRole('tooltip', { exact: true, name: `Current branch: ${branch}` }) + await chip.tap() + await tooltip.waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'branch-details.expected.md'), await tooltip.ariaSnapshot(), MODE) + await chip.tap() + await tooltip.waitFor({ state: 'hidden' }) + await chip.tap() + await tooltip.waitFor() + await page.locator('[class*="heroWorkspaceRow"]').tap({ position: { x: 1, y: 1 } }) + await tooltip.waitFor({ state: 'hidden' }) + await chip.focus() + await page.keyboard.press('Tab') + await page.keyboard.press('Shift+Tab') + await tooltip.waitFor() + await page.keyboard.press('Escape') + await tooltip.waitFor({ state: 'hidden' }) + await page.keyboard.press('Enter') + await tooltip.waitFor() + await page.keyboard.press('Escape') + await tooltip.waitFor({ state: 'hidden' }) + expect(await option.getByRole('checkbox').isChecked()).toBe(false) + expect(await page.getByRole('menu').count()).toBe(0) + await scaffold.ctx.settings.update('locale', { preference: 'zh' }) + await option.getByRole('checkbox', { name: '新建工作树', exact: true }).waitFor() + const { settled } = await sendPrompt(page, scaffold) + await settled + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record').each(['darwin', 'win32'] as const)('closes diff menus when the %s desktop shortcut deactivates a retained tab', async (platform) => { + const { page, scaffold, project, tripwire } = await launchPanel(`web-e2e-forge-menu-${platform}`, 'normal', { desktop: platform }) + await git(project, 'update-ref', 'refs/remotes/origin/main', 'HEAD') + await git(project, 'symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main') + await writeFile(join(project, 'README.md'), 'review this change\n') + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + await page.locator('[data-forge-header]').click() + await page.locator('[data-forge-panel]').getByRole('button', { name: '刷新状态', exact: true }).click() + await page.locator('[data-forge-local]').getByRole('button', { name: /查看本会话的变更：1 个文件/ }).click() + const view = page.locator('[data-forge-changes="local"]') + await view.locator('[data-forge-diff-file="README.md"]').waitFor() + for (const name of ['分支', '全部 1 个文件', 'README.md 的更多操作']) { + await view.getByRole('button', { name, exact: true }).click() + await page.getByRole('menu').waitFor() + await page.evaluate((mac) => { window.forgeKeyboard.deliver({ + kind: 'keyboard', frameName: '', revision: window.forgeKeyboard.revision, code: 'KeyN', + meta: mac, control: !mac, alt: false, shift: false, repeat: false, + }) }, platform === 'darwin') + await expect.poll(() => view.isVisible()).toBe(false) + await expect.poll(() => page.getByRole('menu').count()).toBe(0) + await page.locator(`[data-row-key="session:${sessionId}"]`).click() + await view.waitFor() + await expect.poll(() => page.getByRole('menu').count()).toBe(0) + } + expect(tripwire.warnings).toEqual([]) +}) + +it.skipIf(MODE === 'record').each([120, 4000])('types a review comment beside %i changed lines', async (count) => { + const { scaffold, page, root, tripwire } = await launchPanel('web-e2e-forge-review-typing') + const patch = ['diff --git a/src/typing.ts b/src/typing.ts', 'index 1111111..2222222 100644', + '--- a/src/typing.ts', '+++ b/src/typing.ts', `@@ -1,${count} +1,${count} @@`, + ...Array.from({ length: count }, (_, index) => { + const context = index % 80 === 0 ? 'wrapped context '.repeat(600) : index % 5 === 0 ? 'context '.repeat(30) : '' + return `-export const value${index} = [${index}, '${context}']\n+export const value${index} = [${index + 1}, '${context}']` + }), ''].join('\n') + await writeFile(join(root, 'pr-7.diff'), patch) + const { settled } = await sendPrompt(page, scaffold) + const sessionId = await settled + const session = scaffold.ctx.sessions.get(sessionId) + if (session === undefined) throw new Error('Session must stay loaded') + scaffold.ctx.forgeSession.track(session, PULL) + await page.locator('[data-forge-header]').click() + const change = page.locator(`[data-forge-change="${PULL}"]`) + await change.getByRole('button', { name: '查看 #7 的变更：新增 128 行，删除 14 行', exact: true }).click() + const file = page.locator('[data-forge-diff-file="src/typing.ts"]') + const collapsed = file.getByRole('button', { name: /^文件较大，/ }) + await file.waitFor() + if (count > 120) await collapsed.click() + await file.getByRole('button', { name: '选择第 R5 行', exact: true }).click() + await file.getByRole('button', { name: '添加评论', exact: true }).click() + const input = file.getByRole('textbox', { name: '留下评论…', exact: true }) + await input.waitFor() + const field = await input.boundingBox() + if (field === null) throw new Error('Comment field must be visible') + await page.mouse.move(field.x + field.width - 3, field.y + field.height - 3) + await page.mouse.down() + await page.mouse.move(field.x + field.width - 3, field.y + field.height + 77, { steps: 5 }) + await page.mouse.up() + const resized = await input.boundingBox() + if (resized === null) throw new Error('Resized comment field must remain visible') + expect(resized.height).toBeGreaterThan(field.height + 50) + await input.fill('Review a wrapped line. '.repeat(80)) + expect(await input.evaluate(element => element.scrollHeight > element.clientHeight)).toBe(true) + expect(await input.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + await input.fill('') + await page.keyboard.type('Check the boundary') + await page.keyboard.press('Enter') + const cdp = await page.context().newCDPSession(page) + try { + await cdp.send('Input.imeSetComposition', { text: '检查', selectionStart: 2, selectionEnd: 2 }) + expect(await input.inputValue()).toBe('Check the boundary\n检查') + expect(await file.locator('[data-forge-review-thread]').count()).toBe(0) + await cdp.send('Input.insertText', { text: '检查边界条件' }) + } finally { await cdp.detach() } + expect(await input.inputValue()).toBe('Check the boundary\n检查边界条件') + await input.fill(' \n') + expect(await file.getByRole('button', { name: '开始评审', exact: true }).isDisabled()).toBe(true) + await input.fill('检查边界条件') + await file.getByRole('button', { name: '开始评审', exact: true }).click() + await file.locator('[data-forge-review-thread="pending"]').getByText('检查边界条件', { exact: true }).waitFor() + expect(tripwire.pageErrors).toEqual([]) +}) diff --git a/apps/web/tests/goal-bar.e2e.ts b/apps/web/tests/goal-bar.e2e.ts index a93c9d7c13..132d44569b 100644 --- a/apps/web/tests/goal-bar.e2e.ts +++ b/apps/web/tests/goal-bar.e2e.ts @@ -2,7 +2,7 @@ // The command creates a real projected goal in a real Host session. The // goldens pin the active and disarmed strips, while the clear gesture proves // the acknowledged tombstone leaves neither stale chrome nor a -// duplicate-mutation error. +// duplicate-mutation error. A blocked goal stays resumable after an edit. import { fileURLToPath } from 'node:url' import { join } from 'node:path' import type { Browser, Page } from 'playwright' @@ -18,6 +18,7 @@ import { connectFreshWorkspace, expectTooltipOnTop, newEnglishPage, saveFailureS const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/goal-bar', import.meta.url)) const ACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'active.expected.md') const INACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'inactive.expected.md') +const BLOCKED_EXPECTED = join(SNAPSHOT_DIR, 'blocked.expected.md') const OVERLAY = fileURLToPath(new URL('./goal-bar.overlay.yml', import.meta.url)) const MODE = webSnapshotMode() @@ -108,7 +109,46 @@ describe('web e2e: goal bar clear convergence', () => { expect(tripwire.warnings).toEqual([]) }, 60_000) + it('resumes a blocked goal after its objective is edited', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-goal-bar-blocked-resume')) + // `/goal ` refuses to replace an unfinished goal, so start from none. + for (const existing of scaffold.ctx.agents.list()) { + const current = scaffold.ctx.goals.get(existing) + if (current !== undefined) scaffold.ctx.goals.clear(existing, current) + } + const input = page.locator('[data-composer-input]') + await input.fill('/goal retry after a blocker') + await input.press('Enter') + const bar = page.locator('[data-goal-bar]') + await bar.getByRole('button', { name: 'Pause goal' }).waitFor({ timeout: 10_000 }) + + const agents = scaffold.ctx.agents.list() + expect(agents).toHaveLength(1) + const agent = agents[0]! + const active = scaffold.ctx.goals.get(agent)! + scaffold.ctx.goals.block(agent, active, { code: 'stalled', message: 'No progress in 3 rounds' }) + await bar.getByText('Blocked Goal').waitFor({ timeout: 10_000 }) + expect(await bar.getByRole('button', { name: 'Resume goal' }).count()).toBe(1) + + await bar.getByRole('button', { name: 'Edit goal' }).click() + await bar.getByRole('textbox', { name: 'Goal objective' }).fill('retry with the edited plan') + await bar.getByRole('button', { name: 'Save goal' }).click() + await bar.getByRole('button', { name: 'Edit goal' }).waitFor({ timeout: 10_000 }) + await bar.getByText('retry with the edited plan').waitFor({ timeout: 10_000 }) + expect(scaffold.ctx.goals.get(agent)?.phase).toBe('blocked') + const blocked = await captureStableAria(page, '[data-goal-bar]', scaffold.workspaceCwd) + await compareOrRefreshGolden(BLOCKED_EXPECTED, blocked, MODE) + + await bar.getByRole('button', { name: 'Resume goal' }).click() + await bar.getByRole('button', { name: 'Pause goal' }).waitFor({ timeout: 10_000 }) + expect(scaffold.ctx.goals.get(agent)).toMatchObject({ + phase: 'active', activation: 'armed', objective: 'retry with the edited plan', + }) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 60_000) + it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => { - await assertFixtureInventory(SNAPSHOT_DIR, ['active.expected.md', 'inactive.expected.md']) + await assertFixtureInventory(SNAPSHOT_DIR, ['active.expected.md', 'blocked.expected.md', 'inactive.expected.md']) }) }) diff --git a/apps/web/tests/hover-input.e2e.ts b/apps/web/tests/hover-input.e2e.ts index cae5220a89..8ec5679df0 100644 --- a/apps/web/tests/hover-input.e2e.ts +++ b/apps/web/tests/hover-input.e2e.ts @@ -95,18 +95,24 @@ it.each([false, true])('keeps workspace and archived search actions reachable wi expect(await shortcut.count()).toBe(1) expect(await page.evaluate(() => matchMedia('(pointer: coarse)').matches)).toBe(hasTouch) expect(await shortcut.isVisible()).toBe(!hasTouch) - for (const key of ['ArrowDown', 'Tab']) { + if (hasTouch) { + await page.keyboard.press('Escape') + await page.setViewportSize({ width: 390, height: 900 }) + await page.locator('[data-sidebar-drawer]').waitFor() + await page.locator('[data-shell-leading]').getByRole('button', { name: 'Open sidebar', exact: true }).tap() + await activate(actions) + await archive.waitFor() + } + for (const key of ['ArrowDown', 'Home']) { await page.keyboard.press(key) expect(await page.locator('html').getAttribute('data-input-modality')).toBe('keyboard') expect(await page.getByRole('menu').evaluate(menu => menu.contains(document.activeElement))).toBe(true) expect(await shortcut.isVisible()).toBe(true) if (hasTouch) { - await page.setViewportSize({ width: 390, height: 900 }) await expect.poll(() => shortcut.evaluate((element) => { const bounds = element.getBoundingClientRect() return bounds.left >= 0 && bounds.right <= window.innerWidth })).toBe(true) - await page.setViewportSize({ width: 1280, height: 900 }) } await page.keyboard.press('Escape') if (!hasTouch) await row.hover() @@ -114,6 +120,13 @@ it.each([false, true])('keeps workspace and archived search actions reachable wi await archive.waitFor() expect(await shortcut.isVisible()).toBe(!hasTouch) } + if (hasTouch) { + await page.keyboard.press('Escape') + await page.setViewportSize({ width: 1280, height: 900 }) + await page.locator('[data-sidebar-drawer]').waitFor({ state: 'detached' }) + await activate(actions) + await archive.waitFor() + } await activate(archive) await row.waitFor({ state: 'detached' }) await activate(page.getByRole('button', { name: 'View options', exact: true })) @@ -224,19 +237,23 @@ it.each([false, true])('keeps actions and focus usable with touch=%s across layo await page.getByRole('tooltip').waitFor({ state: 'detached' }) const blockedSplit = panel.locator('[data-dockkit-split-button]').last() expect(await blockedSplit.isDisabled()).toBe(true) - const hit = await blockedSplit.evaluate((button) => { - const bounds = button.getBoundingClientRect() - const x = bounds.x + bounds.width / 2 - const y = bounds.y + bounds.height / 2 - const target = document.elementFromPoint(x, y) - return { x, y, wrapperReceivesInput: target === button.parentElement, cursor: target && getComputedStyle(target).cursor } - }) - expect(hit.wrapperReceivesInput).toBe(true) - expect(['auto', 'default']).toContain(hit.cursor) - // Coordinate input exercises CSS hit testing over the disabled button itself. - if (hasTouch) await page.touchscreen.tap(hit.x, hit.y) - else await page.mouse.click(hit.x, hit.y) - await page.getByRole('tooltip').filter({ hasText: 'Two panes is the limit' }).waitFor() + if (hasTouch) { + expect(await blockedSplit.isVisible()).toBe(false) + expect(await page.getByRole('tooltip').count()).toBe(0) + } else { + const hit = await blockedSplit.evaluate((button) => { + const bounds = button.getBoundingClientRect() + const x = bounds.x + bounds.width / 2 + const y = bounds.y + bounds.height / 2 + const target = document.elementFromPoint(x, y) + return { x, y, wrapperReceivesInput: target === button.parentElement, cursor: target && getComputedStyle(target).cursor } + }) + expect(hit.wrapperReceivesInput).toBe(true) + expect(['auto', 'default']).toContain(hit.cursor) + // Coordinate input exercises CSS hit testing over the disabled button itself. + await page.mouse.click(hit.x, hit.y) + await page.getByRole('tooltip').filter({ hasText: 'Two panes is the limit' }).waitFor() + } expect(await panel.locator('[data-dockkit-pane]').count()).toBe(2) expect(consoleWatch.pageErrors).toEqual([]) }) diff --git a/apps/web/tests/idle-submission-handoff.e2e.ts b/apps/web/tests/idle-submission-handoff.e2e.ts index 25fcebadb6..958c1f5e30 100644 --- a/apps/web/tests/idle-submission-handoff.e2e.ts +++ b/apps/web/tests/idle-submission-handoff.e2e.ts @@ -1,13 +1,10 @@ /** Keep idle submissions in Chat across independently delivered Inbox and transcript frames. */ -import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' -import { tmpdir } from 'node:os' -import { join } from 'node:path' +import { readFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { chromium, type Page } from 'playwright' import { expect, it, onTestFinished } from 'vitest' import type { InboxState } from '@deepseek-ai/dsh-agent/types' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' -import { deriveReplayScript, parseSessionLog } from '@deepseek-ai/dsh-llm-replay' import { parseRemoteStreamClientMessage, parseRemoteStreamServerMessage, } from '@deepseek-ai/dsh-api-gateway/stream-protocol' @@ -71,7 +68,6 @@ class HistoryDeliveryGate { turnStartDelivery(): Delivery | undefined { return this.buffered.find(item => item.event?.type === 'turn/start') } - turnEndDelivery(): Delivery | undefined { return this.buffered.find(item => item.event?.type === 'turn/end') } releaseThrough(target: Delivery): void { let reached = false @@ -123,8 +119,6 @@ it.skipIf(webSnapshotMode() === 'record').each(['inbox-first', 'transcript-first 'keeps an idle submission in Chat under CPU throttling (%s)', async (order) => { const scaffold = await launchWebScaffold({ replayFixture: FIXTURE, compareReplaySession: false }) onTestFinished(() => scaffold.close()) - const releasePrompt = Promise.withResolvers() - const promptBlocked = Promise.withResolvers() const gate = new HistoryDeliveryGate() try { await seedSession(scaffold, await readFile(FIXTURE, 'utf8'), SESSION_ID) @@ -140,21 +134,15 @@ it.skipIf(webSnapshotMode() === 'record').each(['inbox-first', 'transcript-first await page.getByRole('button', { name: 'Send message', exact: true }).waitFor() const cdp = await page.context().newCDPSession(page) await cdp.send('Emulation.setCPUThrottlingRate', { rate: 6 }) - await page.route('**/api/session/prompt', async (route) => { - promptBlocked.resolve(undefined) - await releasePrompt.promise - await route.continue() - }, { times: 1 }) const trace: Array<{ phase: string } & Awaited>> = [] gate.holding = true + const settled = whenTurnSettled(scaffold) const input = page.locator('[data-composer-input]').first() await input.fill(TEXT) await input.press('Enter') - await promptBlocked.promise + // The prompt receipt is not a stream frame: the accepted echo shows while the gate holds every Host frame. await poll(() => placement(page)).toMatchObject({ echo: 1, dock: 0, durable: 0 }) - trace.push({ phase: 'optimistic', ...await placement(page) }) - const settled = whenTurnSettled(scaffold) - releasePrompt.resolve(undefined) + trace.push({ phase: 'accepted', ...await placement(page) }) if (order === 'transcript-first') { await poll(() => gate.turnStartDelivery()).toBeDefined() @@ -198,88 +186,6 @@ it.skipIf(webSnapshotMode() === 'record').each(['inbox-first', 'transcript-first await cdp.detach() expect(tripwire.pageErrors).toEqual([]) } finally { - releasePrompt.resolve(undefined) - gate.releaseAll() - } - }, -) - -it.skipIf(webSnapshotMode() === 'record').each(['ABC', 'ACB', 'BAC', 'BCA', 'CAB', 'CBA'])( - 'hands off three rapid submissions through all Turns in Host order %s', async (hostOrder) => { - const root = await mkdtemp(join(tmpdir(), 'dsh-input-handoff-')) - onTestFinished(() => rm(root, { recursive: true, force: true })) - const releases = new Map(['A', 'B', 'C'].map(id => [id, Promise.withResolvers()])) - const blocked = new Set() - const gate = new HistoryDeliveryGate() - try { - const fixture = await readFile(FIXTURE, 'utf8') - const recorded = deriveReplayScript(parseSessionLog(fixture)) - expect(recorded).toHaveLength(1) - const override = join(root, 'replay.override.json') - await writeFile(override, JSON.stringify([recorded[0], recorded[0], recorded[0]])) - const scaffold = await launchWebScaffold({ replayFixture: FIXTURE, replayOverride: override, compareReplaySession: false }) - onTestFinished(() => scaffold.close()) - await seedSession(scaffold, fixture, SESSION_ID) - const browser = await chromium.launch() - onTestFinished(() => browser.close()) - const page = await newEnglishPage(browser) - const tripwire = watchConsole(page) - await gate.install(page) - await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) - await page.locator('[role="treeitem"]').first().click() - await page.locator('[role="treeitem"]').nth(1).click() - await page.locator('[data-chat-flow-kind="user"]').first().waitFor() - await page.getByRole('button', { name: 'Send message', exact: true }).waitFor() - const text = (id: string) => `RAPID_INPUT_${id}` - await page.route('**/api/session/prompt', async (route) => { - const request = route.request().postData() ?? '' - const id = [...releases.keys()].find(id => request.includes(text(id))) - if (id === undefined) throw new Error('unexpected prompt in rapid input fixture') - blocked.add(id) - await releases.get(id)!.promise - await route.continue() - }) - gate.holding = true - const input = page.locator('[data-composer-input]').first() - for (const id of releases.keys()) { - await input.fill(text(id)) - await input.press('Enter') - await poll(() => blocked.has(id)).toBe(true) - await poll(() => placement(page, text(id))).toMatchObject({ echo: 1, dock: 0, durable: 0 }) - } - const entered: string[] = [] - for (const id of hostOrder) { - const settled = whenTurnSettled(scaffold) - releases.get(id)!.resolve(undefined) - await poll(() => gate.turnStartDelivery()).toBeDefined() - gate.releaseThrough(gate.turnStartDelivery()!) - await poll(() => gate.admissionDelivery(text(id))).toBeDefined() - gate.releaseThrough(gate.admissionDelivery(text(id))!) - entered.push(id) - for (const candidate of releases.keys()) { - const admitted = entered.includes(candidate) - await poll(() => placement(page, text(candidate))).toMatchObject({ - echo: admitted ? 0 : 1, dock: 0, durable: admitted ? 1 : 0, - }) - } - await poll(() => gate.inboxDelivery(true, text(id))).toBeDefined() - gate.releaseThrough(gate.inboxDelivery(true, text(id))!) - await poll(() => placement(page, text(id))).toMatchObject({ echo: 0, dock: 0, durable: 1 }) - await poll(() => gate.inboxDelivery(false, text(id))).toBeDefined() - gate.releaseThrough(gate.inboxDelivery(false, text(id))!) - await poll(() => gate.turnEndDelivery()).toBeDefined() - gate.releaseThrough(gate.turnEndDelivery()!) - await settled - } - gate.releaseAll() - const actual = await page.locator('[data-chat-flow-kind="user"]').allTextContents() - expect(actual.filter(value => value.includes('RAPID_INPUT_')).map(value => - [...releases.keys()].find(id => value.includes(text(id))))).toEqual(hostOrder.split('')) - expect(await page.locator('[data-submission-echo]').count()).toBe(0) - expect(await page.locator('[data-queue-dock]').count()).toBe(0) - expect(tripwire.pageErrors).toEqual([]) - } finally { - for (const release of releases.values()) release.resolve(undefined) gate.releaseAll() } }, diff --git a/apps/web/tests/japanese-plugin-metadata.e2e.ts b/apps/web/tests/japanese-plugin-metadata.e2e.ts index fb56add4f1..9d9103cff9 100644 --- a/apps/web/tests/japanese-plugin-metadata.e2e.ts +++ b/apps/web/tests/japanese-plugin-metadata.e2e.ts @@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url' import { chromium, type Browser } from 'playwright' import { expect, it, onTestFailed, onTestFinished } from 'vitest' import { captureStableAria, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold } from './scaffold.ts' -import { saveFailureShot } from './support.ts' +import { experimentalBundleDescription, saveFailureShot } from './support.ts' it('displays Japanese plugin titles and descriptions from package metadata', async () => { const resources: { scaffold?: WebScaffold; browser?: Browser } = {} @@ -23,7 +23,7 @@ it('displays Japanese plugin titles and descriptions from package metadata', asy const title = panel.getByRole('button', { name: '自動認可レビューを表示', exact: true }) await title.waitFor() const card = title.locator('xpath=ancestor::li') - await card.getByText('各ツール呼び出しの前にモデルが認可を判断する、自動認可レビュー権限モードを提供します。', { exact: true }).waitFor() + await card.getByText(experimentalBundleDescription('auto-review', 'ja'), { exact: true }).waitFor() const expected = fileURLToPath(new URL('./expected/japanese-plugin-metadata/card.expected.md', import.meta.url)) await compareOrRefreshGolden(expected, await captureStableAria(page, '[data-plugin-panel] li:has(button[aria-label="自動認可レビューを表示"])', scaffold.workspaceCwd), webSnapshotMode()) diff --git a/apps/web/tests/layout-bottom.e2e.ts b/apps/web/tests/layout-bottom.e2e.ts index ee213925b3..61c7f4f405 100644 --- a/apps/web/tests/layout-bottom.e2e.ts +++ b/apps/web/tests/layout-bottom.e2e.ts @@ -42,7 +42,8 @@ it('reserves bottom content height without remounting it on main-panel navigatio const viewportHeight = page.viewportSize()!.height expect(result.bottom).toEqual({ top: viewportHeight - height, height, bottom: viewportHeight }) expect(result.main).toEqual({ top: caption, height: viewportHeight - caption - height, bottom: viewportHeight - height }) - expect(result.sidebar).toEqual(result.main) + expect(result.sidebar).toEqual(page.viewportSize()!.width < 768 + ? { top: 0, height: viewportHeight, bottom: viewportHeight } : result.main) expect(result.rightbar).toEqual(result.main) expect(result.overlay).toEqual({ top: 0, height: viewportHeight, bottom: viewportHeight }) for (const handle of result.handles) expect(handle).toEqual(result.main) diff --git a/apps/web/tests/markdown-file-links.e2e.ts b/apps/web/tests/markdown-file-links.e2e.ts index 62b83dfafb..6161bf048e 100644 --- a/apps/web/tests/markdown-file-links.e2e.ts +++ b/apps/web/tests/markdown-file-links.e2e.ts @@ -2,7 +2,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises' import { basename, join } from 'node:path' import { fileURLToPath } from 'node:url' -import { chromium, type Browser, type Page } from 'playwright' +import { chromium, type Browser, type Locator, type Page } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' import { ToolCallId, createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm' import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session' @@ -17,6 +17,13 @@ import { expandOwningTurnProcess, newEnglishPage, saveFailureShot } from './supp const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/markdown-file-links', import.meta.url)) const MODE = webSnapshotMode() +/** A restored preview resolves its Host path after the document's load event. */ +async function reloadPreview(page: Page, column: Locator, absolutePath: string): Promise { + await page.reload({ waitUntil: 'load' }) + await column.getByText(absolutePath, { exact: true }).waitFor() + expect(await column.locator('[data-textpreview-path]').textContent()).toBe(absolutePath) +} + /** Build live test input with a parent-path link and a read result naming the same Host file. */ function parentPathFixture(path: string): string { const session = Session.create(SessionId('parent-file-links-source')) @@ -156,6 +163,54 @@ describe('web e2e: Markdown file links', () => { await assertFixtureInventory(SNAPSHOT_DIR, ['session.v3.jsonl', 'links.expected.md', 'preview.expected.md']) }) + it('replays colon line suffixes as locations and shares tabs with fragment links', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-colon-file-links')) + const fixture = new URL('./fixtures/markdown-colon-file-links/session.v3.jsonl', import.meta.url) + const id = await seedSession(scaffold, await readFile(fixture, 'utf8'), 'colon-file-links') + await page.reload({ waitUntil: 'load' }) + const workspace = page.getByRole('treeitem').first() + await workspace.waitFor() + if (await workspace.getAttribute('aria-expanded') !== 'true') await workspace.click() + await page.locator(`[data-row-key="session:${id}"]`).click() + + const relative = page.getByRole('button', { name: 'Relative colon:24–30', exact: true }) + await relative.waitFor() + expect(await page.getByRole('button', { name: 'Development server', exact: true }).count()).toBe(0) + expect(await page.getByRole('link', { name: 'Development server', exact: true }).getAttribute('href')).toBe('localhost:3000') + expect(await page.getByRole('link', { name: 'Bare URL', exact: true }).getAttribute('href')).toBe('index.ts:24') + expect(await page.getByRole('link', { name: 'Blocked script', exact: true }).count()).toBe(0) + expect(await page.getByRole('button', { name: 'Blocked script', exact: true }).count()).toBe(0) + expect(await page.getByRole('link', { name: 'Mail', exact: true }).getAttribute('href')).toBe('mailto:10086') + await compareOrRefreshGolden( + fileURLToPath(new URL('./expected/markdown-colon-file-links.md', import.meta.url)), + await relative.locator('..').ariaSnapshot(), MODE, + ) + const column = page.locator('[data-rightbar-col]') + for (const label of ['Zero line', 'Reversed range']) { + await page.getByRole('button', { name: label, exact: true }).click() + await expect.poll(() => column.locator('[data-textpreview-path]').textContent()) + .toBe(join(scaffold.workspaceCwd, 'src/example.txt')) + await expect.poll(() => column.locator('[data-textpreview-line="1"]').textContent()).toBe('source line 1\n') + expect(await column.locator('[data-dockkit-tab-title]').allTextContents()).toEqual(['example.txt']) + } + for (const [label, line] of [['Relative colon:24–30', 24], ['Absolute colon:30', 30], ['Column:24:5', 24], ['Fragment:12', 12]] as const) { + const link = page.getByRole('button', { name: label, exact: true }) + await link.focus() + await link.press('Enter') + await expect.poll(() => column.locator(`[data-textpreview-target="${line}"]`).textContent()) + .toBe(`source line ${line}\n`) + await expect.poll(() => column.locator('[data-textpreview-path]').textContent()) + .toBe(join(scaffold.workspaceCwd, 'src/example.txt')) + expect(await column.locator('[data-dockkit-tab-title]').allTextContents()).toEqual(['example.txt']) + } + await reloadPreview(page, column, join(scaffold.workspaceCwd, 'src/example.txt')) + await relative.click() + await expect.poll(() => column.locator('[data-textpreview-target="24"]').textContent()).toBe('source line 24\n') + expect(await column.locator('[data-dockkit-tab-title]').allTextContents()).toEqual(['example.txt']) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }) + it('opens parent-path prose and read-card links while retaining each address across reload', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-parent-file-links')) // Return through the parent into this owned temp root; no shared parent file is created. @@ -186,8 +241,7 @@ describe('web e2e: Markdown file links', () => { await expect.poll(() => column.locator('[data-textpreview-target="30"]').textContent()).toBe('parent line 30\n') expect(await tabs.allTextContents()).toEqual(['parent.txt']) - await page.reload({ waitUntil: 'load' }) - await expect.poll(() => column.locator('[data-textpreview-path]').textContent()).toBe(join(scaffold.workspaceCwd, 'parent.txt')) + await reloadPreview(page, column, join(scaffold.workspaceCwd, 'parent.txt')) await expect.poll(stored).toContain(address) await source.click() await expect.poll(() => column.locator('[data-textpreview-target="24"]').textContent()).toBe('parent line 24\n') diff --git a/apps/web/tests/markdown-image-refresh.e2e.ts b/apps/web/tests/markdown-image-refresh.e2e.ts index bade81cd1e..2a9dc421a3 100644 --- a/apps/web/tests/markdown-image-refresh.e2e.ts +++ b/apps/web/tests/markdown-image-refresh.e2e.ts @@ -1,9 +1,10 @@ // A rewritten local image file shows its current bytes in a newly rendered Markdown image. -import { writeFile } from 'node:fs/promises' +import { readFile, writeFile } from 'node:fs/promises' import { join } from 'node:path' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { createLaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment' import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm' import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-session-title' @@ -50,7 +51,11 @@ describe('web e2e: rewritten Markdown image files', () => { let tripwire: ReturnType beforeAll(async () => { - scaffold = await launchWebScaffold({}) + scaffold = await launchWebScaffold({ + openInAppEnvironment: createLaunchEnvironmentSnapshot([ + { source: 'process', values: { SSH_CONNECTION: '10.0.0.2 55000 10.0.0.9 22' } }, + ]), + }) await writeFile(join(scaffold.workspaceCwd, 'chart.svg'), chart(120, 'red')) await seedSession(scaffold, chartFixture('First chart'), 'markdown-image-refresh-first', undefined, { createdAt: WEB_FIXTURE_TIME - 120_000 }) @@ -81,6 +86,14 @@ describe('web e2e: rewritten Markdown image files', () => { await page.getByRole('treeitem').nth(1).click() await page.getByText('Second chart', { exact: true }).last().waitFor() await expect.poll(width, { timeout: 10_000 }).toBe(240) + await page.getByRole('img', { name: ALT }).click({ button: 'right' }) + const action = page.getByRole('menuitem', { name: 'Download', exact: true }) + await action.waitFor() + const [download] = await Promise.all([page.waitForEvent('download'), action.click()]) + expect(download.suggestedFilename()).toBe('chart.svg') + const path = await download.path() + if (path === null) throw new Error('Browser download unavailable') + expect(await readFile(path, 'utf8')).toBe(chart(240, 'blue')) expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) }, 60_000) diff --git a/apps/web/tests/markdown-wide-table.e2e.ts b/apps/web/tests/markdown-wide-table.e2e.ts index bdd7c5da6f..eba073c473 100644 --- a/apps/web/tests/markdown-wide-table.e2e.ts +++ b/apps/web/tests/markdown-wide-table.e2e.ts @@ -216,8 +216,8 @@ async function awaitTableLayout(target: Page): Promise { if (element === null) return false const tracks = getComputedStyle(element).gridTemplateColumns.split(' ').map(Number.parseFloat) const root = element.querySelector('div[data-phase]') - // Mirrored from ui-layout's SIDEBAR_COLLAPSED; these tests use the Host compiler face. - return tracks[0] === 56 && tracks.at(-1) === 0 + // Desktop retains the rail; the mobile drawer leaves the whole width to the transcript. + return tracks[0] === (element.hasAttribute('data-sidebar-drawer') ? 0 : 56) && tracks.at(-1) === 0 && element.getAnimations().every(animation => animation.playState === 'finished' || animation.playState === 'idle') && root !== null diff --git a/apps/web/tests/menu-material.e2e.ts b/apps/web/tests/menu-material.e2e.ts index 9f96ba008a..4f65a889a8 100644 --- a/apps/web/tests/menu-material.e2e.ts +++ b/apps/web/tests/menu-material.e2e.ts @@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { join } from 'node:path' import { chromium, type Locator } from 'playwright' +import sharp from 'sharp' import { expect, it, onTestFinished } from 'vitest' import { captureStableAria, compareOrRefreshGolden, launchWebScaffold, seedSession, webSnapshotMode } from './scaffold.ts' @@ -48,13 +49,13 @@ it('shares menu transparency and blur across palettes and follows native menu bo }) expect(overlayFill).toBe(platform === 'darwin' ? dark ? 'rgba(48, 49, 54, 0.94)' : 'rgba(248, 249, 250, 0.94)' - : dark ? 'rgba(67, 69, 74, 0.45)' : 'rgba(248, 249, 250, 0.58)') + : dark ? 'rgba(48, 49, 54, 0.64)' : 'rgba(252, 253, 254, 0.7)') await account.click() const menu = page.getByRole('menu').filter({ has: page.getByRole('menuitem', { name: 'Settings', exact: true }) }) await menu.waitFor() const appearance = await material(menu) expect(appearance).toMatchObject({ - fill: dark ? 'rgba(67, 69, 74, 0.45)' : 'rgba(248, 249, 250, 0.58)', + fill: dark ? 'rgba(48, 49, 54, 0.64)' : 'rgba(252, 253, 254, 0.7)', blur: 'blur(40px) saturate(1.5)', }) expect(appearance.shadow).toContain(`${dark ? 'rgba(255, 255, 255, 0.16)' : 'rgba(0, 0, 0, 0.04)'} 0px 0px 0px 0.5px`) @@ -109,4 +110,57 @@ it('shares menu transparency and blur across palettes and follows native menu bo await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd), webSnapshotMode()) await page.keyboard.press('Escape') await expect.poll(() => page.locator('[data-menu-backing]').count()).toBe(0) + + await action.locator('xpath=ancestor::*[@role="treeitem"][1]').click({ button: 'right' }) + await sessionMenu.waitFor() + const popup = page.locator('[data-context-menu]') + const stripes = await page.evaluateHandle(() => { + const element = document.createElement('div') + element.style.cssText = 'position:fixed;inset:0;z-index:1099;pointer-events:none;background:repeating-linear-gradient(90deg,#000 0 4px,#fff 4px 8px)' + document.body.appendChild(element) + return element + }) + try { + // Hide text while preserving layout so pixel contrast measures only the material. + await popup.evaluate((node) => { + for (const child of node.children) { + if (child instanceof HTMLElement && child.getAttribute('aria-hidden') !== 'true') child.style.visibility = 'hidden' + } + }) + const box = (await popup.boundingBox())! + const clip = { x: Math.floor(box.x + box.width / 2 - 32), y: Math.floor(box.y + box.height / 2 - 16), width: 64, height: 32 } + for (const phase of ['enter', 'dismiss', 'replace']) { + await popup.evaluate((node, phase) => { + node.removeAttribute('data-menu-phase') + void (node as HTMLElement).offsetWidth + node.setAttribute('data-menu-phase', phase) + for (const animation of node.getAnimations({ subtree: true })) { + animation.pause() + animation.currentTime = Number(animation.effect!.getComputedTiming().duration) / 2 + } + }, phase) + const stats = await sharp(await page.screenshot({ clip })).stats() + // During a fade the unpainted fraction exposes stripes; a working blur still + // removes substantially more contrast than opacity without backdrop sampling. + expect(stats.channels[0]!.stdev, phase).toBeLessThan(90) + } + await popup.evaluate((node) => { + node.setAttribute('data-menu-phase', 'enter') + for (const animation of node.getAnimations({ subtree: true })) animation.finish() + }) + const settled = await sharp(await page.screenshot({ clip })).stats() + expect(settled.channels[0]!.stdev).toBeLessThan(3) + await popup.evaluate((node) => { + node.style.opacity = '0.999' + // The negative control measures backdrop isolation independently of the theme's fill alpha. + const material = node.querySelector(':scope > [aria-hidden="true"]')! + material.style.backgroundColor = 'transparent' + }) + const isolated = await sharp(await page.screenshot({ clip })).stats() + expect(isolated.channels[0]!.stdev).toBeGreaterThan(90) + } finally { + await stripes.evaluate((node) => { node.remove() }) + await stripes.dispose() + await page.keyboard.press('Escape') + } }) diff --git a/apps/web/tests/minimal-preset.snapshot.ts b/apps/web/tests/minimal-preset.snapshot.ts index bec53293a7..ee65497459 100644 --- a/apps/web/tests/minimal-preset.snapshot.ts +++ b/apps/web/tests/minimal-preset.snapshot.ts @@ -1,11 +1,12 @@ import { executeToolFixture } from '@deepseek-ai/dsh-tool-testkit' -import { mkdir, readFile, writeFile } from 'node:fs/promises' +import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises' import { join } from 'node:path' import { fileURLToPath } from 'node:url' -import type { Browser, Page } from 'playwright' +import type { Browser, Locator, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' import type { AgentHandle } from '@deepseek-ai/dsh-agent' +import type { SessionAttachmentValue } from '@deepseek-ai/dsh-api-session-controller' import { ToolCallId, createUserMessage } from '@deepseek-ai/dsh-llm' import type { GenerateOptions } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' @@ -18,11 +19,15 @@ import { compareOrRefreshGolden, fixtureUserPrompts, launchWebScaffold, + parseSeedFixture, + rawSessionLog, + renderSeedFixture, + seedSession, watchConsole, webSnapshotMode, type WebScaffold, } from './scaffold.ts' -import { newEnglishPage, saveFailureShot } from './support.ts' +import { expandOwningTurnProcess, newEnglishPage, saveFailureShot } from './support.ts' const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/minimal-preset', import.meta.url)) const FIXTURE = join(SNAPSHOT_DIR, 'session.v3.jsonl') @@ -322,6 +327,38 @@ describe('minimal image reading', () => { let browser: Browser | undefined let page: Page | undefined + async function openSession(id: SessionId): Promise { + if (browser === undefined) throw new Error('image scenario browser has not started') + await page?.close() + page = await newEnglishPage(browser) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.locator('[role="treeitem"]').first().click() + await page.locator(`[data-row-key="session:${id}"]`).click() + return page + } + + async function imageCard(current: Page): Promise { + const card = current.locator('[data-tool="read_image"]').first() + await card.waitFor({ state: 'attached' }) + await expandOwningTurnProcess(current, card) + const row = card.locator('[data-disclosure-row]') + if (await row.getAttribute('aria-expanded') === 'false') await row.click() + return card + } + + function interruptedTurn(turn: number, text: string): string { + return [ + { type: 'turn/start', data: { turn } }, + { type: 'step/start', data: { turn, step: 1 } }, + { + type: 'user/message', surfaceOp: 'append', + data: createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }), + }, + { type: 'step/end', data: { turn, step: 1 } }, + { type: 'turn/end', data: { turn, reason: { kind: 'interrupted' } } }, + ].map(event => JSON.stringify(event)).join('\n') + } + beforeAll(async () => { scaffold = await launchWebScaffold({ replayFixture: join(snapshotDir, 'session.v4.jsonl'), compareReplaySession: true, paceMs: 10, @@ -337,6 +374,7 @@ describe('minimal image reading', () => { }) handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: prompt }], source: { kind: 'user' } })) await handle.agent.whenIdle() + if (MODE !== 'record') browser = await chromium.launch() }) afterAll(async () => { @@ -363,21 +401,10 @@ describe('minimal image reading', () => { it.skipIf(MODE === 'record')('renders the existing image tool card and preview', async () => { onTestFailed(() => { if (page !== undefined) void saveFailureShot(page, 'web-minimal-read-image') }) - browser = await chromium.launch() - page = await newEnglishPage(browser) + page = await openSession(handle.agent.session.id) const tripwire = watchConsole(page) - await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) - await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) - await page.locator('[role="treeitem"]').first().click() - await page.locator('[role="treeitem"]').nth(1).click() await page.getByText('MINIMAL_IMAGE_OK', { exact: true }).waitFor() - await page.locator('[data-turn-process]').click() - const group = page.locator('[data-chat-group-key]').first() - await group.locator('[data-process-activity]').click() - const card = group.locator('[data-tool="read_image"]').first() - const row = card.locator('[data-disclosure-row]') - await row.click() - await expect.poll(() => row.getAttribute('aria-expanded')).toBe('true') + const card = await imageCard(page) const preview = card.locator('img').first() await preview.waitFor() await expect.poll(() => preview.evaluate(img => img instanceof HTMLImageElement && img.naturalWidth)).toBe(1) @@ -387,9 +414,143 @@ describe('minimal image reading', () => { expect(tripwire.warnings).toEqual([]) }) + it.skipIf(MODE === 'record')('reads image bytes and preserves the supplied reference with another Session as the gateway scope', async () => { + const image = handle.agent.session.deriveMessages().flatMap(message => message.content).find(block => block.type === 'image') + if (image?.type !== 'image') throw new Error('minimal read_image produced no durable image') + const unrelated = await scaffold.ctx.agents.create({ sessionId: SessionId('minimal-image-unrelated') }) + try { + expect(unrelated.agent.session.deriveMessages().flatMap(message => message.content).some(block => block.type === 'image')).toBe(false) + const read = async (attachment: unknown, rpcId: string) => { + const response = await scaffold.hostFetch('/api/session/attachment', { + method: 'POST', headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + type: 'client-request', rpcId, method: 'session/attachment', + payload: { args: { request: { sessionId: unrelated.agent.session.id, attachment } } }, + }), + }) + expect(response.ok).toBe(true) + return await response.json() as { result: { ok: boolean; value?: SessionAttachmentValue; error?: { code: string } } } + } + const reference = { ...image.attachment, name: 'caller-preview.png' } + const body = await read(reference, 'minimal-image-unrelated') + const stored = await scaffold.ctx.attachments.readImage(image.attachment) + expect(body.result).toEqual({ + ok: true, + value: { attachment: reference, data: Buffer.from(stored.data).toString('base64') }, + }) + const mismatches = [ + { mediaType: 'image/jpeg' }, { bytes: reference.bytes + 1 }, + { width: reference.width + 1 }, { height: reference.height + 1 }, + ] + for (const [index, mismatch] of mismatches.entries()) { + const rejected = await read({ ...reference, ...mismatch }, `minimal-image-mismatch-${index}`) + expect(rejected.result).toMatchObject({ + ok: false, error: { code: 'session/attachment-invalid', details: { reason: 'ATTACHMENT_CORRUPT' } }, + }) + expect(rejected.result.value).toBeUndefined() + } + const invalidFields = [ + { mediaType: 'image/svg+xml' }, { bytes: String(reference.bytes) }, + { width: String(reference.width) }, { height: String(reference.height) }, + ] + for (const [index, invalid] of invalidFields.entries()) { + const rejected = await read({ ...reference, ...invalid }, `minimal-image-schema-${index}`) + expect(rejected.result).toMatchObject({ ok: false, error: { code: 'gateway/input-invalid' } }) + expect(rejected.result.value).toBeUndefined() + } + } finally { + await unrelated.dispose() + } + }) + + it.skipIf(MODE === 'record')('loads persisted images after opening, paging older history, and forking', async () => { + onTestFailed(() => { if (page !== undefined) void saveFailureShot(page, 'web-historical-read-image') }) + const { headerLine, events } = parseSeedFixture(rawSessionLog(handle.agent.session)) + const recorded = renderSeedFixture(headerLine, events) + // User-only interrupted turns move the recorded image beyond the 50-message initial page without inventing model output. + const laterTurns = Array.from({ length: 52 }, (_, index) => + interruptedTurn(index + 2, `Later image-history message ${index + 2}`)) + const historicalId = SessionId('minimal-image-cold') + await seedSession(scaffold, `${recorded}${laterTurns[0]}\n`, historicalId, 'minimal') + expect(scaffold.ctx.agents.get(historicalId)).toBeUndefined() + page = await openSession(historicalId) + let card = await imageCard(page) + await expect.poll(() => card.locator('img').first().evaluate(img => img instanceof HTMLImageElement && img.naturalWidth)).toBe(1) + + const pagedId = await seedSession(scaffold, `${recorded}${laterTurns.join('\n')}\n`, 'minimal-image-paged', 'minimal') + expect(scaffold.ctx.agents.get(pagedId)).toBeUndefined() + page = await openSession(pagedId) + await page.getByText('Later image-history message 53', { exact: true }).waitFor() + expect(await page.locator('[data-tool="read_image"]').count()).toBe(0) + await page.getByRole('button', { name: 'Load earlier', exact: true }).click() + card = await imageCard(page) + await expect.poll(() => card.locator('img').first().evaluate(img => img instanceof HTMLImageElement && img.naturalWidth)).toBe(1) + + const response = await scaffold.hostFetch('/api/session/fork', { + method: 'POST', headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + type: 'client-request', rpcId: 'minimal-image-fork', method: 'session/fork', + payload: { args: { request: { sessionId: historicalId } } }, + }), + }) + expect(response.ok).toBe(true) + const body = await response.json() as { result: { ok: boolean; value?: { sessionId: string } } } + expect(body.result.ok).toBe(true) + if (body.result.value === undefined) throw new Error('image fork did not return a Session ID') + page = await openSession(SessionId(body.result.value.sessionId)) + card = await imageCard(page) + await expect.poll(() => card.locator('img').first().evaluate(img => img instanceof HTMLImageElement && img.naturalWidth)).toBe(1) + }) + + it.skipIf(MODE === 'record')('ends loading with a retryable failure when the persisted image is missing', async () => { + onTestFailed(() => { if (page !== undefined) void saveFailureShot(page, 'web-missing-read-image') }) + const image = handle.agent.session.deriveMessages().flatMap(message => message.content).find(block => block.type === 'image') + if (image?.type !== 'image') throw new Error('minimal read_image produced no durable image') + // The blue pixel owns a different storage object from the recorded red pixel. + const missingImage = await scaffold.ctx.attachments.saveImage({ + data: Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC', 'base64'), + mediaType: 'image/png', name: 'red.png', + }) + expect(missingImage.attachmentId).not.toBe(image.attachment.attachmentId) + const { headerLine, events } = parseSeedFixture(rawSessionLog(handle.agent.session)) + const missingEvents = events.map(event => event.type === 'tool/result' + ? { + ...event, + data: { + ...event.data, + message: { + ...event.data.message, + content: event.data.message.content.map(block => block.type === 'image' + ? { ...block, attachment: missingImage } + : block), + }, + }, + } + : event) + const missingId = await seedSession(scaffold, + `${renderSeedFixture(headerLine, missingEvents)}${interruptedTurn(2, 'Check the missing image')}\n`, + 'minimal-image-missing', 'minimal') + const stored = await scaffold.ctx.attachments.readImage(missingImage) + const path = scaffold.ctx.attachments.imageHostPath(missingImage) + if (path === undefined) throw new Error('local attachment store did not return the stored image path') + await unlink(path) + try { + page = await openSession(missingId) + const card = await imageCard(page) + await card.getByRole('button', { name: 'Image failed to load; click to retry', exact: true }).waitFor() + expect(await card.getByText('Loading image…', { exact: true }).count()).toBe(0) + expect(await card.locator('[aria-busy="true"]').count()).toBe(0) + expect(await card.locator('img').count()).toBe(0) + await compareOrRefreshGolden(join(snapshotDir, 'missing-image.expected.md'), + await captureStableAria(page, '[data-tool="read_image"]', scaffold.workspaceCwd), MODE) + } finally { + await scaffold.ctx.attachments.saveImage({ data: stored.data, mediaType: stored.ref.mediaType }) + } + }) + it('keeps its snapshot inventory closed', async () => { await assertFixtureInventory(snapshotDir, [ - 'session.v4.jsonl', 'system-prompt.expected.md', 'tool-schemas.expected.json', 'ui.expected.md', + 'session.v4.jsonl', 'system-prompt.expected.md', 'tool-schemas.expected.json', 'ui.expected.md', 'missing-image.expected.md', ]) }) }) diff --git a/apps/web/tests/model-badge.e2e.ts b/apps/web/tests/model-badge.e2e.ts new file mode 100644 index 0000000000..4fb6e6aaab --- /dev/null +++ b/apps/web/tests/model-badge.e2e.ts @@ -0,0 +1,185 @@ +/** Catalog badges reach every selector placement through the Host catalog without changing catalog identity. */ +import { fileURLToPath } from 'node:url' +import { LlmAdapter, type LlmModelBadge, type StreamChunk } from '@deepseek-ai/dsh-llm' +import { parseModelListing } from '@deepseek-ai/dsh-llm-deepseek' +import { chromium, type Browser, type Page } from 'playwright' +import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { + captureStableAria, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { connectFreshWorkspaceZh, ZH_BROWSER_LOCALE } from './support.ts' + +const NAME = 'DeepSeek-V4.1-Flash' +const LONG_NAME = 'DeepSeek model with a very long release and capability description that exceeds the selector width' +const FIXTURE = fileURLToPath(new URL('./fixtures/model-badge/session.v4.jsonl', import.meta.url)) +const EXPECTED = fileURLToPath(new URL('./expected/model-badge/models.expected.md', import.meta.url)) +const MODE = webSnapshotMode() + +/** DeepSeek fixture declarations pass through the production wire decoder before replay. */ +function listedModel(id: string, name: string, badge: unknown) { + const entry = parseModelListing({ data: [{ id, name, client_metadata: { 'deepseek-harness': { badge } } }] }).entries[0]! + return { id, name, ...(entry.badge?.kind === 'badge' ? { badge: entry.badge.badge } : {}) } +} + +describe.skipIf(MODE === 'record')('web e2e: catalog model badges', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + + beforeAll(async () => { + scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./fixtures/model-badge/account.overlay.yml', import.meta.url)), + replayFixture: FIXTURE, + replayProvidersOnly: true, + replayProviders: [ + { id: 'deepseek-account', name: 'DeepSeek Account', models: [ + listedModel('deepseek-flash', NAME, { text: ' 1017 ', tone: 'info' }), + ] }, + { id: 'deepseek-official', name: 'DeepSeek', models: [ + listedModel('deepseek-flash', NAME, { text: { en: ' New ', zh: ' 新 ' }, tone: 'success' }), + { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' }, + listedModel('long', LONG_NAME, { text: 'Preview', tone: 'future-tone' }), + listedModel('invalid-badge', 'Invalid badge model', { text: { en: 'New', zh: '\u200b' } }), + ] }, + { id: 'external', name: 'External', models: [{ id: 'deepseek-flash', name: NAME }] }, + ], + }) + browser = await chromium.launch() + page = await browser.newPage({ viewport: { width: 1440, height: 900 }, locale: ZH_BROWSER_LOCALE }) + tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await connectFreshWorkspaceZh(page, scaffold.workspaceCwd) + }) + + afterAll(async () => { + try { await browser?.close() } + finally { await scaffold?.close() } + }) + + it('shows each catalog badge in all placements while preserving the chosen provider and model id', async () => { + const trigger = page.getByRole('button', { name: /^选择模型/ }) + await trigger.getByText('新', { exact: true }).waitFor() + expect(await trigger.textContent()).toContain(`新 ${NAME}`) + expect(await trigger.getAttribute('aria-label')).toBe(`选择模型，当前 ${NAME}`) + expect(await trigger.getByText('新', { exact: true }).getAttribute('data-tone')).toBe('success') + try { + await trigger.click() + const current = page.getByRole('menuitem', { name: /^模型/ }) + expect(await current.getByText('新', { exact: true }).count()).toBe(1) + await current.click() + const menu = page.getByRole('menu', { name: '模型', exact: true }) + await compareOrRefreshGolden(EXPECTED, await captureStableAria(page, '[role="menu"][aria-label="模型"]', scaffold.workspaceCwd), MODE) + expect(await menu.getByRole('group', { name: 'External', exact: true }).locator('[data-tone]').count()).toBe(0) + expect(await menu.getByRole('menuitemradio', { name: 'Invalid badge model', exact: true }).locator('[data-tone]').count()).toBe(0) + expect(await menu.getByRole('menuitemradio', { name: `${LONG_NAME} Preview`, exact: true }).locator('[data-tone]').getAttribute('data-tone')).toBe('neutral') + const account = menu.getByRole('group', { name: 'DeepSeek 账号', exact: true }) + expect(await account.getByText('1017', { exact: true }).getAttribute('data-tone')).toBe('info') + await account.getByRole('menuitemradio', { name: `${NAME} 1017`, exact: true }).click() + await expect.poll(() => scaffold.ctx.agentDefaultModel.currentSelection()).toEqual({ provider: 'deepseek-account', model: 'deepseek-flash' }) + await expect.poll(() => trigger.textContent()).toContain(`1017 ${NAME}`) + const catalog = await scaffold.ctx.llm.listModels('deepseek-account') + expect(catalog.map(model => ({ id: model.id, name: model.name }))).toEqual([{ id: 'deepseek-flash', name: NAME }]) + } finally { + await page.keyboard.press('Escape') + await page.keyboard.press('Escape') + } + }) + + it('updates and clears badges in an already-open page and model menu', async () => { + const provider = 'live-badge' + class CatalogAdapter extends LlmAdapter { + badge: LlmModelBadge | undefined = { text: 'New', tone: 'info' } + override async listModels(route: string) { + return [{ provider: route, id: 'live', name: 'Live model', ...(this.badge === undefined ? {} : { badge: this.badge }) }] + } + override async *stream(): AsyncIterable { throw new Error('catalog-only scenario') } + } + const adapter = new CatalogAdapter() + const unregister = scaffold.ctx.llm.registerAdapter([provider], adapter) + const trigger = page.getByRole('button', { name: /^选择模型/ }) + try { + await trigger.click() + await page.getByRole('menuitem', { name: /^模型/ }).click() + await page.getByRole('menuitemradio', { name: 'Live model New', exact: true }).click() + await expect.poll(() => trigger.textContent()).toContain('New Live model') + await trigger.click() + await page.getByRole('menuitem', { name: /^模型/ }).click() + adapter.badge = { text: 'Updated', tone: 'success' } + scaffold.ctx.emit('llm/models-updated', provider) + await expect.poll(() => trigger.textContent()).toContain('Updated Live model') + const updated = page.getByRole('menuitemradio', { name: 'Live model Updated', exact: true }) + await updated.waitFor() + expect(await updated.locator('[data-tone]').getAttribute('data-tone')).toBe('success') + adapter.badge = undefined + scaffold.ctx.emit('llm/models-updated', provider) + await expect.poll(() => trigger.textContent()).toBe('Live model') + const cleared = page.getByRole('menuitemradio', { name: 'Live model', exact: true }) + await cleared.waitFor() + expect(await cleared.locator('[data-tone]').count()).toBe(0) + } finally { + await page.keyboard.press('Escape') + await page.keyboard.press('Escape') + await trigger.click() + await page.getByRole('menuitem', { name: /^模型/ }).click() + await page.getByRole('menuitemradio', { name: `${NAME} 1017`, exact: true }).click() + unregister() + } + }) + + it('ellipsizes long names while keeping badges visible in every placement and both theme palettes', async () => { + const trigger = page.getByRole('button', { name: /^选择模型/ }) + try { + await trigger.click() + await page.getByRole('menuitem', { name: /^模型/ }).click() + await page.getByRole('menuitemradio', { name: `${LONG_NAME} Preview`, exact: true }).click() + await expect.poll(() => trigger.textContent()).toBe(`Preview ${LONG_NAME}`) + const triggerBadge = trigger.getByText('Preview', { exact: true }) + const triggerBox = (await trigger.boundingBox())! + const triggerBadgeBox = (await triggerBadge.boundingBox())! + expect(triggerBadgeBox.x).toBeGreaterThanOrEqual(triggerBox.x) + expect(triggerBadgeBox.x + triggerBadgeBox.width).toBeLessThanOrEqual(triggerBox.x + triggerBox.width) + const triggerName = trigger.getByText(LONG_NAME, { exact: true }) + expect(await triggerName.evaluate(node => node.scrollWidth > node.clientWidth && getComputedStyle(node).textOverflow === 'ellipsis')).toBe(true) + + await page.setViewportSize({ width: 390, height: 844 }) + await trigger.click() + const current = page.getByRole('menuitem', { name: /^模型/ }) + const rootBadgeBox = (await current.getByText('Preview', { exact: true }).boundingBox())! + const rootBox = (await current.boundingBox())! + expect(rootBadgeBox.x).toBeGreaterThanOrEqual(rootBox.x) + expect(rootBadgeBox.x + rootBadgeBox.width).toBeLessThanOrEqual(rootBox.x + rootBox.width) + expect(await current.getByText(LONG_NAME, { exact: true }).evaluate(node => node.scrollWidth > node.clientWidth)).toBe(true) + await current.click() + const menu = page.getByRole('menu', { name: '模型', exact: true }) + const option = menu.getByRole('menuitemradio', { name: `${LONG_NAME} Preview`, exact: true }) + const badge = option.getByText('Preview', { exact: true }) + const box = await badge.boundingBox() + expect(box).not.toBeNull() + expect(box!.x).toBeGreaterThanOrEqual(12) + expect(box!.x + box!.width).toBeLessThanOrEqual(378) + expect(await option.getByText(LONG_NAME, { exact: true }).evaluate(node => node.scrollWidth > node.clientWidth)).toBe(true) + const colors = await badge.evaluate((node) => { + const body = node.ownerDocument.body + const previous = body.getAttribute('data-ds-dark-theme') + try { + return [false, true].map((dark) => { + body.toggleAttribute('data-ds-dark-theme', dark) + const style = getComputedStyle(node) + return { color: style.color, background: style.backgroundColor } + }) + } finally { + if (previous === null) body.removeAttribute('data-ds-dark-theme') + else body.setAttribute('data-ds-dark-theme', previous) + } + }) + expect(colors[0]).not.toEqual(colors[1]) + for (const color of colors) expect(color.color).not.toBe(color.background) + } finally { + await page.keyboard.press('Escape') + await page.keyboard.press('Escape') + await page.setViewportSize({ width: 1440, height: 900 }) + } + expect(tripwire.pageErrors).toEqual([]) + }) +}) diff --git a/apps/web/tests/model-input-layout.ts b/apps/web/tests/model-input-layout.ts index e911bb3812..5ce07ca4eb 100644 --- a/apps/web/tests/model-input-layout.ts +++ b/apps/web/tests/model-input-layout.ts @@ -1,31 +1,88 @@ -/** Model input types stay below both capacity fields across editor widths. */ +/** Model identity, capacity and input-type fields follow the model row's available width. */ import type { Locator, Page } from 'playwright' import { expect } from 'vitest' /** - * Verify the expanded row at the current viewport and a narrow viewport. + * Verify expanded identity fields, capacity fields and input types across viewport and row-width boundaries. * @param page - page with an explicit viewport, restored even when an assertion fails. - * @param editor - expanded model editor containing the capacity and input-type fields. - * @returns after checking both widths and restoring the caller's size. + * @param editor - expanded model editor containing the first model's identity, capacity and input-type fields. + * @returns after checking all widths and restoring the caller's size. */ export async function assertModelInputLayout(page: Page, editor: Locator): Promise { const original = page.viewportSize() if (original === null) throw new Error('Model input layout checks require an explicit viewport') + const drawerCount = await page.locator('[data-sidebar-drawer]').count() + const entry = editor.locator('[data-row-key]').first() + const originalStyle = await entry.getAttribute('style') + const check = async (): Promise => { + const id = await editor.getByLabel('模型 ID 1', { exact: true }).boundingBox() + const name = await editor.getByRole('textbox', { name: '显示名称 1', exact: true }).boundingBox() + const context = await editor.getByLabel('上下文窗口 1', { exact: true }).boundingBox() + const output = await editor.getByLabel('最大输出 token 数 1', { exact: true }).boundingBox() + const types = await editor.getByRole('group', { name: '输入类型 1' }).boundingBox() + if (id === null || name === null || context === null || output === null || types === null) { + throw new Error('Expanded model fields are not visible') + } + const geometry = await entry.evaluate((element) => { + const style = getComputedStyle(element) + const row = element.firstElementChild! + return { + contentWidth: element.getBoundingClientRect().width - Number.parseFloat(style.paddingLeft) + - Number.parseFloat(style.paddingRight) - Number.parseFloat(style.borderLeftWidth) - Number.parseFloat(style.borderRightWidth), + rowWidth: row.getBoundingClientRect().width, + gap: Number.parseFloat(getComputedStyle(row).columnGap), + buttons: [...row.querySelectorAll(':scope > button')].map(button => button.getBoundingClientRect().width), + } + }) + expect(Math.abs(context.y - output.y)).toBeLessThan(1) + expect(types.y).toBeGreaterThanOrEqual(Math.max(context.y + context.height, output.y + output.height)) + expect(types.width).toBeGreaterThan(context.width) + if (geometry.contentWidth <= 440) { + expect(name.y).toBeGreaterThanOrEqual(id.y + id.height) + expect(name.width).toBeGreaterThan(id.width) + expect(context.y).toBeGreaterThanOrEqual(name.y + name.height) + expect(geometry.buttons).toHaveLength(3) + const available = geometry.rowWidth - geometry.buttons.reduce((sum, width) => sum + width, 0) - 3 * geometry.gap + expect(Math.abs(id.width - available)).toBeLessThan(1) + } else { + expect(Math.abs(id.y - name.y)).toBeLessThan(1) + expect(name.x).toBeGreaterThanOrEqual(id.x + id.width) + } + const overflowing = await editor.getByRole('region', { name: '模型目录', exact: true }).evaluate((region) => { + const widths = [] + for (let element: Element | null = region; element !== null; element = element.parentElement) { + if (element === region || /auto|scroll/.test(getComputedStyle(element).overflowY)) { + widths.push({ width: element.clientWidth, scroll: element.scrollWidth }) + } + if (element.getAttribute('role') === 'dialog') break + } + return widths.filter(({ width, scroll }) => scroll > width) + }) + expect(overflowing).toEqual([]) + } try { - for (const viewport of [original, { width: 760, height: 1000 }]) { + for (const viewport of [original, { width: 760, height: 1000 }, { width: 390, height: 844 }]) { await page.setViewportSize(viewport) - const context = await editor.getByLabel('上下文窗口 1', { exact: true }).boundingBox() - const output = await editor.getByLabel('最大输出 token 数 1', { exact: true }).boundingBox() - const types = await editor.getByRole('group', { name: '输入类型 1' }).boundingBox() - expect(context).not.toBeNull() - expect(output).not.toBeNull() - expect(types).not.toBeNull() - if (context === null || output === null || types === null) throw new Error('Expanded model fields are not visible') - expect(Math.abs(context.y - output.y)).toBeLessThan(1) - expect(types.y).toBeGreaterThanOrEqual(Math.max(context.y + context.height, output.y + output.height)) - expect(types.width).toBeGreaterThan(context.width) + await check() + } + await page.setViewportSize({ width: 1680, height: 1000 }) + for (const width of [440, 441]) { + await entry.evaluate((element, width) => { + element.style.boxSizing = 'content-box' + element.style.width = `${String(width)}px` + }, width) + await check() } } finally { - await page.setViewportSize(original) + try { + await entry.evaluate((element, originalStyle) => { + if (originalStyle === null) element.removeAttribute('style') + else element.setAttribute('style', originalStyle) + }, originalStyle) + } finally { + await page.setViewportSize(original) + // The shell's ResizeObserver must restore its original drawer posture before the next capture. + await expect.poll(async () => page.locator('[data-sidebar-drawer]').count(), { timeout: 5_000 }).toBe(drawerCount) + } } } diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts index ac0de149af..d36008959d 100644 --- a/apps/web/tests/models-settings.e2e.ts +++ b/apps/web/tests/models-settings.e2e.ts @@ -26,7 +26,7 @@ import { assertFixtureInventory, captureStableAria, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, } from './scaffold.ts' -import { openSettings, ZH_BROWSER_LOCALE, saveFailureShot } from './support.ts' +import { expectTooltipOnTop, openSettings, ZH_BROWSER_LOCALE, saveFailureShot } from './support.ts' const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/models-settings', import.meta.url)) const EMPTY_EXPECTED = join(SNAPSHOT_DIR, 'empty.expected.md') @@ -576,6 +576,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => { return { x: rect.left + 20, y: rect.bottom + 4 } }) await page.mouse.move(insertion.x, insertion.y, { steps: 3 }) + expect(await dialog.locator('[data-drop-target]').evaluate(element => getComputedStyle(element).zIndex)).toBe('1') await page.mouse.up() await page.locator('body > div[inert][aria-hidden="true"]:has(button[aria-label^="调整模型顺序 "])').waitFor({ state: 'detached' }) await expect.poll(() => dialog.getByLabel(`模型 ID ${save ? '3' : '2'}`, { exact: true }).inputValue()).toBe('acme-large') @@ -603,7 +604,21 @@ describe('web e2e: Models settings page configures a dormant provider', () => { const viewport = page.viewportSize() if (viewport === null) throw new Error('Model ordering checks require an explicit viewport') try { + const id = dialog.getByRole('textbox', { name: '模型 ID 1', exact: true }) + const name = dialog.getByRole('textbox', { name: '显示名称 1', exact: true }) + const toggle = dialog.getByRole('button', { name: '模型选项 1', exact: true }) + const desktopId = await id.boundingBox() + const desktopName = await name.boundingBox() + if (desktopId === null || desktopName === null) throw new Error('Wide model identity fields are not visible') + expect(Math.abs(desktopId.y - desktopName.y)).toBeLessThan(1) + await name.focus() await page.setViewportSize({ width: 390, height: 844 }) + expect(await name.evaluate(input => input.ownerDocument.activeElement === input)).toBe(true) + expect(await name.isVisible()).toBe(true) + await toggle.click() + await name.waitFor({ state: 'hidden' }) + await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'mobile-collapsed.expected.md'), + await captureStableAria(page, '[data-shortcut-modal="settings"]', scaffold.workspaceCwd), MODE) for (const name of ['调整模型顺序 1', '模型选项 1', '删除模型 1']) { const box = await dialog.getByRole('button', { name, exact: true }).boundingBox() expect(box).not.toBeNull() @@ -611,6 +626,24 @@ describe('web e2e: Models settings page configures a dormant provider', () => { expect(box.x).toBeGreaterThanOrEqual(0) expect(box.x + box.width).toBeLessThanOrEqual(390) } + const compactId = await id.boundingBox() + if (compactId === null) throw new Error('Narrow model ID is not visible') + await toggle.click() + await name.waitFor({ state: 'visible' }) + await name.fill('手机上的完整显示名称') + await toggle.click() + await name.waitFor({ state: 'hidden' }) + expect(await id.inputValue()).toBe('order-second') + await toggle.click() + expect(await name.inputValue()).toBe('手机上的完整显示名称') + const expandedName = await name.boundingBox() + if (expandedName === null) throw new Error('Expanded model name is not visible') + expect(expandedName.y).toBeGreaterThanOrEqual(compactId.y + compactId.height) + expect(expandedName.width).toBeGreaterThan(compactId.width) + expect(await dialog.getByRole('region', { name: '模型目录', exact: true }) + .evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'mobile-expanded.expected.md'), + await captureStableAria(page, '[data-shortcut-modal="settings"]', scaffold.workspaceCwd), MODE) } finally { await page.setViewportSize(viewport) } @@ -618,6 +651,118 @@ describe('web e2e: Models settings page configures a dormant provider', () => { expect(tripwire.pageErrors).toEqual([]) }) + it.each([{ name: 'Chromium', engine: chromium }, { name: 'WebKit', engine: webkit }])( + 'keeps mobile model actions, focus and keyboard order in $name', async ({ name: engineName, engine }) => { + const provider = `review-${engineName.toLowerCase()}` + let mobileBrowser: Browser | undefined + try { + await scaffold.ctx.settings.mutate('llm-pi-ai', [{ + op: 'set', path: ['providers', provider], value: { + api: 'anthropic-messages', baseURL: 'https://layout.example', + models: [{ id: 'layout-model', name: '完整显示名称' }, { id: 'next-model', name: '下一模型' }], + }, + }]) + mobileBrowser = await engine.launch() + const mobilePage = await mobileBrowser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE }) + const errors = watchConsole(mobilePage) + onTestFailed(() => saveFailureShot(mobilePage, `web-e2e-models-mobile-${engineName.toLowerCase()}`)) + await mobilePage.goto(scaffold.authenticatedUrl) + await openSettings(mobilePage, 'zh') + const dialog = mobilePage.getByRole('dialog', { name: '设置' }) + await dialog.getByRole('button', { name: '模型', exact: true }).click() + const edit = dialog.getByRole('button', { name: `编辑 ${provider}`, exact: true }) + await edit.click() + await dialog.getByText('自定义设置').click() + const id = dialog.getByRole('textbox', { name: '模型 ID 1', exact: true }) + const name = dialog.getByRole('textbox', { name: '显示名称 1', exact: true }) + const toggle = dialog.getByRole('button', { name: '模型选项 1', exact: true }) + const nextToggle = dialog.getByRole('button', { name: '模型选项 2', exact: true }) + await toggle.click() + await assertModelInputLayout(mobilePage, dialog) + await dialog.getByRole('button', { name: '调整模型顺序 1', exact: true }).hover() + const tooltip = mobilePage.getByRole('tooltip') + await tooltip.waitFor() + expect(await tooltip.evaluate(element => element.parentElement === element.ownerDocument.body)).toBe(true) + await expectTooltipOnTop(tooltip) + await id.hover() + await tooltip.waitFor({ state: 'hidden' }) + await toggle.click() + await name.fill('缩窄后继续编辑') + const input = await name.elementHandle() + if (input === null) throw new Error('Model name input is missing') + await mobilePage.setViewportSize({ width: 390, height: 844 }) + expect(await input.evaluate(element => element.isConnected && element.ownerDocument.activeElement === element)).toBe(true) + await nextToggle.click() + expect(await nextToggle.getAttribute('aria-expanded')).toBe('true') + expect(await toggle.getAttribute('aria-expanded')).toBe('true') + await nextToggle.click() + await name.fill('手机保存后的名称') + await dialog.getByRole('button', { name: '保存', exact: true }).click() + await id.waitFor({ state: 'detached' }) + expect(scaffold.ctx.settings.describe().find(row => row.ns === 'llm-pi-ai')?.value).toMatchObject({ + providers: { [provider]: { models: [{ id: 'layout-model', name: '手机保存后的名称' }, { id: 'next-model', name: '下一模型' }] } }, + }) + await dialog.getByText(`已保存 ${provider}。`, { exact: true }).waitFor() + await edit.click() + await dialog.getByText('自定义设置').click() + await name.waitFor({ state: 'hidden' }) + await toggle.focus() + await mobilePage.keyboard.press('Enter') + const tab = engine === webkit ? 'Alt+Tab' : 'Tab' + await mobilePage.keyboard.press(tab) + expect(await dialog.getByRole('button', { name: '删除模型 1', exact: true }) + .evaluate(button => button.ownerDocument.activeElement === button)).toBe(true) + await mobilePage.keyboard.press(tab) + expect(await name.evaluate(element => element.ownerDocument.activeElement === element)).toBe(true) + await name.fill('直接点击收起后保留') + await toggle.click() + await name.waitFor({ state: 'hidden' }) + expect(await toggle.getAttribute('aria-expanded')).toBe('false') + expect(await toggle.evaluate(button => button.ownerDocument.activeElement === button)).toBe(true) + await toggle.click() + expect(await name.inputValue()).toBe('直接点击收起后保留') + const region = dialog.getByRole('region', { name: '模型目录', exact: true }) + expect(await region.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) + await dialog.getByRole('button', { name: '取消', exact: true }).click() + expect(errors.pageErrors).toEqual([]) + + const touchPage = await mobileBrowser.newPage({ + viewport: { width: 390, height: 844 }, locale: ZH_BROWSER_LOCALE, isMobile: true, hasTouch: true, + }) + const touchErrors = watchConsole(touchPage) + await touchPage.goto(scaffold.authenticatedUrl) + await openSettings(touchPage, 'zh') + const touchDialog = touchPage.getByRole('dialog', { name: '设置' }) + await touchDialog.getByRole('button', { name: '模型', exact: true }).tap() + await touchDialog.getByRole('button', { name: `编辑 ${provider}`, exact: true }).tap() + await touchDialog.getByText('自定义设置').tap() + const touchToggle = touchDialog.getByRole('button', { name: '模型选项 1', exact: true }) + const touchName = touchDialog.getByRole('textbox', { name: '显示名称 1', exact: true }) + await touchToggle.tap() + expect(await touchName.evaluate(element => element.ownerDocument.activeElement === element)).toBe(false) + await touchName.fill('触屏编辑后的名称') + await touchToggle.tap() + await touchName.waitFor({ state: 'hidden' }) + expect(await touchToggle.getAttribute('aria-expanded')).toBe('false') + await touchToggle.tap() + expect(await touchName.inputValue()).toBe('触屏编辑后的名称') + await touchName.fill('触屏保存后的名称') + const touchNext = touchDialog.getByRole('button', { name: '模型选项 2', exact: true }) + await touchNext.tap() + expect(await touchNext.getAttribute('aria-expanded')).toBe('true') + await touchDialog.getByRole('button', { name: '保存', exact: true }).tap() + await touchName.waitFor({ state: 'detached' }) + expect(scaffold.ctx.settings.describe().find(row => row.ns === 'llm-pi-ai')?.value).toMatchObject({ + providers: { [provider]: { models: [{ id: 'layout-model', name: '触屏保存后的名称' }, { id: 'next-model', name: '下一模型' }] } }, + }) + expect(touchErrors.pageErrors).toEqual([]) + } finally { + await mobileBrowser?.close() + await scaffold.ctx.settings.mutate('llm-pi-ai', [{ op: 'unset', path: ['providers', provider] }]) + } + }, 60_000, + ) + it.each([{ name: 'Chromium', engine: chromium }, { name: 'WebKit', engine: webkit }])( 'keeps keyboard reorder focus and visibility in $name', async ({ engine }) => { const keyboardBrowser = await engine.launch() @@ -704,6 +849,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => { 'configured.expected.md', 'declared-edit.expected.md', 'declared.expected.md', 'delete.expected.md', 'empty.expected.md', 'model-picker.expected.md', 'native-delete.expected.md', 'native-keyless.expected.md', 'catalog-inputs.expected.md', + 'mobile-collapsed.expected.md', 'mobile-expanded.expected.md', 'refreshing.expected.md', 'image-only.expected.md', ]) }) diff --git a/apps/web/tests/navigation-panes.e2e.ts b/apps/web/tests/navigation-panes.e2e.ts index ae8726c23f..9632042b34 100644 --- a/apps/web/tests/navigation-panes.e2e.ts +++ b/apps/web/tests/navigation-panes.e2e.ts @@ -12,7 +12,10 @@ import { join } from 'node:path' import type { Browser, Page, Response } from 'playwright' import { chromium } from 'playwright' import { strFromU8, unzipSync } from 'fflate' -import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, onTestFailed } from 'vitest' +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, onTestFailed, onTestFinished } from 'vitest' +import { ToolCallId, createToolResultMessage } from '@deepseek-ai/dsh-llm' +import type SessionToolResults from '@deepseek-ai/dsh-client-ui-trajectory' +import { defineTool } from '@deepseek-ai/dsh-tools' import { parseSessionLog } from '@deepseek-ai/dsh-llm-replay' import { SESSION_FORMAT_VERSION, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' import { @@ -33,6 +36,9 @@ const CODE_CARD_DIR = fileURLToPath(new URL('./expected/navigation-panes', impor const COMMAND_WRAP_EXPECTED = join(CODE_CARD_DIR, 'command-wrap.expected.md') const CODE_CARD_EXPECTED = join(CODE_CARD_DIR, 'code-card.expected.md') const COPY_MARKDOWN_EXPECTED = join(CODE_CARD_DIR, 'copy-markdown.expected.md') +const EVICTED_RESULT_EXPECTED = join(CODE_CARD_DIR, 'live-result-evicted.expected.md') +const LIVE_RESULT_EXPECTED = join(CODE_CARD_DIR, 'live-result.expected.md') +const RUNNING_RESULT_EXPECTED = join(CODE_CARD_DIR, 'live-result-running.expected.md') const MODE = webSnapshotMode() const SEED_ID = 'navigation-panes-web-e2e' const EXPORTED_LOG_FILE = `session.v${SESSION_FORMAT_VERSION}.jsonl` @@ -306,6 +312,7 @@ describe('web e2e: navigation & panes over a rich seeded session', () => { await page.getByRole('tab', { name: 'Result' }).click() await expect.poll(() => page.getByText('NAVIGATION_OK', { exact: false }).count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(1) expect(await page.locator('[data-timeline-span="message"][data-assistant-timing="true"]').count()).toBeGreaterThan(0) + await page.getByText('Raw results are only available for live tool calls', { exact: true }).waitFor() const snapshot = (await captureStableAria(page, '[class*="viewArea"]', scaffold.workspaceCwd)) .split(SEED_ID).join('{{seededId}}') await compareOrRefreshGolden(TRAJECTORY_EXPECTED, snapshot, MODE) @@ -624,10 +631,218 @@ describe('web e2e: navigation & panes over a rich seeded session', () => { it.skipIf(MODE === 'record')('keeps the recorded fixture inventory exact', async () => { await assertFixtureInventory(CODE_CARD_DIR, [ 'code-card.expected.md', 'command-wrap.expected.md', 'copy-markdown.expected.md', + 'live-result-evicted.expected.md', 'live-result.expected.md', 'live-result-running.expected.md', ]) await assertFixtureInventory(SNAPSHOT_DIR, [ 'session.v3.jsonl', 'search-id-results.expected.md', 'search-results.expected.md', 'trajectory.expected.md', 'terminal-card.expected.md', 'timing.expected.md', ]) }) + it.skipIf(MODE === 'record')('inspects a live tool value without adding it to the Session journal', async () => { + await ensureSeedOpen(page) + await expect.poll(() => scaffold.ctx.agents.get(SessionId(SEED_ID)) !== undefined).toBe(true) + const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))! + const unregister = scaffold.ctx.tools.register(defineTool({ + name: 'live_result_probe', description: 'Live result inspection fixture.', parameters: {}, + output: { schema: { type: 'json' }, render: () => [{ type: 'text', text: 'LIVE_RESULT_RENDERED' }] }, + execute: async () => ({ answer: 42 }), + })) + onTestFinished(unregister) + const callId = ToolCallId('live-result-probe') + let resultEvent: SessionEvent | undefined + const off = scaffold.ctx.on('session/event', (_session, event) => { + if (event.type === 'tool/result' && event.data.message.toolCallId === callId) resultEvent = event + }, { global: true }) + onTestFinished(() => { off() }) + const batch = await scaffold.ctx.tools.execute({ + agent, signal: new AbortController().signal, log: { turn: 2, step: 1 }, + calls: [{ type: 'tool-call', id: callId, name: 'live_result_probe', arguments: '{}' }], + }) + expect(batch.results[0]?.result.isError).toBe(false) + expect(resultEvent).toBeDefined() + expect(resultEvent?.data).not.toHaveProperty('value') + const abort = new AbortController() + const observed = (scaffold.ctx.get('sessionToolResults') as SessionToolResults).watch( + { sessionId: agent.id, seq: resultEvent!.seq }, abort.signal, + )[Symbol.asyncIterator]() + try { + expect((await observed.next()).value).toEqual({ available: true, value: { answer: 42 } }) + } finally { abort.abort(); await observed.return?.() } + + await page.getByRole('tab', { name: 'Trajectory' }).click() + await page.locator('tr[data-kind="tool"]').filter({ hasText: 'live_result_probe' }).click() + const details = page.getByRole('complementary', { name: 'Event details' }) + await details.getByRole('tab', { name: 'Result', exact: true }).click() + await details.getByText('LIVE_RESULT_RENDERED', { exact: true }).waitFor() + const rawSection = details.getByRole('region', { name: 'Raw result', exact: true }) + const renderedSection = details.getByRole('region', { name: 'Rendered result', exact: true }) + await expect.poll(() => rawSection.textContent()).toContain('answer:') + expect(await renderedSection.textContent()).toContain('LIVE_RESULT_RENDERED') + expect(await details.getByRole('button', { name: 'Raw result', exact: true }).count()).toBe(0) + await compareOrRefreshGolden( + LIVE_RESULT_EXPECTED, await captureStableAria(page, '#trajectory-detail-panel', scaffold.workspaceCwd), MODE, + ) + const unregisterJson = scaffold.ctx.tools.register(defineTool({ + name: 'json_result_probe', description: 'JSON result inspection fixture.', parameters: {}, + output: { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }] }, + execute: async () => Array.from({ length: 80 }, (_, index) => index), + })) + onTestFinished(unregisterJson) + const jsonBatch = await scaffold.ctx.tools.execute({ + agent, signal: new AbortController().signal, log: { turn: 2, step: 1 }, + calls: [{ type: 'tool-call', id: ToolCallId('json-result-probe'), name: 'json_result_probe', arguments: '{}' }], + }) + expect(jsonBatch.results[0]?.result.isError).toBe(false) + await page.locator('tr[data-kind="tool"]').filter({ hasText: 'json_result_probe' }).click() + await rawSection.getByRole('tree').waitFor() + await renderedSection.getByRole('tree').waitFor() + const originalViewport = page.viewportSize()! + try { + for (const width of [originalViewport.width, 390]) { + await page.setViewportSize({ width, height: 600 }) + const geometry = await details.getByRole('tabpanel').evaluate((panel) => { + const sections = [...panel.querySelectorAll('section[aria-label]')] + const first = sections[0]!.getBoundingClientRect() + const second = sections[1]!.getBoundingClientRect() + return { + gap: second.top - first.bottom, + headingFonts: sections.map(section => getComputedStyle(section.querySelector('h3')!).fontSize), + overflowingDescendants: [...panel.querySelectorAll('*')].filter(node => + /auto|scroll/.test(getComputedStyle(node).overflowY) && node.scrollHeight > node.clientHeight + 1).length, + scrolls: panel.scrollHeight > panel.clientHeight, + horizontalOverflow: panel.scrollWidth > panel.clientWidth + 1, + headingsAligned: first.left === second.left, + } + }) + expect(geometry).toEqual({ + gap: 2, headingFonts: ['13px', '13px'], overflowingDescendants: 0, + scrolls: true, horizontalOverflow: false, headingsAligned: true, + }) + await details.getByRole('tabpanel').evaluate((panel) => { panel.scrollTop = panel.scrollHeight }) + expect(await details.getByRole('tabpanel').evaluate(panel => panel.scrollTop)).toBeGreaterThan(0) + } + } finally { + await page.setViewportSize(originalViewport) + } + await page.locator('tr[data-kind="tool"]').filter({ hasText: 'live_result_probe' }).click() + await expect.poll(() => rawSection.textContent()).toContain('answer:') + const newer = await scaffold.ctx.tools.execute({ + agent, signal: new AbortController().signal, + calls: Array.from({ length: 1000 }, (_, index) => ({ + type: 'tool-call' as const, id: ToolCallId(`newer-result-${index}`), name: 'live_result_probe', arguments: '{}', + })), + }) + expect(newer.results).toHaveLength(1000) + expect(newer.results.every(entry => !entry.result.isError)).toBe(true) + await details.getByText('Raw results are only available for live tool calls', { exact: true }).waitFor() + // Keep hover and focus tooltips out of the recorded result panel. + await details.getByText('Raw results are only available for live tool calls', { exact: true }).click() + await details.getByRole('tooltip').waitFor({ state: 'hidden' }) + await compareOrRefreshGolden( + EVICTED_RESULT_EXPECTED, await captureStableAria(page, '#trajectory-detail-panel', scaffold.workspaceCwd), MODE, + ) + await details.getByText('LIVE_RESULT_RENDERED', { exact: true }).waitFor() + }) + + it.skipIf(MODE === 'record')('keeps long raw strings and PTC output readable in one result scroller', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-long-tool-results')) + await ensureSeedOpen(page) + await expect.poll(() => scaffold.ctx.agents.get(SessionId(SEED_ID)) !== undefined).toBe(true) + const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))! + agent.session.append('turn/start', { turn: 3 }) + onTestFinished(() => { + agent.session.append('step/end', { turn: 3, step: 1 }) + agent.session.append('turn/end', { turn: 3, reason: { kind: 'completed' } }) + }) + agent.session.append('step/start', { turn: 3, step: 1 }) + const callId = ToolCallId('long-ptc-result') + const call = agent.session.append('tool/call', { + turn: 3, step: 1, callId, name: 'run_code', + arguments: JSON.stringify({ code: 'console.log("PTC output")', description: 'Long program output' }), + }) + await page.getByRole('tab', { name: 'Trajectory' }).click() + await page.locator('tr[data-kind="tool"]').filter({ hasText: 'Long program output' }).click() + const details = page.getByRole('complementary', { name: 'Event details' }) + await details.getByRole('tab', { name: 'Result', exact: true }).click() + const raw = details.getByRole('region', { name: 'Raw result', exact: true }) + const rendered = details.getByRole('region', { name: 'Rendered result', exact: true }) + await raw.getByText('Running…', { exact: true }).waitFor() + await compareOrRefreshGolden( + RUNNING_RESULT_EXPECTED, await captureStableAria(page, '#trajectory-detail-panel', scaffold.workspaceCwd), MODE, + ) + const ptcOutput = [...Array.from({ length: 100 }, (_, i) => `PTC_LINE_${i}`), 'PTC_END'].join('\n') + agent.session.append('tool/result', { + turn: 3, step: 1, + message: createToolResultMessage({ callId, content: [{ type: 'text', text: ptcOutput }], isError: false }), + }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] }) + await rendered.getByText(ptcOutput, { exact: true }).waitFor() + const stringValue = 'raw_output_'.repeat(300) + 'RAW_END' + const probes = [ + { name: 'long_string_probe', value: stringValue }, + { name: 'long_json_probe', value: { detail: 'json_output_'.repeat(120) } }, + ] + for (const probe of probes) { + const unregister = scaffold.ctx.tools.register(defineTool({ + name: probe.name, description: 'Long result layout fixture.', parameters: {}, + output: { + schema: { type: 'json' }, + render: (_args, value) => [{ type: 'text', text: typeof value === 'string' ? 'STRING_RENDERED' : JSON.stringify(value) }], + }, + execute: async () => probe.value, + })) + onTestFinished(unregister) + const batch = await scaffold.ctx.tools.execute({ + agent, signal: new AbortController().signal, log: { turn: 3, step: 1 }, + calls: [{ type: 'tool-call', id: ToolCallId(probe.name), name: probe.name, arguments: '{}' }], + }) + expect(batch.results[0]?.result.isError).toBe(false) + } + const viewport = page.viewportSize()! + try { + for (const width of [viewport.width, 390]) { + await page.setViewportSize({ width, height: 600 }) + for (const name of ['Long program output', ...probes.map(probe => probe.name)]) { + await details.getByRole('button', { name: 'Close details' }).click() + await page.locator('tr[data-kind="tool"]').filter({ hasText: name }).click() + await details.getByRole('tab', { name: 'Result', exact: true }).click() + if (name === 'long_json_probe') { + await raw.getByRole('treeitem').waitFor() + const heights = await Promise.all([raw, rendered].map(section => + section.getByRole('treeitem').evaluate(row => row.getBoundingClientRect().height))) + expect(heights[0]).toBeGreaterThan(3 * 16) + expect(heights[0]).toBe(heights[1]) + } else { + const body = name === 'Long program output' ? rendered : raw + await expect.poll(() => body.locator('pre').textContent()).toBe( + name === 'Long program output' ? ptcOutput : JSON.stringify(stringValue), + ) + } + const panel = details.getByRole('tabpanel') + const geometry = await panel.evaluate((element) => { + element.scrollTop = element.scrollHeight + const bounds = element.getBoundingClientRect() + const pre = element.querySelector('pre') + let tailVisible = true + if (pre?.lastChild !== null && pre?.lastChild !== undefined) { + const range = document.createRange() + range.selectNodeContents(pre) + range.setStart(pre.lastChild, (pre.lastChild.textContent?.length ?? 1) - 1) + const tail = range.getBoundingClientRect() + tailVisible = tail.top >= bounds.top && tail.bottom <= bounds.bottom + } + return { + scrolls: element.scrollTop > 0 && getComputedStyle(element).overflowY === 'auto', + tailVisible, + overflowingDescendants: [...element.querySelectorAll('*')].filter(node => + /auto|scroll/.test(getComputedStyle(node).overflowY) && node.scrollHeight > node.clientHeight + 1).length, + horizontalOverflow: element.scrollWidth > element.clientWidth + 1, + } + }) + expect(geometry).toEqual({ scrolls: true, tailVisible: true, overflowingDescendants: 0, horizontalOverflow: false }) + } + } + } finally { + await page.setViewportSize(viewport) + } + }) }) diff --git a/apps/web/tests/no-sidebar-documentpreview.overlay.yml b/apps/web/tests/no-sidebar-documentpreview.overlay.yml new file mode 100644 index 0000000000..1c98598ecb --- /dev/null +++ b/apps/web/tests/no-sidebar-documentpreview.overlay.yml @@ -0,0 +1,3 @@ +# Exercise the workspace file browser without the document preview. +- id: ui-sidebar-documentpreview + disabled: true diff --git a/apps/web/tests/no-sidebar-files.overlay.yml b/apps/web/tests/no-sidebar-files.overlay.yml new file mode 100644 index 0000000000..4eebce9f6e --- /dev/null +++ b/apps/web/tests/no-sidebar-files.overlay.yml @@ -0,0 +1,3 @@ +# Exercise the document preview without the workspace file browser. +- id: ui-sidebar-files + disabled: true diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts index fd606099de..333accd0aa 100644 --- a/apps/web/tests/onboarding-deepseek-config.e2e.ts +++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts @@ -248,7 +248,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup const customModelId = model.getByLabel('模型 ID 1') await customModelId.fill('private-preview') await model.getByLabel('显示名称 1').fill('Private Preview') - await settings.getByRole('button', { name: '模型选项 1' }).click() + expect(await settings.getByRole('button', { name: '模型选项 1' }).getAttribute('aria-expanded')).toBe('true') await model.getByLabel('上下文窗口 1').fill('131072') await model.getByLabel('最大输出 token 数 1').fill('64K') expect(await settings.getByRole('group', { name: '输入类型 1' }).getByRole('checkbox', { name: '图片' }).isChecked()).toBe(false) diff --git a/apps/web/tests/plan-control-row.e2e.ts b/apps/web/tests/plan-control-row.e2e.ts index 99146362a1..5d8f5b39ae 100644 --- a/apps/web/tests/plan-control-row.e2e.ts +++ b/apps/web/tests/plan-control-row.e2e.ts @@ -62,7 +62,17 @@ async function controlLayout(page: Page) { /** Wait for the responsive column and control row to finish changing width. */ async function resizeControls(page: Page, width: number): Promise { + const previousWidth = page.viewportSize()!.width await page.setViewportSize({ width, height: VIEWPORT.height }) + if (width >= 768 && width < 1024) { + const frame = page.locator('[data-sidebar-collapsed][data-rightbar-collapsed]') + if (previousWidth >= 1024) await frame.waitFor() + const open = page.getByRole('button', { name: 'Open sidebar', exact: true }) + if (await open.isVisible()) { + await open.click() + await expect.poll(() => frame.count()).toBe(0) + } + } await page.locator('[data-composer-card]').evaluate(async (card) => { let previous = card.getBoundingClientRect().width let stable = 0 @@ -201,7 +211,7 @@ describe('web e2e: plan chip click area at the narrow viewport', () => { // Find the content-dependent transition on this platform's fonts, never a // committed pixel threshold. The old 360px rule cannot satisfy this case. let narrowViewport: number | undefined - for (let width = 1100; width >= 650; width -= 10) { + for (let width = 1100; width >= 770; width -= 10) { await resizeControls(page, width) const layout = await controlLayout(page) if (layout.width > 360 && layout.icon && !layout.text) { @@ -256,6 +266,27 @@ describe('web e2e: plan chip click area at the narrow viewport', () => { expect(tripwire.warnings).toEqual([]) }, 200_000) + // The suite above only reaches the icon through the Plan chip's width. This + // case keeps the row otherwise empty: a long model name must still exceed + // the row above the mobile minimum, so a row-relative width cap cannot hide + // the demand behind a shrunken, ellipsized name. + it('collapses the model text on a narrow composer without another control', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-model-collapse-no-plan')) + await page.locator('[data-composer-input]').first().waitFor({ timeout: 10_000 }) + await resizeControls(page, 1680) + await selectModel(page, LONG_MODEL) + await expectControlLayout(page, false) + + await resizeControls(page, 384) + await expectControlLayout(page, true) + const trigger = page.getByRole('button', { name: /Select model/ }) + expect(await trigger.getAttribute('title')).toContain(LONG_MODEL) + expect(await trigger.getAttribute('aria-label')).toContain(LONG_MODEL) + + await resizeControls(page, 1680) + await expectControlLayout(page, false) + }, 120_000) + it('keeps the snapshot inventory closed', async () => { await assertFixtureInventory(SNAPSHOT_DIR, ['session.v3.jsonl']) }) diff --git a/apps/web/tests/plugin-config.e2e.ts b/apps/web/tests/plugin-config.e2e.ts index 39bd1ce0a5..8e78f856eb 100644 --- a/apps/web/tests/plugin-config.e2e.ts +++ b/apps/web/tests/plugin-config.e2e.ts @@ -110,9 +110,15 @@ describe('web e2e: plugin configuration pages', () => { await more.focus() await page.keyboard.press('Enter') await panel.getByRole('heading', { name: '实验性插件', exact: true, level: 1 }).waitFor() + // The More list omits the shipped bundles whose own rows do not run (the visibility rule lives in + // ui-plugin-manager), so it holds fewer cards than the installed optional-bundle list. const bundles = await scaffold.ctx.pluginManager.listBundles() + const hiddenBundles = new Set([ + '@deepseek-ai/dsh-experimental-terminal-bundle', + '@deepseek-ai/dsh-experimental-liveshare', + ]) expect(await panel.locator('[data-plugin-group="more"] [data-plugin-package]').count()) - .toBe(bundles.filter(bundle => bundle.name !== '@deepseek-ai/dsh-experimental-terminal-bundle' + .toBe(bundles.filter(bundle => !hiddenBundles.has(bundle.name) && bundle.official && (bundle.listedByDefault !== false || bundle.enabled || bundle.installed)).length) expect(await basic.count()).toBe(0) expect(await extensions.count()).toBe(0) diff --git a/apps/web/tests/plugin-install-github.e2e.ts b/apps/web/tests/plugin-install-github.e2e.ts index a11f2b942b..7fc4ece9fd 100644 --- a/apps/web/tests/plugin-install-github.e2e.ts +++ b/apps/web/tests/plugin-install-github.e2e.ts @@ -1,6 +1,8 @@ // Real Git reaches a controlled proxy failure or stall; the browser // offers a mirror for a replacement spec, or another way once the install -// already asks the mirror, without retrying the failed address. +// already asks the mirror, without retrying the failed address. Without a +// configured fallback registry the same failure keeps the plain failed +// screen, whose details name the check's own Git run and complete log. import { once } from 'node:events' import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises' import { createServer, type Socket } from 'node:net' @@ -121,3 +123,66 @@ it.each(['network', 'timeout'] as const)('offers a mirror after a GitHub %s, the expect(connections).toBeGreaterThan(checked) expect(tripwire.pageErrors).toEqual([]) }) + +it("shows the failed check's Git run and complete log in the installation details when no mirror is offered", async () => { + const scratch = await mkdtemp(join(tmpdir(), 'dsh-install-github-details-')) + onTestFinished(() => rm(scratch, { recursive: true, force: true })) + const sockets = new Set() + const proxy = createServer((socket) => { + sockets.add(socket) + socket.on('error', () => {}) + socket.once('close', () => { sockets.delete(socket) }) + socket.once('data', () => socket.destroy()) + }) + onTestFinished(async () => { + for (const socket of sockets) socket.destroy() + await new Promise((resolve, reject) => { proxy.close((error) => { if (error) reject(error); else resolve() }) }) + }) + proxy.listen(0, '127.0.0.1') + await once(proxy, 'listening') + const address = proxy.address() + if (address === null || typeof address === 'string') throw new Error('proxy did not bind a TCP port') + const gitConfig = join(scratch, 'git.config') + await writeFile(gitConfig, `[http "https://github.com/"]\n proxy = http://127.0.0.1:${String(address.port)}\n`) + // Without a configured fallback registry the Host has no mirror to offer, so the failure keeps the + // plain failed screen whose details name the check's own run. + const overlay = join(scratch, 'cordis.patch.yml') + await writeFile(overlay, '- id: ui-plugin-manager\n config: { registryProbeEnabled: false }\n- id: plugin-manager\n config: { fallbackRegistries: [] }\n') + const scaffold = await launchWebScaffold({ + profile: { packages: [], packageManager: { command: process.execPath, args: [], env: { GIT_CONFIG_GLOBAL: gitConfig, GIT_CONFIG_NOSYSTEM: '1' } } }, + extraOverlayPath: overlay, + }) + onTestFinished(() => scaffold.close()) + const browser = await chromium.launch() + onTestFinished(() => browser.close()) + const profile = join(scaffold.harnessHome, 'profiles', 'scaffold') + const attempts = join(profile, '.attempts') + await writeFile(join(profile, 'config'), 'console.log("https://registry.npmjs.org/")\n') + await writeFile(attempts, '') + await writeFile(join(profile, 'add'), ` + const fs = require('node:fs'); + fs.appendFileSync('.attempts', JSON.stringify(process.argv) + '\\n'); + process.exitCode = 1; + `) + const page = await browser.newPage({ viewport: { width: 1280, height: 800 }, locale: ZH_BROWSER_LOCALE }) + const tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl) + await page.waitForSelector('[class*="frame"]') + if (await page.getByRole('dialog', { name: '设置' }).count() > 0) await page.keyboard.press('Escape') + await page.getByRole('navigation', { name: '全局面板' }).getByRole('button', { name: '插件', exact: true }).click() + await page.getByRole('button', { name: '添加插件', exact: true }).click() + const spec = 'https://github.com/example/dsh-plugin.git' + let dialog = page.getByRole('dialog', { name: '添加插件', exact: true }) + await dialog.getByRole('textbox', { name: '包名或地址' }).fill(spec) + await dialog.getByRole('button', { name: '安装', exact: true }).click() + dialog = page.getByRole('dialog', { name: '插件安装失败', exact: true }) + await dialog.waitFor() + expect(await dialog.getByText('无法连接 github.com', { exact: false }).count()).toBe(1) + // The details carry the failed check's own Git run and the complete log, not an empty terminal. + await dialog.getByRole('button', { name: '查看安装详情', exact: true }).click() + await dialog.getByText(/git -c credential\.helper= ls-remote -- https:\/\/github\.com\/example\/dsh-plugin\.git HEAD/).waitFor() + await dialog.getByText(/fatal: unable to access/).waitFor() + expect(await dialog.getByText(/^完整日志：.*github-connection-.*git\.log$/).count()).toBe(1) + expect(await readFile(attempts, 'utf8')).toBe('') + expect(tripwire.pageErrors).toEqual([]) +}) diff --git a/apps/web/tests/plugin-install-registry.e2e.ts b/apps/web/tests/plugin-install-registry.e2e.ts index 5a29cceada..70d8f47520 100644 --- a/apps/web/tests/plugin-install-registry.e2e.ts +++ b/apps/web/tests/plugin-install-registry.e2e.ts @@ -124,6 +124,7 @@ it.each(['https://registry.npmjs.org/', MIRROR])('selects the fastest responding const installed = (await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)) .split(process.execPath).join('{{node}}') .split(scaffold.harnessHome).join('{{harnessHome}}') + .replace(/operation-[A-Za-z0-9]+/g, 'operation-{{suffix}}') await compareOrRefreshGolden(fileURLToPath(new URL('./expected/plugin-install-registry/installed.expected.md', import.meta.url)), installed, webSnapshotMode()) // The dialog opened again starts from the registry picked for the last install. await dialog.getByRole('button', { name: '立即启用', exact: true }).click() diff --git a/apps/web/tests/plugin-install-silent-failure.e2e.ts b/apps/web/tests/plugin-install-silent-failure.e2e.ts new file mode 100644 index 0000000000..4a487c24fe --- /dev/null +++ b/apps/web/tests/plugin-install-silent-failure.e2e.ts @@ -0,0 +1,59 @@ +// A real Host/Remote/browser composition with a controllable package-manager process: +// pnpm fails without printing anything, and the dialog still shows what failed and where +// the complete log lives instead of a generic sentence over an empty details panel. +import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { chromium } from 'playwright' +import { expect, it } from 'vitest' +import { launchWebScaffold, captureStableAria, compareOrRefreshGolden, webSnapshotMode, watchConsole, type WebScaffold } from './scaffold.ts' +import { ZH_BROWSER_LOCALE } from './support.ts' + +it('reports a failed install whose pnpm printed nothing with its command line, output, and log file', async () => { + const scratch = await mkdtemp(join(tmpdir(), 'dsh-install-silent-')) + const overlay = join(scratch, 'cordis.patch.yml') + await writeFile(overlay, `- id: plugin-manager\n config: ${JSON.stringify({ pnpmCommand: process.execPath })}\n`) + let scaffold: WebScaffold | undefined + try { + scaffold = await launchWebScaffold({ profile: { packages: [] }, extraOverlayPath: overlay }) + const browser = await chromium.launch() + try { + const profile = join(scaffold.harnessHome, 'profiles', 'scaffold') + // Node stands in for pnpm: `view` answers the check, and `add` exits unsuccessfully without printing + // anything, the way a silent or early-crashing package manager leaves a failed run with no terminal output. + await writeFile(join(profile, 'view'), 'console.log(JSON.stringify({ name: "silent-package", version: "1.0.0", dsh: { bundle: { patch: "./cordis.patch.yml" } } }))\n') + await writeFile(join(profile, 'add'), 'process.exitCode = 1\n') + const page = await browser.newPage({ viewport: { width: 1440, height: 1000 }, locale: ZH_BROWSER_LOCALE }) + const tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl) + await page.waitForSelector('[class*="frame"]') + if (await page.getByRole('dialog', { name: '设置' }).count() > 0) await page.keyboard.press('Escape') + await page.getByRole('navigation', { name: '全局面板' }).getByRole('button', { name: '插件', exact: true }).click() + await page.getByRole('button', { name: '添加插件', exact: true }).click() + const dialog = page.getByRole('dialog') + await dialog.getByRole('textbox').fill('silent-package') + await dialog.getByRole('button', { name: '安装', exact: true }).click() + const failure = page.getByRole('dialog', { name: '插件安装失败', exact: true }) + await failure.waitFor({ timeout: 20_000 }) + // The sentence names the failed stage; the details carry the Host's own record of the run. + await failure.getByText('安装命令失败，原因见安装详情', { exact: true }).waitFor() + await failure.getByRole('button', { name: '查看安装详情', exact: true }).click() + await failure.getByText('pnpm add silent-package', { exact: true }).waitFor() + await failure.getByText(/Command failed with exit code 1:/).waitFor() + expect(await failure.getByText(/^完整日志：.*pnpm\.log$/).count()).toBe(1) + expect(await readFile(join(profile, 'package.json'), 'utf8')).not.toContain('silent-package') + const snapshot = (await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)) + .split(process.execPath).join('{{node}}') + .split(scaffold.harnessHome).join('{{harnessHome}}') + .replace(/operation-[A-Za-z0-9]+/g, 'operation-{{suffix}}') + await compareOrRefreshGolden( + fileURLToPath(new URL('./expected/plugin-install-silent-failure/failed.expected.md', import.meta.url)), snapshot, webSnapshotMode(), + ) + expect(tripwire.pageErrors).toEqual([]) + } finally { await browser.close() } + } finally { + await scaffold?.close() + await rm(scratch, { recursive: true, force: true }) + } +}) diff --git a/apps/web/tests/plugin-manager.e2e.ts b/apps/web/tests/plugin-manager.e2e.ts index 08f08cd77b..124ac12ddb 100644 --- a/apps/web/tests/plugin-manager.e2e.ts +++ b/apps/web/tests/plugin-manager.e2e.ts @@ -2,7 +2,7 @@ // managed scaffold profile: installed bundles, their rows, and bundle enablement. Zero // model calls: everything is client state, seeded Session state, profile files, and the settings // document, so there is no fixture and a stray stream would fail loud on the open llm seam. -import { mkdtemp, readFile } from 'node:fs/promises' +import { mkdtemp, readFile, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { fileURLToPath } from 'node:url' import type { Browser, Locator, Page } from 'playwright' @@ -17,7 +17,7 @@ import { launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, } from './scaffold.ts' import { - ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, openSettings, PLUGIN_TOGGLE_SETTLE_MS, saveFailureShot, + ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, experimentalBundleDescription, openSettings, PLUGIN_TOGGLE_SETTLE_MS, saveFailureShot, } from './support.ts' const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/plugin-manager', import.meta.url)) @@ -268,8 +268,8 @@ describe('web e2e: plugin manager', () => { await bar.getByRole('tablist').waitFor() await add.focus() for (const [width, icons, narrowTabs, wraps] of [ - [1280, false, false, false], [600, true, false, false], - [470, true, true, false], [390, true, true, true], [300, true, true, true], + [1280, false, false, false], [544, true, false, false], + [390, true, true, false], [320, true, true, true], [244, true, true, true], ] as const) { await probe.setViewportSize({ width, height: 480 }) await body.evaluate((element) => { element.scrollTop = 180 }) @@ -840,16 +840,26 @@ describe('web e2e: plugin manager', () => { expect(await panel.getByRole('switch', { name: '启用 自定义插件索引', exact: true }).getAttribute('aria-checked')).toBe('false') expect(await panel.getByRole('switch', { name: '启用 开发者工具', exact: true }).count()).toBe(0) expect(await panel.getByText(/Cordis|Chrome DevTools/).count()).toBe(0) + // A bundle the installation ships but the profile runs no row of stays out of both lists: the + // LiveShare card appears only once its own plugins run (covered by the visibility scenario below). + expect(await panel.locator('[data-plugin-group="extensions"] [data-plugin-package="@deepseek-ai/dsh-experimental-liveshare"]').count()).toBe(0) await panel.getByRole('button', { name: '更多', exact: true }).click() await panel.getByRole('heading', { name: '实验性插件', exact: true, level: 1 }).waitFor() - expect(await panel.getByText('查看调试会话原始数据、聊天消息分组数据，以及调试 NodeJS 后端', { exact: true }).count()).toBe(1) + expect(await panel.getByText(experimentalBundleDescription('inspector-profile', 'zh'), { exact: true }).count()).toBe(1) const bundles = await scaffold.ctx.pluginManager.listBundles() expect(bundles.some(bundle => bundle.name === '@deepseek-ai/dsh-experimental-terminal-bundle')).toBe(true) expect(await panel.getByRole('switch', { name: '启用 持久终端', exact: true }).count()).toBe(0) + // The More list also omits LiveShare until its rows run, so the offered count is one lower than + // the eligible installed optional-bundle list. + expect(await panel.locator('[data-plugin-group="more"] [data-plugin-package="@deepseek-ai/dsh-experimental-liveshare"]').count()).toBe(0) expect(await panel.locator('[data-plugin-group="more"] [data-plugin-package]').count()) .toBe(bundles.filter(bundle => bundle.name !== '@deepseek-ai/dsh-experimental-terminal-bundle' + && bundle.name !== '@deepseek-ai/dsh-experimental-liveshare' && bundle.official && (bundle.listedByDefault !== false || bundle.enabled || bundle.installed)).length) - for (const name of ['@deepseek-ai/dsh-cua-bundle', '@deepseek-ai/dsh-experimental-session-search', '@deepseek-ai/dsh-experimental-ralph-bundle']) { + expect(bundles.find(bundle => bundle.name === '@deepseek-ai/dsh-cua-bundle')) + .toMatchObject({ enabled: false, optional: false, availability: 'missing', listedByDefault: false }) + expect(await panel.locator('[data-plugin-package="@deepseek-ai/dsh-cua-bundle"]').count()).toBe(0) + for (const name of ['@deepseek-ai/dsh-experimental-session-search', '@deepseek-ai/dsh-experimental-ralph-bundle']) { expect((await scaffold.ctx.pluginManager.listBundles()).find(bundle => bundle.name === name)) .toMatchObject({ enabled: false, optional: true, availability: 'installation', listedByDefault: false }) expect(await panel.locator(`[data-plugin-package="${name}"]`).count()).toBe(0) @@ -863,6 +873,7 @@ describe('web e2e: plugin manager', () => { ['@deepseek-ai/dsh-experimental-voice-input-bundle', 1], ['@deepseek-ai/dsh-experimental-plugin-market-bundle', 1], ['@deepseek-ai/dsh-experimental-auto-review', 1], + ['@deepseek-ai/dsh-experimental-forge-bundle', 1], ['@deepseek-ai/dsh-personalized-recommendations', 1], ['@deepseek-ai/dsh-experimental-inspector-profile', 1], ['@deepseek-ai/dsh-experimental-tool-worktree', 1], @@ -1096,7 +1107,7 @@ describe('web e2e: plugin manager', () => { await panel.getByRole('button', { name: '查看 智能体团队', exact: true }).click() const packageName = panel.locator('[data-plugin-name]') expect(await packageName.textContent()).toBe('@deepseek-ai/dsh-experimental-agent-team-profile') - expect(await panel.getByText('为子智能体树添加共享任务板工具与任务面板。').count()).toBe(1) + expect(await panel.getByText(experimentalBundleDescription('agent-team-profile', 'zh')).count()).toBe(1) const child = panel.locator('[data-plugin-row]', { hasText: 'tool-agent-team' }) await child.getByText('团队工具', { exact: true }).waitFor() expect(await child.getByText('为智能体提供共享任务板管理工具。', { exact: true }).count()).toBe(1) @@ -1104,7 +1115,7 @@ describe('web e2e: plugin manager', () => { await setLanguage('en') await panel.getByRole('heading', { name: 'Agent teams', exact: true }).waitFor() expect(await packageName.textContent()).toBe('@deepseek-ai/dsh-experimental-agent-team-profile') - expect(await panel.getByText('Add shared task-board tools and a task panel to the subagent tree.').count()).toBe(1) + expect(await panel.getByText(experimentalBundleDescription('agent-team-profile', 'en')).count()).toBe(1) await child.getByText('Team tools', { exact: true }).waitFor() expect(await child.getByText('Give agents tools to manage their shared task board.', { exact: true }).count()).toBe(1) await panel.getByRole('button', { name: 'Back to plugins' }).click() @@ -1432,6 +1443,76 @@ describe('web e2e: plugin manager', () => { expect(tripwire.pageErrors).toEqual([]) }, 90_000) + it('reveals LiveShare only while its plugin rows run, and hides it again when they stop', async () => { + // A dedicated scaffold keeps this profile patch away from the shared fixture profile above. + const visibilityScaffold = await launchWebScaffold({ profile: { packages: [] } }) + const context = await browser.newContext({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE }) + try { + const probe = await context.newPage() + onTestFailed(() => saveFailureShot(probe, 'web-e2e-plugin-manager-liveshare-visibility')) + const consoleWatch = watchConsole(probe) + await probe.goto(visibilityScaffold.authenticatedUrl, { waitUntil: 'load' }) + await probe.getByRole('button', { name: '插件', exact: true }).click() + const panel = probe.locator('[data-plugin-panel]') + await panel.getByRole('heading', { name: '插件', exact: true }).waitFor({ timeout: 20_000 }) + const liveShare = '@deepseek-ai/dsh-experimental-liveshare' + const card = panel.locator(`[data-plugin-package="${liveShare}"]`) + // The profile is a managed one (the plugin manager lists its bundles) whose base bundle keeps HMR + // on, so writing the patch file recomposes the running loader; each step first waits for that + // recomposition and then re-reads the Host bundle list through the page's own Refresh. + const patchFile = join(visibilityScaffold.harnessHome, 'profiles', 'scaffold', 'cordis.patch.yml') + const declarationsRow = (): boolean => [...visibilityScaffold.ctx.loader.entries()] + .some(entry => entry.options.id === 'liveshare-viewer-declarations') + const refresh = panel.getByRole('button', { name: '刷新', exact: true }) + + // Default install: the package ships, but no row it declares runs, so neither list offers it. + await expect.poll(() => card.count(), { + timeout: 20_000, message: 'the default profile lists a LiveShare card before its rows run', + }).toBe(0) + await panel.getByRole('button', { name: '更多', exact: true }).click() + await probe.getByRole('heading', { name: '实验性插件', exact: true, level: 1 }).waitFor() + await expect.poll(() => card.count(), { + timeout: 20_000, message: 'the default More list offers a LiveShare card before its rows run', + }).toBe(0) + await panel.getByRole('button', { name: '返回插件', exact: true }).click() + + // Enabling through cordis.patch.yml runs one of the bundle's declared rows while the profile still + // selects no such bundle: the card joins the experimental list. + await writeFile(patchFile, [ + '- insert:', + ' - id: liveshare-viewer-declarations', + " name: '@deepseek-ai/dsh-experimental-liveshare/viewer-declarations'", + '', + ].join('\n')) + await expect.poll(declarationsRow, { + timeout: 30_000, message: 'the profile patch did not compose the LiveShare declarations row', + }).toBe(true) + await refresh.click() + await expect.poll(() => card.count(), { + timeout: 30_000, message: 'the patch-enabled bundle did not join the experimental list', + }).toBe(1) + + // Removing the row stops it: the card leaves both lists again. + await writeFile(patchFile, '[]\n') + await expect.poll(declarationsRow, { + timeout: 30_000, message: 'the profile patch did not remove the LiveShare declarations row', + }).toBe(false) + await refresh.click() + await expect.poll(() => card.count(), { + timeout: 30_000, message: 'the card stayed listed after its rows stopped', + }).toBe(0) + await panel.getByRole('button', { name: '更多', exact: true }).click() + await probe.getByRole('heading', { name: '实验性插件', exact: true, level: 1 }).waitFor() + await expect.poll(() => card.count(), { + timeout: 20_000, message: 'the More list kept the card after its rows stopped', + }).toBe(0) + expect(consoleWatch.pageErrors).toEqual([]) + } finally { + await context.close() + await visibilityScaffold.close() + } + }, 120_000) + it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => { expect(tripwire.warnings).toEqual([]) await assertFixtureInventory(SNAPSHOT_DIR, [ diff --git a/apps/web/tests/plugin-market-toolbar.e2e.ts b/apps/web/tests/plugin-market-toolbar.e2e.ts new file mode 100644 index 0000000000..39f3c8ae52 --- /dev/null +++ b/apps/web/tests/plugin-market-toolbar.e2e.ts @@ -0,0 +1,134 @@ +/** Keyless browser geometry for the Discover toolbar against a local plugin index. */ +import { once } from 'node:events' +import { readFile } from 'node:fs/promises' +import { createServer } from 'node:http' +import { fileURLToPath } from 'node:url' +import { chromium, type Locator } from 'playwright' +import { expect, it } from 'vitest' +import type {} from '@deepseek-ai/dsh-plugin-market' +import { compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode } from './scaffold.ts' +import { ZH_BROWSER_LOCALE } from './support.ts' + +const EXPECTED = fileURLToPath(new URL('./expected/plugin-market/toolbar-responsive.expected.md', import.meta.url)) +const INDEX = new URL('./fixtures/plugin-market/toolbar.index.json', import.meta.url) + +/** Read live control geometry, including the index button's intentional left outset. */ +async function measure(toolbar: Locator) { + return toolbar.evaluate((element) => { + const bounds = element.getBoundingClientRect() + const panel = element.closest('[data-plugin-panel]')!.getBoundingClientRect() + const controls = Array.from(element.querySelectorAll('button, input')) + const rects = controls.map(control => control.getBoundingClientRect()) + const contained = rects.every((rect, index) => { + // The index button uses an 8px left outset to align its text with the page content. + const left = index === 0 ? bounds.left - 8 : bounds.left + return rect.left >= left - 1 && rect.right <= bounds.right + 1 + && rect.left >= panel.left && rect.right <= panel.right + && rect.left >= 0 && rect.right <= innerWidth && rect.top >= 0 && rect.bottom <= innerHeight + }) + const reachable = controls.every((control, index) => { + const rect = rects[index]! + const hit = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2) + return rect.width > 0 && rect.height > 0 && (hit === control || control.contains(hit)) + }) + const separated = rects.every((rect, index) => rects.slice(index + 1).every(other => + rect.right <= other.left || other.right <= rect.left || rect.bottom <= other.top || other.bottom <= rect.top)) + const centers = rects.map(rect => rect.top + rect.height / 2) + return { + controls: controls.length, + contained, + reachable, + separated, + overflow: element.scrollWidth > element.clientWidth, + pageOverflow: document.documentElement.scrollWidth > document.documentElement.clientWidth, + singleLine: Math.max(...centers) - Math.min(...centers) < 1, + focused: document.activeElement === element.querySelector('input'), + } + }) +} + +/** Every toolbar action remains visible, reachable, and separate without losing the search focus. */ +function validLayout(layout: Awaited>): boolean { + return layout.controls === 5 && layout.contained && layout.reachable && layout.separated + && !layout.overflow && !layout.pageOverflow && layout.focused +} + +it('keeps Discover controls reachable when the toolbar wraps and retains search focus across widths', async () => { + const body = await readFile(INDEX) + const source = createServer((request, response) => { + if (request.url !== '/index.json') { + response.writeHead(404).end() + return + } + response.writeHead(200, { 'content-type': 'application/json' }).end(body) + }) + source.listen(0, '127.0.0.1') + try { + await once(source, 'listening') + const address = source.address() + if (address === null || typeof address === 'string') throw new Error('The plugin index fixture has no TCP port') + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + profile: { packages: [], bundles: ['@deepseek-ai/dsh-experimental-plugin-market-bundle'] }, + }) + try { + await scaffold.ctx.pluginMarket.setIndexes([`http://127.0.0.1:${address.port}/index.json`]) + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 1280, height: 844 }, locale: ZH_BROWSER_LOCALE, reducedMotion: 'reduce' }) + const consoleWatch = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.getByRole('button', { name: '插件', exact: true }).click() + await page.getByRole('tab', { name: '发现', exact: true }).click() + await page.locator('[data-market-entry="dsh-toolbar-layout-fixture"]').waitFor() + await page.getByRole('button', { name: '收起侧边栏', exact: true }).click() + await page.evaluate(() => document.fonts.ready) + const toolbar = page.locator('[data-discover-toolbar]') + const search = toolbar.getByRole('searchbox', { name: '搜索插件' }) + await search.focus() + const facts: string[] = [] + for (const width of [390, 430, 768, 1280]) { + await page.setViewportSize({ width, height: 844 }) + await expect.poll(async () => { + const layout = await measure(toolbar) + return validLayout(layout) && layout.singleLine === (width >= 768) ? true : layout + }, { message: `Discover toolbar at ${width}px` }).toBe(true) + facts.push(`- ${width}px: ${width >= 768 ? 'single row' : 'wrapped rows'}; index, search, labels, sort, and refresh are contained, reachable, and separate; no horizontal overflow; search focus retained.`) + } + await page.setViewportSize({ width: 390, height: 844 }) + await expect.poll(async () => validLayout(await measure(toolbar))).toBe(true) + const previous = await toolbar.evaluate((element) => { + const previous = { value: element.style.getPropertyValue('flex-wrap'), priority: element.style.getPropertyPriority('flex-wrap') } + element.style.setProperty('flex-wrap', 'nowrap') + return previous + }) + try { + const noWrap = await measure(toolbar) + expect(noWrap.overflow).toBe(true) + expect(validLayout(noWrap)).toBe(false) + } finally { + await toolbar.evaluate((element, previous) => { + if (previous.value === '') element.style.removeProperty('flex-wrap') + else element.style.setProperty('flex-wrap', previous.value, previous.priority) + }, previous) + } + await expect.poll(async () => validLayout(await measure(toolbar))).toBe(true) + expect(consoleWatch.pageErrors).toEqual([]) + await compareOrRefreshGolden(EXPECTED, + `# Discover toolbar responsive layout\n\n${facts.join('\n')}\n\nAt 390px, restoring the previous no-wrap layout causes horizontal overflow and fails the same layout check. Removing that override restores the controls and preserves search focus.`, + webSnapshotMode()) + } finally { + await browser.close() + } + } finally { + await scaffold.close() + } + } finally { + await new Promise((resolve, reject) => { + source.close((error) => { + if (error === undefined) resolve() + else reject(error) + }) + }) + } +}) diff --git a/apps/web/tests/plugin-sticky-motion.e2e.ts b/apps/web/tests/plugin-sticky-motion.e2e.ts index ada88dbe66..86fecc4656 100644 --- a/apps/web/tests/plugin-sticky-motion.e2e.ts +++ b/apps/web/tests/plugin-sticky-motion.e2e.ts @@ -83,8 +83,8 @@ it('preserves both header layouts and follows the scroll position without changi await page.locator('[data-plugin-bar][data-natural]').waitFor() await page.evaluate(() => document.fonts.ready) // Without tabs, whether the actions fit beside the title at 470px depends on the platform font, - // so that width is pinned only with tabs. - for (const width of hasTabs ? [1280, 600, 470, 390] : [1280, 600, 390]) { + // so that width is pinned only with tabs. At 320px the tabs and actions wrap onto separate rows. + for (const width of hasTabs ? [1280, 600, 470, 390, 320] : [1280, 600, 390]) { await page.setViewportSize({ width, height: 480 }) await scrollTo(page, 0) const resting = await reference(page, false) @@ -95,7 +95,7 @@ it('preserves both header layouts and follows the scroll position without changi expect(initial.tabs).toEqual(resting.tabs) if (hasTabs && width <= 600) { const tabs = initial.tabs! - if (width === 390) { + if (width === 320) { expect(initial.toolbar.y).toBeGreaterThanOrEqual(tabs.y + tabs.height) } else { expect(initial.toolbar.x).toBeGreaterThanOrEqual(tabs.x + tabs.width) diff --git a/apps/web/tests/present-svg.e2e.ts b/apps/web/tests/present-svg.e2e.ts index cc698a8186..0e9f2da75c 100644 --- a/apps/web/tests/present-svg.e2e.ts +++ b/apps/web/tests/present-svg.e2e.ts @@ -2,9 +2,11 @@ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join, resolve } from 'node:path' +import { monitorEventLoopDelay } from 'node:perf_hooks' import { fileURLToPath } from 'node:url' import { chromium, type Browser, type Page } from 'playwright' -import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest' +import WebSocket from 'ws' import type {} from '@deepseek-ai/dsh-tool-present/types' import { deriveReplayScript, parseSessionLog } from '@deepseek-ai/dsh-llm-replay' import { @@ -20,6 +22,18 @@ const MODE = webSnapshotMode() const RECORD_PROMPT = '简单画一个 SVG 表示冯诺依曼架构，保存为 von-neumann.svg，并提供独立文件卡片，方便打开。' const FILE = 'von-neumann.svg' +/** Queue counters from the installed ws implementation; payload contents are never recorded. */ +type DiagnosticSocket = WebSocket & { + readonly _sender?: { readonly _state: number; readonly _bufferedBytes: number; readonly _queue: readonly unknown[] } + readonly _receiver?: { readonly _state: number; readonly _bufferedBytes: number } + readonly _socket?: { + readonly bytesRead: number + readonly bytesWritten: number + readonly readableLength: number + readonly writableLength: number + } +} + describe('web e2e: requested SVG is explicitly delivered', () => { let scaffold: WebScaffold let browser: Browser @@ -27,9 +41,40 @@ describe('web e2e: requested SVG is explicitly delivered', () => { let tripwire: ReturnType let cwd: string let replayRoot: string | undefined + let restoreTransportDiagnostics: (() => void) | undefined const connectionDiagnostics: string[] = [] beforeAll(async () => { + const loopDelay = monitorEventLoopDelay({ resolution: 20 }) + loopDelay.enable() + const ping = vi.spyOn(WebSocket.prototype, 'ping') + const terminated = vi.spyOn(WebSocket.prototype, 'terminate').mockImplementation(function (this: WebSocket) { + const socket = this as DiagnosticSocket + connectionDiagnostics.push(`Host termination: ${JSON.stringify({ + readyState: socket.readyState, + bufferedBytes: socket.bufferedAmount, + pingCalls: ping.mock.contexts.filter(context => context === socket).length, + senderState: socket._sender?._state, + senderBufferedBytes: socket._sender?._bufferedBytes, + senderQueueLength: socket._sender?._queue.length, + receiverState: socket._receiver?._state, + receiverBufferedBytes: socket._receiver?._bufferedBytes, + bytesRead: socket._socket?.bytesRead, + bytesWritten: socket._socket?.bytesWritten, + readableLength: socket._socket?.readableLength, + writableLength: socket._socket?.writableLength, + maxEventLoopDelayMs: loopDelay.max / 1e6, + p99EventLoopDelayMs: loopDelay.percentile(99) / 1e6, + })}`) + connectionDiagnostics.push(new Error('Host WebSocket termination').stack ?? 'Host WebSocket termination') + terminated.mockRestore() + this.terminate() + }) + restoreTransportDiagnostics = () => { + terminated.mockRestore() + ping.mockRestore() + loopDelay.disable() + } let replayOverride: string | undefined if (MODE !== 'record') { replayRoot = await mkdtemp(join(tmpdir(), 'dsh-present-svg-replay-')) @@ -42,7 +87,8 @@ describe('web e2e: requested SVG is explicitly delivered', () => { scaffold = await launchWebScaffold({ compareReplaySession: true, extraOverlayPath: fileURLToPath(new URL('./present-svg.overlay.yml', import.meta.url)), - ...(replayOverride === undefined ? {} : { replayFixture: FIXTURE, replayOverride }), + // Replay the large SVG incrementally to avoid a zero-delay traffic burst. + ...(replayOverride === undefined ? {} : { replayFixture: FIXTURE, replayOverride, paceMs: 5 }), }) browser = await chromium.launch() page = await browser.newPage({ @@ -53,6 +99,7 @@ describe('web e2e: requested SVG is explicitly delivered', () => { if (message.text().startsWith('[connection]')) connectionDiagnostics.push(message.text()) }) page.on('websocket', (socket) => { + loopDelay.reset() const openedAt = Date.now() let received = 0 socket.on('framereceived', () => { received++ }) @@ -67,6 +114,7 @@ describe('web e2e: requested SVG is explicitly delivered', () => { }) afterAll(async () => { + restoreTransportDiagnostics?.() try { await browser?.close() } finally { diff --git a/apps/web/tests/present.e2e.ts b/apps/web/tests/present.e2e.ts index 6a9a790de7..c8d4abc172 100644 --- a/apps/web/tests/present.e2e.ts +++ b/apps/web/tests/present.e2e.ts @@ -164,6 +164,8 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con const revealResponse = page.waitForResponse(response => response.url().includes('action=reveal') && response.request().method() === 'POST') await page.getByRole('menuitem', { name: 'Show file location', exact: true }).click() expect((await revealResponse).status()).toBe(204) + await page.waitForFunction(() => document.querySelector('[data-presented-files-row] button:disabled') === null) + expect(await page.getByRole('alert').count()).toBe(0) await expect.poll(opened).toHaveLength(beforeReveal + 1) expect((await opened()).at(-1)).toEqual({ action: 'reveal', content: null, path: await realpath(process.platform === 'darwin' ? join(cwd, 'report.txt') : cwd) }) for (const [name, bytes] of [['report.txt', 'EDITED_REPORT\n'], ['说明.txt', 'EDITED_NOTE\n']] as const) { @@ -172,34 +174,11 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con await row.locator('[data-presented-file]').filter({ hasText: name }).getByRole('button', { name: 'Open in Test Editor', exact: true }).click() expect((await response).status()).toBe(204) await page.waitForFunction(() => document.querySelector('[data-presented-files-row] button:disabled') === null) + expect(await page.getByRole('alert').count()).toBe(0) + expect(await row.locator('[data-presented-file] [role="status"]').count()).toBe(0) expect(await opened()).toHaveLength(count + 1) expect((await opened()).at(-1)).toEqual({ action: 'open', path: await realpath(join(cwd, name)), content: bytes }) } - const success = row.locator('[data-presented-file]').filter({ hasText: '说明.txt' }).locator('[data-success]') - await success.waitFor() - const animation = await success.evaluate((element) => { - const style = getComputedStyle(element) - const fade = element.getAnimations()[0] - if (fade === undefined) throw new Error('Successful file feedback has no fade animation') - // Seek the CSS animation so the 200 ms fade does not race the assertion. - fade.pause() - fade.currentTime = 5100 - return { - delay: style.animationDelay, duration: style.animationDuration, - fill: style.animationFillMode, opacity: Number(getComputedStyle(element).opacity), - } - }) - expect(animation.delay).toBe('5s') - expect(animation.duration).toBe('0.2s') - expect(animation.fill).toBe('forwards') - expect(animation.opacity).toBeGreaterThan(0) - expect(animation.opacity).toBeLessThan(1) - try { - await page.emulateMedia({ reducedMotion: 'reduce' }) - expect(await success.evaluate(element => getComputedStyle(element).animationName)).toBe('none') - } finally { - await page.emulateMedia({ reducedMotion: 'no-preference' }) - } } expect(downloads).toEqual([]) const response = await page.request.get(new URL(`/api/session.export?sessionId=${sessionId}`, scaffold.authenticatedUrl).href) @@ -318,4 +297,64 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) }) + + it('announces mobile native opens and reveals on another device, and reports a deleted file', async () => { + const context = await browser.newContext({ + storageState: await page.context().storageState(), + userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) AppleWebKit/605.1.15 Version/18.6 Mobile/15E148 Safari/604.1', + viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true, locale: 'en-US', timezoneId: 'Asia/Shanghai', + }) + try { + const phone = await context.newPage() + const consoleWatch = watchConsole(phone) + const phoneDownloads: string[] = [] + phone.on('download', (download) => { phoneDownloads.push(download.suggestedFilename()) }) + await phone.goto(page.url(), { waitUntil: 'load' }) + await phone.getByText(/^PRESENT_DONE\.?$/).waitFor({ timeout: 30_000 }) + const card = phone.locator('[data-presented-file]').filter({ hasText: '说明.txt' }) + const open = card.getByRole('button', { name: 'Open in Test Editor', exact: true }) + await open.waitFor() + const notices: string[] = [] + const beforeOpen = (await opened()).length + const openResponse = phone.waitForResponse(response => response.url().includes('/api/present.open?') && response.request().method() === 'POST') + await open.tap() + expect((await openResponse).status()).toBe(204) + const success = phone.getByRole('alert').filter({ hasText: 'Opened on another device' }) + await success.waitFor() + notices.push(`## Open\n\n${await success.ariaSnapshot()}`) + await expect.poll(opened).toHaveLength(beforeOpen + 1) + expect((await opened()).at(-1)).toEqual({ action: 'open', path: await realpath(join(cwd, '说明.txt')), content: 'EDITED_NOTE\n' }) + expect(await card.locator('[role="status"]').count()).toBe(0) + const bounds = await success.boundingBox() + expect(bounds).not.toBeNull() + expect(bounds!.x).toBeGreaterThanOrEqual(0) + expect(bounds!.x + bounds!.width).toBeLessThanOrEqual(390) + + await card.getByRole('button', { name: 'More ways to open', exact: true }).tap() + const revealResponse = phone.waitForResponse(response => response.url().includes('action=reveal') && response.request().method() === 'POST') + await phone.getByRole('menuitem', { name: 'Show file location', exact: true }).tap() + expect((await revealResponse).status()).toBe(204) + const revealed = phone.getByRole('alert').filter({ hasText: 'File location shown on another device' }) + await revealed.waitFor() + notices.push(`## Show file location\n\n${await revealed.ariaSnapshot()}`) + await expect.poll(opened).toHaveLength(beforeOpen + 2) + expect((await opened()).at(-1)).toEqual({ action: 'reveal', content: null, path: await realpath(process.platform === 'darwin' ? join(cwd, '说明.txt') : cwd) }) + + await unlink(join(cwd, '说明.txt')) + const missingResponse = phone.waitForResponse(response => response.url().includes('/api/present.open?') && response.request().method() === 'POST') + await open.tap() + expect((await missingResponse).status()).toBe(404) + const failure = phone.getByRole('alert').filter({ hasText: 'Could not open. Try again.' }) + await failure.waitFor() + notices.push(`## Missing file\n\n${await failure.ariaSnapshot()}`) + await card.getByText('Could not open. Click to retry.', { exact: true }).waitFor() + expect(await opened()).toHaveLength(beforeOpen + 2) + expect(phoneDownloads).toEqual([]) + await compareOrRefreshGolden(join(DIR, 'mobile-open.expected.md'), notices.join('\n\n'), MODE) + expect(consoleWatch.pageErrors).toEqual([]) + expect(consoleWatch.warnings).toEqual([]) + } finally { + await context.close() + } + }) }) diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts index 4173379bfd..cf2aac31b8 100644 --- a/apps/web/tests/preset-migration.snapshot.ts +++ b/apps/web/tests/preset-migration.snapshot.ts @@ -88,11 +88,11 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' }) const signal = new AbortController().signal const address = { kind: 'subagent', parentSessionId: id, childSessionId: childId, mode: 'one-shot' } as const - const childPage = await scaffold.ctx.sessionController.page({ address, throughSeq: childRows.length - 1 }, signal) + const childPage = await scaffold.ctx.sessionController.events({ address, throughSeq: childRows.length - 1 }, signal) expect(childPage.records.map(record => record.event.type)).toEqual(childRows.map(row => row['type'])) - await expect(scaffold.ctx.sessionController.page({ address: { ...address, childSessionId: brokenId, mode: 'unknown' }, throughSeq: 1 }, signal)) + await expect(scaffold.ctx.sessionController.events({ address: { ...address, childSessionId: brokenId, mode: 'unknown' }, throughSeq: 1 }, signal)) .rejects.toThrow() - await expect(scaffold.ctx.sessionController.page({ address: { kind: 'session', sessionId: id }, throughSeq: rows.length - 1 }, signal)) + await expect(scaffold.ctx.sessionController.events({ address: { kind: 'session', sessionId: id }, throughSeq: rows.length - 1 }, signal)) .resolves.toMatchObject({ hasMore: false }) const childWriter = await scaffold.ctx.sessionPersistence.open(childId, 'write') await childWriter.close() diff --git a/apps/web/tests/preview-boot.e2e.ts b/apps/web/tests/preview-boot.e2e.ts index daa7944c36..3cf7695139 100644 --- a/apps/web/tests/preview-boot.e2e.ts +++ b/apps/web/tests/preview-boot.e2e.ts @@ -672,7 +672,11 @@ async function toggleOptionalBundles(page: Page): Promise { inactive: string[] restored: boolean }> = [] - for (const entry of bundles.filter(candidate => candidate.optional)) { + // The packed worker composition cannot mount the Liveshare declaration row and its share host in + // the same patch batch without racing the declaration service; the ordinary Web scaffold covers + // that bundle's enable/disable path (plugin-manager.e2e.ts), so the packed toggle list skips it. + for (const entry of bundles.filter(candidate => candidate.optional + && candidate.name !== '@deepseek-ai/dsh-experimental-liveshare')) { const enable = await remote<{ application: string; error?: unknown }>('pluginManager/setBundleEnabled', { name: entry.name, enabled: true }) const plugins = await remote('pluginManager/listPlugins', {}) const disable = await remote<{ application: string }>('pluginManager/setBundleEnabled', { name: entry.name, enabled: false }) @@ -690,6 +694,7 @@ async function toggleOptionalBundles(page: Page): Promise { }) } return { + cua: bundles.filter(entry => entry.name === '@deepseek-ai/dsh-cua-bundle'), optional: bundles.filter(entry => entry.optional).map(entry => ({ name: entry.name, enabled: entry.enabled, availability: entry.availability, error: entry.error ?? null, title: typeof entry.meta?.title, icon: typeof entry.meta?.icon, metaError: entry.meta?.error ?? null, @@ -701,18 +706,16 @@ async function toggleOptionalBundles(page: Page): Promise { }) expect(result.optional.map(entry => entry.name).sort()).toEqual([...OPTIONAL_BUNDLES].sort()) expect(result.optional.filter(entry => entry.enabled || entry.availability !== 'installation')).toEqual([]) - expect(result.optional.filter(entry => entry.error !== null)).toEqual([ - expect.objectContaining({ name: '@deepseek-ai/dsh-cua-bundle', error: { code: 'unsupported-platform' } }), - ]) + expect(result.optional.filter(entry => entry.error !== null)).toEqual([]) + expect(result.cua).toHaveLength(1) + expect(result.cua[0]).toMatchObject({ name: '@deepseek-ai/dsh-cua-bundle', optional: false, + availability: 'missing', error: { code: 'unsupported-platform' } }) // Metadata resolves through the Worker's Node internal modules: every optional bundle shows its title and icon. expect(result.optional.filter(entry => entry.metaError !== null || entry.title !== 'object' || entry.icon !== 'string')).toEqual([]) expect(result.inventoryErrors).toEqual([]) console.info(`preview boot: optional bundle toggles ${JSON.stringify(result.toggles.map(({ name, enable, disable, error }) => ({ name, enable, disable, error })))}`) - expect(result.toggles.find(toggle => toggle.name === '@deepseek-ai/dsh-cua-bundle')).toMatchObject({ - enable: 'failed', disable: 'applied', error: { code: 'unsupported-platform' }, - changed: 0, inactive: [], restored: true, - }) - const supported = result.toggles.filter(toggle => toggle.name !== '@deepseek-ai/dsh-cua-bundle') + expect(result.toggles.find(toggle => toggle.name === '@deepseek-ai/dsh-cua-bundle')).toBeUndefined() + const supported = result.toggles expect(supported.filter(toggle => toggle.enable !== 'applied' || toggle.disable !== 'applied') .map(({ name, enable, disable }) => ({ name, enable, disable }))).toEqual([]) // Each bundle changes Loader rows, every enabled row it changes runs, and switching it off restores the prior rows. diff --git a/apps/web/tests/prompt-admission.e2e.ts b/apps/web/tests/prompt-admission.e2e.ts new file mode 100644 index 0000000000..7a7b104f65 --- /dev/null +++ b/apps/web/tests/prompt-admission.e2e.ts @@ -0,0 +1,75 @@ +// Keyless browser coverage for Host acceptance through the shipped Web +// composition and the real wire: while the prompt request of a sent message is +// held, the composer stays read-only behind the sending control and Chat shows +// no echo; once the Host accepts the prompt the composer clears and takes the +// keyboard back. queue-actions covers a refused prompt keeping its draft. +import { fileURLToPath } from 'node:url' +import type { Browser, Route } from 'playwright' +import { chromium } from 'playwright' +import { afterEach, describe, expect, it, onTestFailed } from 'vitest' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import { launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold } from './scaffold.ts' +import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts' + +const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/live-interactions/session.v3.jsonl', import.meta.url)) +const MODE = webSnapshotMode() + +const HELD = 'Message held until the Host accepts it' +const FOLLOW_UP = 'Typed once the message was accepted' + +describe('web e2e: prompt admission', () => { + let scaffold: WebScaffold | undefined + let browser: Browser | undefined + + afterEach(async () => { + const failures: unknown[] = [] + await browser?.close().catch((error: unknown) => failures.push(error)) + browser = undefined + const closing = scaffold + scaffold = undefined + await closing?.close().catch((error: unknown) => failures.push(error)) + if (failures.length === 1) throw failures[0] + if (failures.length > 1) throw new AggregateError(failures, 'prompt-admission teardown failed') + }) + + it.skipIf(MODE === 'record')('holds a message in the read-only composer until the Host accepts it', async () => { + const sessionEvents: SessionEvent[] = [] + scaffold = await launchWebScaffold({ replayFixture: FIXTURE, compareReplaySession: false }) + const host = scaffold + host.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) }) + const userMessages = (): number => sessionEvents + .filter(event => event.type === 'user/message' && event.data.source.kind === 'user').length + browser = await chromium.launch() + const page = await newEnglishPage(browser) + const tripwire = watchConsole(page) + await page.goto(host.authenticatedUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + await connectFreshWorkspace(page, host.workspaceCwd) + onTestFailed(() => saveFailureShot(page, 'web-e2e-prompt-admission')) + const input = page.locator('[data-composer-input]').first() + + const held = Promise.withResolvers() + await page.route('**/api/session/prompt', (route) => { held.resolve(route) }, { times: 1 }) + await input.fill(HELD) + await input.press('Enter') + const prompt = await held.promise + const sending = page.getByRole('button', { name: 'Sending message', exact: true }) + await expect.poll(() => sending.getAttribute('aria-busy')).toBe('true') + expect(await input.getAttribute('contenteditable')).toBe('false') + expect(await input.textContent()).toBe(HELD) + expect(await page.locator('[data-submission-echo]').count()).toBe(0) + expect(userMessages()).toBe(0) + + const settled = host.whenTurnSettled() + await prompt.continue() + await settled + await expect.poll(() => input.textContent()).toBe('') + expect(await input.getAttribute('contenteditable')).toBe('true') + // The keyboard returns to the composer, so the next message can be typed at once. + await page.keyboard.type(FOLLOW_UP) + await expect.poll(() => input.textContent()).toBe(FOLLOW_UP) + await page.locator('[data-chat-flow-kind="user"]', { hasText: HELD }).waitFor() + expect(userMessages()).toBe(1) + expect(tripwire.pageErrors).toEqual([]) + }) +}) diff --git a/apps/web/tests/question-composer-recommended.e2e.ts b/apps/web/tests/question-composer-recommended.e2e.ts new file mode 100644 index 0000000000..96ebc2c15a --- /dev/null +++ b/apps/web/tests/question-composer-recommended.e2e.ts @@ -0,0 +1,92 @@ +/** A multi-select question opens with every option marked as recommended already chosen, wherever it sits in the list. */ +import { readFile } from 'node:fs/promises' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { chromium, type Browser, type Page } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import { + assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, + launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { + connectFreshWorkspace, newEnglishPage, pinBrowserClock, pinHostClock, saveFailureShot, +} from './support.ts' + +const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/question-composer-recommended', import.meta.url)) +const FIXTURE = join(SNAPSHOT_DIR, 'session.v4.jsonl') +const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md') +const MODE = webSnapshotMode() + +const PROMPT = 'Use the ask_user_question tool to ask me exactly one multi-select question with id "checks", question "Which checks should run before merging?", header "Checks", and three options in this order: label "Unit tests (Recommended)", label "Full e2e suite", and label "Type check (Recommended)". Set multi_select to true. After I answer, reply with the single word DONE and stop.' + +describe('web e2e: recommended multi-select options', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + const sessionEvents: SessionEvent[] = [] + let hostClock: ReturnType | undefined + + beforeAll(async () => { + if (MODE !== 'record') hostClock = pinHostClock() + scaffold = await launchWebScaffold(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 15, compareReplaySession: true }) + scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) }) + browser = await chromium.launch() + page = await newEnglishPage(browser) + if (MODE !== 'record') await pinBrowserClock(page) + tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + await connectFreshWorkspace(page, scaffold.workspaceCwd) + }, 120_000) + + afterAll(async () => { + try { + await browser?.close() + } finally { + try { await scaffold?.close() } + finally { hostClock?.mockRestore() } + } + }) + + it('preselects every recommended option and submits them unchanged', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-question-recommended')) + if (MODE !== 'record') { + expect(fixtureUserPrompts(await readFile(FIXTURE, 'utf8'))).toEqual([PROMPT]) + } + const input = page.locator('[data-composer-input]').first() + await input.waitFor({ timeout: 10_000 }) + const settled = scaffold.whenTurnSettled(MODE === 'record' ? 180_000 : 30_000) + await input.fill(PROMPT) + await input.press('Enter') + + const composer = page.locator('[data-question-key]') + await composer.waitFor({ timeout: MODE === 'record' ? 120_000 : 30_000 }) + await composer.getByRole('heading', { name: 'Which checks should run before merging?' }).waitFor({ timeout: 10_000 }) + const checked = await composer.getByRole('checkbox').evaluateAll(nodes => + nodes.map(node => node.getAttribute('aria-checked'))) + expect(checked).toEqual(['true', 'false', 'true']) + if (MODE !== 'record') { + const snapshot = await captureStableAria(page, '[data-question-key]', scaffold.workspaceCwd) + await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE) + } + + await composer.getByRole('button', { name: 'Submit', exact: true }).click() + const sessionId = await settled + if (MODE === 'record') { + await recordFixture(scaffold, sessionId, FIXTURE) + return + } + const answerText = sessionEvents.filter(event => event.type === 'tool/result') + .flatMap(event => event.data.message.content.filter(item => item.type === 'text').map(item => item.text)) + .at(-1) + expect(JSON.parse(answerText ?? '')).toEqual({ + answers: [{ id: 'checks', selected: ['Unit tests (Recommended)', 'Type check (Recommended)'] }], + }) + await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + await assertFixtureInventory(SNAPSHOT_DIR, ['session.v4.jsonl', 'ui.expected.md']) + }, 200_000) +}) diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts index d6e619ef01..fb7c805388 100644 --- a/apps/web/tests/queue-actions.e2e.ts +++ b/apps/web/tests/queue-actions.e2e.ts @@ -124,21 +124,15 @@ describe('web e2e: queue row actions', () => { await input.fill(REMOVE) await input.press('Enter') await received.promise - const pending = page.locator('[data-queue-dock] [data-submission-echo]') - await pending.getByRole('status').waitFor() - expect(await pending.getByRole('status').textContent()).toBe('Sending…') - expect(await pending.getByRole('button').count()).toBe(3) - expect(await pending.getByRole('button').evaluateAll(buttons => - buttons.every(button => (button as HTMLButtonElement).disabled))).toBe(true) - expect(await input.textContent()).toBe('') - expect(await input.getAttribute('contenteditable')).toBe('true') + // The composer keeps the message, read-only, until the Host accepts it; the queue shows nothing yet. + const sendingButton = page.getByRole('button', { name: 'Sending message', exact: true }) + await sendingButton.waitFor() + expect(await sendingButton.getAttribute('aria-busy')).toBe('true') + expect(await input.textContent()).toBe(REMOVE) + expect(await input.getAttribute('contenteditable')).toBe('false') + expect(await page.locator('[data-queue-dock] [data-submission-echo]').count()).toBe(0) const sending = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) await compareOrRefreshGolden(SENDING_EXPECTED, sending, MODE) - await page.setViewportSize({ width: 390, height: 1000 }) - await page.locator('[data-sidebar-collapsed="true"]').waitFor() - await expect.poll(() => pending.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true) - await page.setViewportSize({ width: 1680, height: 1000 }) - await page.locator('[data-sidebar-collapsed="true"]').waitFor({ state: 'detached' }) } finally { release.resolve(undefined) } @@ -148,6 +142,8 @@ describe('web e2e: queue row actions', () => { expect(await page.locator('[data-queue-dock]').getByRole('status').count()).toBe(0) await input.fill(EDIT) await input.press('Enter') + // The Host queue row can arrive before the prompt reply that clears the composer. + await expect.poll(() => input.textContent(), { timeout: 10_000 }).toBe('') const queueHeader = page.getByRole('button', { name: '2 queued messages' }) await expect.poll(() => queueHeader.getAttribute('aria-expanded'), { timeout: 10_000 }) .toBe('false') @@ -365,10 +361,11 @@ describe('web e2e: queue row actions', () => { await page.locator('[data-testid="todo-panel"]').waitFor({ timeout: 10_000 }) for (const text of ['Layout queue first', 'Layout queue second']) { - // A just-submitted composer is read-only for the prompt round-trip. await page.locator('[data-composer-input][contenteditable="true"]').first().waitFor({ timeout: 10_000 }) await input.fill(text) await input.press('Enter') + // The composer keeps a sent message, still editable, until the Host accepts it. + await expect.poll(() => input.textContent(), { timeout: 10_000 }).toBe('') } const queueHeader = page.getByRole('button', { name: '2 queued messages' }) await expect.poll(() => queueHeader.getAttribute('aria-expanded'), { timeout: 10_000 }) diff --git a/apps/web/tests/queue-image.e2e.ts b/apps/web/tests/queue-image.e2e.ts index fa6fe753a0..bfea309698 100644 --- a/apps/web/tests/queue-image.e2e.ts +++ b/apps/web/tests/queue-image.e2e.ts @@ -96,7 +96,8 @@ describe('web e2e: queued image submission', () => { await input.press('Enter') await expect.poll(() => existsSync(readyFile), { timeout: 15_000 }).toBe(true) - // A just-submitted composer is read-only for the prompt round-trip. + // The composer keeps the sent prompt, still editable, until the Host accepts it. + await expect.poll(() => input.textContent(), { timeout: 10_000 }).toBe('') await page.locator('[data-composer-input][contenteditable="true"]').first().waitFor({ timeout: 10_000 }) await pasteImage(page, await readFile(PNG)) await page.getByRole('img', { name: 'queued.png' }).waitFor({ timeout: 10_000 }) @@ -126,17 +127,20 @@ describe('web e2e: queued image submission', () => { try { await input.fill(QUEUED_TEXT) await input.press('Enter') - await dockThumb.waitFor({ timeout: 15_000 }) - await expect.poll(() => dockThumb.getAttribute('src'), { timeout: 15_000 }).toMatch(/^blob:/) - expect(await page.locator('[data-queue-dock] [data-submission-echo]').count()).toBe(1) + // The composer keeps the text and image, read-only, until the Host accepts the prompt. + await expect.poll(() => input.getAttribute('contenteditable'), { timeout: 15_000 }).toBe('false') + expect(await page.getByRole('img', { name: 'queued.png' }).count()).toBe(1) + expect(await page.locator('[data-queue-dock] [data-submission-echo]').count()).toBe(0) releasePrompt.resolve(undefined) await expect.poll(() => imageRequested, { timeout: 15_000 }).toBe(true) - await page.getByText(QUEUED_TEXT, { exact: true }).waitFor() + // The Host queue row can arrive before the prompt reply that clears the composer. + await expect.poll(() => input.textContent(), { timeout: 15_000 }).toBe('') + await page.locator('[data-queue-dock]').getByText(QUEUED_TEXT, { exact: true }).waitFor() await page.getByRole('button', { name: 'Remove queued message', disabled: false }).waitFor({ timeout: 15_000 }) expect(await page.locator('[data-queue-dock] [data-submission-echo]').count()).toBe(0) expect(await dockThumb.count()).toBe(0) releaseImage.resolve(undefined) - // Admission replaces the optimistic image; wait for the durable row's own thumbnail. + // The Host queue row replaces the accepted echo; wait for the durable row's own thumbnail. const durableThumb = page.locator('[data-queue-dock] li:not([data-submission-echo]) img[alt="Queued message image"]') await durableThumb.waitFor({ timeout: 15_000 }) await expect.poll(() => durableThumb.getAttribute('src'), { timeout: 15_000 }).toMatch(/^blob:/) diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts index 6e7725cde6..82f436c837 100644 --- a/apps/web/tests/replay-round-trip.e2e.ts +++ b/apps/web/tests/replay-round-trip.e2e.ts @@ -131,7 +131,7 @@ describe('web e2e: fresh round trip through the real assembly', () => { key: 'Enter', code: 'Enter', bubbles: true, cancelable: true, })) // sendSession registered its paint yield first. This frame observes the - // committed echo while admission remains queued on the following task. + // composer holding the message while the Host has not accepted it yet. await new Promise((resolve) => { requestAnimationFrame(() => { resolve() }) }) const echo = document.querySelector('[data-submission-echo]') return [ @@ -145,6 +145,10 @@ describe('web e2e: fresh round trip through the real assembly', () => { expect(await response.json()).toMatchObject({ result: { ok: true, value: { accepted: true } } }) accepted = true await compareOrRefreshGolden(ECHO_EXPECTED, echoSnapshot, MODE) + // Acceptance publishes the echo and clears the composer; maintenance keeps the Turn from starting. + await page.locator('[data-submission-echo]', { hasText: PROMPT }).waitFor() + await expect.poll(() => input.textContent()).toBe('') + expect(await input.getAttribute('contenteditable')).toBe('true') const row = page.getByRole('tree', { name: 'Sessions', exact: true }) .locator('[role="treeitem"][aria-selected="true"]') await expect.poll(() => row.getAttribute('draggable'), { timeout: 5_000 }).toBe('true') diff --git a/apps/web/tests/schedule-after.e2e.ts b/apps/web/tests/schedule-after.e2e.ts index fb45d6c76a..b452ce6c5f 100644 --- a/apps/web/tests/schedule-after.e2e.ts +++ b/apps/web/tests/schedule-after.e2e.ts @@ -868,6 +868,7 @@ describe.skipIf(MODE === 'record')('web e2e: active Schedule catalog', () => { await page.getByRole('menuitem', { name: 'Delete task', exact: true }).click() const confirmation = page.getByRole('dialog', { name: 'Delete this task?' }) await confirmation.getByRole('button', { name: 'Cancel', exact: true }).click() + expect(await moreActions.evaluate(button => button === document.activeElement)).toBe(true) expect((await scaffold.ctx.schedule.catalog()).some(task => task.id === other.id)).toBe(true) await moreActions.click() await page.getByRole('menuitem', { name: 'Delete task', exact: true }).click() diff --git a/apps/web/tests/schedule-header.e2e.ts b/apps/web/tests/schedule-header.e2e.ts index fc79fd571c..631fa3e464 100644 --- a/apps/web/tests/schedule-header.e2e.ts +++ b/apps/web/tests/schedule-header.e2e.ts @@ -58,10 +58,8 @@ it('keeps the automation title intact before moving New to another line', async facts.push(`${language} ${width}px: title and New single-line, New beside the title; contained; New retains focus`) } if (language === 'en') { - // 509px collapses the left sidebar to its rail; expanding it leaves the - // page column narrow enough (measured 172px) to force the wrap. - await page.setViewportSize({ width: 509, height: 1000 }) - await page.getByRole('button', { name: 'Open sidebar', exact: true }).first().click() + // Constrain this page independently of the shell's drawer breakpoint. + await header.evaluate((element) => { element.style.width = '220px' }) await expect.poll(() => header.evaluate((element) => { const title = element.querySelector('h1')! const button = element.querySelector('button')! @@ -76,7 +74,7 @@ it('keeps the automation title intact before moving New to another line', async : buttonRect.top >= titleRect.bottom - 1 ? 'below' as const : 'overlapping' as const, } })).toEqual({ titleSingleLine: true, placement: 'below' }) - facts.push('en 509px with sidebar expanded: title single-line; New moves below the title') + facts.push('en 220px page column: title single-line; New moves below the title') } expect(consoleWatch.pageErrors).toEqual([]) } finally { diff --git a/apps/web/tests/schedule-phone.e2e.ts b/apps/web/tests/schedule-phone.e2e.ts index b28049ba3d..e82104196a 100644 --- a/apps/web/tests/schedule-phone.e2e.ts +++ b/apps/web/tests/schedule-phone.e2e.ts @@ -7,6 +7,7 @@ import { expect, it } from 'vitest' import { SessionId } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-schedule' import { launchWebScaffold, watchConsole } from './scaffold.ts' +import { revealNavigationDrawer } from './support.ts' const PHONE_TASK_SESSION = SessionId('schedule-phone-web-e2e') const PHONE_TASK_TITLE = 'Review overdue deployment' @@ -25,6 +26,7 @@ interface ViewFacts { /** Open the Automation tasks page and return its panel. */ async function openTaskManager(page: Page, url: string): Promise { await page.goto(url, { waitUntil: 'load' }) + await revealNavigationDrawer(page, 'zh') await page.getByRole('button', { name: '自动化任务', exact: true }).click() const panel = page.getByTestId('task-manager-page') await panel.getByRole('heading', { name: '自动化任务', exact: true }).waitFor({ timeout: 30_000 }) diff --git a/apps/web/tests/search-empty-include.e2e.ts b/apps/web/tests/search-empty-include.e2e.ts new file mode 100644 index 0000000000..d14c715616 --- /dev/null +++ b/apps/web/tests/search-empty-include.e2e.ts @@ -0,0 +1,63 @@ +/** Recorded empty-include searches retain the specialized Web result cards. */ +import { readFile } from 'node:fs/promises' +import { fileURLToPath } from 'node:url' +import { chromium, type Browser, type Page } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { + assertFixtureInventory, captureStableAria, compareOrRefreshGolden, + launchWebScaffold, seedSession, selectedSessionFixture, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { expandTurnProcesses, newEnglishPage, saveFailureShot } from './support.ts' + +const ROOT = fileURLToPath(new URL('../../../snapshots', import.meta.url)) +const MODE = webSnapshotMode() + +describe.skipIf(MODE === 'record')('web e2e: search-empty-include', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + + beforeAll(async () => { + scaffold = await launchWebScaffold({}) + const fixture = await selectedSessionFixture(`${ROOT}/session/toolcall-unused-args/session.v4.jsonl`) + await seedSession(scaffold, await readFile(fixture, 'utf8'), 'search-empty-include') + browser = await chromium.launch() + page = await newEnglishPage(browser) + tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + }) + + afterAll(async () => { + try { + await browser?.close() + } finally { + await scaffold?.close() + } + }) + + it('renders both recorded searches as file-grouped matches rather than generic JSON', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-search-empty-include')) + await page.locator('[role="treeitem"]').first().click() + await page.locator('[role="treeitem"]').nth(1).click() + await page.getByText('DONE', { exact: true }).waitFor({ timeout: 15_000 }) + await expandTurnProcesses(page) + const calls = page.locator('[data-variant="search"]') + expect(await calls.count()).toBe(2) + const views: string[] = [] + for (const [index, extension] of ['.ts', '.md'].entries()) { + const call = calls.nth(index) + await call.locator('[data-expandable]').click() + const matches = call.locator('[data-search="matches"]') + await matches.waitFor() + expect(await matches.textContent()).toContain(`example${extension}`) + expect(await matches.textContent()).toContain('marker') + views.push(await captureStableAria(page, `[data-variant="search"] >> nth=${index}`, scaffold.workspaceCwd)) + } + const snapshotDir = `${ROOT}/web/search-empty-include` + await compareOrRefreshGolden(`${snapshotDir}/ui.expected.md`, views.join('\n'), MODE) + await assertFixtureInventory(snapshotDir, ['ui.expected.md']) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }) +}) diff --git a/apps/web/tests/settings-appearance.e2e.ts b/apps/web/tests/settings-appearance.e2e.ts index 8f51764f88..fa55a444df 100644 --- a/apps/web/tests/settings-appearance.e2e.ts +++ b/apps/web/tests/settings-appearance.e2e.ts @@ -1,4 +1,4 @@ -/** Built settings controls share radius and card materials across account, model, and plugin pages. */ +/** Built settings controls share materials and adapt their geometry to the viewport and pointer. */ import { fileURLToPath } from 'node:url' import { join } from 'node:path' import { chromium, type Locator } from 'playwright' @@ -23,6 +23,109 @@ function appearance(element: Locator) { }) } +function rowGeometry(control: Locator) { + return control.evaluate((node) => { + const row = node.parentElement! + const text = row.firstElementChild! + const description = text.lastElementChild!.getBoundingClientRect() + const rowBox = row.getBoundingClientRect() + const textBox = text.getBoundingClientRect() + const controlBox = node.getBoundingClientRect() + return { + widthDifference: rowBox.width - controlBox.width, + leftDifference: controlBox.left - textBox.left, + rightGap: rowBox.right - controlBox.right, + afterText: controlBox.left - textBox.right, + belowDescription: controlBox.top - description.bottom, + centerDifference: (controlBox.top + controlBox.bottom - textBox.top - textBox.bottom) / 2, + height: controlBox.height, + } + }) +} + +it('stacks font fields at narrow widths while keeping font-size controls on the right', async () => { + const scaffold = await launchWebScaffold({ developerTools: false }) + onTestFinished(() => scaffold.close()) + const browser = await chromium.launch() + onTestFinished(() => browser.close()) + + for (const platform of ['web', 'darwin', 'win32'] as const) { + const context = await browser.newContext({ + viewport: { width: 390, height: 844 }, locale: ZH_BROWSER_LOCALE, hasTouch: platform === 'web', + }) + try { + const page = await context.newPage() + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await openSettings(page, 'zh') + const dialog = page.getByRole('dialog', { name: '设置', exact: true }) + await dialog.getByRole('button', { name: '更多字体设置', exact: true }).click() + await page.evaluate((platform) => { + document.documentElement.toggleAttribute('data-windows-titlebar', platform === 'win32') + if (platform === 'darwin') document.documentElement.setAttribute('data-platform', platform) + }, platform) + + for (const width of platform === 'web' ? [390, 767, 768] : [520, 767, 768]) { + await page.setViewportSize({ width, height: 844 }) + for (const name of ['正文字体', '代码字体', '终端字体']) { + const geometry = await rowGeometry(dialog.getByRole('textbox', { name, exact: true }).locator('..')) + if (width <= 767) { + expect(Math.abs(geometry.widthDifference), `${platform} ${width}px ${name} width`).toBeLessThan(1) + expect(Math.abs(geometry.leftDifference), `${platform} ${width}px ${name} alignment`).toBeLessThan(1) + expect(geometry.belowDescription, `${platform} ${width}px ${name} placement`).toBeGreaterThanOrEqual(0) + expect(geometry.height, `${platform} ${width}px ${name} height`).toBeLessThan(60) + } else { + expect(geometry.afterText, `${platform} ${width}px ${name} placement`).toBeGreaterThanOrEqual(0) + } + } + for (const name of ['增大字号', '增大代码字号', '增大终端字号']) { + const geometry = await rowGeometry(dialog.getByRole('button', { name, exact: true }).locator('../../..')) + expect(geometry.afterText, `${platform} ${width}px ${name} placement`).toBeGreaterThanOrEqual(0) + expect(Math.abs(geometry.rightGap), `${platform} ${width}px ${name} alignment`).toBeLessThan(1) + expect(Math.abs(geometry.centerDifference), `${platform} ${width}px ${name} centering`).toBeLessThan(1) + } + expect(await page.evaluate(() => document.documentElement.scrollWidth)).toBeLessThanOrEqual(width) + } + + const field = dialog.getByRole('textbox', { name: '正文字体', exact: true }) + await field.fill('Uncommitted font draft') + const original = await field.elementHandle() + for (const width of [1440, 390]) { + await page.setViewportSize({ width, height: 844 }) + expect(await original!.evaluate(input => input === document.activeElement && input.isConnected)).toBe(true) + expect(await field.inputValue()).toBe('Uncommitted font draft') + } + } finally { + await context.close() + } + } +}) + +it('uses 16px text for coarse-pointer font fields and preserves compact fine-pointer fields', async () => { + const scaffold = await launchWebScaffold({ developerTools: false }) + onTestFinished(() => scaffold.close()) + const browser = await chromium.launch() + onTestFinished(() => browser.close()) + + for (const hasTouch of [true, false]) { + const context = await browser.newContext({ viewport: { width: 390, height: 844 }, locale: ZH_BROWSER_LOCALE, hasTouch }) + try { + const page = await context.newPage() + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await openSettings(page, 'zh') + const dialog = page.getByRole('dialog', { name: '设置', exact: true }) + await dialog.getByRole('button', { name: '更多字体设置', exact: true }).click() + expect(await page.evaluate(() => matchMedia('(pointer: coarse)').matches)).toBe(hasTouch) + for (const name of ['正文字体', '代码字体', '终端字体']) { + const fontSize = await dialog.getByRole('textbox', { name, exact: true }) + .evaluate(input => getComputedStyle(input).fontSize) + expect(fontSize, name).toBe(hasTouch ? '16px' : '14px') + } + } finally { + await context.close() + } + } +}) + it('shares settings card materials and control sizes in both palettes', async () => { const scaffold = await launchWebScaffold({}) onTestFinished(() => scaffold.close()) diff --git a/apps/web/tests/shared-inspector.e2e.ts b/apps/web/tests/shared-inspector.e2e.ts index d72ff60197..ee0229ebfc 100644 --- a/apps/web/tests/shared-inspector.e2e.ts +++ b/apps/web/tests/shared-inspector.e2e.ts @@ -5,6 +5,7 @@ import { join } from 'node:path' import { chromium, type Browser } from 'playwright' import { expect, it, onTestFinished } from 'vitest' import { compareOrRefreshGolden, launchWebScaffold, seedSession, selectedSessionFixture, watchConsole, webSnapshotMode, type WebScaffold } from './scaffold.ts' +import { experimentalBundleDescription } from './support.ts' const bundle = fileURLToPath(new URL('../../../packages/experimental/inspector-profile', import.meta.url)) const fixture = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/session.v4.jsonl', import.meta.url)) @@ -87,14 +88,14 @@ it('toggles bottom DevTools from the page and iframe without a selected Session' it.each([ { locale: 'zh-CN', file: 'zh', plugins: '插件', open: '查看 开发者工具', bundle: '开发者工具', - description: '查看调试会话原始数据、聊天消息分组数据，以及调试 NodeJS 后端', + description: experimentalBundleDescription('inspector-profile', 'zh'), inspector: 'NodeJS 诊断', inspectorDescription: '按 Ctrl/Cmd+Shift+. 在底部面板打开 Chrome DevTools 进行开发调试', session: '会话数据诊断', sessionDescription: '在会话侧边栏启用当前会话的原始数据和聊天分组数据分析功能', openSidebar: '打开右侧边栏', sidebarDescription: '在侧边栏分析当前会话原始日志和聊天分组数据', }, { locale: 'en-US', file: 'en', plugins: 'Plugins', open: 'View Developer tools', bundle: 'Developer tools', - description: 'Inspect and debug raw session data, grouped chat messages, and the NodeJS backend.', + description: experimentalBundleDescription('inspector-profile', 'en'), inspector: 'NodeJS inspector', inspectorDescription: 'Press Ctrl/Cmd+Shift+. to open Chrome DevTools in the bottom panel for development and debugging.', session: 'Session log', sessionDescription: "Enable analysis of the current session's raw data and grouped chat messages in the session sidebar.", openSidebar: 'Open right sidebar', sidebarDescription: 'Analyze raw logs and grouped chat messages for the current session in the sidebar.', diff --git a/apps/web/tests/shortcuts-panels.e2e.ts b/apps/web/tests/shortcuts-panels.e2e.ts index 2036dad448..bdfe036343 100644 --- a/apps/web/tests/shortcuts-panels.e2e.ts +++ b/apps/web/tests/shortcuts-panels.e2e.ts @@ -127,10 +127,16 @@ describe.skipIf(process.platform === 'win32')('Web sidebar shortcuts', () => { const terminalEntry = panel.locator('[data-sidebar-right-guide-entry="terminal"]') const shellMenu = terminalEntry.getByRole('button', { name: 'Choose shell', exact: true }) - const titleBounds = await terminalEntry.getByText('New terminal', { exact: true }).boundingBox() - const arrowBounds = await shellMenu.boundingBox() - expect(arrowBounds!.x).toBeGreaterThanOrEqual(titleBounds!.x + titleBounds!.width) - expect(arrowBounds!.x - titleBounds!.x - titleBounds!.width).toBeLessThan(8) + // Sample both rectangles in one layout instead of crossing the panel's transition frames. + await expect.poll(() => terminalEntry.evaluate((entry) => { + const title = [...entry.querySelectorAll('span[aria-hidden="true"]')].find(element => element.textContent === 'New terminal') + const arrow = entry.querySelector('button[aria-label="Choose shell"]') + if (title === undefined || arrow === null) return null + const titleBounds = title.getBoundingClientRect() + const arrowBounds = arrow.getBoundingClientRect() + const gap = arrowBounds.left - titleBounds.right + return { ordered: gap >= 0, adjacent: gap < 8 } + })).toEqual({ ordered: true, adjacent: true }) await shellMenu.click() await page.getByRole('menu').waitFor() expect(await panel.locator('[data-sidebar-terminal]').count()).toBe(0) @@ -178,6 +184,9 @@ describe.skipIf(process.platform === 'win32')('Web sidebar shortcuts', () => { await page.keyboard.press(`${primary}+Shift+,`) expect(await panel.locator('[data-dockkit-tab]').filter({ hasText: 'Files' }).count()).toBe(1) expect(await panel.locator('[data-dockkit-pane]').evaluate(pane => document.activeElement === pane)).toBe(true) + // Once the reveal's glow has ended, the focused pane draws nothing of its own. file-browser.e2e.ts and the + // seat spec own the glow itself, so this waits for no marker rather than requiring the transient one. + await expect.poll(() => panel.locator('[data-dockkit-pane][data-sidebar-right-flash]').count()).toBe(0) expect(await paneAppearance()).toEqual([plainPane]) await bind(page, primary, 'Toggle panel fullscreen', 'Workspace files') @@ -254,12 +263,12 @@ describe.skipIf(process.platform === 'win32')('Web sidebar shortcuts', () => { await menuTab.click({ button: 'right' }) await page.getByRole('menu').waitFor() expect(await page.getByRole('tooltip').count()).toBe(0) - expect(await page.getByRole('menuitem').getAttribute('aria-keyshortcuts')).toBeNull() + expect(await page.getByRole('menuitem', { name: 'Close', exact: true }).getAttribute('aria-keyshortcuts')).toBe(aria) if (attempt === 0) { await compareOrRefreshGolden(join(expected, 'tab-menu.expected.md'), - await captureStableAria(page, '[data-dockkit-tab-menu]', scaffold.workspaceCwd), mode) + await captureStableAria(page, '[data-context-menu][role="menu"]', scaffold.workspaceCwd), mode) } else { - await page.getByRole('menuitem').focus() + await page.getByRole('menuitem', { name: 'Close', exact: true }).focus() } await page.keyboard.press('Escape') await page.getByRole('menu').waitFor({ state: 'detached' }) diff --git a/apps/web/tests/shortcuts-workspace.e2e.ts b/apps/web/tests/shortcuts-workspace.e2e.ts index 410fa3ce84..d7c81823c2 100644 --- a/apps/web/tests/shortcuts-workspace.e2e.ts +++ b/apps/web/tests/shortcuts-workspace.e2e.ts @@ -178,8 +178,9 @@ describe.skipIf(mode === 'record')('web e2e: workspace shortcuts', () => { await expect.poll(() => launched).toEqual([{ app: 'vscode', path: workspace.path }]) await page.keyboard.press('Meta+Alt+P') - const files = page.locator('[data-files-state="tree"]') + const files = page.locator('[data-files-page]') await files.locator('[data-files-row="empty"]').waitFor() + // The directory opener sits in the files page's header, above the tree. const opener = files.locator('[data-open-target="directory"]') await opener.getByRole('button', { name: 'Open in VS Code', exact: true }).click() await expect.poll(() => launched).toEqual([ @@ -196,7 +197,7 @@ describe.skipIf(mode === 'record')('web e2e: workspace shortcuts', () => { ]) await expect.poll(() => opener.getAttribute('data-state')).toBe('idle') await compareOrRefreshGolden(join(root, 'files-open.expected.md'), - await captureStableAria(page, '[data-files-state="tree"]', scaffold.workspaceCwd), mode) + await captureStableAria(page, '[data-files-page]', scaffold.workspaceCwd), mode) await opener.getByRole('button', { name: 'More ways to open', exact: true }).click() await page.getByRole('menuitem', { name: 'Finder (default)', exact: true }).waitFor() await page.keyboard.press('Escape') diff --git a/apps/web/tests/sidebar-alignment.e2e.ts b/apps/web/tests/sidebar-alignment.e2e.ts new file mode 100644 index 0000000000..82afdd29f2 --- /dev/null +++ b/apps/web/tests/sidebar-alignment.e2e.ts @@ -0,0 +1,566 @@ +/** Browser geometry for sidebar controls, text clearance, and drag previews. */ +import { readFile } from 'node:fs/promises' +import { fileURLToPath } from 'node:url' +import type { Browser, Locator, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, onTestFailed, vi } from 'vitest' +import type { AccountView } from '@deepseek-ai/dsh-deepseek-account/types' +import type {} from '@deepseek-ai/dsh-deepseek-account' +import type {} from '@deepseek-ai/dsh-api-session-controller' +import { + compareOrRefreshGolden, launchWebScaffold, seedSession, watchConsole, + webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { newEnglishPage, saveFailureShot } from './support.ts' + +const SEED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/session.v3.jsonl', import.meta.url)) +const GEOMETRY_EXPECTED = fileURLToPath(new URL('./expected/sidebar-alignment/geometry.expected.md', import.meta.url)) +const MODE = webSnapshotMode() +const ACTION_TARGET_SIZE = 24 +const ACTION_LAYOUT_SIZE = 16 +const ACTION_CENTER_SPACING = 29 +const ACTION_TRAILING_INSET = 7 +const SEARCH_HEIGHT = 32 +const SEARCH_TRANSITION_MS = 180 +const HEADER_LABEL_OFFSET = 7 +const HEADER_ACTION_RIGHT_OFFSETS = { search: -61, view: -29, add: 3 } + +/** + * Measure painted glyphs and pointer targets independently of the row's layout cells. + * @param row - visible, hovered Workspace or Session row. + * @returns row bounds, action geometry, and browser hit-test results. + */ +async function measureRowActions(row: Locator) { + return row.evaluate((element) => { + const rowRect = element.getBoundingClientRect() + const title = element.querySelector('[class*="title"]') + if (title === null) throw new Error('row title not in the DOM') + const buttons = [...element.querySelectorAll('button')] + return { + height: rowRect.height, + overflows: element.scrollWidth > element.clientWidth, + titleRight: title.getBoundingClientRect().right, + actions: buttons.map((button) => { + const rect = button.getBoundingClientRect() + const glyph = button.querySelector('svg') + if (glyph === null) throw new Error('row action glyph not in the DOM') + const glyphRect = glyph.getBoundingClientRect() + const style = getComputedStyle(button) + const center = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 } + // Side samples cover the outer target; corner samples stay inside the rounded border. + const points = [ + { x: center.x - 11.5, y: center.y }, + { x: center.x + 11.5, y: center.y }, + { x: center.x, y: center.y - 11.5 }, + { x: center.x, y: center.y + 11.5 }, + { x: center.x - 9.5, y: center.y - 9.5 }, + { x: center.x + 9.5, y: center.y - 9.5 }, + { x: center.x - 9.5, y: center.y + 9.5 }, + { x: center.x + 9.5, y: center.y + 9.5 }, + ] + const hits = (x: number, y: number): boolean => { + const target = document.elementFromPoint(x, y) + return target !== null && button.contains(target) + } + return { + label: button.getAttribute('aria-label'), + width: rect.width, + height: rect.height, + layoutWidth: rect.width + Number.parseFloat(style.marginLeft) + Number.parseFloat(style.marginRight), + layoutHeight: rect.height + Number.parseFloat(style.marginTop) + Number.parseFloat(style.marginBottom), + margins: [style.marginTop, style.marginRight, style.marginBottom, style.marginLeft], + pseudoContent: getComputedStyle(button, '::after').content, + center, + rowCenterOffset: center.y - (rowRect.y + rowRect.height / 2), + trailingInset: rowRect.right - rect.right, + glyphWidth: glyphRect.width, + glyphHeight: glyphRect.height, + glyphCenterOffset: { + x: glyphRect.x + glyphRect.width / 2 - center.x, + y: glyphRect.y + glyphRect.height / 2 - center.y, + }, + insideRow: center.x - 12 >= rowRect.left && center.x + 12 <= rowRect.right + && center.y - 12 >= rowRect.top && center.y + 12 <= rowRect.bottom, + points, + edgeHits: points.map(({ x, y }) => hits(x, y)), + // Clear Chromium's boundary rounding while still rejecting an oversized 28px target. + outsideHits: [ + hits(center.x - 13.5, center.y), hits(center.x + 13.5, center.y), + hits(center.x, center.y - 13.5), hits(center.x, center.y + 13.5), + ], + } + }), + } + }) +} + +describe('web e2e: sidebar search alignment and row action targets', () => { + const workspaceTitle = 'Sidebar geometry workspace' + const sessionTitle = 'Sidebar geometry session' + const archivedTitle = 'Archived geometry session with a long title that fills its sidebar row' + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + + beforeAll(async () => { + scaffold = await launchWebScaffold({}) + const workspace = await scaffold.ctx.workspaceRegistry.create(scaffold.workspaceCwd, workspaceTitle) + const id = await seedSession(scaffold, await readFile(SEED, 'utf8'), 'sidebar-action-geometry') + await workspace.attachSession(id) + await scaffold.ctx.sessionController.rename({ sessionId: id, title: sessionTitle }) + const archivedId = await seedSession(scaffold, await readFile(SEED, 'utf8'), 'sidebar-search-geometry') + await workspace.attachSession(archivedId) + await scaffold.ctx.sessionController.rename({ sessionId: archivedId, title: archivedTitle }) + await scaffold.ctx.workspaceRegistry.archiveSession(archivedId) + browser = await chromium.launch() + }) + + beforeEach(async () => { + page = await newEnglishPage(browser, 800) + tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + const workspace = page.locator('[data-row-key^="workspace:"]').filter({ hasText: workspaceTitle }) + await workspace.waitFor({ timeout: 30_000 }) + await expect.poll(async () => { + if (await workspace.getAttribute('aria-expanded') !== 'true') { + await workspace.getByText(workspaceTitle, { exact: true }).click() + } + return workspace.getAttribute('aria-expanded') + }, { timeout: 10_000 }).toBe('true') + await page.locator('[data-row-key="session:sidebar-action-geometry"]').waitFor() + }) + + afterEach(async () => { + await page?.close() + }) + + afterAll(async () => { + try { await browser?.close() } finally { await scaffold?.close() } + }) + + it('aligns the 32px expanded search with both edges of New session', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-search-alignment')) + const searchButton = page.getByRole('button', { name: 'Search sessions', exact: true }) + const input = page.getByPlaceholder('Search session names', { exact: true }) + const search = input.locator('..') + const newSession = page.locator('button[class*="newSession"]') + const measure = async () => { + const searchBox = await search.boundingBox() + const newSessionBox = await newSession.boundingBox() + if (searchBox === null || newSessionBox === null) throw new Error('sidebar controls have no layout box') + return { + height: searchBox.height, + leftOffset: searchBox.x - newSessionBox.x, + rightOffset: searchBox.x + searchBox.width - newSessionBox.x - newSessionBox.width, + } + } + for (const dark of [false, true]) { + await page.evaluate(dark => document.body.toggleAttribute('data-ds-dark-theme', dark), dark) + await expect.poll(async () => { + const reference = await newSession.boundingBox() + if (reference === null) throw new Error('New session has no layout box') + const controls = [searchButton, page.getByRole('button', { name: 'View options', exact: true }), page.getByRole('button', { name: 'Add workspace', exact: true })] + const boxes = await Promise.all(controls.map(control => control.boundingBox())) + return boxes.map(box => box === null ? null : box.x + box.width - reference.x - reference.width) + }).toEqual(Object.values(HEADER_ACTION_RIGHT_OFFSETS)) + const labelBox = await page.locator('[class*="sectionHeader"] [class*="sectionLabel"]').boundingBox() + const referenceBox = await newSession.boundingBox() + if (labelBox === null || referenceBox === null) throw new Error('Sidebar heading has no layout box') + expect(labelBox.x - referenceBox.x).toBe(HEADER_LABEL_OFFSET) + await searchButton.click() + await expect.poll(() => searchButton.getAttribute('aria-expanded')).toBe('true') + await expect.poll(measure, { timeout: 10_000 }).toEqual({ height: SEARCH_HEIGHT, leftOffset: 0, rightOffset: 0 }) + expect(await input.evaluate(element => element === document.activeElement)).toBe(true) + await input.press('Escape') + await expect.poll(() => searchButton.getAttribute('aria-expanded')).toBe('false') + } + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }) + + it('interpolates header spacing with the search expansion and collapse', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-search-transition')) + const header = page.locator('[class*="sectionHeader"]').filter({ has: page.getByRole('button', { name: 'Search sessions', exact: true }) }) + for (const expand of [true, false]) { + const samples = await header.evaluate(async (element, { expand, duration }) => { + const button = element.querySelector('button[aria-label="Search sessions"]') + const input = element.querySelector('input') + if (button === null || input === null) throw new Error('Search controls are missing') + // Pause transitions at their first frame, before scheduler delays can consume their duration. + const pause = (event: Event): void => { + if (event.target instanceof Element) { + for (const animation of event.target.getAnimations()) animation.pause() + } + } + element.addEventListener('transitionrun', pause, true) + try { + await new Promise((resolve) => { + element.addEventListener('transitionrun', () => { resolve() }, { once: true }) + if (expand) button.click() + else input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })) + }) + const animations = element.getAnimations({ subtree: true }) + const headerTransitions = element.getAnimations().map(animation => ({ + property: animation instanceof CSSTransition ? animation.transitionProperty : '', + duration: animation.effect?.getTiming().duration, + })) + const frames = [0, 0.25, 0.5, 0.75, 1].map((progress) => { + for (const animation of animations) { animation.pause(); animation.currentTime = duration * progress } + const style = getComputedStyle(element) + return { + marginRight: Number.parseFloat(style.marginRight), + paddingLeft: Number.parseFloat(style.paddingLeft), + paddingRight: Number.parseFloat(style.paddingRight), + gap: Number.parseFloat(style.columnGap), + width: element.getBoundingClientRect().width, + } + }) + for (const animation of animations) animation.finish() + return { headerTransitions, frames } + } finally { + element.removeEventListener('transitionrun', pause, true) + } + }, { expand, duration: SEARCH_TRANSITION_MS }) + for (const property of ['margin-right', 'padding-left', 'padding-right', 'column-gap']) { + expect(samples.headerTransitions).toContainEqual({ property, duration: SEARCH_TRANSITION_MS }) + } + const first = samples.frames[0]! + const last = samples.frames.at(-1)! + expect(first).toMatchObject(expand + ? { marginRight: -4, paddingLeft: 12, paddingRight: 1, gap: 4 } + : { marginRight: 0, paddingLeft: 4, paddingRight: 4, gap: 0 }) + expect(last).toMatchObject(expand + ? { marginRight: 0, paddingLeft: 4, paddingRight: 4, gap: 0 } + : { marginRight: -4, paddingLeft: 12, paddingRight: 1, gap: 4 }) + for (const frame of samples.frames.slice(1, -1)) { + for (const key of ['marginRight', 'paddingLeft', 'paddingRight', 'gap', 'width'] as const) { + expect(frame[key]).toBeGreaterThan(Math.min(first[key], last[key])) + expect(frame[key]).toBeLessThan(Math.max(first[key], last[key])) + } + const progress = (frame.marginRight - first.marginRight) / (last.marginRight - first.marginRight) + for (const key of ['paddingLeft', 'paddingRight', 'gap'] as const) { + expect((frame[key] - first[key]) / (last[key] - first[key])).toBeCloseTo(progress, 2) + } + } + } + }) + + it.each([ + { usedSearch: false, entry: 'toggle' }, + { usedSearch: true, entry: 'toggle' }, + { usedSearch: false, entry: 'search' }, + { usedSearch: true, entry: 'search' }, + { usedSearch: true, entry: 'toggle-with-query' }, + ] as const)('lands the header at its final rail-to-wide geometry ($entry, prior search: $usedSearch)', async ({ usedSearch, entry }) => { + onTestFailed(() => saveFailureShot(page, `web-e2e-sidebar-rail-${entry}-${String(usedSearch)}`)) + if (usedSearch) { + await page.getByRole('button', { name: 'Search sessions', exact: true }).click() + const input = page.getByPlaceholder('Search session names', { exact: true }) + if (entry === 'toggle-with-query') await input.fill(sessionTitle) + else await input.press('Escape') + } + await page.getByRole('button', { name: 'Collapse sidebar', exact: true }).click() + await expect.poll(() => page.getByRole('button', { name: 'Account menu', exact: true }).getAttribute('data-collapsed')).toBe('true') + const add = page.getByRole('button', { name: 'Add workspace', exact: true }) + const samples = await add.evaluate(async (button, entry) => { + const header = button.closest('[class*="sectionHeader"]') + const root = header?.parentElement + if (header === null || root === null || root === undefined) throw new Error('Workspace header is missing') + const railClass = root.className + const measure = () => { + const origin = root.getBoundingClientRect() + const bounds = header.getBoundingClientRect() + const addBounds = button.getBoundingClientRect() + const style = getComputedStyle(header) + return { + left: bounds.left - origin.left, right: bounds.right - origin.left, + top: bounds.top - origin.top, height: bounds.height, + // Search hides this cluster with its own animation; only compare the visible add control. + add: entry === 'toggle' + ? { left: addBounds.left - origin.left, right: addBounds.right - origin.left } + : null, + marginRight: Number.parseFloat(style.marginRight), + paddingLeft: Number.parseFloat(style.paddingLeft), paddingRight: Number.parseFloat(style.paddingRight), + gap: Number.parseFloat(style.columnGap), + transitionDuration: style.transitionDuration, + searchExpanded: header.querySelector('button[aria-label="Search sessions"]')?.getAttribute('aria-expanded'), + } + } + const first = await new Promise>((resolve) => { + // Observe the first rendered wide frame after the rail gesture's React updates. + const observer = new MutationObserver(() => { + if (root.className === railClass) return + observer.disconnect() + requestAnimationFrame(() => { resolve(measure()) }) + }) + observer.observe(root, { attributes: true, attributeFilter: ['class'] }) + const trigger = entry === 'search' + ? root.querySelector('button[aria-label="Search sessions"]') + : document.querySelector('button[aria-label="Open sidebar"]') + if (trigger === null) { observer.disconnect(); throw new Error('Rail expansion trigger is missing') } + trigger.click() + }) + const headerTransitions = header.getAnimations() + .filter(animation => animation instanceof CSSTransition) + .map(animation => animation.transitionProperty) + await Promise.all(root.getAnimations({ subtree: true }) + .filter(animation => animation.effect?.getTiming().iterations !== Infinity) + .map(animation => animation.finished.then(() => undefined, () => undefined))) + return { + first, last: measure(), headerTransitions, + sameHeader: root.querySelector('[class*="sectionHeader"]') === header, + sameAdd: root.querySelector('button[aria-label="Add workspace"]') === button, + } + }, entry) + expect(samples.headerTransitions).toEqual([]) + expect(samples.first.transitionDuration).toBe('0s') + expect(samples.first).toEqual(samples.last) + expect(samples.first).toMatchObject(entry !== 'toggle' + ? { marginRight: 0, paddingLeft: 4, paddingRight: 4, gap: 0, searchExpanded: 'true' } + : { marginRight: -4, paddingLeft: 12, paddingRight: 1, gap: 4, searchExpanded: 'false' }) + expect(samples.sameHeader).toBe(true) + expect(samples.sameAdd).toBe(true) + if (entry === 'search') { + await expect.poll(() => page.getByPlaceholder('Search session names', { exact: true }) + .evaluate(element => element === document.activeElement)).toBe(true) + } + expect(tripwire.pageErrors).toEqual([]) + }) + + it('keeps a clipped search title clear of the unarchive target', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-search-title-clearance')) + await page.getByRole('button', { name: 'View options', exact: true }).click() + await page.getByRole('menuitem', { name: 'All conversations (show archived)', exact: true }).click() + await expect.poll(() => page.locator('[data-row-key="session:sidebar-search-geometry"]').textContent()).toContain(archivedTitle) + await page.getByRole('button', { name: 'Search sessions', exact: true }).click() + await page.getByPlaceholder('Search session names', { exact: true }).fill('Archived geometry') + const row = page.getByRole('treeitem').filter({ hasText: archivedTitle }) + await row.hover() + await row.getByRole('button', { name: 'Unarchive session', exact: true }).waitFor() + const geometry = await row.evaluate((element) => { + const title = element.querySelector('[class*="searchResultTitle"]') + const button = element.querySelector('button') + if (title === null || button === null) throw new Error('Search result title or action is missing') + const titleRect = title.getBoundingClientRect() + const buttonRect = button.getBoundingClientRect() + const titleEdge = document.elementFromPoint(titleRect.right - 0.5, titleRect.top + titleRect.height / 2) + return { + clipped: title.scrollWidth > title.clientWidth, + labelGap: Number.parseFloat(getComputedStyle(title).marginRight), + targetWidth: buttonRect.width, + clearance: buttonRect.left - titleRect.right, + titleEdgeHitsTitle: titleEdge !== null && title.contains(titleEdge), + overflows: element.scrollWidth > element.clientWidth, + } + }) + expect(geometry).toEqual({ + clipped: true, labelGap: 6, targetWidth: ACTION_TARGET_SIZE, clearance: 2, titleEdgeHitsTitle: true, overflows: false, + }) + await compareOrRefreshGolden(GEOMETRY_EXPECTED, [ + '# Sidebar alignment', '', + `- search title is clipped: ${String(geometry.clipped)}`, + `- unarchive hit target width: ${geometry.targetWidth}px`, + `- clipped search title label gap: ${geometry.labelGap}px`, + `- clipped search title clearance from unarchive hit target: ${geometry.clearance}px`, + `- clipped search title edge hit-tests to title: ${String(geometry.titleEdgeHitsTitle)}`, + ].join('\n'), MODE) + expect(tripwire.pageErrors).toEqual([]) + }) + + it.each(['session', 'workspace'] as const)('retains %s row spacing in the native drag preview', async (kind) => { + onTestFailed(() => saveFailureShot(page, `web-e2e-sidebar-${kind}-drag-preview`)) + const row = kind === 'session' + ? page.locator('[data-row-key="session:sidebar-action-geometry"]') + : page.locator('[data-row-key^="workspace:"]').filter({ hasText: workspaceTitle }) + await row.evaluate((element) => { + element.parentElement!.style.setProperty('--dsh-workspace-indent', '24px') + element.parentElement!.style.setProperty('--unrelated-preview-variable', '17px') + }) + const box = await row.boundingBox() + if (box === null) throw new Error('Drag source has no layout box') + await page.mouse.move(box.x + 40, box.y + box.height / 2) + await page.mouse.down() + try { + await page.mouse.move(box.x + 45, box.y + box.height + 10, { steps: 8 }) + const preview = page.locator('body > [inert][aria-hidden="true"] > [role="treeitem"]') + await preview.waitFor({ state: 'attached' }) + const spacing = (target: Locator) => target.evaluate((element) => { + const style = getComputedStyle(element) + const slot = [...element.querySelectorAll('[class*="slot"]')].find(candidate => candidate.getBoundingClientRect().width > 0) + if (slot === undefined) throw new Error('Row leading slot is missing') + return { + paddingStart: style.paddingInlineStart, paddingEnd: style.paddingInlineEnd, + borderStart: style.borderInlineStartWidth, borderEnd: style.borderInlineEndWidth, + gap: style.columnGap, + width: element.getBoundingClientRect().width, + height: element.getBoundingClientRect().height, + slotOffset: slot.getBoundingClientRect().left - element.getBoundingClientRect().left, + } + }) + expect(await spacing(preview)).toEqual(await spacing(row)) + expect(await preview.evaluate(element => [...element.parentElement!.style].filter(name => name.startsWith('--')).sort())) + .toEqual(['--dsh-sidebar-label-gap', '--dsh-sidebar-paint-inset', '--dsh-sidebar-row-padding']) + const titleOffset = (target: Locator) => target.evaluate((element) => { + const title = element.querySelector('[class*="title"]') + if (title === null) throw new Error('Row title is missing') + return title.getBoundingClientRect().left - element.getBoundingClientRect().left + }) + expect(await titleOffset(preview)).toBe(await titleOffset(row)) + } finally { + await page.keyboard.press('Escape') + await page.mouse.up() + } + await page.locator('body > [inert][aria-hidden="true"] > [role="treeitem"]').waitFor({ state: 'detached' }) + expect(tripwire.pageErrors).toEqual([]) + }) + + it.each([false, true])('keeps account footer geometry in wide and rail layouts (signed in: %s)', async (signedIn) => { + onTestFailed(() => saveFailureShot(page, `web-e2e-sidebar-account-${String(signedIn)}`)) + const account = scaffold.ctx.deepseekAccount + const state: AccountView = { + status: 'credential-stored', attempt: null, + links: { usageUrl: 'https://platform.deepseek.com/usage', topUpUrl: 'https://platform.deepseek.com/top_up' }, + } + // Only Platform identity is synthetic; the account provider's RPC and client renderer remain composed. + const mocks = signedIn ? [ + vi.spyOn(account, 'getState').mockResolvedValue(state), + vi.spyOn(account, 'getProfile').mockResolvedValue({ + status: 'ready', value: { id: null, name: 'Sidebar account', contact: null, avatarUrl: null }, + }), + vi.spyOn(account, 'getBalance').mockResolvedValue({ status: 'ready', value: [], bonusWallets: [] }), + vi.spyOn(account, 'watch').mockImplementation(async function* (signal) { + yield state + if (signal.aborted) return + await new Promise((resolve) => { signal.addEventListener('abort', () => { resolve() }, { once: true }) }) + }), + ] : [] + try { + if (signedIn) await page.reload({ waitUntil: 'load' }) + const accountButton = page.getByRole('button', { name: 'Account menu', exact: true }) + await expect.poll(() => accountButton.getAttribute('data-signed-out')).toBe(String(!signedIn)) + const measure = () => accountButton.evaluate((element) => { + const button = element.getBoundingClientRect() + const style = getComputedStyle(element) + const newSession = document.querySelector('button[class*="newSession"]') + if (newSession === null) throw new Error('New session reference is missing') + const reference = newSession.getBoundingClientRect() + const footer = element.closest('[class*="footArea"]')?.getBoundingClientRect() + if (footer === undefined) throw new Error('Account footer is missing') + return { + height: button.height, width: button.width, + footerCenterOffset: (button.left + button.right - footer.left - footer.right) / 2, + leftOffset: button.left - reference.left, rightOffset: button.right - reference.right, + paintedLeftOffset: button.left + Number.parseFloat(style.borderLeftWidth) - reference.left, + paintedRightOffset: button.right - Number.parseFloat(style.borderRightWidth) - reference.right, + } + }) + const wide = await measure() + expect(wide.height).toBe(signedIn ? 44 : 32) + expect(wide.leftOffset).toBe(signedIn ? -2 : -4) + expect(wide.rightOffset).toBe(signedIn ? 2 : 4) + expect(wide.paintedLeftOffset).toBe(signedIn ? -2 : -1) + expect(wide.paintedRightOffset).toBe(signedIn ? 2 : 1) + await page.getByRole('button', { name: 'Collapse sidebar', exact: true }).click() + await expect.poll(() => accountButton.getAttribute('data-collapsed')).toBe('true') + await expect.poll(async () => { + const rect = await accountButton.boundingBox() + return rect === null ? null : { width: rect.width, height: rect.height } + }).toEqual({ width: 36, height: 36 }) + await page.locator('button[class*="newSession"]').evaluate(async (element) => { + await Promise.all(element.getAnimations().map(animation => animation.finished)) + }) + const rail = await measure() + expect(rail.footerCenterOffset).toBe(0) + await compareOrRefreshGolden( + fileURLToPath(new URL(`./expected/sidebar-alignment/account-${signedIn ? 'signed-in' : 'signed-out'}.expected.md`, import.meta.url)), + JSON.stringify({ wide, rail }, null, 2), MODE, + ) + expect(tripwire.pageErrors).toEqual([]) + } finally { + await page.close() + mocks.forEach((mock) => { mock.mockRestore() }) + } + }) + + it.each(['session', 'workspace'] as const)('keeps %s action glyphs in 16px layout space with 24px buttons', async (kind) => { + onTestFailed(() => saveFailureShot(page, `web-e2e-sidebar-${kind}-action-targets`)) + const row = kind === 'session' + ? page.locator('[data-row-key="session:sidebar-action-geometry"]') + : page.locator('[data-row-key^="workspace:"]').filter({ hasText: workspaceTitle }) + const restingBox = await row.boundingBox() + await row.hover() + const labels = kind === 'session' + ? [`Session actions for ${sessionTitle}`, 'Archive session', 'Pin session'] as const + : [`Workspace actions for ${workspaceTitle}`, `New session in ${workspaceTitle}`] as const + await row.getByRole('button', { name: labels[0], exact: true }).waitFor() + const metrics = await measureRowActions(row) + expect(await row.boundingBox()).toEqual(restingBox) + expect(metrics.height).toBe(kind === 'session' ? 32 : 34) + expect(metrics.overflows).toBe(false) + expect(metrics.actions.map(action => action.label)).toEqual(labels) + for (const [index, action] of metrics.actions.entries()) { + expect(action.width).toBe(ACTION_TARGET_SIZE) + expect(action.height).toBe(ACTION_TARGET_SIZE) + expect(action.layoutWidth).toBe(ACTION_LAYOUT_SIZE) + expect(action.layoutHeight).toBe(ACTION_LAYOUT_SIZE) + expect(action.margins).toEqual(['-4px', '-4px', '-4px', '-4px']) + expect(action.pseudoContent).toBe('none') + expect(action.rowCenterOffset).toBe(0) + expect(action.glyphWidth).toBe(index === 0 ? 16 : 14) + expect(action.glyphHeight).toBe(index === 0 ? 16 : 14) + expect(action.glyphCenterOffset).toEqual({ x: 0, y: 0 }) + expect(action.insideRow).toBe(true) + expect(action.edgeHits).toEqual(Array(8).fill(true)) + expect(action.outsideHits).toEqual([false, false, false, false]) + const previous = metrics.actions[index - 1] + if (previous !== undefined) { + expect(action.center.x - previous.center.x).toBe(ACTION_CENTER_SPACING) + expect(previous.center.x + 12).toBeLessThan(action.center.x - 12) + } else { + expect(metrics.titleRight).toBeLessThanOrEqual(action.center.x - 12) + } + } + expect(metrics.actions.at(-1)?.trailingInset).toBe(ACTION_TRAILING_INSET) + + if (kind === 'session') expect(await row.getAttribute('aria-selected')).toBe('false') + const selectedRows = page.locator('[role="tree"][aria-label="Sessions"] [aria-selected="true"]') + const selectedKeys = await selectedRows.evaluateAll(rows => rows.map(row => row.getAttribute('data-row-key'))) + const expanded = await row.getAttribute('aria-expanded') + const menuButton = row.getByRole('button', { name: labels[0], exact: true }) + const menu = page.getByRole('menu') + const menuAction = kind === 'session' ? 'Pin session' : 'Rename' + const first = metrics.actions[0] + if (first === undefined) throw new Error('row has no menu trigger') + for (const point of first.points.slice(0, 4)) { + // Edge clicks exercise the enlarged target rather than the glyph's center. + await page.mouse.click(point.x, point.y) + await menu.getByRole('menuitem', { name: menuAction, exact: true }).waitFor() + expect(await selectedRows.evaluateAll(rows => rows.map(row => row.getAttribute('data-row-key')))).toEqual(selectedKeys) + expect(await row.getAttribute('aria-expanded')).toBe(expanded) + await page.keyboard.press('Escape') + await menu.waitFor({ state: 'detached' }) + await menuButton.hover() + } + const tooltipAnchor = row.getByRole('button', { name: labels[1], exact: true }) + const tooltip = page.getByRole('tooltip').filter({ hasText: kind === 'session' ? 'Archive' : 'New session' }) + await tooltipAnchor.hover() + await tooltip.waitFor({ timeout: 10_000 }) + const anchorBox = await tooltipAnchor.boundingBox() + const tooltipBox = await tooltip.boundingBox() + if (anchorBox === null || tooltipBox === null) throw new Error('hover tooltip or its anchor has no layout box') + expect(tooltipBox.y).toBe(anchorBox.y + anchorBox.height + 8) + expect(tooltipBox.x + tooltipBox.width).toBe(anchorBox.x + anchorBox.width) + await page.mouse.move(1000, 400) + await tooltip.waitFor({ state: 'detached' }) + if (kind === 'session') { + expect(await menuButton.evaluate(element => element === document.activeElement)).toBe(true) + expect(await tooltipAnchor.isVisible()).toBe(true) + } + await page.mouse.click(1000, 400) + expect(await tooltipAnchor.isVisible()).toBe(false) + expect(await page.getByRole('tooltip').count()).toBe(0) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }) +}) diff --git a/apps/web/tests/sidebar-drawer.e2e.ts b/apps/web/tests/sidebar-drawer.e2e.ts new file mode 100644 index 0000000000..99b5c3fd43 --- /dev/null +++ b/apps/web/tests/sidebar-drawer.e2e.ts @@ -0,0 +1,737 @@ +/** Narrow sidebar geometry, navigation, focus and retained content in the shipped profile. */ +import { readFile } from 'node:fs/promises' +import { fileURLToPath } from 'node:url' +import type { Locator } from 'playwright' +import { chromium } from 'playwright' +import { expect, it } from 'vitest' +import { compareOrRefreshGolden, launchWebScaffold, seedSession, watchConsole, webSnapshotMode } from './scaffold.ts' + +/** A returning rail uses its compact layout without wide-content or icon-entry animations. */ +async function assertCompactRail(sidebar: Locator): Promise { + expect(await sidebar.getByRole('button', { name: 'New session', exact: true }).count()).toBe(1) + expect(await sidebar.evaluate((el) => { + const root = el.firstElementChild! + return { + fits: root.getBoundingClientRect().width <= el.parentElement!.getBoundingClientRect().width, + animations: root.getAnimations({ subtree: true }) + .filter((animation): animation is CSSAnimation => + animation instanceof CSSAnimation && /wide-in|rail-in|rail-fade-in/.test(animation.animationName)) + .map(animation => animation.animationName), + } + })).toEqual({ fits: true, animations: [] }) +} + +it.each(['light', 'dark'] as const)('keeps the macOS drawer opaque and excludes inert content from window drag regions in %s mode', async (colorScheme) => { + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + }) + try { + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 520, height: 680 }, colorScheme, locale: 'en-US' }) + await page.goto(scaffold.authenticatedUrl) + const opener = page.getByRole('button', { name: 'Open sidebar', exact: true }) + await opener.waitFor() + await page.evaluate(() => { document.documentElement.dataset.platform = 'darwin' }) + await opener.click() + const drawer = page.getByRole('dialog', { name: 'Navigation', exact: true }) + await drawer.waitFor() + const column = page.locator('[data-slot="sidebar"]').locator('..') + const background = await column.evaluate((el) => { + const style = getComputedStyle(el) + return { color: style.backgroundColor, image: style.backgroundImage } + }) + expect(background.image).toBe('none') + expect(background.color).toMatch(/^rgb\(/) + expect(await drawer.getByRole('button', { name: 'New session', exact: true }).last().evaluate((el) => { + const actual = getComputedStyle(el).backgroundColor + const root = document.documentElement + const platform = root.dataset.platform + delete root.dataset.platform + try { + return actual === getComputedStyle(el).backgroundColor + } finally { + root.dataset.platform = platform + } + })).toBe(true) + const inactiveContent = page.locator('[inert], [inert] *') + expect(await inactiveContent.count()).toBeGreaterThan(0) + expect(await inactiveContent.evaluateAll(elements => elements + .filter(el => getComputedStyle(el).getPropertyValue('app-region') !== 'none') + .map(el => `${el.tagName}.${el.getAttribute('class')}: ${getComputedStyle(el).getPropertyValue('app-region')}`))) + .toEqual([]) + expect(await drawer.locator('[data-window-drag]').first().evaluate(el => getComputedStyle(el).getPropertyValue('app-region'))) + .toBe('drag') + const collapse = drawer.getByRole('button', { name: 'Collapse sidebar', exact: true }) + await collapse.click() + await drawer.waitFor({ state: 'hidden' }) + await page.setViewportSize({ width: 1200, height: 800 }) + const sidebar = page.locator('[data-slot="sidebar"]').locator('..') + await expect.poll(() => sidebar.evaluate(el => getComputedStyle(el).backgroundImage)).not.toBe('none') + const activeDragRows = page.locator('[data-window-drag]:not([inert] [data-window-drag])') + expect(await activeDragRows.count()).toBeGreaterThan(0) + expect(await activeDragRows.evaluateAll(rows => rows.every(row => getComputedStyle(row).getPropertyValue('app-region') === 'drag'))) + .toBe(true) + } finally { + await browser.close() + } + } finally { + await scaffold.close() + } +}) + +it('hides a collapsed rail immediately when it becomes a drawer', async () => { + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + }) + try { + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 768, height: 844 }, locale: 'en-US' }) + await page.goto(scaffold.authenticatedUrl) + await page.getByRole('button', { name: 'Open sidebar', exact: true }).waitFor() + const sidebar = page.locator('[data-slot="sidebar"]') + const sidebarColumn = sidebar.locator('..') + await expect.poll(async () => (await sidebarColumn.boundingBox())?.width).toBe(56) + await sidebarColumn.evaluate((el) => { + el.parentElement!.style.setProperty('--ds-transition-duration-slow', '100s') + }) + await page.setViewportSize({ width: 767, height: 844 }) + await page.locator('[data-sidebar-drawer]').waitFor() + const state = await sidebarColumn.evaluate(el => ({ + visibility: getComputedStyle(el).visibility, + transitions: el.getAnimations().filter(animation => animation instanceof CSSTransition) + .map(animation => animation.transitionProperty), + })) + expect(state).toEqual({ visibility: 'hidden', transitions: [] }) + await page.setViewportSize({ width: 768, height: 844 }) + await page.locator('[data-sidebar-drawer]').waitFor({ state: 'detached' }) + await assertCompactRail(sidebar) + await page.setViewportSize({ width: 767, height: 844 }) + await page.locator('[data-sidebar-drawer]').waitFor() + await page.getByRole('button', { name: 'Open sidebar', exact: true }).click() + const drawer = page.getByRole('dialog', { name: 'Navigation', exact: true }) + await drawer.waitFor() + expect(await sidebarColumn.evaluate(el => el.getAnimations().some(animation => + animation instanceof CSSTransition && animation.transitionProperty === 'transform'))).toBe(true) + await sidebarColumn.evaluate((el) => { + for (const animation of el.parentElement!.getAnimations({ subtree: true })) animation.finish() + }) + await drawer.getByRole('button', { name: 'Collapse sidebar', exact: true }).click() + expect(await sidebarColumn.evaluate(el => el.getAnimations().some(animation => + animation instanceof CSSTransition && animation.transitionProperty === 'transform'))).toBe(true) + await sidebarColumn.evaluate((el) => { + for (const animation of el.parentElement!.getAnimations({ subtree: true })) animation.finish() + }) + await page.setViewportSize({ width: 768, height: 844 }) + await page.locator('[data-sidebar-drawer]').waitFor({ state: 'detached' }) + await assertCompactRail(sidebar) + } finally { + await browser.close() + } + } finally { + await scaffold.close() + } +}) + +it('retains the closing slide when an expanded sidebar becomes a collapsed drawer', async () => { + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + }) + try { + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 1024, height: 844 }, locale: 'en-US' }) + await page.goto(scaffold.authenticatedUrl) + await page.getByRole('button', { name: 'Collapse sidebar', exact: true }).waitFor() + const sidebarColumn = page.locator('[data-slot="sidebar"]').locator('..') + await expect.poll(async () => (await sidebarColumn.boundingBox())?.width).toBe(280) + await sidebarColumn.evaluate((el) => { + el.parentElement!.style.setProperty('--ds-transition-duration-slow', '100s') + }) + await page.setViewportSize({ width: 767, height: 844 }) + await page.locator('[data-sidebar-drawer][data-sidebar-collapsed]').waitFor() + expect(await sidebarColumn.evaluate(el => el.getAnimations().some(animation => + animation instanceof CSSTransition && animation.transitionProperty === 'transform'))).toBe(true) + } finally { + await browser.close() + } + } finally { + await scaffold.close() + } +}) + +/** Sample the CSS fade at its midpoint without depending on the host's frame rate. */ +async function assertMaskFade(frame: Locator, from: number, to: number): Promise { + const sample = await frame.locator('[data-sidebar-mask]').evaluate((el) => { + const fade = el.getAnimations().find(animation => animation instanceof CSSTransition && animation.transitionProperty === 'opacity') + if (fade === undefined || !(fade.effect instanceof KeyframeEffect)) throw new Error('Drawer mask opacity transition is missing') + fade.pause() + fade.currentTime = Number(fade.effect.getComputedTiming().duration) / 2 + return { + endpoints: fade.effect.getKeyframes().map(keyframe => Number(keyframe.opacity)), + opacity: Number(getComputedStyle(el).opacity), + } + }) + expect(sample.endpoints).toEqual([from, to]) + expect(sample.opacity).toBeGreaterThan(0) + expect(sample.opacity).toBeLessThan(1) + await frame.evaluate((el) => { + for (const animation of el.getAnimations({ subtree: true })) { + if (animation instanceof CSSTransition) animation.finish() + } + el.style.removeProperty('--ds-transition-duration-slow') + }) +} + +/** Sample both width transitions on the same clock to detect detached sidebar controls. */ +async function assertFoldResize(toggle: Locator, from: number, to: number): Promise { + await expect.poll(() => toggle.evaluate((button, target) => { + const frame = button.closest('[data-animating]') + return frame !== null && parseFloat(frame.style.gridTemplateColumns) === target && frame.getAnimations().some(animation => + animation instanceof CSSTransition && animation.transitionProperty === 'grid-template-columns') + }, to)).toBe(true) + const sample = await toggle.evaluate((button) => { + const frame = button.closest('[data-animating]')! + const transitions = frame.getAnimations({ subtree: true }).filter((animation): animation is CSSTransition => + animation instanceof CSSTransition && ['grid-template-columns', 'width'].includes(animation.transitionProperty)) + const grid = transitions.find(animation => animation.transitionProperty === 'grid-template-columns') + if (grid === undefined) throw new Error('Fold width transition is missing') + const at = (progress: number) => { + for (const transition of transitions) { + transition.pause() + transition.currentTime = Number(transition.effect!.getComputedTiming().duration) * progress + } + const width = parseFloat(getComputedStyle(frame).gridTemplateColumns) + return { width, gap: frame.getBoundingClientRect().left + width - button.getBoundingClientRect().right } + } + const start = at(0) + const middle = at(0.5) + const end = at(1) + for (const transition of transitions) transition.finish() + frame.style.removeProperty('--ds-transition-duration-slow') + return { endpoints: [start.width, end.width], start, middle } + }) + expect(sample.endpoints).toEqual([from, to]) + expect(sample.middle.width).toBeGreaterThan(Math.min(from, to)) + expect(sample.middle.width).toBeLessThan(Math.max(from, to)) + expect(sample.middle.gap).toBeCloseTo(sample.start.gap, 1) +} + +it('overlays the conversation and closes after navigation without losing its sidebar content', async () => { + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + }) + try { + const workspace = await scaffold.ctx.workspaceRegistry.create(scaffold.workspaceCwd) + const seed = await readFile(new URL('../../../snapshots/web/seeded-history/session.v3.jsonl', import.meta.url), 'utf8') + const sessionId = await seedSession(scaffold, seed, 'session-c4421b66-252e-44c0-80ed-6e320abeba25') + await workspace.attachSession(sessionId) + await scaffold.ctx.sessionController.rename({ sessionId, title: 'Drawer navigation' }) + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 390, height: 844 }, hasTouch: true, locale: 'en-US' }) + const console = watchConsole(page) + await page.goto(scaffold.authenticatedUrl) + const opener = page.getByRole('button', { name: 'Open sidebar', exact: true }) + await opener.waitFor() + const frame = page.locator('[data-sidebar-drawer]') + expect(await page.locator('[data-shell-leading]').getByRole('button').count()).toBe(1) + expect(await frame.evaluate(el => getComputedStyle(el).getPropertyValue('--dsh-frame-leading-clearance').trim())) + .toBe('48px') + await expect.poll(() => frame.getAttribute('data-sidebar-collapsed')).toBe('true') + const sidebar = page.locator('[data-slot="sidebar"]') + const original = await sidebar.elementHandle() + const main = page.locator('[data-slot="main"]').locator('..') + const closed = await main.boundingBox() + // A long test-owned duration keeps the transition available until its + // animation clock is sampled and finished explicitly. + await frame.evaluate((el) => { el.style.setProperty('--ds-transition-duration-slow', '100s') }) + await opener.tap() + const drawer = page.getByRole('dialog', { name: 'Navigation', exact: true }) + await drawer.waitFor() + await assertMaskFade(frame, 0, 1) + await expect.poll(() => main.boundingBox()).toEqual(closed) + expect(closed?.width).toBe(390) + expect(await main.evaluate(el => el.closest('[inert]') !== null)).toBe(true) + expect(await page.locator('[data-side="sidebar"]').count()).toBe(0) + const workspaceRow = drawer.locator('[data-row-key^="workspace:"]').first() + const workspaceButtons = workspaceRow.getByRole('button', { includeHidden: true }) + expect(await workspaceRow.getAttribute('aria-expanded')).toBe('true') + expect(await workspaceButtons.count()).toBe(2) + for (const button of await workspaceButtons.all()) await button.waitFor() + await workspaceRow.tap() + expect(await workspaceRow.getAttribute('aria-expanded')).toBe('false') + for (const button of await workspaceButtons.all()) expect(await button.isVisible()).toBe(false) + await workspaceRow.tap() + for (const button of await workspaceButtons.all()) await button.waitFor() + await drawer.getByRole('button', { name: 'Search sessions', exact: true }).tap() + const search = drawer.getByPlaceholder('Search session names') + expect(await search.evaluate(el => getComputedStyle(el).fontSize)).toBe('16px') + await drawer.getByRole('button', { name: 'Clear search', exact: true }).tap() + await frame.evaluate((el) => { el.style.setProperty('--ds-transition-duration-slow', '100s') }) + await page.getByRole('treeitem').filter({ has: page.getByText('Drawer navigation', { exact: true }) }).tap() + await assertMaskFade(frame, 1, 0) + await drawer.waitFor({ state: 'hidden' }) + await page.getByRole('navigation', { name: 'Session hierarchy' }).getByText('Drawer navigation', { exact: true }).waitFor() + const chatTab = page.getByRole('tab', { name: 'Chat', exact: true }) + const tabInset = () => chatTab.evaluate((tab) => { + const label = document.createRange() + label.selectNodeContents(tab) + return label.getBoundingClientRect().left - tab.closest('header')!.getBoundingClientRect().left + }) + expect(await tabInset()).toBeCloseTo(20, 1) + // Restore CSS-probe markers in the same synchronous task, before rendering. + const desktopInsets = await chatTab.evaluate((tab) => { + const root = document.documentElement + try { + return ['darwin', 'win32'].map((platform) => { + root.dataset.platform = platform + const label = document.createRange() + label.selectNodeContents(tab) + return label.getBoundingClientRect().left - tab.closest('header')!.getBoundingClientRect().left + }) + } finally { + delete root.dataset.platform + } + }) + for (const inset of desktopInsets) expect(inset).toBeCloseTo(28, 1) + await page.setViewportSize({ width: 768, height: 844 }) + await frame.waitFor({ state: 'detached' }) + expect(await tabInset()).toBeCloseTo(28, 1) + await page.setViewportSize({ width: 390, height: 844 }) + await frame.waitFor() + await opener.click() + const selectedRow = drawer.getByRole('treeitem', { selected: true }) + const more = selectedRow.getByRole('button', { name: 'Session actions for Drawer navigation', exact: true }) + await more.waitFor() + expect(await selectedRow.getByRole('button', { name: 'Archive session', exact: true }).isVisible()).toBe(false) + expect(await selectedRow.getByRole('button', { name: 'Pin session', exact: true }).isVisible()).toBe(false) + expect(await selectedRow.getByRole('button').count()).toBe(1) + await more.tap() + const menu = page.getByRole('menu') + await menu.getByRole('menuitem', { name: 'Archive session', exact: true }).waitFor() + await menu.getByRole('menuitem', { name: 'Pin session', exact: true }).tap() + await menu.waitFor({ state: 'hidden' }) + const unpin = selectedRow.getByRole('button', { name: 'Unpin session', exact: true }) + await expect.poll(() => selectedRow.getByLabel('Pinned', { exact: true }).count()).toBe(1) + expect(await unpin.isVisible()).toBe(true) + const timestamp = selectedRow.getByText(/^(?:now|\d+min)$/, { exact: true }) + expect(await timestamp.count()).toBe(1) + expect(await timestamp.textContent()).toMatch(/^(?:now|\d+min)$/) + expect(await timestamp.isVisible()).toBe(false) + const unpinBox = (await unpin.boundingBox())! + const moreBox = (await more.boundingBox())! + const folderMoreBox = (await workspaceButtons.nth(0).boundingBox())! + const folderNewBox = (await workspaceButtons.nth(1).boundingBox())! + expect(moreBox.x - unpinBox.x).toBeCloseTo(folderNewBox.x - folderMoreBox.x, 1) + await unpin.tap() + await expect.poll(() => selectedRow.getByLabel('Pinned', { exact: true }).count()).toBe(0) + expect(await drawer.isVisible()).toBe(true) + await more.tap() + await menu.getByRole('menuitem', { name: 'Pin session', exact: true }).tap() + await menu.waitFor({ state: 'hidden' }) + await unpin.waitFor() + await more.tap() + await menu.getByRole('menuitem', { name: 'Unpin session', exact: true }).tap() + await menu.waitFor({ state: 'hidden' }) + await expect.poll(() => selectedRow.getByLabel('Pinned', { exact: true }).count()).toBe(0) + await drawer.getByRole('button', { name: 'Plugins', exact: true }).tap() + await drawer.waitFor({ state: 'hidden' }) + const pluginPanel = page.locator('[data-plugin-panel]') + await pluginPanel.waitFor() + for (const width of [390, 767, 768]) { + await page.setViewportSize({ width, height: 844 }) + expect(await pluginPanel.evaluate(el => Number.parseFloat(getComputedStyle(el).paddingLeft))) + .toBeCloseTo(width < 768 ? 20 : width * 0.04, 1) + } + await page.setViewportSize({ width: 390, height: 844 }) + await frame.waitFor() + await opener.click() + await drawer.getByRole('button', { name: 'Automation tasks', exact: true }).tap() + await drawer.waitFor({ state: 'hidden' }) + const tasksContent = page.getByTestId('task-manager-page').locator('[class*="pageContent"]') + await tasksContent.waitFor() + for (const width of [390, 767, 768]) { + await page.setViewportSize({ width, height: 844 }) + expect(await tasksContent.evaluate(el => Number.parseFloat(getComputedStyle(el).paddingLeft))) + .toBeCloseTo(width < 768 ? 20 : width * 0.04, 1) + } + await page.setViewportSize({ width: 390, height: 844 }) + await frame.waitFor() + await opener.click() + await drawer.waitFor() + await page.touchscreen.tap(370, 420) + await drawer.waitFor({ state: 'hidden' }) + await opener.click() + await page.keyboard.press('Escape') + await drawer.waitFor({ state: 'hidden' }) + expect(await opener.evaluate(el => el === document.activeElement)).toBe(true) + expect(await sidebar.evaluate((el, previous) => el === previous, original)).toBe(true) + await original?.dispose() + + await page.setViewportSize({ width: 768, height: 844 }) + await expect.poll(() => frame.count()).toBe(0) + await expect.poll(async () => Math.round((await main.boundingBox())!.width)).toBe(712) + await page.setViewportSize({ width: 767, height: 844 }) + await expect.poll(() => frame.count()).toBe(1) + + await page.emulateMedia({ reducedMotion: 'reduce' }) + await opener.tap() + const mask = frame.locator('[data-sidebar-mask]') + expect(await mask.evaluate(el => getComputedStyle(el).opacity)).toBe('1') + expect(await mask.evaluate(el => el.getAnimations().length)).toBe(0) + await drawer.getByRole('button', { name: 'Collapse sidebar', exact: true }).tap() + expect(await mask.evaluate(el => getComputedStyle(el).opacity)).toBe('0') + await page.emulateMedia({ reducedMotion: 'no-preference' }) + await expect.poll(async () => Math.round((await main.boundingBox())!.width)).toBe(767) + expect(await page.evaluate(() => document.documentElement.scrollWidth)).toBe(767) + await page.evaluate(() => { document.documentElement.dataset.platform = 'darwin' }) + await expect.poll(() => main.evaluate(el => getComputedStyle(el).paddingTop)).toBe('0px') + await page.evaluate(() => { delete document.documentElement.dataset.platform }) + await expect.poll(() => main.evaluate(el => getComputedStyle(el).paddingTop)).toBe('48px') + + await page.setViewportSize({ width: 390, height: 844 }) + await drawer.waitFor({ state: 'hidden' }) + await opener.tap() + await drawer.getByRole('button', { name: 'New session', exact: true }).last().tap() + await drawer.waitFor({ state: 'hidden' }) + const home = page.locator('[data-phase="hero"]') + await home.waitFor() + const editor = home.locator('[contenteditable="true"]') + await editor.tap() + const homeEditorBox = await editor.boundingBox() + // Chromium cannot raise a phone keyboard; simulate document panning + // before the visual viewport publishes the matching offset. + const restoreViewport = await page.evaluateHandle(() => { + const viewport = window.visualViewport! + const scrollY = Object.getOwnPropertyDescriptor(window, 'scrollY')! + Object.defineProperty(window, 'scrollY', { configurable: true, value: 80 }) + Object.defineProperties(viewport, { + height: { configurable: true, value: 360 }, + offsetTop: { configurable: true, value: 0 }, + }) + viewport.dispatchEvent(new Event('resize')) + viewport.dispatchEvent(new Event('scroll')) + window.dispatchEvent(new Event('scroll')) + return () => { + Object.defineProperty(window, 'scrollY', scrollY) + Reflect.deleteProperty(viewport, 'height') + Reflect.deleteProperty(viewport, 'offsetTop') + window.dispatchEvent(new Event('scroll')) + viewport.dispatchEvent(new Event('resize')) + } + }) + const root = page.locator('#root') + await expect.poll(() => root.boundingBox()).toEqual({ x: 0, y: 0, width: 390, height: 844 }) + expect(await editor.boundingBox()).toEqual(homeEditorBox) + await page.evaluate(() => { + Object.defineProperty(window.visualViewport!, 'offsetTop', { configurable: true, value: 80 }) + window.visualViewport!.dispatchEvent(new Event('scroll')) + }) + await expect.poll(() => root.boundingBox()).toEqual({ x: 0, y: 0, width: 390, height: 844 }) + await expect.poll(async () => (await main.boundingBox())?.height).toBe(844) + await opener.tap() + await expect.poll(async () => (await drawer.boundingBox())?.height).toBe(844) + const searchWithKeyboard = drawer.getByPlaceholder('Search session names') + await drawer.getByRole('button', { name: 'Search sessions', exact: true }).tap() + await searchWithKeyboard.tap() + await searchWithKeyboard.fill('retained search') + await drawer.getByRole('button', { name: 'Account menu', exact: true }).tap() + await page.getByRole('menuitem', { name: 'Settings', exact: true }).tap() + const settings = page.getByRole('dialog', { name: 'Settings', exact: true }) + await settings.waitFor() + const settingsBox = (await settings.boundingBox())! + expect(settingsBox.x).toBeGreaterThanOrEqual(0) + expect(settingsBox.y).toBeGreaterThanOrEqual(0) + expect(settingsBox.x + settingsBox.width).toBeLessThanOrEqual(390) + expect(settingsBox.y + settingsBox.height).toBeLessThanOrEqual(844) + const closeSettings = settings.getByRole('button', { name: 'Close', exact: true }) + const closeBox = (await closeSettings.boundingBox())! + expect(closeBox.y).toBeGreaterThanOrEqual(0) + expect(closeBox.y + closeBox.height).toBeLessThanOrEqual(844) + await closeSettings.tap() + await settings.waitFor({ state: 'hidden' }) + await expect.poll(() => searchWithKeyboard.inputValue()).toBe('retained search') + await restoreViewport.evaluate((restore) => { restore() }) + await restoreViewport.dispose() + await expect.poll(() => root.boundingBox()).toEqual({ x: 0, y: 0, width: 390, height: 844 }) + await expect.poll(async () => (await drawer.boundingBox())?.height).toBe(844) + await frame.evaluate((el) => { el.scrollLeft = 10 }) + expect(await frame.evaluate(el => el.scrollLeft)).toBe(0) + await expect.poll(() => mask.boundingBox()).toEqual({ x: 0, y: 0, width: 390, height: 844 }) + await expect.poll(() => drawer.evaluate((el) => { + const frame = el.closest('[data-sidebar-drawer]')! + let column = el + while (column.parentElement !== frame) column = column.parentElement! + const { y, height } = column.getBoundingClientRect() + return { y, height } + })).toEqual({ y: 0, height: 844 }) + await expect.poll(async () => (await drawer.boundingBox())?.height).toBe(844) + await page.setViewportSize({ width: 844, height: 390 }) + await expect.poll(async () => (await root.boundingBox())?.height).toBe(390) + await expect.poll(() => frame.count()).toBe(0) + await page.setViewportSize({ width: 390, height: 844 }) + await expect.poll(async () => (await root.boundingBox())?.height).toBe(844) + await expect.poll(() => frame.count()).toBe(1) + + const posture = await page.context().newCDPSession(page) + try { + await page.setViewportSize({ width: 951, height: 669 }) + await expect.poll(() => frame.count()).toBe(0) + await posture.send('Emulation.setDevicePostureOverride', { posture: { type: 'folded' } }) + await opener.tap() + await expect.poll(() => main.boundingBox()).toEqual({ x: 475.5, y: 0, width: 475.5, height: 669 }) + expect(await page.locator('[data-side="sidebar"]').count()).toBe(0) + const foldSearch = page.getByPlaceholder('Search session names') + if (!(await foldSearch.isVisible())) await page.getByRole('button', { name: 'Search sessions', exact: true }).tap() + await foldSearch.fill('fold search') + const wideFrame = page.locator('[data-rightbar-collapsed]') + const collapseSidebar = page.getByRole('button', { name: 'Collapse sidebar', exact: true }) + await wideFrame.evaluate((el) => { el.style.setProperty('--ds-transition-duration-slow', '100s') }) + await posture.send('Emulation.clearDevicePostureOverride') + await assertFoldResize(collapseSidebar, 475.5, 280) + await expect.poll(() => main.boundingBox()).toEqual({ x: 280, y: 0, width: 671, height: 669 }) + expect(await page.locator('[data-side="sidebar"]').count()).toBe(1) + expect(await foldSearch.evaluate(el => el === document.activeElement)).toBe(true) + expect(await foldSearch.inputValue()).toBe('fold search') + await wideFrame.evaluate((el) => { el.style.setProperty('--ds-transition-duration-slow', '100s') }) + await posture.send('Emulation.setDevicePostureOverride', { posture: { type: 'folded' } }) + await assertFoldResize(collapseSidebar, 280, 475.5) + await expect.poll(async () => (await main.boundingBox())?.x).toBe(475.5) + expect(await foldSearch.evaluate(el => el === document.activeElement)).toBe(true) + await page.emulateMedia({ reducedMotion: 'reduce' }) + await posture.send('Emulation.clearDevicePostureOverride') + await expect.poll(async () => (await main.boundingBox())?.x).toBe(280) + // Scroll-driven text fades remain registered even with reduced motion. + expect(await wideFrame.evaluate(el => el.getAnimations({ subtree: true }) + .filter(animation => animation.timeline === document.timeline).length)).toBe(0) + await posture.send('Emulation.setDevicePostureOverride', { posture: { type: 'folded' } }) + await expect.poll(async () => (await main.boundingBox())?.x).toBe(475.5) + await page.emulateMedia({ reducedMotion: 'no-preference' }) + await page.setViewportSize({ width: 669, height: 951 }) + await expect.poll(() => frame.getAttribute('data-sidebar-collapsed')).toBe('true') + await drawer.waitFor({ state: 'hidden' }) + await opener.tap() + await expect.poll(async () => (await drawer.boundingBox())?.width).toBe(280) + expect(await main.boundingBox()).toEqual({ x: 0, y: 0, width: 669, height: 951 }) + } finally { + await posture.detach() + } + + const pointerPage = await browser.newPage({ viewport: { width: 390, height: 844 }, locale: 'en-US' }) + try { + await pointerPage.goto(scaffold.authenticatedUrl) + await pointerPage.getByRole('button', { name: 'Open sidebar', exact: true }).click() + expect(await pointerPage.getByPlaceholder('Search session names').evaluate(el => getComputedStyle(el).fontSize)).toBe('13px') + const pointerWorkspace = pointerPage.locator('[data-row-key^="workspace:"]').first() + const pointerWorkspaceButtons = pointerWorkspace.getByRole('button', { includeHidden: true }) + await pointerWorkspace.click() + expect(await pointerWorkspace.getAttribute('aria-expanded')).toBe('false') + const collapseSidebar = pointerPage.getByRole('button', { name: 'Collapse sidebar', exact: true }) + await collapseSidebar.focus() + await collapseSidebar.hover() + for (const button of await pointerWorkspaceButtons.all()) expect(await button.isVisible()).toBe(false) + await pointerWorkspace.hover() + for (const button of await pointerWorkspaceButtons.all()) await button.waitFor() + await pointerWorkspace.click() + for (const label of ['Collapse sidebar', 'View options']) { + await pointerPage.getByRole('button', { name: label, exact: true }).hover() + const tooltip = pointerPage.getByRole('tooltip').filter({ hasText: label }) + await tooltip.waitFor() + expect(await tooltip.evaluate(el => el.closest('[data-slot="sidebar"]'))).toBeNull() + const box = (await tooltip.boundingBox())! + expect(box.x).toBeGreaterThanOrEqual(12) + expect(box.x + box.width).toBeLessThanOrEqual(378) + } + const pointerRow = pointerPage.getByRole('treeitem').filter({ has: pointerPage.getByText('Drawer navigation', { exact: true }) }) + await pointerRow.click() + await pointerPage.getByRole('dialog', { name: 'Navigation', exact: true }).waitFor({ state: 'hidden' }) + await pointerPage.getByRole('button', { name: 'Open sidebar', exact: true }).click() + await pointerPage.getByRole('button', { name: 'Collapse sidebar', exact: true }).hover() + await expect.poll(() => pointerRow.getByRole('button', { name: 'Session actions for Drawer navigation', exact: true }).isVisible()).toBe(false) + await pointerRow.hover() + for (const label of ['Session actions for Drawer navigation', 'Archive session', 'Pin session']) { + await pointerRow.getByRole('button', { name: label, exact: true }).waitFor() + } + await pointerPage.getByRole('button', { name: 'Collapse sidebar', exact: true }).click() + const pointerDrawer = pointerPage.getByRole('dialog', { name: 'Navigation', exact: true }) + await pointerDrawer.waitFor({ state: 'hidden' }) + await pointerPage.setViewportSize({ width: 767, height: 844 }) + await pointerPage.getByRole('button', { name: 'Open sidebar', exact: true }).press('Enter') + await pointerDrawer.waitFor() + expect(await pointerDrawer.evaluate(el => el.contains(document.activeElement))).toBe(true) + await pointerPage.getByRole('button', { name: 'Search sessions', exact: true }).click() + await expect.poll(() => pointerPage.getByPlaceholder('Search session names') + .evaluate(el => el === document.activeElement)).toBe(true) + await pointerPage.setViewportSize({ width: 768, height: 844 }) + await pointerPage.locator('[data-sidebar-drawer]').waitFor({ state: 'detached' }) + const pointerSidebar = pointerPage.locator('[data-slot="sidebar"]') + await expect.poll(() => pointerSidebar.getByRole('button', { name: 'New session', exact: true }).count()).toBe(1) + const railToggle = pointerSidebar.getByRole('button', { name: 'Open sidebar', exact: true }) + expect(await railToggle.evaluate(el => el === document.activeElement)).toBe(true) + } finally { + await pointerPage.close() + } + expect(console.pageErrors).toEqual([]) + expect(console.warnings).toEqual([]) + const result = [ + '390px: closed sidebar has no rail; main width 390px', + 'open: main geometry retained; background inert; no resize handle', + 'close: Session navigation, Plugins navigation, mask and Escape', + 'retained: sidebar DOM and opener focus', + '768px: 56px rail; main width 712px; drawer focus transfers to the rail toggle', + 'breakpoint motion: collapsed rail hides immediately and returns compact without crossfades; expanded sidebar and explicit toggles retain their slides', + '767px: hidden drawer; main width 767px; no page overflow', + 'global panels: browser top inset 48px; macOS keeps its existing clearance', + 'tooltips: sidebar and workspace controls escape the drawer and fit the viewport', + 'search input: 16px on touch; 13px with a fine pointer', + 'simulated keyboard: homepage and drawer retain 844px layout height without following the 360px visual viewport; Settings stays within the viewport', + 'keyboard close: layout height stays 844px; sidebar search retained; Settings close remains reachable', + 'shell coverage: drawer backing and mask cover 844px without synthetic safe-area insets', + 'rotation: 844x390 then 390x844 restores shell height and sidebar breakpoint', + 'folded landscape: 951px frame splits at 475.5px without a resize handle; unfolding restores 280px and search focus; portrait retains the drawer', + 'fold transitions: sidebar controls follow the divider in both directions; reduced motion changes width without animation', + 'drawer mask: opacity transitions from 0 to 1 on open and 1 to 0 on close', + 'reduced motion: drawer and mask settle without transitions', + 'Web header: only the sidebar opener remains, with 48px leading clearance', + 'below 768px: plugin and automation pages use 20px insets; Web view tabs align at 20px, while Desktop and wider Web tabs retain 28px', + 'touch selected Session: More remains visible; update time is hidden; pinned rows offer Unpin before More with Workspace action spacing', + 'touch Workspace: actions appear only while expanded, including after folding the focused row', + 'fine pointer: folded Workspace actions remain available on hover', + 'fine pointer: selected Session actions stay hidden until hover, including at 390px', + ].join('\n') + await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-drawer.expected.md', import.meta.url)), result, webSnapshotMode()) + } finally { + await browser.close() + } + } finally { + await scaffold.close() + } +}) + +it('dismisses retained sidebar menus at the drawer breakpoint and preserves their rows', async () => { + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + }) + try { + const workspace = await scaffold.ctx.workspaceRegistry.create(scaffold.workspaceCwd) + const seed = await readFile(new URL('../../../snapshots/web/seeded-history/session.v3.jsonl', import.meta.url), 'utf8') + const sessionId = await seedSession(scaffold, seed, 'session-c4421b66-252e-44c0-80ed-6e320abeba25') + await workspace.attachSession(sessionId) + await scaffold.ctx.sessionController.rename({ sessionId, title: 'Menu regression' }) + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 1024, height: 844 }, locale: 'en-US' }) + await page.goto(scaffold.authenticatedUrl) + const row = page.locator(`[data-row-key="session:${sessionId}"]`) + await row.waitFor() + const original = await row.elementHandle() + for (const label of ['View options', 'Session actions for Menu regression']) { + await page.setViewportSize({ width: 1024, height: 844 }) + await page.getByRole('button', { name: 'Collapse sidebar', exact: true }).waitFor() + if (label.startsWith('Session')) await row.hover() + await page.getByRole('button', { name: label, exact: true }).click() + await page.getByRole('menu').waitFor() + await page.setViewportSize({ width: 767, height: 844 }) + await page.getByRole('menu').waitFor({ state: 'hidden' }) + const opener = page.getByRole('button', { name: 'Open sidebar', exact: true }) + await expect.poll(() => opener.evaluate(element => element === document.activeElement)).toBe(true) + await opener.click() + await row.waitFor() + expect(await row.evaluate((element, before) => element === before, original)).toBe(true) + } + await original?.dispose() + await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-menu-dismissal.expected.md', import.meta.url)), [ + 'View options and Session menus close when the sidebar becomes an inert drawer.', + 'Focus returns to the visible sidebar opener; retained Session rows keep their DOM identity.', + ].join('\n'), webSnapshotMode()) + } finally { await browser.close() } + } finally { await scaffold.close() } +}) + +it('keeps drawer shortcuts and hit targets above fullscreen and floating right panels', async () => { + const scaffold = await launchWebScaffold({ + extraOverlayPath: fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)), + }) + try { + const workspace = await scaffold.ctx.workspaceRegistry.create(scaffold.workspaceCwd) + const seed = await readFile(new URL('../../../snapshots/web/seeded-history/session.v3.jsonl', import.meta.url), 'utf8') + const sessionId = await seedSession(scaffold, seed, 'session-c4421b66-252e-44c0-80ed-6e320abeba25') + await workspace.attachSession(sessionId) + await scaffold.ctx.sessionController.rename({ sessionId, title: 'Drawer overlay checks' }) + const browser = await chromium.launch() + try { + const page = await browser.newPage({ viewport: { width: 1280, height: 844 }, locale: 'en-US' }) + await page.addInitScript(() => { Object.defineProperty(navigator, 'platform', { value: 'MacIntel' }) }) + await page.goto(scaffold.authenticatedUrl) + const row = page.getByRole('treeitem').filter({ has: page.getByText('Drawer overlay checks', { exact: true }) }) + await row.click() + await page.locator('[data-sidebar-right-expand]').click() + await page.locator('[data-sidebar-right-guide-entry="files"]').click() + const panel = page.locator('[data-sidebar-right-open]') + const primary = await page.evaluate(() => /mac/i.test(navigator.platform) ? 'Meta' : 'Control') + const toggle = `${primary}+Alt+b` + await row.hover() + const card = page.getByRole('button', { name: 'Copy: Drawer overlay checks', exact: true }) + await card.waitFor() + await page.setViewportSize({ width: 390, height: 844 }) + await card.waitFor({ state: 'hidden' }) + expect(await row.count()).toBe(1) + const drawer = page.getByRole('dialog', { name: 'Navigation', exact: true }) + await expect.poll(() => panel.getAttribute('data-sidebar-right-panel')).toBe('fullscreen') + const assertAboveRightPanel = async (coveredPoint?: { x: number; y: number }) => { + await page.locator('[data-sidebar-drawer][data-sidebar-collapsed]').waitFor() + await page.keyboard.press(toggle) + await drawer.waitFor() + const collapse = drawer.getByRole('button', { name: 'Collapse sidebar', exact: true }) + await expect.poll(() => collapse.evaluate(el => document.activeElement === el)).toBe(true) + await expect.poll(() => drawer.evaluate((el) => { + const box = el.getBoundingClientRect() + return el.contains(document.elementFromPoint(box.left + 140, 30)) + })).toBe(true) + expect(await page.evaluate(() => document.elementFromPoint(380, 420)?.hasAttribute('data-sidebar-mask'))).toBe(true) + if (coveredPoint !== undefined) { + expect(await drawer.evaluate((el, point) => { + const hit = document.elementFromPoint(point.x, point.y) + return el.contains(hit) || hit?.hasAttribute('data-sidebar-mask') + }, coveredPoint)).toBe(true) + } + await page.keyboard.press(`${primary}+Alt+k`) + await expect.poll(() => drawer.getByPlaceholder('Search session names').evaluate(el => document.activeElement === el)).toBe(true) + await page.keyboard.press(toggle) + await drawer.waitFor({ state: 'hidden' }) + expect(await panel.evaluate(el => el.closest('[inert]') === null)).toBe(true) + } + await page.keyboard.press(`${primary}+Alt+k`) + await drawer.waitFor() + await expect.poll(() => drawer.getByPlaceholder('Search session names') + .evaluate(el => el === document.activeElement)).toBe(true) + await page.keyboard.press(toggle) + await drawer.waitFor({ state: 'hidden' }) + await assertAboveRightPanel() + await page.setViewportSize({ width: 1280, height: 844 }) + await expect.poll(() => panel.getAttribute('data-sidebar-right-panel')).toBe('push') + const tab = panel.locator('[data-dockkit-tab]').filter({ hasText: 'Files' }) + const bounds = (await tab.boundingBox())! + await page.mouse.move(bounds.x + 6, bounds.y + bounds.height / 2) + await page.mouse.down() + try { + await page.mouse.move(190, 400, { steps: 8 }) + } finally { await page.mouse.up() } + const floating = page.locator('[data-dockkit-float]') + await floating.waitFor() + await page.setViewportSize({ width: 390, height: 844 }) + const box = (await floating.boundingBox())! + expect(box.x).toBeLessThan(390) + expect(box.x + box.width).toBeGreaterThan(0) + const point = { x: (Math.max(0, box.x) + Math.min(390, box.x + box.width)) / 2, y: box.y + 40 } + await expect.poll(() => floating.evaluate((el, at) => el.contains(document.elementFromPoint(at.x, at.y)), point)).toBe(true) + await assertAboveRightPanel(point) + } finally { + await browser.close() + } + } finally { + await scaffold.close() + } +}) diff --git a/apps/web/tests/sidebar-right.e2e.ts b/apps/web/tests/sidebar-right.e2e.ts index 79fc706ec9..064adbb620 100644 --- a/apps/web/tests/sidebar-right.e2e.ts +++ b/apps/web/tests/sidebar-right.e2e.ts @@ -1046,6 +1046,92 @@ describe('web e2e: shipped right Sidebar', () => { expect(tripwire.warnings).toEqual([]) }, 90_000) + it('resists a floating panel dragged past the viewport edges and springs it back inside', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-float-edge')) + const column = await resetSidebar(page) + const floats = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]') + await proseChip(page).click() + await expect.poll(async () => await tabTitles(paneAt(column, 0))).toEqual(['Files', SAMPLE_NAME]) + await floatByDrag(page, paneAt(column, 0).locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME })) + await expect.poll(async () => await floats.count()).toBe(1) + const panel = floats.first() + const viewport = page.viewportSize() + if (viewport === null) throw new Error('page has no viewport') + + // Carrying the grip to the bottom-right corner asks for the panel well past both edges. + const grip = await centre(panel.locator('[data-dockkit-float-grip]')) + await page.mouse.move(grip.x, grip.y) + await page.mouse.down() + await page.mouse.move(viewport.width - 2, viewport.height - 2, { steps: 8 }) + const pushed = await panel.boundingBox() + if (pushed === null) throw new Error('float is not rendered') + expect(pushed.x + pushed.width).toBeGreaterThan(viewport.width) + expect(pushed.x + pushed.width).toBeLessThan(viewport.width + 120) + expect(pushed.y + pushed.height).toBeGreaterThan(viewport.height) + expect(pushed.y + pushed.height).toBeLessThan(viewport.height + 120) + await page.mouse.up() + + // The return overshoots inward and can pass the edges before it ends, so + // wait for the resting style, which drops the inline position. + await expect.poll(async () => await panel.evaluate(node => (node as HTMLElement).style.left)).toBe('') + const rest = await panel.boundingBox() + if (rest === null) throw new Error('float is not rendered') + expect({ right: Math.round(rest.x + rest.width), bottom: Math.round(rest.y + rest.height) }) + .toEqual({ right: viewport.width, bottom: viewport.height }) + + // At rest the stylesheet clamps on its own: a rectangle published from a + // stale viewport reading, far outside and larger than the viewport, still + // draws inside it. + const clamped = await panel.evaluate((node) => { + const element = node as HTMLElement + for (const name of ['x', 'y', 'width', 'height']) element.style.setProperty(`--dsh-dockkit-float-${name}`, '5000px') + const box = element.getBoundingClientRect() + return { left: box.left, top: box.top, right: box.right, bottom: box.bottom } + }) + expect(clamped).toEqual({ left: 0, top: 0, right: viewport.width, bottom: viewport.height }) + + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 60_000) + + it('expands the collapsed column when a floating panel\'s dock control returns its tab', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-dock-expands')) + const column = await resetSidebar(page) + const floats = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]') + const open = column.locator('[data-sidebar-right-open]') + const selected = (): Promise => + column.locator('[role="tab"][aria-selected="true"] [data-dockkit-tab-title]').allTextContents() + await proseChip(page).click() + await expect.poll(async () => await tabTitles(paneAt(column, 0))).toEqual(['Files', SAMPLE_NAME]) + await floatByDrag(page, paneAt(column, 0).locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME })) + await expect.poll(async () => await floats.count()).toBe(1) + + // The docked column still holds Files while collapsed. + await column.locator('[data-sidebar-right-toggle]').click() + await expect.poll(async () => await open.count()).toBe(0) + await floats.first().locator('[data-dockkit-float-dock]').click() + await expect.poll(async () => await open.count()).toBe(1) + expect(await floats.count()).toBe(0) + await expect.poll(async () => await tabTitles(column)).toEqual(['Files', SAMPLE_NAME]) + await expect.poll(selected).toEqual([SAMPLE_NAME]) + + // Closing the column's only other tab collapses it empty; docking fills it with the tab alone. + await floatByDrag(page, column.locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME })) + await expect.poll(async () => await floats.count()).toBe(1) + const files = column.locator('[data-dockkit-tab]').filter({ hasText: 'Files' }) + await files.hover() + await files.locator('[data-dockkit-tab-close]').click() + await expect.poll(async () => await open.count()).toBe(0) + await floats.first().locator('[data-dockkit-float-dock]').click() + await expect.poll(async () => await open.count()).toBe(1) + expect(await floats.count()).toBe(0) + await expect.poll(async () => await tabTitles(column)).toEqual([SAMPLE_NAME]) + await expect.poll(selected).toEqual([SAMPLE_NAME]) + + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 60_000) + it('drops a pane whose last tab closes, and follows the last-tab rule on the surface', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-settle')) const column = await resetSidebar(page) @@ -1080,8 +1166,28 @@ describe('web e2e: shipped right Sidebar', () => { expect(await column.locator('[data-dockkit-tab-close]').count()).toBe(0) expect(await column.locator('[data-dockkit-tab-quiet]').count()).toBe(1) await column.locator('[data-dockkit-tab]').first().click({ button: 'right' }) - expect(await page.locator('[data-dockkit-tab-menu]').isVisible()).toBe(false) + // Wait for prepared content, rather than passing before the opening delay. + const emptyMenu = page.locator('[data-context-menu][role="menu"]') + await emptyMenu.waitFor({ state: 'attached' }) + expect(await emptyMenu.evaluate(node => getComputedStyle(node).display)).toBe('none') + expect(await emptyMenu.isVisible()).toBe(false) expect(await page.getByRole('menu').count()).toBe(0) + expect(await column.locator('[data-dockkit-tab]').first().evaluate(node => node.contains(document.activeElement))).toBe(true) + const backingSize = await page.locator('[data-menu-backing]').evaluate((node) => { + const root = document.documentElement + const platform = root.getAttribute('data-platform') + root.setAttribute('data-platform', 'darwin') + try { + const { width, height } = node.getBoundingClientRect() + return { width, height } + } finally { + if (platform === null) root.removeAttribute('data-platform') + else root.setAttribute('data-platform', platform) + } + }) + expect(backingSize).toEqual({ width: 0, height: 0 }) + await page.keyboard.press('Escape') + await emptyMenu.waitFor({ state: 'detached' }) // Any other tab standing alone closes together with the column. Open the // sample file, close the guide (an ordinary close with two tabs), then @@ -1183,13 +1289,10 @@ describe('web e2e: shipped right Sidebar', () => { // is the secondary press. expect(await column.locator('[data-dockkit-tab-more]').count()).toBe(0) await column.locator('[data-dockkit-tab]').filter({ hasText: 'Start' }).click({ button: 'right' }) - const menu = page.locator('[data-dockkit-tab-menu]') + const menu = page.locator('[data-context-menu][role="menu"]') await expect.poll(async () => await menu.count()).toBe(1) - // The kit's one item; the extension seat is declared and rendered, and - // with no registrant it contributes nothing, which is what "declared, not - // speculative" looks like from the outside. - await expect.poll(async () => await menu.getByRole('menuitem').allInnerTexts()).toEqual(['Close']) + await expect.poll(() => menu.ariaSnapshot()).toBe('- menu:\n - menuitem "Close"\n - menuitem "Close Other Tabs"') // The menu hangs below the strip that clips its overflow. Its pixels are // its own: a hit test at its centre lands on it, not on whatever the // strip would have shown through a clipped box. diff --git a/apps/web/tests/sidebar-scrollbar.e2e.ts b/apps/web/tests/sidebar-scrollbar.e2e.ts index f15a893682..afcedbf0ca 100644 --- a/apps/web/tests/sidebar-scrollbar.e2e.ts +++ b/apps/web/tests/sidebar-scrollbar.e2e.ts @@ -37,6 +37,7 @@ interface ListMetrics { band: number scrollbarEdgeOffset: number rowEdgeInset: number + rowPaintInset: number clientRight: number borderRight: number timeRight: number @@ -93,8 +94,8 @@ function measureList(page: Page): Promise { const pseudoWidth = getComputedStyle(list, '::-webkit-scrollbar').width const barWidth = pseudoWidth === 'auto' ? 15 : Number.parseFloat(pseudoWidth) const listRect = list.getBoundingClientRect() - const sidebarEdge = list.parentElement?.getBoundingClientRect().right - if (sidebarEdge === undefined) throw new Error('sidebar session list has no layout parent') + const listParentRight = list.parentElement?.getBoundingClientRect().right + if (listParentRight === undefined) throw new Error('sidebar session list has no layout parent') return { gutter: style.scrollbarGutter, width: pseudoWidth, @@ -106,8 +107,9 @@ function measureList(page: Page): Promise { hoverToken: resolve('--dsh-scrollbar-thumb-hover'), overflows: list.scrollHeight > list.clientHeight, band: listRect.width - list.clientWidth, - scrollbarEdgeOffset: sidebarEdge - listRect.right, - rowEdgeInset: sidebarEdge - row.getBoundingClientRect().right, + scrollbarEdgeOffset: listParentRight - listRect.right, + rowEdgeInset: listParentRight - row.getBoundingClientRect().right, + rowPaintInset: listParentRight - row.getBoundingClientRect().right + Number.parseFloat(getComputedStyle(row).borderRightWidth), clientRight: listRect.left + list.clientWidth, borderRight: listRect.right, timeRight: time.getBoundingClientRect().right, @@ -129,17 +131,18 @@ function measureList(page: Page): Promise { * @param page - the page under test. * @returns the list overflow state and first row's trailing inset. */ -function measureRowInset(page: Page): Promise> { +function measureRowInset(page: Page): Promise> { return page.evaluate(() => { const list = document.querySelector('[role="tree"][aria-label="Sessions"]') if (list === null) throw new Error('sidebar session list not in the DOM') const row = list.querySelector('[role="treeitem"]') if (row === null) throw new Error('no row in the sidebar list') - const sidebarEdge = list.parentElement?.getBoundingClientRect().right - if (sidebarEdge === undefined) throw new Error('sidebar session list has no layout parent') + const listParentRight = list.parentElement?.getBoundingClientRect().right + if (listParentRight === undefined) throw new Error('sidebar session list has no layout parent') return { overflows: list.scrollHeight > list.clientHeight, - rowEdgeInset: sidebarEdge - row.getBoundingClientRect().right, + rowEdgeInset: listParentRight - row.getBoundingClientRect().right, + rowPaintInset: listParentRight - row.getBoundingClientRect().right + Number.parseFloat(getComputedStyle(row).borderRightWidth), } }) } @@ -192,8 +195,9 @@ function renderGeometry(light: PaletteMetrics, dark: PaletteMetrics): string { `- --dsh-scrollbar-thumb-hover, pointer over the list: ${metrics.hoverToken}`, `- list overflows: ${String(metrics.overflows)}`, `- reserved band: ${String(metrics.band)}px`, - `- scrollbar inset from the sidebar edge: ${String(metrics.scrollbarEdgeOffset)}px`, - `- row background inset from the sidebar edge: ${String(metrics.rowEdgeInset)}px`, + `- scrollbar inset from the list parent edge: ${String(metrics.scrollbarEdgeOffset)}px`, + `- row hitbox inset from the list parent edge: ${String(metrics.rowEdgeInset)}px`, + `- row background inset from the list parent edge: ${String(metrics.rowPaintInset)}px`, `- relative time covered by the bar: ${String(metrics.timeCoveredBy)}px`, `- relative time ends inside the content area: ${String(metrics.timeRight <= metrics.clientRight)}`, `- content area ends before the border box: ${String(metrics.clientRight < metrics.borderRight)}`, @@ -321,7 +325,8 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum // Pin presence, not width, because the width is platform-dependent. expect(metrics.band).toBeGreaterThan(0) expect(metrics.scrollbarEdgeOffset).toBe(2) - expect(metrics.rowEdgeInset).toBe(12) + expect(metrics.rowEdgeInset).toBe(8) + expect(metrics.rowPaintInset).toBe(11) // Measure against the bar because overlay scrollbars do not move the client edge. expect(metrics.timeCoveredBy).toBe(0) expect(metrics.timeRight).toBeLessThanOrEqual(metrics.clientRight) @@ -359,12 +364,12 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum it('keeps the row background inset when overflow disappears', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-scrollbar-stable-inset')) - expect(await measureRowInset(page)).toEqual({ overflows: true, rowEdgeInset: 12 }) + expect(await measureRowInset(page)).toEqual({ overflows: true, rowEdgeInset: 8, rowPaintInset: 11 }) const bucket = page.getByText('Ungrouped', { exact: true }).locator('..').locator('..') await bucket.click() try { await expect.poll(async () => (await measureRowInset(page)).overflows, { timeout: 10_000 }).toBe(false) - expect(await measureRowInset(page)).toEqual({ overflows: false, rowEdgeInset: 12 }) + expect(await measureRowInset(page)).toEqual({ overflows: false, rowEdgeInset: 8, rowPaintInset: 11 }) } finally { await expandSeededSessions(page) } diff --git a/apps/web/tests/sidebar-terminal.e2e.ts b/apps/web/tests/sidebar-terminal.e2e.ts index 6709a336ab..6ca14145f2 100644 --- a/apps/web/tests/sidebar-terminal.e2e.ts +++ b/apps/web/tests/sidebar-terminal.e2e.ts @@ -681,7 +681,7 @@ describe.skipIf(process.platform === 'win32')('Web sidebar terminal', () => { await expect.poll(() => page.locator('.xterm-rows:visible').innerText()).toContain('RECONNECT_READY') const transport = await controlTransport(page) await page.reload({ waitUntil: 'load' }) - await expect.poll(() => page.locator('.xterm-rows:visible').innerText()).toContain('RECONNECT_READY') + await page.locator('.xterm-rows:visible').filter({ hasText: 'RECONNECT_READY' }).waitFor({ timeout: 30_000 }) await transport.disconnect() const reconnect = page.getByRole('button', { name: 'Reconnect', exact: true }) await reconnect.waitFor() diff --git a/apps/web/tests/snapshots/client-ui-stats-panel/panel.expected.md b/apps/web/tests/snapshots/client-ui-stats-panel/panel.expected.md new file mode 100644 index 0000000000..e410795800 --- /dev/null +++ b/apps/web/tests/snapshots/client-ui-stats-panel/panel.expected.md @@ -0,0 +1,43 @@ +- table "Statistics": + - rowgroup: + - row "Turn / step Trigger Execution Context Output Cache hit First token Model time Output speed Tool time Total time": + - columnheader "Turn / step" + - columnheader "Trigger" + - columnheader "Execution" + - columnheader "Context" + - columnheader "Output" + - columnheader "Cache hit" + - columnheader "First token" + - columnheader "Model time" + - columnheader "Output speed" + - columnheader "Tool time" + - columnheader "Total time" + - rowgroup: + - row "Expand or collapse turn 1 · 01-15 {{clock}} Show the measured round. read ×1 → 7 chars 5.2K 0.24K 69.23% {{ttft}} {{duration}} {{tps}} {{duration}} {{duration}}": + - cell "Expand or collapse turn 1 · 01-15 {{clock}}": + - button "Expand or collapse turn 1" [expanded]: Turn 1 + - text: · 01-15 {{clock}} + - cell "Show the measured round." + - cell "read ×1 → 7 chars" + - cell "5.2K" + - cell "0.24K" + - cell "69.23%" + - cell "{{ttft}}" + - cell "{{duration}}" + - cell "{{tps}}" + - cell "{{duration}}" + - cell "{{duration}}" + - row "Expand or collapse the tool details of step 1 · details 01-15 {{clock}} read /work/notes.md 2 lines 5.2K 0.24K 69.23% {{ttft}} {{duration}} {{tps}} {{duration}} {{duration}}": + - cell "Expand or collapse the tool details of step 1 · details": + - button "Expand or collapse the tool details of step 1": Step 1 + - text: · details + - cell "01-15 {{clock}}" + - cell "read /work/notes.md 2 lines" + - cell "5.2K" + - cell "0.24K" + - cell "69.23%" + - cell "{{ttft}}" + - cell "{{duration}}" + - cell "{{tps}}" + - cell "{{duration}}" + - cell "{{duration}}" diff --git a/apps/web/tests/startup-rpc-budget.e2e.ts b/apps/web/tests/startup-rpc-budget.e2e.ts index f6655ffbf3..80b2630328 100644 --- a/apps/web/tests/startup-rpc-budget.e2e.ts +++ b/apps/web/tests/startup-rpc-budget.e2e.ts @@ -1,6 +1,6 @@ -// Cold boot may issue at most two settings/describe calls regardless of client -// plugin count. No model call or replay fixture is involved. -import type { Browser, Page } from 'playwright' +// Cold boot bounds shared settings reads and the Web Search credential reads +// caused by their publication waves. No model call or replay fixture is involved. +import type { Browser, Page, Request, Route } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts' @@ -8,6 +8,8 @@ import { newEnglishPage } from './support.ts' /** One eager read plus one first-connection reset closes the pre-subscription commit window. */ const DESCRIBE_BUDGET = 2 +/** One eager Web Search credential read plus one per settings publication wave. */ +const WEB_SEARCH_CREDENTIAL_BUDGET = 3 let scaffold: WebScaffold let browser: Browser @@ -25,20 +27,58 @@ afterAll(async () => { }) describe('startup RPC budget', () => { - it('keeps cold-boot settings.describe at the mirror count', async () => { + it('keeps settings and Web Search credential reads at their publication counts', async () => { page = await newEnglishPage(browser) watchConsole(page) const calls: string[] = [] + const credentials: string[][] = [] + const pending = new Set() + const webSearchRequests = new Set() + const credentialStarted = Promise.withResolvers() + let settingsFinished = 0 + let webSearchFinished = 0 + // Both settings answers must reach the card after it subscribes, regardless + // of plugin load order. The eager credential request proves that subscription. + const holdSettings = async (route: Route): Promise => { + await credentialStarted.promise + await route.continue() + } + await page.route('**/api/settings/describe', holdSettings) page.on('request', (request) => { const url = new URL(request.url()) - if (url.pathname.startsWith('/api/')) calls.push(url.pathname.slice('/api/'.length)) + if (!url.pathname.startsWith('/api/')) return + const method = url.pathname.slice('/api/'.length) + calls.push(method) + pending.add(request) + if (method === 'credentials/describe') { + const body = request.postDataJSON() as { payload: { args: { refs: string[] } } } + const refs = body.payload.args.refs + credentials.push(refs) + // Models requests batch references; the Web Search card asks for this one key. + if (refs.length === 1 && refs[0] === 'DEEPSEEK_API_KEY') { + webSearchRequests.add(request) + credentialStarted.resolve(undefined) + } + } }) - await page.goto(scaffold.authenticatedUrl) - // Boot settles when the workspace picker is interactive; the trailing wait - // absorbs the first-connection reset wave the budget must include. - await page.getByRole('textbox', { name: 'Choose workspace' }).waitFor({ timeout: 30_000 }) - await page.waitForTimeout(3000) - const describeCount = calls.filter(method => method === 'settings/describe').length - expect(describeCount, `startup /api calls:\n${calls.join('\n')}`).toBe(DESCRIBE_BUDGET) + page.on('requestfinished', (request) => { + pending.delete(request) + if (new URL(request.url()).pathname === '/api/settings/describe') settingsFinished++ + if (webSearchRequests.has(request)) webSearchFinished++ + }) + page.on('requestfailed', request => pending.delete(request)) + try { + await page.goto(scaffold.authenticatedUrl) + await page.getByRole('textbox', { name: 'Choose workspace' }).waitFor({ timeout: 30_000 }) + await expect.poll(() => settingsFinished, { timeout: 30_000 }).toBeGreaterThanOrEqual(DESCRIBE_BUDGET) + await expect.poll(() => webSearchFinished, { timeout: 30_000 }).toBeGreaterThanOrEqual(WEB_SEARCH_CREDENTIAL_BUDGET) + await expect.poll(() => pending.size, { timeout: 30_000 }).toBe(0) + const describeCount = calls.filter(method => method === 'settings/describe').length + expect(describeCount, `startup /api calls:\n${calls.join('\n')}`).toBe(DESCRIBE_BUDGET) + expect(webSearchRequests.size, `startup credential references:\n${JSON.stringify(credentials)}`).toBe(WEB_SEARCH_CREDENTIAL_BUDGET) + } finally { + credentialStarted.resolve(undefined) + await page.unrouteAll({ behavior: 'wait' }) + } }) }) diff --git a/apps/web/tests/stats-truncated-tooltip.e2e.ts b/apps/web/tests/stats-truncated-tooltip.e2e.ts index 18e7d5e64c..fc3e25b419 100644 --- a/apps/web/tests/stats-truncated-tooltip.e2e.ts +++ b/apps/web/tests/stats-truncated-tooltip.e2e.ts @@ -92,7 +92,7 @@ describe('web e2e: truncated composer statistics', () => { const cut = () => label.evaluate(element => element.scrollWidth > element.clientWidth) expect(await cut()).toBe(false) - await page.setViewportSize({ width: 390, height: 900 }) + await page.setViewportSize({ width: 334, height: 900 }) await expect.poll(cut).toBe(true) await usagePill.hover() await expect.poll(() => tooltip.textContent()).toBe(USAGE_READING) diff --git a/apps/web/tests/submission-echo.e2e.ts b/apps/web/tests/submission-echo.e2e.ts index b8b93c4afa..a1401e9e9a 100644 --- a/apps/web/tests/submission-echo.e2e.ts +++ b/apps/web/tests/submission-echo.e2e.ts @@ -1,18 +1,17 @@ // @vitest-environment jsdom -// Local submission echo over the BUILT client graph (keyless RemoteMock -// transport): a text-plus-image send paints its echo bubble synchronously on -// the submit keystroke — before serialization, transport, or the fixture's -// durable admission — with the composer already cleared and editable, and the -// durable user/message replaces the echo without a duplicate. The fixture host -// echoes the prompt requestId as the durable source's rpcId, so the retirement -// path here is the production correlation, not a test hook. +// Submission echo over the BUILT client graph (keyless RemoteMock transport): +// a text-plus-image send stays in the read-only composer, with its image rail +// and a busy send control, until the fixture host accepts the prompt; only then +// does the composer clear, and the conversation shows the message once. The +// fixture host echoes the prompt requestId as the durable source's rpcId, so +// the reconciliation here is the production correlation, not a test hook. import { fireEvent, screen, waitFor } from '@testing-library/react' import { expect, it } from 'vitest' import { createAssembledSessionComposer, installAssembledBootEnv, mountAssembledApp } from './assembled-boot.ts' installAssembledBootEnv() -it('paints the submission echo on the send keystroke and swaps it for the durable node', async () => { +it('keeps a send in the composer until the Host accepts it and then shows the message once', async () => { const remote = mountAssembledApp() const composer = await createAssembledSessionComposer(remote) const image = new File([new Uint8Array([137, 80, 78, 71])], 'echoed.png', { type: 'image/png' }) @@ -33,30 +32,32 @@ it('paints the submission echo on the send keystroke and swaps it for the durabl await waitFor(() => { expect(composer.textContent).toBe('回显这条消息') }) fireEvent.keyDown(composer, { key: 'Enter' }) - // Synchronously after the keystroke: the echo bubble is in the flow with - // the draft text and the object-URL preview, while the prompt has not even - // been serialized yet (it starts after a paint yield). The composer is - // already cleared, editable, and free of the rail. - const echo = document.querySelector('[data-submission-echo]') - if (echo === null) throw new Error('submission echo missing on the send keystroke') - expect(echo.textContent).toContain('回显这条消息') - expect(echo.querySelector('img')?.getAttribute('src')?.split(':')[0]).toBe('blob') - expect(composer.textContent).toBe('') - expect(composer.getAttribute('contenteditable')).toBe('true') - expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).toBeNull() + // Synchronously after the keystroke, before the prompt is even serialized + // (it starts after a paint yield): the draft and its image stay in the + // read-only composer behind a busy send control, and the conversation shows + // nothing yet. + expect(document.querySelector('[data-submission-echo]')).toBeNull() + expect(composer.textContent).toBe('回显这条消息') + expect(composer.getAttribute('contenteditable')).toBe('false') + expect(document.querySelector('[role="group"][aria-label="Pending attachments"] img')).not.toBeNull() + expect(screen.getByRole('button', { name: 'Sending message' }).getAttribute('aria-busy')).toBe('true') - // The fixture's durable user/message (source.rpcId echoes the prompt - // requestId) replaces the echo: one bubble, no marker left, and the image - // now renders from the durable gallery. + // The Host accepts the prompt: the composer clears and becomes editable + // again, its rail is gone, and the durable user/message (source.rpcId + // echoes the prompt requestId) is the one bubble, its image rendering from + // the durable gallery. + await waitFor(() => { + expect(composer.textContent).toBe('') + expect(composer.getAttribute('contenteditable')).toBe('true') + expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).toBeNull() + }, { timeout: 10_000 }) await waitFor(() => { if (document.querySelector('[data-submission-echo]') !== null) { throw new Error('submission echo still present after the durable node arrived') } - }, { timeout: 10_000 }) - expect(screen.getAllByText('回显这条消息')).toHaveLength(1) - await waitFor(() => { if (document.querySelector('[data-align="end"] img') === null) { throw new Error('durable user gallery missing') } }, { timeout: 10_000 }) + expect(screen.getAllByText('回显这条消息')).toHaveLength(1) }) diff --git a/apps/web/tests/support.ts b/apps/web/tests/support.ts index ef7d3765c4..ad741f474d 100644 --- a/apps/web/tests/support.ts +++ b/apps/web/tests/support.ts @@ -1,5 +1,5 @@ // Shared plumbing for the web smoke tests (dist location, free port, failure shots). -import { existsSync, mkdirSync } from 'node:fs' +import { existsSync, mkdirSync, readFileSync } from 'node:fs' import { createServer } from 'node:net' import { createRequire } from 'node:module' import { join } from 'node:path' @@ -12,6 +12,17 @@ export const DIST_INDEX = fileURLToPath(new URL('../dist/index.html', import.met export const REPO_ROOT = fileURLToPath(new URL('../../..', import.meta.url)) +/** + * Read the `meta.description` an experimental bundle's plugin page shows for one locale. + * @param bundle - Package directory under `packages/experimental`. + * @param locale - Locale resource name, such as `en` or `zh`. + * @returns The description text from `locale/.json`. + */ +export function experimentalBundleDescription(bundle: string, locale: string): string { + const resource = JSON.parse(readFileSync(join(REPO_ROOT, 'packages/experimental', bundle, 'locale', `${locale}.json`), 'utf8')) as { meta: { description: string } } + return resource.meta.description +} + const installationRequire = createRequire(join(REPO_ROOT, 'apps/cli/package.json')) /** @@ -189,6 +200,23 @@ export function probeFreePort(): Promise { }) } +/** + * Open collapsed mobile navigation before using a sidebar action. + * @param page - browser page with the mounted sidebar. + * @param locale - current UI language. + */ +export async function revealNavigationDrawer(page: Page, locale: 'en' | 'zh' | 'ja'): Promise { + const drawer = await page.evaluate(() => window.innerWidth < 768 + && !document.documentElement.hasAttribute('data-windows-titlebar')) + await page.waitForFunction(expected => Boolean(document.querySelector('[data-sidebar-drawer]')) === expected, drawer) + const closed = page.locator('[data-sidebar-drawer][data-sidebar-collapsed]') + if (await closed.count() === 0) return + await page.locator('[data-shell-leading]').getByRole('button', { + name: { en: 'Open sidebar', zh: '打开侧边栏', ja: 'サイドバーを開く' }[locale], exact: true, + }).click() + await closed.waitFor({ state: 'detached' }) +} + /** * Drive the hero's workspace picker through the composed directory dialog * until the live composer unlocks. A fresh world has no Workspace, so the boot @@ -208,6 +236,7 @@ export function probeFreePort(): Promise { */ export async function connectFreshWorkspace(page: Page, root: string, name = 'workspace'): Promise { mkdirSync(join(root, name), { recursive: true }) + await revealNavigationDrawer(page, 'en') await page.getByRole('button', { name: 'Add workspace', exact: true }).click() const dialog = page.getByRole('dialog', { name: 'Select Workspace Directory' }) await dialog.waitFor({ timeout: 10_000 }) @@ -234,6 +263,7 @@ export async function connectFreshWorkspace(page: Page, root: string, name = 'wo */ export async function connectFreshWorkspaceZh(page: Page, root: string, name = 'workspace', modelAvailable = true): Promise { mkdirSync(join(root, name), { recursive: true }) + await revealNavigationDrawer(page, 'zh') await page.getByRole('button', { name: '添加工作区', exact: true }).click() const dialog = page.getByRole('dialog', { name: '选择工作区目录' }) await dialog.waitFor({ timeout: 10_000 }) @@ -335,6 +365,14 @@ export function conversationContextKey(kind: string, id: string): string { */ export async function openSettings(page: Page, locale: 'en' | 'zh' | 'ja'): Promise { const labels = { en: ['Account menu', 'Settings'], zh: ['账号菜单', '设置'], ja: ['アカウントメニュー', '設定'] } as const - await page.getByRole('button', { name: labels[locale][0], exact: true }).click() + const trigger = page.getByRole('button', { + name: labels[locale][0], exact: true, includeHidden: true, + }) + await trigger.waitFor({ state: 'attached' }) + await revealNavigationDrawer(page, locale) + if (!await trigger.isVisible()) { + await page.getByRole('button', { name: { en: 'Open sidebar', zh: '打开侧边栏', ja: 'サイドバーを開く' }[locale], exact: true }).click() + } + await trigger.click() await page.getByRole('menuitem', { name: labels[locale][1], exact: true }).click() } diff --git a/apps/web/tests/window-drag-coverage.e2e.ts b/apps/web/tests/window-drag-coverage.e2e.ts index cdbb727736..70fd84f7a1 100644 --- a/apps/web/tests/window-drag-coverage.e2e.ts +++ b/apps/web/tests/window-drag-coverage.e2e.ts @@ -107,10 +107,10 @@ async function collectedRegions(page: Page, selector: string): Promise { const top = document.elementFromPoint(x, y) - // A pane's programmatic focus target also contains its window-drag strip. - // The strip owns those pixels; controls inside it still need their own subtraction. - const strip = top?.closest('[data-dockkit-strip][data-window-drag]') - if (element.matches('[data-dockkit-pane][tabindex="-1"]') + // Panes and the navigation dialog contain their own window-drag rows. + // Those rows own their pixels; controls inside still subtract themselves. + const strip = top?.closest('[data-window-drag]') + if (element.matches('[data-dockkit-pane][tabindex="-1"], [data-shortcut-modal="sidebar"][role="dialog"]') && strip != null && element.contains(strip)) return false return top !== null && (top === element || element.contains(top)) }) @@ -231,6 +231,41 @@ describe('web e2e: macOS window drag coverage', () => { return { page, tripwire } } + it('keeps the macOS sidebar toggle stationary as its expanded content starts fading', async () => { + const { page, tripwire } = await desktopPage() + try { + const open = page.getByRole('button', { name: 'Open sidebar', exact: true }) + if (await open.isVisible()) await open.click() + const toggle = page.getByRole('button', { name: 'Collapse sidebar', exact: true }) + await toggle.waitFor() + const positions = await toggle.evaluate(async (button) => { + if (!(button instanceof HTMLButtonElement)) throw new Error('Sidebar toggle is not a button') + const root = button.closest('[class*="topStrip"]')!.parentElement! + const position = () => ({ + left: button.getBoundingClientRect().left - root.getBoundingClientRect().left, + transform: getComputedStyle(button).transform, + }) + const before = position() + // Observe the class change before the 150ms fade can settle under host contention. + const fading = await new Promise>((resolve) => { + const observer = new MutationObserver(() => { + if (![...root.classList].some(name => name.includes('fading'))) return + observer.disconnect() + resolve(position()) + }) + observer.observe(root, { attributes: true, attributeFilter: ['class'] }) + button.click() + }) + return { before, fading } + }) + expect(positions.before.transform).toBe('matrix(1, 0, 0, 1, 4, 0)') + expect(positions.fading).toEqual(positions.before) + expect(tripwire.pageErrors).toEqual([]) + } finally { + await page.close() + } + }) + it.each(['darwin', 'win32'] as const)('%s keeps compact Plugins controls below native chrome in both sidebar states', async (platform) => { const { page, tripwire } = await desktopPage(platform) try { @@ -468,6 +503,32 @@ describe('web e2e: macOS window drag coverage', () => { } }, 120_000) + it('keeps the drawer titlebar draggable without swallowing its close button', async () => { + const { page, tripwire } = await desktopPage() + try { + await page.setViewportSize({ width: 571, height: 696 }) + await page.locator('[data-sidebar-drawer][data-sidebar-collapsed]').waitFor() + await page.locator('[data-shell-leading]').getByRole('button', { name: 'Open sidebar', exact: true }).click() + const drawer = page.getByRole('dialog', { name: 'Navigation', exact: true }) + await drawer.waitFor() + await settled(page) + const toggle = drawer.getByRole('button', { name: 'Collapse sidebar', exact: true }) + const button = (await toggle.boundingBox())! + const seat = await rectOf(page, '[data-shell-leading]') + const regions = await collectedRegions(page, INTERACTIVE_SELECTOR) + const y = button.y + button.height / 2 + expect(isDraggableAt(regions, seat.x + seat.width / 2, y), 'the inactive header controls behind the drawer').toBe(true) + expect(isDraggableAt(regions, (seat.x + seat.width + button.x) / 2, y), 'the gap before the close button').toBe(true) + expect(isDraggableAt(regions, button.x + button.width / 2, y), 'the close button').toBe(false) + expect(swallowedBoxes(regions)).toEqual([]) + await toggle.click() + await drawer.waitFor({ state: 'hidden' }) + expect(tripwire.pageErrors).toEqual([]) + } finally { + await page.close() + } + }) + it('keeps an entry page’s chrome row draggable', async () => { const { page, tripwire } = await desktopPage() try { diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts index ba6cb7cbe3..096c159be4 100644 --- a/apps/web/tests/workspace-management.e2e.ts +++ b/apps/web/tests/workspace-management.e2e.ts @@ -567,7 +567,10 @@ describe('web e2e: workspace management (create / rename / grouping / hover affo const consoleWatch = watchConsole(hoverPage) await hoverPage.goto(scaffold.authenticatedUrl) const row = await seededSessionRow(hoverPage) + await row.click() + await hoverPage.getByText('DONE', { exact: true }).waitFor() const title = row.locator('[class*="title"]') + await expect.poll(() => title.innerText()).not.toBe('Untitled') const card = hoverPage.getByRole('button', { name: `Copy: ${await title.innerText()}` }) const tooltip = hoverPage.getByRole('tooltip') const observations: { stage: string; details: boolean; tooltips: string[] }[] = [] @@ -575,6 +578,7 @@ describe('web e2e: workspace management (create / rename / grouping / hover affo observations.push({ stage, details: await card.count() > 0, tooltips: await tooltip.allTextContents() }) } const clockStart = Date.now() + await hoverPage.getByRole('button', { name: 'Account menu', exact: true }).hover() await hoverPage.clock.install({ time: clockStart }) await hoverPage.clock.pauseAt(clockStart + 1000) await title.hover() @@ -612,9 +616,11 @@ describe('web e2e: workspace management (create / rename / grouping / hover affo const menu = row.getByRole('button', { name: /^Session actions for / }) await menu.click() + await hoverPage.clock.runFor(1000) await hoverPage.getByRole('menu').waitFor() expect(await card.count()).toBe(0) await hoverPage.keyboard.press('Escape') + await hoverPage.clock.runFor(1000) await hoverPage.getByRole('menu').waitFor({ state: 'detached' }) await title.hover() await hoverPage.clock.runFor(1600) @@ -821,8 +827,10 @@ describe('web e2e: workspace management (create / rename / grouping / hover affo await item.hover() await page.waitForTimeout(POINTER_HOLD_MS) expect(await page.getByRole('menuitem', { name: 'Rename' }).count()).toBe(1) - // Pointer-leave dismissal still applies once the pointer genuinely leaves. + // Context menus stay open across pointer departure and dismiss on an outside press. await page.getByRole('button', { name: 'Account menu', exact: true }).hover() + expect(await item.isVisible()).toBe(true) + await page.locator('[data-row-key]').first().click() await expect.poll(() => page.getByRole('menuitem', { name: 'Rename' }).count(), { timeout: 5_000 }).toBe(0) expect(tripwire.pageErrors).toEqual([]) }, 60_000) @@ -862,9 +870,8 @@ describe('web e2e: workspace management (create / rename / grouping / hover affo await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) acknowledgeReloadConnectionLoss(tripwire, warningStart) await expect.poll(() => page.getByText('Workspaces', { exact: true }).count(), { timeout: 15_000 }).toBe(1) - // Initial Workspace reconnection can focus the composer after the tree renders. - // Finish that navigation before the next test opens a path editor. - await page.locator('[role="treeitem"][aria-selected="true"]').waitFor({ timeout: 15_000 }) + // The last Session can leave the new-session page with no selected row. + // Wait for composer focus so reconnection cannot steal the next editor's focus. await expect.poll( () => page.locator('[data-composer-input][contenteditable="true"]') .evaluate(element => element === document.activeElement), diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 365d275118..7d094253a5 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -23,9 +23,11 @@ // this client-registered project must not also hold them (one program // cannot see both sides of the cordis Context merges). "exclude": [ + "tests/sidebar-drawer.e2e.ts", "tests/creation-recommendations.e2e.ts", "tests/plugin-recommendations.e2e.ts", "tests/japanese-plugin-metadata.e2e.ts", + "tests/context-menus.e2e.ts", "tests/additional-locales.e2e.ts", "tests/rich-text-quotes.e2e.ts", "tests/hover-input.e2e.ts", @@ -43,6 +45,7 @@ "tests/composer-shortcuts.e2e.ts", "tests/default-product-isolation.e2e.ts", "tests/diff-context.e2e.ts", + "tests/search-empty-include.e2e.ts", "tests/code-card-layout.e2e.ts", "tests/code-language.snapshot.ts", "tests/scaffold.ts", @@ -52,6 +55,7 @@ "tests/voice-input.e2e.ts", "tests/cot-translation.e2e.ts", "tests/cot-translation-paid.e2e.ts", + "tests/forge-panel.e2e.ts", "tests/voice-setup.e2e.ts", "tests/voice-download.e2e.ts", "tests/prefix-proxy.ts", @@ -65,6 +69,7 @@ "tests/subagent-fork-schedule.snapshot.ts", "tests/live-interactions.e2e.ts", "tests/question-composer.e2e.ts", + "tests/question-composer-recommended.e2e.ts", "tests/question-ptc.e2e.ts", "tests/approval-composer.e2e.ts", "tests/ptc-escalation.e2e.ts", @@ -84,6 +89,8 @@ "tests/details-session-lifecycle.e2e.ts", "tests/sessionless-header.e2e.ts", "tests/document-preview.e2e.ts", + "tests/file-browser.e2e.ts", + "tests/file-browser-composition.e2e.ts", "tests/excel-opc.e2e.ts", "tests/office-fixture.ts", "tests/sidebar-browser.e2e.ts", @@ -91,6 +98,7 @@ "tests/plugin-config.e2e.ts", "tests/input-plugin-extensions.e2e.ts", "tests/plugin-manager.e2e.ts", + "tests/plugin-market-toolbar.e2e.ts", "tests/plugin-sticky-motion.e2e.ts", "tests/entry-customization.e2e.ts", "tests/cua-optin.e2e.ts", @@ -110,6 +118,7 @@ "tests/plugin-hmr-lifecycle.e2e.ts", "tests/plugin-install-registry.e2e.ts", "tests/plugin-install-github.e2e.ts", + "tests/plugin-install-silent-failure.e2e.ts", "tests/client-plugin-live.e2e.ts", "tests/icon-skin.e2e.ts", "tests/draft-initialization.e2e.ts", @@ -124,7 +133,7 @@ "tests/developer-tools-settings.e2e.ts", "tests/models-settings.e2e.ts", "tests/deepseek-messages-settings.e2e.ts", - "tests/deepseek-model-label-1017.e2e.ts", + "tests/model-badge.e2e.ts", "tests/deepseek-messages-chat.e2e.ts", "tests/models-settings-recovery.e2e.ts", "tests/default-model.e2e.ts", @@ -155,6 +164,7 @@ "tests/stats-paged-history.e2e.ts", "tests/stats-truncated-tooltip.e2e.ts", "tests/sidebar-scrollbar.e2e.ts", + "tests/sidebar-alignment.e2e.ts", "tests/sidebar-title-hover-scroll.e2e.ts", "tests/rail-search-expand.e2e.ts", "tests/conversation-column-overflow.e2e.ts", @@ -162,6 +172,7 @@ "tests/present.e2e.ts", "tests/present-svg.e2e.ts", "tests/present-after-closing-reply.e2e.ts", + "tests/autolink-cjk-punctuation.e2e.ts", "tests/composer-draft-scroll.e2e.ts", "tests/composer-focus.e2e.ts", "tests/composer-placeholder.e2e.ts", @@ -185,6 +196,7 @@ "tests/markdown-inline-code-links.e2e.ts", "tests/clickable-links-gallery.e2e.ts", "tests/queue-actions.e2e.ts", + "tests/prompt-admission.e2e.ts", "tests/idle-submission-handoff.e2e.ts", "tests/cold-blank-session.e2e.ts", "tests/blank-writer-reuse.e2e.ts", @@ -202,6 +214,7 @@ "tests/feedback-command.e2e.ts", "tests/feedback-release.e2e.ts", "tests/agent-team-panel.e2e.ts", + "tests/client-ui-stats-panel.e2e.ts", "tests/sidebar-right.e2e.ts", "tests/sidebar-terminal.e2e.ts", "tests/startup-auto-selection.e2e.ts", diff --git a/benchmarks/conversation-fold/conversation-fold.bench.client.ts b/benchmarks/conversation-fold/conversation-fold.bench.client.ts index add5a34629..3ab528a616 100644 --- a/benchmarks/conversation-fold/conversation-fold.bench.client.ts +++ b/benchmarks/conversation-fold/conversation-fold.bench.client.ts @@ -1,4 +1,4 @@ -/** Required performance budgets for compiled Client history folding and tool preparation. */ +/** Required performance budgets for compiled Client history folding and live Assistant updates. */ import { join } from 'node:path' import { describe, expect, it } from 'vitest' @@ -10,8 +10,8 @@ import { ciTimeBudget, PERFORMANCE_BUDGET_HEADROOM, } from '../support/calibration.ts' -import { recordTimings, type BenchmarkCase } from '../support/scaling-report.ts' -import type { ConversationFoldWorkerReport, PreparingToolWorkerReport } from './conversation-fold.worker.client.ts' +import { recordPeakMemory, recordTimings, type BenchmarkCase } from '../support/scaling-report.ts' +import type { ConversationFoldWorkerReport, PreparingToolWorkerReport, StreamingAssistantWorkerReport } from './conversation-fold.worker.client.ts' /** Replies in the folded window; each carries one reasoning block and one text block. */ const TURNS = 200 @@ -54,6 +54,20 @@ const PREPARING_CASES = [ { tool: 'bash', characters: 128 * 1024, expectedMs: 150, expectedMb: 8 }, ] as const +const STREAMING_CHARACTERS = 256 * 1024 +const STREAMING_SAMPLES = 5 +/** Reference-machine expectations; shared CI scaling applies only to elapsed time. */ +const STREAMING_WORKLOADS = [ + { fragments: 4_096, expectedMs: 12 }, + { fragments: 16_384, expectedMs: 32 }, +] as const +const STREAMING_CASES = STREAMING_WORKLOADS.flatMap(workload => [ + { ...workload, blockType: 'text', pattern: 'ordinary' }, + { ...workload, blockType: 'reasoning', pattern: 'leading-whitespace' }, +] as const) +/** Incremental heap while the Assembler, live entries, and published Chat state remain reachable. */ +const EXPECTED_STREAMING_RETAINED_MB = 16 + const WORKER = join( import.meta.dirname, '..', @@ -127,3 +141,39 @@ describe('preparing tool arguments', () => { expect(retainedMb).toBeLessThanOrEqual(budgetMb) }) }) + +describe('live Assistant text publication', () => { + it.each(STREAMING_CASES)('publishes $fragments $blockType deltas with $pattern content within bounded CPU and heap costs', async (workload) => { + const samples: StreamingAssistantWorkerReport[] = [] + for (let index = 0; index < STREAMING_SAMPLES; index++) { + const run = await runBuiltBenchmarkWorker({ + worker: WORKER, + args: ['streaming', workload.blockType, workload.pattern, String(STREAMING_CHARACTERS), String(workload.fragments)], + exposeGc: true, timeoutMs: WORKER_TIMEOUT_MS, + }) + expect(run.timedOut, run.stderr).toBe(false) + expect(run.signal, run.stderr).toBeNull() + expect(run.exitCode, run.stderr).toBe(0) + const report = requireReport(run) + expect(report.characters).toBe(STREAMING_CHARACTERS) + expect(report.fragments).toBe(workload.fragments) + samples.push(report) + } + const median = samples.toSorted((a, b) => a.elapsedMs - b.elapsedMs)[Math.floor(STREAMING_SAMPLES / 2)]! + const retainedMb = samples.map(sample => sample.retainedMb).toSorted((a, b) => a - b)[Math.floor(STREAMING_SAMPLES / 2)]! + const budgetMs = ciTimeBudget(workload.expectedMs) + const budgetMb = EXPECTED_STREAMING_RETAINED_MB * PERFORMANCE_BUDGET_HEADROOM + const benchmarkCase: BenchmarkCase = { + id: `conversation-fold/streaming-${workload.blockType}-${workload.pattern}-${String(workload.fragments)}`, + measures: `Client append, final Chat publication, and complete text read for ${String(STREAMING_CHARACTERS / 1024)} KiB in ${String(workload.fragments)} ${workload.blockType} deltas with ${workload.pattern} content.`, + affects: 'Local processing of a long active model response; excludes model pacing, network transport, and browser rendering.', + } + console.log(JSON.stringify({ benchmark: benchmarkCase.id, samples, medianMs: median.elapsedMs, retainedMb, budgetMs, budgetMb })) + recordTimings(benchmarkCase, { + medianMs: { ms: median.elapsedMs, cpuMs: median.cpuUserMs + median.cpuSystemMs }, + }, { medianMs: budgetMs }) + recordPeakMemory(benchmarkCase, { peakRssMb: Math.max(...samples.map(sample => sample.maxRssMb)) }) + expect(median.elapsedMs).toBeLessThanOrEqual(budgetMs) + expect(retainedMb).toBeLessThanOrEqual(budgetMb) + }) +}) diff --git a/benchmarks/conversation-fold/conversation-fold.worker.client.ts b/benchmarks/conversation-fold/conversation-fold.worker.client.ts index 77297a131e..ee42c361a5 100644 --- a/benchmarks/conversation-fold/conversation-fold.worker.client.ts +++ b/benchmarks/conversation-fold/conversation-fold.worker.client.ts @@ -1,4 +1,4 @@ -/** Compiled worker for Client history folding and live tool preparation. */ +/** Compiled worker for Client history folding, live Assistant text, and tool preparation. */ import { performance } from 'node:perf_hooks' import { Context } from '@deepseek-ai/cordis' @@ -57,6 +57,20 @@ export interface PreparingToolWorkerReport { readonly detail: string | undefined } +/** One live Assistant block folded and read through the published Chat snapshot. */ +export interface StreamingAssistantWorkerReport { + readonly blockType: 'text' | 'reasoning' + readonly pattern: 'ordinary' | 'leading-whitespace' + readonly characters: number + readonly fragments: number + readonly checksum: number + readonly elapsedMs: number + readonly cpuUserMs: number + readonly cpuSystemMs: number + readonly retainedMb: number + readonly maxRssMb: number +} + function registerEventDefinitions(ctx: Context): ConversationEventRegistry { const events = new ConversationEventRegistry(ctx) // Only the service holder is an adapter; registrations and routing use production code. @@ -257,6 +271,74 @@ function preparingTool(tool: 'write' | 'bash', characters: number, definitions: } } +function streamingAssistant( + blockType: StreamingAssistantWorkerReport['blockType'], + pattern: StreamingAssistantWorkerReport['pattern'], + characters: number, + fragments: number, + definitions: ConversationEventRegistry, +): StreamingAssistantWorkerReport { + if (globalThis.gc === undefined) throw new Error('streaming benchmark requires --expose-gc') + if (characters % fragments !== 0) throw new Error('streaming characters must divide evenly into fragments') + const chunkSize = characters / fragments + const payload = pattern === 'ordinary' + ? 'abcdefghijklmno '.repeat(Math.ceil(characters / 16)).slice(0, characters) + : ' '.repeat(characters / 2) + 'abcdefghijklmno '.repeat(Math.ceil(characters / 32)).slice(0, characters / 2) + const attemptId = LlmAttemptId('streaming-benchmark') + const live = (index: number, chunk: StreamChunk): SessionEventLikeEntry => ({ + type: 'transient', + event: { + type: 'assistant/live-chunk', seq: 2 + index / (fragments + 1), time: TIME_ZERO + index, + data: { turn: 1, step: 1, attemptId, chunk }, + }, + }) + const chunks: SessionEventLikeEntry[] = [] + for (let index = 0; index < fragments; index++) { + chunks.push(live(index + 1, { + type: blockType === 'text' ? 'text-delta' : 'reasoning-delta', index: 0, + text: payload.slice(index * chunkSize, (index + 1) * chunkSize), + })) + } + const assembler = new ConversationNodeAssembler(definitions, new BenchViewDefinitions()) + assembler.replaceWindow([ + entry(0, 'turn/start', { turn: 1 }), + entry(1, 'step/start', { turn: 1, step: 1 }), + live(0, { type: 'block-start', index: 0, blockType }), + ], false) + assembler.activateTarget('chat') + globalThis.gc() + const before = process.memoryUsage().heapUsed + const start = performance.now() + const cpuStart = process.cpuUsage() + for (const chunk of chunks) assembler.append(chunk) + assembler.flush() + const text = streamingText(assembler, blockType) + // Consuming every character includes any deferred string materialization in the endpoint. + let checksum = 0 + for (let index = 0; index < text.length; index++) checksum += text.charCodeAt(index) + const cpu = process.cpuUsage(cpuStart) + const elapsedMs = performance.now() - start + if (text !== payload) throw new Error('streaming benchmark did not publish the complete Assistant text') + globalThis.gc() + const retainedMb = (process.memoryUsage().heapUsed - before) / 1048576 + // This read keeps the complete owner graph reachable across endpoint collection. + if (streamingText(assembler, blockType) !== text) throw new Error('streaming benchmark lost its published Assistant text') + return { + blockType, pattern, characters: text.length, fragments, checksum, + elapsedMs, cpuUserMs: cpu.user / 1000, cpuSystemMs: cpu.system / 1000, + retainedMb, maxRssMb: process.resourceUsage().maxRSS / 1024, + } +} + +function streamingText(assembler: ConversationNodeAssembler, blockType: StreamingAssistantWorkerReport['blockType']): string { + const node = assembler.get('chat')?.nodes.values().find((candidate): candidate is ChatNode<'assistant-step'> => candidate.kind === 'assistant-step') + const block = node?.data.blocks[0] + if (block?.kind !== blockType || (block.kind !== 'text' && block.kind !== 'reasoning')) { + throw new Error('streaming benchmark did not create its Assistant block') + } + return block.text +} + assertBuiltBenchmarkRuntime(import.meta.url, { '@deepseek-ai/dsh-brand': import.meta.resolve('@deepseek-ai/dsh-brand'), '@deepseek-ai/dsh-client-store': import.meta.resolve('@deepseek-ai/dsh-client-store'), @@ -273,6 +355,16 @@ try { if (tool !== 'write' && tool !== 'bash') throw new Error('preparing benchmark tool must be write or bash') const report = preparingTool(tool, positiveInteger(process.argv[4], 'characters'), definitions) process.stdout.write(`${JSON.stringify(report)}\n`) + } else if (process.argv[2] === 'streaming') { + const blockType = process.argv[3] + const pattern = process.argv[4] + if (blockType !== 'text' && blockType !== 'reasoning') throw new Error('streaming block type must be text or reasoning') + if (pattern !== 'ordinary' && pattern !== 'leading-whitespace') throw new Error('streaming pattern must be ordinary or leading-whitespace') + const report = streamingAssistant( + blockType, pattern, positiveInteger(process.argv[5], 'characters'), + positiveInteger(process.argv[6], 'fragments'), definitions, + ) + process.stdout.write(`${JSON.stringify(report)}\n`) } else { const [turnsValue, smallDeltasValue, largeDeltasValue, attemptsValue] = process.argv.slice(2) const turns = positiveInteger(turnsValue, 'turns') diff --git a/benchmarks/session-corpus/README.i18n.yaml b/benchmarks/session-corpus/README.i18n.yaml index 2162840b3e..5e02d08e37 100644 --- a/benchmarks/session-corpus/README.i18n.yaml +++ b/benchmarks/session-corpus/README.i18n.yaml @@ -12,8 +12,8 @@ en: 66a769ce60d49ff3 zh: 7e0bfa7c598157fa /session-corpus-benchmarks/run: - en: 2560e832041ae481 - zh: 2fbbff71135e52ab + en: c770082e58aa8194 + zh: 339d659595a1f97d /session-corpus-benchmarks/measurements: en: c357c231c3bfb588 zh: 3d901a2caccf2587 diff --git a/benchmarks/session-corpus/README.md b/benchmarks/session-corpus/README.md index d504417d77..f55fc563ec 100644 --- a/benchmarks/session-corpus/README.md +++ b/benchmarks/session-corpus/README.md @@ -18,7 +18,7 @@ Measure the Web Host's Session list, content search, and fork over synthetic cor From the repository root, build the libraries and workers with `pnpm run build:bench`, then run `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/session-corpus/session-corpus.bench.ts`. Do not overlap timing runs with builds or other benchmarks. Seeding writes about 1.5 GB of Zstandard logs under a private temporary root, which the test removes after success or failure. -The test reports every fresh-process sample, the CPU model, available parallelism, platform, and Node version, and enforces median budgets. Its last case fails when the file, including seeding, exceeds five minutes. A failed worker reports its exit, signal, timeout, and stderr tail. The required benchmark lane discovers this file automatically. +The test reports every fresh-process sample, the CPU model, available parallelism, platform, and Node version, and enforces median budgets. Its last case fails when the file, including seeding, exceeds five minutes. Fork workers use a fixed V8 heap limit; peak RSS still measures the whole process. A failed worker reports its exit, signal, timeout, and stderr tail. The required benchmark lane discovers this file automatically. diff --git a/benchmarks/session-corpus/README.zh.md b/benchmarks/session-corpus/README.zh.md index 1077b5233e..e7b1f1586a 100644 --- a/benchmarks/session-corpus/README.zh.md +++ b/benchmarks/session-corpus/README.zh.md @@ -18,7 +18,7 @@ 在仓库根目录使用 `pnpm run build:bench` 构建库和 worker，然后运行 `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/session-corpus/session-corpus.bench.ts`。不要让计时运行与构建或其他基准重叠。播种过程会在私有临时根目录下写入约 1.5 GB 的 Zstandard 日志，测试成功或失败后都会删除该目录。 -测试报告每个新进程样本、CPU 型号、可用并行度、平台和 Node 版本，并约束中位数预算。当整个文件（包括播种）超过五分钟时，最后一个用例失败。worker 失败时报告退出状态、信号、超时和 stderr 末尾。必需基准通道自动发现此文件。 +测试报告每个新进程样本、CPU 型号、可用并行度、平台和 Node 版本，并约束中位数预算。当整个文件（包括播种）超过五分钟时，最后一个用例失败。Fork worker 使用固定的 V8 堆上限；峰值 RSS 仍测量整个进程。worker 失败时报告退出状态、信号、超时和 stderr 末尾。必需基准通道自动发现此文件。 diff --git a/benchmarks/session-corpus/session-corpus.bench.ts b/benchmarks/session-corpus/session-corpus.bench.ts index 00bc2d2979..3bbb66809c 100644 --- a/benchmarks/session-corpus/session-corpus.bench.ts +++ b/benchmarks/session-corpus/session-corpus.bench.ts @@ -29,6 +29,8 @@ const CORPUS = { search: 1_000, fork: 1_000, list: 3_000 } as const const FILE_LIMIT_MS = 300_000 /** Per-child deadline: an endpoint slower than its budget still reports a measurement instead of a kill. */ const WORKER_TIMEOUT_MS = FILE_LIMIT_MS +/** Fixed old-space capacity makes fork RSS comparable across hosted V8 heap defaults. */ +const FORK_HEAP_LIMIT_MB = 512 /** Fresh processes per list and fork-strata scenario; the median enforces each budget. */ const ATTEMPTS = { list: 3, fork: 3 } as const /** Concurrent anchor-preparation processes; standard hosted runners have two CPUs. */ @@ -119,7 +121,10 @@ function serialDeadline(workers: number): number { } async function run(args: readonly string[]): Promise { - const outcome = await runBuiltBenchmarkWorker({ worker: WORKER, args, timeoutMs: WORKER_TIMEOUT_MS, exposeGc: true }) + const outcome = await runBuiltBenchmarkWorker({ + worker: WORKER, args, timeoutMs: WORKER_TIMEOUT_MS, exposeGc: true, + ...(args[1] === 'fork' ? { heapLimitMb: FORK_HEAP_LIMIT_MB } : {}), + }) if (outcome.report === undefined) { const stderr = outcome.stderr.trim().split('\n').slice(-20).join('\n') throw new Error(`session-corpus worker ${args[1] ?? ''} failed: exit=${String(outcome.exitCode)}, ` diff --git a/benchmarks/session-open/session-open.worker.ts b/benchmarks/session-open/session-open.worker.ts index 5e0b163aa1..6788e3f382 100644 --- a/benchmarks/session-open/session-open.worker.ts +++ b/benchmarks/session-open/session-open.worker.ts @@ -29,7 +29,8 @@ import SessionTitleService from '@deepseek-ai/dsh-session-title' import * as SessionTurnOutlinePlugin from '@deepseek-ai/dsh-session-turn-outline' import TokenMeter from '@deepseek-ai/dsh-token-meter' // These Host-only adapters have no public Node export and are compiled into the benchmark worker. -import { SessionHistoryController } from '../../packages/api/session-controller/src/history.ts' +import { HistoryController } from '../../packages/api/session-controller/src/history/controller.ts' +import { WebController } from '../../packages/api/session-controller/src/web/controller.ts' import { assertBuiltBenchmarkRuntime } from '../support/built-worker.ts' import { SYNTHETIC_SESSION_ID } from './session-open.constants.ts' @@ -151,7 +152,7 @@ class SessionBenchmarkHost { private constructor( private readonly ctx: Context, private readonly scenario: SessionOpenBenchmarkScenario, - private readonly history: SessionHistoryController | undefined, + private readonly history: WebController | undefined, ) {} static async create(root: string, scenario: SessionOpenBenchmarkScenario): Promise { @@ -165,10 +166,10 @@ class SessionBenchmarkHost { } await installProjectionSet(ctx) await ctx.plugin(JsonlSessionPersistence, { root, compression: 'zstd' }) - let history: SessionHistoryController | undefined + let history: WebController | undefined if (scenario === 'first-history') { new BenchmarkSessionQuery(ctx) - history = new SessionHistoryController(ctx, (observation) => { + history = new WebController(ctx, new HistoryController(ctx), (observation) => { // First-history ends at snapshot delivery; Agent-resume owns live activation and retention. observation[Symbol.dispose]() }) diff --git a/benchmarks/user-text/user-text.worker.client.ts b/benchmarks/user-text/user-text.worker.client.ts index 52e10ac919..dbd4f7fd1d 100644 --- a/benchmarks/user-text/user-text.worker.client.ts +++ b/benchmarks/user-text/user-text.worker.client.ts @@ -164,20 +164,22 @@ interface Workload { readonly evaluationsPerSample: number } -/** Named fixed workloads; adversarial inputs appear at two sizes so their scaling is observable. */ -function workloads(): readonly Workload[] { +/** Scaling sizes share adjacent rounds; standalone workloads occupy one group. */ +function workloadGroups(): readonly (readonly Workload[])[] { return [ - { id: 'typical-messages', group: 'unmatched', texts: messages(5_000), evaluationsPerSample: 1 }, + [{ id: 'typical-messages', group: 'unmatched', texts: messages(5_000), evaluationsPerSample: 1 }], ...Object.entries({ prose: PROSE, code: CODE, base64: BASE64, markdown: MARKDOWN, log: LOG, json: JSON_LINES, shell: SHELL }) - .map(([name, unit]): Workload => ({ + .map(([name, unit]): readonly Workload[] => [{ id: `${name}-256k`, group: 'unmatched', texts: [fill(unit, 256 * KIB)], evaluationsPerSample: SINGLE_DOCUMENT_EVALUATIONS, - })), - ...Object.entries(CREDENTIALS).map(([name, credential]): Workload => ({ + }]), + ...Object.entries(CREDENTIALS).map(([name, credential]): readonly Workload[] => [{ id: `messages-with-${name}`, group: 'matched', texts: credentialMessages(5_000, credential), evaluationsPerSample: 1, - })), - { id: 'env-keys-1000', group: 'matched', texts: [envFile(1_000)], evaluationsPerSample: 2 * SINGLE_DOCUMENT_EVALUATIONS }, - { id: 'env-keys-2000', group: 'matched', texts: [envFile(2_000)], evaluationsPerSample: SINGLE_DOCUMENT_EVALUATIONS }, - ...Object.entries(ADVERSARIAL_UNITS).flatMap(([name, unit]): Workload[] => [ + }]), + [ + { id: 'env-keys-1000', group: 'matched', texts: [envFile(1_000)], evaluationsPerSample: 2 * SINGLE_DOCUMENT_EVALUATIONS }, + { id: 'env-keys-2000', group: 'matched', texts: [envFile(2_000)], evaluationsPerSample: SINGLE_DOCUMENT_EVALUATIONS }, + ], + ...Object.entries(ADVERSARIAL_UNITS).map(([name, unit]): readonly Workload[] => [ { id: `adversarial-${name}-64k`, group: 'adversarial', texts: [fill(unit, 64 * KIB)], evaluationsPerSample: 2 * SINGLE_DOCUMENT_EVALUATIONS, @@ -256,25 +258,34 @@ async function evaluatePair(texts: readonly string[], index: number, evaluations return { base: await sample(withoutSecret, texts, evaluations), secret } } -async function measure(texts: readonly string[], attempts: number, evaluations: number): Promise { - for (let warm = 0; warm < WARMUP_PAIRS; warm++) await evaluatePair(texts, warm, evaluations) - const pairs: SamplePair[] = [] - for (let attempt = 0; attempt < attempts; attempt++) { - pairs.push(await evaluatePair(texts, attempt, evaluations)) - } - const best = pairs.reduce((min, pair) => ({ - base: pair.base.ms < min.base.ms ? pair.base : min.base, - secret: pair.secret.ms < min.secret.ms ? pair.secret : min.secret, - })) - return { - ...best, - samples: pairs.map(pair => ({ - baseMs: pair.base.ms, baseCpuMs: pair.base.cpuMs, - withSecretMs: pair.secret.ms, withSecretCpuMs: pair.secret.cpuMs, - })), +})[]> { + const measured = workloads.map(workload => ({ workload, pairs: new Array() })) + for (let round = 0; round < WARMUP_PAIRS + attempts; round++) { + for (let position = 0; position < measured.length; position++) { + const index = round % 2 === 0 ? position : measured.length - 1 - position + const { workload, pairs } = measured[index]! + const pair = await evaluatePair(workload.texts, round, workload.evaluationsPerSample) + if (round >= WARMUP_PAIRS) pairs.push(pair) + } } + return measured.map(({ workload, pairs }) => { + const best = pairs.reduce((min, pair) => ({ + base: pair.base.ms < min.base.ms ? pair.base : min.base, + secret: pair.secret.ms < min.secret.ms ? pair.secret : min.secret, + })) + return { + workload, + ...best, + samples: pairs.map(pair => ({ + baseMs: pair.base.ms, baseCpuMs: pair.base.cpuMs, + withSecretMs: pair.secret.ms, withSecretCpuMs: pair.secret.cpuMs, + })), + } + }) } declare const gc: (() => void) | undefined @@ -366,7 +377,7 @@ async function allocations(): Promise { if (gc === undefined) throw new Error('user-text allocation mode needs --expose-gc') const collect = gc const results: UserTextWorkloadAllocation[] = [] - for (const { id, texts } of workloads()) { + for (const { id, texts } of workloadGroups().flat()) { results.push({ id, ruleAllocatedBytes: await allocatedBytes(texts, collect), ...returned(texts) }) } return { workloads: results } @@ -374,23 +385,24 @@ async function allocations(): Promise { async function timings(attempts: number): Promise { const results: UserTextWorkloadTiming[] = [] - for (const { id, group, texts, evaluationsPerSample } of workloads()) { - const { base, secret, samples } = await measure(texts, attempts, evaluationsPerSample) - results.push({ - id, - group, - documents: texts.length, - characters: texts.reduce((sum, text) => sum + text.length, 0), - evaluationsPerSample, - secrets: secret.secrets, - maskedCharacters: secret.maskedCharacters, - baseMs: base.ms, - baseCpuMs: base.cpuMs, - withSecretMs: secret.ms, - withSecretCpuMs: secret.cpuMs, - ratio: secret.ms / base.ms, - samples, - }) + for (const workloads of workloadGroups()) { + for (const { workload: { id, group, texts, evaluationsPerSample }, base, secret, samples } of await measure(workloads, attempts)) { + results.push({ + id, + group, + documents: texts.length, + characters: texts.reduce((sum, text) => sum + text.length, 0), + evaluationsPerSample, + secrets: secret.secrets, + maskedCharacters: secret.maskedCharacters, + baseMs: base.ms, + baseCpuMs: base.cpuMs, + withSecretMs: secret.ms, + withSecretCpuMs: secret.cpuMs, + ratio: secret.ms / base.ms, + samples, + }) + } } return { warmupPairs: WARMUP_PAIRS, attempts, workloads: results } } diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 39ebd5cd9c..d1766b9e80 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -74,4 +74,4 @@ Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this l ## Repository references -Use relative Markdown links for current files and tags or PR numbers for historical references. `verify-md-links` checks local targets. [Reference validation](../scripts/verify-repository-references.ts) rejects actual commit identifiers and disallowed organization URLs in maintained files. +Use relative Markdown links for current files and tags or PR numbers for historical references. `verify-md-links` checks local targets. [Reference validation](../scripts/verify-repository-references.ts) rejects commit identifiers containing a hexadecimal letter and disallowed organization URLs in maintained files. Decimal-only tokens are ignored to avoid collisions with numeric data, even when they identify commits. diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 84c0f093c0..ccac86a189 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.i18n.yaml @@ -27,8 +27,8 @@ en: 1a79a70b62c04cdb zh: c86d765e21430405 /deepseek-harness-architecture/session-log: - en: 8a7f19b95d426c99 - zh: d5bb0538404e20ea + en: b3b63d8fe7cab9fe + zh: 3703fcf30b1639d0 /deepseek-harness-architecture/capability-seams: en: a419cc2a37a80f7f zh: 70654d3c77ea2cc0 diff --git a/docs/architecture.md b/docs/architecture.md index 4a6d503ce7..6a1bf36436 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -129,7 +129,7 @@ Session consumers know only the current logical format. Header-only `stat` and ` **Model-visible means logged.** Every model request must be reconstructable from the log. New model-visible inputs require session events. Plugins changing existing message content register [pure message projections](subsystems/session.md#plugin-owned-message-projections); detached readers supply the same definitions explicitly. Tool changes are capability-independent; [Session tool history](../packages/core/session/README.md) supplies provider declarations. -**Projection seam.** `dsh-session-projection` owns `ctx.sessionProjections`: registered units fold committed events incrementally, and carriers batch cropped client views with `snapshot()`. Domain services await registration during activation, retain private handles, and expose business methods for other plugins. Releasing registration removes global participation; retained handles continue folding Session events. `AgentRegistry` owns turn and step state and exposes `turnBoundaryOf(session)` ([registration lifecycle](../packages/session/session-projection/README.md)). `AgentLoop` owns `modelSelection` and constructs each Agent’s `model` instance alongside its inbox. +**Projection seam.** `dsh-session-projection` owns `ctx.sessionProjections`: registered units fold committed events; carriers read selected client views through `snapshot()`. Domain services await registration, retain private handles, and expose business methods ([registration lifecycle](../packages/session/session-projection/README.md)). `AgentRegistry` exposes turn and step state through `turnBoundaryOf(session)`. `AgentLoop` owns `modelSelection` and inbox state ([loop lifecycle](../packages/core/agent-loop/README.md)). [Working directories](subsystems/working-directory.md) supply user context and execution paths without changing original project identity, sandbox write roots, or existing process directories. diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index 830cb2039b..fcbb18cb4f 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -133,7 +133,7 @@ Session 消费方只了解当前逻辑格式。仅 header 的 `stat` 与 `list` **模型可见即已记录。** 每个模型请求都必须能从日志重建。新增模型可见输入需要会话事件。修改现有消息内容的插件注册[纯消息投影](subsystems/session.zh.md#plugin-owned-message-projections)，独立读取器显式传入相同的处理器。 工具变更不依赖能力；[Session 工具历史](../packages/core/session/README.zh.md)提供提供方声明。 -**投影 seam。** `dsh-session-projection` 提供 `ctx.sessionProjections`：已注册单元增量折叠已提交事件，载体通过 `snapshot()` 批量取得裁剪后的客户端视图。领域服务在激活时等待注册完成，在内部保留句柄，并向其他插件提供业务方法。释放注册会移除全局参与关系；已有句柄仍可继续折叠 Session 事件。`AgentRegistry` 持有轮次和步骤状态，并提供 `turnBoundaryOf(session)`（[注册生命周期](../packages/session/session-projection/README.zh.md)）。 `AgentLoop` 持有 `modelSelection`，并与 inbox 一起构建每个 Agent 的 `model` 实例。 +**投影 seam。** `dsh-session-projection` 提供 `ctx.sessionProjections`：已注册单元折叠已提交事件，载体通过 `snapshot()` 读取选定的客户端视图。领域服务等待注册完成，在内部保留句柄，并提供业务方法（[注册生命周期](../packages/session/session-projection/README.zh.md)）。`AgentRegistry` 通过 `turnBoundaryOf(session)` 提供轮次和步骤状态。`AgentLoop` 持有 `modelSelection` 和 inbox 状态（[Loop 生命周期](../packages/core/agent-loop/README.zh.md)）。 [工作目录](subsystems/working-directory.zh.md) 提供用户上下文和执行路径，不改变原始项目标识、沙箱写入根目录或已有进程目录。 diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml index 6ebfb8e14f..0ed513f50f 100644 --- a/docs/capability-seams.i18n.yaml +++ b/docs/capability-seams.i18n.yaml @@ -6,5 +6,5 @@ en: 41d772192075e133 zh: 5ef3da69b4de1d8a /capability-seams-and-core-services: - en: eb93c7501376985c - zh: 178bfc8e12149b47 + en: d8b13c7286951262 + zh: 13e0a1eefc101c8f diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 2c515ce9d3..01e1a8028e 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -36,6 +36,13 @@ flowchart LR svc_connection["ctx.connection
Authenticated browser transport"] pkg_api_gateway["api-gateway"] pkg_host_frontend_static["host-frontend-static"] + pkg_experimental_forge["experimental-forge"] + svc_forge["ctx.forge
Code host change requests"] + pkg_experimental_forge_github["experimental-forge-github"] + pkg_experimental_forge_session["experimental-forge-session"] + pkg_experimental_client_ui_forge["experimental-client-ui-forge"] + svc_forgeSession["ctx.forgeSession
Session change request bindings"] + svc_forgePanel["ctx.forgePanel
Forge panel Remote"] pkg_experimental_worktree["experimental-worktree"] svc_worktrees["ctx.worktrees
Git worktree creation"] pkg_experimental_tool_worktree["experimental-tool-worktree"] @@ -77,9 +84,10 @@ flowchart LR pkg_llm_replay["llm-replay"] pkg_agent_loop["agent-loop"] pkg_compaction_basic["compaction-basic"] + pkg_session_log_deepseek["session-log-deepseek"] + svc_sessionLogDeepSeek["ctx.sessionLogDeepSeek
Session-log upload policy"] pkg_deepseek_llm_api_extensions["deepseek-llm-api-extensions"] svc_deepseekLlmApiExtensions["ctx.deepseekLlmApiExtensions
Official DeepSeek request extensions"] - pkg_session_log_deepseek["session-log-deepseek"] pkg_plugin_package_inventory_deepseek["plugin-package-inventory-deepseek"] pkg_token_meter["token-meter"] svc_tokenMeter["ctx.tokenMeter
Replay token measurement"] @@ -308,6 +316,8 @@ flowchart LR pkg_cordis_host_runner["cordis-host-runner"] svc_dynamicCordisRunner["ctx.dynamicCordisRunner
Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
Dynamic Cordis inspect registry"] + pkg_experimental_liveshare["experimental-liveshare"] + svc_liveshareShares["ctx.liveshareShares
Owner share management Remote"] pkg_action_cards --> svc_actionCards pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel @@ -359,8 +369,13 @@ flowchart LR pkg_experimental_browser_use_stagehand_native --> svc_browserUse pkg_experimental_claude_code_mods --> svc_claudeCodeMods pkg_experimental_client_ui_cot_translation --> svc_cotTranslation + pkg_experimental_client_ui_forge --> svc_forgePanel pkg_experimental_computer_use_cua_driver_mcp --> svc_computerUse pkg_experimental_computer_use_cua_driver_native --> svc_computerUse + pkg_experimental_forge --> svc_forge + pkg_experimental_forge_github --> svc_forge + pkg_experimental_forge_session --> svc_forgeSession + pkg_experimental_liveshare --> svc_liveshareShares pkg_experimental_ptc_runtime_python --> svc_ptcRuntime pkg_experimental_speech_to_text --> svc_speechToText pkg_experimental_speech_to_text_sensevoice --> svc_speechToText @@ -411,6 +426,7 @@ flowchart LR pkg_schedule --> svc_schedule pkg_session --> svc_sessions pkg_session_log_deepseek --> svc_deepseekLlmApiExtensions + pkg_session_log_deepseek --> svc_sessionLogDeepSeek pkg_session_persistence --> svc_sessionPersistence pkg_session_persistence_jsonl --> svc_sessionPersistence pkg_session_projection --> svc_sessionProjections @@ -511,6 +527,9 @@ flowchart LR svc_dynamicCordisRunner --> pkg_tool_cordis svc_fileReferences --> pkg_api_session_controller svc_fileUploads --> pkg_api_session_controller + svc_forge --> pkg_experimental_client_ui_forge + svc_forge --> pkg_experimental_forge_session + svc_forgeSession --> pkg_experimental_client_ui_forge svc_fs --> pkg_tool_fs svc_headlessStartup --> pkg_headless svc_hmr --> pkg_app_boot @@ -651,6 +670,9 @@ flowchart LR | `ctx.pluginMarket` | `core` | [`plugin-market`](../packages/boot/plugin-market) | - | [`client-ui-plugin-market`](../packages/client/ui-plugin-market), [`plugin-market`](../packages/boot/plugin-market) | - | Fetches and validates the index sources the user configures; installation goes through the plugin manager. | | `ctx.profileContext` | `core` | [`app-boot`](../packages/boot/app-boot) | - | [`plugin-manager`](../packages/boot/plugin-manager) | - | The dsh launcher supplies data-only profile locations and composition inputs; reload scheduling belongs to dsh-hmr. | | `ctx.connection` | `core` | [`client-connection`](../packages/client/connection) | - | [`api-gateway`](../packages/api/gateway), [`host-frontend-static`](../packages/host/frontend-static) | - | Owns browser authentication and shared HTTP request dispatch; API adapters register endpoints and streams. | +| `ctx.forge` | `seam` | [`experimental-forge`](../packages/experimental/forge) | [`experimental-forge-github`](../packages/experimental/forge-github) | [`experimental-forge-session`](../packages/experimental/forge-session), [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | - | Providers map remote and change request URLs, look up change requests by head branch, and read status in batches; watchers of one change request share one polling loop. | +| `ctx.forgeSession` | `service` | [`experimental-forge-session`](../packages/experimental/forge-session) | - | [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | - | A Session projection derives bindings from shell results and binding records and publishes their URLs without status to clients; push results trigger head-branch discovery, and Session watchers poll bound change requests through the forge registry. | +| `ctx.forgePanel` | `service` | [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | - | - | - | Streams one panel state per followed Session: Git inspection using Session permissions, the recognized code host and its sign-in, and the bound change requests with polled status. | | `ctx.worktrees` | `seam` | [`experimental-worktree`](../packages/experimental/worktree) | [`experimental-worktree`](../packages/experimental/worktree) | [`experimental-tool-worktree`](../packages/experimental/tool-worktree) | - | Explicit experimental creation from a pinned local commit. Existing write permissions govern checkout and shared Git metadata; the working-directory service owns the resulting Session directory. | | `ctx.workingDirectory` | `seam` | [`working-directory`](../packages/session/working-directory) | [`working-directory`](../packages/session/working-directory) | [`tool-working-directory`](../packages/session/tool-working-directory), [`tool-fs`](../packages/fs/tool-fs), [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`subagent`](../packages/subagent/subagent), [`sdk-jsonrpc-server`](../packages/sdk/server) | - | One Session projection owns the effective execution directory. The filesystem validates changes; user context reports them while original metadata and write grants stay fixed. | | `ctx.mcpResources` | `seam` | [`mcp-resources`](../packages/mcp/mcp-resources) | [`mcp-client`](../packages/mcp/mcp-client) | [`mcp-resources`](../packages/mcp/mcp-resources) | - | Connection-owned providers serve shared resource tools in the calling agent scope. | @@ -661,6 +683,7 @@ flowchart LR | `ctx.attachments` | `seam` | [`attachment`](../packages/attachment/attachment) | [`attachment-local`](../packages/attachment/attachment-local) | [`api-session-controller`](../packages/api/session-controller), [`tool-fs`](../packages/fs/tool-fs), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-deepseek`](../packages/llm/llm-deepseek) | - | The host commits accepted images before session events; provider adapters resolve authorized durable references into provider-native content. | | `ctx.fileUploads` | `core` | [`client-file-upload`](../packages/client/file-upload) | - | [`api-session-controller`](../packages/api/session-controller) | - | Owns streaming intake, durable storage, and staged receipt lifetime; the Session controller binds receipts to accepted submissions. | | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/test-support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compaction-basic`](../packages/compaction/compaction-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. | +| `ctx.sessionLogDeepSeek` | `core` | [`session-log-deepseek`](../packages/session/session-log-deepseek) | - | - | - | Plugins register caller-owned exclusions before the canonical Session-log request contribution is prepared; unmatched requests use normal upload eligibility. | | `ctx.deepseekLlmApiExtensions` | `seam` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | [`session-log-deepseek`](../packages/session/session-log-deepseek), [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | [`llm-deepseek`](../packages/llm/llm-deepseek) | - | Plugins prepare independent top-level fields; the official adapter merges them and commits their delivery state after HTTP acceptance. | | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compaction-basic`](../packages/compaction/compaction-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. | | `ctx.toolResultPruner` | `core` | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | - | [`compaction-basic`](../packages/compaction/compaction-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. | @@ -744,5 +767,6 @@ flowchart LR | `ctx.lsp` | `seam` | [`lsp`](../packages/lsp/lsp) | [`lsp-stdio`](../packages/lsp/lsp-stdio) | [`tool-lsp`](../packages/lsp/tool-lsp) | - | Provider registration and selection plus normalized query execution over exactly four operations; the seam offers no protocol escape hatch, so a backend translates into the normalized request and result. | | `ctx.dynamicCordisRunner` | `core` | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | - | [`tool-cordis`](../packages/extensions/tool-cordis) | - | Owns the in-memory definition registry, the vm sandbox for host halves, and the request-run round trip; browser pages reach the same service over the wire through its remote namespace. | | `ctx.cordisInspect` | `core` | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | - | [`tool-cordis`](../packages/extensions/tool-cordis) | - | Registers host inspect providers, mirrors the client provider manifest, and routes client queries through the dynamic Cordis transport. | +| `ctx.liveshareShares` | `service` | [`experimental-liveshare`](../packages/experimental/liveshare) | - | - | - | Publishes the owner share-management operations as one Typert Remote namespace that the owner client face calls; every method delegates to the same operations the same-origin routes used. | Maintenance mode: hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard. diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md index 9700224fde..cde68b5223 100644 --- a/docs/capability-seams.zh.md +++ b/docs/capability-seams.zh.md @@ -38,6 +38,13 @@ flowchart LR svc_connection["ctx.connection
Authenticated browser transport"] pkg_api_gateway["api-gateway"] pkg_host_frontend_static["host-frontend-static"] + pkg_experimental_forge["experimental-forge"] + svc_forge["ctx.forge
Code host change requests"] + pkg_experimental_forge_github["experimental-forge-github"] + pkg_experimental_forge_session["experimental-forge-session"] + pkg_experimental_client_ui_forge["experimental-client-ui-forge"] + svc_forgeSession["ctx.forgeSession
Session change request bindings"] + svc_forgePanel["ctx.forgePanel
Forge panel Remote"] pkg_experimental_worktree["experimental-worktree"] svc_worktrees["ctx.worktrees
Git worktree creation"] pkg_experimental_tool_worktree["experimental-tool-worktree"] @@ -79,9 +86,10 @@ flowchart LR pkg_llm_replay["llm-replay"] pkg_agent_loop["agent-loop"] pkg_compaction_basic["compaction-basic"] + pkg_session_log_deepseek["session-log-deepseek"] + svc_sessionLogDeepSeek["ctx.sessionLogDeepSeek
Session-log upload policy"] pkg_deepseek_llm_api_extensions["deepseek-llm-api-extensions"] svc_deepseekLlmApiExtensions["ctx.deepseekLlmApiExtensions
Official DeepSeek request extensions"] - pkg_session_log_deepseek["session-log-deepseek"] pkg_plugin_package_inventory_deepseek["plugin-package-inventory-deepseek"] pkg_token_meter["token-meter"] svc_tokenMeter["ctx.tokenMeter
Replay token measurement"] @@ -310,6 +318,8 @@ flowchart LR pkg_cordis_host_runner["cordis-host-runner"] svc_dynamicCordisRunner["ctx.dynamicCordisRunner
Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
Dynamic Cordis inspect registry"] + pkg_experimental_liveshare["experimental-liveshare"] + svc_liveshareShares["ctx.liveshareShares
Owner share management Remote"] pkg_action_cards --> svc_actionCards pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel @@ -361,8 +371,13 @@ flowchart LR pkg_experimental_browser_use_stagehand_native --> svc_browserUse pkg_experimental_claude_code_mods --> svc_claudeCodeMods pkg_experimental_client_ui_cot_translation --> svc_cotTranslation + pkg_experimental_client_ui_forge --> svc_forgePanel pkg_experimental_computer_use_cua_driver_mcp --> svc_computerUse pkg_experimental_computer_use_cua_driver_native --> svc_computerUse + pkg_experimental_forge --> svc_forge + pkg_experimental_forge_github --> svc_forge + pkg_experimental_forge_session --> svc_forgeSession + pkg_experimental_liveshare --> svc_liveshareShares pkg_experimental_ptc_runtime_python --> svc_ptcRuntime pkg_experimental_speech_to_text --> svc_speechToText pkg_experimental_speech_to_text_sensevoice --> svc_speechToText @@ -413,6 +428,7 @@ flowchart LR pkg_schedule --> svc_schedule pkg_session --> svc_sessions pkg_session_log_deepseek --> svc_deepseekLlmApiExtensions + pkg_session_log_deepseek --> svc_sessionLogDeepSeek pkg_session_persistence --> svc_sessionPersistence pkg_session_persistence_jsonl --> svc_sessionPersistence pkg_session_projection --> svc_sessionProjections @@ -513,6 +529,9 @@ flowchart LR svc_dynamicCordisRunner --> pkg_tool_cordis svc_fileReferences --> pkg_api_session_controller svc_fileUploads --> pkg_api_session_controller + svc_forge --> pkg_experimental_client_ui_forge + svc_forge --> pkg_experimental_forge_session + svc_forgeSession --> pkg_experimental_client_ui_forge svc_fs --> pkg_tool_fs svc_headlessStartup --> pkg_headless svc_hmr --> pkg_app_boot @@ -653,6 +672,9 @@ flowchart LR | `ctx.pluginMarket` | `core` | [`plugin-market`](../packages/boot/plugin-market) | - | [`client-ui-plugin-market`](../packages/client/ui-plugin-market), [`plugin-market`](../packages/boot/plugin-market) | - | 获取并校验用户配置的索引源；安装通过插件管理器完成。 | | `ctx.profileContext` | `core` | [`app-boot`](../packages/boot/app-boot) | - | [`plugin-manager`](../packages/boot/plugin-manager) | - | dsh launcher 提供纯数据形式的 profile 位置与组合输入；重载调度由 dsh-hmr 负责。 | | `ctx.connection` | `core` | [`client-connection`](../packages/client/connection) | - | [`api-gateway`](../packages/api/gateway), [`host-frontend-static`](../packages/host/frontend-static) | - | 负责浏览器认证与共享 HTTP 请求分发；API 适配器注册端点和流。 | +| `ctx.forge` | `seam` | [`experimental-forge`](../packages/experimental/forge) | [`experimental-forge-github`](../packages/experimental/forge-github) | [`experimental-forge-session`](../packages/experimental/forge-session), [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | - | 提供方映射远端与变更请求 URL、按 head 分支查找变更请求并批量读取状态；同一变更请求的监听方共享一个轮询循环。 | +| `ctx.forgeSession` | `service` | [`experimental-forge-session`](../packages/experimental/forge-session) | - | [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | - | Session 投影从 shell 结果与绑定记录派生绑定，并把不含状态的 URL 发布给客户端；推送结果触发按 head 分支的发现，Session 监听方通过 forge 注册表轮询已绑定的变更请求。 | +| `ctx.forgePanel` | `service` | [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | - | - | - | 为每个被跟随的 Session 推送一份面板状态：使用 Session 权限进行的 Git 检查、识别出的代码托管平台及其登录状态，以及带轮询状态的已绑定变更请求。 | | `ctx.worktrees` | `seam` | [`experimental-worktree`](../packages/experimental/worktree) | [`experimental-worktree`](../packages/experimental/worktree) | [`experimental-tool-worktree`](../packages/experimental/tool-worktree) | - | 显式实验组合从固定的本地提交创建工作树。检出目录与共享 Git 元数据受现有写权限约束；工作目录服务拥有创建后的 Session 目录。 | | `ctx.workingDirectory` | `seam` | [`working-directory`](../packages/session/working-directory) | [`working-directory`](../packages/session/working-directory) | [`tool-working-directory`](../packages/session/tool-working-directory), [`tool-fs`](../packages/fs/tool-fs), [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`subagent`](../packages/subagent/subagent), [`sdk-jsonrpc-server`](../packages/sdk/server) | - | 一个 Session 投影拥有有效执行目录。文件系统验证变更，用户上下文报告目录信息，原始元数据与写入授权保持不变。 | | `ctx.mcpResources` | `seam` | [`mcp-resources`](../packages/mcp/mcp-resources) | [`mcp-client`](../packages/mcp/mcp-client) | [`mcp-resources`](../packages/mcp/mcp-resources) | - | 连接所有者提供的操作在调用 agent 的作用域内服务于共享资源工具。 | @@ -663,6 +685,7 @@ flowchart LR | `ctx.attachments` | `seam` | [`attachment`](../packages/attachment/attachment) | [`attachment-local`](../packages/attachment/attachment-local) | [`api-session-controller`](../packages/api/session-controller), [`tool-fs`](../packages/fs/tool-fs), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-deepseek`](../packages/llm/llm-deepseek) | - | 宿主会在会话事件之前提交已接受的图片；提供方适配器将已授权的持久引用解析为提供方原生内容。 | | `ctx.fileUploads` | `core` | [`client-file-upload`](../packages/client/file-upload) | - | [`api-session-controller`](../packages/api/session-controller) | - | 负责流式接收、持久存储和暂存回执生命周期；Session Controller 将回执绑定到已接受的提交。 | | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/test-support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compaction-basic`](../packages/compaction/compaction-basic) | - | 适配器注册提供方实现；agent loop（智能体循环）与压缩功能调用提供方无关的流服务。 | +| `ctx.sessionLogDeepSeek` | `core` | [`session-log-deepseek`](../packages/session/session-log-deepseek) | - | - | - | 插件在准备权威 Session 日志请求贡献前注册归调用方所有的排除条件；没有条件匹配的请求应用普通上传资格判断。 | | `ctx.deepseekLlmApiExtensions` | `seam` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | [`session-log-deepseek`](../packages/session/session-log-deepseek), [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | [`llm-deepseek`](../packages/llm/llm-deepseek) | - | 插件准备彼此独立的顶层字段；官方适配器会合并这些字段，并在 HTTP 接受后提交其交付状态。 | | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 拥有按会话隔离的回放折叠区；压力消费方共享不可变且带修订版本的测量结果。 | | `ctx.toolResultPruner` | `core` | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | - | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 在摘要压缩前，通过可回放的单节点表层替换来改写过大的当前工具结果。 | @@ -746,5 +769,6 @@ flowchart LR | `ctx.lsp` | `seam` | [`lsp`](../packages/lsp/lsp) | [`lsp-stdio`](../packages/lsp/lsp-stdio) | [`tool-lsp`](../packages/lsp/tool-lsp) | - | 提供方注册与选择，加上恰好四种操作的标准化查询执行；该 seam 不提供协议逃生口，后端必须转换为标准化请求和结果。 | | `ctx.dynamicCordisRunner` | `core` | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | - | [`tool-cordis`](../packages/extensions/tool-cordis) | - | 拥有内存定义注册表、Host 半的 vm 沙箱和 request-run 往返流程；浏览器页面通过其 Remote 命名空间在线访问同一服务。 | | `ctx.cordisInspect` | `core` | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | - | [`tool-cordis`](../packages/extensions/tool-cordis) | - | 注册 Host inspect 提供方、镜像 Client 提供方 manifest，并通过动态 Cordis 传输路由 Client 查询。 | +| `ctx.liveshareShares` | `service` | [`experimental-liveshare`](../packages/experimental/liveshare) | - | - | - | 以单个 Typert Remote 命名空间发布 owner 分享管理操作，供 owner 客户端面调用；每个方法都委托给同源路由原先使用的同一组操作。 | 维护模式：混合模式。服务从 Cordis 声明中发现；接口、实现和消费方角色在 `scripts/gen-doc-graphs.ts` 中分类，并设有完整性守卫。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index fd4d9a7f3b..05a001d2b4 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -203,7 +203,7 @@ export interface Config { ## `@deepseek-ai/dsh-api-gateway` - `inject`: `typert` · `remoteAccess` -- `source`: [`packages/api/gateway/src/index.ts:156`](../packages/api/gateway/src/index.ts) +- `source`: [`packages/api/gateway/src/index.ts:158`](../packages/api/gateway/src/index.ts) ```ts config-catalog /** Gateway transport configuration. */ @@ -242,8 +242,8 @@ export interface Config { ## `@deepseek-ai/dsh-api-session-controller` -- `inject`: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `fs` · `llm` · `remoteAccess` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry` -- `source`: [`packages/api/session-controller/src/index.ts:109`](../packages/api/session-controller/src/index.ts) +- `inject`: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `fs` · `llm` · `remoteAccess` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `typertGateway` · `workspaceRegistry` +- `source`: [`packages/api/session-controller/src/index.ts:110`](../packages/api/session-controller/src/index.ts) ```ts config-catalog /** Session Controller deployment policy. */ @@ -706,13 +706,30 @@ export type ThemePreference = typeof THEME_PREFERENCES[number] ``` + + + +## `@deepseek-ai/dsh-client-ui-trajectory` + +- `inject`: `sessions` · `typert` +- `source`: [`packages/client/ui-trajectory/src/index.ts:25`](../packages/client/ui-trajectory/src/index.ts) + +```ts config-catalog +/** Count limit for each live Session's transient tool results. */ +export interface Config { + /** Maximum retained results per Session, including values awaiting a result event. */ + maxResultsPerSession: number +} +``` + + ## `@deepseek-ai/dsh-compaction-basic` - `inject`: `llm` · `tokenMeter` · `sessions` -- `source`: [`packages/compaction/compaction-basic/src/types.ts:40`](../packages/compaction/compaction-basic/src/types.ts) +- `source`: [`packages/compaction/compaction-basic/src/types.ts:46`](../packages/compaction/compaction-basic/src/types.ts) ```ts config-catalog /** Basic compaction configuration with an optional exact-target policy table. */ @@ -1021,6 +1038,44 @@ export interface CotTranslationPreferences { ``` + + + +## `@deepseek-ai/dsh-experimental-client-ui-forge` + +- `inject`: `forge` · `forgeSession` · `sessionProjections` · `workingDirectory` · `fs` · `subprocess` · `sandbox` · `sandboxPolicy` · `agents` +- `source`: [`packages/experimental/client-ui-forge/src/types.ts:318`](../packages/experimental/client-ui-forge/src/types.ts) + +```ts config-catalog +/** Host settings of the forge panel Remote. */ +export interface Config { + /** Git executable name or absolute path in the Session's execution world. */ + gitCommand?: string + /** Deadline in milliseconds for one Git command, including confinement. */ + gitTimeoutMs?: number + /** Termination grace period in milliseconds for each Git process. */ + graceMs?: number + /** Maximum captured bytes per Git output stream. */ + maxOutputBytes?: number + /** Deadline in milliseconds for one provider sign-in probe. */ + readinessTimeoutMs?: number + /** Most local branches listed as worktree bases. */ + maxBranches?: number + /** + * Prefix of the branch and checkout directory created for a Session worktree; the first eight + * hexadecimal digits of the Session id's UUID, a hyphen, and four random hexadecimal digits follow it. + */ + worktreePrefix?: string + /** Largest diff, or file read to show unchanged lines, in bytes. */ + maxDiffBytes?: number + /** Most untracked files a local diff or the local changes card includes. */ + maxUntrackedFiles?: number + /** Most UTF-8 bytes of change request diffs kept in memory for later reads at the same head commit and base branch. */ + maxCachedDiffBytes?: number +} +``` + + @@ -1060,6 +1115,68 @@ export type Config = CuaConfig ``` + + + +## `@deepseek-ai/dsh-experimental-forge` + +- `source`: [`packages/experimental/forge/src/types.ts:232`](../packages/experimental/forge/src/types.ts) + +```ts config-catalog +/** Poll cadence and fetch deadline for watched change requests. */ +export interface Config { + /** Poll interval in milliseconds while checks run or mergeability is unknown. */ + activeIntervalMs?: number + /** Poll interval in milliseconds for a closed request or an open request whose checks have settled. */ + idleIntervalMs?: number + /** Largest delay in milliseconds between polls after consecutive failures. */ + maxBackoffMs?: number + /** Deadline in milliseconds for one provider fetch. */ + fetchTimeoutMs?: number +} +``` + + + + + +## `@deepseek-ai/dsh-experimental-forge-github` + +- `inject`: `forge` +- `source`: [`packages/experimental/forge-github/src/index.ts:14`](../packages/experimental/forge-github/src/index.ts) + +```ts config-catalog +/** GitHub CLI executable, served hosts, and invocation limits. */ +export interface Config { + /** GitHub CLI executable name or absolute host path. */ + ghCommand?: string + /** Host names this provider serves; list GitHub Enterprise hosts explicitly. */ + hosts?: string[] + /** Deadline in milliseconds for one `gh` invocation. */ + timeoutMs?: number + /** Maximum captured bytes per `gh` output stream and combined JSON bytes of one complete check read. */ + maxOutputBytes?: number +} +``` + + + + + +## `@deepseek-ai/dsh-experimental-forge-session` + +- `inject`: `forge` · `sessions` · `sessionProjections` +- `source`: [`packages/experimental/forge-session/src/types.ts:91`](../packages/experimental/forge-session/src/types.ts) + +```ts config-catalog +/** Deployment settings of `forgeSession`. */ +export interface Config { + /** Deadline in milliseconds for one change request lookup after a push. */ + discoveryTimeoutMs?: number +} +``` + + @@ -1385,7 +1502,7 @@ export type PaidTranslationProvider = 'deepseek-account' | 'deepseek-official' ## `@deepseek-ai/dsh-experimental-worktree` - `inject`: `workingDirectory` · `fs` · `subprocess` · `sandbox` · `sandboxPolicy` -- `source`: [`packages/experimental/worktree/src/index.ts:19`](../packages/experimental/worktree/src/index.ts) +- `source`: [`packages/experimental/worktree/src/index.ts:21`](../packages/experimental/worktree/src/index.ts) ```ts config-catalog /** Worktree location, generated names, executables, and subprocess resource limits. */ @@ -2104,8 +2221,8 @@ export type PiAiThinkingTokenBudgetField = NonNullable @@ -2477,7 +2596,7 @@ export interface PlanModeConfig { - `inject`: `loader` · `profileContext` - `refs`: [`NpmFileSource`](subsystems/boot.md) -- `source`: [`packages/boot/plugin-manager/src/index.ts:53`](../packages/boot/plugin-manager/src/index.ts) +- `source`: [`packages/boot/plugin-manager/src/index.ts:54`](../packages/boot/plugin-manager/src/index.ts) ```ts config-catalog /** The pnpm executable, registries, and limits for diagnostics, lookups and connection checks. */ @@ -2590,8 +2709,10 @@ export interface Config { export interface Config { /** Worker invocation in the subprocess world; omitted selects the local carrier. */ launch?: LaunchConfig - /** per-call starts fresh processes; persistent-in-memory retains a REPL per owner under the same file policy. */ - executionMode?: 'per-call' | 'persistent-in-memory' + /** per-call uses fresh async function bodies; vm-script uses VM contexts; persistent-in-memory retains a REPL per owner. */ + executionMode?: 'per-call' | 'persistent-in-memory' | 'vm-script' + /** Retain a Script process and context per stateOwner; only supported with executionMode: vm-script. */ + scriptPersistence?: boolean /** Default elapsed deadline, including nested tool and approval waits. */ timeoutMs?: number /** Maximum numeric elapsed budget accepted by resolve. */ @@ -2863,7 +2984,7 @@ export interface JsonRpcConfig { - `inject`: `deepseekLlmApiExtensions` · `sessions` - `refs`: `Volatile` (`@deepseek-ai/cordis`) -- `source`: [`packages/session/session-log-deepseek/src/index.ts:39`](../packages/session/session-log-deepseek/src/index.ts) +- `source`: [`packages/session/session-log-deepseek/src/index.ts:47`](../packages/session/session-log-deepseek/src/index.ts) ```ts config-catalog /** Session-log request contribution configuration. */ @@ -4129,7 +4250,7 @@ export interface Config { ## `@deepseek-ai/dsh-tool-skill` - `inject`: `agents` · `tools` · `skills` · `workingDirectory` -- `source`: [`packages/skill/tool-skill/src/index.ts:62`](../packages/skill/tool-skill/src/index.ts) +- `source`: [`packages/skill/tool-skill/src/index.ts:64`](../packages/skill/tool-skill/src/index.ts) ```ts config-catalog /** Model-facing skill catalog configuration. */ @@ -4715,14 +4836,15 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co | `@deepseek-ai/dsh-client-ui-brand-official` | — | [`packages/client/ui-brand-official/src/index.ts`](../packages/client/ui-brand-official/src/index.ts) | | `@deepseek-ai/dsh-client-ui-chat` | — | [`packages/client/ui-chat/src/index.ts`](../packages/client/ui-chat/src/index.ts) | | `@deepseek-ai/dsh-client-ui-commands` | — | [`packages/client/ui-commands/src/index.ts`](../packages/client/ui-commands/src/index.ts) | +| `@deepseek-ai/dsh-client-ui-context-menu` | — | [`packages/client/ui-context-menu/src/index.ts`](../packages/client/ui-context-menu/src/index.ts) | | `@deepseek-ai/dsh-client-ui-conversation` | — | [`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts) | | `@deepseek-ai/dsh-client-ui-cordis` | — | [`packages/extensions/ui-cordis/src/index.ts`](../packages/extensions/ui-cordis/src/index.ts) | | `@deepseek-ai/dsh-client-ui-creation-recommendations` | — | [`packages/experimental/client-ui-creation-recommendations/src/index.ts`](../packages/experimental/client-ui-creation-recommendations/src/index.ts) | -| `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` | — | [`packages/client/ui-deepseek-model-label-1017/src/index.ts`](../packages/client/ui-deepseek-model-label-1017/src/index.ts) | | `@deepseek-ai/dsh-client-ui-deliverables` | `connection` · `sessionQuery` · `sessionController` · `workspaceFiles` · `fs` · `sandboxPolicy` · `workspaceChanges` | [`packages/client/ui-deliverables/src/index.ts`](../packages/client/ui-deliverables/src/index.ts) | | `@deepseek-ai/dsh-client-ui-directory-picker-browse` | — | [`packages/client/ui-directory-picker-browse/src/index.ts`](../packages/client/ui-directory-picker-browse/src/index.ts) | | `@deepseek-ai/dsh-client-ui-directory-picker-native` | — | [`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts) | | `@deepseek-ai/dsh-client-ui-entry-customization` | — | [`packages/client/ui-entry-customization/src/index.ts`](../packages/client/ui-entry-customization/src/index.ts) | +| `@deepseek-ai/dsh-client-ui-file-actions` | — | [`packages/client/ui-file-actions/src/index.ts`](../packages/client/ui-file-actions/src/index.ts) | | `@deepseek-ai/dsh-client-ui-file-drag` | — | [`packages/client/ui-file-drag/src/index.ts`](../packages/client/ui-file-drag/src/index.ts) | | `@deepseek-ai/dsh-client-ui-goal` | — | [`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts) | | `@deepseek-ai/dsh-client-ui-input-trigger` | — | [`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts) | @@ -4758,7 +4880,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co | `@deepseek-ai/dsh-client-ui-skill` | — | [`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts) | | `@deepseek-ai/dsh-client-ui-subagent` | — | [`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts) | | `@deepseek-ai/dsh-client-ui-tool` | — | [`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts) | -| `@deepseek-ai/dsh-client-ui-trajectory` | — | [`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts) | | `@deepseek-ai/dsh-client-ui-user-questions` | — | [`packages/client/ui-user-questions/src/index.ts`](../packages/client/ui-user-questions/src/index.ts) | | `@deepseek-ai/dsh-client-ui-workflow-run` | — | [`packages/client/ui-workflow-run/src/index.ts`](../packages/client/ui-workflow-run/src/index.ts) | | `@deepseek-ai/dsh-client-ui-workspace` | — | [`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts) | @@ -4777,6 +4898,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co | `@deepseek-ai/dsh-experimental-auto-review` | `approval` · `llm` · `permissionPresets` · `sessions` · `tools` · `workingDirectory` | [`packages/experimental/auto-review/src/index.ts`](../packages/experimental/auto-review/src/index.ts) | | `@deepseek-ai/dsh-experimental-client-ui-agent-team` | — | [`packages/experimental/client-ui-agent-team/src/index.ts`](../packages/experimental/client-ui-agent-team/src/index.ts) | | `@deepseek-ai/dsh-experimental-client-ui-claude-code-mods` | — | [`packages/experimental/client-ui-claude-code-mods/src/index.ts`](../packages/experimental/client-ui-claude-code-mods/src/index.ts) | +| `@deepseek-ai/dsh-experimental-client-ui-stats` | — | [`packages/experimental/client-ui-stats/src/index.ts`](../packages/experimental/client-ui-stats/src/index.ts) | | `@deepseek-ai/dsh-experimental-client-ui-voice-input` | — | [`packages/experimental/client-ui-voice-input/src/index.ts`](../packages/experimental/client-ui-voice-input/src/index.ts) | | `@deepseek-ai/dsh-experimental-computer-use-cua-driver-native` | `computerUse` · `tools` · `systemPrompt` | [`packages/experimental/computer-use-cua-driver-native/src/index.ts`](../packages/experimental/computer-use-cua-driver-native/src/index.ts) | | `@deepseek-ai/dsh-experimental-session-inspector` | — | [`packages/experimental/session-inspector/src/index.ts`](../packages/experimental/session-inspector/src/index.ts) | @@ -4870,7 +4992,9 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them. | `@deepseek-ai/dsh-experimental-badge-skill-bundle` | — | [`packages/experimental/badge-skill-bundle/src/index.ts`](../packages/experimental/badge-skill-bundle/src/index.ts) | | `@deepseek-ai/dsh-experimental-browser-use-runtime` | — | [`packages/experimental/browser-use-runtime/src/index.ts`](../packages/experimental/browser-use-runtime/src/index.ts) | | `@deepseek-ai/dsh-experimental-cot-translation-bundle` | — | [`packages/experimental/cot-translation-bundle/src/index.ts`](../packages/experimental/cot-translation-bundle/src/index.ts) | +| `@deepseek-ai/dsh-experimental-forge-bundle` | — | [`packages/experimental/forge-bundle/src/index.ts`](../packages/experimental/forge-bundle/src/index.ts) | | `@deepseek-ai/dsh-experimental-inspector-profile` | — | [`packages/experimental/inspector-profile/src/index.ts`](../packages/experimental/inspector-profile/src/index.ts) | +| `@deepseek-ai/dsh-experimental-liveshare` | — | [`packages/experimental/liveshare/src/index.ts`](../packages/experimental/liveshare/src/index.ts) | | `@deepseek-ai/dsh-experimental-liveshare-protocol` | — | [`packages/experimental/liveshare-protocol/src/index.ts`](../packages/experimental/liveshare-protocol/src/index.ts) | | `@deepseek-ai/dsh-experimental-plugin-market-bundle` | — | [`packages/experimental/plugin-market-bundle/src/index.ts`](../packages/experimental/plugin-market-bundle/src/index.ts) | | `@deepseek-ai/dsh-experimental-ralph-bundle` | — | [`packages/experimental/ralph-bundle/src/index.ts`](../packages/experimental/ralph-bundle/src/index.ts) | diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index e9fe0943c9..cbb7492c9f 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -205,7 +205,7 @@ export interface Config { ## `@deepseek-ai/dsh-api-gateway` - `inject`: `typert` · `remoteAccess` -- `source`: [`packages/api/gateway/src/index.ts:156`](../packages/api/gateway/src/index.ts) +- `source`: [`packages/api/gateway/src/index.ts:158`](../packages/api/gateway/src/index.ts) ```ts config-catalog /** Gateway transport configuration. */ @@ -244,8 +244,8 @@ export interface Config { ## `@deepseek-ai/dsh-api-session-controller` -- `inject`: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `fs` · `llm` · `remoteAccess` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry` -- `source`: [`packages/api/session-controller/src/index.ts:109`](../packages/api/session-controller/src/index.ts) +- `inject`: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `fs` · `llm` · `remoteAccess` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `typertGateway` · `workspaceRegistry` +- `source`: [`packages/api/session-controller/src/index.ts:110`](../packages/api/session-controller/src/index.ts) ```ts config-catalog /** Session Controller deployment policy. */ @@ -708,13 +708,30 @@ export type ThemePreference = typeof THEME_PREFERENCES[number] ``` + + + +## `@deepseek-ai/dsh-client-ui-trajectory` + +- `inject`: `sessions` · `typert` +- `source`: [`packages/client/ui-trajectory/src/index.ts:25`](../packages/client/ui-trajectory/src/index.ts) + +```ts config-catalog +/** Count limit for each live Session's transient tool results. */ +export interface Config { + /** Maximum retained results per Session, including values awaiting a result event. */ + maxResultsPerSession: number +} +``` + + ## `@deepseek-ai/dsh-compaction-basic` - `inject`: `llm` · `tokenMeter` · `sessions` -- `source`: [`packages/compaction/compaction-basic/src/types.ts:40`](../packages/compaction/compaction-basic/src/types.ts) +- `source`: [`packages/compaction/compaction-basic/src/types.ts:46`](../packages/compaction/compaction-basic/src/types.ts) ```ts config-catalog /** Basic compaction configuration with an optional exact-target policy table. */ @@ -1023,6 +1040,44 @@ export interface CotTranslationPreferences { ``` + + + +## `@deepseek-ai/dsh-experimental-client-ui-forge` + +- `inject`: `forge` · `forgeSession` · `sessionProjections` · `workingDirectory` · `fs` · `subprocess` · `sandbox` · `sandboxPolicy` · `agents` +- `source`: [`packages/experimental/client-ui-forge/src/types.ts:318`](../packages/experimental/client-ui-forge/src/types.ts) + +```ts config-catalog +/** Host settings of the forge panel Remote. */ +export interface Config { + /** Git executable name or absolute path in the Session's execution world. */ + gitCommand?: string + /** Deadline in milliseconds for one Git command, including confinement. */ + gitTimeoutMs?: number + /** Termination grace period in milliseconds for each Git process. */ + graceMs?: number + /** Maximum captured bytes per Git output stream. */ + maxOutputBytes?: number + /** Deadline in milliseconds for one provider sign-in probe. */ + readinessTimeoutMs?: number + /** Most local branches listed as worktree bases. */ + maxBranches?: number + /** + * Prefix of the branch and checkout directory created for a Session worktree; the first eight + * hexadecimal digits of the Session id's UUID, a hyphen, and four random hexadecimal digits follow it. + */ + worktreePrefix?: string + /** Largest diff, or file read to show unchanged lines, in bytes. */ + maxDiffBytes?: number + /** Most untracked files a local diff or the local changes card includes. */ + maxUntrackedFiles?: number + /** Most UTF-8 bytes of change request diffs kept in memory for later reads at the same head commit and base branch. */ + maxCachedDiffBytes?: number +} +``` + + @@ -1062,6 +1117,68 @@ export type Config = CuaConfig ``` + + + +## `@deepseek-ai/dsh-experimental-forge` + +- `source`: [`packages/experimental/forge/src/types.ts:232`](../packages/experimental/forge/src/types.ts) + +```ts config-catalog +/** Poll cadence and fetch deadline for watched change requests. */ +export interface Config { + /** Poll interval in milliseconds while checks run or mergeability is unknown. */ + activeIntervalMs?: number + /** Poll interval in milliseconds for a closed request or an open request whose checks have settled. */ + idleIntervalMs?: number + /** Largest delay in milliseconds between polls after consecutive failures. */ + maxBackoffMs?: number + /** Deadline in milliseconds for one provider fetch. */ + fetchTimeoutMs?: number +} +``` + + + + + +## `@deepseek-ai/dsh-experimental-forge-github` + +- `inject`: `forge` +- `source`: [`packages/experimental/forge-github/src/index.ts:14`](../packages/experimental/forge-github/src/index.ts) + +```ts config-catalog +/** GitHub CLI executable, served hosts, and invocation limits. */ +export interface Config { + /** GitHub CLI executable name or absolute host path. */ + ghCommand?: string + /** Host names this provider serves; list GitHub Enterprise hosts explicitly. */ + hosts?: string[] + /** Deadline in milliseconds for one `gh` invocation. */ + timeoutMs?: number + /** Maximum captured bytes per `gh` output stream and combined JSON bytes of one complete check read. */ + maxOutputBytes?: number +} +``` + + + + + +## `@deepseek-ai/dsh-experimental-forge-session` + +- `inject`: `forge` · `sessions` · `sessionProjections` +- `source`: [`packages/experimental/forge-session/src/types.ts:91`](../packages/experimental/forge-session/src/types.ts) + +```ts config-catalog +/** Deployment settings of `forgeSession`. */ +export interface Config { + /** Deadline in milliseconds for one change request lookup after a push. */ + discoveryTimeoutMs?: number +} +``` + + @@ -1387,7 +1504,7 @@ export type PaidTranslationProvider = 'deepseek-account' | 'deepseek-official' ## `@deepseek-ai/dsh-experimental-worktree` - `inject`: `workingDirectory` · `fs` · `subprocess` · `sandbox` · `sandboxPolicy` -- `source`: [`packages/experimental/worktree/src/index.ts:19`](../packages/experimental/worktree/src/index.ts) +- `source`: [`packages/experimental/worktree/src/index.ts:21`](../packages/experimental/worktree/src/index.ts) ```ts config-catalog /** Worktree location, generated names, executables, and subprocess resource limits. */ @@ -2106,8 +2223,8 @@ export type PiAiThinkingTokenBudgetField = NonNullable @@ -2479,7 +2598,7 @@ export interface PlanModeConfig { - `inject`: `loader` · `profileContext` - `refs`: [`NpmFileSource`](subsystems/boot.zh.md) -- `source`: [`packages/boot/plugin-manager/src/index.ts:53`](../packages/boot/plugin-manager/src/index.ts) +- `source`: [`packages/boot/plugin-manager/src/index.ts:54`](../packages/boot/plugin-manager/src/index.ts) ```ts config-catalog /** The pnpm executable, registries, and limits for diagnostics, lookups and connection checks. */ @@ -2592,8 +2711,10 @@ export interface Config { export interface Config { /** Worker invocation in the subprocess world; omitted selects the local carrier. */ launch?: LaunchConfig - /** per-call starts fresh processes; persistent-in-memory retains a REPL per owner under the same file policy. */ - executionMode?: 'per-call' | 'persistent-in-memory' + /** per-call uses fresh async function bodies; vm-script uses VM contexts; persistent-in-memory retains a REPL per owner. */ + executionMode?: 'per-call' | 'persistent-in-memory' | 'vm-script' + /** Retain a Script process and context per stateOwner; only supported with executionMode: vm-script. */ + scriptPersistence?: boolean /** Default elapsed deadline, including nested tool and approval waits. */ timeoutMs?: number /** Maximum numeric elapsed budget accepted by resolve. */ @@ -2865,7 +2986,7 @@ export interface JsonRpcConfig { - `inject`: `deepseekLlmApiExtensions` · `sessions` - `refs`: `Volatile` (`@deepseek-ai/cordis`) -- `source`: [`packages/session/session-log-deepseek/src/index.ts:39`](../packages/session/session-log-deepseek/src/index.ts) +- `source`: [`packages/session/session-log-deepseek/src/index.ts:47`](../packages/session/session-log-deepseek/src/index.ts) ```ts config-catalog /** Session-log request contribution configuration. */ @@ -4131,7 +4252,7 @@ export interface Config { ## `@deepseek-ai/dsh-tool-skill` - `inject`: `agents` · `tools` · `skills` · `workingDirectory` -- `source`: [`packages/skill/tool-skill/src/index.ts:62`](../packages/skill/tool-skill/src/index.ts) +- `source`: [`packages/skill/tool-skill/src/index.ts:64`](../packages/skill/tool-skill/src/index.ts) ```ts config-catalog /** Model-facing skill catalog configuration. */ @@ -4717,14 +4838,15 @@ export interface Config { | `@deepseek-ai/dsh-client-ui-brand-official` | — | [`packages/client/ui-brand-official/src/index.ts`](../packages/client/ui-brand-official/src/index.ts) | | `@deepseek-ai/dsh-client-ui-chat` | — | [`packages/client/ui-chat/src/index.ts`](../packages/client/ui-chat/src/index.ts) | | `@deepseek-ai/dsh-client-ui-commands` | — | [`packages/client/ui-commands/src/index.ts`](../packages/client/ui-commands/src/index.ts) | +| `@deepseek-ai/dsh-client-ui-context-menu` | — | [`packages/client/ui-context-menu/src/index.ts`](../packages/client/ui-context-menu/src/index.ts) | | `@deepseek-ai/dsh-client-ui-conversation` | — | [`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts) | | `@deepseek-ai/dsh-client-ui-cordis` | — | [`packages/extensions/ui-cordis/src/index.ts`](../packages/extensions/ui-cordis/src/index.ts) | | `@deepseek-ai/dsh-client-ui-creation-recommendations` | — | [`packages/experimental/client-ui-creation-recommendations/src/index.ts`](../packages/experimental/client-ui-creation-recommendations/src/index.ts) | -| `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` | — | [`packages/client/ui-deepseek-model-label-1017/src/index.ts`](../packages/client/ui-deepseek-model-label-1017/src/index.ts) | | `@deepseek-ai/dsh-client-ui-deliverables` | `connection` · `sessionQuery` · `sessionController` · `workspaceFiles` · `fs` · `sandboxPolicy` · `workspaceChanges` | [`packages/client/ui-deliverables/src/index.ts`](../packages/client/ui-deliverables/src/index.ts) | | `@deepseek-ai/dsh-client-ui-directory-picker-browse` | — | [`packages/client/ui-directory-picker-browse/src/index.ts`](../packages/client/ui-directory-picker-browse/src/index.ts) | | `@deepseek-ai/dsh-client-ui-directory-picker-native` | — | [`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts) | | `@deepseek-ai/dsh-client-ui-entry-customization` | — | [`packages/client/ui-entry-customization/src/index.ts`](../packages/client/ui-entry-customization/src/index.ts) | +| `@deepseek-ai/dsh-client-ui-file-actions` | — | [`packages/client/ui-file-actions/src/index.ts`](../packages/client/ui-file-actions/src/index.ts) | | `@deepseek-ai/dsh-client-ui-file-drag` | — | [`packages/client/ui-file-drag/src/index.ts`](../packages/client/ui-file-drag/src/index.ts) | | `@deepseek-ai/dsh-client-ui-goal` | — | [`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts) | | `@deepseek-ai/dsh-client-ui-input-trigger` | — | [`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts) | @@ -4760,7 +4882,6 @@ export interface Config { | `@deepseek-ai/dsh-client-ui-skill` | — | [`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts) | | `@deepseek-ai/dsh-client-ui-subagent` | — | [`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts) | | `@deepseek-ai/dsh-client-ui-tool` | — | [`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts) | -| `@deepseek-ai/dsh-client-ui-trajectory` | — | [`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts) | | `@deepseek-ai/dsh-client-ui-user-questions` | — | [`packages/client/ui-user-questions/src/index.ts`](../packages/client/ui-user-questions/src/index.ts) | | `@deepseek-ai/dsh-client-ui-workflow-run` | — | [`packages/client/ui-workflow-run/src/index.ts`](../packages/client/ui-workflow-run/src/index.ts) | | `@deepseek-ai/dsh-client-ui-workspace` | — | [`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts) | @@ -4779,6 +4900,7 @@ export interface Config { | `@deepseek-ai/dsh-experimental-auto-review` | `approval` · `llm` · `permissionPresets` · `sessions` · `tools` · `workingDirectory` | [`packages/experimental/auto-review/src/index.ts`](../packages/experimental/auto-review/src/index.ts) | | `@deepseek-ai/dsh-experimental-client-ui-agent-team` | — | [`packages/experimental/client-ui-agent-team/src/index.ts`](../packages/experimental/client-ui-agent-team/src/index.ts) | | `@deepseek-ai/dsh-experimental-client-ui-claude-code-mods` | — | [`packages/experimental/client-ui-claude-code-mods/src/index.ts`](../packages/experimental/client-ui-claude-code-mods/src/index.ts) | +| `@deepseek-ai/dsh-experimental-client-ui-stats` | — | [`packages/experimental/client-ui-stats/src/index.ts`](../packages/experimental/client-ui-stats/src/index.ts) | | `@deepseek-ai/dsh-experimental-client-ui-voice-input` | — | [`packages/experimental/client-ui-voice-input/src/index.ts`](../packages/experimental/client-ui-voice-input/src/index.ts) | | `@deepseek-ai/dsh-experimental-computer-use-cua-driver-native` | `computerUse` · `tools` · `systemPrompt` | [`packages/experimental/computer-use-cua-driver-native/src/index.ts`](../packages/experimental/computer-use-cua-driver-native/src/index.ts) | | `@deepseek-ai/dsh-experimental-session-inspector` | — | [`packages/experimental/session-inspector/src/index.ts`](../packages/experimental/session-inspector/src/index.ts) | @@ -4872,7 +4994,9 @@ export interface Config { | `@deepseek-ai/dsh-experimental-badge-skill-bundle` | — | [`packages/experimental/badge-skill-bundle/src/index.ts`](../packages/experimental/badge-skill-bundle/src/index.ts) | | `@deepseek-ai/dsh-experimental-browser-use-runtime` | — | [`packages/experimental/browser-use-runtime/src/index.ts`](../packages/experimental/browser-use-runtime/src/index.ts) | | `@deepseek-ai/dsh-experimental-cot-translation-bundle` | — | [`packages/experimental/cot-translation-bundle/src/index.ts`](../packages/experimental/cot-translation-bundle/src/index.ts) | +| `@deepseek-ai/dsh-experimental-forge-bundle` | — | [`packages/experimental/forge-bundle/src/index.ts`](../packages/experimental/forge-bundle/src/index.ts) | | `@deepseek-ai/dsh-experimental-inspector-profile` | — | [`packages/experimental/inspector-profile/src/index.ts`](../packages/experimental/inspector-profile/src/index.ts) | +| `@deepseek-ai/dsh-experimental-liveshare` | — | [`packages/experimental/liveshare/src/index.ts`](../packages/experimental/liveshare/src/index.ts) | | `@deepseek-ai/dsh-experimental-liveshare-protocol` | — | [`packages/experimental/liveshare-protocol/src/index.ts`](../packages/experimental/liveshare-protocol/src/index.ts) | | `@deepseek-ai/dsh-experimental-plugin-market-bundle` | — | [`packages/experimental/plugin-market-bundle/src/index.ts`](../packages/experimental/plugin-market-bundle/src/index.ts) | | `@deepseek-ai/dsh-experimental-ralph-bundle` | — | [`packages/experimental/ralph-bundle/src/index.ts`](../packages/experimental/ralph-bundle/src/index.ts) | diff --git a/docs/cookbook/adding-a-plugin-preview.i18n.yaml b/docs/cookbook/adding-a-plugin-preview.i18n.yaml index 0111677ab5..9884dce36b 100644 --- a/docs/cookbook/adding-a-plugin-preview.i18n.yaml +++ b/docs/cookbook/adding-a-plugin-preview.i18n.yaml @@ -3,17 +3,17 @@ # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/cookbook/adding-a-plugin-preview.md /cookbook-add-a-plugin-feature-preview: - en: c37096cd3cdb886c - zh: fc6850d68c638898 + en: a0db5c6e164abfa1 + zh: 792c831c20a41e5d /cookbook-add-a-plugin-feature-preview/1-decide-whether-an-image-helps: - en: ee84f52d834cbccf - zh: 7bf3a425a231b5e6 + en: 0b401d0094e3b8ae + zh: d9eaedfaf8be012e /cookbook-add-a-plugin-feature-preview/2-draw-one-fixed-size-svg: en: 3a28640aa605dce8 zh: c5336958f92b5a70 -/cookbook-add-a-plugin-feature-preview/3-put-it-at-the-top-of-the-detail-document: - en: 17e2ace32a89c419 - zh: c635a890e86a41ec +/cookbook-add-a-plugin-feature-preview/3-make-it-the-detail-document: + en: ad09702c601e05a6 + zh: ae03649d34ab08b1 /cookbook-add-a-plugin-feature-preview/4-page-behavior: en: 20ce358cb110104c zh: abb8d72fed81f3c8 diff --git a/docs/cookbook/adding-a-plugin-preview.md b/docs/cookbook/adding-a-plugin-preview.md index 1683aab10a..1a2ceb9d81 100644 --- a/docs/cookbook/adding-a-plugin-preview.md +++ b/docs/cookbook/adding-a-plugin-preview.md @@ -2,11 +2,11 @@ English | [中文](adding-a-plugin-preview.zh.md) -A feature preview is an optional illustration at the top of a bundle's detail document, the long description that its page in **Plugins** shows first. Follow this guide when drawing one for an official bundle. The detail document itself is declared through [`meta.detail`](adding-a-package.md#plugin-display-metadata). +A feature preview is an optional illustration in a bundle's detail document, the document that its page in **Plugins** shows below the description. Follow this guide when drawing one for an official bundle. The detail document itself is declared through [`meta.detail`](adding-a-package.md#plugin-display-metadata). ## 1. Decide whether an image helps -Show one concrete result or recognizable capability. Omit the image when the description is enough: no image is required. Essential instructions stay in the document's text or in configuration outside the illustration. +Show one concrete result or recognizable capability. Omit the image when the description is enough: no image is required. Essential instructions stay in the bundle's description or in configuration outside the illustration. ## 2. Draw one fixed-size SVG @@ -21,15 +21,15 @@ Show one concrete result or recognizable capability. Omit the image when the des The SVG is self-contained: no fonts, remote resources, scripts, handlers, animation, stylesheets, `text`, or `foreignObject`. An `image` element may embed an unchanged official PNG/JPEG/WebP brand asset as a base64 data URL. Small plugin icons remain geometry-only. The page renders the SVG through ``. Keep each file small; the Host refuses images above plugin-manager's `detailImageMaxBytes`, 5 MiB by default. -## 3. Put it at the top of the detail document +## 3. Make it the detail document -Save the pair as `docs/preview.svg` and `docs/preview.zh.svg` in the bundle package, beside `docs/DETAIL.md` and `docs/DETAIL.zh.md`, and make the image the first line of each document: +Save the pair as `docs/preview.svg` and `docs/preview.zh.svg` in the bundle package, beside `docs/DETAIL.md` and `docs/DETAIL.zh.md`, and make the image the only line of each document: ```markdown ![Example feature preview](preview.svg) ``` -The Chinese document references `preview.zh.svg` with Chinese alternative text. Use the [badge skill](../../packages/experimental/badge-skill-bundle/docs/DETAIL.md) and [voice input](../../packages/experimental/voice-input-bundle/docs/DETAIL.md) documents as examples. The voice transcript is explanatory sample content, not a recording result. +The Chinese document references `preview.zh.svg` with Chinese alternative text. Use the [badge skill](../../packages/experimental/badge-skill-bundle/docs/DETAIL.md) and [voice input](../../packages/experimental/voice-input-bundle/docs/DETAIL.md) documents as examples. The voice transcript is explanatory sample content, not a recording result. Describe what the bundle does and how to use it, at the level of behavior, in `meta.description`, which the page shows above the image. ## 4. Page behavior diff --git a/docs/cookbook/adding-a-plugin-preview.zh.md b/docs/cookbook/adding-a-plugin-preview.zh.md index 3d3caeb1bf..bc6d208ac3 100644 --- a/docs/cookbook/adding-a-plugin-preview.zh.md +++ b/docs/cookbook/adding-a-plugin-preview.zh.md @@ -2,11 +2,11 @@ [English](adding-a-plugin-preview.md) | 中文 -功能配图是位于组合包详细介绍文档顶部的可选插图；详细介绍文档是该组合包在**插件**中的页面最先显示的长描述。为官方组合包绘制配图时遵循本指引。详细介绍文档本身通过 [`meta.detail`](adding-a-package.zh.md#plugin-display-metadata) 声明。 +功能配图是组合包详细介绍文档中的可选插图；详细介绍文档是该组合包在**插件**中的页面显示在描述下方的文档。为官方组合包绘制配图时遵循本指引。详细介绍文档本身通过 [`meta.detail`](adding-a-package.zh.md#plugin-display-metadata) 声明。 ## 1. 判断是否需要配图 -展示一个具体结果或容易辨认的能力。文字说明足够时省略配图：配图不是必需的。必要操作说明仍放在文档文字或图外的配置中。 +展示一个具体结果或容易辨认的能力。文字说明足够时省略配图：配图不是必需的。必要操作说明仍放在组合包描述或图外的配置中。 ## 2. 绘制一张固定尺寸 SVG @@ -21,15 +21,15 @@ SVG 必须自包含：不使用字体、远程资源、脚本、事件处理器、动画、样式表、`text` 或 `foreignObject`。`image` 元素可以通过 base64 data URL 嵌入未改动的官方 PNG/JPEG/WebP 品牌素材。小插件图标仍仅使用几何图形。页面通过 `` 渲染 SVG。每个文件都应控制大小；Host 会拒绝超过 plugin-manager 的 `detailImageMaxBytes`（默认 5 MiB）的图片。 -## 3. 放在详细介绍文档顶部 +## 3. 用它作为详细介绍文档 -将这对文件保存为组合包中的 `docs/preview.svg` 和 `docs/preview.zh.svg`，与 `docs/DETAIL.md` 和 `docs/DETAIL.zh.md` 放在一起，并把图片作为每份文档的第一行： +将这对文件保存为组合包中的 `docs/preview.svg` 和 `docs/preview.zh.svg`，与 `docs/DETAIL.md` 和 `docs/DETAIL.zh.md` 放在一起，并把图片作为每份文档唯一的一行： ```markdown ![Example feature preview](preview.svg) ``` -中文文档引用 `preview.zh.svg`，并使用中文替代文字。可参考[徽章技能](../../packages/experimental/badge-skill-bundle/docs/DETAIL.md)和[语音输入](../../packages/experimental/voice-input-bundle/docs/DETAIL.md)文档。语音图中的转写文字是说明性示例，不是录音结果。 +中文文档引用 `preview.zh.svg`，并使用中文替代文字。可参考[徽章技能](../../packages/experimental/badge-skill-bundle/docs/DETAIL.md)和[语音输入](../../packages/experimental/voice-input-bundle/docs/DETAIL.md)文档。语音图中的转写文字是说明性示例，不是录音结果。组合包做什么、怎么用，按行为层面写在 `meta.description` 中，页面将其显示在配图上方。 ## 4. 页面行为 diff --git a/docs/cordis-api/context.md b/docs/cordis-api/context.md index 320b23de1c..453f607768 100644 --- a/docs/cordis-api/context.md +++ b/docs/cordis-api/context.md @@ -110,7 +110,7 @@ The root context of the application (every child context shares it). @experiment ```ts cordis-catalog /** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */ -baseUrl?: string +baseUrl?: string | undefined ``` Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. diff --git a/docs/cordis-api/context.zh.md b/docs/cordis-api/context.zh.md index b97fe51eb8..a5c7e36b4b 100644 --- a/docs/cordis-api/context.zh.md +++ b/docs/cordis-api/context.zh.md @@ -112,7 +112,7 @@ root: this ```ts cordis-catalog /** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */ -baseUrl?: string +baseUrl?: string | undefined ``` 用于解析相对插件／模块说明符的基础 URL，前提是运行时设置了该值。 diff --git a/docs/cordis-api/events.i18n.yaml b/docs/cordis-api/events.i18n.yaml index 68421a5f2c..f423afad17 100644 --- a/docs/cordis-api/events.i18n.yaml +++ b/docs/cordis-api/events.i18n.yaml @@ -9,29 +9,29 @@ en: 9d809e3de33dd783 zh: b965aee4a65c6c1a /events/ctx-parallel-name-args: - en: e583c71acb606915 - zh: 0560679b20f8d7f0 + en: 9c0a63f484e33428 + zh: 09ee4c26931324af /events/ctx-emit-name-args: - en: ff6f4023b66f8164 - zh: af16d24d663a7eb7 + en: b41bd01cf219cbd6 + zh: 2e9660a05dc07cfc /events/ctx-serial-name-args: - en: c431c0e3ac72e854 - zh: c43b7d899ea8161c + en: 46708104f4d6a034 + zh: f1b7fcb92a5b05c0 /events/ctx-bail-name-args: - en: 85b8b2178c3e3c33 - zh: ad8af3e0743e231c + en: 6577e113d5b8ce40 + zh: b925f8070cf387f7 /events/ctx-waterfall-name-args: - en: 3b32d0511b7da48b - zh: e0ac62e59d8e2152 + en: 105fda32f60c7cea + zh: c67e6c6051c9a1af /events/ctx-on-name-listener-options: - en: 74a1fe55f4a47ec8 - zh: 87d37038af3bab0e + en: ec7c7e8a8b15d460 + zh: 79eba67c31873b0b /events/ctx-once-name-listener-options: - en: 64802f0580705984 - zh: 3f6ce2d7ce1e760d + en: 27143e45f63622dd + zh: 095f804dfa47ad37 /events/eventoptions: - en: 937453f689836c80 - zh: ebf0cc0f28127245 + en: 14ed1031e4a7abee + zh: 2380e2f73f8931af /events/dispatchmode: - en: 1c8548fb249ed794 - zh: 86b92a28f39b2a12 + en: 1081bbd7aa27baf8 + zh: cc4434892b0bb93f diff --git a/docs/cordis-api/events.md b/docs/cordis-api/events.md index 8b8eb2358e..1916532331 100644 --- a/docs/cordis-api/events.md +++ b/docs/cordis-api/events.md @@ -26,7 +26,7 @@ Dispatch an event, running all listeners concurrently. **Returns** a promise resolving once every listener has settled. -[Source](../../vendor/cordis/src/events.ts#L44) +[Source](../../vendor/cordis/src/events.ts#L43) ### ctx.emit(name, ...args) @@ -46,7 +46,7 @@ Dispatch an event synchronously, ignoring listener return values. - `name` — the event name. - `args` — arguments passed to every listener. -[Source](../../vendor/cordis/src/events.ts#L53) +[Source](../../vendor/cordis/src/events.ts#L52) ### ctx.serial(name, ...args) @@ -69,7 +69,7 @@ Dispatch an event, awaiting listeners in order until one bails. **Returns** the first bail value (non-null, non-false, non-undefined), if any. -[Source](../../vendor/cordis/src/events.ts#L63) +[Source](../../vendor/cordis/src/events.ts#L62) ### ctx.bail(name, ...args) @@ -92,7 +92,7 @@ Dispatch an event, calling listeners in order until one bails. **Returns** the first bail value (non-null, non-false, non-undefined), if any. -[Source](../../vendor/cordis/src/events.ts#L73) +[Source](../../vendor/cordis/src/events.ts#L72) ### ctx.waterfall(name, ...args) @@ -120,7 +120,7 @@ Each listener wraps the rest of the chain: calling `next()` invokes the next lis **Returns** the outermost listener's return value. -[Source](../../vendor/cordis/src/events.ts#L86) +[Source](../../vendor/cordis/src/events.ts#L85) ### ctx.on(name, listener, options?) @@ -144,7 +144,7 @@ Register an event listener owned by the current fiber. **Returns** a disposer removing the listener; `true` if it was still registered. -[Source](../../vendor/cordis/src/events.ts#L97) +[Source](../../vendor/cordis/src/events.ts#L96) ### ctx.once(name, listener, options?) @@ -168,7 +168,7 @@ Same as `on()`, but the listener disposes itself after its first call. **Returns** a disposer removing the listener; `true` if it was still registered. -[Source](../../vendor/cordis/src/events.ts#L106) +[Source](../../vendor/cordis/src/events.ts#L105) ## EventOptions @@ -184,7 +184,7 @@ interface EventOptions { } ``` -[Source](../../vendor/cordis/src/events.ts#L112) +[Source](../../vendor/cordis/src/events.ts#L111) ## DispatchMode @@ -204,4 +204,4 @@ Event dispatch strategy used by the event service. type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall' ``` -[Source](../../vendor/cordis/src/events.ts#L32) +[Source](../../vendor/cordis/src/events.ts#L31) diff --git a/docs/cordis-api/events.zh.md b/docs/cordis-api/events.zh.md index 60b0580496..b66a1fc4d3 100644 --- a/docs/cordis-api/events.zh.md +++ b/docs/cordis-api/events.zh.md @@ -28,7 +28,7 @@ parallel(thisArg: NoInfer>, name: K, **返回值**：一个 Promise，在所有监听器均已完成后兑现。 -[源码](../../vendor/cordis/src/events.ts#L44) +[源码](../../vendor/cordis/src/events.ts#L43) ### ctx.emit(name, ...args) @@ -48,7 +48,7 @@ emit(thisArg: NoInfer>, name: K, ... - `name`：事件名称。 - `args`：传递给每个监听器的参数。 -[源码](../../vendor/cordis/src/events.ts#L53) +[源码](../../vendor/cordis/src/events.ts#L52) ### ctx.serial(name, ...args) @@ -71,7 +71,7 @@ serial(thisArg: NoInfer>, name: K, . **返回值**：第一个提前终止值（非 null、非 false 且非 undefined）；如果没有，则不返回此类值。 -[源码](../../vendor/cordis/src/events.ts#L63) +[源码](../../vendor/cordis/src/events.ts#L62) ### ctx.bail(name, ...args) @@ -94,7 +94,7 @@ bail(thisArg: NoInfer>, name: K, ... **返回值**：第一个提前终止值（非 null、非 false 且非 undefined）；如果没有，则不返回此类值。 -[源码](../../vendor/cordis/src/events.ts#L73) +[源码](../../vendor/cordis/src/events.ts#L72) ### ctx.waterfall(name, ...args) @@ -122,7 +122,7 @@ waterfall(thisArg: NoInfer>, name: K **返回值**：最外层监听器的返回值。 -[源码](../../vendor/cordis/src/events.ts#L86) +[源码](../../vendor/cordis/src/events.ts#L85) ### ctx.on(name, listener, options?) @@ -146,7 +146,7 @@ on(name: K, listener: Events[K], options?: boolean | Eve **返回值**：一个用于移除监听器的资源释放函数；如果调用该函数时监听器仍处于注册状态，则返回 `true`。 -[源码](../../vendor/cordis/src/events.ts#L97) +[源码](../../vendor/cordis/src/events.ts#L96) ### ctx.once(name, listener, options?) @@ -170,7 +170,7 @@ once(name: K, listener: Events[K], options?: boolean | E **返回值**：一个用于移除监听器的资源释放函数；如果调用该函数时监听器仍处于注册状态，则返回 `true`。 -[源码](../../vendor/cordis/src/events.ts#L106) +[源码](../../vendor/cordis/src/events.ts#L105) ## EventOptions @@ -186,7 +186,7 @@ interface EventOptions { } ``` -[源码](../../vendor/cordis/src/events.ts#L112) +[源码](../../vendor/cordis/src/events.ts#L111) ## DispatchMode @@ -206,4 +206,4 @@ interface EventOptions { type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall' ``` -[源码](../../vendor/cordis/src/events.ts#L32) +[源码](../../vendor/cordis/src/events.ts#L31) diff --git a/docs/cordis-api/fiber.i18n.yaml b/docs/cordis-api/fiber.i18n.yaml index 042af3ba02..aeba613660 100644 --- a/docs/cordis-api/fiber.i18n.yaml +++ b/docs/cordis-api/fiber.i18n.yaml @@ -9,14 +9,14 @@ en: b5b3510f4b6dd13a zh: a0c70471b6d779b5 /fiber/ctx-effect-execute-label: - en: ef3418fd5ffbe86d - zh: c98935435da8bc7e + en: 38bab93cf931eec1 + zh: 50fed09622da4926 /fiber/ctx-fiber: en: a10e38bf26b4ecfe zh: 7c91817984c95c99 /fiber/the-fiber-class: - en: 0e0fcb134ed44957 - zh: 326f4232aa0e65d1 + en: 31ca1205552db9ef + zh: 5fa2e5b9a7396576 /fiber/the-fiber-class/fiber-uid: en: 2f0eb3658bb8497e zh: 65d3c17ca8bd4f95 @@ -24,50 +24,53 @@ en: 1b527d85759324f9 zh: 54aa40db2705b95c /fiber/the-fiber-class/fiber-config: - en: 1efe137a7ef0e599 - zh: bb4b9818fb48f4e9 + en: 73b05dc38761b681 + zh: d663668f3e8fd33f /fiber/the-fiber-class/fiber-state: - en: 999ad29dfc29661b - zh: 20245d11c338e3f1 + en: eda419fecddc4dc8 + zh: 1a1b90f405cf3cbc /fiber/the-fiber-class/fiber-dispose: - en: 29e304d183eb9104 - zh: 9ac5023f518e06c4 -/fiber/the-fiber-class/fiber-store: - en: c4185e5d051136a2 - zh: 5714d9e4f5461ca3 + en: 43f4ad79a728a492 + zh: 71b216695d0afb22 +/fiber/the-fiber-class/fiber-committed: + en: 0485c9d782bf90da + zh: 74304cd05e9c0796 +/fiber/the-fiber-class/fiber-provisions: + en: 1cf8235d0ca54124 + zh: 3d2e39064853165f /fiber/the-fiber-class/fiber-inertia: en: 2a3b1d3bc37bf986 zh: 83bd257ee685d38b /fiber/the-fiber-class/fiber-name: - en: e5c2ecca13167a32 - zh: 284a461f0f1cd35b + en: cdc0677ce1d83361 + zh: a58305521a0626de /fiber/the-fiber-class/fiber-assertactive: - en: cceb503899634d09 - zh: a8381af1a23436f3 + en: 0c3e8008ff2d69e2 + zh: 7b454626d3e3a3b6 /fiber/the-fiber-class/fiber-effect-execute-label: - en: 55dcfacf295bbcf2 - zh: 6e3ec27bb8da5a3d + en: 0e905aa798ce3830 + zh: bbd0b0c537097d37 /fiber/the-fiber-class/fiber-geteffects: - en: 4d739a9c186fd9c2 - zh: f80fd3b87e79b004 + en: 729a1000bda8ee36 + zh: 5bfc19df3addab80 /fiber/the-fiber-class/fiber-rawconfig: - en: 898aab51825bd8c3 - zh: b9ab6339574002df + en: 80d4007e42bd8b47 + zh: 14c11dc09c6402ce /fiber/the-fiber-class/fiber-effectiveconfig: - en: 93ac680251e7023f - zh: 8ea7d7de5db39b8e + en: 8e9fcdcf458c8bde + zh: 36d21cafbf4f0198 /fiber/the-fiber-class/fiber-resolveconfig-config: - en: d7319852e2a1c3a9 - zh: 3300fac049227006 + en: f8a9ca27b288bd4c + zh: 03ce360b5200fbdb /fiber/the-fiber-class/fiber-await: - en: c9a6544cacdbc28e - zh: 636bf93efad95bc9 + en: 3f228c1861466386 + zh: 43b3f3acfc3d314b /fiber/the-fiber-class/fiber-restart: - en: 6ffc1baba98d689f - zh: 7e13bc92225c7e0a + en: 152116f669f52e95 + zh: 11d3cd941ce32d88 /fiber/the-fiber-class/fiber-update-config-nosave: - en: 5c176a6e67073e92 - zh: ee07edc8dbf7c1f3 + en: a4f711258eb70e47 + zh: fff4d880d820de10 /fiber/effect: en: 007d5b214e8a8610 zh: d74c26fbb1b8aeb6 diff --git a/docs/cordis-api/fiber.md b/docs/cordis-api/fiber.md index e85cc7b3e6..3bfc3a00e9 100644 --- a/docs/cordis-api/fiber.md +++ b/docs/cordis-api/fiber.md @@ -34,7 +34,7 @@ Register a cleanup-aware effect on this fiber. **Returns** a disposer that tears the effect down and settles once done. -[Source](../../vendor/cordis/src/fiber.ts#L415) +[Source](../../vendor/cordis/src/fiber.ts#L421) ### ctx.fiber @@ -51,7 +51,7 @@ The fiber (plugin runtime instance) that owns this context. Runtime instance of one plugin application. -A fiber tracks dependency state, validated config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`. +A fiber tracks dependency state, raw and effective config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`. [Source](../../vendor/cordis/src/fiber.ts#L184) @@ -80,11 +80,11 @@ The context this fiber's plugin runs in (extends the parent context). ### fiber.config ```ts cordis-catalog -/** The validated plugin config (updated by `update()`); read through {@link effectiveConfig}. */ +/** Raw plugin input retained for the next activation. */ public config: any ``` -The validated plugin config (updated by `update()`); read through effectiveConfig. +Raw plugin input retained for the next activation. [Source](../../vendor/cordis/src/fiber.ts#L190) @@ -97,7 +97,7 @@ public state Current lifecycle state; transitions emit `internal/status`. -[Source](../../vendor/cordis/src/fiber.ts#L194) +[Source](../../vendor/cordis/src/fiber.ts#L192) ### fiber.dispose @@ -108,16 +108,27 @@ public readonly dispose: () => Promise Dispose this fiber: unload the plugin, then settle once cleanup finished. -[Source](../../vendor/cordis/src/fiber.ts#L196) +[Source](../../vendor/cordis/src/fiber.ts#L194) -### fiber.store +### fiber.committed ```ts cordis-catalog -/** Snapshot of required service implementations while loaded; `undefined` otherwise. */ -public store: Dict | undefined +/** Required implementations retained through dependent teardown. */ +public committed: Readonly> | undefined ``` -Snapshot of required service implementations while loaded; `undefined` otherwise. +Required implementations retained through dependent teardown. + +[Source](../../vendor/cordis/src/fiber.ts#L196) + +### fiber.provisions + +```ts cordis-catalog +/** Service implementations owned by this fiber, including isolated provisions. */ +public readonly provisions: Set +``` + +Service implementations owned by this fiber, including isolated provisions. [Source](../../vendor/cordis/src/fiber.ts#L198) @@ -141,7 +152,7 @@ get name() The plugin's display name, inherited from the nearest named ancestor, else `'root'`. -[Source](../../vendor/cordis/src/fiber.ts#L336) +[Source](../../vendor/cordis/src/fiber.ts#L342) ### fiber.assertActive() @@ -159,7 +170,7 @@ Throw if the fiber has already been disposed. **Returns** nothing when the fiber is still active. -[Source](../../vendor/cordis/src/fiber.ts#L351) +[Source](../../vendor/cordis/src/fiber.ts#L357) ### fiber.effect(execute, label?) @@ -190,7 +201,7 @@ Register a cleanup-aware effect on this fiber. **Returns** a disposer that tears the effect down and settles once done. -[Source](../../vendor/cordis/src/fiber.ts#L415) +[Source](../../vendor/cordis/src/fiber.ts#L421) ### fiber.getEffects() @@ -207,7 +218,7 @@ Return metadata for currently registered effects. **Returns** one `EffectMeta` tree per labeled live effect. -[Source](../../vendor/cordis/src/fiber.ts#L568) +[Source](../../vendor/cordis/src/fiber.ts#L574) ### fiber.rawConfig @@ -218,21 +229,22 @@ get rawConfig(): unknown Raw input retained for the next activation, without evaluating expressions or validating it. -[Source](../../vendor/cordis/src/fiber.ts#L642) +[Source](../../vendor/cordis/src/fiber.ts#L649) ### fiber.effectiveConfig ```ts cordis-catalog /** - * The config object published by the existing activation/update lifecycle, without cloning or re-parsing. - * It is undefined before the first resolution and remains readable after unload; callers requiring a live instance check `state`. + * The object passed to plugin activation or the latest successful update that retained the instance. + * Candidate resolution does not publish it; volatile updates retain its references. + * Undefined before activation and readable after unload; callers requiring a live instance check `state`. */ get effectiveConfig(): unknown ``` -The config object published by the existing activation/update lifecycle, without cloning or re-parsing. It is undefined before the first resolution and remains readable after unload; callers requiring a live instance check `state`. +The object passed to plugin activation or the latest successful update that retained the instance. Candidate resolution does not publish it; volatile updates retain its references. Undefined before activation and readable after unload; callers requiring a live instance check `state`. -[Source](../../vendor/cordis/src/fiber.ts#L655) +[Source](../../vendor/cordis/src/fiber.ts#L664) ### fiber.resolveConfig(config) @@ -254,7 +266,7 @@ Evaluate and validate a candidate using this fiber's `internal/config` hooks and **Returns** The candidate's resolved config, retaining the schema's result identity. -[Source](../../vendor/cordis/src/fiber.ts#L667) +[Source](../../vendor/cordis/src/fiber.ts#L676) ### fiber.await() @@ -272,7 +284,7 @@ Wait for current lifecycle work and rethrow startup errors. **Returns** this fiber, once it has settled into a stable state. -[Source](../../vendor/cordis/src/fiber.ts#L731) +[Source](../../vendor/cordis/src/fiber.ts#L754) ### fiber.restart() @@ -290,35 +302,29 @@ Dispose and immediately reload this plugin with its current config. **Returns** a promise resolving once the reload settled. -[Source](../../vendor/cordis/src/fiber.ts#L745) +[Source](../../vendor/cordis/src/fiber.ts#L768) ### fiber.update(config, noSave?) ```ts cordis-catalog /** - * Validate and apply new config, then restart the plugin. - * - * Runs the `internal/update` waterfall first, so update hooks (and HMR) - * can veto or replace the restart. - * - * @param config — the new raw config; validated before anything restarts. - * @param noSave — hint for persistence hooks not to write the change back. - * @returns nothing; the restart runs behind the `internal/update` waterfall. - * @throws {ValidationError} when the new config fails validation. + * Resolve a candidate, retain its raw config and apply it through the update waterfall. + * @param config Raw config; pending fibers defer resolution until activation. + * @param noSave Suppress the persistence notification when true. + * @returns The awaited update/restart result, or undefined when a synchronous listener handles it. + * @throws {ValidationError} when an active fiber's candidate is invalid. */ -update(config: any, noSave = false) +update(config: any, noSave = false): Awaitable ``` -Validate and apply new config, then restart the plugin. +Resolve a candidate, retain its raw config and apply it through the update waterfall. -Runs the `internal/update` waterfall first, so update hooks (and HMR) can veto or replace the restart. +- `config` — Raw config; pending fibers defer resolution until activation. +- `noSave` — Suppress the persistence notification when true. -- `config` — the new raw config; validated before anything restarts. -- `noSave` — hint for persistence hooks not to write the change back. +**Returns** The awaited update/restart result, or undefined when a synchronous listener handles it. -**Returns** nothing; the restart runs behind the `internal/update` waterfall. - -[Source](../../vendor/cordis/src/fiber.ts#L764) +[Source](../../vendor/cordis/src/fiber.ts#L783) ## Effect diff --git a/docs/cordis-api/fiber.zh.md b/docs/cordis-api/fiber.zh.md index d529013e73..88d253452d 100644 --- a/docs/cordis-api/fiber.zh.md +++ b/docs/cordis-api/fiber.zh.md @@ -36,7 +36,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable> **返回**一个用于撤销该作用的清理函数，并在清理完成后结算。 -[源码](../../vendor/cordis/src/fiber.ts#L415) +[源码](../../vendor/cordis/src/fiber.ts#L421) ### ctx.fiber @@ -53,7 +53,7 @@ fiber: Fiber 单次插件应用的运行时实例。 -fiber 会跟踪 `ctx.plugin()` 返回的插件上下文所对应的依赖状态、经过校验的配置、生命周期作用和清理操作。 +fiber 会跟踪 `ctx.plugin()` 返回的插件上下文所对应的依赖状态、原始配置与有效配置、生命周期作用和清理操作。 [源码](../../vendor/cordis/src/fiber.ts#L184) @@ -82,11 +82,11 @@ public readonly ctx: Context ### fiber.config ```ts cordis-catalog -/** The validated plugin config (updated by `update()`); read through {@link effectiveConfig}. */ +/** Raw plugin input retained for the next activation. */ public config: any ``` -经过校验的插件配置（由 `update()` 更新）；通过 `effectiveConfig` 读取。 +为下次激活保留的原始插件输入。 [源码](../../vendor/cordis/src/fiber.ts#L190) @@ -99,7 +99,7 @@ public state 当前生命周期状态；状态转换会发出 `internal/status`。 -[源码](../../vendor/cordis/src/fiber.ts#L194) +[源码](../../vendor/cordis/src/fiber.ts#L192) ### fiber.dispose @@ -110,16 +110,27 @@ public readonly dispose: () => Promise dispose 此 fiber：卸载插件，并在清理完成后结算。 -[源码](../../vendor/cordis/src/fiber.ts#L196) +[源码](../../vendor/cordis/src/fiber.ts#L194) -### fiber.store +### fiber.committed ```ts cordis-catalog -/** Snapshot of required service implementations while loaded; `undefined` otherwise. */ -public store: Dict | undefined +/** Required implementations retained through dependent teardown. */ +public committed: Readonly> | undefined ``` -加载期间所需服务实现的快照；其他情况下为 `undefined`。 +在依赖方清理完成前保留的所需服务实现。 + +[源码](../../vendor/cordis/src/fiber.ts#L196) + +### fiber.provisions + +```ts cordis-catalog +/** Service implementations owned by this fiber, including isolated provisions. */ +public readonly provisions: Set +``` + +此 fiber 拥有的服务实现，包括隔离域中的服务。 [源码](../../vendor/cordis/src/fiber.ts#L198) @@ -143,7 +154,7 @@ get name() 插件的显示名称，继承自最近的具名祖先；如果不存在，则为 `'root'`。 -[源码](../../vendor/cordis/src/fiber.ts#L336) +[源码](../../vendor/cordis/src/fiber.ts#L342) ### fiber.assertActive() @@ -161,7 +172,7 @@ assertActive() **返回**：fiber 仍处于活动状态时不返回任何内容。 -[源码](../../vendor/cordis/src/fiber.ts#L351) +[源码](../../vendor/cordis/src/fiber.ts#L357) ### fiber.effect(execute, label?) @@ -192,7 +203,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable> **返回**一个用于撤销该作用的清理函数，并在清理完成后结算。 -[源码](../../vendor/cordis/src/fiber.ts#L415) +[源码](../../vendor/cordis/src/fiber.ts#L421) ### fiber.getEffects() @@ -209,7 +220,7 @@ getEffects() **返回**：每个带标签的活动作用对应一棵 `EffectMeta` 树。 -[源码](../../vendor/cordis/src/fiber.ts#L568) +[源码](../../vendor/cordis/src/fiber.ts#L574) ### fiber.rawConfig @@ -218,23 +229,25 @@ getEffects() get rawConfig(): unknown ``` + 保留供下次激活使用的原始输入，不执行表达式求值或验证。 -[源码](../../vendor/cordis/src/fiber.ts#L642) +[源码](../../vendor/cordis/src/fiber.ts#L649) ### fiber.effectiveConfig ```ts cordis-catalog /** - * The config object published by the existing activation/update lifecycle, without cloning or re-parsing. - * It is undefined before the first resolution and remains readable after unload; callers requiring a live instance check `state`. + * The object passed to plugin activation or the latest successful update that retained the instance. + * Candidate resolution does not publish it; volatile updates retain its references. + * Undefined before activation and readable after unload; callers requiring a live instance check `state`. */ get effectiveConfig(): unknown ``` -既有激活／更新生命周期发布的配置对象，不克隆或重新解析。首次解析前为 undefined，卸载后仍可读取；需要运行实例的调用方应检查 `state`。 +传给插件激活过程或最近一次成功保留实例的更新的对象。候选配置求值不发布结果；volatile 更新保留其中的引用。激活前为 undefined，卸载后仍可读取；需要运行中实例的调用方还应检查 `state`。 -[源码](../../vendor/cordis/src/fiber.ts#L655) +[源码](../../vendor/cordis/src/fiber.ts#L664) ### fiber.resolveConfig(config) @@ -250,13 +263,14 @@ get effectiveConfig(): unknown resolveConfig(config: unknown): unknown ``` + 通过此 fiber 的 `internal/config` 钩子和运行时 schema 对候选值求值并验证。此操作不发布结果、不替换原始输入，也不提交运行中的 volatile 引用。钩子访问的注入服务必须已经可用。 - `config`：原始候选输入。 **返回**候选配置的解析结果，保留 schema 返回对象的身份。 -[源码](../../vendor/cordis/src/fiber.ts#L667) +[源码](../../vendor/cordis/src/fiber.ts#L676) ### fiber.await() @@ -274,7 +288,7 @@ async await() **返回**：进入稳定状态后的此 fiber。 -[源码](../../vendor/cordis/src/fiber.ts#L731) +[源码](../../vendor/cordis/src/fiber.ts#L754) ### fiber.restart() @@ -292,35 +306,29 @@ dispose 此插件，并立即使用其当前配置重新加载。 **返回**一个在重新加载完成后兑现的 promise。 -[源码](../../vendor/cordis/src/fiber.ts#L745) +[源码](../../vendor/cordis/src/fiber.ts#L768) ### fiber.update(config, noSave?) ```ts cordis-catalog /** - * Validate and apply new config, then restart the plugin. - * - * Runs the `internal/update` waterfall first, so update hooks (and HMR) - * can veto or replace the restart. - * - * @param config — the new raw config; validated before anything restarts. - * @param noSave — hint for persistence hooks not to write the change back. - * @returns nothing; the restart runs behind the `internal/update` waterfall. - * @throws {ValidationError} when the new config fails validation. + * Resolve a candidate, retain its raw config and apply it through the update waterfall. + * @param config Raw config; pending fibers defer resolution until activation. + * @param noSave Suppress the persistence notification when true. + * @returns The awaited update/restart result, or undefined when a synchronous listener handles it. + * @throws {ValidationError} when an active fiber's candidate is invalid. */ -update(config: any, noSave = false) +update(config: any, noSave = false): Awaitable ``` -校验并应用新配置，然后重新启动插件。 +求值候选配置，保留原始输入，并通过更新 waterfall 应用结果。 -首先运行 `internal/update` waterfall（瀑布式事件），因此更新钩子（以及 HMR（热模块替换））可以否决或取代重新启动操作。 +- `config` — 原始配置；pending fiber 将求值推迟到激活时。 +- `noSave` — 为 true 时不发出持久化通知。 -- `config`：新的原始配置；在任何内容重新启动前进行校验。 -- `noSave`：提示持久化钩子不要写回此变更。 +**返回** 可等待的更新或重启结果；同步监听器处理更新时为 undefined。 -**返回**无返回值；重启由 `internal/update` waterfall 执行。 - -[源码](../../vendor/cordis/src/fiber.ts#L764) +[源码](../../vendor/cordis/src/fiber.ts#L783) ## Effect diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md index cc62683cb5..c414eaedd5 100644 --- a/docs/cordis-api/inherited.md +++ b/docs/cordis-api/inherited.md @@ -21,15 +21,16 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie ## Inherited events (cordis core + loader/hmr/timer) -- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:331`](../../vendor/cordis/src/events.ts)) -- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:333`](../../vendor/cordis/src/events.ts)) -- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:341`](../../vendor/cordis/src/events.ts)) -- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:343`](../../vendor/cordis/src/events.ts)) -- `internal/config` — Waterfall: a fiber config is being resolved before validation. ([`vendor/cordis/src/events.ts:339`](../../vendor/cordis/src/events.ts)) -- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:345`](../../vendor/cordis/src/events.ts)) -- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:347`](../../vendor/cordis/src/events.ts)) -- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:349`](../../vendor/cordis/src/events.ts)) -- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:351`](../../vendor/cordis/src/events.ts)) +- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:337`](../../vendor/cordis/src/events.ts)) +- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:339`](../../vendor/cordis/src/events.ts)) +- `internal/service` — A service binding was refreshed in the matching isolation scope. ([`vendor/cordis/src/events.ts:341`](../../vendor/cordis/src/events.ts)) +- `internal/update` — Waterfall: apply resolved config; omitting next() keeps the current instance. ([`vendor/cordis/src/events.ts:348`](../../vendor/cordis/src/events.ts)) +- `internal/commit` — Persist raw config from a programmatic update unless noSave is set. ([`vendor/cordis/src/events.ts:355`](../../vendor/cordis/src/events.ts)) +- `internal/config` — Waterfall: resolve a candidate after injections are active without publishing it. ([`vendor/cordis/src/events.ts:362`](../../vendor/cordis/src/events.ts)) +- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:364`](../../vendor/cordis/src/events.ts)) +- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:366`](../../vendor/cordis/src/events.ts)) +- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:368`](../../vendor/cordis/src/events.ts)) +- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:370`](../../vendor/cordis/src/events.ts)) - `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts)) - `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts)) - `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts)) diff --git a/docs/deepseek-llm-api-wire-extensions.i18n.yaml b/docs/deepseek-llm-api-wire-extensions.i18n.yaml index 79b48d6dc5..c5248fa3f7 100644 --- a/docs/deepseek-llm-api-wire-extensions.i18n.yaml +++ b/docs/deepseek-llm-api-wire-extensions.i18n.yaml @@ -9,8 +9,8 @@ en: 1da81051addc4b47 zh: 3e8d7cd3f8c1cdba /official-deepseek-llm-api-wire-extensions/request-headers: - en: 740e92e903ecb594 - zh: f934d3c9e5c56bfe + en: d3d6a2c8240b80e9 + zh: debf42ed01233728 /official-deepseek-llm-api-wire-extensions/body-extension-transaction: en: 48001cfd1281a23b zh: d410530ae8aa2823 @@ -18,8 +18,8 @@ en: f89059050613f3e8 zh: da5cf2a4eeb81b75 /official-deepseek-llm-api-wire-extensions/dsh-session-log: - en: de1a3f2c377d74e3 - zh: 7c803345f71117c5 + en: 0d033f72951e2920 + zh: 767efca0dc39ac03 /official-deepseek-llm-api-wire-extensions/dsh-session-log/wire-session-header: en: ccd8fcd773df21c4 zh: 7ea020068ad093ae diff --git a/docs/deepseek-llm-api-wire-extensions.md b/docs/deepseek-llm-api-wire-extensions.md index 1a30f7c463..e9a270d98e 100644 --- a/docs/deepseek-llm-api-wire-extensions.md +++ b/docs/deepseek-llm-api-wire-extensions.md @@ -28,7 +28,7 @@ The [`DeepSeekLlmApiExtensionRegistry`](../packages/llm/deepseek-llm-api-extensi | `x-deepseek-harness-session-id` | Model requests carrying a Session id | The exact request `sessionId` string | | `x-deepseek-harness-compact` | Model requests whose purpose is `compaction` | The literal string `1` | -Credential failure happens before anonymous-user-id resolution, so an unauthorized request neither sends these headers nor creates the identity file. A direct request without a Session omits `x-deepseek-harness-session-id`. Session-title requests have no additional purpose header; the ordinary Session-id rule still applies when one carries a `sessionId`. +Credential failure happens before anonymous-user-id resolution, so an unauthorized request neither sends these headers nor creates the identity file. A direct request without a Session omits `x-deepseek-harness-session-id`. Session-title and Auto review requests have no additional purpose header; the ordinary Session-id rule still applies when one carries a `sessionId`. ## Body-extension transaction @@ -73,7 +73,7 @@ An enabled inventory with no qualifying entries sends `packages: []`; disabling ## `dsh_session_log` -[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.md) contributes one contiguous suffix of the canonical Session log. The field is enabled by default. It applies to a request with a live Session and at least one event; a direct request, a stale Session id, or an empty log omits the field, as does a request whose first pending event alone exceeds `maxBytes` or cannot be serialized; a composition disables it with `enabled: false`. The examples below use logical Session format 2 only to illustrate the wire fields; they do not identify the [current writer format](session-format-status.md). +[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.md) contributes one contiguous suffix of the canonical Session log. The field is enabled by default. It applies to a request with a live Session and at least one event; a direct request, a stale Session id, an empty log, or a request matched by a registered upload exclusion omits the field, as does a request whose first pending event alone exceeds `maxBytes` or cannot be serialized; a composition disables it with `enabled: false`. The examples below use logical Session format 2 only to illustrate the wire fields; they do not identify the [current writer format](session-format-status.md). ```json { diff --git a/docs/deepseek-llm-api-wire-extensions.zh.md b/docs/deepseek-llm-api-wire-extensions.zh.md index dcccecc6a7..d498e8f951 100644 --- a/docs/deepseek-llm-api-wire-extensions.zh.md +++ b/docs/deepseek-llm-api-wire-extensions.zh.md @@ -28,7 +28,7 @@ | `x-deepseek-harness-session-id` | 携带会话 id 的模型请求 | 确切的请求 `sessionId` 字符串 | | `x-deepseek-harness-compact` | 用途为 `compaction` 的模型请求 | 字面字符串 `1` | -凭据失败发生在解析匿名用户 id 之前，因此未授权请求既不会发送这些标头，也不会创建身份文件。没有会话的直接请求会省略 `x-deepseek-harness-session-id`。会话标题请求没有额外的用途标头；请求携带 `sessionId` 时，仍然适用普通的会话 id 规则。 +凭据失败发生在解析匿名用户 id 之前，因此未授权请求既不会发送这些标头，也不会创建身份文件。没有会话的直接请求会省略 `x-deepseek-harness-session-id`。会话标题请求和 Auto 审查请求没有额外的用途标头；请求携带 `sessionId` 时，仍然适用普通的会话 id 规则。 ## 正文扩展事务 @@ -73,7 +73,7 @@ ## `dsh_session_log` -[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认启用。它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id 或空日志会省略该字段，第一条待发事件本身超过 `maxBytes` 或无法序列化的请求也会省略该字段；组合可用 `enabled: false` 禁用它。下方示例使用逻辑 Session 格式 2 仅为说明协议字段，并不标识[当前写入格式](session-format-status.zh.md)。 +[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认启用。它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id、空日志或命中已注册上传排除条件的请求会省略该字段，第一条待发事件本身超过 `maxBytes` 或无法序列化的请求也会省略该字段；组合可用 `enabled: false` 禁用它。下方示例使用逻辑 Session 格式 2 仅为说明协议字段，并不标识[当前写入格式](session-format-status.zh.md)。 ```json { diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml index f0498f2df1..6e50a46793 100644 --- a/docs/development.i18n.yaml +++ b/docs/development.i18n.yaml @@ -21,8 +21,8 @@ en: 3221d1076554001f zh: 29f166be6a5c04d9 /development-guide/contributor-reference/typescript-project-layout: - en: 7486eed38e4086b9 - zh: 0b6152dc4f38b53a + en: 16d67911ecaa50d3 + zh: f5259b0fbf022db3 /development-guide/contributor-reference/environment-variables: en: dba2c72ee6ffa930 zh: b65c27fbb9129ec8 diff --git a/docs/development.md b/docs/development.md index 9513bf4ecb..5f0eccff14 100644 --- a/docs/development.md +++ b/docs/development.md @@ -66,6 +66,8 @@ The repository uses isolated Host and Client aggregates. An ordinary package is | `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No | | `tsconfig.base.client.json` | Browser compiler settings (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No | +Host and Client aggregate type checks run with an 8 GiB Node old-space limit. This is a per-compiler limit; concurrent build steps need additional memory. `pnpm run build:official --serial` prevents build steps from overlapping, even with `DSH_GATE_CONCURRENCY` set; the DSH publication workflow uses this option. + Host and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow: - `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope. diff --git a/docs/development.zh.md b/docs/development.zh.md index 5ad35bc525..aa1c75effe 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -70,6 +70,8 @@ pnpm run typecheck | `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 | | `tsconfig.base.client.json` | 浏览器编译设置（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 | +Host 和 Client aggregate 类型检查为 Node 老生代堆设置 8 GiB 上限。这是单个编译进程的上限；并发构建步骤还需要额外内存。`pnpm run build:official --serial` 阻止构建步骤重叠，即使设置了 `DSH_GATE_CONCURRENCY` 也不例外；DSH 发布 workflow 使用此选项。 + Host 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律： - `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。 diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index f419955c56..9defd245a7 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.i18n.yaml @@ -6,8 +6,8 @@ en: 41d772192075e133 zh: dda91c6c670cfd9d /event-producer-and-consumer-matrix: - en: 19f30fda81e73345 - zh: a8505006244f5619 + en: 2fac23d1dcc1fd3d + zh: 5fb06020a810adbf /event-producer-and-consumer-matrix/non-harness-or-undeclared-event-strings-seen-in-package-source: en: 96dc0ff1580e5741 zh: 96dc0ff1580e5741 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index f340e97ddf..ab9f81afc1 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -5,29 +5,31 @@ This matrix shows which packages dispatch each harness-owned event and which packages listen to it. Events are many-to-many, so the dense relation data is presented as a table rather than one large graph. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment. +Application listeners are outside this package matrix. Desktop Host subscribes to `plugin-manager/operation` through [`installOperationDiagnostics`](../apps/desktop-host/src/operation-diagnostics.ts) and forwards bounded records to the shell. + | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:198`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - | | `agent-preset/selected` | `emit` | [`packages/preset/agent-preset-registry/src/types.ts:66`](../packages/preset/agent-preset-registry/src/types.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`) | [`cua`](../packages/experimental/cua), `remotes` | | `agent/assistant-stream` | `emit` | [`packages/core/agent/src/runtime-types.ts:407`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`headless`](../packages/bundle/headless), `session-controller` | -| `agent/created` | `serial` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`serial`) | `browser-use-runtime`, `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`cua`](../packages/experimental/cua), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`loader-smoke`](../packages/test-support/loader-smoke), [`permission-presets`](../packages/interaction/permission-presets), `session-controller`, `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | +| `agent/created` | `serial` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`serial`) | `browser-use-runtime`, `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`cua`](../packages/experimental/cua), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`loader-smoke`](../packages/test-support/loader-smoke), [`permission-presets`](../packages/interaction/permission-presets), `session-controller`, `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `server`, `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:437`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`deepseek-account`](../packages/credentials/deepseek-account), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), `server`, `session-controller`, [`session-telemetry`](../packages/session/session-telemetry), [`subagent`](../packages/subagent/subagent) | | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:336`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`user-questions`](../packages/interaction/user-questions) | | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:344`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | -| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:325`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | -| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:358`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`action-cards`](../packages/experimental/action-cards), [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `session-controller`, [`session-reference`](../packages/context/session-reference), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill) | +| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:325`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | `client-ui-forge`, [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | +| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:358`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`action-cards`](../packages/experimental/action-cards), [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, `client-ui-forge`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `session-controller`, [`session-reference`](../packages/context/session-reference), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill) | | `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:397`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm-retry`](../packages/llm/llm-retry) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:309`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:425`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `agent/wait-notified` | `emit` | [`packages/core/agent/src/runtime-types.ts:317`](../packages/core/agent/src/runtime-types.ts) | `agent-team` (`emitAgentEvent`) | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:600`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:580`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:607`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:53`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:691`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:671`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:698`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:677`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:684`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:55`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:87`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes`, `server` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | - | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | @@ -46,27 +48,31 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `deepseek-account/signed-out` | `emit` | [`packages/credentials/deepseek-account/src/index.ts:12`](../packages/credentials/deepseek-account/src/index.ts) | [`deepseek-account-platform`](../packages/credentials/deepseek-account-platform) (`emit`) | [`deepseek-account`](../packages/credentials/deepseek-account) | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `workspace-controller` | | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:58`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | -| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | -| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` | +| `forge/providers-changed` | `parallel` | [`packages/experimental/forge/src/index.ts:27`](../packages/experimental/forge/src/index.ts) | `forge` (`parallel`) | `forge-session` | +| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | `liveshare` (`emit`), [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | +| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes`, `server` | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `hmr/change` | `emit` | [`packages/boot/hmr/src/index.ts:35`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | | `hmr/reload` | `emit` | [`packages/boot/hmr/src/index.ts:40`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | -| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), `remotes` | +| `llm-pi-ai/request-headers` | `waterfall` | [`packages/llm/llm-pi-ai/src/index.ts:114`](../packages/llm/llm-pi-ai/src/index.ts) | [`llm-pi-ai`](../packages/llm/llm-pi-ai) (`waterfall`) | - | +| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:24`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), `remotes` | +| `llm/models-updated` | `emit` | [`packages/llm/llm/src/types.ts:30`](../packages/llm/llm/src/types.ts) | [`llm-deepseek`](../packages/llm/llm-deepseek) (`emit`) | `remotes` | | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:75`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) | | `permission-presets/catalog-changed` | `emit` | [`packages/interaction/permission-presets/src/types.ts:48`](../packages/interaction/permission-presets/src/types.ts) | [`permission-presets`](../packages/interaction/permission-presets) (`events.dispatch`) | `remotes` | -| `plugin-manager/changed` | `emit` | [`packages/boot/plugin-manager/src/types.ts:394`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | -| `plugin-manager/install-log` | `emit` | [`packages/boot/plugin-manager/src/types.ts:400`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | -| `plugin-manager/install-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:407`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | -| `plugin-manager/update-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:414`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/changed` | `emit` | [`packages/boot/plugin-manager/src/types.ts:432`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/install-log` | `emit` | [`packages/boot/plugin-manager/src/types.ts:438`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/install-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:445`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/operation` | `parallel` | [`packages/boot/plugin-manager/src/types.ts:424`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`parallel`) | - | +| `plugin-manager/update-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:452`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | | `plugin-market/changed` | `emit` | [`packages/boot/plugin-market/src/types.ts:168`](../packages/boot/plugin-market/src/types.ts) | [`plugin-market`](../packages/boot/plugin-market) (`emit`) | `remotes` | | `schedule/changed` | `emit` | [`packages/schedule/schedule/src/types.ts:484`](../packages/schedule/schedule/src/types.ts) | [`schedule`](../packages/schedule/schedule) (`emit`) | `remotes` | | `schedule/resolve-agent` | `waterfall` | [`packages/schedule/schedule/src/index.ts:74`](../packages/schedule/schedule/src/index.ts) | [`schedule`](../packages/schedule/schedule) (`waterfall`) | `server` | | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:44`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - | | `session/created` | `emit` | [`packages/core/session/src/index.ts:56`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`schedule`](../packages/schedule/schedule), `server`, `session-controller`, [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry) | -| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:65`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `file-upload`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `session/event` | `emit` | [`packages/core/session/src/index.ts:76`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`tool-jobs`](../packages/jobs/tool-jobs), [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:65`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `file-upload`, `forge-session`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), `ui-trajectory`, [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `session/event` | `emit` | [`packages/core/session/src/index.ts:76`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `claude-code-mods`, `client-ui-forge`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, `forge-session`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`tool-jobs`](../packages/jobs/tool-jobs), `ui-trajectory`, [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-telemetry`](../packages/session/session-telemetry) | | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:75`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`emit`) | `remotes` | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:296`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - | @@ -76,12 +82,12 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/experimental/hooks-claude-code) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | `browser-use-runtime`, [`working-directory`](../packages/session/working-directory) | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/events.ts:56`](../packages/core/tools/src/events.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime`, [`tool-subagent`](../packages/subagent/tool-subagent) | +| `tools/change` | `emit` | [`packages/core/tools/src/events.ts:56`](../packages/core/tools/src/events.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime` | | `tools/execute` | `waterfall` | [`packages/core/tools/src/events.ts:29`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `browser-use-runtime`, `browser-use-stagehand-native`, `claude-code-mods`, `computer-use-cua-driver-native`, [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/events.ts:41`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `claude-code-mods`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) | -| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/events.ts:18`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/events.ts:18`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tool-executor-ptc/src/runtime-types.ts:46`](../packages/core/tool-executor-ptc/src/runtime-types.ts) | [`tool-executor-ptc`](../packages/core/tool-executor-ptc) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) | -| `tools/result` | `emit` | [`packages/core/tools/src/events.ts:49`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present) | +| `tools/result` | `emit` | [`packages/core/tools/src/events.ts:49`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, `forge-session`, `liveshare`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present), `ui-trajectory` | | `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:174`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes`, `server` | | `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:44`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `connection`, `inspector`, `modules`, `remote-access`, `shortcuts`, `ui-sidebar-documentpreview`, `ui-theme` | | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | @@ -100,14 +106,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac | Event string | Dispatchers | Listeners | | --- | --- | --- | | `agent/request` | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic) | +| `connection/reset` | `gateway` (`emit`) | `terminal-controller`, `ui-settings` | | `internal/config` | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | | `internal/dispatch` | - | [`terminal-bash`](../packages/terminal/terminal-bash) | | `internal/plugin` | - | `computer-use-cua-driver-native`, `inspector`, `loader`, [`lsp-stdio`](../packages/lsp/lsp-stdio), [`mcp-client`](../packages/mcp/mcp-client), `modules` | -| `internal/service` | - | `gateway` | -| `internal/status` | - | [`agent`](../packages/core/agent), `inspector`, `translator`, [`web`](../packages/web/web) | -| `internal/update` | - | [`app-boot`](../packages/boot/app-boot) | -| `loader/volatile-update` | - | [`cua`](../packages/experimental/cua), [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`plugin-market`](../packages/boot/plugin-market), `product-analytics`, `speech-to-text` | +| `internal/service` | - | `client-ui-forge`, `gateway` | +| `internal/status` | - | [`agent`](../packages/core/agent), `claude-code-mods`, `inspector`, `translator`, [`web`](../packages/web/web) | +| `loader/volatile-update` | - | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`plugin-market`](../packages/boot/plugin-market), `product-analytics`, `speech-to-text` | +| `locale/change` | `locale` (`emit`) | `locale` | | `slots/changed` | `ui-renderer` (`emit`) | - | +| `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` | Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program. diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index dd177d0c3f..ad95cb1d46 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -7,29 +7,31 @@ 本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。事件之间存在多对多关系，因此密集的关系数据以表格而非一张大型关系图呈现。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。 +应用级监听者不在本包矩阵范围内。Desktop Host 通过 [`installOperationDiagnostics`](../apps/desktop-host/src/operation-diagnostics.ts) 订阅 `plugin-manager/operation`，并向壳转发有界记录。 + | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:198`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - | | `agent-preset/selected` | `emit` | [`packages/preset/agent-preset-registry/src/types.ts:66`](../packages/preset/agent-preset-registry/src/types.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`) | [`cua`](../packages/experimental/cua), `remotes` | | `agent/assistant-stream` | `emit` | [`packages/core/agent/src/runtime-types.ts:407`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`headless`](../packages/bundle/headless), `session-controller` | -| `agent/created` | `serial` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`serial`) | `browser-use-runtime`, `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`cua`](../packages/experimental/cua), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`loader-smoke`](../packages/test-support/loader-smoke), [`permission-presets`](../packages/interaction/permission-presets), `session-controller`, `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | +| `agent/created` | `serial` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`serial`) | `browser-use-runtime`, `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`cua`](../packages/experimental/cua), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`loader-smoke`](../packages/test-support/loader-smoke), [`permission-presets`](../packages/interaction/permission-presets), `session-controller`, `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:299`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-loop`](../packages/core/agent-loop), `claude-code-mods`, [`creation-recommendations`](../packages/experimental/creation-recommendations), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), `server`, `session-controller`, [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:437`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`deepseek-account`](../packages/credentials/deepseek-account), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), `server`, `session-controller`, [`session-telemetry`](../packages/session/session-telemetry), [`subagent`](../packages/subagent/subagent) | | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:336`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`user-questions`](../packages/interaction/user-questions) | | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:344`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | -| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:325`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | -| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:358`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`action-cards`](../packages/experimental/action-cards), [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `session-controller`, [`session-reference`](../packages/context/session-reference), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill) | +| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:325`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | `client-ui-forge`, [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | +| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:358`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`action-cards`](../packages/experimental/action-cards), [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, `client-ui-forge`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `session-controller`, [`session-reference`](../packages/context/session-reference), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill) | | `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:397`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm-retry`](../packages/llm/llm-retry) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:309`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:425`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `agent/wait-notified` | `emit` | [`packages/core/agent/src/runtime-types.ts:317`](../packages/core/agent/src/runtime-types.ts) | `agent-team` (`emitAgentEvent`) | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:600`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:580`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:607`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:53`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:691`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:671`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:698`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:677`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:684`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:55`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:87`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes`, `server` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | - | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | @@ -48,27 +50,31 @@ | `deepseek-account/signed-out` | `emit` | [`packages/credentials/deepseek-account/src/index.ts:12`](../packages/credentials/deepseek-account/src/index.ts) | [`deepseek-account-platform`](../packages/credentials/deepseek-account-platform) (`emit`) | [`deepseek-account`](../packages/credentials/deepseek-account) | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `workspace-controller` | | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:58`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | -| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | -| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` | +| `forge/providers-changed` | `parallel` | [`packages/experimental/forge/src/index.ts:27`](../packages/experimental/forge/src/index.ts) | `forge` (`parallel`) | `forge-session` | +| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | `liveshare` (`emit`), [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | +| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:147`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes`, `server` | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `hmr/change` | `emit` | [`packages/boot/hmr/src/index.ts:35`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | | `hmr/reload` | `emit` | [`packages/boot/hmr/src/index.ts:40`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | -| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), `remotes` | +| `llm-pi-ai/request-headers` | `waterfall` | [`packages/llm/llm-pi-ai/src/index.ts:114`](../packages/llm/llm-pi-ai/src/index.ts) | [`llm-pi-ai`](../packages/llm/llm-pi-ai) (`waterfall`) | - | +| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:24`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), `remotes` | +| `llm/models-updated` | `emit` | [`packages/llm/llm/src/types.ts:30`](../packages/llm/llm/src/types.ts) | [`llm-deepseek`](../packages/llm/llm-deepseek) (`emit`) | `remotes` | | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:75`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) | | `permission-presets/catalog-changed` | `emit` | [`packages/interaction/permission-presets/src/types.ts:48`](../packages/interaction/permission-presets/src/types.ts) | [`permission-presets`](../packages/interaction/permission-presets) (`events.dispatch`) | `remotes` | -| `plugin-manager/changed` | `emit` | [`packages/boot/plugin-manager/src/types.ts:394`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | -| `plugin-manager/install-log` | `emit` | [`packages/boot/plugin-manager/src/types.ts:400`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | -| `plugin-manager/install-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:407`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | -| `plugin-manager/update-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:414`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/changed` | `emit` | [`packages/boot/plugin-manager/src/types.ts:432`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/install-log` | `emit` | [`packages/boot/plugin-manager/src/types.ts:438`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/install-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:445`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | +| `plugin-manager/operation` | `parallel` | [`packages/boot/plugin-manager/src/types.ts:424`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`parallel`) | - | +| `plugin-manager/update-state` | `emit` | [`packages/boot/plugin-manager/src/types.ts:452`](../packages/boot/plugin-manager/src/types.ts) | [`plugin-manager`](../packages/boot/plugin-manager) (`emit`) | `remotes` | | `plugin-market/changed` | `emit` | [`packages/boot/plugin-market/src/types.ts:168`](../packages/boot/plugin-market/src/types.ts) | [`plugin-market`](../packages/boot/plugin-market) (`emit`) | `remotes` | | `schedule/changed` | `emit` | [`packages/schedule/schedule/src/types.ts:484`](../packages/schedule/schedule/src/types.ts) | [`schedule`](../packages/schedule/schedule) (`emit`) | `remotes` | | `schedule/resolve-agent` | `waterfall` | [`packages/schedule/schedule/src/index.ts:74`](../packages/schedule/schedule/src/index.ts) | [`schedule`](../packages/schedule/schedule) (`waterfall`) | `server` | | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:44`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - | | `session/created` | `emit` | [`packages/core/session/src/index.ts:56`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`schedule`](../packages/schedule/schedule), `server`, `session-controller`, [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry) | -| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:65`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `file-upload`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`workspace-changes`](../packages/deliverables/workspace-changes) | -| `session/event` | `emit` | [`packages/core/session/src/index.ts:76`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`tool-jobs`](../packages/jobs/tool-jobs), [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:65`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `file-upload`, `forge-session`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), `ui-trajectory`, [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `session/event` | `emit` | [`packages/core/session/src/index.ts:76`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `claude-code-mods`, `client-ui-forge`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, `forge-session`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`tool-jobs`](../packages/jobs/tool-jobs), `ui-trajectory`, [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-telemetry`](../packages/session/session-telemetry) | | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:75`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`emit`) | `remotes` | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:296`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - | @@ -78,12 +84,12 @@ | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/experimental/hooks-claude-code) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | `browser-use-runtime`, [`working-directory`](../packages/session/working-directory) | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/events.ts:56`](../packages/core/tools/src/events.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime`, [`tool-subagent`](../packages/subagent/tool-subagent) | +| `tools/change` | `emit` | [`packages/core/tools/src/events.ts:56`](../packages/core/tools/src/events.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime` | | `tools/execute` | `waterfall` | [`packages/core/tools/src/events.ts:29`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `browser-use-runtime`, `browser-use-stagehand-native`, `claude-code-mods`, `computer-use-cua-driver-native`, [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/events.ts:41`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `claude-code-mods`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) | -| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/events.ts:18`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) | +| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/events.ts:18`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), `liveshare`, [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tool-executor-ptc/src/runtime-types.ts:46`](../packages/core/tool-executor-ptc/src/runtime-types.ts) | [`tool-executor-ptc`](../packages/core/tool-executor-ptc) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) | -| `tools/result` | `emit` | [`packages/core/tools/src/events.ts:49`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present) | +| `tools/result` | `emit` | [`packages/core/tools/src/events.ts:49`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`action-cards`](../packages/experimental/action-cards), [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, `forge-session`, `liveshare`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present), `ui-trajectory` | | `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:174`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes`, `server` | | `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:44`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `connection`, `inspector`, `modules`, `remote-access`, `shortcuts`, `ui-sidebar-documentpreview`, `ui-theme` | | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | @@ -102,14 +108,16 @@ | Event string | Dispatchers | Listeners | | --- | --- | --- | | `agent/request` | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic) | +| `connection/reset` | `gateway` (`emit`) | `terminal-controller`, `ui-settings` | | `internal/config` | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | | `internal/dispatch` | - | [`terminal-bash`](../packages/terminal/terminal-bash) | | `internal/plugin` | - | `computer-use-cua-driver-native`, `inspector`, `loader`, [`lsp-stdio`](../packages/lsp/lsp-stdio), [`mcp-client`](../packages/mcp/mcp-client), `modules` | -| `internal/service` | - | `gateway` | -| `internal/status` | - | [`agent`](../packages/core/agent), `inspector`, `translator`, [`web`](../packages/web/web) | -| `internal/update` | - | [`app-boot`](../packages/boot/app-boot) | -| `loader/volatile-update` | - | [`cua`](../packages/experimental/cua), [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`plugin-market`](../packages/boot/plugin-market), `product-analytics`, `speech-to-text` | +| `internal/service` | - | `client-ui-forge`, `gateway` | +| `internal/status` | - | [`agent`](../packages/core/agent), `claude-code-mods`, `inspector`, `translator`, [`web`](../packages/web/web) | +| `loader/volatile-update` | - | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`plugin-market`](../packages/boot/plugin-market), `product-analytics`, `speech-to-text` | +| `locale/change` | `locale` (`emit`) | `locale` | | `slots/changed` | `ui-renderer` (`emit`) | - | +| `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` | Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program. diff --git a/docs/experimental-persistence-catalog.i18n.yaml b/docs/experimental-persistence-catalog.i18n.yaml index 7dd24c2aa4..4a5c0e237a 100644 --- a/docs/experimental-persistence-catalog.i18n.yaml +++ b/docs/experimental-persistence-catalog.i18n.yaml @@ -6,5 +6,5 @@ en: a11f106978c9dce7 zh: a11f106978c9dce7 /experimental-plugin-record-catalog: - en: cb931db3b4bcbe33 - zh: aca9cfecfdee34c0 + en: 2e4c95aeb435f35e + zh: 669270a7e95ad6f2 diff --git a/docs/experimental-persistence-catalog.md b/docs/experimental-persistence-catalog.md index b6d3a73de4..902cf83798 100644 --- a/docs/experimental-persistence-catalog.md +++ b/docs/experimental-persistence-catalog.md @@ -14,5 +14,7 @@ Shared Session event declarations and resolved schemas appear in the [Session pe | Record | Owner | Purpose | Payload and source | |---|---|---|---| | `plugin:action-cards/decision` | `@deepseek-ai/dsh-action-cards` | Dismissals and kind-defined progress of action cards. | ActionCardDecision · [`packages/experimental/action-cards/src/types.ts`](../packages/experimental/action-cards/src/types.ts) | +| `plugin:client-ui-forge/worktree` | `@deepseek-ai/dsh-experimental-client-ui-forge` | A request, withdrawal, or creation of the worktree a Session starts in. | WorktreeRecord · [`packages/experimental/client-ui-forge/src/types.ts`](../packages/experimental/client-ui-forge/src/types.ts) | +| `plugin:forge-session/binding` | `@deepseek-ai/dsh-experimental-forge-session` | A caller or discovery action that binds, restores, or hides one change request. | BindingRecord · [`packages/experimental/forge-session/src/types.ts`](../packages/experimental/forge-session/src/types.ts) | | `plugin:translator/request` | `@deepseek-ai/dsh-experimental-translator` | Provider-independent translation input, retained before dispatch. | TranslationRequestRecord · [`packages/experimental/translator/src/types.ts`](../packages/experimental/translator/src/types.ts) | | `plugin:translator/result` | `@deepseek-ai/dsh-experimental-translator` | Successful translation, retained before it is returned to the consumer. | TranslationResultRecord · [`packages/experimental/translator/src/types.ts`](../packages/experimental/translator/src/types.ts) | diff --git a/docs/experimental-persistence-catalog.zh.md b/docs/experimental-persistence-catalog.zh.md index c32cdcabd0..d36c9541ca 100644 --- a/docs/experimental-persistence-catalog.zh.md +++ b/docs/experimental-persistence-catalog.zh.md @@ -14,5 +14,7 @@ | 记录 | 所属包 | 用途 | 载荷与源码 | |---|---|---|---| | `plugin:action-cards/decision` | `@deepseek-ai/dsh-action-cards` | Dismissals and kind-defined progress of action cards. | ActionCardDecision · [`packages/experimental/action-cards/src/types.ts`](../packages/experimental/action-cards/src/types.ts) | +| `plugin:client-ui-forge/worktree` | `@deepseek-ai/dsh-experimental-client-ui-forge` | A request, withdrawal, or creation of the worktree a Session starts in. | WorktreeRecord · [`packages/experimental/client-ui-forge/src/types.ts`](../packages/experimental/client-ui-forge/src/types.ts) | +| `plugin:forge-session/binding` | `@deepseek-ai/dsh-experimental-forge-session` | A caller or discovery action that binds, restores, or hides one change request. | BindingRecord · [`packages/experimental/forge-session/src/types.ts`](../packages/experimental/forge-session/src/types.ts) | | `plugin:translator/request` | `@deepseek-ai/dsh-experimental-translator` | Provider-independent translation input, retained before dispatch. | TranslationRequestRecord · [`packages/experimental/translator/src/types.ts`](../packages/experimental/translator/src/types.ts) | | `plugin:translator/result` | `@deepseek-ai/dsh-experimental-translator` | Successful translation, retained before it is returned to the consumer. | TranslationResultRecord · [`packages/experimental/translator/src/types.ts`](../packages/experimental/translator/src/types.ts) | diff --git a/docs/module-graph.md b/docs/module-graph.md index b16e224a4a..5c57b56ac7 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -166,13 +166,14 @@ flowchart TD pkg_client_ui_brand_official["client-ui-brand-official"] pkg_client_ui_chat["client-ui-chat"] pkg_client_ui_commands["client-ui-commands"] + pkg_client_ui_context_menu["client-ui-context-menu"] pkg_client_ui_conversation["client-ui-conversation"] - pkg_client_ui_deepseek_model_label_1017["client-ui-deepseek-model-label-1017"] pkg_client_ui_deliverables["client-ui-deliverables"] pkg_client_ui_directory_picker_browse["client-ui-directory-picker-browse"] pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_dockkit["client-ui-dockkit"] pkg_client_ui_entry_customization["client-ui-entry-customization"] + pkg_client_ui_file_actions["client-ui-file-actions"] pkg_client_ui_file_drag["client-ui-file-drag"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] @@ -275,13 +276,20 @@ flowchart TD pkg_experimental_client_ui_agent_team["experimental-client-ui-agent-team"] pkg_experimental_client_ui_claude_code_mods["experimental-client-ui-claude-code-mods"] pkg_experimental_client_ui_cot_translation["experimental-client-ui-cot-translation"] + pkg_experimental_client_ui_forge["experimental-client-ui-forge"] + pkg_experimental_client_ui_stats["experimental-client-ui-stats"] pkg_experimental_client_ui_voice_input["experimental-client-ui-voice-input"] pkg_experimental_computer_use_cua_driver_mcp["experimental-computer-use-cua-driver-mcp"] pkg_experimental_computer_use_cua_driver_native["experimental-computer-use-cua-driver-native"] pkg_experimental_cot_translation_bundle["experimental-cot-translation-bundle"] pkg_experimental_cua_macos["experimental-cua-macos"] + pkg_experimental_forge["experimental-forge"] + pkg_experimental_forge_bundle["experimental-forge-bundle"] + pkg_experimental_forge_github["experimental-forge-github"] + pkg_experimental_forge_session["experimental-forge-session"] pkg_experimental_inspector["experimental-inspector"] pkg_experimental_inspector_profile["experimental-inspector-profile"] + pkg_experimental_liveshare["experimental-liveshare"] pkg_experimental_liveshare_protocol["experimental-liveshare-protocol"] pkg_experimental_plugin_market_bundle["experimental-plugin-market-bundle"] pkg_experimental_ptc_runtime_python["experimental-ptc-runtime-python"] @@ -494,6 +502,7 @@ flowchart TD pkg_credentials_local --> pkg_credentials pkg_credentials_local --> pkg_home_paths pkg_credentials_local --> pkg_launch_environment + pkg_experimental_liveshare --> pkg_scope pkg_anonymous_user_id --> pkg_brand pkg_anonymous_user_id --> pkg_home_paths pkg_lsp --> pkg_brand @@ -521,6 +530,8 @@ flowchart TD pkg_hmr --> pkg_cmdline pkg_deliverable_file_references --> pkg_system_prompt pkg_experimental_computer_use_cua_driver_mcp --> pkg_computer_use + pkg_experimental_forge_github --> pkg_experimental_forge + pkg_experimental_forge_github --> pkg_subprocess pkg_experimental_webworker_runtime --> pkg_client_connection pkg_experimental_webworker_runtime --> pkg_client_modules pkg_experimental_webworker_runtime --> pkg_host_webserver @@ -781,9 +792,6 @@ flowchart TD pkg_deepseek_account_platform --> pkg_credentials pkg_deepseek_account_platform --> pkg_deepseek_account pkg_deepseek_account_platform --> pkg_host_webserver - pkg_cua --> pkg_attachment - pkg_cua --> pkg_scope - pkg_cua --> pkg_user_questions pkg_experimental_ptc_runtime_python --> pkg_ptc_runtime pkg_experimental_ptc_runtime_python --> pkg_sandbox pkg_experimental_ptc_runtime_python --> pkg_sandbox_policy @@ -947,6 +955,10 @@ flowchart TD pkg_creation_recommendations --> pkg_session pkg_creation_recommendations --> pkg_skill pkg_creation_recommendations --> pkg_tools + pkg_cua --> pkg_attachment + pkg_cua --> pkg_ptc_runtime_node + pkg_cua --> pkg_scope + pkg_cua --> pkg_user_questions pkg_experimental_browser_use_chrome_devtools_mcp --> pkg_agent pkg_experimental_browser_use_chrome_devtools_mcp --> pkg_browser_use pkg_experimental_browser_use_chrome_devtools_mcp --> pkg_system_prompt @@ -961,6 +973,11 @@ flowchart TD pkg_experimental_browser_use_stagehand_native --> pkg_browser_use pkg_experimental_browser_use_stagehand_native --> pkg_system_prompt pkg_experimental_browser_use_stagehand_native --> pkg_tools + pkg_experimental_client_ui_forge --> pkg_experimental_forge + pkg_experimental_client_ui_forge --> pkg_experimental_worktree + pkg_experimental_client_ui_forge --> pkg_fs + pkg_experimental_client_ui_forge --> pkg_session + pkg_experimental_client_ui_forge --> pkg_timeout pkg_experimental_computer_use_cua_driver_native --> pkg_computer_use pkg_experimental_computer_use_cua_driver_native --> pkg_system_prompt pkg_experimental_computer_use_cua_driver_native --> pkg_tools @@ -1118,6 +1135,13 @@ flowchart TD pkg_experimental_auto_review --> pkg_session pkg_experimental_auto_review --> pkg_tools pkg_experimental_auto_review --> pkg_working_directory + pkg_experimental_forge_session --> pkg_experimental_forge + pkg_experimental_forge_session --> pkg_sandbox_policy + pkg_experimental_forge_session --> pkg_session + pkg_experimental_forge_session --> pkg_session_projection + pkg_experimental_forge_session --> pkg_shell + pkg_experimental_forge_session --> pkg_shell_env + pkg_experimental_forge_session --> pkg_tools pkg_webhook --> pkg_agent pkg_webhook --> pkg_agent_default_model pkg_webhook --> pkg_agent_preset_registry @@ -1300,7 +1324,6 @@ flowchart TD pkg_tool_subagent --> pkg_agent pkg_tool_subagent --> pkg_agent_preset_registry pkg_tool_subagent --> pkg_llm - pkg_tool_subagent --> pkg_scope pkg_tool_subagent --> pkg_session pkg_tool_subagent --> pkg_session_projection pkg_tool_subagent --> pkg_subagent @@ -1406,6 +1429,7 @@ flowchart TD pkg_tool_ralph --> pkg_system_prompt pkg_tool_ralph --> pkg_tools pkg_tool_ralph --> pkg_workflow + pkg_sdk_protocol --> pkg_commands pkg_sdk_protocol --> pkg_llm pkg_sdk_protocol --> pkg_session pkg_sdk_protocol --> pkg_subagent @@ -1452,6 +1476,7 @@ flowchart TD pkg_client_test_runtime --> pkg_client_modules pkg_client_test_runtime --> pkg_client_store pkg_client_test_runtime --> pkg_client_ui_chat + pkg_client_test_runtime --> pkg_client_ui_context_menu pkg_client_test_runtime --> pkg_client_ui_conversation pkg_client_test_runtime --> pkg_client_ui_renderer pkg_client_test_runtime --> pkg_client_ui_session @@ -1474,6 +1499,8 @@ flowchart TD pkg_tool_schedule --> pkg_tools pkg_sdk_jsonrpc_server --> pkg_agent pkg_sdk_jsonrpc_server --> pkg_attachment + pkg_sdk_jsonrpc_server --> pkg_commands + pkg_sdk_jsonrpc_server --> pkg_goal pkg_sdk_jsonrpc_server --> pkg_llm pkg_sdk_jsonrpc_server --> pkg_llm_deepseek_api_key pkg_sdk_jsonrpc_server --> pkg_schedule @@ -1536,13 +1563,14 @@ flowchart TD | [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | — | | [`client-ui-chat`](../packages/client/ui-chat) | `client` | — | | [`client-ui-commands`](../packages/client/ui-commands) | `client` | — | +| [`client-ui-context-menu`](../packages/client/ui-context-menu) | `client` | — | | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | — | -| [`client-ui-deepseek-model-label-1017`](../packages/client/ui-deepseek-model-label-1017) | `client` | — | | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — | | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — | | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | | [`client-ui-dockkit`](../packages/client/ui-dockkit) | `client` | — | | [`client-ui-entry-customization`](../packages/client/ui-entry-customization) | `client` | — | +| [`client-ui-file-actions`](../packages/client/ui-file-actions) | `client` | — | | [`client-ui-file-drag`](../packages/client/ui-file-drag) | `client` | — | | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | @@ -1599,8 +1627,11 @@ flowchart TD | [`experimental-badge-skill-bundle`](../packages/experimental/badge-skill-bundle) | `experimental` | — | | [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | — | | [`experimental-client-ui-claude-code-mods`](../packages/experimental/client-ui-claude-code-mods) | `experimental` | — | +| [`experimental-client-ui-stats`](../packages/experimental/client-ui-stats) | `experimental` | — | | [`experimental-client-ui-voice-input`](../packages/experimental/client-ui-voice-input) | `experimental` | — | | [`experimental-cot-translation-bundle`](../packages/experimental/cot-translation-bundle) | `experimental` | — | +| [`experimental-forge`](../packages/experimental/forge) | `experimental` | — | +| [`experimental-forge-bundle`](../packages/experimental/forge-bundle) | `experimental` | — | | [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | — | | [`experimental-inspector-profile`](../packages/experimental/inspector-profile) | `experimental` | — | | [`experimental-liveshare-protocol`](../packages/experimental/liveshare-protocol) | `experimental` | — | @@ -1645,6 +1676,7 @@ flowchart TD | [`computer-use`](../packages/computer-use/computer-use) | `computer-use` | [`brand`](../packages/util/brand) | | [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`llm`](../packages/llm/llm) | | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment) | +| [`experimental-liveshare`](../packages/experimental/liveshare) | `experimental` | [`scope`](../packages/core/scope) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths) | | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`storage`](../packages/storage/storage) | @@ -1663,6 +1695,7 @@ flowchart TD | [`hmr`](../packages/boot/hmr) | `boot` | [`app-boot`](../packages/boot/app-boot), [`cmdline`](../packages/boot/cmdline) | | [`deliverable-file-references`](../packages/deliverables/deliverable-file-references) | `deliverables` | [`system-prompt`](../packages/core/system-prompt) | | [`experimental-computer-use-cua-driver-mcp`](../packages/experimental/computer-use-cua-driver-mcp) | `experimental` | [`computer-use`](../packages/computer-use/computer-use) | +| [`experimental-forge-github`](../packages/experimental/forge-github) | `experimental` | [`experimental-forge`](../packages/experimental/forge), [`subprocess`](../packages/subprocess/subprocess) | | [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) | | [`plugin-recommendations`](../packages/experimental/plugin-recommendations) | `experimental` | [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`typert-protocol`](../packages/typert/protocol) | | [`skill-badge`](../packages/experimental/skill-badge) | `experimental` | [`skill`](../packages/skill/skill) | @@ -1738,7 +1771,6 @@ flowchart TD | [`api-account-controller`](../packages/api/account-controller) | `api` | [`agent`](../packages/core/agent), [`deepseek-account`](../packages/credentials/deepseek-account), [`typert-protocol`](../packages/typert/protocol) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`deepseek-account-platform`](../packages/credentials/deepseek-account-platform) | `credentials` | [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`deepseek-account`](../packages/credentials/deepseek-account), [`host-webserver`](../packages/host/webserver) | -| [`cua`](../packages/experimental/cua) | `experimental` | [`attachment`](../packages/attachment/attachment), [`scope`](../packages/core/scope), [`user-questions`](../packages/interaction/user-questions) | | [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | `experimental` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) | | [`experimental-worktree`](../packages/experimental/worktree) | `experimental` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`subprocess`](../packages/subprocess/subprocess), [`working-directory`](../packages/session/working-directory) | | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | @@ -1770,9 +1802,11 @@ flowchart TD | [`workspace-changes`](../packages/deliverables/workspace-changes) | `deliverables` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) | | [`action-cards`](../packages/experimental/action-cards) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) | | [`creation-recommendations`](../packages/experimental/creation-recommendations) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) | +| [`cua`](../packages/experimental/cua) | `experimental` | [`attachment`](../packages/attachment/attachment), [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), [`scope`](../packages/core/scope), [`user-questions`](../packages/interaction/user-questions) | | [`experimental-browser-use-chrome-devtools-mcp`](../packages/experimental/browser-use-chrome-devtools-mcp) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | | [`experimental-browser-use-playwright-mcp`](../packages/experimental/browser-use-playwright-mcp) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | | [`experimental-browser-use-stagehand-native`](../packages/experimental/browser-use-stagehand-native) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | `experimental` | [`experimental-forge`](../packages/experimental/forge), [`experimental-worktree`](../packages/experimental/worktree), [`fs`](../packages/fs/fs), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`experimental-computer-use-cua-driver-native`](../packages/experimental/computer-use-cua-driver-native) | `experimental` | [`computer-use`](../packages/computer-use/computer-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`experimental-cua-macos`](../packages/experimental/cua-macos) | `experimental` | [`agent`](../packages/core/agent), [`computer-use`](../packages/computer-use/computer-use), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`experimental-tool-worktree`](../packages/experimental/tool-worktree) | `experimental` | [`experimental-worktree`](../packages/experimental/worktree), [`tools`](../packages/core/tools) | @@ -1804,6 +1838,7 @@ flowchart TD | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env) | | [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | +| [`experimental-forge-session`](../packages/experimental/forge-session) | `experimental` | [`experimental-forge`](../packages/experimental/forge), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`tools`](../packages/core/tools) | | [`webhook`](../packages/experimental/webhook) | `experimental` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`app-boot`](../packages/boot/app-boot), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) | @@ -1832,7 +1867,7 @@ flowchart TD | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process) | `subagent` | [`subagent`](../packages/subagent/subagent) | -| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`settings`](../packages/settings/settings), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) | | [`plugin-market`](../packages/boot/plugin-market) | `boot` | [`plugin-manager`](../packages/boot/plugin-manager), [`settings`](../packages/settings/settings), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) | @@ -1844,13 +1879,13 @@ flowchart TD | [`experimental-tool-subagent-oar`](../packages/experimental/tool-subagent-oar) | `experimental` | [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/experimental/hooks-claude-code) | `experimental` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/experimental/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | | [`tool-ralph`](../packages/experimental/tool-ralph) | `experimental` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | -| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | +| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | | [`workflow-ptc`](../packages/workflow/workflow-ptc) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow), [`working-directory`](../packages/session/working-directory) | | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`schedule`](../packages/schedule/schedule) | `schedule` | [`agent`](../packages/core/agent), [`api-session-controller`](../packages/api/session-controller), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`util-time`](../packages/util/time), [`workspace`](../packages/workspace/workspace) | | [`sdk-client`](../packages/sdk/client) | `sdk` | [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | -| [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-hmr`](../packages/client/hmr), [`client-modules`](../packages/client/modules), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web`](../packages/client/web), [`remote-mock`](../packages/test-support/remote-mock), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | +| [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-hmr`](../packages/client/hmr), [`client-modules`](../packages/client/modules), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-context-menu`](../packages/client/ui-context-menu), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web`](../packages/client/web), [`remote-mock`](../packages/test-support/remote-mock), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | | [`tool-schedule`](../packages/schedule/tool-schedule) | `schedule` | [`llm`](../packages/llm/llm), [`schedule`](../packages/schedule/schedule), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | +| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 8d5500ef79..f0c86af34f 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -168,13 +168,14 @@ flowchart TD pkg_client_ui_brand_official["client-ui-brand-official"] pkg_client_ui_chat["client-ui-chat"] pkg_client_ui_commands["client-ui-commands"] + pkg_client_ui_context_menu["client-ui-context-menu"] pkg_client_ui_conversation["client-ui-conversation"] - pkg_client_ui_deepseek_model_label_1017["client-ui-deepseek-model-label-1017"] pkg_client_ui_deliverables["client-ui-deliverables"] pkg_client_ui_directory_picker_browse["client-ui-directory-picker-browse"] pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_dockkit["client-ui-dockkit"] pkg_client_ui_entry_customization["client-ui-entry-customization"] + pkg_client_ui_file_actions["client-ui-file-actions"] pkg_client_ui_file_drag["client-ui-file-drag"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] @@ -277,13 +278,20 @@ flowchart TD pkg_experimental_client_ui_agent_team["experimental-client-ui-agent-team"] pkg_experimental_client_ui_claude_code_mods["experimental-client-ui-claude-code-mods"] pkg_experimental_client_ui_cot_translation["experimental-client-ui-cot-translation"] + pkg_experimental_client_ui_forge["experimental-client-ui-forge"] + pkg_experimental_client_ui_stats["experimental-client-ui-stats"] pkg_experimental_client_ui_voice_input["experimental-client-ui-voice-input"] pkg_experimental_computer_use_cua_driver_mcp["experimental-computer-use-cua-driver-mcp"] pkg_experimental_computer_use_cua_driver_native["experimental-computer-use-cua-driver-native"] pkg_experimental_cot_translation_bundle["experimental-cot-translation-bundle"] pkg_experimental_cua_macos["experimental-cua-macos"] + pkg_experimental_forge["experimental-forge"] + pkg_experimental_forge_bundle["experimental-forge-bundle"] + pkg_experimental_forge_github["experimental-forge-github"] + pkg_experimental_forge_session["experimental-forge-session"] pkg_experimental_inspector["experimental-inspector"] pkg_experimental_inspector_profile["experimental-inspector-profile"] + pkg_experimental_liveshare["experimental-liveshare"] pkg_experimental_liveshare_protocol["experimental-liveshare-protocol"] pkg_experimental_plugin_market_bundle["experimental-plugin-market-bundle"] pkg_experimental_ptc_runtime_python["experimental-ptc-runtime-python"] @@ -496,6 +504,7 @@ flowchart TD pkg_credentials_local --> pkg_credentials pkg_credentials_local --> pkg_home_paths pkg_credentials_local --> pkg_launch_environment + pkg_experimental_liveshare --> pkg_scope pkg_anonymous_user_id --> pkg_brand pkg_anonymous_user_id --> pkg_home_paths pkg_lsp --> pkg_brand @@ -523,6 +532,8 @@ flowchart TD pkg_hmr --> pkg_cmdline pkg_deliverable_file_references --> pkg_system_prompt pkg_experimental_computer_use_cua_driver_mcp --> pkg_computer_use + pkg_experimental_forge_github --> pkg_experimental_forge + pkg_experimental_forge_github --> pkg_subprocess pkg_experimental_webworker_runtime --> pkg_client_connection pkg_experimental_webworker_runtime --> pkg_client_modules pkg_experimental_webworker_runtime --> pkg_host_webserver @@ -783,9 +794,6 @@ flowchart TD pkg_deepseek_account_platform --> pkg_credentials pkg_deepseek_account_platform --> pkg_deepseek_account pkg_deepseek_account_platform --> pkg_host_webserver - pkg_cua --> pkg_attachment - pkg_cua --> pkg_scope - pkg_cua --> pkg_user_questions pkg_experimental_ptc_runtime_python --> pkg_ptc_runtime pkg_experimental_ptc_runtime_python --> pkg_sandbox pkg_experimental_ptc_runtime_python --> pkg_sandbox_policy @@ -949,6 +957,10 @@ flowchart TD pkg_creation_recommendations --> pkg_session pkg_creation_recommendations --> pkg_skill pkg_creation_recommendations --> pkg_tools + pkg_cua --> pkg_attachment + pkg_cua --> pkg_ptc_runtime_node + pkg_cua --> pkg_scope + pkg_cua --> pkg_user_questions pkg_experimental_browser_use_chrome_devtools_mcp --> pkg_agent pkg_experimental_browser_use_chrome_devtools_mcp --> pkg_browser_use pkg_experimental_browser_use_chrome_devtools_mcp --> pkg_system_prompt @@ -963,6 +975,11 @@ flowchart TD pkg_experimental_browser_use_stagehand_native --> pkg_browser_use pkg_experimental_browser_use_stagehand_native --> pkg_system_prompt pkg_experimental_browser_use_stagehand_native --> pkg_tools + pkg_experimental_client_ui_forge --> pkg_experimental_forge + pkg_experimental_client_ui_forge --> pkg_experimental_worktree + pkg_experimental_client_ui_forge --> pkg_fs + pkg_experimental_client_ui_forge --> pkg_session + pkg_experimental_client_ui_forge --> pkg_timeout pkg_experimental_computer_use_cua_driver_native --> pkg_computer_use pkg_experimental_computer_use_cua_driver_native --> pkg_system_prompt pkg_experimental_computer_use_cua_driver_native --> pkg_tools @@ -1120,6 +1137,13 @@ flowchart TD pkg_experimental_auto_review --> pkg_session pkg_experimental_auto_review --> pkg_tools pkg_experimental_auto_review --> pkg_working_directory + pkg_experimental_forge_session --> pkg_experimental_forge + pkg_experimental_forge_session --> pkg_sandbox_policy + pkg_experimental_forge_session --> pkg_session + pkg_experimental_forge_session --> pkg_session_projection + pkg_experimental_forge_session --> pkg_shell + pkg_experimental_forge_session --> pkg_shell_env + pkg_experimental_forge_session --> pkg_tools pkg_webhook --> pkg_agent pkg_webhook --> pkg_agent_default_model pkg_webhook --> pkg_agent_preset_registry @@ -1302,7 +1326,6 @@ flowchart TD pkg_tool_subagent --> pkg_agent pkg_tool_subagent --> pkg_agent_preset_registry pkg_tool_subagent --> pkg_llm - pkg_tool_subagent --> pkg_scope pkg_tool_subagent --> pkg_session pkg_tool_subagent --> pkg_session_projection pkg_tool_subagent --> pkg_subagent @@ -1408,6 +1431,7 @@ flowchart TD pkg_tool_ralph --> pkg_system_prompt pkg_tool_ralph --> pkg_tools pkg_tool_ralph --> pkg_workflow + pkg_sdk_protocol --> pkg_commands pkg_sdk_protocol --> pkg_llm pkg_sdk_protocol --> pkg_session pkg_sdk_protocol --> pkg_subagent @@ -1454,6 +1478,7 @@ flowchart TD pkg_client_test_runtime --> pkg_client_modules pkg_client_test_runtime --> pkg_client_store pkg_client_test_runtime --> pkg_client_ui_chat + pkg_client_test_runtime --> pkg_client_ui_context_menu pkg_client_test_runtime --> pkg_client_ui_conversation pkg_client_test_runtime --> pkg_client_ui_renderer pkg_client_test_runtime --> pkg_client_ui_session @@ -1476,6 +1501,8 @@ flowchart TD pkg_tool_schedule --> pkg_tools pkg_sdk_jsonrpc_server --> pkg_agent pkg_sdk_jsonrpc_server --> pkg_attachment + pkg_sdk_jsonrpc_server --> pkg_commands + pkg_sdk_jsonrpc_server --> pkg_goal pkg_sdk_jsonrpc_server --> pkg_llm pkg_sdk_jsonrpc_server --> pkg_llm_deepseek_api_key pkg_sdk_jsonrpc_server --> pkg_schedule @@ -1538,13 +1565,14 @@ flowchart TD | [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | — | | [`client-ui-chat`](../packages/client/ui-chat) | `client` | — | | [`client-ui-commands`](../packages/client/ui-commands) | `client` | — | +| [`client-ui-context-menu`](../packages/client/ui-context-menu) | `client` | — | | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | — | -| [`client-ui-deepseek-model-label-1017`](../packages/client/ui-deepseek-model-label-1017) | `client` | — | | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — | | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — | | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | | [`client-ui-dockkit`](../packages/client/ui-dockkit) | `client` | — | | [`client-ui-entry-customization`](../packages/client/ui-entry-customization) | `client` | — | +| [`client-ui-file-actions`](../packages/client/ui-file-actions) | `client` | — | | [`client-ui-file-drag`](../packages/client/ui-file-drag) | `client` | — | | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | @@ -1601,8 +1629,11 @@ flowchart TD | [`experimental-badge-skill-bundle`](../packages/experimental/badge-skill-bundle) | `experimental` | — | | [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | — | | [`experimental-client-ui-claude-code-mods`](../packages/experimental/client-ui-claude-code-mods) | `experimental` | — | +| [`experimental-client-ui-stats`](../packages/experimental/client-ui-stats) | `experimental` | — | | [`experimental-client-ui-voice-input`](../packages/experimental/client-ui-voice-input) | `experimental` | — | | [`experimental-cot-translation-bundle`](../packages/experimental/cot-translation-bundle) | `experimental` | — | +| [`experimental-forge`](../packages/experimental/forge) | `experimental` | — | +| [`experimental-forge-bundle`](../packages/experimental/forge-bundle) | `experimental` | — | | [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | — | | [`experimental-inspector-profile`](../packages/experimental/inspector-profile) | `experimental` | — | | [`experimental-liveshare-protocol`](../packages/experimental/liveshare-protocol) | `experimental` | — | @@ -1647,6 +1678,7 @@ flowchart TD | [`computer-use`](../packages/computer-use/computer-use) | `computer-use` | [`brand`](../packages/util/brand) | | [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`llm`](../packages/llm/llm) | | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment) | +| [`experimental-liveshare`](../packages/experimental/liveshare) | `experimental` | [`scope`](../packages/core/scope) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths) | | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`storage`](../packages/storage/storage) | @@ -1665,6 +1697,7 @@ flowchart TD | [`hmr`](../packages/boot/hmr) | `boot` | [`app-boot`](../packages/boot/app-boot), [`cmdline`](../packages/boot/cmdline) | | [`deliverable-file-references`](../packages/deliverables/deliverable-file-references) | `deliverables` | [`system-prompt`](../packages/core/system-prompt) | | [`experimental-computer-use-cua-driver-mcp`](../packages/experimental/computer-use-cua-driver-mcp) | `experimental` | [`computer-use`](../packages/computer-use/computer-use) | +| [`experimental-forge-github`](../packages/experimental/forge-github) | `experimental` | [`experimental-forge`](../packages/experimental/forge), [`subprocess`](../packages/subprocess/subprocess) | | [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) | | [`plugin-recommendations`](../packages/experimental/plugin-recommendations) | `experimental` | [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`typert-protocol`](../packages/typert/protocol) | | [`skill-badge`](../packages/experimental/skill-badge) | `experimental` | [`skill`](../packages/skill/skill) | @@ -1740,7 +1773,6 @@ flowchart TD | [`api-account-controller`](../packages/api/account-controller) | `api` | [`agent`](../packages/core/agent), [`deepseek-account`](../packages/credentials/deepseek-account), [`typert-protocol`](../packages/typert/protocol) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`deepseek-account-platform`](../packages/credentials/deepseek-account-platform) | `credentials` | [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`deepseek-account`](../packages/credentials/deepseek-account), [`host-webserver`](../packages/host/webserver) | -| [`cua`](../packages/experimental/cua) | `experimental` | [`attachment`](../packages/attachment/attachment), [`scope`](../packages/core/scope), [`user-questions`](../packages/interaction/user-questions) | | [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | `experimental` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) | | [`experimental-worktree`](../packages/experimental/worktree) | `experimental` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`subprocess`](../packages/subprocess/subprocess), [`working-directory`](../packages/session/working-directory) | | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | @@ -1772,9 +1804,11 @@ flowchart TD | [`workspace-changes`](../packages/deliverables/workspace-changes) | `deliverables` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) | | [`action-cards`](../packages/experimental/action-cards) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) | | [`creation-recommendations`](../packages/experimental/creation-recommendations) | `experimental` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) | +| [`cua`](../packages/experimental/cua) | `experimental` | [`attachment`](../packages/attachment/attachment), [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), [`scope`](../packages/core/scope), [`user-questions`](../packages/interaction/user-questions) | | [`experimental-browser-use-chrome-devtools-mcp`](../packages/experimental/browser-use-chrome-devtools-mcp) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | | [`experimental-browser-use-playwright-mcp`](../packages/experimental/browser-use-playwright-mcp) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | | [`experimental-browser-use-stagehand-native`](../packages/experimental/browser-use-stagehand-native) | `experimental` | [`agent`](../packages/core/agent), [`browser-use`](../packages/browser-use/browser-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`experimental-client-ui-forge`](../packages/experimental/client-ui-forge) | `experimental` | [`experimental-forge`](../packages/experimental/forge), [`experimental-worktree`](../packages/experimental/worktree), [`fs`](../packages/fs/fs), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`experimental-computer-use-cua-driver-native`](../packages/experimental/computer-use-cua-driver-native) | `experimental` | [`computer-use`](../packages/computer-use/computer-use), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`experimental-cua-macos`](../packages/experimental/cua-macos) | `experimental` | [`agent`](../packages/core/agent), [`computer-use`](../packages/computer-use/computer-use), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`experimental-tool-worktree`](../packages/experimental/tool-worktree) | `experimental` | [`experimental-worktree`](../packages/experimental/worktree), [`tools`](../packages/core/tools) | @@ -1806,6 +1840,7 @@ flowchart TD | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env) | | [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | +| [`experimental-forge-session`](../packages/experimental/forge-session) | `experimental` | [`experimental-forge`](../packages/experimental/forge), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`tools`](../packages/core/tools) | | [`webhook`](../packages/experimental/webhook) | `experimental` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`app-boot`](../packages/boot/app-boot), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) | @@ -1834,7 +1869,7 @@ flowchart TD | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process) | `subagent` | [`subagent`](../packages/subagent/subagent) | -| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`settings`](../packages/settings/settings), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) | | [`plugin-market`](../packages/boot/plugin-market) | `boot` | [`plugin-manager`](../packages/boot/plugin-manager), [`settings`](../packages/settings/settings), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) | @@ -1846,13 +1881,13 @@ flowchart TD | [`experimental-tool-subagent-oar`](../packages/experimental/tool-subagent-oar) | `experimental` | [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/experimental/hooks-claude-code) | `experimental` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/experimental/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) | | [`tool-ralph`](../packages/experimental/tool-ralph) | `experimental` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | -| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | +| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-questions`](../packages/interaction/user-questions) | | [`workflow-ptc`](../packages/workflow/workflow-ptc) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow), [`working-directory`](../packages/session/working-directory) | | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-names`](../packages/subagent/subagent-names), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`schedule`](../packages/schedule/schedule) | `schedule` | [`agent`](../packages/core/agent), [`api-session-controller`](../packages/api/session-controller), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`util-time`](../packages/util/time), [`workspace`](../packages/workspace/workspace) | | [`sdk-client`](../packages/sdk/client) | `sdk` | [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | -| [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-hmr`](../packages/client/hmr), [`client-modules`](../packages/client/modules), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web`](../packages/client/web), [`remote-mock`](../packages/test-support/remote-mock), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | +| [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-hmr`](../packages/client/hmr), [`client-modules`](../packages/client/modules), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-context-menu`](../packages/client/ui-context-menu), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web`](../packages/client/web), [`remote-mock`](../packages/test-support/remote-mock), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | | [`tool-schedule`](../packages/schedule/tool-schedule) | `schedule` | [`llm`](../packages/llm/llm), [`schedule`](../packages/schedule/schedule), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | +| [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`llm-deepseek-api-key`](../packages/llm/llm-deepseek-api-key), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions), [`working-directory`](../packages/session/working-directory) | diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index 2b350f86b6..26340e4d42 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.i18n.yaml @@ -9,8 +9,8 @@ en: 1387c4505dde2faf zh: 48570fa1c13d6910 /session-persistence-event-catalog/persistence-type-fingerprints: - en: 74b497d16862ed7b - zh: c70f43a287216d23 + en: 088cb72804e82469 + zh: 318436b677ab8075 /session-persistence-event-catalog/event-envelope: en: 56414ffd00cdc32a zh: 6dc11eb013e95e41 @@ -186,14 +186,14 @@ en: 6c6a27578dff5828 zh: 9a5add2bc0df2d0a /session-persistence-event-catalog/events/session/session-title-llm-request-log-only: - en: 50d9e29d3d2bfe52 - zh: 3ff1d959cf7776b9 + en: 59b02baa2be32ca0 + zh: 3637c99652ca89cf /session-persistence-event-catalog/events/session-log-deepseek: en: 7b827672c80aecdd zh: 7b827672c80aecdd /session-persistence-event-catalog/events/session-log-deepseek/session-log-deepseek-delivery-accepted-log-only: - en: 4e9ce9182ec05808 - zh: 7f643a6756ec8f76 + en: a3e2059fcc540b64 + zh: cc9933fd677560f0 /session-persistence-event-catalog/events/step: en: bd0dcbbc352b771a zh: bd0dcbbc352b771a @@ -561,8 +561,8 @@ en: 028791baa24a6a0a zh: 028791baa24a6a0a /session-persistence-event-catalog/resolved-persistence-types/in-history: - en: 3e9695c61a9e30c8 - zh: cdc765b18de2d665 + en: ad2f023eedbc2a7e + zh: 2124b8dedfbf8383 /session-persistence-event-catalog/resolved-persistence-types/in-progress: en: 61de2b0c9de8c15b zh: 61de2b0c9de8c15b @@ -759,8 +759,11 @@ en: 1e5fb67af2382e55 zh: 1e5fb67af2382e55 /session-persistence-event-catalog/resolved-persistence-types/set: - en: b2a724cef8d97ef7 - zh: b2a724cef8d97ef7 + en: 8e70b63b25a29f58 + zh: 8e70b63b25a29f58 +/session-persistence-event-catalog/resolved-persistence-types/share-viewer: + en: 761fbf929bc6e6ed + zh: 761fbf929bc6e6ed /session-persistence-event-catalog/resolved-persistence-types/skill-catalog: en: 9483a26e4c21d639 zh: 9483a26e4c21d639 @@ -999,11 +1002,11 @@ en: 87f2aaf2b23a5249 zh: 3d6c5ed6603bee31 /session-persistence-event-catalog/resolved-persistence-types/contentblock: - en: d3eb9a17ab27856f - zh: a71b16a1e36a36ac + en: 920125405e3f3d40 + zh: f2b241fc44cd63be /session-persistence-event-catalog/resolved-persistence-types/contentblocktype: - en: 27dc8b92bae26f1f - zh: e05ace867fb59ae1 + en: d51d3737a6f1208f + zh: 7109487fbfaee359 /session-persistence-event-catalog/resolved-persistence-types/contentblock~2: en: 9207aa0489ccf8db zh: 850dd92da6769998 @@ -1017,11 +1020,11 @@ en: a6a2e38fdd6d127a zh: 1fe82356d89f5769 /session-persistence-event-catalog/resolved-persistence-types/deepseeksearchllmrequest: - en: 0e286bae74e78505 - zh: b1c9da5aa56d5a81 + en: fd75d1f4b9bd643c + zh: dde892ea9752f298 /session-persistence-event-catalog/resolved-persistence-types/developermessage: - en: 3d8a393be23efcde - zh: f95f337d816dbbe7 + en: c6171fd8144d74b1 + zh: 2f3dd34cc8d7ed92 /session-persistence-event-catalog/resolved-persistence-types/epochheader: en: 3bdc8ecd0bdf0c9c zh: 0fe5b75c174ebab4 @@ -1035,11 +1038,11 @@ en: 0bf0caf488d14011 zh: 734501852de79a21 /session-persistence-event-catalog/resolved-persistence-types/fileblock: - en: 4cab6c6ed2abedd8 - zh: a6cdd344e6c36c24 + en: cc6e6a199425dde9 + zh: 8a23127ba156d058 /session-persistence-event-catalog/resolved-persistence-types/finishreason: - en: 49fd9834247f3cc2 - zh: 4378ead90069d0d6 + en: 4a9e91f2673dfed0 + zh: 89d08b1d16191cfe /session-persistence-event-catalog/resolved-persistence-types/goalblockreason: en: b1589f9578a585dd zh: 3783dbbd8793bb37 @@ -1074,8 +1077,8 @@ en: 76ee1e266cd651da zh: 55c7c95a223ccbed /session-persistence-event-catalog/resolved-persistence-types/imageblock: - en: ccafbcae37570ce2 - zh: fbf43a8c7ff26154 + en: 31b19d23dfee0571 + zh: 3ffa6c6d18cf73d5 /session-persistence-event-catalog/resolved-persistence-types/imagemediatype: en: 32d86426192176d5 zh: c86291efc19bdc91 @@ -1125,17 +1128,17 @@ en: 8f669d7819805099 zh: 391d51d7835afe02 /session-persistence-event-catalog/resolved-persistence-types/llmfailure: - en: a18d2091f7e64726 - zh: 550fc25036bd096e + en: 1c1591ce9b3cc186 + zh: 74ebe1b8c58e87d7 /session-persistence-event-catalog/resolved-persistence-types/llmretryeventdata: en: 6dbe099c62f7c226 zh: 6fd788f63c038c91 /session-persistence-event-catalog/resolved-persistence-types/llmretrystartedeventdata: - en: 3d2f7c88259b6446 - zh: 58bee68c335d6d4f + en: 06b510217b6056c4 + zh: 5b3a1e022f96de57 /session-persistence-event-catalog/resolved-persistence-types/message: - en: 76d13d39fe22f7bd - zh: b1e19cfe90a6d6b6 + en: 7a8ec632289bc7f9 + zh: 5c90cb4f3d5d0a67 /session-persistence-event-catalog/resolved-persistence-types/messagefeedbackdelete: en: c582953270d4ca44 zh: 966ccfe2e7660a2a @@ -1146,14 +1149,14 @@ en: f58575a1fc96df42 zh: 9f0c6ed9033e5c9d /session-persistence-event-catalog/resolved-persistence-types/messagefeedbackrating: - en: 887549d6401dd116 - zh: 30198672b67dac6b + en: 65fb012fcc0fa7db + zh: b829c586714e45e2 /session-persistence-event-catalog/resolved-persistence-types/messagesource: - en: 2f21414632f8d184 - zh: d85f66e001fd814c + en: ddeed90cb6112496 + zh: cefb41765c45b22f /session-persistence-event-catalog/resolved-persistence-types/message~2: - en: 87e95476b4985e5e - zh: 0e0322e005b3e995 + en: 8e96551640079569 + zh: a06d587638d42237 /session-persistence-event-catalog/resolved-persistence-types/modelmessagesource: en: 5f9154ca34235ab9 zh: a833105910ebfa82 @@ -1173,11 +1176,8 @@ en: 3e36e2f29ff1b506 zh: 3dcc1a1dced59d9f /session-persistence-event-catalog/resolved-persistence-types/presentedfile~2: - en: bb11552744e477b8 - zh: afb881f3ebf97e68 -/session-persistence-event-catalog/resolved-persistence-types/principal: - en: 6d0d81e0e833403e - zh: fa47cd75ee75f948 + en: 764b3e83192daae3 + zh: aa3f87bffe8fb501 /session-persistence-event-catalog/resolved-persistence-types/ptcdispatcheventdata: en: c0f7b22b41cb0608 zh: de14a1b5cac17665 @@ -1185,11 +1185,11 @@ en: aca35dac4f9d2add zh: 6a4bdb95e3c7b0ce /session-persistence-event-catalog/resolved-persistence-types/reasoningblock: - en: 07e04c3e336f880f - zh: 6f8986ede9994fa1 + en: 8d2873c634bf6405 + zh: 91e92b5730462cf0 /session-persistence-event-catalog/resolved-persistence-types/replayenvelope: - en: 488050ba0b6438b4 - zh: 2bf607b5ad51e39d + en: 34cbedee7bc95921 + zh: f7deeddb8d60152a /session-persistence-event-catalog/resolved-persistence-types/requestcontext: en: 544039047a28b6bb zh: c691f0bb1e23db08 @@ -1215,11 +1215,11 @@ en: 9a54c4478ad3b620 zh: 02c4c1fd7e252770 /session-persistence-event-catalog/resolved-persistence-types/sessiontitleeventdata: - en: c0104327b481ae54 - zh: b4624d112bee37f1 + en: 1f9f610fa0e05abf + zh: 11560710a1b871de /session-persistence-event-catalog/resolved-persistence-types/sessiontitlellmrequesteventdata: - en: 2e40681d575da503 - zh: 57cbccb16548e2da + en: 465fe144e60dd62f + zh: 29e1029426106c3b /session-persistence-event-catalog/resolved-persistence-types/sessiontitlemodelidentity: en: 9531468264499498 zh: 9da23c0ad2776563 @@ -1227,17 +1227,20 @@ en: 13de8e35b749db45 zh: 01e4f3bcb6784fc8 /session-persistence-event-catalog/resolved-persistence-types/sessiontitlesource: - en: 2642015fb4518c8c - zh: 152b294f41fbdcca + en: 8e07874aa7841b0b + zh: d93527a0f8837075 +/session-persistence-event-catalog/resolved-persistence-types/shareviewerprincipal: + en: a7b8c3f842059eec + zh: 4b345faa13cc39f6 /session-persistence-event-catalog/resolved-persistence-types/skillcatalogsource: - en: de04d42a8b0004df - zh: db64863dd7da1e26 + en: 2c3148e4a9f0c8f9 + zh: dab42cb485067bcd /session-persistence-event-catalog/resolved-persistence-types/skillinvocationsource: en: ecc15ebadb77afdf zh: 97ac27d6a4175f6f /session-persistence-event-catalog/resolved-persistence-types/streamchunk: - en: 6a9cc39c2df1b476 - zh: 697ea4d14d77f59c + en: 76ef1d6de369c7b5 + zh: e033b6bbaa455e87 /session-persistence-event-catalog/resolved-persistence-types/subagentcatalogevent: en: 725539dcd5c335ed zh: 5ca08d3667f84ff9 @@ -1275,8 +1278,8 @@ en: a5fefaa709230c60 zh: e08a6d4ef753aa1b /session-persistence-event-catalog/resolved-persistence-types/textblock: - en: c5fcd2cdd37ea387 - zh: 9c678fbdea0bf25c + en: 7ad0f4915397b511 + zh: bcaa8bd449927989 /session-persistence-event-catalog/resolved-persistence-types/todoitem: en: ee24f9407df530ac zh: 310bedf3ac730d77 @@ -1284,20 +1287,20 @@ en: 8bf023246cbd0887 zh: dbf7113574c1bf59 /session-persistence-event-catalog/resolved-persistence-types/tokenusage: - en: 0aa983637b619157 - zh: e0f68258606aae78 + en: 09833c3cf66cc620 + zh: b7e9b3c138dae85b /session-persistence-event-catalog/resolved-persistence-types/tooladditionblock: - en: 7ba7c600fc529015 - zh: 94b69e9d5bd1fcfd + en: bbce95b556fe670f + zh: a1f1cae553a356ab /session-persistence-event-catalog/resolved-persistence-types/toolcallblock: - en: 78482b09dc227306 - zh: fb5852ac93beb20e + en: d7478804801b52a4 + zh: 27287739a5874fdd /session-persistence-event-catalog/resolved-persistence-types/toolmessagesource: en: 036b2595215410bb zh: 41792808ebac1fa3 /session-persistence-event-catalog/resolved-persistence-types/toolremovalblock: - en: fdac0df45529e14c - zh: c5e38de83a0e0a42 + en: 0080c345c319a4b5 + zh: de1a8b3ed621ce21 /session-persistence-event-catalog/resolved-persistence-types/toolrestriction: en: d70be5d46cb1ef7d zh: d3d5a05d62e443fe @@ -1305,8 +1308,8 @@ en: 2258683c3cfa4ce3 zh: 5663aa76c911761b /session-persistence-event-catalog/resolved-persistence-types/toolschema: - en: 689c56f199c0035d - zh: 48bcb9d508d1892c + en: afa1e3fd9ccdd95b + zh: 7af667e3ebac25e8 /session-persistence-event-catalog/resolved-persistence-types/toolschema~2: en: 12c14727bb7834e2 zh: b0f3c877873c36db @@ -1326,14 +1329,14 @@ en: 778debd61e0284a2 zh: 2cc82ad9e80f18b1 /session-persistence-event-catalog/resolved-persistence-types/turnendreason: - en: 933770adc9ee2780 - zh: 8d8462c33ed6029e + en: 953127f7cf1e0866 + zh: 3613ef1aafd8191a /session-persistence-event-catalog/resolved-persistence-types/usermessage: - en: 79b3ac6c731859aa - zh: 81058fe7edf61bdb + en: a15a08beb2b824da + zh: 4fd8dc6b9680c4cf /session-persistence-event-catalog/resolved-persistence-types/usermessage~2: - en: 8e699c0217638bbe - zh: a2047db24c25217b + en: 85e537b82f1da7d8 + zh: 73a1b9d4b5d29ab0 /session-persistence-event-catalog/resolved-persistence-types/workflowagentoutcome: en: d0a3f9aab18c3de5 zh: 76ac69a835ca4e29 @@ -1359,8 +1362,8 @@ en: 2786fef560851bb4 zh: 5d787475356b2606 /session-persistence-event-catalog/resolved-persistence-types/string: - en: b29b01875054c0c3 - zh: 5ea4dfdd60f30112 + en: e5a7ee4569d7d428 + zh: 9c7b9d92151feb2f /session-persistence-event-catalog/resolved-persistence-types/string~2: en: 0089620bf4638263 zh: 1922bef1713094bb @@ -1380,9 +1383,12 @@ en: f692844b29923b2e zh: 72f12bca08d63267 /session-persistence-event-catalog/resolved-persistence-types/union-2-variants~2: - en: 69d360cf5a1ae6b4 - zh: f23faf39a2a0e6f1 + en: 4a1acf31ea15d403 + zh: d1ebe94ffd308763 /session-persistence-event-catalog/resolved-persistence-types/union-2-variants~3: + en: 4318d8c6211d4e95 + zh: d08f3f8c11c32506 +/session-persistence-event-catalog/resolved-persistence-types/union-2-variants~4: en: 5a1af9849b0967ea zh: 1085d793bbc47360 /session-persistence-event-catalog/resolved-persistence-types/union-3-variants: @@ -1488,14 +1494,17 @@ en: 10a2d594b106f6fe zh: 8408379e744ad987 /session-persistence-event-catalog/resolved-persistence-types/description-name: - en: e501ab0e92f12d77 - zh: 087fb91a04f85398 + en: 26072d80c066a334 + zh: 48deed5b57fecba4 /session-persistence-event-catalog/resolved-persistence-types/description-name~2: en: a07969828eed2e6f zh: e06893743af544b5 /session-persistence-event-catalog/resolved-persistence-types/dialect-handlerid-matcher-point: - en: eeba88520aacd126 - zh: 8e2ca4e2bd2c1e3a + en: 9748b4f0facfe9f8 + zh: 83ae2cd2cd02b804 +/session-persistence-event-catalog/resolved-persistence-types/displayname-providerid-subjectid-tenantid: + en: d2c98ed9b98325ae + zh: bf8c2f7967cf9cc8 /session-persistence-event-catalog/resolved-persistence-types/end-start: en: 4b7a8793663d3fef zh: 249459c825d330c3 @@ -1509,17 +1518,17 @@ en: d019b2909673d2a7 zh: cc16e9c055ea603d /session-persistence-event-catalog/resolved-persistence-types/failure-kind-aborted: - en: 349cd90f2598fd12 - zh: 1eda02d520ad5d76 + en: 7dddcbc923491531 + zh: bbdaea7d433b6fda /session-persistence-event-catalog/resolved-persistence-types/failure-kind-error: - en: 51af619ed8532a43 - zh: a5ad878c63d0e046 + en: 4cb1c48095df98dc + zh: 5a03e44761af559e /session-persistence-event-catalog/resolved-persistence-types/header-reason-startsseries: - en: e4a915fcd4cca68b - zh: 04a70157c20a2f80 + en: 7d1610d20e987988 + zh: 1297cba0f2a2c73d /session-persistence-event-catalog/resolved-persistence-types/headerseq-message-step-turn: - en: 0f367699daf0d4de - zh: 58b980af0f365374 + en: 4f9635604ed5b84d + zh: 74810a2d049907e6 /session-persistence-event-catalog/resolved-persistence-types/height-width: en: a5df50710083ac25 zh: aad3ccf6f6de70e4 @@ -1536,11 +1545,11 @@ en: 41f73c58a77dfa28 zh: af77f4aee3cb4a40 /session-persistence-event-catalog/resolved-persistence-types/inherited: - en: 0e761849881f1b90 - zh: 62f72209fb941192 + en: 8b5c65ce7b57514f + zh: 231494d71e5d635a /session-persistence-event-catalog/resolved-persistence-types/inserted-outcome-removedcount-start: - en: 1750502af87d698c - zh: 382a3356f0a61546 + en: 5a3be677a8dc51ff + zh: c5fc8b80f73e72d9 /session-persistence-event-catalog/resolved-persistence-types/interrupted-message-step-stream: en: 8e86cd838e3e4a49 zh: f5fec2a8adf1f3cc @@ -1659,8 +1668,8 @@ en: 673110c18ee48238 zh: e8dd81d68e1a4ee0 /session-persistence-event-catalog/resolved-persistence-types/kind-max-tokens: - en: 337ebe760096729a - zh: bd35a401103a3071 + en: 7092c1681af1dacb + zh: a0c5505f839592ed /session-persistence-event-catalog/resolved-persistence-types/kind-model-selection: en: a5165486dca91116 zh: b7051ca8167806ef @@ -1680,8 +1689,11 @@ en: 3c986a3b9cbc4f95 zh: 875bc0c6d786f80e /session-persistence-event-catalog/resolved-persistence-types/kind-model-selection-form-snapshot: - en: 509f9a91aedb2da1 - zh: db1071678bfb98d1 + en: b0e849caa4bd0be7 + zh: e5d0dbcf8a326caf +/session-persistence-event-catalog/resolved-persistence-types/kind-owner: + en: 686b6465397b96c2 + zh: c21c1cc3c9df4fd8 /session-persistence-event-catalog/resolved-persistence-types/kind-parent: en: 5ab43c283829de53 zh: 5ed4e90922a3a88b @@ -1776,8 +1788,8 @@ en: c99d8a67438771ff zh: 070f6160fc419fa5 /session-persistence-event-catalog/resolved-persistence-types/kind-stop: - en: 09ce6f3196938ccf - zh: 1b8d5540f47fd3aa + en: a54b282e864ff035 + zh: 973e729590675d85 /session-persistence-event-catalog/resolved-persistence-types/kind-time-context: en: 5733addfc8b12a47 zh: aaf60d5396e30971 @@ -1821,8 +1833,8 @@ en: b05115b92a176f3a zh: 22ba93572bd0209a /session-persistence-event-catalog/resolved-persistence-types/kind-tool-calls: - en: 65fb50e399cddd05 - zh: 9e713bbcb1b7db35 + en: b9203133bb7e6d5a + zh: b3f32a61983bb2e4 /session-persistence-event-catalog/resolved-persistence-types/kind-tool-goal: en: e11ea3169004ae33 zh: 7d6a3a77cb9bf205 @@ -1866,11 +1878,11 @@ en: 08be4349548406a9 zh: 8e7cf9966198ef78 /session-persistence-event-catalog/resolved-persistence-types/kind-tool-registry: - en: 5a0bbf4c76266ac5 - zh: 0b20854f90f9d74d + en: 4e102391d685eff5 + zh: 9762243a13014f3d /session-persistence-event-catalog/resolved-persistence-types/kind-user: - en: 81620af099525ee9 - zh: 812db2fdf9e5d309 + en: 984cac7296874653 + zh: 13b4ee707a8ce305 /session-persistence-event-catalog/resolved-persistence-types/kind-user-approval: en: a52d2dfbaf844127 zh: 4c5306ca40f20873 @@ -1932,8 +1944,8 @@ en: 04b34b8ffe7e7764 zh: a792d5371516fd9d /session-persistence-event-catalog/resolved-persistence-types/sessionformatversion-sessionid-throughseq: - en: 8aaa02b06896492d - zh: 4dd0e1ee40d8f22d + en: 8063597183ef767f + zh: b064698c54089f07 /session-persistence-event-catalog/resolved-persistence-types/shadowedrange-shadowedseqs-shadowedtokencount: en: 7a2ab7b62244f43b zh: 1084e3f8876feebc @@ -1956,11 +1968,11 @@ en: 374b8adee8d571fa zh: b21057efc58e6490 /session-persistence-event-catalog/resolved-persistence-types/type-agent-preset-selected: - en: 6a59f1cd472759e9 - zh: 1db67f4f97207efc + en: da6e084997b20cdc + zh: 1780f6fcf3496de1 /session-persistence-event-catalog/resolved-persistence-types/type-agent-inbox-spliced: - en: 6c276128e62a5432 - zh: 4ff5e93d255caece + en: 1a79ed1a97145a14 + zh: d6f658a85c1e65f7 /session-persistence-event-catalog/resolved-persistence-types/type-approval-asked: en: 9c77f18b0dad22f0 zh: 8894cf2878fe90db @@ -1977,11 +1989,11 @@ en: bb507524bcc39c53 zh: 8314898562437473 /session-persistence-event-catalog/resolved-persistence-types/type-block-end: - en: f23d45580ba6d17b - zh: 4bdf4fc300a5b287 + en: 7513d6a33f4ad113 + zh: 652201059a3de858 /session-persistence-event-catalog/resolved-persistence-types/type-block-start: - en: ec1f0e5653a604db - zh: f905b8ce4d3730be + en: 56230efa41e79869 + zh: 9ca4b8990a28d4d9 /session-persistence-event-catalog/resolved-persistence-types/type-chunk: en: 2186ede3e9917aea zh: 0cfef64045dce95b @@ -2004,11 +2016,11 @@ en: ba73fb10b7e2ffc9 zh: 8d5c97e63e5f16da /session-persistence-event-catalog/resolved-persistence-types/type-deliverables-presented: - en: 10d95ce64c285e64 - zh: 0ddb26f1fa16629c + en: b9c35ef9a9e1d585 + zh: 7b8ad008c8b7389c /session-persistence-event-catalog/resolved-persistence-types/type-developer-message: - en: 78d421c83506ebe9 - zh: 2e9399ba2d360627 + en: b0a3c504326f42f9 + zh: f13a1c1ca28f7da3 /session-persistence-event-catalog/resolved-persistence-types/type-disabled: en: 585627a50ece4e5f zh: 157837aee3da0ac3 @@ -2022,8 +2034,8 @@ en: 14e4b48d856bcf57 zh: 72ba176535dc7f3f /session-persistence-event-catalog/resolved-persistence-types/type-finish: - en: 76f708f530d4fc9a - zh: b6f1100c734a5991 + en: 30f8f49d0755dc2d + zh: d8553c9590a0e9bf /session-persistence-event-catalog/resolved-persistence-types/type-goal-change: en: aad2516b62d3ee83 zh: e7204c4dc4e8e408 @@ -2061,8 +2073,8 @@ en: 34e5591d75322649 zh: a216839f305c9796 /session-persistence-event-catalog/resolved-persistence-types/type-reasoning-delta: - en: d1bf7fbf222b717a - zh: e88811c2e0d45fb6 + en: a3f08ffda3526201 + zh: e599517be130ff99 /session-persistence-event-catalog/resolved-persistence-types/type-request-context: en: f8addb1a01da9ca1 zh: 4ef11ebddd302c05 @@ -2082,11 +2094,11 @@ en: acf7e21e4d21ebff zh: fb83a853634d204a /session-persistence-event-catalog/resolved-persistence-types/type-session-title: - en: 26d99fabe31f7fa3 - zh: 0a44b5c8f7f6488c + en: 5a42c1482248e385 + zh: c7ba7d071e4756de /session-persistence-event-catalog/resolved-persistence-types/type-session-title-llm-request: - en: bbbb345651600abf - zh: e3b29e05fecb136a + en: d88fd740ff167f04 + zh: fe6598a1bf4cd9bf /session-persistence-event-catalog/resolved-persistence-types/type-step-end: en: 7fc233c4a569dae2 zh: bc2b3fed4a397c00 @@ -2124,8 +2136,8 @@ en: 1484738718de5312 zh: 3e6fbe9c64068225 /session-persistence-event-catalog/resolved-persistence-types/type-text-delta: - en: 38a0279d2ba3a230 - zh: 42d7be8102d27995 + en: 5f30a603fab07135 + zh: 3b7e2076351a1473 /session-persistence-event-catalog/resolved-persistence-types/type-todo-write: en: 2fa7ba77598a95b4 zh: 50972b51d77e9155 @@ -2133,8 +2145,8 @@ en: 32f732b97739e4d2 zh: f288e48e356969c0 /session-persistence-event-catalog/resolved-persistence-types/type-tool-call-delta: - en: 5822c230b4880a6e - zh: e0b86bdee2834b24 + en: 0e907728f330a8c7 + zh: d9d1400d4c468ab2 /session-persistence-event-catalog/resolved-persistence-types/type-tool-workflow-agent-end: en: 8eb5e1eb95722bc7 zh: 8dd5980029600648 @@ -2166,11 +2178,11 @@ en: 1b045de96172be4b zh: 8a15c6f35b576b37 /session-persistence-event-catalog/resolved-persistence-types/type-usage: - en: ebb801c4444061fb - zh: f2d6531de88ee16e + en: a1d9300dd7a7b043 + zh: 3cb1e0e6834e9765 /session-persistence-event-catalog/resolved-persistence-types/type-user-message: - en: 536f875df13987d0 - zh: 857a381433a4217f + en: 44035d460a9d926b + zh: 8006b6dbfc58d5ae /session-persistence-event-catalog/resolved-persistence-types/type-web-deepseek-search-llm-request: en: 99c8837344178a47 zh: bf746f5678346596 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 995ba54784..4cc4550d40 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -23,7 +23,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover | `JsonlHeaderLine` | header | `18ee62b8900a4c3d046700f05d7a4d49d6cab2a660a020c87481d1603dd8bd4f` | [`HeaderLine`](#persistence-type-sha256-18ee62b8900a4c3d046700f05d7a4d49d6cab2a660a020c87481d1603dd8bd4f) | | `SessionEventEnvelope` | envelope | `5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc` | [`union (3 variants)`](#persistence-type-sha256-5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc) | | `event:agent-preset/selected` | event | `a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b` | [`{ type: "agent-preset/selected" }`](#persistence-type-sha256-a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b) | -| `event:agent/inbox/spliced` | event | `b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e` | [`{ type: "agent/inbox/spliced" }`](#persistence-type-sha256-b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e) | +| `event:agent/inbox/spliced` | event | `cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e` | [`{ type: "agent/inbox/spliced" }`](#persistence-type-sha256-cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e) | | `event:approval/asked` | event | `3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1` | [`{ type: "approval/asked" }`](#persistence-type-sha256-3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1) | | `event:approval/decided` | event | `bb1ab3d08f49a9f3b265f844cd78d5c49813062a7b34b54904b426f85d0ff6e3` | [`{ type: "approval/decided" }`](#persistence-type-sha256-bb1ab3d08f49a9f3b265f844cd78d5c49813062a7b34b54904b426f85d0ff6e3) | | `event:approval/policy` | event | `26718e15e7e395bce9642dba5bbe09b3b1a4ce2213d20d566cd9207d7fc5fb78` | [`{ type: "approval/policy" }`](#persistence-type-sha256-26718e15e7e395bce9642dba5bbe09b3b1a4ce2213d20d566cd9207d7fc5fb78) | @@ -36,7 +36,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover | `event:compaction/start` | event | `db874d463b0fdec77e9da1c4568f37cb70bd6596781eb93800db44fb8a116965` | [`{ type: "compaction/start" }`](#persistence-type-sha256-db874d463b0fdec77e9da1c4568f37cb70bd6596781eb93800db44fb8a116965) | | `event:compaction/summary` | event | `e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602` | [`{ type: "compaction/summary" }`](#persistence-type-sha256-e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602) | | `event:deliverables/presented` | event | `13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176` | [`{ type: "deliverables/presented" }`](#persistence-type-sha256-13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176) | -| `event:developer/message` | event | `5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be` | [`{ type: "developer/message" }`](#persistence-type-sha256-5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be) | +| `event:developer/message` | event | `70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f` | [`{ type: "developer/message" }`](#persistence-type-sha256-70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f) | | `event:feedback/message-delete` | event | `3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796` | [`{ type: "feedback/message-delete" }`](#persistence-type-sha256-3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796) | | `event:feedback/message-put` | event | `b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf` | [`{ type: "feedback/message-put" }`](#persistence-type-sha256-b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf) | | `event:feedback/record` | event | `b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8` | [`{ type: "feedback/record" }`](#persistence-type-sha256-b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8) | @@ -58,7 +58,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover | `event:session-log-deepseek/delivery-accepted` | event | `d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9` | [`{ type: "session-log-deepseek/delivery-accepted" }`](#persistence-type-sha256-d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9) | | `event:session/end-seed` | event | `5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e` | [`{ type: "session/end-seed" }`](#persistence-type-sha256-5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e) | | `event:session/title` | event | `1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5` | [`{ type: "session/title" }`](#persistence-type-sha256-1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5) | -| `event:session/title-llm-request` | event | `efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc) | +| `event:session/title-llm-request` | event | `2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c) | | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) | | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) | | `event:subagent-name/bound` | event | `2073e98f0c214cc431b1a9a027efe75d22190a8ed8fed2791b47c2b52dd32a57` | [`{ type: "subagent-name/bound" }`](#persistence-type-sha256-2073e98f0c214cc431b1a9a027efe75d22190a8ed8fed2791b47c2b52dd32a57) | @@ -81,7 +81,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover | `event:tool/result` | event | `7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397` | [`{ type: "tool/result" }`](#persistence-type-sha256-7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397) | | `event:turn/end` | event | `0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce` | [`{ type: "turn/end" }`](#persistence-type-sha256-0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce) | | `event:turn/start` | event | `aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8` | [`{ type: "turn/start" }`](#persistence-type-sha256-aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8) | -| `event:user/message` | event | `58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019` | [`{ type: "user/message" }`](#persistence-type-sha256-58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019) | +| `event:user/message` | event | `5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451` | [`{ type: "user/message" }`](#persistence-type-sha256-5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451) | | `event:web/deepseek-search-llm-request` | event | `0c556c9b9f2a96238a6b9bbb99e748206cbff2ed6203041c9571f04ae5802f52` | [`{ type: "web/deepseek-search-llm-request" }`](#persistence-type-sha256-0c556c9b9f2a96238a6b9bbb99e748206cbff2ed6203041c9571f04ae5802f52) | | `event:working-directory/change` | event | `124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3` | [`{ type: "working-directory/change" }`](#persistence-type-sha256-124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3) | | `event:workspace/changes` | event | `e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72` | [`{ type: "workspace/changes" }`](#persistence-type-sha256-e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72) | @@ -878,7 +878,7 @@ Source: [`packages/session/session-title/src/index.ts:77`](../packages/session/s Types: [SessionTitleLlmRequestEventData](subsystems/session-title.md) -Source: [`packages/session/session-title-llm/src/index.ts:57`](../packages/session/session-title-llm/src/index.ts) +Source: [`packages/session/session-title-llm/src/index.ts:63`](../packages/session/session-title-llm/src/index.ts) ### `session-log-deepseek/*` @@ -898,7 +898,7 @@ Source: [`packages/session/session-title-llm/src/index.ts:57`](../packages/sessi } ``` -Source: [`packages/session/session-log-deepseek/src/types.ts:81`](../packages/session/session-log-deepseek/src/types.ts) +Source: [`packages/session/session-log-deepseek/src/types.ts:96`](../packages/session/session-log-deepseek/src/types.ts) ### `step/*` @@ -2023,7 +2023,7 @@ SHA-256: `ebb768d85ec87fb68e42fc14fd7d8535b5ac11791b14d04c6770180f0a719bf8` SHA-256: `f311671e07bc7fa645a0b6597de9966b97147956565296ba76a36543801b66c5` -Sources: [`packages/llm/llm/src/types.ts:414`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:440`](../packages/llm/llm/src/types.ts) `"in-history"` @@ -2555,6 +2555,14 @@ SHA-256: `b765ee31033cea463863faf3fc6a0a1b85c47c6a2f13fe1ce833abe56105114b` `"set"` + + +### `"share-viewer"` + +SHA-256: `6ba7edb6447b6a3e7947dddf5e4116c1526000c4e62882a6d65edc67ba797c2c` + +`"share-viewer"` + ### `"skill-catalog"` @@ -3290,7 +3298,7 @@ Sources: [`packages/compaction/compaction/src/checkpoint.ts:22`](../packages/com SHA-256: `8064c03c87c357fd1575cb9395ce86e6dcbe2d275bf7717864a02cddf01827d5` -Sources: [`packages/llm/llm/src/types.ts:150`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:157`](../packages/llm/llm/src/types.ts) One of: @@ -3312,7 +3320,7 @@ One of: SHA-256: `7d65acf0a3a43a8f445ce5d3320b42eca492739fc931b2a7516bfb8368dc2c68` -Sources: [`packages/llm/llm/src/types.ts:148`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:155`](../packages/llm/llm/src/types.ts) One of: @@ -3399,7 +3407,7 @@ Sources: [`packages/web/web-search-deepseek/src/provider.ts:55`](../packages/web | `body` | required | [`{ max_tokens, messages, model, thinking?, … }`](#persistence-type-sha256-9c001ecb5e1d3c3894410db2a1e383842e5f8454fb52182338686158abc1b3ee) | | `endpoint` | required | `string` | - + @@ -3407,7 +3415,7 @@ Sources: [`packages/web/web-search-deepseek/src/provider.ts:55`](../packages/web ### `DeveloperMessage` -SHA-256: `7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616` +SHA-256: `64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428` Sources: [`packages/llm/llm/src/message.ts:157`](../packages/llm/llm/src/message.ts) @@ -3416,7 +3424,7 @@ Sources: [`packages/llm/llm/src/message.ts:157`](../packages/llm/llm/src/message | `content` | required | [`ContentBlock[]`](#persistence-type-sha256-b52f215a6cd691058a3413c12f161fa3b563a2f4895adb3df6f744ec4b0a6ef1) | | `id` | required | `string` | | `role` | required | `"developer"` | -| `source` | required | [`MessageSource`](#persistence-type-sha256-7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690) | +| `source` | required | [`MessageSource`](#persistence-type-sha256-7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a) | Source compatibility: `source` — `session-source-attribution` v1; `session.developer-message.source`; `kind`; `preserve`. @@ -3505,7 +3513,7 @@ Sources: [`packages/attachment/attachment/src/types.ts:39`](../packages/attachme SHA-256: `f2da0f27c1e6add59982c37b15e4a4912c5b33466859cce3b13d503600e24aef` -Sources: [`packages/llm/llm/src/types.ts:98`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:105`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -3522,7 +3530,7 @@ Sources: [`packages/llm/llm/src/types.ts:98`](../packages/llm/llm/src/types.ts) SHA-256: `5808e36c95355f0e745201b5db1b6bcec4ebf5adb75d3e82d7d59cc89635ab80` -Sources: [`packages/llm/llm/src/types.ts:165`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:172`](../packages/llm/llm/src/types.ts) | kind | Form property | Other required fields | Full definition | |---|---|---|---| @@ -3760,7 +3768,7 @@ Sources: [`packages/attachment/attachment/src/types.ts:11`](../packages/attachme SHA-256: `12d5808fac1996b9b3c2afa806e03022252ba2d7b88f835862ae1896591f60c7` -Sources: [`packages/llm/llm/src/types.ts:79`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:86`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -4068,7 +4076,7 @@ Sources: [`packages/llm/llm/src/call-config.ts:54`](../packages/llm/llm/src/call SHA-256: `5f2117d1856a5ab43c28371faa978ebfaa48f8c7d734ea3fc94842210df83dca` -Sources: [`packages/llm/llm/src/types.ts:41`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:48`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -4115,7 +4123,7 @@ Sources: [`packages/llm/llm-retry/src/types.ts:43`](../packages/llm/llm-retry/sr | `step` | required | `number` | | `turn` | required | `number` | - + @@ -4123,15 +4131,15 @@ Sources: [`packages/llm/llm-retry/src/types.ts:43`](../packages/llm/llm-retry/sr ### `Message` -SHA-256: `cda79b839d8cc0c7a7bd09dd067de04925f6e9037080d878b65aaa5a383f117c` +SHA-256: `c78b9097bfae83cd08f0a98a92730236ba80ac61d712046959e4fc7f28aa1f36` Sources: [`packages/llm/llm/src/message.ts:196`](../packages/llm/llm/src/message.ts) One of: - [`ToolResultMessage`](#persistence-type-sha256-4b259f7f8f0a44ad5e90b70a73553ced1df27012d126921d397ff403b6c86731) -- [`DeveloperMessage`](#persistence-type-sha256-7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616) -- [`UserMessage`](#persistence-type-sha256-b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69) +- [`DeveloperMessage`](#persistence-type-sha256-64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428) +- [`UserMessage`](#persistence-type-sha256-4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce) - [`SystemMessage`](#persistence-type-sha256-09f3f8dc417f278257202714132f98ba7b52957d7b558c4a04456603890eb363) - [`AssistantMessage`](#persistence-type-sha256-fa87537f4a9c1e25602990a8bf686b383e9e00352ec8946e16ae24ba7c1625be) @@ -4208,7 +4216,7 @@ One of: - `"negative"` - `"positive"` - + @@ -4216,7 +4224,7 @@ One of: ### `MessageSource` -SHA-256: `7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690` +SHA-256: `7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a` Sources: [`packages/llm/llm/src/message.ts:136`](../packages/llm/llm/src/message.ts) @@ -4293,7 +4301,7 @@ Sources: [`packages/llm/llm/src/message.ts:136`](../packages/llm/llm/src/message | `schedule` | `"snapshot"` | `sections`: [`ContextSnapshotSection[]`](#persistence-type-sha256-c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262) | [`{ kind: "schedule", form: "snapshot" }`](#persistence-type-sha256-28936c614bd4e7e2774806edcbb3cbfd3ee643ac1cbf0bbdff43d915505a8fe3) | | `schedule` | not declared | none | [`{ kind: "schedule" }`](#persistence-type-sha256-f29d63336e8266d80dd7baeab219436db86341304f6be1cd0edb36f5134c4a47) | | `session-reference` | `"recall"` | `references`: [`{ capturedFormatVersion?, capturedThroughSeq, compacted, inputIndex, … }[]`](#persistence-type-sha256-df843efd87c78cf8de98f8e0d0216956cd568d0d0e56a22c853663e274aa1a18); `version`: `1` | [`SessionReferenceSource`](#persistence-type-sha256-f56c5b59ca0161310c338d31dd16cf14287ccd602ff4181058df178c1c286d7f) | -| `skill-catalog` | `"catalog"` | `entries`: [`{ description, name }[]`](#persistence-type-sha256-aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba) | [`SkillCatalogSource`](#persistence-type-sha256-fc2ae6962f9f8801c2b1e414668e1e17cbb7544c4f39381198977a38bd10c093) | +| `skill-catalog` | `"catalog"` | `entries`: [`{ description, name }[]`](#persistence-type-sha256-aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba) | [`SkillCatalogSource`](#persistence-type-sha256-65d583e66518c5236015e0846470fb32efcf92375ed306aef14e50a9d2cd2099) | | `skill-invocation` | `"instructions"` | `name`: `string` | [`SkillInvocationSource`](#persistence-type-sha256-672c4aa2a9b736e3d6e5da6346d2e2ed5e3573f2d0baafa18e7407c9f3fee3db) | | `subagent-settled` | `"notice"` | `senderSessionId`: `string`; `summary`: `string` | [`SubagentSettledMessageSource`](#persistence-type-sha256-4e97c3d85c0fc817ee58873c38c25a2474abaaa0af4839311b50b68db3b8cf1a) | | `system-prompt` | not declared | none | [`SystemPromptMessageSource`](#persistence-type-sha256-65a8400e451e667e5b6e34df72ceb81fca8c12330330fa72083ad40279b189ad) | @@ -4328,7 +4336,7 @@ Sources: [`packages/llm/llm/src/message.ts:136`](../packages/llm/llm/src/message | `tool-jobs` | `"snapshot"` | `sections`: [`ContextSnapshotSection[]`](#persistence-type-sha256-c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262) | [`{ kind: "tool-jobs", form: "snapshot" }`](#persistence-type-sha256-c5228b7a55498d84f529591744a0ab26e0b93ade18a70a26db1377a1ecfa6b49) | | `tool-jobs` | not declared | none | [`{ kind: "tool-jobs" }`](#persistence-type-sha256-24ce31aa528272e59f21cd26da9eca08968bcc97529756a749bfdab71746d9c8) | | `tool-registry` | not declared | none | [`{ kind: "tool-registry" }`](#persistence-type-sha256-8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543) | -| `user` | not declared | `rpcId`: `string` | [`{ kind: "user" }`](#persistence-type-sha256-6dacb1584f2bfbe209dc6b6f578d51da6d55595f64d0e63c727c98f359278def) | +| `user` | not declared | `rpcId`: `string` | [`{ kind: "user" }`](#persistence-type-sha256-a4afec59b75aad5d13ef82d6931f35cc2d98918503916cf069355b77c5e42302) | | `user` | not declared | none | [`CommandSource`](#persistence-type-sha256-ada310bf0bdb8fed51f3b56ea63f6ea6b18bbd587f04fccb63a14ab0b2a24e05) | | `user-approval` | `"catalog"` | none | [`{ kind: "user-approval", form: "catalog" }`](#persistence-type-sha256-825ca23416b1ea9d81442afead5cf9229a6fa05842f042135cc3aa9710a6a2d8) | | `user-approval` | `"instructions"` | none | [`{ kind: "user-approval", form: "instructions" }`](#persistence-type-sha256-aa2bf9e82b9fdeb94a42af20031fffa30e4e23f01f4ac39757427d4c64c407f0) | @@ -4341,13 +4349,13 @@ Sources: [`packages/llm/llm/src/message.ts:136`](../packages/llm/llm/src/message | `webhook` | `"notice"` | `deliveryId`: `string`; `provider`: `string`; `ruleId`: `string`; `source`: `string`; `summary`: `string` | [`{ kind: "webhook", form: "notice" }`](#persistence-type-sha256-9edc162949abf93bd5ff049191b345454ba104f583937ce5580fb50f067d2b94) | | `working-directory` | not declared | none | [`{ kind: "working-directory" }`](#persistence-type-sha256-2235d957bf4b7c6cf959231d480f0ba1f3a6d72d82981493fb6c7c963021d3d5) | - + ### `Message[]` -SHA-256: `78b9204976ab9faaf133c3488b73d1dfb6f1a4bb6c0903e3473cd41a5e1e39e1` +SHA-256: `ff2cbb53582d1827b02622482246979942f59e07e0393b76a161251423549e72` -Array of [`Message`](#persistence-type-sha256-cda79b839d8cc0c7a7bd09dd067de04925f6e9037080d878b65aaa5a383f117c). +Array of [`Message`](#persistence-type-sha256-c78b9097bfae83cd08f0a98a92730236ba80ac61d712046959e4fc7f28aa1f36). @@ -4465,22 +4473,6 @@ SHA-256: `1d9cb3caa96100b18b1911fa3ff8c751ef6992971a03c5f4d9aefc1a0004a345` Array of [`PresentedFile`](#persistence-type-sha256-b8fc636a2121df9d8423c242e03c9d23b7ab7c6fdce00e45746932c60b730f97). - - - - - - -### `Principal` - -SHA-256: `deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5` - -Sources: [`packages/typert/protocol/src/types.ts:457`](../packages/typert/protocol/src/types.ts) · [`packages/typert/protocol/src/types.ts:461`](../packages/typert/protocol/src/types.ts) - -| Property | Presence | Type | -|---|---|---| -| `kind` | required | `"owner"` | - @@ -4535,7 +4527,7 @@ Sources: [`packages/core/tool-executor-ptc/src/types.ts:12`](../packages/core/to SHA-256: `814d9434e1ddf9078612b3b34322f26e9363b469213335007f7e9ba7fee9464e` -Sources: [`packages/llm/llm/src/types.ts:68`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:75`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -4552,7 +4544,7 @@ Sources: [`packages/llm/llm/src/types.ts:68`](../packages/llm/llm/src/types.ts) SHA-256: `0acd94fe8794574c9ae72c7855ee16d29c546096d4af760d16d1225385764555` -Sources: [`packages/llm/llm/src/types.ts:448`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:474`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -4731,7 +4723,7 @@ Sources: [`packages/session/session-title/src/types.ts:41`](../packages/session/ | `source` | required | [`SessionTitleSource`](#persistence-type-sha256-30d5a537b296685770b1241c4b4bbde19d5a31ff81aa23df73fab5e90b8fc65f) | | `title` | required | `string` | - + @@ -4739,15 +4731,15 @@ Sources: [`packages/session/session-title/src/types.ts:41`](../packages/session/ ### `SessionTitleLlmRequestEventData` -SHA-256: `a3e299483348f27a4787a36bb3f29cd86024c65336abc10bb3d687468302c4cf` +SHA-256: `7ff62f6599c083ceb5a0d7a8940ff85ba80dc1d7ddd6ba9339903e93f74cba54` -Sources: [`packages/session/session-title-llm/src/index.ts:37`](../packages/session/session-title-llm/src/index.ts) +Sources: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts) | Property | Presence | Type | |---|---|---| | `maxTokens` | required | `number` | | `messageSeqs` | required | [`number[]`](#persistence-type-sha256-5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78) | -| `messages` | required | [`Message[]`](#persistence-type-sha256-78b9204976ab9faaf133c3488b73d1dfb6f1a4bb6c0903e3473cd41a5e1e39e1) | +| `messages` | required | [`Message[]`](#persistence-type-sha256-ff2cbb53582d1827b02622482246979942f59e07e0393b76a161251423549e72) | | `reasoningEffort` | optional | `string` | | `route` | required | [`SessionTitleModelIdentity`](#persistence-type-sha256-07e1a58c58b593f507b8e7f25723bb0aa42baae6e00f5ecfddf28cb1e64d3235) | | `system` | required | `string` | @@ -4800,7 +4792,25 @@ Sources: [`packages/session/session-title/src/types.ts:28`](../packages/session/ | `provider` | not declared | `provider`: `string` | [`{ kind: "provider" }`](#persistence-type-sha256-b81e9de81a481b24e1e1f9adf038bfc59e57b4f35ce62f8f1e45284186f4f812) | | `user` | not declared | none | [`CommandSource`](#persistence-type-sha256-ada310bf0bdb8fed51f3b56ea63f6ea6b18bbd587f04fccb63a14ab0b2a24e05) | - + + + + + + +### `ShareViewerPrincipal` + +SHA-256: `4d60dddaa65d3da8d4cd014d85ce3d2c2875664dd0433e331d8e9d395289686b` + +Sources: [`packages/experimental/liveshare/src/host/viewer-principal.ts:24`](../packages/experimental/liveshare/src/host/viewer-principal.ts) + +| Property | Presence | Type | +|---|---|---| +| `actor` | required | [`{ displayName?, providerId, subjectId, tenantId }`](#persistence-type-sha256-0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623) | +| `kind` | required | `"share-viewer"` | +| `shareId` | required | `string` | + + @@ -4808,7 +4818,7 @@ Sources: [`packages/session/session-title/src/types.ts:28`](../packages/session/ ### `SkillCatalogSource` -SHA-256: `fc2ae6962f9f8801c2b1e414668e1e17cbb7544c4f39381198977a38bd10c093` +SHA-256: `65d583e66518c5236015e0846470fb32efcf92375ed306aef14e50a9d2cd2099` Sources: [`packages/skill/tool-skill/src/index.ts:35`](../packages/skill/tool-skill/src/index.ts) @@ -4816,6 +4826,7 @@ Sources: [`packages/skill/tool-skill/src/index.ts:35`](../packages/skill/tool-sk |---|---|---| | `entries` | required | [`{ description, name }[]`](#persistence-type-sha256-aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba) | | `form` | required | `"catalog"` | +| `incomplete` | optional | `true` | | `kind` | required | `"skill-catalog"` | | `update` | optional | `true` | @@ -4847,7 +4858,7 @@ Sources: [`packages/skill/skill/src/index.ts:146`](../packages/skill/skill/src/i SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180` -Sources: [`packages/llm/llm/src/types.ts:470`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:496`](../packages/llm/llm/src/types.ts) One of: @@ -5100,7 +5111,7 @@ One of: SHA-256: `4e887768586528565381dadbddee6cef555874148089f4579e0b4b1ad096fc9c` -Sources: [`packages/llm/llm/src/types.ts:62`](../packages/llm/llm/src/types.ts) · [`packages/web/web-search-deepseek/src/provider.ts:66`](../packages/web/web-search-deepseek/src/provider.ts) +Sources: [`packages/llm/llm/src/types.ts:69`](../packages/llm/llm/src/types.ts) · [`packages/web/web-search-deepseek/src/provider.ts:66`](../packages/web/web-search-deepseek/src/provider.ts) | Property | Presence | Type | |---|---|---| @@ -5142,7 +5153,7 @@ Array of [`TodoItem`](#persistence-type-sha256-a99f76fd149051c363f960bfeeb5b9509 SHA-256: `fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394` -Sources: [`packages/llm/llm/src/types.ts:175`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:182`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -5163,7 +5174,7 @@ Sources: [`packages/llm/llm/src/types.ts:175`](../packages/llm/llm/src/types.ts) SHA-256: `8e611bf46821e5003a1605a73560a6f56388295149d449dfe2142d5ec335f29c` -Sources: [`packages/llm/llm/src/types.ts:115`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:122`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -5181,7 +5192,7 @@ Sources: [`packages/llm/llm/src/types.ts:115`](../packages/llm/llm/src/types.ts) SHA-256: `c1f0f17b6493b85db6453bb30e01b208d703731b25bc1e68e5d4fc72eea9cdea` -Sources: [`packages/llm/llm/src/types.ts:105`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:112`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -5217,7 +5228,7 @@ Sources: [`packages/llm/llm/src/message.ts:29`](../packages/llm/llm/src/message. SHA-256: `43e311235aa537df1bacdd92d144df8a952337a76e9ac892cdf670f1a797bad8` -Sources: [`packages/llm/llm/src/types.ts:127`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:134`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -5272,7 +5283,7 @@ Sources: [`packages/llm/llm/src/message.ts:173`](../packages/llm/llm/src/message SHA-256: `66ba70f6f068da443f969a0b947a013c3addd776b9b60a0a393759c19825e9a2` -Sources: [`packages/llm/llm/src/types.ts:491`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:517`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -5403,7 +5414,7 @@ Sources: [`packages/core/session/src/types.ts:238`](../packages/core/session/src | `interrupted` | not declared | none | [`{ kind: "interrupted" }`](#persistence-type-sha256-56b7c047694875a843ba020dfea3c8380d54ae4ff88ab349e72004dc21e07c23) | | `max-tokens` | not declared | none | [`{ kind: "max-tokens" }`](#persistence-type-sha256-ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7) | - + @@ -5411,7 +5422,7 @@ Sources: [`packages/core/session/src/types.ts:238`](../packages/core/session/src ### `UserMessage` -SHA-256: `b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69` +SHA-256: `4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce` Sources: [`packages/llm/llm/src/message.ts:162`](../packages/llm/llm/src/message.ts) @@ -5420,19 +5431,19 @@ Sources: [`packages/llm/llm/src/message.ts:162`](../packages/llm/llm/src/message | `content` | required | [`ContentBlock[]`](#persistence-type-sha256-b52f215a6cd691058a3413c12f161fa3b563a2f4895adb3df6f744ec4b0a6ef1) | | `id` | required | `string` | | `role` | required | `"user"` | -| `source` | required | [`MessageSource`](#persistence-type-sha256-7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690) | +| `source` | required | [`MessageSource`](#persistence-type-sha256-7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a) | Source compatibility: `source` — `session-source-attribution` v1; `session.user-message.source`; `kind`; `preserve`. Attribution-only additions: `action-cards`, `tmux-context`, `user-question-reply`, `working-directory`. - + ### `UserMessage[]` -SHA-256: `5d00abf938272f22eb47199e9d40801e8d8ec4c88e2b138b15aa2a5a5bf87520` +SHA-256: `7c203f3d4dfa6638ff2601247cc7ca5d46731d2c614aa61217475b9eb1fbd0b3` -Array of [`UserMessage`](#persistence-type-sha256-b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69). +Array of [`UserMessage`](#persistence-type-sha256-4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce). @@ -5624,7 +5635,7 @@ Array of `number`. SHA-256: `4cd48f3e5108bd6ebedf7301c3638839b8b2b9db8dbd493974177fbdeb91a01b` -Sources: [`packages/api/session-controller/src/types.ts:380`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:21`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/webhook/src/brand.ts:12`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:6`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:9`](../packages/experimental/webhook/src/brand.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/jobs/jobs/src/brand.ts:19`](../packages/jobs/jobs/src/brand.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:14`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts) +Sources: [`packages/api/session-controller/src/types.ts:388`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:21`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/webhook/src/brand.ts:12`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:6`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:9`](../packages/experimental/webhook/src/brand.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/jobs/jobs/src/brand.ts:19`](../packages/jobs/jobs/src/brand.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:14`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts) `string` @@ -5696,6 +5707,17 @@ One of: - `"fork"` - `"fresh"` + + +### `union (2 variants)` + +SHA-256: `824a4aad44a54e245c67196817d67946734a2dc0eee0b0b6834a5b2a6ef352ce` + +| kind | Form property | Other required fields | Full definition | +|---|---|---|---| +| `owner` | not declared | none | [`{ kind: "owner" }`](#persistence-type-sha256-deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5) | +| `share-viewer` | not declared | `actor`: [`{ displayName?, providerId, subjectId, tenantId }`](#persistence-type-sha256-0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623); `shareId`: `string` | [`ShareViewerPrincipal`](#persistence-type-sha256-4d60dddaa65d3da8d4cd014d85ce3d2c2875664dd0433e331d8e9d395289686b) | + ### `union (2 variants)` @@ -6202,7 +6224,7 @@ Sources: [`packages/llm/llm-retry/src/types.ts:30`](../packages/llm/llm-retry/sr SHA-256: `83079c8a3f733ac3fa603eefa0fbb4737ca4d8b69e7e2e7298b60f9ac4098693` -Sources: [`packages/skill/tool-skill/src/index.ts:41`](../packages/skill/tool-skill/src/index.ts) +Sources: [`packages/skill/tool-skill/src/index.ts:43`](../packages/skill/tool-skill/src/index.ts) | Property | Presence | Type | |---|---|---| @@ -6233,6 +6255,21 @@ Sources: [`packages/experimental/hook-protocol/src/types.ts:19`](../packages/exp | `point` | required | `string` | | `turn` | required | `number` | + + +### `{ displayName?, providerId, subjectId, tenantId }` + +SHA-256: `0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623` + +Sources: [`packages/experimental/liveshare/src/host/viewer-principal.ts:29`](../packages/experimental/liveshare/src/host/viewer-principal.ts) + +| Property | Presence | Type | +|---|---|---| +| `displayName` | optional | `string` | +| `providerId` | required | `string` | +| `subjectId` | required | `string` | +| `tenantId` | required | `string` | + ### `{ end, start }` @@ -6295,7 +6332,7 @@ Sources: [`packages/core/session/src/types.ts:383`](../packages/core/session/src SHA-256: `8e31bb958e9b015e6f8407eaade32217068159e816f3cc99c3ad76eb889732e0` -Sources: [`packages/llm/llm/src/types.ts:160`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:167`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -6308,7 +6345,7 @@ Sources: [`packages/llm/llm/src/types.ts:160`](../packages/llm/llm/src/types.ts) SHA-256: `693f4952fb5565da96c06bace8924b098ac2fbc915fde0ff8019701183abc057` -Sources: [`packages/llm/llm/src/types.ts:161`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:168`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -6329,18 +6366,18 @@ Sources: [`packages/core/session/src/types.ts:398`](../packages/core/session/src | `reason` | required | [`RequestHeaderReason`](#persistence-type-sha256-530da6c0267813bb4511af72883cc518834e624e3b3220a7062955fd57a788a6) | | `startsSeries` | optional | `true` | - + ### `{ headerSeq?, message, step, turn }` -SHA-256: `7404c6123fdaa591474a37979a5a8ae70d1387af7c9f09bfe568b218935a974d` +SHA-256: `53d4f8256bc58109468ea358ac54d437760cd765012360cafe72a401e6a41d4a` Sources: [`packages/core/session/src/types.ts:317`](../packages/core/session/src/types.ts) | Property | Presence | Type | |---|---|---| | `headerSeq` | optional | `number` | -| `message` | required | [`DeveloperMessage`](#persistence-type-sha256-7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616) | +| `message` | required | [`DeveloperMessage`](#persistence-type-sha256-64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428) | | `step` | required | `number` | | `turn` | required | `number` | @@ -6424,17 +6461,17 @@ Sources: [`packages/core/session/src/types.ts:435`](../packages/core/session/src |---|---|---| | `inherited` | optional | `true` | - + ### `{ inserted, outcome?, removedCount?, start, … }` -SHA-256: `b2a948a5340a9341fa3bab99507c7090c5b0456de72ec28b5b157b8df3f1d640` +SHA-256: `d4d960185026266ed7bd127be1e252234689e8b4890c7c2677a644ba58f35401` Sources: [`packages/core/agent/src/types.ts:110`](../packages/core/agent/src/types.ts) | Property | Presence | Type | |---|---|---| -| `inserted` | required | [`UserMessage[]`](#persistence-type-sha256-5d00abf938272f22eb47199e9d40801e8d8ec4c88e2b138b15aa2a5a5bf87520) | +| `inserted` | required | [`UserMessage[]`](#persistence-type-sha256-7c203f3d4dfa6638ff2601247cc7ca5d46731d2c614aa61217475b9eb1fbd0b3) | | `outcome` | optional | `"canceled"` | | `removedCount` | optional | `number` | | `start` | required | `number` | @@ -6904,7 +6941,7 @@ Sources: [`packages/core/session/src/types.ts:201`](../packages/core/session/src SHA-256: `ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7` -Sources: [`packages/core/session/src/types.ts:220`](../packages/core/session/src/types.ts) · [`packages/llm/llm/src/types.ts:159`](../packages/llm/llm/src/types.ts) +Sources: [`packages/core/session/src/types.ts:220`](../packages/core/session/src/types.ts) · [`packages/llm/llm/src/types.ts:166`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -6988,6 +7025,18 @@ SHA-256: `52c6113cb0e53f345324bf84f01928bea5d5df57ee80bc0dd65407b8bc5a3734` | `kind` | required | `"model-selection"` | | `sections` | required | [`ContextSnapshotSection[]`](#persistence-type-sha256-c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262) | + + +### `{ kind: "owner" }` + +SHA-256: `deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5` + +Sources: [`packages/typert/protocol/src/types.ts:457`](../packages/typert/protocol/src/types.ts) + +| Property | Presence | Type | +|---|---|---| +| `kind` | required | `"owner"` | + ### `{ kind: "parent" }` @@ -7344,7 +7393,7 @@ SHA-256: `28936c614bd4e7e2774806edcbb3cbfd3ee643ac1cbf0bbdff43d915505a8fe3` SHA-256: `1d76406cbb2ddadb0dbbb51e9d8bc6cf678fed455cf8eb512f36f7c86d37a62f` -Sources: [`packages/llm/llm/src/types.ts:157`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:164`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -7512,7 +7561,7 @@ SHA-256: `49dab019d00e8c26f27ad2ccff7b604d69e323ae4d17e0d2a7b6b8a830b1ade2` SHA-256: `287211846beea1eccb5f9acee00d20388a38fcb2e95858fa2332d6f58529379a` -Sources: [`packages/llm/llm/src/types.ts:158`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:165`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -7686,19 +7735,19 @@ Sources: [`packages/core/tools/src/index.ts:28`](../packages/core/tools/src/inde |---|---|---| | `kind` | required | `"tool-registry"` | - + ### `{ kind: "user" }` -SHA-256: `6dacb1584f2bfbe209dc6b6f578d51da6d55595f64d0e63c727c98f359278def` +SHA-256: `a4afec59b75aad5d13ef82d6931f35cc2d98918503916cf069355b77c5e42302` -Sources: [`packages/api/session-controller/src/types.ts:389`](../packages/api/session-controller/src/types.ts) +Sources: [`packages/api/session-controller/src/types.ts:397`](../packages/api/session-controller/src/types.ts) | Property | Presence | Type | |---|---|---| | `clientTimeZone` | optional | `string` | | `kind` | required | `"user"` | -| `principal` | optional | [`Principal`](#persistence-type-sha256-deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5) | +| `principal` | optional | [`union (2 variants)`](#persistence-type-sha256-824a4aad44a54e245c67196817d67946734a2dc0eee0b0b6834a5b2a6ef352ce) | | `rpcId` | required | `string` | @@ -7966,7 +8015,7 @@ Sources: [`packages/web/web-search-deepseek/src/provider.ts:64`](../packages/web SHA-256: `8bb8c3751a6ce64b61aba1ec7ae798c00a5803c4d868a0430873216c6569ed52` -Sources: [`packages/session/session-log-deepseek/src/types.ts:81`](../packages/session/session-log-deepseek/src/types.ts) +Sources: [`packages/session/session-log-deepseek/src/types.ts:96`](../packages/session/session-log-deepseek/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -8081,17 +8130,17 @@ SHA-256: `a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b` | `time` | required | `number` | | `type` | required | `"agent-preset/selected"` | - + ### `{ type: "agent/inbox/spliced" }` -SHA-256: `b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e` +SHA-256: `cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e` | Property | Presence | Type | |---|---|---| -| `data` | required | [`{ inserted, outcome?, removedCount?, start, … }`](#persistence-type-sha256-b2a948a5340a9341fa3bab99507c7090c5b0456de72ec28b5b157b8df3f1d640) | +| `data` | required | [`{ inserted, outcome?, removedCount?, start, … }`](#persistence-type-sha256-d4d960185026266ed7bd127be1e252234689e8b4890c7c2677a644ba58f35401) | | `ignorable` | optional | `true` | | `seq` | required | `number` | | `time` | required | `number` | @@ -8184,7 +8233,7 @@ SHA-256: `1033093edd0db80ff410e00830b523405e00bb0c7684948e531ff65095799625` SHA-256: `d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d` -Sources: [`packages/llm/llm/src/types.ts:475`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:501`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -8198,7 +8247,7 @@ Sources: [`packages/llm/llm/src/types.ts:475`](../packages/llm/llm/src/types.ts) SHA-256: `3bec87f9e6ab3da03346f49923d3c51621debc0159df68605e543c3b2a026f90` -Sources: [`packages/llm/llm/src/types.ts:471`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:497`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -8332,17 +8381,17 @@ SHA-256: `13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176` | `time` | required | `number` | | `type` | required | `"deliverables/presented"` | - + ### `{ type: "developer/message" }` -SHA-256: `5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be` +SHA-256: `70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f` | Property | Presence | Type | |---|---|---| -| `data` | required | [`{ headerSeq?, message, step, turn }`](#persistence-type-sha256-7404c6123fdaa591474a37979a5a8ae70d1387af7c9f09bfe568b218935a974d) | +| `data` | required | [`{ headerSeq?, message, step, turn }`](#persistence-type-sha256-53d4f8256bc58109468ea358ac54d437760cd765012360cafe72a401e6a41d4a) | | `ignorable` | optional | `true` | | `seq` | required | `number` | | `sourceEventSeqs` | optional | [`number[]`](#persistence-type-sha256-5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78) | @@ -8416,7 +8465,7 @@ SHA-256: `b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8` SHA-256: `a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1` -Sources: [`packages/llm/llm/src/types.ts:477`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:503`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -8622,7 +8671,7 @@ Sources: [`packages/llm/llm/src/assistant-stream.ts:28`](../packages/llm/llm/src SHA-256: `2abb711460e6238d851c30f3e4bdd87a2aa1887ee70575b3d3b7b25610673095` -Sources: [`packages/llm/llm/src/types.ts:473`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:499`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -8742,17 +8791,17 @@ SHA-256: `1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5` | `time` | required | `number` | | `type` | required | `"session/title"` | - + ### `{ type: "session/title-llm-request" }` -SHA-256: `efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc` +SHA-256: `2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c` | Property | Presence | Type | |---|---|---| -| `data` | required | [`SessionTitleLlmRequestEventData`](#persistence-type-sha256-a3e299483348f27a4787a36bb3f29cd86024c65336abc10bb3d687468302c4cf) | +| `data` | required | [`SessionTitleLlmRequestEventData`](#persistence-type-sha256-7ff62f6599c083ceb5a0d7a8940ff85ba80dc1d7ddd6ba9339903e93f74cba54) | | `ignorable` | optional | `true` | | `seq` | required | `number` | | `time` | required | `number` | @@ -8958,7 +9007,7 @@ Sources: [`packages/llm/llm/src/assistant-stream.ts:21`](../packages/llm/llm/src SHA-256: `95080295115fbd83544520ba247b68a03790131f6a2eac323d388758cb542f65` -Sources: [`packages/llm/llm/src/types.ts:472`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:498`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -9006,7 +9055,7 @@ Sources: [`packages/llm/llm/src/assistant-stream.ts:35`](../packages/llm/llm/src SHA-256: `88a610b831be6d92612a464be5c7d0b88ec24d97bd299837bf74bf7672183c9a` -Sources: [`packages/llm/llm/src/types.ts:474`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:500`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| @@ -9184,24 +9233,24 @@ SHA-256: `aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8` SHA-256: `f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515` -Sources: [`packages/llm/llm/src/types.ts:476`](../packages/llm/llm/src/types.ts) +Sources: [`packages/llm/llm/src/types.ts:502`](../packages/llm/llm/src/types.ts) | Property | Presence | Type | |---|---|---| | `type` | required | `"usage"` | | `usage` | required | [`TokenUsage`](#persistence-type-sha256-fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394) | - + ### `{ type: "user/message" }` -SHA-256: `58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019` +SHA-256: `5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451` | Property | Presence | Type | |---|---|---| -| `data` | required | [`UserMessage`](#persistence-type-sha256-b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69) | +| `data` | required | [`UserMessage`](#persistence-type-sha256-4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce) | | `ignorable` | optional | `true` | | `seq` | required | `number` | | `sourceEventSeqs` | optional | [`number[]`](#persistence-type-sha256-5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78) | diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index 69540e0000..ee58ed99d2 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -25,7 +25,7 @@ | `JsonlHeaderLine` | header | `18ee62b8900a4c3d046700f05d7a4d49d6cab2a660a020c87481d1603dd8bd4f` | [`HeaderLine`](#persistence-type-sha256-18ee62b8900a4c3d046700f05d7a4d49d6cab2a660a020c87481d1603dd8bd4f) | | `SessionEventEnvelope` | envelope | `5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc` | [`union (3 variants)`](#persistence-type-sha256-5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc) | | `event:agent-preset/selected` | event | `a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b` | [`{ type: "agent-preset/selected" }`](#persistence-type-sha256-a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b) | -| `event:agent/inbox/spliced` | event | `b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e` | [`{ type: "agent/inbox/spliced" }`](#persistence-type-sha256-b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e) | +| `event:agent/inbox/spliced` | event | `cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e` | [`{ type: "agent/inbox/spliced" }`](#persistence-type-sha256-cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e) | | `event:approval/asked` | event | `3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1` | [`{ type: "approval/asked" }`](#persistence-type-sha256-3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1) | | `event:approval/decided` | event | `bb1ab3d08f49a9f3b265f844cd78d5c49813062a7b34b54904b426f85d0ff6e3` | [`{ type: "approval/decided" }`](#persistence-type-sha256-bb1ab3d08f49a9f3b265f844cd78d5c49813062a7b34b54904b426f85d0ff6e3) | | `event:approval/policy` | event | `26718e15e7e395bce9642dba5bbe09b3b1a4ce2213d20d566cd9207d7fc5fb78` | [`{ type: "approval/policy" }`](#persistence-type-sha256-26718e15e7e395bce9642dba5bbe09b3b1a4ce2213d20d566cd9207d7fc5fb78) | @@ -38,7 +38,7 @@ | `event:compaction/start` | event | `db874d463b0fdec77e9da1c4568f37cb70bd6596781eb93800db44fb8a116965` | [`{ type: "compaction/start" }`](#persistence-type-sha256-db874d463b0fdec77e9da1c4568f37cb70bd6596781eb93800db44fb8a116965) | | `event:compaction/summary` | event | `e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602` | [`{ type: "compaction/summary" }`](#persistence-type-sha256-e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602) | | `event:deliverables/presented` | event | `13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176` | [`{ type: "deliverables/presented" }`](#persistence-type-sha256-13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176) | -| `event:developer/message` | event | `5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be` | [`{ type: "developer/message" }`](#persistence-type-sha256-5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be) | +| `event:developer/message` | event | `70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f` | [`{ type: "developer/message" }`](#persistence-type-sha256-70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f) | | `event:feedback/message-delete` | event | `3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796` | [`{ type: "feedback/message-delete" }`](#persistence-type-sha256-3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796) | | `event:feedback/message-put` | event | `b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf` | [`{ type: "feedback/message-put" }`](#persistence-type-sha256-b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf) | | `event:feedback/record` | event | `b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8` | [`{ type: "feedback/record" }`](#persistence-type-sha256-b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8) | @@ -60,7 +60,7 @@ | `event:session-log-deepseek/delivery-accepted` | event | `d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9` | [`{ type: "session-log-deepseek/delivery-accepted" }`](#persistence-type-sha256-d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9) | | `event:session/end-seed` | event | `5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e` | [`{ type: "session/end-seed" }`](#persistence-type-sha256-5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e) | | `event:session/title` | event | `1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5` | [`{ type: "session/title" }`](#persistence-type-sha256-1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5) | -| `event:session/title-llm-request` | event | `efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc) | +| `event:session/title-llm-request` | event | `2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c) | | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) | | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) | | `event:subagent-name/bound` | event | `2073e98f0c214cc431b1a9a027efe75d22190a8ed8fed2791b47c2b52dd32a57` | [`{ type: "subagent-name/bound" }`](#persistence-type-sha256-2073e98f0c214cc431b1a9a027efe75d22190a8ed8fed2791b47c2b52dd32a57) | @@ -83,7 +83,7 @@ | `event:tool/result` | event | `7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397` | [`{ type: "tool/result" }`](#persistence-type-sha256-7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397) | | `event:turn/end` | event | `0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce` | [`{ type: "turn/end" }`](#persistence-type-sha256-0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce) | | `event:turn/start` | event | `aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8` | [`{ type: "turn/start" }`](#persistence-type-sha256-aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8) | -| `event:user/message` | event | `58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019` | [`{ type: "user/message" }`](#persistence-type-sha256-58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019) | +| `event:user/message` | event | `5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451` | [`{ type: "user/message" }`](#persistence-type-sha256-5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451) | | `event:web/deepseek-search-llm-request` | event | `0c556c9b9f2a96238a6b9bbb99e748206cbff2ed6203041c9571f04ae5802f52` | [`{ type: "web/deepseek-search-llm-request" }`](#persistence-type-sha256-0c556c9b9f2a96238a6b9bbb99e748206cbff2ed6203041c9571f04ae5802f52) | | `event:working-directory/change` | event | `124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3` | [`{ type: "working-directory/change" }`](#persistence-type-sha256-124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3) | | `event:workspace/changes` | event | `e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72` | [`{ type: "workspace/changes" }`](#persistence-type-sha256-e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72) | @@ -880,7 +880,7 @@ export type SessionEvent = { 类型：[SessionTitleLlmRequestEventData](subsystems/session-title.zh.md) -来源：[`packages/session/session-title-llm/src/index.ts:57`](../packages/session/session-title-llm/src/index.ts) +来源：[`packages/session/session-title-llm/src/index.ts:63`](../packages/session/session-title-llm/src/index.ts) ### `session-log-deepseek/*` @@ -900,7 +900,7 @@ export type SessionEvent = { } ``` -来源：[`packages/session/session-log-deepseek/src/types.ts:81`](../packages/session/session-log-deepseek/src/types.ts) +来源：[`packages/session/session-log-deepseek/src/types.ts:96`](../packages/session/session-log-deepseek/src/types.ts) ### `step/*` @@ -2025,7 +2025,7 @@ SHA-256: `ebb768d85ec87fb68e42fc14fd7d8535b5ac11791b14d04c6770180f0a719bf8` SHA-256: `f311671e07bc7fa645a0b6597de9966b97147956565296ba76a36543801b66c5` -来源：[`packages/llm/llm/src/types.ts:414`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:440`](../packages/llm/llm/src/types.ts) `"in-history"` @@ -2557,6 +2557,14 @@ SHA-256: `b765ee31033cea463863faf3fc6a0a1b85c47c6a2f13fe1ce833abe56105114b` `"set"` + + +### `"share-viewer"` + +SHA-256: `6ba7edb6447b6a3e7947dddf5e4116c1526000c4e62882a6d65edc67ba797c2c` + +`"share-viewer"` + ### `"skill-catalog"` @@ -3292,7 +3300,7 @@ SHA-256: `31907de9563751822af6d9be02bafaf26faa098bbd1cb412524134d577cc1648` SHA-256: `8064c03c87c357fd1575cb9395ce86e6dcbe2d275bf7717864a02cddf01827d5` -来源：[`packages/llm/llm/src/types.ts:150`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:157`](../packages/llm/llm/src/types.ts) 以下类型之一： @@ -3314,7 +3322,7 @@ SHA-256: `8064c03c87c357fd1575cb9395ce86e6dcbe2d275bf7717864a02cddf01827d5` SHA-256: `7d65acf0a3a43a8f445ce5d3320b42eca492739fc931b2a7516bfb8368dc2c68` -来源：[`packages/llm/llm/src/types.ts:148`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:155`](../packages/llm/llm/src/types.ts) 以下类型之一： @@ -3401,7 +3409,7 @@ SHA-256: `abd6ca62a5ab166553848324a23fef90eed7f59c8021bd63e7ea5bc6fd666b0c` | `body` | 必需 | [`{ max_tokens, messages, model, thinking?, … }`](#persistence-type-sha256-9c001ecb5e1d3c3894410db2a1e383842e5f8454fb52182338686158abc1b3ee) | | `endpoint` | 必需 | `string` | - + @@ -3409,7 +3417,7 @@ SHA-256: `abd6ca62a5ab166553848324a23fef90eed7f59c8021bd63e7ea5bc6fd666b0c` ### `DeveloperMessage` -SHA-256: `7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616` +SHA-256: `64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428` 来源：[`packages/llm/llm/src/message.ts:157`](../packages/llm/llm/src/message.ts) @@ -3418,7 +3426,7 @@ SHA-256: `7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616` | `content` | 必需 | [`ContentBlock[]`](#persistence-type-sha256-b52f215a6cd691058a3413c12f161fa3b563a2f4895adb3df6f744ec4b0a6ef1) | | `id` | 必需 | `string` | | `role` | 必需 | `"developer"` | -| `source` | 必需 | [`MessageSource`](#persistence-type-sha256-7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690) | +| `source` | 必需 | [`MessageSource`](#persistence-type-sha256-7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a) | 消息源兼容策略：`source` — `session-source-attribution` v1; `session.developer-message.source`; `kind`; `preserve`. @@ -3507,7 +3515,7 @@ SHA-256: `f19bee84bf3d20904553cdcd57465232bc1c2a194f54c4d195292ba0487223a6` SHA-256: `f2da0f27c1e6add59982c37b15e4a4912c5b33466859cce3b13d503600e24aef` -来源：[`packages/llm/llm/src/types.ts:98`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:105`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -3524,7 +3532,7 @@ SHA-256: `f2da0f27c1e6add59982c37b15e4a4912c5b33466859cce3b13d503600e24aef` SHA-256: `5808e36c95355f0e745201b5db1b6bcec4ebf5adb75d3e82d7d59cc89635ab80` -来源：[`packages/llm/llm/src/types.ts:165`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:172`](../packages/llm/llm/src/types.ts) | kind | form 属性 | 其他必需字段 | 完整定义 | |---|---|---|---| @@ -3762,7 +3770,7 @@ SHA-256: `b0b0eb1b16490f6bee135b2377e8f8c39227974c799ad7d49ff418af23ecbc35` SHA-256: `12d5808fac1996b9b3c2afa806e03022252ba2d7b88f835862ae1896591f60c7` -来源：[`packages/llm/llm/src/types.ts:79`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:86`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -4070,7 +4078,7 @@ SHA-256: `326a9bfda27dda5882fb3cbe6e715df41dae2298fdae3d66437457268a665693` SHA-256: `5f2117d1856a5ab43c28371faa978ebfaa48f8c7d734ea3fc94842210df83dca` -来源：[`packages/llm/llm/src/types.ts:41`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:48`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -4117,7 +4125,7 @@ SHA-256: `6f72ece8f317cd080c4f20a93f1bf709965f5b81ac4669528f5a023191cfcf20` | `step` | 必需 | `number` | | `turn` | 必需 | `number` | - + @@ -4125,15 +4133,15 @@ SHA-256: `6f72ece8f317cd080c4f20a93f1bf709965f5b81ac4669528f5a023191cfcf20` ### `Message` -SHA-256: `cda79b839d8cc0c7a7bd09dd067de04925f6e9037080d878b65aaa5a383f117c` +SHA-256: `c78b9097bfae83cd08f0a98a92730236ba80ac61d712046959e4fc7f28aa1f36` 来源：[`packages/llm/llm/src/message.ts:196`](../packages/llm/llm/src/message.ts) 以下类型之一： - [`ToolResultMessage`](#persistence-type-sha256-4b259f7f8f0a44ad5e90b70a73553ced1df27012d126921d397ff403b6c86731) -- [`DeveloperMessage`](#persistence-type-sha256-7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616) -- [`UserMessage`](#persistence-type-sha256-b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69) +- [`DeveloperMessage`](#persistence-type-sha256-64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428) +- [`UserMessage`](#persistence-type-sha256-4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce) - [`SystemMessage`](#persistence-type-sha256-09f3f8dc417f278257202714132f98ba7b52957d7b558c4a04456603890eb363) - [`AssistantMessage`](#persistence-type-sha256-fa87537f4a9c1e25602990a8bf686b383e9e00352ec8946e16ae24ba7c1625be) @@ -4210,7 +4218,7 @@ SHA-256: `390eed1028aba02774f14408647acec10ec5516e97d4f15ecde2b9989d5a69f2` - `"negative"` - `"positive"` - + @@ -4218,7 +4226,7 @@ SHA-256: `390eed1028aba02774f14408647acec10ec5516e97d4f15ecde2b9989d5a69f2` ### `MessageSource` -SHA-256: `7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690` +SHA-256: `7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a` 来源：[`packages/llm/llm/src/message.ts:136`](../packages/llm/llm/src/message.ts) @@ -4295,7 +4303,7 @@ SHA-256: `7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690` | `schedule` | `"snapshot"` | `sections`: [`ContextSnapshotSection[]`](#persistence-type-sha256-c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262) | [`{ kind: "schedule", form: "snapshot" }`](#persistence-type-sha256-28936c614bd4e7e2774806edcbb3cbfd3ee643ac1cbf0bbdff43d915505a8fe3) | | `schedule` | 未声明 | 无 | [`{ kind: "schedule" }`](#persistence-type-sha256-f29d63336e8266d80dd7baeab219436db86341304f6be1cd0edb36f5134c4a47) | | `session-reference` | `"recall"` | `references`: [`{ capturedFormatVersion?, capturedThroughSeq, compacted, inputIndex, … }[]`](#persistence-type-sha256-df843efd87c78cf8de98f8e0d0216956cd568d0d0e56a22c853663e274aa1a18); `version`: `1` | [`SessionReferenceSource`](#persistence-type-sha256-f56c5b59ca0161310c338d31dd16cf14287ccd602ff4181058df178c1c286d7f) | -| `skill-catalog` | `"catalog"` | `entries`: [`{ description, name }[]`](#persistence-type-sha256-aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba) | [`SkillCatalogSource`](#persistence-type-sha256-fc2ae6962f9f8801c2b1e414668e1e17cbb7544c4f39381198977a38bd10c093) | +| `skill-catalog` | `"catalog"` | `entries`: [`{ description, name }[]`](#persistence-type-sha256-aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba) | [`SkillCatalogSource`](#persistence-type-sha256-65d583e66518c5236015e0846470fb32efcf92375ed306aef14e50a9d2cd2099) | | `skill-invocation` | `"instructions"` | `name`: `string` | [`SkillInvocationSource`](#persistence-type-sha256-672c4aa2a9b736e3d6e5da6346d2e2ed5e3573f2d0baafa18e7407c9f3fee3db) | | `subagent-settled` | `"notice"` | `senderSessionId`: `string`; `summary`: `string` | [`SubagentSettledMessageSource`](#persistence-type-sha256-4e97c3d85c0fc817ee58873c38c25a2474abaaa0af4839311b50b68db3b8cf1a) | | `system-prompt` | 未声明 | 无 | [`SystemPromptMessageSource`](#persistence-type-sha256-65a8400e451e667e5b6e34df72ceb81fca8c12330330fa72083ad40279b189ad) | @@ -4330,7 +4338,7 @@ SHA-256: `7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690` | `tool-jobs` | `"snapshot"` | `sections`: [`ContextSnapshotSection[]`](#persistence-type-sha256-c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262) | [`{ kind: "tool-jobs", form: "snapshot" }`](#persistence-type-sha256-c5228b7a55498d84f529591744a0ab26e0b93ade18a70a26db1377a1ecfa6b49) | | `tool-jobs` | 未声明 | 无 | [`{ kind: "tool-jobs" }`](#persistence-type-sha256-24ce31aa528272e59f21cd26da9eca08968bcc97529756a749bfdab71746d9c8) | | `tool-registry` | 未声明 | 无 | [`{ kind: "tool-registry" }`](#persistence-type-sha256-8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543) | -| `user` | 未声明 | `rpcId`: `string` | [`{ kind: "user" }`](#persistence-type-sha256-6dacb1584f2bfbe209dc6b6f578d51da6d55595f64d0e63c727c98f359278def) | +| `user` | 未声明 | `rpcId`: `string` | [`{ kind: "user" }`](#persistence-type-sha256-a4afec59b75aad5d13ef82d6931f35cc2d98918503916cf069355b77c5e42302) | | `user` | 未声明 | 无 | [`CommandSource`](#persistence-type-sha256-ada310bf0bdb8fed51f3b56ea63f6ea6b18bbd587f04fccb63a14ab0b2a24e05) | | `user-approval` | `"catalog"` | 无 | [`{ kind: "user-approval", form: "catalog" }`](#persistence-type-sha256-825ca23416b1ea9d81442afead5cf9229a6fa05842f042135cc3aa9710a6a2d8) | | `user-approval` | `"instructions"` | 无 | [`{ kind: "user-approval", form: "instructions" }`](#persistence-type-sha256-aa2bf9e82b9fdeb94a42af20031fffa30e4e23f01f4ac39757427d4c64c407f0) | @@ -4343,13 +4351,13 @@ SHA-256: `7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690` | `webhook` | `"notice"` | `deliveryId`: `string`; `provider`: `string`; `ruleId`: `string`; `source`: `string`; `summary`: `string` | [`{ kind: "webhook", form: "notice" }`](#persistence-type-sha256-9edc162949abf93bd5ff049191b345454ba104f583937ce5580fb50f067d2b94) | | `working-directory` | 未声明 | 无 | [`{ kind: "working-directory" }`](#persistence-type-sha256-2235d957bf4b7c6cf959231d480f0ba1f3a6d72d82981493fb6c7c963021d3d5) | - + ### `Message[]` -SHA-256: `78b9204976ab9faaf133c3488b73d1dfb6f1a4bb6c0903e3473cd41a5e1e39e1` +SHA-256: `ff2cbb53582d1827b02622482246979942f59e07e0393b76a161251423549e72` -[`Message`](#persistence-type-sha256-cda79b839d8cc0c7a7bd09dd067de04925f6e9037080d878b65aaa5a383f117c) 的数组。 +[`Message`](#persistence-type-sha256-c78b9097bfae83cd08f0a98a92730236ba80ac61d712046959e4fc7f28aa1f36) 的数组。 @@ -4467,22 +4475,6 @@ SHA-256: `1d9cb3caa96100b18b1911fa3ff8c751ef6992971a03c5f4d9aefc1a0004a345` [`PresentedFile`](#persistence-type-sha256-b8fc636a2121df9d8423c242e03c9d23b7ab7c6fdce00e45746932c60b730f97) 的数组。 - - - - - - -### `Principal` - -SHA-256: `deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5` - -来源：[`packages/typert/protocol/src/types.ts:457`](../packages/typert/protocol/src/types.ts) · [`packages/typert/protocol/src/types.ts:461`](../packages/typert/protocol/src/types.ts) - -| 属性 | 存在性 | 类型 | -|---|---|---| -| `kind` | 必需 | `"owner"` | - @@ -4537,7 +4529,7 @@ SHA-256: `2fe5026daf14bd4ff2b7bfb7cf9791c302d9cbba06802178b6dfec00b892698f` SHA-256: `814d9434e1ddf9078612b3b34322f26e9363b469213335007f7e9ba7fee9464e` -来源：[`packages/llm/llm/src/types.ts:68`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:75`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -4554,7 +4546,7 @@ SHA-256: `814d9434e1ddf9078612b3b34322f26e9363b469213335007f7e9ba7fee9464e` SHA-256: `0acd94fe8794574c9ae72c7855ee16d29c546096d4af760d16d1225385764555` -来源：[`packages/llm/llm/src/types.ts:448`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:474`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -4733,7 +4725,7 @@ SHA-256: `b56f6a885da3dc394c69a3e3cc5c0cfc4da15601b63fda4989eee8f40efc5be4` | `source` | 必需 | [`SessionTitleSource`](#persistence-type-sha256-30d5a537b296685770b1241c4b4bbde19d5a31ff81aa23df73fab5e90b8fc65f) | | `title` | 必需 | `string` | - + @@ -4741,15 +4733,15 @@ SHA-256: `b56f6a885da3dc394c69a3e3cc5c0cfc4da15601b63fda4989eee8f40efc5be4` ### `SessionTitleLlmRequestEventData` -SHA-256: `a3e299483348f27a4787a36bb3f29cd86024c65336abc10bb3d687468302c4cf` +SHA-256: `7ff62f6599c083ceb5a0d7a8940ff85ba80dc1d7ddd6ba9339903e93f74cba54` -来源：[`packages/session/session-title-llm/src/index.ts:37`](../packages/session/session-title-llm/src/index.ts) +来源：[`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts) | 属性 | 存在性 | 类型 | |---|---|---| | `maxTokens` | 必需 | `number` | | `messageSeqs` | 必需 | [`number[]`](#persistence-type-sha256-5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78) | -| `messages` | 必需 | [`Message[]`](#persistence-type-sha256-78b9204976ab9faaf133c3488b73d1dfb6f1a4bb6c0903e3473cd41a5e1e39e1) | +| `messages` | 必需 | [`Message[]`](#persistence-type-sha256-ff2cbb53582d1827b02622482246979942f59e07e0393b76a161251423549e72) | | `reasoningEffort` | 可选 | `string` | | `route` | 必需 | [`SessionTitleModelIdentity`](#persistence-type-sha256-07e1a58c58b593f507b8e7f25723bb0aa42baae6e00f5ecfddf28cb1e64d3235) | | `system` | 必需 | `string` | @@ -4802,7 +4794,25 @@ SHA-256: `30d5a537b296685770b1241c4b4bbde19d5a31ff81aa23df73fab5e90b8fc65f` | `provider` | 未声明 | `provider`: `string` | [`{ kind: "provider" }`](#persistence-type-sha256-b81e9de81a481b24e1e1f9adf038bfc59e57b4f35ce62f8f1e45284186f4f812) | | `user` | 未声明 | 无 | [`CommandSource`](#persistence-type-sha256-ada310bf0bdb8fed51f3b56ea63f6ea6b18bbd587f04fccb63a14ab0b2a24e05) | - + + + + + + +### `ShareViewerPrincipal` + +SHA-256: `4d60dddaa65d3da8d4cd014d85ce3d2c2875664dd0433e331d8e9d395289686b` + +来源：[`packages/experimental/liveshare/src/host/viewer-principal.ts:24`](../packages/experimental/liveshare/src/host/viewer-principal.ts) + +| 属性 | 存在性 | 类型 | +|---|---|---| +| `actor` | 必需 | [`{ displayName?, providerId, subjectId, tenantId }`](#persistence-type-sha256-0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623) | +| `kind` | 必需 | `"share-viewer"` | +| `shareId` | 必需 | `string` | + + @@ -4810,7 +4820,7 @@ SHA-256: `30d5a537b296685770b1241c4b4bbde19d5a31ff81aa23df73fab5e90b8fc65f` ### `SkillCatalogSource` -SHA-256: `fc2ae6962f9f8801c2b1e414668e1e17cbb7544c4f39381198977a38bd10c093` +SHA-256: `65d583e66518c5236015e0846470fb32efcf92375ed306aef14e50a9d2cd2099` 来源：[`packages/skill/tool-skill/src/index.ts:35`](../packages/skill/tool-skill/src/index.ts) @@ -4818,6 +4828,7 @@ SHA-256: `fc2ae6962f9f8801c2b1e414668e1e17cbb7544c4f39381198977a38bd10c093` |---|---|---| | `entries` | 必需 | [`{ description, name }[]`](#persistence-type-sha256-aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba) | | `form` | 必需 | `"catalog"` | +| `incomplete` | 可选 | `true` | | `kind` | 必需 | `"skill-catalog"` | | `update` | 可选 | `true` | @@ -4849,7 +4860,7 @@ SHA-256: `672c4aa2a9b736e3d6e5da6346d2e2ed5e3573f2d0baafa18e7407c9f3fee3db` SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180` -来源：[`packages/llm/llm/src/types.ts:470`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:496`](../packages/llm/llm/src/types.ts) 以下类型之一： @@ -5102,7 +5113,7 @@ SHA-256: `b2d2a01e51341a3bfec809198952c8c830a7899f4cb6ecd3c1dc0b5d9a2af943` SHA-256: `4e887768586528565381dadbddee6cef555874148089f4579e0b4b1ad096fc9c` -来源：[`packages/llm/llm/src/types.ts:62`](../packages/llm/llm/src/types.ts) · [`packages/web/web-search-deepseek/src/provider.ts:66`](../packages/web/web-search-deepseek/src/provider.ts) +来源：[`packages/llm/llm/src/types.ts:69`](../packages/llm/llm/src/types.ts) · [`packages/web/web-search-deepseek/src/provider.ts:66`](../packages/web/web-search-deepseek/src/provider.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -5144,7 +5155,7 @@ SHA-256: `4b7ddaf3710b88ff9b8df66304f5f97bf03688fd19730eedc2e9535203c820ea` SHA-256: `fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394` -来源：[`packages/llm/llm/src/types.ts:175`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:182`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -5165,7 +5176,7 @@ SHA-256: `fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394` SHA-256: `8e611bf46821e5003a1605a73560a6f56388295149d449dfe2142d5ec335f29c` -来源：[`packages/llm/llm/src/types.ts:115`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:122`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -5183,7 +5194,7 @@ SHA-256: `8e611bf46821e5003a1605a73560a6f56388295149d449dfe2142d5ec335f29c` SHA-256: `c1f0f17b6493b85db6453bb30e01b208d703731b25bc1e68e5d4fc72eea9cdea` -来源：[`packages/llm/llm/src/types.ts:105`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:112`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -5219,7 +5230,7 @@ SHA-256: `d9c462b9f62fdd3efc76a44b9524dc8781f6b91cd9c7e584b17d971defafebab` SHA-256: `43e311235aa537df1bacdd92d144df8a952337a76e9ac892cdf670f1a797bad8` -来源：[`packages/llm/llm/src/types.ts:127`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:134`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -5274,7 +5285,7 @@ SHA-256: `4b259f7f8f0a44ad5e90b70a73553ced1df27012d126921d397ff403b6c86731` SHA-256: `66ba70f6f068da443f969a0b947a013c3addd776b9b60a0a393759c19825e9a2` -来源：[`packages/llm/llm/src/types.ts:491`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:517`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -5405,7 +5416,7 @@ SHA-256: `f1687f982fa3d41ef29e159feed154ecd13af4dd209acaee16038f223f2e9402` | `interrupted` | 未声明 | 无 | [`{ kind: "interrupted" }`](#persistence-type-sha256-56b7c047694875a843ba020dfea3c8380d54ae4ff88ab349e72004dc21e07c23) | | `max-tokens` | 未声明 | 无 | [`{ kind: "max-tokens" }`](#persistence-type-sha256-ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7) | - + @@ -5413,7 +5424,7 @@ SHA-256: `f1687f982fa3d41ef29e159feed154ecd13af4dd209acaee16038f223f2e9402` ### `UserMessage` -SHA-256: `b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69` +SHA-256: `4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce` 来源：[`packages/llm/llm/src/message.ts:162`](../packages/llm/llm/src/message.ts) @@ -5422,19 +5433,19 @@ SHA-256: `b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69` | `content` | 必需 | [`ContentBlock[]`](#persistence-type-sha256-b52f215a6cd691058a3413c12f161fa3b563a2f4895adb3df6f744ec4b0a6ef1) | | `id` | 必需 | `string` | | `role` | 必需 | `"user"` | -| `source` | 必需 | [`MessageSource`](#persistence-type-sha256-7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690) | +| `source` | 必需 | [`MessageSource`](#persistence-type-sha256-7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a) | 消息源兼容策略：`source` — `session-source-attribution` v1; `session.user-message.source`; `kind`; `preserve`. 仅表示归属的新增 kind：`action-cards`, `tmux-context`, `user-question-reply`, `working-directory`. - + ### `UserMessage[]` -SHA-256: `5d00abf938272f22eb47199e9d40801e8d8ec4c88e2b138b15aa2a5a5bf87520` +SHA-256: `7c203f3d4dfa6638ff2601247cc7ca5d46731d2c614aa61217475b9eb1fbd0b3` -[`UserMessage`](#persistence-type-sha256-b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69) 的数组。 +[`UserMessage`](#persistence-type-sha256-4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce) 的数组。 @@ -5626,7 +5637,7 @@ SHA-256: `5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78` SHA-256: `4cd48f3e5108bd6ebedf7301c3638839b8b2b9db8dbd493974177fbdeb91a01b` -来源：[`packages/api/session-controller/src/types.ts:380`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:21`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/webhook/src/brand.ts:12`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:6`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:9`](../packages/experimental/webhook/src/brand.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/jobs/jobs/src/brand.ts:19`](../packages/jobs/jobs/src/brand.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:14`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts) +来源：[`packages/api/session-controller/src/types.ts:388`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:21`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/webhook/src/brand.ts:12`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:6`](../packages/experimental/webhook/src/brand.ts) · [`packages/experimental/webhook/src/brand.ts:9`](../packages/experimental/webhook/src/brand.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/jobs/jobs/src/brand.ts:19`](../packages/jobs/jobs/src/brand.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:14`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts) `string` @@ -5698,6 +5709,17 @@ SHA-256: `50cf02d875f8a1f1411f4a6fbcffab9120ccef5f74a47331fbf29480e5f68f48` - `"fork"` - `"fresh"` + + +### `union (2 variants)` + +SHA-256: `824a4aad44a54e245c67196817d67946734a2dc0eee0b0b6834a5b2a6ef352ce` + +| kind | form 属性 | 其他必需字段 | 完整定义 | +|---|---|---|---| +| `owner` | 未声明 | 无 | [`{ kind: "owner" }`](#persistence-type-sha256-deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5) | +| `share-viewer` | 未声明 | `actor`: [`{ displayName?, providerId, subjectId, tenantId }`](#persistence-type-sha256-0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623); `shareId`: `string` | [`ShareViewerPrincipal`](#persistence-type-sha256-4d60dddaa65d3da8d4cd014d85ce3d2c2875664dd0433e331d8e9d395289686b) | + ### `union (2 variants)` @@ -6204,7 +6226,7 @@ SHA-256: `374fdd68aee5ff844e378c0cbdd961d247a0f22e4ade0bb03d800cd2a46a2b8b` SHA-256: `83079c8a3f733ac3fa603eefa0fbb4737ca4d8b69e7e2e7298b60f9ac4098693` -来源：[`packages/skill/tool-skill/src/index.ts:41`](../packages/skill/tool-skill/src/index.ts) +来源：[`packages/skill/tool-skill/src/index.ts:43`](../packages/skill/tool-skill/src/index.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -6235,6 +6257,21 @@ SHA-256: `119abe2b9c0b2f46ecb31d82b9acba4d4b30e049f655e2475e8b4ae12d5a9e25` | `point` | 必需 | `string` | | `turn` | 必需 | `number` | + + +### `{ displayName?, providerId, subjectId, tenantId }` + +SHA-256: `0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623` + +来源：[`packages/experimental/liveshare/src/host/viewer-principal.ts:29`](../packages/experimental/liveshare/src/host/viewer-principal.ts) + +| 属性 | 存在性 | 类型 | +|---|---|---| +| `displayName` | 可选 | `string` | +| `providerId` | 必需 | `string` | +| `subjectId` | 必需 | `string` | +| `tenantId` | 必需 | `string` | + ### `{ end, start }` @@ -6297,7 +6334,7 @@ SHA-256: `5302e763151277614b97e77f00e3b326694c6c1247b916a20503c344dc970777` SHA-256: `8e31bb958e9b015e6f8407eaade32217068159e816f3cc99c3ad76eb889732e0` -来源：[`packages/llm/llm/src/types.ts:160`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:167`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -6310,7 +6347,7 @@ SHA-256: `8e31bb958e9b015e6f8407eaade32217068159e816f3cc99c3ad76eb889732e0` SHA-256: `693f4952fb5565da96c06bace8924b098ac2fbc915fde0ff8019701183abc057` -来源：[`packages/llm/llm/src/types.ts:161`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:168`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -6331,18 +6368,18 @@ SHA-256: `ad0c38a0adb82a94c925456df41586d9b5f9202fca18593eae2213d4445b4585` | `reason` | 必需 | [`RequestHeaderReason`](#persistence-type-sha256-530da6c0267813bb4511af72883cc518834e624e3b3220a7062955fd57a788a6) | | `startsSeries` | 可选 | `true` | - + ### `{ headerSeq?, message, step, turn }` -SHA-256: `7404c6123fdaa591474a37979a5a8ae70d1387af7c9f09bfe568b218935a974d` +SHA-256: `53d4f8256bc58109468ea358ac54d437760cd765012360cafe72a401e6a41d4a` 来源：[`packages/core/session/src/types.ts:317`](../packages/core/session/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| | `headerSeq` | 可选 | `number` | -| `message` | 必需 | [`DeveloperMessage`](#persistence-type-sha256-7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616) | +| `message` | 必需 | [`DeveloperMessage`](#persistence-type-sha256-64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428) | | `step` | 必需 | `number` | | `turn` | 必需 | `number` | @@ -6426,17 +6463,17 @@ SHA-256: `17d1afb770d9941936130996da00dc86782cfef731d8d6526162c301256a4ac3` |---|---|---| | `inherited` | 可选 | `true` | - + ### `{ inserted, outcome?, removedCount?, start, … }` -SHA-256: `b2a948a5340a9341fa3bab99507c7090c5b0456de72ec28b5b157b8df3f1d640` +SHA-256: `d4d960185026266ed7bd127be1e252234689e8b4890c7c2677a644ba58f35401` 来源：[`packages/core/agent/src/types.ts:110`](../packages/core/agent/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| -| `inserted` | 必需 | [`UserMessage[]`](#persistence-type-sha256-5d00abf938272f22eb47199e9d40801e8d8ec4c88e2b138b15aa2a5a5bf87520) | +| `inserted` | 必需 | [`UserMessage[]`](#persistence-type-sha256-7c203f3d4dfa6638ff2601247cc7ca5d46731d2c614aa61217475b9eb1fbd0b3) | | `outcome` | 可选 | `"canceled"` | | `removedCount` | 可选 | `number` | | `start` | 必需 | `number` | @@ -6906,7 +6943,7 @@ SHA-256: `eaa71be0fbf0f702df8ea6c11d0aa2f9782263d45a10d0fb14eda662f4bfe04c` SHA-256: `ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7` -来源：[`packages/core/session/src/types.ts:220`](../packages/core/session/src/types.ts) · [`packages/llm/llm/src/types.ts:159`](../packages/llm/llm/src/types.ts) +来源：[`packages/core/session/src/types.ts:220`](../packages/core/session/src/types.ts) · [`packages/llm/llm/src/types.ts:166`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -6990,6 +7027,18 @@ SHA-256: `52c6113cb0e53f345324bf84f01928bea5d5df57ee80bc0dd65407b8bc5a3734` | `kind` | 必需 | `"model-selection"` | | `sections` | 必需 | [`ContextSnapshotSection[]`](#persistence-type-sha256-c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262) | + + +### `{ kind: "owner" }` + +SHA-256: `deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5` + +来源：[`packages/typert/protocol/src/types.ts:457`](../packages/typert/protocol/src/types.ts) + +| 属性 | 存在性 | 类型 | +|---|---|---| +| `kind` | 必需 | `"owner"` | + ### `{ kind: "parent" }` @@ -7346,7 +7395,7 @@ SHA-256: `28936c614bd4e7e2774806edcbb3cbfd3ee643ac1cbf0bbdff43d915505a8fe3` SHA-256: `1d76406cbb2ddadb0dbbb51e9d8bc6cf678fed455cf8eb512f36f7c86d37a62f` -来源：[`packages/llm/llm/src/types.ts:157`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:164`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -7514,7 +7563,7 @@ SHA-256: `49dab019d00e8c26f27ad2ccff7b604d69e323ae4d17e0d2a7b6b8a830b1ade2` SHA-256: `287211846beea1eccb5f9acee00d20388a38fcb2e95858fa2332d6f58529379a` -来源：[`packages/llm/llm/src/types.ts:158`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:165`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -7688,19 +7737,19 @@ SHA-256: `8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543` |---|---|---| | `kind` | 必需 | `"tool-registry"` | - + ### `{ kind: "user" }` -SHA-256: `6dacb1584f2bfbe209dc6b6f578d51da6d55595f64d0e63c727c98f359278def` +SHA-256: `a4afec59b75aad5d13ef82d6931f35cc2d98918503916cf069355b77c5e42302` -来源：[`packages/api/session-controller/src/types.ts:389`](../packages/api/session-controller/src/types.ts) +来源：[`packages/api/session-controller/src/types.ts:397`](../packages/api/session-controller/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| | `clientTimeZone` | 可选 | `string` | | `kind` | 必需 | `"user"` | -| `principal` | 可选 | [`Principal`](#persistence-type-sha256-deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5) | +| `principal` | 可选 | [`union (2 variants)`](#persistence-type-sha256-824a4aad44a54e245c67196817d67946734a2dc0eee0b0b6834a5b2a6ef352ce) | | `rpcId` | 必需 | `string` | @@ -7968,7 +8017,7 @@ SHA-256: `9a2a9029f8d7ede05336980d8342737557f487b913bfd28853d0ab5214600ab5` SHA-256: `8bb8c3751a6ce64b61aba1ec7ae798c00a5803c4d868a0430873216c6569ed52` -来源：[`packages/session/session-log-deepseek/src/types.ts:81`](../packages/session/session-log-deepseek/src/types.ts) +来源：[`packages/session/session-log-deepseek/src/types.ts:96`](../packages/session/session-log-deepseek/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -8083,17 +8132,17 @@ SHA-256: `a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b` | `time` | 必需 | `number` | | `type` | 必需 | `"agent-preset/selected"` | - + ### `{ type: "agent/inbox/spliced" }` -SHA-256: `b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e` +SHA-256: `cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e` | 属性 | 存在性 | 类型 | |---|---|---| -| `data` | 必需 | [`{ inserted, outcome?, removedCount?, start, … }`](#persistence-type-sha256-b2a948a5340a9341fa3bab99507c7090c5b0456de72ec28b5b157b8df3f1d640) | +| `data` | 必需 | [`{ inserted, outcome?, removedCount?, start, … }`](#persistence-type-sha256-d4d960185026266ed7bd127be1e252234689e8b4890c7c2677a644ba58f35401) | | `ignorable` | 可选 | `true` | | `seq` | 必需 | `number` | | `time` | 必需 | `number` | @@ -8186,7 +8235,7 @@ SHA-256: `1033093edd0db80ff410e00830b523405e00bb0c7684948e531ff65095799625` SHA-256: `d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d` -来源：[`packages/llm/llm/src/types.ts:475`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:501`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -8200,7 +8249,7 @@ SHA-256: `d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d` SHA-256: `3bec87f9e6ab3da03346f49923d3c51621debc0159df68605e543c3b2a026f90` -来源：[`packages/llm/llm/src/types.ts:471`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:497`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -8334,17 +8383,17 @@ SHA-256: `13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176` | `time` | 必需 | `number` | | `type` | 必需 | `"deliverables/presented"` | - + ### `{ type: "developer/message" }` -SHA-256: `5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be` +SHA-256: `70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f` | 属性 | 存在性 | 类型 | |---|---|---| -| `data` | 必需 | [`{ headerSeq?, message, step, turn }`](#persistence-type-sha256-7404c6123fdaa591474a37979a5a8ae70d1387af7c9f09bfe568b218935a974d) | +| `data` | 必需 | [`{ headerSeq?, message, step, turn }`](#persistence-type-sha256-53d4f8256bc58109468ea358ac54d437760cd765012360cafe72a401e6a41d4a) | | `ignorable` | 可选 | `true` | | `seq` | 必需 | `number` | | `sourceEventSeqs` | 可选 | [`number[]`](#persistence-type-sha256-5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78) | @@ -8418,7 +8467,7 @@ SHA-256: `b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8` SHA-256: `a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1` -来源：[`packages/llm/llm/src/types.ts:477`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:503`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -8624,7 +8673,7 @@ SHA-256: `71bb3254ec8f1e491ce63b762a7b5f18709de23aa4e8abcc8b886f4b6ce051dd` SHA-256: `2abb711460e6238d851c30f3e4bdd87a2aa1887ee70575b3d3b7b25610673095` -来源：[`packages/llm/llm/src/types.ts:473`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:499`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -8744,17 +8793,17 @@ SHA-256: `1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5` | `time` | 必需 | `number` | | `type` | 必需 | `"session/title"` | - + ### `{ type: "session/title-llm-request" }` -SHA-256: `efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc` +SHA-256: `2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c` | 属性 | 存在性 | 类型 | |---|---|---| -| `data` | 必需 | [`SessionTitleLlmRequestEventData`](#persistence-type-sha256-a3e299483348f27a4787a36bb3f29cd86024c65336abc10bb3d687468302c4cf) | +| `data` | 必需 | [`SessionTitleLlmRequestEventData`](#persistence-type-sha256-7ff62f6599c083ceb5a0d7a8940ff85ba80dc1d7ddd6ba9339903e93f74cba54) | | `ignorable` | 可选 | `true` | | `seq` | 必需 | `number` | | `time` | 必需 | `number` | @@ -8960,7 +9009,7 @@ SHA-256: `e72269f931559e901e5e8fe1cfcbd0669fb795f43cc038ff39fba62f60403c33` SHA-256: `95080295115fbd83544520ba247b68a03790131f6a2eac323d388758cb542f65` -来源：[`packages/llm/llm/src/types.ts:472`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:498`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -9008,7 +9057,7 @@ SHA-256: `3860b4757d512a2869be833acb0faf834335b1b056bf3f83df5474dce95f8fa6` SHA-256: `88a610b831be6d92612a464be5c7d0b88ec24d97bd299837bf74bf7672183c9a` -来源：[`packages/llm/llm/src/types.ts:474`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:500`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| @@ -9186,24 +9235,24 @@ SHA-256: `aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8` SHA-256: `f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515` -来源：[`packages/llm/llm/src/types.ts:476`](../packages/llm/llm/src/types.ts) +来源：[`packages/llm/llm/src/types.ts:502`](../packages/llm/llm/src/types.ts) | 属性 | 存在性 | 类型 | |---|---|---| | `type` | 必需 | `"usage"` | | `usage` | 必需 | [`TokenUsage`](#persistence-type-sha256-fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394) | - + ### `{ type: "user/message" }` -SHA-256: `58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019` +SHA-256: `5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451` | 属性 | 存在性 | 类型 | |---|---|---| -| `data` | 必需 | [`UserMessage`](#persistence-type-sha256-b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69) | +| `data` | 必需 | [`UserMessage`](#persistence-type-sha256-4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce) | | `ignorable` | 可选 | `true` | | `seq` | 必需 | `number` | | `sourceEventSeqs` | 可选 | [`number[]`](#persistence-type-sha256-5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78) | diff --git a/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.i18n.yaml b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.i18n.yaml new file mode 100644 index 0000000000..4202182528 --- /dev/null +++ b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.i18n.yaml @@ -0,0 +1,28 @@ +# Bilingual-pair consistency record for 2026-10-13-liveshare-share-viewer-principal.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/persistence-changes/2026-10-13-liveshare-share-viewer-principal.md +/: + en: 3d5a424ae7d7e46b + zh: c22a8e4a62d8cc1a +/2026-10-13-liveshare-share-viewer-principal: + en: 9b8097ab5922733e + zh: e52f33004c75f18f +/2026-10-13-liveshare-share-viewer-principal/summary: + en: 32551ff4ee358694 + zh: f6cfc403bed4f780 +/2026-10-13-liveshare-share-viewer-principal/table-of-contents: + en: 6cf314a069ceb451 + zh: 9adff678e9ecab3b +/2026-10-13-liveshare-share-viewer-principal/declaration: + en: 6907136f28e48c90 + zh: 02f8298485f3d8e7 +/2026-10-13-liveshare-share-viewer-principal/compatibility: + en: 3c4faef3cc5010bb + zh: 051485cd767ec6bc +/2026-10-13-liveshare-share-viewer-principal/verification: + en: 427079a2393d0ffe + zh: 17249b4e0fc0faeb +/2026-10-13-liveshare-share-viewer-principal/dev-note: + en: b75c8458928b72b9 + zh: 003ba4e17b4b5269 diff --git a/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.md b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.md new file mode 100644 index 0000000000..a22251e96d --- /dev/null +++ b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.md @@ -0,0 +1,60 @@ +--- +description: "Records a persistence type transition and its compatibility acknowledgement." +kind: persistence-change +--- + +# 2026-10-13-liveshare-share-viewer-principal + +English | [中文](2026-10-13-liveshare-share-viewer-principal.zh.md) + +## Summary + +Adds the LiveShare share-viewer principal, including the Relay-asserted display name when available, to the user-rpc message source of prompts a share reader submits. + +## Table of Contents + +- [Declaration](#declaration) +- [Compatibility](#compatibility) +- [Verification](#verification) +- [Dev Note](#dev-note) + + +## Declaration + +```yaml persistence-change +schemaVersion: 1 +id: 2026-10-13-liveshare-share-viewer-principal +baseline: false +changes: + - root: "event:agent/inbox/spliced" + previous: "2026-10-25-skill-catalog-incomplete" + after: "cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e" + decision: same-version + - root: "event:developer/message" + previous: "2026-10-25-skill-catalog-incomplete" + after: "70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f" + decision: same-version + - root: "event:session/title-llm-request" + previous: "2026-10-25-skill-catalog-incomplete" + after: "2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c" + decision: same-version + - root: "event:user/message" + previous: "2026-10-25-skill-catalog-incomplete" + after: "5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451" + decision: same-version +``` + + +## Compatibility + +The share-viewer variant is written only for a prompt that a LiveShare share reader's Peer submits; owner prompts still omit principal, so their sources and every existing Session log are unchanged. The value carries the share id and the Relay-asserted provider, tenant, and subject ids. It also carries an optional display name when the Relay asserts one, for attribution only; credentials and avatars are never persisted, and authorization still uses the identity triple. Readers that do not know the optional field keep showing the durable subject id. The LiveShare host consumes it in two places: the `agent/pre-step` admission check re-reads the Relay's grant for every entering message whose principal is a share viewer, and rejects the step when that grant no longer holds; the same step records, in memory for that turn only, that the running turn was viewer-started, which confines that turn to the shared tool surface and leaves an owner-started turn on the Session's native tools. That marker is never appended to the Session log and is recomputed from the next admitted step. A build without LiveShare keeps the message an ordinary user message because the kind stays 'user', and a principal kind this package does not drive is left to whoever drives it. A current reader of an older log finds no share-viewer principal and admits those prompts as ordinary input, as before. The field is not part of any model request. SESSION_FORMAT_VERSION does not change. + + +## Verification + +pnpm exec vitest run packages/experimental/liveshare/tests/relay-target-admission.host.spec.ts packages/experimental/liveshare/tests/relay-pre-step-admission.host.spec.ts packages/experimental/liveshare/tests/share-host-listeners.spec.ts packages/experimental/liveshare packages/experimental/liveshare-protocol: a share reader's prompt persists source.principal in agent/inbox/spliced, recovered reader input is refused at the `agent/pre-step` admission check, an admitted one enters the model, and a principal this package does not drive is left alone; the optional displayName is persisted for attribution, accepted only as a non-empty string, and missing or malformed values fall back to the subject id; 35 tests passed plus the two-package LiveShare and protocol suites. + + +## Dev Note + +None. diff --git a/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.schema.json b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.schema.json new file mode 100644 index 0000000000..dcce773ee6 --- /dev/null +++ b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.schema.json @@ -0,0 +1,253 @@ +{ + "formatVersion": 2, + "roots": [ + {"key":"event:agent/inbox/spliced","kind":"event","event":"agent/inbox/spliced","surface":false,"digest":"cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e"}, + {"key":"event:developer/message","kind":"event","event":"developer/message","surface":true,"digest":"70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f"}, + {"key":"event:session/title-llm-request","kind":"event","event":"session/title-llm-request","surface":false,"digest":"2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c"}, + {"key":"event:user/message","kind":"event","event":"user/message","surface":true,"digest":"5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451"} + ], + "types": [], + "nodes": { + "0203243b72fc867a": {"kind":"object","properties":[{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "022623b9ef98ec47": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "02b2c23f2d94b028": {"kind":"object","properties":[{"name":"kind","type":"c5687b1313206a6f","optional":false}],"indices":[]}, + "05205074b24d8340": {"kind":"literal","value":"action-cards"}, + "0657d3ca5ac4e7bf": {"kind":"primitive","type":"number"}, + "07e1a58c58b593f5": {"kind":"object","properties":[{"name":"model","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "09655b34d7f3cf1e": {"kind":"literal","value":"system-prompt"}, + "09f3f8dc417f2782": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"8af841fc9b265ade","optional":false},{"name":"source","type":"65a8400e451e667e","optional":false}],"indices":[]}, + "0a92c5bdfa06c2e2": {"kind":"object","properties":[{"name":"displayName","type":"4cd48f3e5108bd6e","optional":true},{"name":"providerId","type":"4cd48f3e5108bd6e","optional":false},{"name":"subjectId","type":"4cd48f3e5108bd6e","optional":false},{"name":"tenantId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "0ed8d1108fe7a5e1": {"kind":"object","properties":[{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "0eeb17e1df89b1eb": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "0f46153645c29784": {"kind":"object","properties":[{"name":"height","type":"0657d3ca5ac4e7bf","optional":false},{"name":"width","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "0fe52387f6505270": {"kind":"literal","value":"plan-mode"}, + "11638dc58a31496f": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "12d5808fac1996b9": {"kind":"object","properties":[{"name":"attachment","type":"b0b0eb1b16490f6b","optional":false},{"name":"offloaded","type":"dacf3d5f3e4ff619","optional":true},{"name":"type","type":"fb8b6a2e53cb9cf4","optional":false}],"indices":[]}, + "1379f0b72275994d": {"kind":"literal","value":"developer/message"}, + "16d0507cb94b4cfc": {"kind":"literal","value":"relay"}, + "1922cd79a70806c1": {"kind":"literal","value":"skill-invocation"}, + "1938c8c20f1cba7c": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "1e709346005826eb": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "1f0133217eeeffd8": {"kind":"literal","value":"tool-call"}, + "1f1385dbc3e875c0": {"kind":"literal","value":"repeat-tool-reminder"}, + "1fdad624334d3548": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "2152caf1a71e588e": {"kind":"object","properties":[{"name":"kind","type":"2e4debca12f2c449","optional":false},{"name":"messageId","type":"4cd48f3e5108bd6e","optional":false},{"name":"senderId","type":"4cd48f3e5108bd6e","optional":false},{"name":"senderName","type":"4cd48f3e5108bd6e","optional":false},{"name":"teamId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "2235d957bf4b7c6c": {"kind":"object","properties":[{"name":"kind","type":"7b1ce60193fa8b69","optional":false}],"indices":[]}, + "224aa11d4d5f88c4": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "23af3759678a30de": {"kind":"literal","value":"dsh-session-title-llm"}, + "24b10f7cdae64928": {"kind":"literal","value":"runtime-context"}, + "24ce31aa528272e5": {"kind":"object","properties":[{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "260523b412c19ad8": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "2765e9119edf5816": {"kind":"literal","value":"model"}, + "277b61f9c6f81704": {"kind":"literal","value":"file"}, + "28936c614bd4e7e2": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "290f32bfd81ff85a": {"kind":"object","properties":[{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "297fbd8067d7815a": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "2aad1179f9576314": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "2ab12a0e345658f9": {"kind":"array","element":"83da72c6857601c7"}, + "2e4debca12f2c449": {"kind":"literal","value":"team-message"}, + "2e505098f9209e52": {"kind":"object","properties":[{"name":"data","type":"7ff62f6599c083ce","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"587bb11da730e06a","optional":false}],"indices":[]}, + "2f1e6a7ebace43d7": {"kind":"union","types":["3f74ba74acd10644","58f94390b982f8a5","de30b1fa12c75f81","ebb768d85ec87fb6"]}, + "2f3f201c8846e19c": {"kind":"literal","value":"tool-goal"}, + "312aee2f0c42aabb": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "31907de956375182": {"kind":"object","properties":[{"name":"compactionId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"6b23ed9ce1b397e6","optional":false},{"name":"sourceCommandId","type":"4cd48f3e5108bd6e","optional":true}],"indices":[]}, + "3247e566f4340029": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "335e242de1fcc17b": {"kind":"union","types":["bcf0caf62d964b2f","e438a9d4fb883b3e"]}, + "383cf73ae4748e5b": {"kind":"literal","value":"recall"}, + "3b04790e08b35241": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "3b4f2c9ef2c1217e": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "3bd652ebfa8726b3": {"kind":"union","types":["0657d3ca5ac4e7bf","938f7c7357bc403e"]}, + "3bdb8dc6989655b0": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "3c2535ca0a2062f1": {"kind":"literal","value":"reasoning"}, + "3e2ece4967cfebe9": {"kind":"literal","value":"next-step"}, + "3f74ba74acd10644": {"kind":"literal","value":"image/jpeg"}, + "4035903993dfee62": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"68f44f59e91c4139","optional":false},{"name":"source","type":"7e9f1072c17f7aa8","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.user-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, + "408927267422a7b2": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "43e311235aa537df": {"kind":"object","properties":[{"name":"toolName","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"83d6916021eede8f","optional":false}],"indices":[]}, + "45f005e6bbb76452": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "4991dfc415c9efeb": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "49dab019d00e8c26": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "4a9bef9f27a94252": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"82470020b5bfcb1a","optional":false},{"name":"senderSessionId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4b259f7f8f0a44ad": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"isError","type":"aa93010d0e521ad7","optional":true},{"name":"role","type":"a13d8f379222ece8","optional":false},{"name":"source","type":"d9c462b9f62fdd3e","optional":false},{"name":"toolCallId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4cd48f3e5108bd6e": {"kind":"primitive","type":"string"}, + "4d60dddaa65d3da8": {"kind":"object","properties":[{"name":"actor","type":"0a92c5bdfa06c2e2","optional":false},{"name":"kind","type":"6ba7edb6447b6a3e","optional":false},{"name":"shareId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4e44c9118152f682": {"kind":"literal","value":"text"}, + "4e88776858652856": {"kind":"object","properties":[{"name":"text","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"4e44c9118152f682","optional":false}],"indices":[]}, + "4e97c3d85c0fc817": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"bf16d2e98a7f1389","optional":false},{"name":"senderSessionId","type":"4cd48f3e5108bd6e","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4edec1b770e8ec4c": {"kind":"literal","value":"ptc-mode"}, + "4f91f187baeabef5": {"kind":"object","properties":[{"name":"capturedFormatVersion","type":"0657d3ca5ac4e7bf","optional":true},{"name":"capturedThroughSeq","type":"3bd652ebfa8726b3","optional":false},{"name":"compacted","type":"aa93010d0e521ad7","optional":false},{"name":"inputIndex","type":"0657d3ca5ac4e7bf","optional":false},{"name":"label","type":"4cd48f3e5108bd6e","optional":false},{"name":"omittedBytes","type":"0657d3ca5ac4e7bf","optional":false},{"name":"omittedMessages","type":"0657d3ca5ac4e7bf","optional":false},{"name":"originalMessages","type":"0657d3ca5ac4e7bf","optional":false},{"name":"retainedMessages","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sessionId","type":"4cd48f3e5108bd6e","optional":false},{"name":"truncated","type":"aa93010d0e521ad7","optional":false}],"indices":[]}, + "52c6113cb0e53f34": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "53cf1704ae0709c7": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "53d4f8256bc58109": {"kind":"object","properties":[{"name":"headerSeq","type":"0657d3ca5ac4e7bf","optional":true},{"name":"message","type":"64ef542b1bfc9883","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "5654685d7557ec74": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "58015da1c1950a66": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "587bb11da730e06a": {"kind":"literal","value":"session/title-llm-request"}, + "589d0d91239681f8": {"kind":"literal","value":"developer"}, + "58f94390b982f8a5": {"kind":"literal","value":"image/png"}, + "5bb231bc5afdb532": {"kind":"object","properties":[{"name":"data","type":"4035903993dfee62","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"de25352d2dc41963","optional":false}],"indices":[]}, + "5bb69b88517f6214": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "5bc66269cfaf614c": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "5cdbf342b7748d15": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "5d03ba38734809bc": {"kind":"array","element":"0657d3ca5ac4e7bf"}, + "5d7a64ed6aac5551": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "6085488d223aeffd": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "6292bcbedaa97fea": {"kind":"object","properties":[{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "62ecb62dc0fe1b5e": {"kind":"literal","value":"next-turn"}, + "64ef542b1bfc9883": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"589d0d91239681f8","optional":false},{"name":"source","type":"7e9f1072c17f7aa8","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.developer-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, + "65a8400e451e667e": {"kind":"object","properties":[{"name":"kind","type":"09655b34d7f3cf1e","optional":false}],"indices":[]}, + "65d583e66518c523": {"kind":"object","properties":[{"name":"entries","type":"aba175fb20ffc711","optional":false},{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"incomplete","type":"dacf3d5f3e4ff619","optional":true},{"name":"kind","type":"6ebcc2dbec9f2dab","optional":false},{"name":"update","type":"dacf3d5f3e4ff619","optional":true}],"indices":[]}, + "672c4aa2a9b736e3": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"1922cd79a70806c1","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "68f44f59e91c4139": {"kind":"literal","value":"user"}, + "6b23ed9ce1b397e6": {"kind":"literal","value":"compact-checkpoint"}, + "6ba7edb6447b6a3e": {"kind":"literal","value":"share-viewer"}, + "6ccb6bc423fb3952": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "6ea608bdc8a7a63d": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "6ebcc2dbec9f2dab": {"kind":"literal","value":"skill-catalog"}, + "6f22a9d02b9a1f11": {"kind":"object","properties":[{"name":"baseline","type":"dacf3d5f3e4ff619","optional":true},{"name":"baselineIdentity","type":"4cd48f3e5108bd6e","optional":true},{"name":"changes","type":"2ab12a0e345658f9","optional":false},{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"fbd2c74b346a1595","optional":false}],"indices":[]}, + "6f44f32be9bcd9a8": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "6f9e00383836275e": {"kind":"literal","value":"snapshot"}, + "70d2acdec1ebcfea": {"kind":"object","properties":[{"name":"data","type":"53d4f8256bc58109","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"1379f0b72275994d","optional":false}],"indices":[]}, + "719c51f67074f970": {"kind":"object","properties":[{"name":"kind","type":"2765e9119edf5816","optional":false},{"name":"model","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"replayState","type":"bbc5696e3f13c758","optional":true}],"indices":[]}, + "7382c4fc95fe8c5d": {"kind":"literal","value":"remove"}, + "7554565be416b034": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "756b5e23a5cb2c7f": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "78a9be340090b735": {"kind":"literal","value":"tmux-context"}, + "7b1ce60193fa8b69": {"kind":"literal","value":"working-directory"}, + "7c203f3d4dfa6638": {"kind":"array","element":"4035903993dfee62"}, + "7df62978a2b7de85": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "7e9f1072c17f7aa8": {"kind":"union","types":["0203243b72fc867a","022623b9ef98ec47","02b2c23f2d94b028","0ed8d1108fe7a5e1","0eeb17e1df89b1eb","11638dc58a31496f","1938c8c20f1cba7c","1e709346005826eb","1fdad624334d3548","2152caf1a71e588e","2235d957bf4b7c6c","224aa11d4d5f88c4","24ce31aa528272e5","260523b412c19ad8","28936c614bd4e7e2","290f32bfd81ff85a","297fbd8067d7815a","2aad1179f9576314","312aee2f0c42aabb","31907de956375182","3247e566f4340029","3b04790e08b35241","3b4f2c9ef2c1217e","3bdb8dc6989655b0","408927267422a7b2","45f005e6bbb76452","4991dfc415c9efeb","49dab019d00e8c26","4a9bef9f27a94252","4e97c3d85c0fc817","52c6113cb0e53f34","53cf1704ae0709c7","5654685d7557ec74","58015da1c1950a66","5bb69b88517f6214","5bc66269cfaf614c","5cdbf342b7748d15","5d7a64ed6aac5551","6085488d223aeffd","6292bcbedaa97fea","65a8400e451e667e","65d583e66518c523","672c4aa2a9b736e3","6ccb6bc423fb3952","6ea608bdc8a7a63d","6f22a9d02b9a1f11","6f44f32be9bcd9a8","719c51f67074f970","7554565be416b034","756b5e23a5cb2c7f","7df62978a2b7de85","7eaef7a763ba5b94","7f959241c24128b4","80677c8c8b804189","825ca23416b1ea9d","8338ee303e2bd448","854db3efdfb0cd39","85fe96bf15d5c755","8620189c8e335827","87b1a33564b9a4d6","88841202942c7683","8a046b52331959aa","8c1c4f72755a78ea","8c627d7a45fa406c","8f324cea3916c051","8fcb0b44a575e998","96bfb916a727cd44","99135d8a39379779","99f0e98184709ad1","9edc162949abf93b","9f65c43e340bba31","a15a19ef63cf5d1b","a16e567c8cd2c55c","a2066bd52f61218b","a3c6f1ea38e9a61d","a4afec59b75aad5d","aa2bf9e82b9fdeb9","aae343bc3d663c83","ada310bf0bdb8fed","ade057f4fdc387ae","b062078e899958f9","b2a5c8c008a31e3d","b3681c026a0b98e9","b4ec0af39fd52ed9","b613f83572fe2fbf","b6f94c17dd9bbd7c","b70f3e81fe11b7a5","b79641a9d25e7566","ba2a1a8f194b1bb2","ba4c40b4381e0dcd","baccc97ec34be6c4","c5228b7a55498d84","c55827fba7018198","cb1c8959e1726f82","cda2345a9be9d139","d85590a5675c6e2f","d9c462b9f62fdd3e","db06ef35b27a3842","dba54c09c6e7aafc","dd00cdccd0ba487b","dd5ee8762bd8a14b","dd6cc2bb2a8f2824","dde0cdf9d426768b","deaae5cd30987d4f","e7f4cbb3a57f4cbd","edbbfff1128099fd","ee577a0cc18664c9","f230c0b583e23b25","f29d63336e8266d8","f4a66f654996c093","f56c5b59ca016131","f6329fb30c7ea801","f6605d6c57933aea","f6afe41e3926f422","f7283223aacdc39b","f97f47b0eb87905e","fcf81d3c58c13593","fe1a7acdeed4d0f5"]}, + "7eaef7a763ba5b94": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "7f13860ee89a2d35": {"kind":"literal","value":"session-reference"}, + "7f959241c24128b4": {"kind":"object","properties":[{"name":"goalId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"b815d7b91cdd9fc6","optional":false},{"name":"revision","type":"0657d3ca5ac4e7bf","optional":false},{"name":"round","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "7ff62f6599c083ce": {"kind":"object","properties":[{"name":"maxTokens","type":"0657d3ca5ac4e7bf","optional":false},{"name":"messageSeqs","type":"5d03ba38734809bc","optional":false},{"name":"messages","type":"ff2cbb53582d1827","optional":false},{"name":"reasoningEffort","type":"4cd48f3e5108bd6e","optional":true},{"name":"route","type":"07e1a58c58b593f5","optional":false},{"name":"system","type":"4cd48f3e5108bd6e","optional":false},{"name":"titleProvider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "8064c03c87c357fd": {"kind":"union","types":["12d5808fac1996b9","43e311235aa537df","4e88776858652856","814d9434e1ddf907","8e611bf46821e500","c1f0f17b6493b85d","f2da0f27c1e6add5"]}, + "80677c8c8b804189": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "8067b0d232c350f1": {"kind":"literal","value":"time-context"}, + "814d9434e1ddf907": {"kind":"object","properties":[{"name":"text","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"3c2535ca0a2062f1","optional":false}],"indices":[]}, + "82470020b5bfcb1a": {"kind":"literal","value":"agent-message"}, + "824a4aad44a54e24": {"kind":"union","types":["4d60dddaa65d3da8","deebfc7c62177ea8"]}, + "825ca23416b1ea9d": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "829a2fb3be6efd4b": {"kind":"literal","value":"agent/inbox/spliced"}, + "83079c8a3f733ac3": {"kind":"object","properties":[{"name":"description","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "8338ee303e2bd448": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "83d6916021eede8f": {"kind":"literal","value":"tool-removal"}, + "83da72c6857601c7": {"kind":"object","properties":[{"name":"action","type":"904bf499d98be4a3","optional":false},{"name":"digest","type":"4cd48f3e5108bd6e","optional":true},{"name":"path","type":"4cd48f3e5108bd6e","optional":false},{"name":"scope","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "854db3efdfb0cd39": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "85d6d96ff8842974": {"kind":"literal","value":"answered"}, + "85f9b505b7bdff1f": {"kind":"literal","value":"tool-addition"}, + "85fe96bf15d5c755": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "8620189c8e335827": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "86e1e384495ee09a": {"kind":"object","properties":[{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"text","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "87b1a33564b9a4d6": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "88841202942c7683": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "8a046b52331959aa": {"kind":"object","properties":[{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "8af841fc9b265ade": {"kind":"literal","value":"system"}, + "8c1c4f72755a78ea": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "8c627d7a45fa406c": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "8e611bf46821e500": {"kind":"object","properties":[{"name":"tool","type":"fcf427290c6213c2","optional":true},{"name":"toolName","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"85f9b505b7bdff1f","optional":false}],"indices":[]}, + "8f324cea3916c051": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "8fcb0b44a575e998": {"kind":"object","properties":[{"name":"kind","type":"a720757f704a2512","optional":false}],"indices":[]}, + "904bf499d98be4a3": {"kind":"union","types":["7382c4fc95fe8c5d","b765ee31033cea46","f6cb462f808309e3"]}, + "938f7c7357bc403e": {"kind":"primitive","type":"null"}, + "95a3ffccbf3c8afc": {"kind":"literal","value":"owner"}, + "95c0e88fcf0bafb2": {"kind":"literal","value":"assistant"}, + "9645cf93769a6dfb": {"kind":"literal","value":"user-question-reply"}, + "96bfb916a727cd44": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "96f4a9c81fc0f940": {"kind":"union","types":["3e2ece4967cfebe9","62ecb62dc0fe1b5e"]}, + "99135d8a39379779": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "99e7e7d7fed55ae6": {"kind":"literal","value":"tool-jobs"}, + "99f0e98184709ad1": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "9ac52f0f84fec2eb": {"kind":"literal","value":"model-selection"}, + "9edc162949abf93b": {"kind":"object","properties":[{"name":"deliveryId","type":"4cd48f3e5108bd6e","optional":false},{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"db6c5246911d47a7","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"ruleId","type":"4cd48f3e5108bd6e","optional":false},{"name":"source","type":"4cd48f3e5108bd6e","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "9f65c43e340bba31": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "a13d8f379222ece8": {"kind":"literal","value":"tool"}, + "a15a19ef63cf5d1b": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "a16e567c8cd2c55c": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "a2066bd52f61218b": {"kind":"object","properties":[{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "a3c6f1ea38e9a61d": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "a4afec59b75aad5d": {"kind":"object","properties":[{"name":"clientTimeZone","type":"4cd48f3e5108bd6e","optional":true},{"name":"kind","type":"68f44f59e91c4139","optional":false},{"name":"principal","type":"824a4aad44a54e24","optional":true},{"name":"rpcId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "a720757f704a2512": {"kind":"literal","value":"tool-registry"}, + "a9059a81430b3207": {"kind":"literal","value":"hooks-claude-code"}, + "aa2bf9e82b9fdeb9": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "aa93010d0e521ad7": {"kind":"primitive","type":"boolean"}, + "aae343bc3d663c83": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "aba175fb20ffc711": {"kind":"array","element":"83079c8a3f733ac3"}, + "ada310bf0bdb8fed": {"kind":"object","properties":[{"name":"kind","type":"68f44f59e91c4139","optional":false}],"indices":[]}, + "ade057f4fdc387ae": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "aec150797b655c5f": {"kind":"literal","value":"catalog"}, + "b062078e899958f9": {"kind":"object","properties":[{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "b0b0eb1b16490f6b": {"kind":"object","properties":[{"name":"attachmentId","type":"4cd48f3e5108bd6e","optional":false},{"name":"bytes","type":"0657d3ca5ac4e7bf","optional":false},{"name":"height","type":"0657d3ca5ac4e7bf","optional":false},{"name":"mediaType","type":"2f1e6a7ebace43d7","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":true},{"name":"originalDimensions","type":"0f46153645c29784","optional":true},{"name":"width","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "b2a5c8c008a31e3d": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "b3681c026a0b98e9": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "b4ec0af39fd52ed9": {"kind":"object","properties":[{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "b52f215a6cd69105": {"kind":"array","element":"8064c03c87c357fd"}, + "b613f83572fe2fbf": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "b6f94c17dd9bbd7c": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "b70f3e81fe11b7a5": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "b765ee31033cea46": {"kind":"literal","value":"set"}, + "b79641a9d25e7566": {"kind":"object","properties":[{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "b815d7b91cdd9fc6": {"kind":"literal","value":"goal"}, + "ba2a1a8f194b1bb2": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "ba4c40b4381e0dcd": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "baccc97ec34be6c4": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "bb94f3217aa56c88": {"kind":"literal","value":"hooks-codex"}, + "bbc5696e3f13c758": {"kind":"opaque","reason":"unknown"}, + "bcf0caf62d964b2f": {"kind":"object","properties":[{"name":"endSeq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"op","type":"f6cb462f808309e3","optional":false},{"name":"startSeq","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "bf16d2e98a7f1389": {"kind":"literal","value":"subagent-settled"}, + "c1f0f17b6493b85d": {"kind":"object","properties":[{"name":"arguments","type":"4cd48f3e5108bd6e","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"1f0133217eeeffd8","optional":false}],"indices":[]}, + "c5228b7a55498d84": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "c55827fba7018198": {"kind":"object","properties":[{"name":"callId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"9645cf93769a6dfb","optional":false},{"name":"outcome","type":"85d6d96ff8842974","optional":false}],"indices":[]}, + "c5687b1313206a6f": {"kind":"literal","value":"cordis-host-runner"}, + "c748fb42c80a1200": {"kind":"array","element":"86e1e384495ee09a"}, + "c78b9097bfae83cd": {"kind":"union","types":["09f3f8dc417f2782","4035903993dfee62","4b259f7f8f0a44ad","64ef542b1bfc9883","fa87537f4a9c1e25"]}, + "cb1c8959e1726f82": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "cda2345a9be9d139": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "cdf988172b589b23": {"kind":"object","properties":[{"name":"data","type":"d4d960185026266e","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"829a2fb3be6efd4b","optional":false}],"indices":[]}, + "d4d960185026266e": {"kind":"object","properties":[{"name":"inserted","type":"7c203f3d4dfa6638","optional":false},{"name":"outcome","type":"d4e4d575abeb4b72","optional":true},{"name":"removedCount","type":"0657d3ca5ac4e7bf","optional":true},{"name":"start","type":"0657d3ca5ac4e7bf","optional":false},{"name":"target","type":"96f4a9c81fc0f940","optional":false}],"indices":[]}, + "d4e4d575abeb4b72": {"kind":"literal","value":"canceled"}, + "d85590a5675c6e2f": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "d9c462b9f62fdd3e": {"kind":"object","properties":[{"name":"callId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"a13d8f379222ece8","optional":false}],"indices":[]}, + "d9edf1862e4471d6": {"kind":"literal","value":"schedule"}, + "dacf3d5f3e4ff619": {"kind":"literal","value":true}, + "db06ef35b27a3842": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "db6c5246911d47a7": {"kind":"literal","value":"webhook"}, + "dba54c09c6e7aafc": {"kind":"object","properties":[{"name":"kind","type":"4edec1b770e8ec4c","optional":false}],"indices":[]}, + "dd00cdccd0ba487b": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "dd5ee8762bd8a14b": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "dd6cc2bb2a8f2824": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "dde0cdf9d426768b": {"kind":"object","properties":[{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "de25352d2dc41963": {"kind":"literal","value":"user/message"}, + "de30b1fa12c75f81": {"kind":"literal","value":"image/gif"}, + "deaae5cd30987d4f": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "deebfc7c62177ea8": {"kind":"object","properties":[{"name":"kind","type":"95a3ffccbf3c8afc","optional":false}],"indices":[]}, + "df843efd87c78cf8": {"kind":"array","element":"4f91f187baeabef5"}, + "e438a9d4fb883b3e": {"kind":"literal","value":"append"}, + "e7f4cbb3a57f4cbd": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "e8de0f457fed5b9f": {"kind":"literal","value":"notice"}, + "ebb768d85ec87fb6": {"kind":"literal","value":"image/webp"}, + "edbbfff1128099fd": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "ee577a0cc18664c9": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "f19bee84bf3d2090": {"kind":"object","properties":[{"name":"attachmentId","type":"4cd48f3e5108bd6e","optional":false},{"name":"bytes","type":"0657d3ca5ac4e7bf","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "f230c0b583e23b25": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "f29d63336e8266d8": {"kind":"object","properties":[{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "f2da0f27c1e6add5": {"kind":"object","properties":[{"name":"attachment","type":"f19bee84bf3d2090","optional":false},{"name":"type","type":"277b61f9c6f81704","optional":false}],"indices":[]}, + "f4a66f654996c093": {"kind":"object","properties":[{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "f56c5b59ca016131": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"7f13860ee89a2d35","optional":false},{"name":"references","type":"df843efd87c78cf8","optional":false},{"name":"version","type":"f88f1b7b6bb733f6","optional":false}],"indices":[]}, + "f6329fb30c7ea801": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "f6605d6c57933aea": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "f68c335306535a00": {"kind":"literal","value":"user-approval"}, + "f6afe41e3926f422": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "f6cb462f808309e3": {"kind":"literal","value":"replace"}, + "f7283223aacdc39b": {"kind":"object","properties":[{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "f88f1b7b6bb733f6": {"kind":"literal","value":1}, + "f97f47b0eb87905e": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "fa87537f4a9c1e25": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"95c0e88fcf0bafb2","optional":false},{"name":"source","type":"719c51f67074f970","optional":false}],"indices":[]}, + "fb8b6a2e53cb9cf4": {"kind":"literal","value":"image"}, + "fbd2c74b346a1595": {"kind":"literal","value":"agent-instructions"}, + "fcf427290c6213c2": {"kind":"primitive","type":"never"}, + "fcf81d3c58c13593": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "fe1a7acdeed4d0f5": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "fee1caf8ab6a65c1": {"kind":"literal","value":"instructions"}, + "ff2cbb53582d1827": {"kind":"array","element":"c78b9097bfae83cd"} + } +} diff --git a/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.zh.md b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.zh.md new file mode 100644 index 0000000000..7250b05ac2 --- /dev/null +++ b/docs/persistence-changes/2026-10-13-liveshare-share-viewer-principal.zh.md @@ -0,0 +1,60 @@ +--- +description: "记录持久化类型更改及其兼容性确认。" +kind: persistence-change +--- + +# 2026-10-13-liveshare-share-viewer-principal + +[English](2026-10-13-liveshare-share-viewer-principal.md) | 中文 + +## 概述 + +为分享读者提交的提示词，在 user-rpc 消息来源中加入 LiveShare 的 share-viewer principal；Relay 断言了显示名时一并保存。 + +## 目录 + +- [声明](#declaration) +- [兼容性](#compatibility) +- [验证](#verification) +- [开发备注](#dev-note) + + +## 声明 + +```yaml persistence-change +schemaVersion: 1 +id: 2026-10-13-liveshare-share-viewer-principal +baseline: false +changes: + - root: "event:agent/inbox/spliced" + previous: "2026-10-25-skill-catalog-incomplete" + after: "cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e" + decision: same-version + - root: "event:developer/message" + previous: "2026-10-25-skill-catalog-incomplete" + after: "70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f" + decision: same-version + - root: "event:session/title-llm-request" + previous: "2026-10-25-skill-catalog-incomplete" + after: "2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c" + decision: same-version + - root: "event:user/message" + previous: "2026-10-25-skill-catalog-incomplete" + after: "5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451" + decision: same-version +``` + + +## 兼容性 + +只有 LiveShare 分享读者的 Peer 提交提示词时才写入 share-viewer 变体；所有者的提示词仍不写 principal，因此其来源与所有已有会话日志都不变。该值含分享 ID 和 Relay 断言的 provider、tenant、subject ID；Relay 断言了显示名时还包含可选的 displayName，仅供展示。凭据与头像永不持久化，授权仍只使用身份三元组；不认识该可选字段的读取方继续显示持久化的 subject id。LiveShare Host 在两个地方消费它：`agent/pre-step` 准入校验会为每条带分享查看者 principal 的进入消息重新读取 Relay 授权，授权不再成立时拒绝该步骤；同一步骤还会在当前轮次的内存状态中记录该轮次由查看者发起，使该轮次只运行共享工具面，而所有者自己发起的轮次保留会话原生工具。该标记不写入会话日志，并从下一个准入步骤重新计算。未装 LiveShare 的构建因 kind 仍为 'user' 而照常把它当作普通用户消息；本包不驱动的 principal 种类交由驱动它的插件处理。当前读取方读取旧日志时找不到 share-viewer principal，与以往一样把这些提示词当作普通输入放行。该字段不进入任何模型请求。SESSION_FORMAT_VERSION 不变。 + + +## 验证 + +pnpm exec vitest run packages/experimental/liveshare/tests/relay-target-admission.host.spec.ts packages/experimental/liveshare/tests/relay-pre-step-admission.host.spec.ts packages/experimental/liveshare/tests/share-host-listeners.spec.ts packages/experimental/liveshare packages/experimental/liveshare-protocol：分享读者的提示词在 agent/inbox/spliced 中持久化 source.principal，恢复的读者输入在 `agent/pre-step` 准入校验中被拒绝，已准入的输入进入模型，本包不驱动的 principal 种类不受影响；可选 displayName 仅用于展示，只接受非空字符串，缺失或非法值回退 subject id；35 个测试通过，另有 LiveShare 与协议两个包的全量测试。 + + +## 开发备注 + +无。 diff --git a/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.i18n.yaml b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.i18n.yaml new file mode 100644 index 0000000000..d9f830e422 --- /dev/null +++ b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.i18n.yaml @@ -0,0 +1,28 @@ +# Bilingual-pair consistency record for 2026-10-25-skill-catalog-incomplete.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/persistence-changes/2026-10-25-skill-catalog-incomplete.md +/: + en: 3d5a424ae7d7e46b + zh: c22a8e4a62d8cc1a +/2026-10-25-skill-catalog-incomplete: + en: 77f5988a4e0ad23e + zh: 7def799f40328fd9 +/2026-10-25-skill-catalog-incomplete/summary: + en: 2e5d228ea592110b + zh: 4d6a7c1fcde5e7c8 +/2026-10-25-skill-catalog-incomplete/table-of-contents: + en: 6cf314a069ceb451 + zh: 9adff678e9ecab3b +/2026-10-25-skill-catalog-incomplete/declaration: + en: 6907136f28e48c90 + zh: 02f8298485f3d8e7 +/2026-10-25-skill-catalog-incomplete/compatibility: + en: 5c837cd1fe40b2ab + zh: 7e0f980f2d2fb250 +/2026-10-25-skill-catalog-incomplete/verification: + en: f8bd4f442ccb271b + zh: 0f659a17ca577c0c +/2026-10-25-skill-catalog-incomplete/dev-note: + en: b75c8458928b72b9 + zh: 003ba4e17b4b5269 diff --git a/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.md b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.md new file mode 100644 index 0000000000..5d0638e9b2 --- /dev/null +++ b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.md @@ -0,0 +1,60 @@ +--- +description: "Records a persistence type transition and its compatibility acknowledgement." +kind: persistence-change +--- + +# 2026-10-25-skill-catalog-incomplete + +English | [中文](2026-10-25-skill-catalog-incomplete.zh.md) + +## Summary + +Adds optional incomplete: true metadata to skill-catalog message sources when discovery returns only the currently readable skills. + +## Table of Contents + +- [Declaration](#declaration) +- [Compatibility](#compatibility) +- [Verification](#verification) +- [Dev Note](#dev-note) + + +## Declaration + +```yaml persistence-change +schemaVersion: 1 +id: 2026-10-25-skill-catalog-incomplete +baseline: false +changes: + - root: "event:agent/inbox/spliced" + previous: "2026-10-22-action-card-status" + after: "9e8043098fb89db6d7c92a92c70146c5c8d24fa88f733c687fa29e5e7a58ab30" + decision: same-version + - root: "event:developer/message" + previous: "2026-10-22-action-card-status" + after: "95acdbd066cf445d37092e5fdfe2e8717ef6ca1aed50f70e2e6037a6989a1f2f" + decision: same-version + - root: "event:session/title-llm-request" + previous: "2026-10-22-action-card-status" + after: "eaa9125aec0fb28478096c46e73e21bf512ab0d84d826bfb41e7308707734cb5" + decision: same-version + - root: "event:user/message" + previous: "2026-10-22-action-card-status" + after: "39adb7fce8475af6402acd925ea79697b3341c22422ac32833d71217d84e987f" + decision: same-version +``` + + +## Compatibility + +Existing catalogs omit the flag and remain complete. New readers compare both entries and completeness. Older readers accept the unchanged source discriminator and entry fields, preserve the already-rendered discovery warning in message content, and ignore the optional flag. No event discriminator, required field, or Session format version changes. + + +## Verification + +Focused skill-filesystem and tool-skill tests: 71 passed with 100% coverage for both changed source files. Keyless headless skill-root-isolation and skill-load snapshots: 2 passed; the isolation fixture logs the partial catalog and loads a readable skill despite a failing root. + + +## Dev Note + +None. diff --git a/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.schema.json b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.schema.json new file mode 100644 index 0000000000..3ae2f36178 --- /dev/null +++ b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.schema.json @@ -0,0 +1,249 @@ +{ + "formatVersion": 2, + "roots": [ + {"key":"event:agent/inbox/spliced","kind":"event","event":"agent/inbox/spliced","surface":false,"digest":"9e8043098fb89db6d7c92a92c70146c5c8d24fa88f733c687fa29e5e7a58ab30"}, + {"key":"event:developer/message","kind":"event","event":"developer/message","surface":true,"digest":"95acdbd066cf445d37092e5fdfe2e8717ef6ca1aed50f70e2e6037a6989a1f2f"}, + {"key":"event:session/title-llm-request","kind":"event","event":"session/title-llm-request","surface":false,"digest":"eaa9125aec0fb28478096c46e73e21bf512ab0d84d826bfb41e7308707734cb5"}, + {"key":"event:user/message","kind":"event","event":"user/message","surface":true,"digest":"39adb7fce8475af6402acd925ea79697b3341c22422ac32833d71217d84e987f"} + ], + "types": [], + "nodes": { + "0203243b72fc867a": {"kind":"object","properties":[{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "022623b9ef98ec47": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "02b2c23f2d94b028": {"kind":"object","properties":[{"name":"kind","type":"c5687b1313206a6f","optional":false}],"indices":[]}, + "05205074b24d8340": {"kind":"literal","value":"action-cards"}, + "0657d3ca5ac4e7bf": {"kind":"primitive","type":"number"}, + "07e1a58c58b593f5": {"kind":"object","properties":[{"name":"model","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "09655b34d7f3cf1e": {"kind":"literal","value":"system-prompt"}, + "09f3f8dc417f2782": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"8af841fc9b265ade","optional":false},{"name":"source","type":"65a8400e451e667e","optional":false}],"indices":[]}, + "0ed8d1108fe7a5e1": {"kind":"object","properties":[{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "0eeb17e1df89b1eb": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "0f46153645c29784": {"kind":"object","properties":[{"name":"height","type":"0657d3ca5ac4e7bf","optional":false},{"name":"width","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "0fe52387f6505270": {"kind":"literal","value":"plan-mode"}, + "11638dc58a31496f": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "12d5808fac1996b9": {"kind":"object","properties":[{"name":"attachment","type":"b0b0eb1b16490f6b","optional":false},{"name":"offloaded","type":"dacf3d5f3e4ff619","optional":true},{"name":"type","type":"fb8b6a2e53cb9cf4","optional":false}],"indices":[]}, + "12f9a5a7506bca46": {"kind":"object","properties":[{"name":"headerSeq","type":"0657d3ca5ac4e7bf","optional":true},{"name":"message","type":"cebb7e9f3f663e66","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "1379f0b72275994d": {"kind":"literal","value":"developer/message"}, + "16d0507cb94b4cfc": {"kind":"literal","value":"relay"}, + "1922cd79a70806c1": {"kind":"literal","value":"skill-invocation"}, + "1938c8c20f1cba7c": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "1e709346005826eb": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "1f0133217eeeffd8": {"kind":"literal","value":"tool-call"}, + "1f1385dbc3e875c0": {"kind":"literal","value":"repeat-tool-reminder"}, + "1fdad624334d3548": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "2152caf1a71e588e": {"kind":"object","properties":[{"name":"kind","type":"2e4debca12f2c449","optional":false},{"name":"messageId","type":"4cd48f3e5108bd6e","optional":false},{"name":"senderId","type":"4cd48f3e5108bd6e","optional":false},{"name":"senderName","type":"4cd48f3e5108bd6e","optional":false},{"name":"teamId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "2235d957bf4b7c6c": {"kind":"object","properties":[{"name":"kind","type":"7b1ce60193fa8b69","optional":false}],"indices":[]}, + "224aa11d4d5f88c4": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "23af3759678a30de": {"kind":"literal","value":"dsh-session-title-llm"}, + "24b10f7cdae64928": {"kind":"literal","value":"runtime-context"}, + "24ce31aa528272e5": {"kind":"object","properties":[{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "260523b412c19ad8": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "2765e9119edf5816": {"kind":"literal","value":"model"}, + "277b61f9c6f81704": {"kind":"literal","value":"file"}, + "28936c614bd4e7e2": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "290f32bfd81ff85a": {"kind":"object","properties":[{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "297fbd8067d7815a": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "2aad1179f9576314": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "2ab12a0e345658f9": {"kind":"array","element":"83da72c6857601c7"}, + "2e4debca12f2c449": {"kind":"literal","value":"team-message"}, + "2f1e6a7ebace43d7": {"kind":"union","types":["3f74ba74acd10644","58f94390b982f8a5","de30b1fa12c75f81","ebb768d85ec87fb6"]}, + "2f3f201c8846e19c": {"kind":"literal","value":"tool-goal"}, + "312aee2f0c42aabb": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "31907de956375182": {"kind":"object","properties":[{"name":"compactionId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"6b23ed9ce1b397e6","optional":false},{"name":"sourceCommandId","type":"4cd48f3e5108bd6e","optional":true}],"indices":[]}, + "3247e566f4340029": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "335e242de1fcc17b": {"kind":"union","types":["bcf0caf62d964b2f","e438a9d4fb883b3e"]}, + "383cf73ae4748e5b": {"kind":"literal","value":"recall"}, + "39adb7fce8475af6": {"kind":"object","properties":[{"name":"data","type":"8bca2b4f53ec7745","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"de25352d2dc41963","optional":false}],"indices":[]}, + "3b04790e08b35241": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "3b4f2c9ef2c1217e": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "3bd652ebfa8726b3": {"kind":"union","types":["0657d3ca5ac4e7bf","938f7c7357bc403e"]}, + "3bdb8dc6989655b0": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "3c2535ca0a2062f1": {"kind":"literal","value":"reasoning"}, + "3e2ece4967cfebe9": {"kind":"literal","value":"next-step"}, + "3f74ba74acd10644": {"kind":"literal","value":"image/jpeg"}, + "408927267422a7b2": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "43e311235aa537df": {"kind":"object","properties":[{"name":"toolName","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"83d6916021eede8f","optional":false}],"indices":[]}, + "45f005e6bbb76452": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "4991dfc415c9efeb": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "49dab019d00e8c26": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "4a9bef9f27a94252": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"82470020b5bfcb1a","optional":false},{"name":"senderSessionId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4b259f7f8f0a44ad": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"isError","type":"aa93010d0e521ad7","optional":true},{"name":"role","type":"a13d8f379222ece8","optional":false},{"name":"source","type":"d9c462b9f62fdd3e","optional":false},{"name":"toolCallId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4cd48f3e5108bd6e": {"kind":"primitive","type":"string"}, + "4e44c9118152f682": {"kind":"literal","value":"text"}, + "4e88776858652856": {"kind":"object","properties":[{"name":"text","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"4e44c9118152f682","optional":false}],"indices":[]}, + "4e97c3d85c0fc817": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"bf16d2e98a7f1389","optional":false},{"name":"senderSessionId","type":"4cd48f3e5108bd6e","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "4edec1b770e8ec4c": {"kind":"literal","value":"ptc-mode"}, + "4f9125fa028a5628": {"kind":"union","types":["09f3f8dc417f2782","4b259f7f8f0a44ad","8bca2b4f53ec7745","cebb7e9f3f663e66","fa87537f4a9c1e25"]}, + "4f91f187baeabef5": {"kind":"object","properties":[{"name":"capturedFormatVersion","type":"0657d3ca5ac4e7bf","optional":true},{"name":"capturedThroughSeq","type":"3bd652ebfa8726b3","optional":false},{"name":"compacted","type":"aa93010d0e521ad7","optional":false},{"name":"inputIndex","type":"0657d3ca5ac4e7bf","optional":false},{"name":"label","type":"4cd48f3e5108bd6e","optional":false},{"name":"omittedBytes","type":"0657d3ca5ac4e7bf","optional":false},{"name":"omittedMessages","type":"0657d3ca5ac4e7bf","optional":false},{"name":"originalMessages","type":"0657d3ca5ac4e7bf","optional":false},{"name":"retainedMessages","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sessionId","type":"4cd48f3e5108bd6e","optional":false},{"name":"truncated","type":"aa93010d0e521ad7","optional":false}],"indices":[]}, + "52c6113cb0e53f34": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "53cf1704ae0709c7": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "5654685d7557ec74": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "58015da1c1950a66": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "587bb11da730e06a": {"kind":"literal","value":"session/title-llm-request"}, + "589d0d91239681f8": {"kind":"literal","value":"developer"}, + "58f94390b982f8a5": {"kind":"literal","value":"image/png"}, + "5bb69b88517f6214": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "5bc66269cfaf614c": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "5cdbf342b7748d15": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "5d03ba38734809bc": {"kind":"array","element":"0657d3ca5ac4e7bf"}, + "5d7a64ed6aac5551": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "6085488d223aeffd": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "6292bcbedaa97fea": {"kind":"object","properties":[{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "62ecb62dc0fe1b5e": {"kind":"literal","value":"next-turn"}, + "65a8400e451e667e": {"kind":"object","properties":[{"name":"kind","type":"09655b34d7f3cf1e","optional":false}],"indices":[]}, + "65d583e66518c523": {"kind":"object","properties":[{"name":"entries","type":"aba175fb20ffc711","optional":false},{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"incomplete","type":"dacf3d5f3e4ff619","optional":true},{"name":"kind","type":"6ebcc2dbec9f2dab","optional":false},{"name":"update","type":"dacf3d5f3e4ff619","optional":true}],"indices":[]}, + "672c4aa2a9b736e3": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"1922cd79a70806c1","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "68f44f59e91c4139": {"kind":"literal","value":"user"}, + "6b23ed9ce1b397e6": {"kind":"literal","value":"compact-checkpoint"}, + "6ccb6bc423fb3952": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "6dacb1584f2bfbe2": {"kind":"object","properties":[{"name":"clientTimeZone","type":"4cd48f3e5108bd6e","optional":true},{"name":"kind","type":"68f44f59e91c4139","optional":false},{"name":"principal","type":"deebfc7c62177ea8","optional":true},{"name":"rpcId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "6ea608bdc8a7a63d": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "6ebcc2dbec9f2dab": {"kind":"literal","value":"skill-catalog"}, + "6f22a9d02b9a1f11": {"kind":"object","properties":[{"name":"baseline","type":"dacf3d5f3e4ff619","optional":true},{"name":"baselineIdentity","type":"4cd48f3e5108bd6e","optional":true},{"name":"changes","type":"2ab12a0e345658f9","optional":false},{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"fbd2c74b346a1595","optional":false}],"indices":[]}, + "6f44f32be9bcd9a8": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "6f9e00383836275e": {"kind":"literal","value":"snapshot"}, + "719c51f67074f970": {"kind":"object","properties":[{"name":"kind","type":"2765e9119edf5816","optional":false},{"name":"model","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"replayState","type":"bbc5696e3f13c758","optional":true}],"indices":[]}, + "7382c4fc95fe8c5d": {"kind":"literal","value":"remove"}, + "7554565be416b034": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "756b5e23a5cb2c7f": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "78a9be340090b735": {"kind":"literal","value":"tmux-context"}, + "7b1ce60193fa8b69": {"kind":"literal","value":"working-directory"}, + "7df62978a2b7de85": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "7eaef7a763ba5b94": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "7f13860ee89a2d35": {"kind":"literal","value":"session-reference"}, + "7f959241c24128b4": {"kind":"object","properties":[{"name":"goalId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"b815d7b91cdd9fc6","optional":false},{"name":"revision","type":"0657d3ca5ac4e7bf","optional":false},{"name":"round","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "8064c03c87c357fd": {"kind":"union","types":["12d5808fac1996b9","43e311235aa537df","4e88776858652856","814d9434e1ddf907","8e611bf46821e500","c1f0f17b6493b85d","f2da0f27c1e6add5"]}, + "80677c8c8b804189": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "8067b0d232c350f1": {"kind":"literal","value":"time-context"}, + "814d9434e1ddf907": {"kind":"object","properties":[{"name":"text","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"3c2535ca0a2062f1","optional":false}],"indices":[]}, + "82470020b5bfcb1a": {"kind":"literal","value":"agent-message"}, + "825ca23416b1ea9d": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "829a2fb3be6efd4b": {"kind":"literal","value":"agent/inbox/spliced"}, + "83079c8a3f733ac3": {"kind":"object","properties":[{"name":"description","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "8338ee303e2bd448": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "83d6916021eede8f": {"kind":"literal","value":"tool-removal"}, + "83da72c6857601c7": {"kind":"object","properties":[{"name":"action","type":"904bf499d98be4a3","optional":false},{"name":"digest","type":"4cd48f3e5108bd6e","optional":true},{"name":"path","type":"4cd48f3e5108bd6e","optional":false},{"name":"scope","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "854db3efdfb0cd39": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "85d6d96ff8842974": {"kind":"literal","value":"answered"}, + "85f9b505b7bdff1f": {"kind":"literal","value":"tool-addition"}, + "85fe96bf15d5c755": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "8620189c8e335827": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "86e1e384495ee09a": {"kind":"object","properties":[{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"text","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "87b1a33564b9a4d6": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "88841202942c7683": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "8a046b52331959aa": {"kind":"object","properties":[{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "8af841fc9b265ade": {"kind":"literal","value":"system"}, + "8bca2b4f53ec7745": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"68f44f59e91c4139","optional":false},{"name":"source","type":"b112459dcb068609","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.user-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, + "8c1c4f72755a78ea": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "8c627d7a45fa406c": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "8e611bf46821e500": {"kind":"object","properties":[{"name":"tool","type":"fcf427290c6213c2","optional":true},{"name":"toolName","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"85f9b505b7bdff1f","optional":false}],"indices":[]}, + "8f324cea3916c051": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "8fcb0b44a575e998": {"kind":"object","properties":[{"name":"kind","type":"a720757f704a2512","optional":false}],"indices":[]}, + "904bf499d98be4a3": {"kind":"union","types":["7382c4fc95fe8c5d","b765ee31033cea46","f6cb462f808309e3"]}, + "938f7c7357bc403e": {"kind":"primitive","type":"null"}, + "95a3ffccbf3c8afc": {"kind":"literal","value":"owner"}, + "95acdbd066cf445d": {"kind":"object","properties":[{"name":"data","type":"12f9a5a7506bca46","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"1379f0b72275994d","optional":false}],"indices":[]}, + "95c0e88fcf0bafb2": {"kind":"literal","value":"assistant"}, + "9645cf93769a6dfb": {"kind":"literal","value":"user-question-reply"}, + "96bfb916a727cd44": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "96f4a9c81fc0f940": {"kind":"union","types":["3e2ece4967cfebe9","62ecb62dc0fe1b5e"]}, + "9808c3d0f0a1be8f": {"kind":"object","properties":[{"name":"maxTokens","type":"0657d3ca5ac4e7bf","optional":false},{"name":"messageSeqs","type":"5d03ba38734809bc","optional":false},{"name":"messages","type":"d2b617d9dfcc4e0a","optional":false},{"name":"reasoningEffort","type":"4cd48f3e5108bd6e","optional":true},{"name":"route","type":"07e1a58c58b593f5","optional":false},{"name":"system","type":"4cd48f3e5108bd6e","optional":false},{"name":"titleProvider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "99135d8a39379779": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "99e7e7d7fed55ae6": {"kind":"literal","value":"tool-jobs"}, + "99f0e98184709ad1": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "9ac52f0f84fec2eb": {"kind":"literal","value":"model-selection"}, + "9e8043098fb89db6": {"kind":"object","properties":[{"name":"data","type":"c433ef580a5b229b","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"829a2fb3be6efd4b","optional":false}],"indices":[]}, + "9edc162949abf93b": {"kind":"object","properties":[{"name":"deliveryId","type":"4cd48f3e5108bd6e","optional":false},{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"db6c5246911d47a7","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"ruleId","type":"4cd48f3e5108bd6e","optional":false},{"name":"source","type":"4cd48f3e5108bd6e","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "9f65c43e340bba31": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "a13d8f379222ece8": {"kind":"literal","value":"tool"}, + "a15a19ef63cf5d1b": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "a16e567c8cd2c55c": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "a2066bd52f61218b": {"kind":"object","properties":[{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, + "a3c6f1ea38e9a61d": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "a720757f704a2512": {"kind":"literal","value":"tool-registry"}, + "a9059a81430b3207": {"kind":"literal","value":"hooks-claude-code"}, + "aa2bf9e82b9fdeb9": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, + "aa93010d0e521ad7": {"kind":"primitive","type":"boolean"}, + "aada2771a250136c": {"kind":"array","element":"8bca2b4f53ec7745"}, + "aae343bc3d663c83": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "aba175fb20ffc711": {"kind":"array","element":"83079c8a3f733ac3"}, + "ada310bf0bdb8fed": {"kind":"object","properties":[{"name":"kind","type":"68f44f59e91c4139","optional":false}],"indices":[]}, + "ade057f4fdc387ae": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "aec150797b655c5f": {"kind":"literal","value":"catalog"}, + "b062078e899958f9": {"kind":"object","properties":[{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "b0b0eb1b16490f6b": {"kind":"object","properties":[{"name":"attachmentId","type":"4cd48f3e5108bd6e","optional":false},{"name":"bytes","type":"0657d3ca5ac4e7bf","optional":false},{"name":"height","type":"0657d3ca5ac4e7bf","optional":false},{"name":"mediaType","type":"2f1e6a7ebace43d7","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":true},{"name":"originalDimensions","type":"0f46153645c29784","optional":true},{"name":"width","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "b112459dcb068609": {"kind":"union","types":["0203243b72fc867a","022623b9ef98ec47","02b2c23f2d94b028","0ed8d1108fe7a5e1","0eeb17e1df89b1eb","11638dc58a31496f","1938c8c20f1cba7c","1e709346005826eb","1fdad624334d3548","2152caf1a71e588e","2235d957bf4b7c6c","224aa11d4d5f88c4","24ce31aa528272e5","260523b412c19ad8","28936c614bd4e7e2","290f32bfd81ff85a","297fbd8067d7815a","2aad1179f9576314","312aee2f0c42aabb","31907de956375182","3247e566f4340029","3b04790e08b35241","3b4f2c9ef2c1217e","3bdb8dc6989655b0","408927267422a7b2","45f005e6bbb76452","4991dfc415c9efeb","49dab019d00e8c26","4a9bef9f27a94252","4e97c3d85c0fc817","52c6113cb0e53f34","53cf1704ae0709c7","5654685d7557ec74","58015da1c1950a66","5bb69b88517f6214","5bc66269cfaf614c","5cdbf342b7748d15","5d7a64ed6aac5551","6085488d223aeffd","6292bcbedaa97fea","65a8400e451e667e","65d583e66518c523","672c4aa2a9b736e3","6ccb6bc423fb3952","6dacb1584f2bfbe2","6ea608bdc8a7a63d","6f22a9d02b9a1f11","6f44f32be9bcd9a8","719c51f67074f970","7554565be416b034","756b5e23a5cb2c7f","7df62978a2b7de85","7eaef7a763ba5b94","7f959241c24128b4","80677c8c8b804189","825ca23416b1ea9d","8338ee303e2bd448","854db3efdfb0cd39","85fe96bf15d5c755","8620189c8e335827","87b1a33564b9a4d6","88841202942c7683","8a046b52331959aa","8c1c4f72755a78ea","8c627d7a45fa406c","8f324cea3916c051","8fcb0b44a575e998","96bfb916a727cd44","99135d8a39379779","99f0e98184709ad1","9edc162949abf93b","9f65c43e340bba31","a15a19ef63cf5d1b","a16e567c8cd2c55c","a2066bd52f61218b","a3c6f1ea38e9a61d","aa2bf9e82b9fdeb9","aae343bc3d663c83","ada310bf0bdb8fed","ade057f4fdc387ae","b062078e899958f9","b2a5c8c008a31e3d","b3681c026a0b98e9","b4ec0af39fd52ed9","b613f83572fe2fbf","b6f94c17dd9bbd7c","b70f3e81fe11b7a5","b79641a9d25e7566","ba2a1a8f194b1bb2","ba4c40b4381e0dcd","baccc97ec34be6c4","c5228b7a55498d84","c55827fba7018198","cb1c8959e1726f82","cda2345a9be9d139","d85590a5675c6e2f","d9c462b9f62fdd3e","db06ef35b27a3842","dba54c09c6e7aafc","dd00cdccd0ba487b","dd5ee8762bd8a14b","dd6cc2bb2a8f2824","dde0cdf9d426768b","deaae5cd30987d4f","e7f4cbb3a57f4cbd","edbbfff1128099fd","ee577a0cc18664c9","f230c0b583e23b25","f29d63336e8266d8","f4a66f654996c093","f56c5b59ca016131","f6329fb30c7ea801","f6605d6c57933aea","f6afe41e3926f422","f7283223aacdc39b","f97f47b0eb87905e","fcf81d3c58c13593","fe1a7acdeed4d0f5"]}, + "b2a5c8c008a31e3d": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, + "b3681c026a0b98e9": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "b4ec0af39fd52ed9": {"kind":"object","properties":[{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "b52f215a6cd69105": {"kind":"array","element":"8064c03c87c357fd"}, + "b613f83572fe2fbf": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "b6f94c17dd9bbd7c": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, + "b70f3e81fe11b7a5": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, + "b765ee31033cea46": {"kind":"literal","value":"set"}, + "b79641a9d25e7566": {"kind":"object","properties":[{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "b815d7b91cdd9fc6": {"kind":"literal","value":"goal"}, + "ba2a1a8f194b1bb2": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "ba4c40b4381e0dcd": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "baccc97ec34be6c4": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "bb94f3217aa56c88": {"kind":"literal","value":"hooks-codex"}, + "bbc5696e3f13c758": {"kind":"opaque","reason":"unknown"}, + "bcf0caf62d964b2f": {"kind":"object","properties":[{"name":"endSeq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"op","type":"f6cb462f808309e3","optional":false},{"name":"startSeq","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "bf16d2e98a7f1389": {"kind":"literal","value":"subagent-settled"}, + "c1f0f17b6493b85d": {"kind":"object","properties":[{"name":"arguments","type":"4cd48f3e5108bd6e","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"1f0133217eeeffd8","optional":false}],"indices":[]}, + "c433ef580a5b229b": {"kind":"object","properties":[{"name":"inserted","type":"aada2771a250136c","optional":false},{"name":"outcome","type":"d4e4d575abeb4b72","optional":true},{"name":"removedCount","type":"0657d3ca5ac4e7bf","optional":true},{"name":"start","type":"0657d3ca5ac4e7bf","optional":false},{"name":"target","type":"96f4a9c81fc0f940","optional":false}],"indices":[]}, + "c5228b7a55498d84": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "c55827fba7018198": {"kind":"object","properties":[{"name":"callId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"9645cf93769a6dfb","optional":false},{"name":"outcome","type":"85d6d96ff8842974","optional":false}],"indices":[]}, + "c5687b1313206a6f": {"kind":"literal","value":"cordis-host-runner"}, + "c748fb42c80a1200": {"kind":"array","element":"86e1e384495ee09a"}, + "cb1c8959e1726f82": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false}],"indices":[]}, + "cda2345a9be9d139": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "cebb7e9f3f663e66": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"589d0d91239681f8","optional":false},{"name":"source","type":"b112459dcb068609","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.developer-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, + "d2b617d9dfcc4e0a": {"kind":"array","element":"4f9125fa028a5628"}, + "d4e4d575abeb4b72": {"kind":"literal","value":"canceled"}, + "d85590a5675c6e2f": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false}],"indices":[]}, + "d9c462b9f62fdd3e": {"kind":"object","properties":[{"name":"callId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"a13d8f379222ece8","optional":false}],"indices":[]}, + "d9edf1862e4471d6": {"kind":"literal","value":"schedule"}, + "dacf3d5f3e4ff619": {"kind":"literal","value":true}, + "db06ef35b27a3842": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "db6c5246911d47a7": {"kind":"literal","value":"webhook"}, + "dba54c09c6e7aafc": {"kind":"object","properties":[{"name":"kind","type":"4edec1b770e8ec4c","optional":false}],"indices":[]}, + "dd00cdccd0ba487b": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "dd5ee8762bd8a14b": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "dd6cc2bb2a8f2824": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "dde0cdf9d426768b": {"kind":"object","properties":[{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "de25352d2dc41963": {"kind":"literal","value":"user/message"}, + "de30b1fa12c75f81": {"kind":"literal","value":"image/gif"}, + "deaae5cd30987d4f": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "deebfc7c62177ea8": {"kind":"object","properties":[{"name":"kind","type":"95a3ffccbf3c8afc","optional":false}],"indices":[]}, + "df843efd87c78cf8": {"kind":"array","element":"4f91f187baeabef5"}, + "e438a9d4fb883b3e": {"kind":"literal","value":"append"}, + "e7f4cbb3a57f4cbd": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"05205074b24d8340","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false},{"name":"through","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "e8de0f457fed5b9f": {"kind":"literal","value":"notice"}, + "eaa9125aec0fb284": {"kind":"object","properties":[{"name":"data","type":"9808c3d0f0a1be8f","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"587bb11da730e06a","optional":false}],"indices":[]}, + "ebb768d85ec87fb6": {"kind":"literal","value":"image/webp"}, + "edbbfff1128099fd": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "ee577a0cc18664c9": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "f19bee84bf3d2090": {"kind":"object","properties":[{"name":"attachmentId","type":"4cd48f3e5108bd6e","optional":false},{"name":"bytes","type":"0657d3ca5ac4e7bf","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "f230c0b583e23b25": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, + "f29d63336e8266d8": {"kind":"object","properties":[{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, + "f2da0f27c1e6add5": {"kind":"object","properties":[{"name":"attachment","type":"f19bee84bf3d2090","optional":false},{"name":"type","type":"277b61f9c6f81704","optional":false}],"indices":[]}, + "f4a66f654996c093": {"kind":"object","properties":[{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "f56c5b59ca016131": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"7f13860ee89a2d35","optional":false},{"name":"references","type":"df843efd87c78cf8","optional":false},{"name":"version","type":"f88f1b7b6bb733f6","optional":false}],"indices":[]}, + "f6329fb30c7ea801": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, + "f6605d6c57933aea": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "f68c335306535a00": {"kind":"literal","value":"user-approval"}, + "f6afe41e3926f422": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, + "f6cb462f808309e3": {"kind":"literal","value":"replace"}, + "f7283223aacdc39b": {"kind":"object","properties":[{"name":"kind","type":"9ac52f0f84fec2eb","optional":false}],"indices":[]}, + "f88f1b7b6bb733f6": {"kind":"literal","value":1}, + "f97f47b0eb87905e": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "fa87537f4a9c1e25": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"95c0e88fcf0bafb2","optional":false},{"name":"source","type":"719c51f67074f970","optional":false}],"indices":[]}, + "fb8b6a2e53cb9cf4": {"kind":"literal","value":"image"}, + "fbd2c74b346a1595": {"kind":"literal","value":"agent-instructions"}, + "fcf427290c6213c2": {"kind":"primitive","type":"never"}, + "fcf81d3c58c13593": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "fe1a7acdeed4d0f5": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, + "fee1caf8ab6a65c1": {"kind":"literal","value":"instructions"} + } +} diff --git a/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.zh.md b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.zh.md new file mode 100644 index 0000000000..f87865566f --- /dev/null +++ b/docs/persistence-changes/2026-10-25-skill-catalog-incomplete.zh.md @@ -0,0 +1,60 @@ +--- +description: "记录持久化类型更改及其兼容性确认。" +kind: persistence-change +--- + +# 2026-10-25-skill-catalog-incomplete + +[English](2026-10-25-skill-catalog-incomplete.md) | 中文 + +## 概述 + +当技能发现仅返回当前可读技能时，为 skill-catalog 消息来源添加可选的 incomplete: true 元数据。 + +## 目录 + +- [声明](#declaration) +- [兼容性](#compatibility) +- [验证](#verification) +- [开发备注](#dev-note) + + +## 声明 + +```yaml persistence-change +schemaVersion: 1 +id: 2026-10-25-skill-catalog-incomplete +baseline: false +changes: + - root: "event:agent/inbox/spliced" + previous: "2026-10-22-action-card-status" + after: "9e8043098fb89db6d7c92a92c70146c5c8d24fa88f733c687fa29e5e7a58ab30" + decision: same-version + - root: "event:developer/message" + previous: "2026-10-22-action-card-status" + after: "95acdbd066cf445d37092e5fdfe2e8717ef6ca1aed50f70e2e6037a6989a1f2f" + decision: same-version + - root: "event:session/title-llm-request" + previous: "2026-10-22-action-card-status" + after: "eaa9125aec0fb28478096c46e73e21bf512ab0d84d826bfb41e7308707734cb5" + decision: same-version + - root: "event:user/message" + previous: "2026-10-22-action-card-status" + after: "39adb7fce8475af6402acd925ea79697b3341c22422ac32833d71217d84e987f" + decision: same-version +``` + + +## 兼容性 + +已有目录不含此标记，仍按完整目录读取。新读取方同时比较条目与完整性。旧读取方接受未变的来源判别值与条目字段，保留消息正文中已渲染的发现警告，并忽略可选标记。不改变事件判别值、必填字段或 Session 格式版本。 + + +## 验证 + +skill-filesystem 与 tool-skill 定向测试共 71 项通过，两个修改源文件覆盖率均为 100%。无密钥 headless skill-root-isolation 与 skill-load 快照共 2 项通过；隔离夹具记录部分目录，并在一个根失败时成功加载可读技能。 + + +## 开发备注 + +无。 diff --git a/docs/persistence-changes/historical-formats/README.i18n.yaml b/docs/persistence-changes/historical-formats/README.i18n.yaml index 5cca810556..cae6902733 100644 --- a/docs/persistence-changes/historical-formats/README.i18n.yaml +++ b/docs/persistence-changes/historical-formats/README.i18n.yaml @@ -15,8 +15,8 @@ en: 14c57f30e676f6e3 zh: b1a0ccf26fab3727 /session-persistence-formats/format-references: - en: 379b5d3a99868871 - zh: 10e6ef07dd41766a + en: 83fd4c4276a2600d + zh: 4f3431c960a7f8da /session-persistence-formats/scope-and-evidence: en: b220062139ddac1e zh: 7c4c0efe05dafa9c diff --git a/docs/persistence-changes/historical-formats/README.md b/docs/persistence-changes/historical-formats/README.md index 88791a985e..da1a2d629e 100644 --- a/docs/persistence-changes/historical-formats/README.md +++ b/docs/persistence-changes/historical-formats/README.md @@ -32,7 +32,7 @@ The index is generated from validated snapshots and the current writer constant. | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 | | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 | | 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 | -| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 66 / 625 | +| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 66 / 629 | diff --git a/docs/persistence-changes/historical-formats/README.zh.md b/docs/persistence-changes/historical-formats/README.zh.md index ad01f3dad0..8a2460c46c 100644 --- a/docs/persistence-changes/historical-formats/README.zh.md +++ b/docs/persistence-changes/historical-formats/README.zh.md @@ -32,7 +32,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式 | 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 | | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 | | 3 | PR #4320 | [V3](v3.zh.md) | [JSON](v3.schema.json) | 60 / 467 | -| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 66 / 625 | +| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 66 / 629 | diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json index 5969d891c1..3085786f53 100644 --- a/docs/persistence-schema.json +++ b/docs/persistence-schema.json @@ -5,7 +5,7 @@ {"key":"JsonlHeaderLine","kind":"header","digest":"18ee62b8900a4c3d046700f05d7a4d49d6cab2a660a020c87481d1603dd8bd4f"}, {"key":"SessionEventEnvelope","kind":"envelope","digest":"5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc"}, {"key":"event:agent-preset/selected","kind":"event","event":"agent-preset/selected","surface":false,"digest":"a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b"}, - {"key":"event:agent/inbox/spliced","kind":"event","event":"agent/inbox/spliced","surface":false,"digest":"b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e"}, + {"key":"event:agent/inbox/spliced","kind":"event","event":"agent/inbox/spliced","surface":false,"digest":"cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e"}, {"key":"event:approval/asked","kind":"event","event":"approval/asked","surface":false,"digest":"3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1"}, {"key":"event:approval/decided","kind":"event","event":"approval/decided","surface":false,"digest":"bb1ab3d08f49a9f3b265f844cd78d5c49813062a7b34b54904b426f85d0ff6e3"}, {"key":"event:approval/policy","kind":"event","event":"approval/policy","surface":false,"digest":"26718e15e7e395bce9642dba5bbe09b3b1a4ce2213d20d566cd9207d7fc5fb78"}, @@ -18,7 +18,7 @@ {"key":"event:compaction/start","kind":"event","event":"compaction/start","surface":false,"digest":"db874d463b0fdec77e9da1c4568f37cb70bd6596781eb93800db44fb8a116965"}, {"key":"event:compaction/summary","kind":"event","event":"compaction/summary","surface":false,"digest":"e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602"}, {"key":"event:deliverables/presented","kind":"event","event":"deliverables/presented","surface":false,"digest":"13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176"}, - {"key":"event:developer/message","kind":"event","event":"developer/message","surface":true,"digest":"5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be"}, + {"key":"event:developer/message","kind":"event","event":"developer/message","surface":true,"digest":"70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f"}, {"key":"event:feedback/message-delete","kind":"event","event":"feedback/message-delete","surface":false,"digest":"3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796"}, {"key":"event:feedback/message-put","kind":"event","event":"feedback/message-put","surface":false,"digest":"b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf"}, {"key":"event:feedback/record","kind":"event","event":"feedback/record","surface":false,"digest":"b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8"}, @@ -40,7 +40,7 @@ {"key":"event:session-log-deepseek/delivery-accepted","kind":"event","event":"session-log-deepseek/delivery-accepted","surface":false,"digest":"d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9"}, {"key":"event:session/end-seed","kind":"event","event":"session/end-seed","surface":false,"digest":"5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e"}, {"key":"event:session/title","kind":"event","event":"session/title","surface":false,"digest":"1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5"}, - {"key":"event:session/title-llm-request","kind":"event","event":"session/title-llm-request","surface":false,"digest":"efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc"}, + {"key":"event:session/title-llm-request","kind":"event","event":"session/title-llm-request","surface":false,"digest":"2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c"}, {"key":"event:step/end","kind":"event","event":"step/end","surface":false,"digest":"e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05"}, {"key":"event:step/start","kind":"event","event":"step/start","surface":false,"digest":"4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986"}, {"key":"event:subagent-name/bound","kind":"event","event":"subagent-name/bound","surface":false,"digest":"2073e98f0c214cc431b1a9a027efe75d22190a8ed8fed2791b47c2b52dd32a57"}, @@ -63,7 +63,7 @@ {"key":"event:tool/result","kind":"event","event":"tool/result","surface":true,"digest":"7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397"}, {"key":"event:turn/end","kind":"event","event":"turn/end","surface":false,"digest":"0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce"}, {"key":"event:turn/start","kind":"event","event":"turn/start","surface":false,"digest":"aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8"}, - {"key":"event:user/message","kind":"event","event":"user/message","surface":true,"digest":"58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019"}, + {"key":"event:user/message","kind":"event","event":"user/message","surface":true,"digest":"5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451"}, {"key":"event:web/deepseek-search-llm-request","kind":"event","event":"web/deepseek-search-llm-request","surface":false,"digest":"0c556c9b9f2a96238a6b9bbb99e748206cbff2ed6203041c9571f04ae5802f52"}, {"key":"event:working-directory/change","kind":"event","event":"working-directory/change","surface":false,"digest":"124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3"}, {"key":"event:workspace/changes","kind":"event","event":"workspace/changes","surface":false,"digest":"e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72"} @@ -85,8 +85,9 @@ {"digest":"09f3f8dc417f278257202714132f98ba7b52957d7b558c4a04456603890eb363","names":["packages/llm/llm/src/message.ts#SystemMessage"],"sources":["packages/llm/llm/src/message.ts:151"]}, {"digest":"0a30c3be336cdd4f8f34e66543a3d46d611c43986edd9b3ce6cbb9b721d3b5d3","names":[],"sources":["packages/core/session/src/types.ts:209"]}, {"digest":"0a8a062bc9c3c0d97fd97742262f2ea53dd32297f834e81114870d38ac3dc6da","names":[],"sources":[]}, + {"digest":"0a92c5bdfa06c2e2615b777728f3aa95f408d43b9012e7b754568311251db623","names":[],"sources":["packages/experimental/liveshare/src/host/viewer-principal.ts:29"]}, {"digest":"0aa62ab51b36c0e64b134bd03ba8725d758744180a1a447da49beaad194f219f","names":[],"sources":[]}, - {"digest":"0acd94fe8794574c9ae72c7855ee16d29c546096d4af760d16d1225385764555","names":["packages/llm/llm/src/types.ts#ReplayEnvelope"],"sources":["packages/llm/llm/src/types.ts:448"]}, + {"digest":"0acd94fe8794574c9ae72c7855ee16d29c546096d4af760d16d1225385764555","names":["packages/llm/llm/src/types.ts#ReplayEnvelope"],"sources":["packages/llm/llm/src/types.ts:474"]}, {"digest":"0af3ecfb8c60d416fc40a7cc4fb2c4851a8e46608b2b38ab9e510670c971aa1f","names":[],"sources":[]}, {"digest":"0b6d718c693fdf7f06dcccb0bcbbabe78cc63514eafc62d6b2a3899735279d6f","names":["packages/goal/goal/src/types.ts#GoalRef"],"sources":["packages/goal/goal/src/types.ts:20"]}, {"digest":"0b9b8facbe2c19773b3fb0ecc824ccbcc603d41b8f18069faa3807d449572fce","names":[],"sources":[]}, @@ -109,7 +110,7 @@ {"digest":"11f70b595aa76897fc4e25a352bfa718c659f44b799e5aa14e84e5a38fe72912","names":[],"sources":["packages/interaction/user-approval/src/index.ts:41"]}, {"digest":"124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3","names":[],"sources":[]}, {"digest":"12a0cfa619ac4a5fc6c3e8e359c8dae15769edc61497a575935c78d5842f8e42","names":[],"sources":[]}, - {"digest":"12d5808fac1996b9b3c2afa806e03022252ba2d7b88f835862ae1896591f60c7","names":["packages/llm/llm/src/types.ts#ImageBlock"],"sources":["packages/llm/llm/src/types.ts:79"]}, + {"digest":"12d5808fac1996b9b3c2afa806e03022252ba2d7b88f835862ae1896591f60c7","names":["packages/llm/llm/src/types.ts#ImageBlock"],"sources":["packages/llm/llm/src/types.ts:86"]}, {"digest":"1379f0b72275994d20f1ddca2d60a96ab16ec80397ca9f1af21bdc67ba5c269c","names":[],"sources":[]}, {"digest":"13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176","names":[],"sources":[]}, {"digest":"14230f9b8b5797bb7e8c621fa636531cfbde2ffba1ef5f1fd058216ff21952a0","names":[],"sources":[]}, @@ -139,7 +140,7 @@ {"digest":"1ccb56061942f5ccb0d30c9e4f2883b9d115ff906560029de637b61d3cde896d","names":[],"sources":["packages/core/session/src/types.ts:349"]}, {"digest":"1cde1bedde79c5e8a56aee9c05c8e0a579cf5bc611deb85b93fa331a16ca978f","names":["packages/compaction/compaction-image-offload/src/projection.ts#ImageOffloadTarget"],"sources":["packages/compaction/compaction-image-offload/src/projection.ts:9"]}, {"digest":"1d5f04a03ea75fc8eeece544129eba0f49f0c82046e9c404461920390135c7b2","names":[],"sources":[]}, - {"digest":"1d76406cbb2ddadb0dbbb51e9d8bc6cf678fed455cf8eb512f36f7c86d37a62f","names":[],"sources":["packages/llm/llm/src/types.ts:157"]}, + {"digest":"1d76406cbb2ddadb0dbbb51e9d8bc6cf678fed455cf8eb512f36f7c86d37a62f","names":[],"sources":["packages/llm/llm/src/types.ts:164"]}, {"digest":"1d8798b1a5e8c545ee4dcd2b4e75c0b4c9ffd985e4744c6d1a1aab992f859721","names":[],"sources":[]}, {"digest":"1d9cb3caa96100b18b1911fa3ff8c751ef6992971a03c5f4d9aefc1a0004a345","names":[],"sources":[]}, {"digest":"1df34a6c086866ffdc2dd9e8e5c581c3751a010cdf6b8538a7327f7a3237f0b4","names":["packages/goal/goal/src/domain.ts#GoalSnapshotChangeMeta"],"sources":["packages/goal/goal/src/domain.ts:24"]}, @@ -170,13 +171,13 @@ {"digest":"26c879bdd130e8b8683a6ce588414fad2244783d6573ca399fa0de184a2b0bb1","names":[],"sources":[]}, {"digest":"2765e9119edf5816ac1ab4c95c5ee32c90403f3742962eff11544f7752d59d2e","names":[],"sources":[]}, {"digest":"277b61f9c6f8170425fa6ffe06cfa14376757a896a4749cb82a687d7364c4fc9","names":[],"sources":[]}, - {"digest":"287211846beea1eccb5f9acee00d20388a38fcb2e95858fa2332d6f58529379a","names":[],"sources":["packages/llm/llm/src/types.ts:158"]}, + {"digest":"287211846beea1eccb5f9acee00d20388a38fcb2e95858fa2332d6f58529379a","names":[],"sources":["packages/llm/llm/src/types.ts:165"]}, {"digest":"28936c614bd4e7e2774806edcbb3cbfd3ee643ac1cbf0bbdff43d915505a8fe3","names":[],"sources":[]}, {"digest":"290f32bfd81ff85a8095886a8066fae06e885942b63a8bcd6a8d66d328445808","names":[],"sources":[]}, {"digest":"297fbd8067d7815adae02b89790ec6ff5fb7c2cb0d0eb026e1746c24ec857761","names":[],"sources":[]}, {"digest":"2aad1179f957631477b582e57cd8f538cb82618fc3fb816bde1171154235b065","names":[],"sources":[]}, {"digest":"2ab12a0e345658f9342816d773fe610f049982bcad82631f43b9205abe43e5ee","names":[],"sources":[]}, - {"digest":"2abb711460e6238d851c30f3e4bdd87a2aa1887ee70575b3d3b7b25610673095","names":[],"sources":["packages/llm/llm/src/types.ts:473"]}, + {"digest":"2abb711460e6238d851c30f3e4bdd87a2aa1887ee70575b3d3b7b25610673095","names":[],"sources":["packages/llm/llm/src/types.ts:499"]}, {"digest":"2aed07493b1c65b6d00de5586da1e743cf501684b9ad43a1765fb4007d4ea456","names":[],"sources":[]}, {"digest":"2c4c21f19f426a58f2dac914e34313aa43f8408972de857a486d1f086d5adb6c","names":[],"sources":[]}, {"digest":"2c64d4bc7264fd3f8bed47e96ab8a593bce05a1e4e1c436dcd244a3b7e0c2a9d","names":[],"sources":[]}, @@ -184,6 +185,7 @@ {"digest":"2da725e554cd89301d829ed9dc45a572c3cd1b93b5e91d0d71f007976d8a0863","names":[],"sources":[]}, {"digest":"2e3523541e942ef6cc9fbc5b91f242e0ca4c6ada479b79b96025b797f6e41f3f","names":["packages/schedule/schedule/src/types.ts#ScheduleChange"],"sources":["packages/schedule/schedule/src/types.ts:256"]}, {"digest":"2e4debca12f2c449f96dc6574f3fbf2fb346193443114a241d01a236362ec48c","names":[],"sources":[]}, + {"digest":"2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c","names":[],"sources":[]}, {"digest":"2eafefdc6f79a4922d68a787a09eaf4dd2b2369c3777fba4c05e800b5678ac8e","names":["packages/experimental/agent-team/src/types.ts#TeamMessageSnapshot"],"sources":["packages/experimental/agent-team/src/types.ts:107"]}, {"digest":"2f1e6a7ebace43d727ae138ddcd352eb3813960009e5805b8c5ac84300c97716","names":["packages/attachment/attachment/src/types.ts#ImageMediaType"],"sources":["packages/attachment/attachment/src/types.ts:8"]}, {"digest":"2f3f201c8846e19c20bb75c02280e3d4eb3c57509e4715f0c0a4d1d4f91a7a06","names":[],"sources":[]}, @@ -215,7 +217,7 @@ {"digest":"3bc287e765d58dc3a22672a0495a6cfd561220dd38fbaecef80aa95b96caed79","names":[],"sources":[]}, {"digest":"3bd652ebfa8726b3ce3937a4f1bd2759e02f86b3a08a20f9e41a8513656fbc5f","names":["packages/core/session/src/types.ts#OptionalSessionSeq"],"sources":["packages/core/session/src/types.ts:66"]}, {"digest":"3bdb8dc6989655b0d4ec361edafb8e2629bc263e1ea591819414fdafc1a413b3","names":[],"sources":[]}, - {"digest":"3bec87f9e6ab3da03346f49923d3c51621debc0159df68605e543c3b2a026f90","names":[],"sources":["packages/llm/llm/src/types.ts:471"]}, + {"digest":"3bec87f9e6ab3da03346f49923d3c51621debc0159df68605e543c3b2a026f90","names":[],"sources":["packages/llm/llm/src/types.ts:497"]}, {"digest":"3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1","names":[],"sources":[]}, {"digest":"3c2535ca0a2062f172f15344f8040755002b5ac506cf94fc4ebaa822b15feb8c","names":[],"sources":[]}, {"digest":"3cfc3a56502da1f8c6153c2c56657bab4b749056968634dd0991d325ec1c919f","names":["packages/core/tools/src/contracts.ts#ToolRestriction"],"sources":["packages/core/tools/src/contracts.ts:376"]}, @@ -226,11 +228,12 @@ {"digest":"3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796","names":[],"sources":[]}, {"digest":"3f74ba74acd10644c1ed6947a411d8088bd2cfac74f61bb8540f96d68e31f004","names":[],"sources":[]}, {"digest":"3fdf9582c3b5597df104d32d97dab6c6ee3a93794f3034ec6ada6272404ea27f","names":["packages/schedule/schedule/src/types.ts#LegacyAfterScheduleRecord"],"sources":["packages/schedule/schedule/src/types.ts:161"]}, + {"digest":"4035903993dfee62cca2142c0ca51ab57075909ddee2817d0620daa97ac4d4ce","names":["packages/llm/llm/src/message.ts#UserMessage"],"sources":["packages/llm/llm/src/message.ts:162"]}, {"digest":"408927267422a7b2beb6df354ff7c1406d929a5646554f48adf85eb8372f811c","names":[],"sources":[]}, {"digest":"4208123b50df5006b181481ab45fcf1cde807b88d3fd4d340090bc2e202fac41","names":[],"sources":[]}, {"digest":"42e0916e0dda5f6d1e7bb05d8514717147c036a79c9f36085683469516c1fd3f","names":[],"sources":[]}, {"digest":"4312134fc6f9cad507c31390bd3d147535492dd77621ec517c5e85f853d53a03","names":[],"sources":[]}, - {"digest":"43e311235aa537df1bacdd92d144df8a952337a76e9ac892cdf670f1a797bad8","names":["packages/llm/llm/src/types.ts#ToolRemovalBlock"],"sources":["packages/llm/llm/src/types.ts:127"]}, + {"digest":"43e311235aa537df1bacdd92d144df8a952337a76e9ac892cdf670f1a797bad8","names":["packages/llm/llm/src/types.ts#ToolRemovalBlock"],"sources":["packages/llm/llm/src/types.ts:134"]}, {"digest":"44818000e56acb97afdb5045ce235eb55e3fb1ccabc9fc7d0750bb38f36a7f8e","names":[],"sources":[]}, {"digest":"44c8c77aa9aa100b0d74d2deee85474b29faa6eee0ac0f662f7abe9931ddd7f2","names":[],"sources":[]}, {"digest":"4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986","names":[],"sources":[]}, @@ -238,7 +241,7 @@ {"digest":"45f2a07ea94573123b6ae14db787a40062dec3834f36d8be92c523d40ba28448","names":[],"sources":["packages/interaction/user-approval/src/types.ts:44"]}, {"digest":"477614bca595a9e7adb5a1870be446b9a8684f3ba8950259d6289f2d3b74f028","names":[],"sources":["packages/compaction/compaction-image-offload/src/projection.ts:25"]}, {"digest":"47e5d84f1a93450a78c7f3954b43990d0f629af7c034a56313e5deb63e772c1b","names":[],"sources":[]}, - {"digest":"47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180","names":["packages/llm/llm/src/types.ts#StreamChunk"],"sources":["packages/llm/llm/src/types.ts:470"]}, + {"digest":"47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180","names":["packages/llm/llm/src/types.ts#StreamChunk"],"sources":["packages/llm/llm/src/types.ts:496"]}, {"digest":"487b65c37bfedb8b72088c4107a0a90a6249701f6b26745f6d98f9b8a22b07c7","names":[],"sources":["packages/llm/llm/src/assistant-stream.ts:44"]}, {"digest":"48e5c9861f16ac07e78cb7b5ae9dabdf7bb85c58baed5a51b4ad275050ea58e3","names":[],"sources":[]}, {"digest":"48f9c19417a1abbedfa59f4667bba36b93ac2db407adf5e84cb3ba0de30942cb","names":[],"sources":[]}, @@ -251,10 +254,11 @@ {"digest":"4b259f7f8f0a44ad5e90b70a73553ced1df27012d126921d397ff403b6c86731","names":["packages/llm/llm/src/message.ts#ToolResultMessage"],"sources":["packages/llm/llm/src/message.ts:173"]}, {"digest":"4b7ddaf3710b88ff9b8df66304f5f97bf03688fd19730eedc2e9535203c820ea","names":[],"sources":[]}, {"digest":"4bb451330ff699f36b45539ceb0eb2606ead72084e2c5bb637c36cc80e2252db","names":[],"sources":["packages/core/session/src/types.ts:198"]}, - {"digest":"4cd48f3e5108bd6ebedf7301c3638839b8b2b9db8dbd493974177fbdeb91a01b","names":["packages/api/session-controller/src/types.ts#SessionRequestId","packages/attachment/attachment/src/brand.ts#AttachmentId","packages/compaction/compaction/src/brand.ts#CompactionId","packages/core/session/src/types.ts#SessionId","packages/experimental/agent-team/src/types.ts#TeamId","packages/experimental/agent-team/src/types.ts#TeamMessageId","packages/experimental/agent-team/src/types.ts#TeamTaskId","packages/experimental/webhook/src/brand.ts#WebhookDeliveryId","packages/experimental/webhook/src/brand.ts#WebhookRuleId","packages/experimental/webhook/src/brand.ts#WebhookSourceId","packages/feedback/message-feedback/src/types.ts#MessageFeedbackVersion","packages/goal/goal/src/types.ts#GoalId","packages/interaction/commands/src/brand.ts#CommandId","packages/interaction/user-approval/src/types.ts#ApprovalRequestId","packages/jobs/jobs/src/brand.ts#JobId","packages/llm/llm-retry/src/brand.ts#RetryId","packages/llm/llm/src/brand.ts#MessageId","packages/llm/llm/src/brand.ts#ProviderRequestId","packages/llm/llm/src/brand.ts#ReasoningEffortId","packages/llm/llm/src/brand.ts#ToolCallId","packages/schedule/schedule/src/types.ts#ScheduleId","packages/session/session-title/src/index.ts#SessionTitleProviderId","packages/session/session-title/src/types.ts#SessionTitleProviderId","packages/workflow/workflow/src/types.ts#WorkflowRunId"],"sources":["packages/api/session-controller/src/types.ts:380","packages/attachment/attachment/src/brand.ts:6","packages/compaction/compaction/src/brand.ts:4","packages/core/session/src/types.ts:21","packages/experimental/agent-team/src/types.ts:20","packages/experimental/agent-team/src/types.ts:32","packages/experimental/agent-team/src/types.ts:8","packages/experimental/webhook/src/brand.ts:12","packages/experimental/webhook/src/brand.ts:6","packages/experimental/webhook/src/brand.ts:9","packages/feedback/message-feedback/src/types.ts:14","packages/goal/goal/src/types.ts:17","packages/interaction/commands/src/brand.ts:31","packages/interaction/user-approval/src/types.ts:17","packages/jobs/jobs/src/brand.ts:19","packages/llm/llm-retry/src/brand.ts:4","packages/llm/llm/src/brand.ts:16","packages/llm/llm/src/brand.ts:31","packages/llm/llm/src/brand.ts:43","packages/llm/llm/src/brand.ts:67","packages/schedule/schedule/src/types.ts:14","packages/session/session-title/src/index.ts:42","packages/session/session-title/src/types.ts:17","packages/workflow/workflow/src/types.ts:13"]}, + {"digest":"4cd48f3e5108bd6ebedf7301c3638839b8b2b9db8dbd493974177fbdeb91a01b","names":["packages/api/session-controller/src/types.ts#SessionRequestId","packages/attachment/attachment/src/brand.ts#AttachmentId","packages/compaction/compaction/src/brand.ts#CompactionId","packages/core/session/src/types.ts#SessionId","packages/experimental/agent-team/src/types.ts#TeamId","packages/experimental/agent-team/src/types.ts#TeamMessageId","packages/experimental/agent-team/src/types.ts#TeamTaskId","packages/experimental/webhook/src/brand.ts#WebhookDeliveryId","packages/experimental/webhook/src/brand.ts#WebhookRuleId","packages/experimental/webhook/src/brand.ts#WebhookSourceId","packages/feedback/message-feedback/src/types.ts#MessageFeedbackVersion","packages/goal/goal/src/types.ts#GoalId","packages/interaction/commands/src/brand.ts#CommandId","packages/interaction/user-approval/src/types.ts#ApprovalRequestId","packages/jobs/jobs/src/brand.ts#JobId","packages/llm/llm-retry/src/brand.ts#RetryId","packages/llm/llm/src/brand.ts#MessageId","packages/llm/llm/src/brand.ts#ProviderRequestId","packages/llm/llm/src/brand.ts#ReasoningEffortId","packages/llm/llm/src/brand.ts#ToolCallId","packages/schedule/schedule/src/types.ts#ScheduleId","packages/session/session-title/src/index.ts#SessionTitleProviderId","packages/session/session-title/src/types.ts#SessionTitleProviderId","packages/workflow/workflow/src/types.ts#WorkflowRunId"],"sources":["packages/api/session-controller/src/types.ts:388","packages/attachment/attachment/src/brand.ts:6","packages/compaction/compaction/src/brand.ts:4","packages/core/session/src/types.ts:21","packages/experimental/agent-team/src/types.ts:20","packages/experimental/agent-team/src/types.ts:32","packages/experimental/agent-team/src/types.ts:8","packages/experimental/webhook/src/brand.ts:12","packages/experimental/webhook/src/brand.ts:6","packages/experimental/webhook/src/brand.ts:9","packages/feedback/message-feedback/src/types.ts:14","packages/goal/goal/src/types.ts:17","packages/interaction/commands/src/brand.ts:31","packages/interaction/user-approval/src/types.ts:17","packages/jobs/jobs/src/brand.ts:19","packages/llm/llm-retry/src/brand.ts:4","packages/llm/llm/src/brand.ts:16","packages/llm/llm/src/brand.ts:31","packages/llm/llm/src/brand.ts:43","packages/llm/llm/src/brand.ts:67","packages/schedule/schedule/src/types.ts:14","packages/session/session-title/src/index.ts:42","packages/session/session-title/src/types.ts:17","packages/workflow/workflow/src/types.ts:13"]}, + {"digest":"4d60dddaa65d3da8d4cd014d85ce3d2c2875664dd0433e331d8e9d395289686b","names":["packages/experimental/liveshare/src/host/viewer-principal.ts#ShareViewerPrincipal"],"sources":["packages/experimental/liveshare/src/host/viewer-principal.ts:24"]}, {"digest":"4e011753f8263f436efaabfbb3b4db53a98fc55342c5ded2daf7208b217be159","names":[],"sources":[]}, {"digest":"4e44c9118152f6829634bfd508e47669ab0497caffa380c94b4be91f9390d35d","names":[],"sources":[]}, - {"digest":"4e887768586528565381dadbddee6cef555874148089f4579e0b4b1ad096fc9c","names":["packages/llm/llm/src/types.ts#TextBlock"],"sources":["packages/llm/llm/src/types.ts:62","packages/web/web-search-deepseek/src/provider.ts:66"]}, + {"digest":"4e887768586528565381dadbddee6cef555874148089f4579e0b4b1ad096fc9c","names":["packages/llm/llm/src/types.ts#TextBlock"],"sources":["packages/llm/llm/src/types.ts:69","packages/web/web-search-deepseek/src/provider.ts:66"]}, {"digest":"4e97c3d85c0fc817ee58873c38c25a2474abaaa0af4839311b50b68db3b8cf1a","names":["packages/subagent/subagent/src/continuation-messages.ts#SubagentSettledMessageSource"],"sources":["packages/subagent/subagent/src/continuation-messages.ts:29"]}, {"digest":"4edec1b770e8ec4ce1220bf42edc5ac46713a1b48d4caa778dcfc98bad1f28a3","names":[],"sources":[]}, {"digest":"4f507598cf476214aa7646ce7841a7064a9dcb05d0a1eaaefaf79c2b738f160f","names":[],"sources":[]}, @@ -271,6 +275,7 @@ {"digest":"530da6c0267813bb4511af72883cc518834e624e3b3220a7062955fd57a788a6","names":["packages/core/session/src/types.ts#RequestHeaderReason"],"sources":["packages/core/session/src/types.ts:279"]}, {"digest":"53750b9abf61efb7992b0aadc3e247ec927449c63266df28230fd1139f5590ac","names":[],"sources":[]}, {"digest":"53cf1704ae0709c7678bcf070c83c619fc48ca1b5c173b74cfa8702f22a8e492","names":[],"sources":[]}, + {"digest":"53d4f8256bc58109468ea358ac54d437760cd765012360cafe72a401e6a41d4a","names":[],"sources":["packages/core/session/src/types.ts:317"]}, {"digest":"54f9276a1617d7c12594722c89cfe864bcbe4517e9a6f9c98bab14f199a135e0","names":[],"sources":["packages/core/session/src/types.ts:363"]}, {"digest":"557e148d30b79ee48645850832b30c717d7c3b64641deb5d6133b8b4e91ee0b8","names":[],"sources":[]}, {"digest":"5654685d7557ec747e74887237065e626a5bdfa426ca43f7fbb0b6fee9b0916c","names":[],"sources":[]}, @@ -280,14 +285,14 @@ {"digest":"5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc","names":[],"sources":[]}, {"digest":"57f3f606ff8b6c84d9c443faace9d1dd10cca0354f37a4f515ef075f7c351b90","names":[],"sources":[]}, {"digest":"58015da1c1950a66daf66ae24913d6a1fc6d1d9ac441b155f8847f7f8584ba8e","names":[],"sources":[]}, - {"digest":"5808e36c95355f0e745201b5db1b6bcec4ebf5adb75d3e82d7d59cc89635ab80","names":["packages/llm/llm/src/types.ts#FinishReason"],"sources":["packages/llm/llm/src/types.ts:165"]}, + {"digest":"5808e36c95355f0e745201b5db1b6bcec4ebf5adb75d3e82d7d59cc89635ab80","names":["packages/llm/llm/src/types.ts#FinishReason"],"sources":["packages/llm/llm/src/types.ts:172"]}, {"digest":"587bb11da730e06aa52b62c087d217d6f8f22459b25f31cb9e1e1baf17944e5e","names":[],"sources":[]}, {"digest":"589d0d91239681f89ee485459dc8c2f73ea47183b5534289d966637024a2c35d","names":[],"sources":[]}, - {"digest":"58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019","names":[],"sources":[]}, {"digest":"58f94390b982f8a5ac1f4f235ba612557f4a1dc4a995d8b1cec63ce7639decb0","names":[],"sources":[]}, {"digest":"5abab3a27fd2736660ecddd94b28d6bbf114986dd894880153bd1be3ccacb563","names":[],"sources":[]}, {"digest":"5b232a9b9bfcc0fc6794dab7865bcf203a65785c5de5aa647a51228bff628413","names":[],"sources":[]}, {"digest":"5b6fb1f226ff56402db08a6aae82af76100b14056271875f69ec526a1ae05d51","names":[],"sources":["packages/interaction/commands/src/types.ts:112"]}, + {"digest":"5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451","names":[],"sources":[]}, {"digest":"5bb69b88517f6214f2af4d1a6d2b771e271ad3ad695cc9c2c272069ae698c9bc","names":[],"sources":[]}, {"digest":"5bc66269cfaf614c0ecda8ecb469f23101a7609793fc2b693ac23c4aecdb575e","names":[],"sources":[]}, {"digest":"5bd310104cfe448e530beb11422d2f791e2e32e8e95fdc528a15f9ca693dae75","names":[],"sources":[]}, @@ -295,7 +300,6 @@ {"digest":"5cb63db9fe57dc09c3a1c2b84c3edf73ff5b62960155d8436a2377a5c43ce32c","names":[],"sources":[]}, {"digest":"5cc512378245b2dfad1cf88a732c05d86e41c91408421f2fff2b3b0a06557974","names":[],"sources":[]}, {"digest":"5cdbf342b7748d152bc987b68f58e565e5bba4b227e076e2d2120d87662e45cd","names":[],"sources":[]}, - {"digest":"5d00abf938272f22eb47199e9d40801e8d8ec4c88e2b138b15aa2a5a5bf87520","names":[],"sources":[]}, {"digest":"5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78","names":[],"sources":[]}, {"digest":"5d17f27a1ef9f7026c0232714adf7573961536d75f3303ca97973975f5af170e","names":[],"sources":[]}, {"digest":"5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694","names":[],"sources":[]}, @@ -303,8 +307,7 @@ {"digest":"5dd766ccd1702a1142ad8b4bd44f2242f8e8a6752669ad3de0a5d224329b1438","names":[],"sources":["packages/compaction/compaction/src/types.ts:82"]}, {"digest":"5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e","names":[],"sources":[]}, {"digest":"5ebce1317eacd2c148456627a09668e927ee15c204f0643f5ea76b46b54a2647","names":[],"sources":[]}, - {"digest":"5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be","names":[],"sources":[]}, - {"digest":"5f2117d1856a5ab43c28371faa978ebfaa48f8c7d734ea3fc94842210df83dca","names":["packages/llm/llm/src/types.ts#LlmFailure"],"sources":["packages/llm/llm/src/types.ts:41"]}, + {"digest":"5f2117d1856a5ab43c28371faa978ebfaa48f8c7d734ea3fc94842210df83dca","names":["packages/llm/llm/src/types.ts#LlmFailure"],"sources":["packages/llm/llm/src/types.ts:48"]}, {"digest":"5f26a6c20b37632f8f57729d171c671def4683d994ac6257a8dffcd855101627","names":[],"sources":[]}, {"digest":"5f758f3de5f00c18968a7c6d347083aac5c9ae13f6a79c78f6611b23c4973564","names":["packages/subagent/subagent/src/descriptor.ts#OneShotSubagentDescriptorData"],"sources":["packages/subagent/subagent/src/descriptor.ts:61"]}, {"digest":"6085488d223aeffdef51d7ae17655fc26ab22ee13cbed82a50e62e2b6fb5b918","names":[],"sources":[]}, @@ -315,9 +318,11 @@ {"digest":"62e6a429ff3f390a46ac39fb468692032f42936ca0db19b53454184189401379","names":[],"sources":[]}, {"digest":"62ecb62dc0fe1b5e70217f8a80c39256a40ee3a1917be14e5ca899d20c35f7fd","names":[],"sources":[]}, {"digest":"6487b10ba7542f3c447b1e41a1c6a590b7bfafe0b9b66b49f34028da85bb970f","names":["packages/subagent/subagent/src/descriptor.ts#ContinuableSubagentDescriptorData"],"sources":["packages/subagent/subagent/src/descriptor.ts:72"]}, + {"digest":"64ef542b1bfc988382d337f2ea85aab8ad76ea55341cf082163919d315688428","names":["packages/llm/llm/src/message.ts#DeveloperMessage"],"sources":["packages/llm/llm/src/message.ts:157"]}, {"digest":"6598cd6da253948d6b207c6374a45335804c79b576866d6215649c2d1bc85e25","names":["packages/experimental/agent-team/src/types.ts#TeamMemberSnapshot"],"sources":["packages/experimental/agent-team/src/types.ts:50"]}, {"digest":"65a8400e451e667e5b6e34df72ceb81fca8c12330330fa72083ad40279b189ad","names":["packages/llm/llm/src/message.ts#SystemPromptMessageSource"],"sources":["packages/llm/llm/src/message.ts:35"]}, - {"digest":"66ba70f6f068da443f969a0b947a013c3addd776b9b60a0a393759c19825e9a2","names":["packages/llm/llm/src/types.ts#ToolSchema"],"sources":["packages/llm/llm/src/types.ts:491"]}, + {"digest":"65d583e66518c5236015e0846470fb32efcf92375ed306aef14e50a9d2cd2099","names":["packages/skill/tool-skill/src/index.ts#SkillCatalogSource"],"sources":["packages/skill/tool-skill/src/index.ts:35"]}, + {"digest":"66ba70f6f068da443f969a0b947a013c3addd776b9b60a0a393759c19825e9a2","names":["packages/llm/llm/src/types.ts#ToolSchema"],"sources":["packages/llm/llm/src/types.ts:517"]}, {"digest":"671fc8cbd3a924961ccfeada2462f460120381a806c7dc97a2c01ba6a74ac960","names":[],"sources":[]}, {"digest":"672c4aa2a9b736e3d6e5da6346d2e2ed5e3573f2d0baafa18e7407c9f3fee3db","names":["packages/skill/skill/src/index.ts#SkillInvocationSource"],"sources":["packages/skill/skill/src/index.ts:146"]}, {"digest":"67d5f73ceae82f5265258142ad6cf172de2c1fef93ba551b7f0454e0a93bffe0","names":["packages/llm/llm/src/call-config.ts#LlmCallConfig"],"sources":["packages/llm/llm/src/call-config.ts:31"]}, @@ -325,10 +330,11 @@ {"digest":"688e853dc149f0d30b31765c12ec7e3be74169bdf1a4c6463a10b945d50cc1b8","names":[],"sources":[]}, {"digest":"68f44f59e91c41395076cb77265981a601680ec8a381bbbeb6ab754ffdc94573","names":[],"sources":[]}, {"digest":"69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1","names":[],"sources":[]}, - {"digest":"693f4952fb5565da96c06bace8924b098ac2fbc915fde0ff8019701183abc057","names":[],"sources":["packages/llm/llm/src/types.ts:161"]}, + {"digest":"693f4952fb5565da96c06bace8924b098ac2fbc915fde0ff8019701183abc057","names":[],"sources":["packages/llm/llm/src/types.ts:168"]}, {"digest":"69d238a6e9b08d67f601b1825962963d8d3523cb69ebf6208c697dc5d058c199","names":[],"sources":[]}, {"digest":"6ab45ac76839722df912f3ba50f1c6b41f2d614bde11f1aabfae04117ccdc80d","names":[],"sources":[]}, {"digest":"6b23ed9ce1b397e602788dbe033693bf97642a69e23fcab1cc45bf6f13b6d619","names":[],"sources":[]}, + {"digest":"6ba7edb6447b6a3e7947dddf5e4116c1526000c4e62882a6d65edc67ba797c2c","names":[],"sources":[]}, {"digest":"6bbe793f6a93dc8d50a4d4d3fbb6f8ed15650bcb7e151d28669628f7b7c3fc25","names":["packages/goal/goal/src/types.ts#GoalSnapshot"],"sources":["packages/goal/goal/src/types.ts:60"]}, {"digest":"6bc8e51124d0874bc89e1d0ceff381a9c3cd0fc240667d69f841ce4f60f65fe5","names":[],"sources":["packages/core/session/src/types.ts:338"]}, {"digest":"6c03546143cdf6ae88f1745ac98c5139efa1588d1415249bbc5f3104d32ab800","names":[],"sources":["packages/core/session/src/types.ts:196"]}, @@ -337,7 +343,6 @@ {"digest":"6ccb6bc423fb3952458abf9c1b1c3284208b7e660344b612cc55da773d61afe4","names":[],"sources":[]}, {"digest":"6cda0d6d3b4336d83998fe580628426df81c2afbab5d768b8813b56d569120e8","names":[],"sources":[]}, {"digest":"6cf082d0fb6034dea61636787ff0ddf43b6e59aad71e644435a479bc9b83ad65","names":[],"sources":[]}, - {"digest":"6dacb1584f2bfbe209dc6b6f578d51da6d55595f64d0e63c727c98f359278def","names":[],"sources":["packages/api/session-controller/src/types.ts:389"]}, {"digest":"6e52dd55a1d48954ed5464ec46fe34d9eb65f709baabc9561e7a279910b0c406","names":[],"sources":["packages/preset/agent-preset-registry/src/session.ts:30"]}, {"digest":"6ea608bdc8a7a63d3d23b84c49721325094db88d136482e43a820945295eee3e","names":[],"sources":[]}, {"digest":"6ebcc2dbec9f2dabca9f668ae6d39e877899b180740570f453409db339221df3","names":[],"sources":[]}, @@ -348,47 +353,48 @@ {"digest":"6f72ece8f317cd080c4f20a93f1bf709965f5b81ac4669528f5a023191cfcf20","names":["packages/llm/llm-retry/src/types.ts#LlmRetryStartedEventData"],"sources":["packages/llm/llm-retry/src/types.ts:43"]}, {"digest":"6f9e00383836275e46c0a9915767f9bb561be5fc30aae490174908a93e99a912","names":[],"sources":[]}, {"digest":"70b082fe78991edf13cf66e1b4d06cd2dcff9cacfd76f8cfb996bfb61939e7b2","names":[],"sources":[]}, + {"digest":"70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f","names":[],"sources":[]}, {"digest":"7180844e1066230c5e891f1b9ccd942423b0fe48aac6ded7eef2a285b288a732","names":[],"sources":[]}, {"digest":"719c51f67074f97034a6c94297fe1f4b5d3c8d392c57586dab732aa5398c7a91","names":["packages/llm/llm/src/message.ts#ModelMessageSource"],"sources":["packages/llm/llm/src/message.ts:24"]}, {"digest":"71bb3254ec8f1e491ce63b762a7b5f18709de23aa4e8abcc8b886f4b6ce051dd","names":[],"sources":["packages/llm/llm/src/assistant-stream.ts:28"]}, {"digest":"72ec79127a9c0d0241b1106a74cc2b24c81ce467170f1c3c93f7b71a9496d227","names":[],"sources":[]}, {"digest":"7382c4fc95fe8c5db65ca4d9da572b115d0dbb818b7f32c22ab040318ffbb4bc","names":[],"sources":[]}, - {"digest":"7404c6123fdaa591474a37979a5a8ae70d1387af7c9f09bfe568b218935a974d","names":[],"sources":["packages/core/session/src/types.ts:317"]}, {"digest":"750a2b129d67704df675c06823c20c80b65cbae89d5aaa914fd5a72e3df395b5","names":["packages/jobs/jobs/src/types.ts#JobSettleCause"],"sources":["packages/jobs/jobs/src/types.ts:247"]}, {"digest":"7554565be416b0342053ee6a46256c9dab07c487349b4a5f10bab1edc151c619","names":[],"sources":[]}, {"digest":"756b5e23a5cb2c7f486f366a828f7461c88902af21125bd6810881f4ccbff6cc","names":[],"sources":[]}, - {"digest":"7580e7d96dc8475fffe813a42af499665de3d4517fcdb3bc2337d0340e98d616","names":["packages/llm/llm/src/message.ts#DeveloperMessage"],"sources":["packages/llm/llm/src/message.ts:157"]}, {"digest":"7624ca28c61ca0eaa4f015140f3cea6e0c16cce2f2960fab5f531203d253903e","names":[],"sources":[]}, {"digest":"763c8a20af487263a0080548274f7437ef4a86e0ba8769127d1ced10a72c664d","names":[],"sources":[]}, {"digest":"76632533f67879dcb346fcae640540dbc89b2472b0bce88c59f7e48fc5c0e668","names":[],"sources":[]}, {"digest":"78a9be340090b735a39980e7222ce730c972fbcf1de7c9e0aef2125884b7caee","names":[],"sources":[]}, - {"digest":"78b9204976ab9faaf133c3488b73d1dfb6f1a4bb6c0903e3473cd41a5e1e39e1","names":[],"sources":[]}, {"digest":"79650cfa10aa3c52440328d85e8a25f0ffadc8d7efd784e3c0819d8bb74a1985","names":[],"sources":["packages/core/session/src/types.ts:218"]}, {"digest":"79ddc907312f97cf9553d4841e8b3fc937097bd8d97900a790efad3c05255e99","names":[],"sources":["packages/todo/tool-todo/src/types.ts:33"]}, - {"digest":"7a5b68bd1a5118c827df9e2466acc5e4d16b83e3f97a2304d992958647592690","names":["packages/llm/llm/src/message.ts#MessageSource"],"sources":["packages/llm/llm/src/message.ts:136"]}, {"digest":"7a651f3b672c52fb615f22c0ce9cb3cc5b22aad92e6bbeefb0808fd7b9233a50","names":[],"sources":[]}, {"digest":"7af85bf70d4eafce63e739adae38ea85501e68df3a0e22f97f3a0be90fd9e4cb","names":[],"sources":[]}, {"digest":"7b1ce60193fa8b69292e5843858d9cee7dc565dcb40d33c136e5d7e8b8d4296a","names":[],"sources":[]}, + {"digest":"7c203f3d4dfa6638ff2601247cc7ca5d46731d2c614aa61217475b9eb1fbd0b3","names":[],"sources":[]}, {"digest":"7c6129b6961cf4b2a030f36c78d2b0a5be38617651a9b81322e054ee512bee06","names":["packages/feedback/message-feedback/src/types.ts#MessageFeedbackDelete"],"sources":["packages/feedback/message-feedback/src/types.ts:46"]}, {"digest":"7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397","names":[],"sources":[]}, {"digest":"7d226b9fd95b4ba213d4237c22e930a91c3c769c95ca7f92977b9d625ba13438","names":["packages/goal/goal/src/domain.ts#GoalChangeMeta"],"sources":["packages/goal/goal/src/domain.ts:44"]}, {"digest":"7d54a5a5e629e2e7783bfac72683bcc5e969e9f43426b9289826aaf294ff6344","names":["packages/feedback/command-feedback/src/types.ts#FeedbackRecord"],"sources":["packages/feedback/command-feedback/src/types.ts:27"]}, - {"digest":"7d65acf0a3a43a8f445ce5d3320b42eca492739fc931b2a7516bfb8368dc2c68","names":["packages/llm/llm/src/types.ts#ContentBlockType"],"sources":["packages/llm/llm/src/types.ts:148"]}, + {"digest":"7d65acf0a3a43a8f445ce5d3320b42eca492739fc931b2a7516bfb8368dc2c68","names":["packages/llm/llm/src/types.ts#ContentBlockType"],"sources":["packages/llm/llm/src/types.ts:155"]}, {"digest":"7df62978a2b7de8540e714152297743e0a622209a46a5ac9513fc0fad73ca23b","names":[],"sources":[]}, + {"digest":"7e9f1072c17f7aa86547c9c8b02766c1006d866a1859a3d677a336e932f70d1a","names":["packages/llm/llm/src/message.ts#MessageSource"],"sources":["packages/llm/llm/src/message.ts:136"]}, {"digest":"7eaef7a763ba5b949b8464bc8add8980a3a5ab566014b69787aeba71e5dfe07b","names":[],"sources":[]}, {"digest":"7f13860ee89a2d35ce09f958e85a04566cd59cb1de1d73a9619a9b631961dc71","names":[],"sources":[]}, {"digest":"7f7fd5a6b0064f597534b29ff62ef26e786dffccf5e14f654a7d4fcea2c35f04","names":[],"sources":[]}, {"digest":"7f9365bae9fcb73e1e34061a1acfe0422c1a5fd351848cace9bebbe806f28462","names":["packages/workflow/tool-workflow/src/types.ts#ToolWorkflowRunEndData"],"sources":["packages/workflow/tool-workflow/src/types.ts:36"]}, {"digest":"7f959241c24128b4983b559984811861dc59774b85905c8fa57c6cb0148a3dbc","names":["packages/goal/goal/src/domain.ts#GoalMessageSource"],"sources":["packages/goal/goal/src/domain.ts:47"]}, - {"digest":"8064c03c87c357fd1575cb9395ce86e6dcbe2d275bf7717864a02cddf01827d5","names":["packages/llm/llm/src/types.ts#ContentBlock"],"sources":["packages/llm/llm/src/types.ts:150"]}, + {"digest":"7ff62f6599c083ceb5a0d7a8940ff85ba80dc1d7ddd6ba9339903e93f74cba54","names":["packages/session/session-title-llm/src/index.ts#SessionTitleLlmRequestEventData"],"sources":["packages/session/session-title-llm/src/index.ts:43"]}, + {"digest":"8064c03c87c357fd1575cb9395ce86e6dcbe2d275bf7717864a02cddf01827d5","names":["packages/llm/llm/src/types.ts#ContentBlock"],"sources":["packages/llm/llm/src/types.ts:157"]}, {"digest":"80677c8c8b804189a0fde8aa70dd4ad7af8bb12dfd03027e8e023c8592c838bc","names":[],"sources":[]}, {"digest":"8067b0d232c350f189738e60ee3c9939d46ca3b32b45db5525237b077893f649","names":[],"sources":[]}, {"digest":"811229eedcec57979dbadca7dbea832a59f8580cff30cb217fca5e2da16314bd","names":[],"sources":[]}, - {"digest":"814d9434e1ddf9078612b3b34322f26e9363b469213335007f7e9ba7fee9464e","names":["packages/llm/llm/src/types.ts#ReasoningBlock"],"sources":["packages/llm/llm/src/types.ts:68"]}, + {"digest":"814d9434e1ddf9078612b3b34322f26e9363b469213335007f7e9ba7fee9464e","names":["packages/llm/llm/src/types.ts#ReasoningBlock"],"sources":["packages/llm/llm/src/types.ts:75"]}, {"digest":"82470020b5bfcb1a843e2aa05602af7d37df99e82d01f015c7c589ba054fd89d","names":[],"sources":[]}, + {"digest":"824a4aad44a54e245c67196817d67946734a2dc0eee0b0b6834a5b2a6ef352ce","names":[],"sources":[]}, {"digest":"825ca23416b1ea9d81442afead5cf9229a6fa05842f042135cc3aa9710a6a2d8","names":[],"sources":[]}, {"digest":"829a2fb3be6efd4ba36aef8ed2d381a4c6fb2a0aaf50c823a6f3f8290786b809","names":[],"sources":[]}, - {"digest":"83079c8a3f733ac3fa603eefa0fbb4737ca4d8b69e7e2e7298b60f9ac4098693","names":[],"sources":["packages/skill/tool-skill/src/index.ts:41"]}, + {"digest":"83079c8a3f733ac3fa603eefa0fbb4737ca4d8b69e7e2e7298b60f9ac4098693","names":[],"sources":["packages/skill/tool-skill/src/index.ts:43"]}, {"digest":"8338ee303e2bd448e9e6144069942f63e3cfd5868962bddc9347d7009e8919d6","names":[],"sources":[]}, {"digest":"83d6916021eede8f2d83a1872716caa1efdec39a3681890996c55147187fdd12","names":[],"sources":[]}, {"digest":"83da72c6857601c75da11212ef847f57d457b9c99f0a82246dcdff3e26700239","names":["packages/context/agent-instructions/src/render.ts#AgentInstructionChange"],"sources":["packages/context/agent-instructions/src/render.ts:62"]}, @@ -405,18 +411,18 @@ {"digest":"871bfd6f7bb91061246768d3377f3fd58d6b8ea7c31f44c714ae7ab215650d62","names":[],"sources":[]}, {"digest":"87b1a33564b9a4d63b00988a524c12259243953aebb9c9a05127d87b27464df9","names":[],"sources":[]}, {"digest":"88841202942c7683b3b7e5ea6a796047ec326b6701ac23e58cc236d85613b9fa","names":[],"sources":[]}, - {"digest":"88a610b831be6d92612a464be5c7d0b88ec24d97bd299837bf74bf7672183c9a","names":[],"sources":["packages/llm/llm/src/types.ts:474"]}, + {"digest":"88a610b831be6d92612a464be5c7d0b88ec24d97bd299837bf74bf7672183c9a","names":[],"sources":["packages/llm/llm/src/types.ts:500"]}, {"digest":"8a046b52331959aa3394680d6acbe09b8a5447c6b61375f263445bfcef19b7f1","names":[],"sources":[]}, {"digest":"8a6e1ec9e8db346b0e02f027db73c07a94f067a26d40c1aef1abd09c47ce7ba0","names":[],"sources":[]}, {"digest":"8a9c990773f798eac10ca8878e6bcc531ee080bc589cac956730e462cc6a09ad","names":[],"sources":["packages/interaction/permission-presets/src/index.ts:53"]}, {"digest":"8ad45ad053b4d89f8865c17cc9ff3b8748e86045f3f0fb816269a34af2619141","names":[],"sources":["packages/experimental/hook-protocol/src/types.ts:31"]}, {"digest":"8af841fc9b265ade3441caf9fe40dd24db24226befba48150e6d0eeccc1389c3","names":[],"sources":[]}, - {"digest":"8bb8c3751a6ce64b61aba1ec7ae798c00a5803c4d868a0430873216c6569ed52","names":[],"sources":["packages/session/session-log-deepseek/src/types.ts:81"]}, + {"digest":"8bb8c3751a6ce64b61aba1ec7ae798c00a5803c4d868a0430873216c6569ed52","names":[],"sources":["packages/session/session-log-deepseek/src/types.ts:96"]}, {"digest":"8c1c4f72755a78ea163523a46565316e36e9b644382eb48e6635c71a6f412dd2","names":[],"sources":[]}, {"digest":"8c627d7a45fa406cea879a3922105e27ed4c3c7966e264afaf11ea7a330f2dd1","names":[],"sources":[]}, {"digest":"8cdd3fdd295cee53035de16a1b23411716f75e9f994fe9510cac5d7fef605c76","names":[],"sources":[]}, - {"digest":"8e31bb958e9b015e6f8407eaade32217068159e816f3cc99c3ad76eb889732e0","names":[],"sources":["packages/llm/llm/src/types.ts:160"]}, - {"digest":"8e611bf46821e5003a1605a73560a6f56388295149d449dfe2142d5ec335f29c","names":["packages/llm/llm/src/types.ts#ToolAdditionBlock"],"sources":["packages/llm/llm/src/types.ts:115"]}, + {"digest":"8e31bb958e9b015e6f8407eaade32217068159e816f3cc99c3ad76eb889732e0","names":[],"sources":["packages/llm/llm/src/types.ts:167"]}, + {"digest":"8e611bf46821e5003a1605a73560a6f56388295149d449dfe2142d5ec335f29c","names":["packages/llm/llm/src/types.ts#ToolAdditionBlock"],"sources":["packages/llm/llm/src/types.ts:122"]}, {"digest":"8e8155594e07812356b67d732196dda894b0f9c91a5969d51612cf490b0a016d","names":[],"sources":[]}, {"digest":"8e8e91646a5cae3fc78f7532a0013ff2088ae47077642c2edd507a508209b8af","names":["packages/schedule/schedule/src/types.ts#OneShotScheduleDispatchChange"],"sources":["packages/schedule/schedule/src/types.ts:237"]}, {"digest":"8f324cea3916c0517261e88167def8efb3a9994c1135e23d40ed9fd48f8c7bd4","names":[],"sources":[]}, @@ -430,7 +436,7 @@ {"digest":"93cbbc5a7fd0b1aa1ff1b9a6bb5ec52b073f48e5a5200365c45c0cd54059e1b9","names":[],"sources":["packages/interaction/user-approval/src/types.ts:55"]}, {"digest":"93d38436347f67c9022aacbc4472e283d722bcab8eb73fc376aaf7b6a6b9fb35","names":[],"sources":[]}, {"digest":"94c56aeb1564ad735eb773d88636b40761d063efa1610f1308004d32923f5378","names":[],"sources":[]}, - {"digest":"95080295115fbd83544520ba247b68a03790131f6a2eac323d388758cb542f65","names":[],"sources":["packages/llm/llm/src/types.ts:472"]}, + {"digest":"95080295115fbd83544520ba247b68a03790131f6a2eac323d388758cb542f65","names":[],"sources":["packages/llm/llm/src/types.ts:498"]}, {"digest":"95a3ffccbf3c8afcf9a2f3b355f724da8e07e98dc47ee741166dde7f9ea058bd","names":[],"sources":[]}, {"digest":"95c0e88fcf0bafb2087f912ad9e2369de6ae6530cc0c4c2772c96205b57f7f60","names":[],"sources":[]}, {"digest":"9645cf93769a6dfb227bd400bd6cb9fa7bab9140f4a851e4ae92514ade6e3114","names":[],"sources":[]}, @@ -464,13 +470,13 @@ {"digest":"a15a19ef63cf5d1b711db1d249821dab0cedcd3a9ad09137b47352c93841fd20","names":[],"sources":[]}, {"digest":"a16e567c8cd2c55cf1e911aed3c200c4e1f6febb1459ff2a9e7adf159afb68cb","names":[],"sources":[]}, {"digest":"a2066bd52f61218ba15b758def2641cc6a8bd3d4a594a488ee4c65be356d7e39","names":[],"sources":[]}, - {"digest":"a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1","names":[],"sources":["packages/llm/llm/src/types.ts:477"]}, + {"digest":"a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1","names":[],"sources":["packages/llm/llm/src/types.ts:503"]}, {"digest":"a2be0f0cb59f0d4a06557d45847d1938aced238baa77a6da416e590b8b958553","names":[],"sources":[]}, {"digest":"a3a259a1aa5401af786ce08c4a8419681d3000d73467991b5fc563389bc4ebd2","names":[],"sources":[]}, {"digest":"a3c6f1ea38e9a61d7a9706057ba65aabe02dfe6d9dd90d4736aa62325d874531","names":[],"sources":[]}, - {"digest":"a3e299483348f27a4787a36bb3f29cd86024c65336abc10bb3d687468302c4cf","names":["packages/session/session-title-llm/src/index.ts#SessionTitleLlmRequestEventData"],"sources":["packages/session/session-title-llm/src/index.ts:37"]}, {"digest":"a3edd1efd1fef21b72c55e213c8a8b24196b091abde2b89db52be0b2aaae3cfa","names":[],"sources":[]}, {"digest":"a40d12070f6f4a124f32fb3cc86e7857554702e32f0eda3080a25c4b9ac9b18c","names":[],"sources":["packages/experimental/agent-team/src/types.ts:172"]}, + {"digest":"a4afec59b75aad5d13ef82d6931f35cc2d98918503916cf069355b77c5e42302","names":[],"sources":["packages/api/session-controller/src/types.ts:397"]}, {"digest":"a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc","names":[],"sources":[]}, {"digest":"a6b41f5bede8094d7bf635be5d69b1bd7a25e006ca9cf9415bceb9322f1a7feb","names":["packages/experimental/hook-protocol/src/types.ts#HookDialect"],"sources":["packages/experimental/hook-protocol/src/types.ts:48"]}, {"digest":"a6da9ad5d42ae83a6833a8288b076688e8e0801633ea36cbdd8a30a6d9f3160c","names":["packages/workflow/tool-workflow/src/types.ts#ToolWorkflowRunStartData"],"sources":["packages/workflow/tool-workflow/src/types.ts:14"]}, @@ -489,7 +495,7 @@ {"digest":"aa93010d0e521ad7c42273f58d5c9b8bf1dfc94edf1b805a3971b364a35c1877","names":[],"sources":[]}, {"digest":"aacda84a69739238aa782eea902d3073017d9d74b9808de2bf5a83c9738cbdc6","names":[],"sources":[]}, {"digest":"aae343bc3d663c83f2e8b5e1c7eea5d509dc7a5361bc8bd8b5ac3bb8d3b1ed56","names":[],"sources":[]}, - {"digest":"ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7","names":[],"sources":["packages/core/session/src/types.ts:220","packages/llm/llm/src/types.ts:159"]}, + {"digest":"ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7","names":[],"sources":["packages/core/session/src/types.ts:220","packages/llm/llm/src/types.ts:166"]}, {"digest":"aba175fb20ffc71112c55efe70458ff5d7dbfb83501892b4ba8d077f0ea5d7ba","names":[],"sources":[]}, {"digest":"abd6ca62a5ab166553848324a23fef90eed7f59c8021bd63e7ea5bc6fd666b0c","names":["packages/web/web-search-deepseek/src/provider.ts#DeepSeekSearchLlmRequest"],"sources":["packages/web/web-search-deepseek/src/provider.ts:55"]}, {"digest":"ad0c38a0adb82a94c925456df41586d9b5f9202fca18593eae2213d4445b4585","names":[],"sources":["packages/core/session/src/types.ts:398"]}, @@ -513,10 +519,8 @@ {"digest":"b222069eea2d768065161c1147b1f2c78c1b54328c84b3586ae5c8f91b8ed35e","names":[],"sources":[]}, {"digest":"b2245a906e13aa94f2d3cc6cf7b04cfa0267f7b7f4d468de1b00b1a314e54626","names":[],"sources":[]}, {"digest":"b2a5c8c008a31e3dc6c3013502f2356aca13894b31c8e70601fa92f2d40d1dba","names":[],"sources":[]}, - {"digest":"b2a948a5340a9341fa3bab99507c7090c5b0456de72ec28b5b157b8df3f1d640","names":[],"sources":["packages/core/agent/src/types.ts:110"]}, {"digest":"b2d2a01e51341a3bfec809198952c8c830a7899f4cb6ecd3c1dc0b5d9a2af943","names":["packages/experimental/agent-team/src/types.ts#TeamTaskStatus"],"sources":["packages/experimental/agent-team/src/types.ts:61"]}, {"digest":"b3681c026a0b98e98b103f057dfd217fbe904129c090efd668253ec9aea7fece","names":[],"sources":[]}, - {"digest":"b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e","names":[],"sources":[]}, {"digest":"b38f206d59bad891fa58c89f97a0036987b3defe7685acbd318fa55eb85f9751","names":[],"sources":[]}, {"digest":"b4ec0af39fd52ed971990e42f04e5be3204882e555c409eb330f8238eec21569","names":[],"sources":[]}, {"digest":"b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf","names":[],"sources":[]}, @@ -532,7 +536,6 @@ {"digest":"b6f94c17dd9bbd7cd57015198b7c7c88407f0e3b89faab176ca3c11c3d864d3e","names":[],"sources":[]}, {"digest":"b70f3e81fe11b7a5f2504fb47a4502fb8d9c8f0731fdfe8ddcaf9b41f5a6e196","names":[],"sources":[]}, {"digest":"b765ee31033cea463863faf3fc6a0a1b85c47c6a2f13fe1ce833abe56105114b","names":[],"sources":[]}, - {"digest":"b782058cef83caf3eb44a16adeef5657e4d5cdff2d50655aba418c4490670a69","names":["packages/llm/llm/src/message.ts#UserMessage"],"sources":["packages/llm/llm/src/message.ts:162"]}, {"digest":"b79641a9d25e756636dc0c706fdf3c4583ccb7d4920e009e6e86c0759cf4de4c","names":[],"sources":[]}, {"digest":"b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5","names":[],"sources":[]}, {"digest":"b815d7b91cdd9fc6ccc7dcba05cfc5ce1d55fab5fc0c0801803cd3630cedb602","names":[],"sources":[]}, @@ -556,7 +559,7 @@ {"digest":"bf16d2e98a7f13894ded2cffe5ce857bf473954a0e3c0ed9bc7739e2e1c7b78a","names":[],"sources":[]}, {"digest":"c0ea97bc89dfc46fa94eab956f5c3ee6af2f964aa7db6327cb18b451f207bef7","names":["packages/workflow/tool-workflow/src/types.ts#ToolWorkflowAgentEndData"],"sources":["packages/workflow/tool-workflow/src/types.ts:29"]}, {"digest":"c170da8ab7c37635b10867b2571811d9e317ac3ec394e8ff8efe53f902fc41c1","names":["packages/llm/llm-retry/src/types.ts#LlmRetryEventData"],"sources":["packages/llm/llm-retry/src/types.ts:16"]}, - {"digest":"c1f0f17b6493b85db6453bb30e01b208d703731b25bc1e68e5d4fc72eea9cdea","names":["packages/llm/llm/src/types.ts#ToolCallBlock"],"sources":["packages/llm/llm/src/types.ts:105"]}, + {"digest":"c1f0f17b6493b85db6453bb30e01b208d703731b25bc1e68e5d4fc72eea9cdea","names":["packages/llm/llm/src/types.ts#ToolCallBlock"],"sources":["packages/llm/llm/src/types.ts:112"]}, {"digest":"c1f9e0405de6d18cabb9ee70782a027f9bbdc57e5abec9dcccdd56119e2e9058","names":[],"sources":[]}, {"digest":"c219efbdfd53b836786202ab4532913d555798f0a8615a4e9629736e3799fb70","names":[],"sources":[]}, {"digest":"c2deb7c9183735d4e0fffddf5c623f4e34daa1c8e96b111982e957dfcbbcf896","names":["packages/workflow/workflow/src/types.ts#WorkflowAgentOutcome"],"sources":["packages/workflow/workflow/src/types.ts:110"]}, @@ -568,6 +571,7 @@ {"digest":"c589e938cc0e4989df8b82abef6339de621f0dc4fe62c230d145b94996af7f92","names":[],"sources":[]}, {"digest":"c592ce75aab73fcab19c1d7845684c72cf402b78d2e1f2833a58ecf9f3598ed6","names":["packages/util/values/src/index.ts#JsonValue"],"sources":["packages/util/values/src/index.ts:4"]}, {"digest":"c748fb42c80a120038a8c587af80ec39924803c401364db11c8974d5bf6d0262","names":[],"sources":[]}, + {"digest":"c78b9097bfae83cd08f0a98a92730236ba80ac61d712046959e4fc7f28aa1f36","names":["packages/llm/llm/src/message.ts#Message"],"sources":["packages/llm/llm/src/message.ts:196"]}, {"digest":"c8e6f48878cc2a2f0dc59682280d81f407943fb503f32c64bf9ff3d9393c3eff","names":[],"sources":[]}, {"digest":"c99e20441bf15341e9db54385e558e5c03d21dff2eb1ac08ccbf47c2d8747954","names":[],"sources":[]}, {"digest":"ca085dba2c877feceebf3c62f9d39c6c2a4d2314d97b94b3927a780fe8fe2bb2","names":[],"sources":[]}, @@ -577,15 +581,16 @@ {"digest":"cbca49bde16b656d5b8fbe4a8a507769f7b594c6287782b809c03814941bc5e3","names":[],"sources":[]}, {"digest":"cd186c309e2bef305705e1d324139240f5e681f4f6a957d6a25b0225f65560df","names":[],"sources":[]}, {"digest":"cda2345a9be9d139df49ccbd16dcba716f3440178bf20ff8b801fda1f5eb77dc","names":[],"sources":[]}, - {"digest":"cda79b839d8cc0c7a7bd09dd067de04925f6e9037080d878b65aaa5a383f117c","names":["packages/llm/llm/src/message.ts#Message"],"sources":["packages/llm/llm/src/message.ts:196"]}, {"digest":"cdca80b8dad24d4e7b1d5a288a8475ba8d8d46be385bd2da85f122ee836f1670","names":[],"sources":[]}, {"digest":"cdee10e87dbed8440d8b6935888624884878efc7af95402e94171b29f173dced","names":[],"sources":["packages/llm/llm-retry/src/types.ts:17"]}, + {"digest":"cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e","names":[],"sources":[]}, {"digest":"cef171adf021a1867d244618a3dbbaafc22beb17c7f3df3ee203393271c8c6f6","names":["packages/core/tool-executor-ptc/src/types.ts#PtcDispatchEventData"],"sources":["packages/core/tool-executor-ptc/src/types.ts:21"]}, {"digest":"cffcdc19881ab61ec0a9ce18743996f7ac44ac8889f34dfac36ae745574aa22f","names":["packages/goal/goal/src/domain.ts#GoalClearChangeMeta"],"sources":["packages/goal/goal/src/domain.ts:35"]}, {"digest":"d0fbb0ca1bbba059830826f33f801da1aced35a2504376d61e020bdfec8d50c0","names":[],"sources":[]}, {"digest":"d28765f87d6b6ab408e0b2f3e7e297791b004b806d8e302c49903ebae815feb2","names":[],"sources":[]}, - {"digest":"d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d","names":[],"sources":["packages/llm/llm/src/types.ts:475"]}, + {"digest":"d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d","names":[],"sources":["packages/llm/llm/src/types.ts:501"]}, {"digest":"d4c799e3d51cae1040362ba4968efc484739e14416c9c1df20c2f108b4ef2eb5","names":[],"sources":[]}, + {"digest":"d4d960185026266ed7bd127be1e252234689e8b4890c7c2677a644ba58f35401","names":[],"sources":["packages/core/agent/src/types.ts:110"]}, {"digest":"d4e4d575abeb4b72d616dc65c17ac0eaa943cc135609395044c38d5afcb10e31","names":[],"sources":[]}, {"digest":"d595ec73b32b016a6055333c67a5d646032b22e672da1d4a09c5b1ae398a093a","names":[],"sources":[]}, {"digest":"d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9","names":[],"sources":[]}, @@ -610,7 +615,7 @@ {"digest":"de25352d2dc4196309bd84b5bac6319f6d5c898ea0e82bb5ae66c5738d0d426f","names":[],"sources":[]}, {"digest":"de30b1fa12c75f81df6aa4096e1595296d2d04e2be14a7c29849cf8028b79048","names":[],"sources":[]}, {"digest":"deaae5cd30987d4f49398e8f9d994c125907e7f928300745fb1dbf15f145d0e7","names":[],"sources":[]}, - {"digest":"deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5","names":["packages/typert/protocol/src/types.ts#Principal"],"sources":["packages/typert/protocol/src/types.ts:457","packages/typert/protocol/src/types.ts:461"]}, + {"digest":"deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5","names":[],"sources":["packages/typert/protocol/src/types.ts:457"]}, {"digest":"df5d9709b7db2a72510dc52052a23f0c38f39730af1504bab8bccabc14fae528","names":[],"sources":[]}, {"digest":"df843efd87c78cf8de98f8e0d0216956cd568d0d0e56a22c853663e274aa1a18","names":[],"sources":[]}, {"digest":"dfce5db4aa42b7ebe0bb79eca92553587287e18c06b9eba85cbfb9d332e26acd","names":["packages/experimental/agent-team/src/types.ts#TeamMemberPhase"],"sources":["packages/experimental/agent-team/src/types.ts:47"]}, @@ -652,17 +657,16 @@ {"digest":"ef11a3b7fa2033ae4279545ff8a8a2ee4e301b9b73e5b91654c48e6d08283545","names":[],"sources":["packages/core/session/src/types.ts:305","packages/core/session/src/types.ts:307"]}, {"digest":"ef226a90ddac6cd8e631a3a337a3a3e27f9494be92befb7c718b404681d75e21","names":[],"sources":[]}, {"digest":"ef4f00923b9edbae15c7ef05320280bf61147ca17146cf59690359bfd5e5da45","names":[],"sources":[]}, - {"digest":"efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc","names":[],"sources":[]}, {"digest":"f05fb85e715af4ab4de0b6ba111166dd0435bd8bb74a0fa0f32b9d174113fc7c","names":[],"sources":[]}, {"digest":"f09e5e7acf5ff5ccd193ff2eeec015fa2ff7c29d98bc465f8c3302058d47e29b","names":["packages/core/agent/src/types.ts#ModelSelection"],"sources":["packages/core/agent/src/types.ts:79"]}, {"digest":"f1687f982fa3d41ef29e159feed154ecd13af4dd209acaee16038f223f2e9402","names":["packages/core/session/src/types.ts#TurnEndReason"],"sources":["packages/core/session/src/types.ts:238"]}, {"digest":"f1996af2602e6f62b5ab179ca5c4af00d8753938b74cc6ef102de09e99e74a7e","names":[],"sources":[]}, {"digest":"f19bee84bf3d20904553cdcd57465232bc1c2a194f54c4d195292ba0487223a6","names":["packages/attachment/attachment/src/types.ts#FileAttachmentRef"],"sources":["packages/attachment/attachment/src/types.ts:39"]}, - {"digest":"f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515","names":[],"sources":["packages/llm/llm/src/types.ts:476"]}, + {"digest":"f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515","names":[],"sources":["packages/llm/llm/src/types.ts:502"]}, {"digest":"f230c0b583e23b25ee0a61dbe4c05e95c1e2ae44b27939501eb9e03696f0c278","names":[],"sources":[]}, {"digest":"f29d63336e8266d80dd7baeab219436db86341304f6be1cd0edb36f5134c4a47","names":[],"sources":[]}, - {"digest":"f2da0f27c1e6add59982c37b15e4a4912c5b33466859cce3b13d503600e24aef","names":["packages/llm/llm/src/types.ts#FileBlock"],"sources":["packages/llm/llm/src/types.ts:98"]}, - {"digest":"f311671e07bc7fa645a0b6597de9966b97147956565296ba76a36543801b66c5","names":["packages/llm/llm/src/types.ts#SystemPromptUpdate"],"sources":["packages/llm/llm/src/types.ts:414"]}, + {"digest":"f2da0f27c1e6add59982c37b15e4a4912c5b33466859cce3b13d503600e24aef","names":["packages/llm/llm/src/types.ts#FileBlock"],"sources":["packages/llm/llm/src/types.ts:105"]}, + {"digest":"f311671e07bc7fa645a0b6597de9966b97147956565296ba76a36543801b66c5","names":["packages/llm/llm/src/types.ts#SystemPromptUpdate"],"sources":["packages/llm/llm/src/types.ts:440"]}, {"digest":"f4a66f654996c093aae700ea4c434ff2ee3569fea9c0e5813ccf6afdccabd163","names":[],"sources":[]}, {"digest":"f5520c1d261ca86ea03735799c311a0a9ede8babb588cf0a65422576d2ee0ad1","names":[],"sources":[]}, {"digest":"f56c5b59ca0161310c338d31dd16cf14287ccd602ff4181058df178c1c286d7f","names":["packages/context/session-reference/src/types.ts#SessionReferenceSource"],"sources":["packages/context/session-reference/src/types.ts:13"]}, @@ -685,15 +689,15 @@ {"digest":"fb5e0517050d2c6d40e5b8145db1f7c5ca7044d5d50fada6ff80e0b22c6ca973","names":[],"sources":[]}, {"digest":"fb8b6a2e53cb9cf44c551176de0fb77d1ddc60037b99a891ff8a860b6d5c29a0","names":[],"sources":[]}, {"digest":"fbd2c74b346a1595b376139c587fadd23e4a21acc9c0abce342975b6cfc60986","names":[],"sources":[]}, - {"digest":"fc2ae6962f9f8801c2b1e414668e1e17cbb7544c4f39381198977a38bd10c093","names":["packages/skill/tool-skill/src/index.ts#SkillCatalogSource"],"sources":["packages/skill/tool-skill/src/index.ts:35"]}, {"digest":"fc351843b8ecbd05d739c4ca4fcd4bc7cfad6c0beacbbd48389959bb1bf06cf3","names":[],"sources":[]}, {"digest":"fcf427290c6213c2a7feb57492d832ce324f5b9737a759f424dab69e6bd101a0","names":[],"sources":[]}, {"digest":"fcf81d3c58c13593bf2594e342e31734f4ab2d24938dc610875194c6079749c7","names":[],"sources":[]}, {"digest":"fd0d91a1f9dd2efb8959bdf5e07f8f0a98b1cdfa38ce8d4732ebde0b44c3abd4","names":[],"sources":[]}, {"digest":"fe1a7acdeed4d0f5ab483396eaa5b3dc97263b7c10eb4da2f0028cb01728bfc9","names":[],"sources":[]}, {"digest":"fe792a6cd430494503837e21e79f91677704ccdd9e870c679aabd7d43ed47ddd","names":[],"sources":[]}, - {"digest":"fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394","names":["packages/llm/llm/src/types.ts#TokenUsage"],"sources":["packages/llm/llm/src/types.ts:175"]}, - {"digest":"fee1caf8ab6a65c1bc981f5a1730164490f22a2a89ffa3d0b76f1f432c44c8b5","names":[],"sources":[]} + {"digest":"fec5442b9ee4122e10514d81d5a43648003fe8bfb7ee2ba50c0cdbdd383ed394","names":["packages/llm/llm/src/types.ts#TokenUsage"],"sources":["packages/llm/llm/src/types.ts:182"]}, + {"digest":"fee1caf8ab6a65c1bc981f5a1730164490f22a2a89ffa3d0b76f1f432c44c8b5","names":[],"sources":[]}, + {"digest":"ff2cbb53582d1827b02622482246979942f59e07e0393b76a161251423549e72","names":[],"sources":[]} ], "nodes": { "0116b1f89c05221d": {"kind":"literal","value":"web_search_20250305"}, @@ -712,6 +716,7 @@ "09f3f8dc417f2782": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"8af841fc9b265ade","optional":false},{"name":"source","type":"65a8400e451e667e","optional":false}],"indices":[]}, "0a30c3be336cdd4f": {"kind":"object","properties":[{"name":"kind","type":"1e0b0b66b6f0c53f","optional":false},{"name":"reason","type":"1f8c126cfab3df81","optional":false}],"indices":[]}, "0a8a062bc9c3c0d9": {"kind":"literal","value":"subagent/model-selection-policy"}, + "0a92c5bdfa06c2e2": {"kind":"object","properties":[{"name":"displayName","type":"4cd48f3e5108bd6e","optional":true},{"name":"providerId","type":"4cd48f3e5108bd6e","optional":false},{"name":"subjectId","type":"4cd48f3e5108bd6e","optional":false},{"name":"tenantId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "0aa62ab51b36c0e6": {"kind":"object","properties":[],"indices":[{"key":"4cd48f3e5108bd6e","value":"bbc5696e3f13c758"}]}, "0acd94fe8794574c": {"kind":"object","properties":[{"name":"blocks","type":"b1664fa89f8eab49","optional":true},{"name":"response","type":"bbc5696e3f13c758","optional":false}],"indices":[]}, "0af3ecfb8c60d416": {"kind":"literal","value":"turn/start"}, @@ -811,6 +816,7 @@ "2da725e554cd8930": {"kind":"literal","value":"fork"}, "2e3523541e942ef6": {"kind":"union","types":["18dc21f12bbac8ad","8e8e91646a5cae3f","e6063d0451dc0202","eea687d437880bd5"]}, "2e4debca12f2c449": {"kind":"literal","value":"team-message"}, + "2e505098f9209e52": {"kind":"object","properties":[{"name":"data","type":"7ff62f6599c083ce","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"587bb11da730e06a","optional":false}],"indices":[]}, "2eafefdc6f79a492": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"senderId","type":"4cd48f3e5108bd6e","optional":false},{"name":"senderName","type":"4cd48f3e5108bd6e","optional":false},{"name":"targetId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "2f1e6a7ebace43d7": {"kind":"union","types":["3f74ba74acd10644","58f94390b982f8a5","de30b1fa12c75f81","ebb768d85ec87fb6"]}, "2f3f201c8846e19c": {"kind":"literal","value":"tool-goal"}, @@ -853,6 +859,7 @@ "3ee93b06f3a12585": {"kind":"object","properties":[{"name":"data","type":"7c6129b6961cf4b2","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"44818000e56acb97","optional":false}],"indices":[]}, "3f74ba74acd10644": {"kind":"literal","value":"image/jpeg"}, "3fdf9582c3b5597d": {"kind":"object","properties":[{"name":"afterSeconds","type":"0657d3ca5ac4e7bf","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"5b232a9b9bfcc0fc","optional":false},{"name":"prompt","type":"4cd48f3e5108bd6e","optional":false},{"name":"scheduledAt","type":"4cd48f3e5108bd6e","optional":false},{"name":"title","type":"4cd48f3e5108bd6e","optional":true}],"indices":[]}, + "4035903993dfee62": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"68f44f59e91c4139","optional":false},{"name":"source","type":"7e9f1072c17f7aa8","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.user-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, "408927267422a7b2": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"0fe52387f6505270","optional":false}],"indices":[]}, "4208123b50df5006": {"kind":"object","properties":[{"name":"data","type":"ad0c38a0adb82a94","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"3e0eff5946255ff0","optional":false}],"indices":[]}, "42e0916e0dda5f6d": {"kind":"object","properties":[{"name":"data","type":"7f9365bae9fcb73e","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"fe792a6cd4304945","optional":false}],"indices":[]}, @@ -879,6 +886,7 @@ "4b7ddaf3710b88ff": {"kind":"array","element":"a99f76fd149051c3"}, "4bb451330ff699f3": {"kind":"object","properties":[{"name":"kind","type":"b38f206d59bad891","optional":false}],"indices":[]}, "4cd48f3e5108bd6e": {"kind":"primitive","type":"string"}, + "4d60dddaa65d3da8": {"kind":"object","properties":[{"name":"actor","type":"0a92c5bdfa06c2e2","optional":false},{"name":"kind","type":"6ba7edb6447b6a3e","optional":false},{"name":"shareId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "4e011753f8263f43": {"kind":"literal","value":"team/message/queued"}, "4e44c9118152f682": {"kind":"literal","value":"text"}, "4e88776858652856": {"kind":"object","properties":[{"name":"text","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"4e44c9118152f682","optional":false}],"indices":[]}, @@ -898,6 +906,7 @@ "530da6c0267813bb": {"kind":"union","types":["34d1ab5c5df37818","4f507598cf476214","e7ce49f12953583f","f789af5ab844827e"]}, "53750b9abf61efb7": {"kind":"object","properties":[{"name":"data","type":"f731ffe80810b028","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"44c8c77aa9aa100b","optional":false}],"indices":[]}, "53cf1704ae0709c7": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false}],"indices":[]}, + "53d4f8256bc58109": {"kind":"object","properties":[{"name":"headerSeq","type":"0657d3ca5ac4e7bf","optional":true},{"name":"message","type":"64ef542b1bfc9883","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "54f9276a1617d7c1": {"kind":"object","properties":[{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"stream","type":"84bbfdce7d2eab5b","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "557e148d30b79ee4": {"kind":"literal","value":"agent-preset/selected"}, "5654685d7557ec74": {"kind":"object","properties":[{"name":"form","type":"6f9e00383836275e","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false},{"name":"sections","type":"c748fb42c80a1200","optional":false}],"indices":[]}, @@ -910,11 +919,11 @@ "5808e36c95355f0e": {"kind":"union","types":["1d76406cbb2ddadb","287211846beea1ec","693f4952fb5565da","8e31bb958e9b015e","ab7ec5f9eb2c6dfa"]}, "587bb11da730e06a": {"kind":"literal","value":"session/title-llm-request"}, "589d0d91239681f8": {"kind":"literal","value":"developer"}, - "58b122df513aeaf7": {"kind":"object","properties":[{"name":"data","type":"b782058cef83caf3","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"de25352d2dc41963","optional":false}],"indices":[]}, "58f94390b982f8a5": {"kind":"literal","value":"image/png"}, "5abab3a27fd27366": {"kind":"literal","value":"text-delta"}, "5b232a9b9bfcc0fc": {"kind":"literal","value":"after"}, "5b6fb1f226ff5640": {"kind":"object","properties":[{"name":"commandId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"1ab2ef1296f157ba","optional":false},{"name":"sourceEventSeq","type":"0657d3ca5ac4e7bf","optional":true},{"name":"text","type":"4cd48f3e5108bd6e","optional":true}],"indices":[]}, + "5bb231bc5afdb532": {"kind":"object","properties":[{"name":"data","type":"4035903993dfee62","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"de25352d2dc41963","optional":false}],"indices":[]}, "5bb69b88517f6214": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"99e7e7d7fed55ae6","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "5bc66269cfaf614c": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"d9edf1862e4471d6","optional":false}],"indices":[]}, "5bd310104cfe448e": {"kind":"literal","value":"resource-cost"}, @@ -922,7 +931,6 @@ "5cb63db9fe57dc09": {"kind":"literal","value":"teardown"}, "5cc512378245b2df": {"kind":"literal","value":"subagent-name/bound"}, "5cdbf342b7748d15": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, - "5d00abf938272f22": {"kind":"array","element":"b782058cef83caf3"}, "5d03ba38734809bc": {"kind":"array","element":"0657d3ca5ac4e7bf"}, "5d17f27a1ef9f702": {"kind":"literal","value":"tool-workflow/agent-end"}, "5d542ac7bdf13310": {"kind":"object","properties":[{"name":"childCreatedAt","type":"0657d3ca5ac4e7bf","optional":false},{"name":"childId","type":"4cd48f3e5108bd6e","optional":false},{"name":"label","type":"4cd48f3e5108bd6e","optional":true},{"name":"mode","type":"d28765f87d6b6ab4","optional":false},{"name":"version","type":"93d38436347f67c9","optional":false}],"indices":[]}, @@ -930,7 +938,6 @@ "5dd766ccd1702a11": {"kind":"object","properties":[{"name":"shadowedRange","type":"9e41386b3a0c9572","optional":false},{"name":"shadowedSeqs","type":"5d03ba38734809bc","optional":false},{"name":"shadowedTokenCount","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "5e6db6e24948d4a8": {"kind":"object","properties":[{"name":"data","type":"17d1afb770d99419","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"1c2686c0682e7bc5","optional":false}],"indices":[]}, "5ebce1317eacd2c1": {"kind":"literal","value":"subagent/descriptor"}, - "5ef58f2a1bdc576c": {"kind":"object","properties":[{"name":"data","type":"7404c6123fdaa591","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"1379f0b72275994d","optional":false}],"indices":[]}, "5f2117d1856a5ab4": {"kind":"object","properties":[{"name":"code","type":"4cd48f3e5108bd6e","optional":false},{"name":"message","type":"4cd48f3e5108bd6e","optional":false},{"name":"offloadImages","type":"0657d3ca5ac4e7bf","optional":true},{"name":"providerRetryAfterMs","type":"0657d3ca5ac4e7bf","optional":true},{"name":"requestId","type":"4cd48f3e5108bd6e","optional":true},{"name":"status","type":"0657d3ca5ac4e7bf","optional":true}],"indices":[]}, "5f26a6c20b37632f": {"kind":"object","properties":[{"name":"data","type":"9a410ddf56792b2b","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"ad92f473a03ae725","optional":false}],"indices":[]}, "5f758f3de5f00c18": {"kind":"object","properties":[{"name":"label","type":"4cd48f3e5108bd6e","optional":true},{"name":"mode","type":"d28765f87d6b6ab4","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"version","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, @@ -942,8 +949,10 @@ "62e6a429ff3f390a": {"kind":"union","types":["1d8798b1a5e8c545","1e346446e183ee76","34d1ab5c5df37818","7624ca28c61ca0ea","ad22a5ca5bbaab2e","d9196086e41e4dd5"]}, "62ecb62dc0fe1b5e": {"kind":"literal","value":"next-turn"}, "6487b10ba7542f3c": {"kind":"object","properties":[{"name":"agentModel","type":"4cd48f3e5108bd6e","optional":true},{"name":"agentProvider","type":"4cd48f3e5108bd6e","optional":true},{"name":"agentReasoningEffort","type":"4cd48f3e5108bd6e","optional":true},{"name":"label","type":"4cd48f3e5108bd6e","optional":false},{"name":"mode","type":"e5d3828df1ec3e2a","optional":false},{"name":"persona","type":"4cd48f3e5108bd6e","optional":true},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"toolFilter","type":"3cfc3a56502da1f8","optional":true},{"name":"version","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "64ef542b1bfc9883": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"589d0d91239681f8","optional":false},{"name":"source","type":"7e9f1072c17f7aa8","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.developer-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, "6598cd6da253948d": {"kind":"object","properties":[{"name":"context","type":"50cf02d875f8a1f1","optional":false},{"name":"description","type":"4cd48f3e5108bd6e","optional":false},{"name":"error","type":"4cd48f3e5108bd6e","optional":true},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"phase","type":"dfce5db4aa42b7eb","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "65a8400e451e667e": {"kind":"object","properties":[{"name":"kind","type":"09655b34d7f3cf1e","optional":false}],"indices":[]}, + "65d583e66518c523": {"kind":"object","properties":[{"name":"entries","type":"aba175fb20ffc711","optional":false},{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"incomplete","type":"dacf3d5f3e4ff619","optional":true},{"name":"kind","type":"6ebcc2dbec9f2dab","optional":false},{"name":"update","type":"dacf3d5f3e4ff619","optional":true}],"indices":[]}, "66ba70f6f068da44": {"kind":"object","properties":[{"name":"deferLoading","type":"dacf3d5f3e4ff619","optional":true},{"name":"description","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"parameters","type":"0aa62ab51b36c0e6","optional":false}],"indices":[]}, "671fc8cbd3a92496": {"kind":"object","properties":[{"name":"childId","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"version","type":"f88f1b7b6bb733f6","optional":false}],"indices":[]}, "672c4aa2a9b736e3": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"1922cd79a70806c1","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, @@ -956,6 +965,7 @@ "69d238a6e9b08d67": {"kind":"literal","value":"interrupted"}, "6ab45ac76839722d": {"kind":"literal","value":"assistant/message"}, "6b23ed9ce1b397e6": {"kind":"literal","value":"compact-checkpoint"}, + "6ba7edb6447b6a3e": {"kind":"literal","value":"share-viewer"}, "6bbe793f6a93dc8d": {"kind":"object","properties":[{"name":"blockedReason","type":"84ac8c1a66ffc697","optional":true},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"maxGoalRounds","type":"0657d3ca5ac4e7bf","optional":false},{"name":"objective","type":"4cd48f3e5108bd6e","optional":false},{"name":"phase","type":"b8327af7ee576795","optional":false},{"name":"revision","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "6bc8e51124d0874b": {"kind":"object","properties":[{"name":"message","type":"09f3f8dc417f2782","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "6c03546143cdf6ae": {"kind":"object","properties":[{"name":"kind","type":"e6411b09c1d982f7","optional":false}],"indices":[]}, @@ -964,7 +974,6 @@ "6ccb6bc423fb3952": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "6cda0d6d3b4336d8": {"kind":"literal","value":"feedback/message-put"}, "6cf082d0fb6034de": {"kind":"literal","value":"producer"}, - "6dacb1584f2bfbe2": {"kind":"object","properties":[{"name":"clientTimeZone","type":"4cd48f3e5108bd6e","optional":true},{"name":"kind","type":"68f44f59e91c4139","optional":false},{"name":"principal","type":"deebfc7c62177ea8","optional":true},{"name":"rpcId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "6e52dd55a1d48954": {"kind":"object","properties":[{"name":"agentPreset","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "6ea608bdc8a7a63d": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, "6ebcc2dbec9f2dab": {"kind":"literal","value":"skill-catalog"}, @@ -975,44 +984,45 @@ "6f72ece8f317cd08": {"kind":"object","properties":[{"name":"retry","type":"0657d3ca5ac4e7bf","optional":false},{"name":"retryId","type":"4cd48f3e5108bd6e","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "6f9e00383836275e": {"kind":"literal","value":"snapshot"}, "70b082fe78991edf": {"kind":"literal","value":"request/context"}, + "70d2acdec1ebcfea": {"kind":"object","properties":[{"name":"data","type":"53d4f8256bc58109","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"1379f0b72275994d","optional":false}],"indices":[]}, "7180844e1066230c": {"kind":"literal","value":"service-stability"}, "719c51f67074f970": {"kind":"object","properties":[{"name":"kind","type":"2765e9119edf5816","optional":false},{"name":"model","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"replayState","type":"bbc5696e3f13c758","optional":true}],"indices":[]}, "71bb3254ec8f1e49": {"kind":"object","properties":[{"name":"dt","type":"5d03ba38734809bc","optional":false},{"name":"index","type":"0657d3ca5ac4e7bf","optional":false},{"name":"texts","type":"93c33d9687613293","optional":false},{"name":"time0","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"688e853dc149f0d3","optional":false}],"indices":[]}, "72ec79127a9c0d02": {"kind":"array","element":"c592ce75aab73fca"}, "7382c4fc95fe8c5d": {"kind":"literal","value":"remove"}, - "7404c6123fdaa591": {"kind":"object","properties":[{"name":"headerSeq","type":"0657d3ca5ac4e7bf","optional":true},{"name":"message","type":"7580e7d96dc8475f","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "750a2b129d67704d": {"kind":"union","types":["5cb63db9fe57dc09","6cf082d0fb6034de","bab6865794007548"]}, "7554565be416b034": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"2f3f201c8846e19c","optional":false}],"indices":[]}, "756b5e23a5cb2c7f": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, - "7580e7d96dc8475f": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"589d0d91239681f8","optional":false},{"name":"source","type":"7a5b68bd1a5118c8","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.developer-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, "7624ca28c61ca0ea": {"kind":"literal","value":"create"}, "763c8a20af487263": {"kind":"object","properties":[{"name":"data","type":"7d226b9fd95b4ba2","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"237c004c73b6b288","optional":false}],"indices":[]}, "76632533f67879dc": {"kind":"literal","value":"delegation"}, "78a9be340090b735": {"kind":"literal","value":"tmux-context"}, - "78b9204976ab9faa": {"kind":"array","element":"cda79b839d8cc0c7"}, "79650cfa10aa3c52": {"kind":"object","properties":[{"name":"error","type":"5f2117d1856a5ab4","optional":false},{"name":"kind","type":"a2be0f0cb59f0d4a","optional":false}],"indices":[]}, "79ddc907312f97cf": {"kind":"object","properties":[{"name":"todos","type":"4b7ddaf3710b88ff","optional":false}],"indices":[]}, - "7a5b68bd1a5118c8": {"kind":"union","types":["0203243b72fc867a","022623b9ef98ec47","02b2c23f2d94b028","0ed8d1108fe7a5e1","0eeb17e1df89b1eb","11638dc58a31496f","1938c8c20f1cba7c","1e709346005826eb","1fdad624334d3548","2152caf1a71e588e","2235d957bf4b7c6c","224aa11d4d5f88c4","24ce31aa528272e5","260523b412c19ad8","28936c614bd4e7e2","290f32bfd81ff85a","297fbd8067d7815a","2aad1179f9576314","312aee2f0c42aabb","31907de956375182","3247e566f4340029","3b04790e08b35241","3b4f2c9ef2c1217e","3bdb8dc6989655b0","408927267422a7b2","45f005e6bbb76452","4991dfc415c9efeb","49dab019d00e8c26","4a9bef9f27a94252","4e97c3d85c0fc817","52c6113cb0e53f34","53cf1704ae0709c7","5654685d7557ec74","58015da1c1950a66","5bb69b88517f6214","5bc66269cfaf614c","5cdbf342b7748d15","5d7a64ed6aac5551","6085488d223aeffd","6292bcbedaa97fea","65a8400e451e667e","672c4aa2a9b736e3","6ccb6bc423fb3952","6dacb1584f2bfbe2","6ea608bdc8a7a63d","6f22a9d02b9a1f11","6f44f32be9bcd9a8","719c51f67074f970","7554565be416b034","756b5e23a5cb2c7f","7df62978a2b7de85","7eaef7a763ba5b94","7f959241c24128b4","80677c8c8b804189","825ca23416b1ea9d","8338ee303e2bd448","854db3efdfb0cd39","85fe96bf15d5c755","8620189c8e335827","87b1a33564b9a4d6","88841202942c7683","8a046b52331959aa","8c1c4f72755a78ea","8c627d7a45fa406c","8f324cea3916c051","8fcb0b44a575e998","96bfb916a727cd44","99135d8a39379779","99f0e98184709ad1","9edc162949abf93b","9f65c43e340bba31","a15a19ef63cf5d1b","a16e567c8cd2c55c","a2066bd52f61218b","a3c6f1ea38e9a61d","aa2bf9e82b9fdeb9","aae343bc3d663c83","ada310bf0bdb8fed","ade057f4fdc387ae","b062078e899958f9","b2a5c8c008a31e3d","b3681c026a0b98e9","b4ec0af39fd52ed9","b613f83572fe2fbf","b6f94c17dd9bbd7c","b70f3e81fe11b7a5","b79641a9d25e7566","ba2a1a8f194b1bb2","ba4c40b4381e0dcd","baccc97ec34be6c4","c5228b7a55498d84","c55827fba7018198","cb1c8959e1726f82","cda2345a9be9d139","d85590a5675c6e2f","d9c462b9f62fdd3e","db06ef35b27a3842","dba54c09c6e7aafc","dd00cdccd0ba487b","dd5ee8762bd8a14b","dd6cc2bb2a8f2824","dde0cdf9d426768b","deaae5cd30987d4f","e7f4cbb3a57f4cbd","edbbfff1128099fd","ee577a0cc18664c9","f230c0b583e23b25","f29d63336e8266d8","f4a66f654996c093","f56c5b59ca016131","f6329fb30c7ea801","f6605d6c57933aea","f6afe41e3926f422","f7283223aacdc39b","f97f47b0eb87905e","fc2ae6962f9f8801","fcf81d3c58c13593","fe1a7acdeed4d0f5"]}, "7a651f3b672c52fb": {"kind":"literal","value":"session/title"}, "7af85bf70d4eafce": {"kind":"object","properties":[{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "7b1ce60193fa8b69": {"kind":"literal","value":"working-directory"}, + "7c203f3d4dfa6638": {"kind":"array","element":"4035903993dfee62"}, "7c6129b6961cf4b2": {"kind":"object","properties":[{"name":"messageId","type":"4cd48f3e5108bd6e","optional":false},{"name":"sessionId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "7c9f44e90a0058f4": {"kind":"object","properties":[{"name":"data","type":"5302e76315127761","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"sourceEventSeqs","type":"5d03ba38734809bc","optional":true},{"name":"surfaceOp","type":"335e242de1fcc17b","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"570e850224346133","optional":false}],"indices":[]}, "7d226b9fd95b4ba2": {"kind":"union","types":["1df34a6c086866ff","cffcdc19881ab61e"]}, "7d54a5a5e629e2e7": {"kind":"object","properties":[{"name":"category","type":"3305a4bb6b6c29b4","optional":true},{"name":"text","type":"4cd48f3e5108bd6e","optional":true}],"indices":[]}, "7d65acf0a3a43a8f": {"kind":"union","types":["1f0133217eeeffd8","277b61f9c6f81704","3c2535ca0a2062f1","4e44c9118152f682","83d6916021eede8f","85f9b505b7bdff1f","fb8b6a2e53cb9cf4"]}, "7df62978a2b7de85": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, + "7e9f1072c17f7aa8": {"kind":"union","types":["0203243b72fc867a","022623b9ef98ec47","02b2c23f2d94b028","0ed8d1108fe7a5e1","0eeb17e1df89b1eb","11638dc58a31496f","1938c8c20f1cba7c","1e709346005826eb","1fdad624334d3548","2152caf1a71e588e","2235d957bf4b7c6c","224aa11d4d5f88c4","24ce31aa528272e5","260523b412c19ad8","28936c614bd4e7e2","290f32bfd81ff85a","297fbd8067d7815a","2aad1179f9576314","312aee2f0c42aabb","31907de956375182","3247e566f4340029","3b04790e08b35241","3b4f2c9ef2c1217e","3bdb8dc6989655b0","408927267422a7b2","45f005e6bbb76452","4991dfc415c9efeb","49dab019d00e8c26","4a9bef9f27a94252","4e97c3d85c0fc817","52c6113cb0e53f34","53cf1704ae0709c7","5654685d7557ec74","58015da1c1950a66","5bb69b88517f6214","5bc66269cfaf614c","5cdbf342b7748d15","5d7a64ed6aac5551","6085488d223aeffd","6292bcbedaa97fea","65a8400e451e667e","65d583e66518c523","672c4aa2a9b736e3","6ccb6bc423fb3952","6ea608bdc8a7a63d","6f22a9d02b9a1f11","6f44f32be9bcd9a8","719c51f67074f970","7554565be416b034","756b5e23a5cb2c7f","7df62978a2b7de85","7eaef7a763ba5b94","7f959241c24128b4","80677c8c8b804189","825ca23416b1ea9d","8338ee303e2bd448","854db3efdfb0cd39","85fe96bf15d5c755","8620189c8e335827","87b1a33564b9a4d6","88841202942c7683","8a046b52331959aa","8c1c4f72755a78ea","8c627d7a45fa406c","8f324cea3916c051","8fcb0b44a575e998","96bfb916a727cd44","99135d8a39379779","99f0e98184709ad1","9edc162949abf93b","9f65c43e340bba31","a15a19ef63cf5d1b","a16e567c8cd2c55c","a2066bd52f61218b","a3c6f1ea38e9a61d","a4afec59b75aad5d","aa2bf9e82b9fdeb9","aae343bc3d663c83","ada310bf0bdb8fed","ade057f4fdc387ae","b062078e899958f9","b2a5c8c008a31e3d","b3681c026a0b98e9","b4ec0af39fd52ed9","b613f83572fe2fbf","b6f94c17dd9bbd7c","b70f3e81fe11b7a5","b79641a9d25e7566","ba2a1a8f194b1bb2","ba4c40b4381e0dcd","baccc97ec34be6c4","c5228b7a55498d84","c55827fba7018198","cb1c8959e1726f82","cda2345a9be9d139","d85590a5675c6e2f","d9c462b9f62fdd3e","db06ef35b27a3842","dba54c09c6e7aafc","dd00cdccd0ba487b","dd5ee8762bd8a14b","dd6cc2bb2a8f2824","dde0cdf9d426768b","deaae5cd30987d4f","e7f4cbb3a57f4cbd","edbbfff1128099fd","ee577a0cc18664c9","f230c0b583e23b25","f29d63336e8266d8","f4a66f654996c093","f56c5b59ca016131","f6329fb30c7ea801","f6605d6c57933aea","f6afe41e3926f422","f7283223aacdc39b","f97f47b0eb87905e","fcf81d3c58c13593","fe1a7acdeed4d0f5"]}, "7eaef7a763ba5b94": {"kind":"object","properties":[{"name":"form","type":"16d0507cb94b4cfc","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, "7f13860ee89a2d35": {"kind":"literal","value":"session-reference"}, "7f7fd5a6b0064f59": {"kind":"object","properties":[{"name":"data","type":"5dd766ccd1702a11","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"10e386801903f9d4","optional":false}],"indices":[]}, "7f9365bae9fcb73e": {"kind":"object","properties":[{"name":"runId","type":"4cd48f3e5108bd6e","optional":false},{"name":"stopReason","type":"8465ece5e9d9007c","optional":false}],"indices":[]}, "7f959241c24128b4": {"kind":"object","properties":[{"name":"goalId","type":"4cd48f3e5108bd6e","optional":false},{"name":"kind","type":"b815d7b91cdd9fc6","optional":false},{"name":"revision","type":"0657d3ca5ac4e7bf","optional":false},{"name":"round","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "7ff62f6599c083ce": {"kind":"object","properties":[{"name":"maxTokens","type":"0657d3ca5ac4e7bf","optional":false},{"name":"messageSeqs","type":"5d03ba38734809bc","optional":false},{"name":"messages","type":"ff2cbb53582d1827","optional":false},{"name":"reasoningEffort","type":"4cd48f3e5108bd6e","optional":true},{"name":"route","type":"07e1a58c58b593f5","optional":false},{"name":"system","type":"4cd48f3e5108bd6e","optional":false},{"name":"titleProvider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "8064c03c87c357fd": {"kind":"union","types":["12d5808fac1996b9","43e311235aa537df","4e88776858652856","814d9434e1ddf907","8e611bf46821e500","c1f0f17b6493b85d","f2da0f27c1e6add5"]}, "80677c8c8b804189": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, "8067b0d232c350f1": {"kind":"literal","value":"time-context"}, "811229eedcec5797": {"kind":"literal","value":"allowed-once"}, "814d9434e1ddf907": {"kind":"object","properties":[{"name":"text","type":"4cd48f3e5108bd6e","optional":false},{"name":"type","type":"3c2535ca0a2062f1","optional":false}],"indices":[]}, "82470020b5bfcb1a": {"kind":"literal","value":"agent-message"}, + "824a4aad44a54e24": {"kind":"union","types":["4d60dddaa65d3da8","deebfc7c62177ea8"]}, "825ca23416b1ea9d": {"kind":"object","properties":[{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"f68c335306535a00","optional":false}],"indices":[]}, "829a2fb3be6efd4b": {"kind":"literal","value":"agent/inbox/spliced"}, "83079c8a3f733ac3": {"kind":"object","properties":[{"name":"description","type":"4cd48f3e5108bd6e","optional":false},{"name":"name","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, @@ -1095,9 +1105,9 @@ "a2be0f0cb59f0d4a": {"kind":"literal","value":"error"}, "a3a259a1aa5401af": {"kind":"literal","value":"hook/result"}, "a3c6f1ea38e9a61d": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"9ac52f0f84fec2eb","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, - "a3e299483348f27a": {"kind":"object","properties":[{"name":"maxTokens","type":"0657d3ca5ac4e7bf","optional":false},{"name":"messageSeqs","type":"5d03ba38734809bc","optional":false},{"name":"messages","type":"78b9204976ab9faa","optional":false},{"name":"reasoningEffort","type":"4cd48f3e5108bd6e","optional":true},{"name":"route","type":"07e1a58c58b593f5","optional":false},{"name":"system","type":"4cd48f3e5108bd6e","optional":false},{"name":"titleProvider","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "a3edd1efd1fef21b": {"kind":"literal","value":"workspace-write"}, "a40d12070f6f4a12": {"kind":"object","properties":[{"name":"task","type":"51edec100659da3a","optional":false},{"name":"teamId","type":"4cd48f3e5108bd6e","optional":false},{"name":"version","type":"a0f906856fc06f1c","optional":false}],"indices":[]}, + "a4afec59b75aad5d": {"kind":"object","properties":[{"name":"clientTimeZone","type":"4cd48f3e5108bd6e","optional":true},{"name":"kind","type":"68f44f59e91c4139","optional":false},{"name":"principal","type":"824a4aad44a54e24","optional":true},{"name":"rpcId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "a6567ccb2e530606": {"kind":"object","properties":[{"name":"data","type":"0d47a8f3d847243c","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"0a8a062bc9c3c0d9","optional":false}],"indices":[]}, "a6b41f5bede8094d": {"kind":"union","types":["15495614ccfa9cbd","aff60ef947c18b01"]}, "a6da9ad5d42ae83a": {"kind":"object","properties":[{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"runId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, @@ -1140,10 +1150,8 @@ "b222069eea2d7680": {"kind":"object","properties":[{"name":"data","type":"477614bca595a9e7","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"9acbe713f3f64192","optional":false}],"indices":[]}, "b2245a906e13aa94": {"kind":"literal","value":"forked"}, "b2a5c8c008a31e3d": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"23af3759678a30de","optional":false}],"indices":[]}, - "b2a948a5340a9341": {"kind":"object","properties":[{"name":"inserted","type":"5d00abf938272f22","optional":false},{"name":"outcome","type":"d4e4d575abeb4b72","optional":true},{"name":"removedCount","type":"0657d3ca5ac4e7bf","optional":true},{"name":"start","type":"0657d3ca5ac4e7bf","optional":false},{"name":"target","type":"96f4a9c81fc0f940","optional":false}],"indices":[]}, "b2d2a01e51341a3b": {"kind":"union","types":["1ebc6f9ff3aa9e3a","234142ee4f996f38","94c56aeb1564ad73","e7e8f1318170b828"]}, "b3681c026a0b98e9": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, - "b36fd842cd004b53": {"kind":"object","properties":[{"name":"data","type":"b2a948a5340a9341","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"829a2fb3be6efd4b","optional":false}],"indices":[]}, "b38f206d59bad891": {"kind":"literal","value":"disposed"}, "b4ec0af39fd52ed9": {"kind":"object","properties":[{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, "b5086d249e8502e9": {"kind":"object","properties":[{"name":"data","type":"aa7bc2817014ca6c","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"6cda0d6d3b4336d8","optional":false}],"indices":[]}, @@ -1159,7 +1167,6 @@ "b6f94c17dd9bbd7c": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"bb94f3217aa56c88","optional":false}],"indices":[]}, "b70f3e81fe11b7a5": {"kind":"object","properties":[{"name":"form","type":"fee1caf8ab6a65c1","optional":false},{"name":"kind","type":"a9059a81430b3207","optional":false}],"indices":[]}, "b765ee31033cea46": {"kind":"literal","value":"set"}, - "b782058cef83caf3": {"kind":"object","properties":[{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"id","type":"4cd48f3e5108bd6e","optional":false},{"name":"role","type":"68f44f59e91c4139","optional":false},{"name":"source","type":"7a5b68bd1a5118c8","optional":false,"compatibility":{"version":1,"policy":"session-source-attribution","binding":"session.user-message.source","discriminator":"kind","unknownKinds":"preserve","attributionKinds":["action-cards","tmux-context","user-question-reply","working-directory"]}}],"indices":[]}, "b79641a9d25e7566": {"kind":"object","properties":[{"name":"kind","type":"8067b0d232c350f1","optional":false}],"indices":[]}, "b79ada42962cad01": {"kind":"object","properties":[{"name":"data","type":"86d1d0e9cfebb240","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"5ebce1317eacd2c1","optional":false}],"indices":[]}, "b815d7b91cdd9fc6": {"kind":"literal","value":"goal"}, @@ -1195,6 +1202,7 @@ "c589e938cc0e4989": {"kind":"literal","value":"tool/call"}, "c592ce75aab73fca": {"kind":"union","types":["0657d3ca5ac4e7bf","4cd48f3e5108bd6e","529e0ccd0e34079a","72ec79127a9c0d02","938f7c7357bc403e","aa93010d0e521ad7"]}, "c748fb42c80a1200": {"kind":"array","element":"86e1e384495ee09a"}, + "c78b9097bfae83cd": {"kind":"union","types":["09f3f8dc417f2782","4035903993dfee62","4b259f7f8f0a44ad","64ef542b1bfc9883","fa87537f4a9c1e25"]}, "c8e6f48878cc2a2f": {"kind":"literal","value":"active"}, "c99e20441bf15341": {"kind":"literal","value":"feedback/record"}, "ca085dba2c877fec": {"kind":"literal","value":"sandbox/mode"}, @@ -1204,15 +1212,16 @@ "cbca49bde16b656d": {"kind":"literal","value":"block-start"}, "cd186c309e2bef30": {"kind":"literal","value":"approval/asked"}, "cda2345a9be9d139": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"24b10f7cdae64928","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, - "cda79b839d8cc0c7": {"kind":"union","types":["09f3f8dc417f2782","4b259f7f8f0a44ad","7580e7d96dc8475f","b782058cef83caf3","fa87537f4a9c1e25"]}, "cdca80b8dad24d4e": {"kind":"literal","value":"tool-workflow/run-start"}, "cdee10e87dbed844": {"kind":"object","properties":[{"name":"delayMs","type":"0657d3ca5ac4e7bf","optional":false},{"name":"failure","type":"5f2117d1856a5ab4","optional":false},{"name":"maxRetries","type":"0657d3ca5ac4e7bf","optional":false},{"name":"mode","type":"3bc287e765d58dc3","optional":false},{"name":"policyKey","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"retry","type":"0657d3ca5ac4e7bf","optional":false},{"name":"retryId","type":"4cd48f3e5108bd6e","optional":false},{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, + "cdf988172b589b23": {"kind":"object","properties":[{"name":"data","type":"d4d960185026266e","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"829a2fb3be6efd4b","optional":false}],"indices":[]}, "cef171adf021a186": {"kind":"object","properties":[{"name":"arguments","type":"bbc5696e3f13c758","optional":false},{"name":"content","type":"b52f215a6cd69105","optional":false},{"name":"error","type":"a81059ca06999da1","optional":true},{"name":"isError","type":"aa93010d0e521ad7","optional":false},{"name":"meta","type":"c592ce75aab73fca","optional":true},{"name":"name","type":"4cd48f3e5108bd6e","optional":false},{"name":"parentCallId","type":"4cd48f3e5108bd6e","optional":false},{"name":"rootCallId","type":"4cd48f3e5108bd6e","optional":false},{"name":"subCallId","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "cffcdc19881ab61e": {"kind":"object","properties":[{"name":"cleared","type":"0b6d718c693fdf7f","optional":false},{"name":"clearedAt","type":"0657d3ca5ac4e7bf","optional":false},{"name":"kind","type":"237c004c73b6b288","optional":false},{"name":"operation","type":"e7e154d47d5fbc53","optional":false},{"name":"version","type":"f88f1b7b6bb733f6","optional":false}],"indices":[]}, "d0fbb0ca1bbba059": {"kind":"literal","value":"delete"}, "d28765f87d6b6ab4": {"kind":"literal","value":"one-shot"}, "d4b739491689cc6b": {"kind":"object","properties":[{"name":"block","type":"8064c03c87c357fd","optional":false},{"name":"index","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"eefbea819caeeea9","optional":false}],"indices":[]}, "d4c799e3d51cae10": {"kind":"literal","value":"working-directory/change"}, + "d4d960185026266e": {"kind":"object","properties":[{"name":"inserted","type":"7c203f3d4dfa6638","optional":false},{"name":"outcome","type":"d4e4d575abeb4b72","optional":true},{"name":"removedCount","type":"0657d3ca5ac4e7bf","optional":true},{"name":"start","type":"0657d3ca5ac4e7bf","optional":false},{"name":"target","type":"96f4a9c81fc0f940","optional":false}],"indices":[]}, "d4e4d575abeb4b72": {"kind":"literal","value":"canceled"}, "d595ec73b32b016a": {"kind":"object","properties":[{"name":"data","type":"a40d12070f6f4a12","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"b57ae1b37e52bee0","optional":false}],"indices":[]}, "d63b8b8ffad9c02f": {"kind":"object","properties":[{"name":"data","type":"8bb8c3751a6ce64b","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"47e5d84f1a93450a","optional":false}],"indices":[]}, @@ -1279,7 +1288,6 @@ "ef11a3b7fa2033ae": {"kind":"object","properties":[{"name":"step","type":"0657d3ca5ac4e7bf","optional":false},{"name":"turn","type":"0657d3ca5ac4e7bf","optional":false}],"indices":[]}, "ef226a90ddac6cd8": {"kind":"literal","value":"killed"}, "ef4f00923b9edbae": {"kind":"literal","value":"compaction/summary"}, - "efa1a091017ce533": {"kind":"object","properties":[{"name":"data","type":"a3e299483348f27a","optional":false},{"name":"ignorable","type":"dacf3d5f3e4ff619","optional":true},{"name":"seq","type":"0657d3ca5ac4e7bf","optional":false},{"name":"time","type":"0657d3ca5ac4e7bf","optional":false},{"name":"type","type":"587bb11da730e06a","optional":false}],"indices":[]}, "f05fb85e715af4ab": {"kind":"literal","value":"task-result"}, "f09e5e7acf5ff5cc": {"kind":"object","properties":[{"name":"model","type":"4cd48f3e5108bd6e","optional":false},{"name":"provider","type":"4cd48f3e5108bd6e","optional":false},{"name":"reasoningEffort","type":"4cd48f3e5108bd6e","optional":true}],"indices":[]}, "f1687f982fa3d41e": {"kind":"union","types":["023a355b2be0d688","0a30c3be336cdd4f","56b7c047694875a8","79650cfa10aa3c52","ab7ec5f9eb2c6dfa","b6ef9c6210be8350","ec8b5ff7c77ca689"]}, @@ -1312,7 +1320,6 @@ "fb5e0517050d2c6d": {"kind":"literal","value":"tool/ptc-dispatch"}, "fb8b6a2e53cb9cf4": {"kind":"literal","value":"image"}, "fbd2c74b346a1595": {"kind":"literal","value":"agent-instructions"}, - "fc2ae6962f9f8801": {"kind":"object","properties":[{"name":"entries","type":"aba175fb20ffc711","optional":false},{"name":"form","type":"aec150797b655c5f","optional":false},{"name":"kind","type":"6ebcc2dbec9f2dab","optional":false},{"name":"update","type":"dacf3d5f3e4ff619","optional":true}],"indices":[]}, "fc351843b8ecbd05": {"kind":"literal","value":"external"}, "fcf427290c6213c2": {"kind":"primitive","type":"never"}, "fcf81d3c58c13593": {"kind":"object","properties":[{"name":"form","type":"383cf73ae4748e5b","optional":false},{"name":"kind","type":"78a9be340090b735","optional":false}],"indices":[]}, @@ -1320,6 +1327,7 @@ "fe1a7acdeed4d0f5": {"kind":"object","properties":[{"name":"form","type":"e8de0f457fed5b9f","optional":false},{"name":"kind","type":"1f1385dbc3e875c0","optional":false},{"name":"summary","type":"4cd48f3e5108bd6e","optional":false}],"indices":[]}, "fe792a6cd4304945": {"kind":"literal","value":"tool-workflow/run-end"}, "fec5442b9ee4122e": {"kind":"object","properties":[{"name":"cacheReadTokens","type":"0657d3ca5ac4e7bf","optional":true},{"name":"cacheWriteTokens","type":"0657d3ca5ac4e7bf","optional":true},{"name":"inputTokens","type":"0657d3ca5ac4e7bf","optional":false},{"name":"outputTokens","type":"0657d3ca5ac4e7bf","optional":false},{"name":"reasoningTokens","type":"0657d3ca5ac4e7bf","optional":true},{"name":"totalTokens","type":"0657d3ca5ac4e7bf","optional":true}],"indices":[]}, - "fee1caf8ab6a65c1": {"kind":"literal","value":"instructions"} + "fee1caf8ab6a65c1": {"kind":"literal","value":"instructions"}, + "ff2cbb53582d1827": {"kind":"array","element":"c78b9097bfae83cd"} } } diff --git a/docs/rescope.i18n.yaml b/docs/rescope.i18n.yaml index f6ace06890..f418069ce3 100644 --- a/docs/rescope.i18n.yaml +++ b/docs/rescope.i18n.yaml @@ -6,8 +6,8 @@ en: c8aa4d3384ea1306 zh: 5aa030587d5b634d /vendored-package-rescope/name-mapping: - en: cc0f91dc4bb82605 - zh: 81d5031752c6ea74 + en: 239fa7993825ac62 + zh: df35fa9f5ef42a05 /vendored-package-rescope/what-the-rename-does-not-touch: en: 9bb7d09f8cccf695 zh: 2a8f3f60ae5116f3 diff --git a/docs/rescope.md b/docs/rescope.md index 2e25989742..85917bbfce 100644 --- a/docs/rescope.md +++ b/docs/rescope.md @@ -8,13 +8,13 @@ The Cordis framework and its foundation libraries are vendored under [`vendor/`] | Directory | Upstream name | Published name | Upstream version | Role | |---|---|---|---|---| -| `vendor/cordis/` | `cordis` | `@deepseek-ai/cordis` | 4.0.0-rc.7 | Framework core: `Context`, `Service`, `Fiber`, events | +| `vendor/cordis/` | `cordis` | `@deepseek-ai/cordis` | 4.0.0-rc.11 | Framework core: `Context`, `Service`, `Fiber`, events | | `vendor/cosmokit/` | `cosmokit` | `@deepseek-ai/cosmokit` | 1.8.1 | Shared utilities the framework and Schemastery build on | | `vendor/schemastery/` | `schemastery` | `@deepseek-ai/schemastery` | 3.18.0 | Config schemas (`Schema`) behind every plugin's `Config` | | `vendor/loader/` | `@cordisjs/plugin-loader` | `@deepseek-ai/cordis-plugin-loader` | 1.0.0-rc.5 | `cordis.yml` loading, plugin resolution, repository cache | | `vendor/include/` | `@cordisjs/plugin-include` | `@deepseek-ai/cordis-plugin-include` | 1.0.4 | Config includes and patch overlays | | `vendor/group/` | `@cordisjs/plugin-group` | `@deepseek-ai/cordis-plugin-group` | 1.0.0 | Nested plugin groups | -| `vendor/timer/` | `@cordisjs/plugin-timer` | `@deepseek-ai/cordis-plugin-timer` | 1.1.2 | Disposal-aware timers on `ctx` | +| `vendor/timer/` | `@cordisjs/plugin-timer` | `@deepseek-ai/cordis-plugin-timer` | 1.1.4 | Disposal-aware timers on `ctx` | | `vendor/hmr/` | `@cordisjs/plugin-hmr` | `@deepseek-ai/cordis-plugin-hmr` | 1.0.15 | Hot module replacement for plugins and config | | `vendor/logger-console/` | `@cordisjs/plugin-logger-console` | `@deepseek-ai/cordis-plugin-logger-console` | 1.0.0 | Console logger exporter | diff --git a/docs/rescope.zh.md b/docs/rescope.zh.md index 7b888ede0c..8d13ed539b 100644 --- a/docs/rescope.zh.md +++ b/docs/rescope.zh.md @@ -8,13 +8,13 @@ Cordis 框架及其基础库以源码形式 vendored 在 [`vendor/`](../vendor/R | 目录 | 上游名 | 发布名 | 上游版本 | 角色 | |---|---|---|---|---| -| `vendor/cordis/` | `cordis` | `@deepseek-ai/cordis` | 4.0.0-rc.7 | 框架核心：`Context`、`Service`、`Fiber`、事件 | +| `vendor/cordis/` | `cordis` | `@deepseek-ai/cordis` | 4.0.0-rc.11 | 框架核心：`Context`、`Service`、`Fiber`、事件 | | `vendor/cosmokit/` | `cosmokit` | `@deepseek-ai/cosmokit` | 1.8.1 | 框架与 Schemastery 共用的基础工具 | | `vendor/schemastery/` | `schemastery` | `@deepseek-ai/schemastery` | 3.18.0 | 配置 schema（`Schema`），每个插件的 `Config` 都基于它 | | `vendor/loader/` | `@cordisjs/plugin-loader` | `@deepseek-ai/cordis-plugin-loader` | 1.0.0-rc.5 | `cordis.yml` 装载、插件解析、repository 缓存 | | `vendor/include/` | `@cordisjs/plugin-include` | `@deepseek-ai/cordis-plugin-include` | 1.0.4 | 配置包含与 patch 叠加 | | `vendor/group/` | `@cordisjs/plugin-group` | `@deepseek-ai/cordis-plugin-group` | 1.0.0 | 嵌套插件分组 | -| `vendor/timer/` | `@cordisjs/plugin-timer` | `@deepseek-ai/cordis-plugin-timer` | 1.1.2 | `ctx` 上随 disposal 回收的定时器 | +| `vendor/timer/` | `@cordisjs/plugin-timer` | `@deepseek-ai/cordis-plugin-timer` | 1.1.4 | `ctx` 上随 disposal 回收的定时器 | | `vendor/hmr/` | `@cordisjs/plugin-hmr` | `@deepseek-ai/cordis-plugin-hmr` | 1.0.15 | 插件与配置的热替换 | | `vendor/logger-console/` | `@cordisjs/plugin-logger-console` | `@deepseek-ai/cordis-plugin-logger-console` | 1.0.0 | 控制台日志导出 | diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml index fd13bb4d00..7db6ca626f 100644 --- a/docs/subsystems/README.i18n.yaml +++ b/docs/subsystems/README.i18n.yaml @@ -3,5 +3,5 @@ # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/README.md /subsystems: - en: 857da1eede1f5523 - zh: 93fc3928f4eb43b5 + en: 67b61c092349059c + zh: 20175133518bef86 diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md index 92ac9554ce..b3c3d762ab 100644 --- a/docs/subsystems/README.md +++ b/docs/subsystems/README.md @@ -20,6 +20,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events | | [working-directory.md](working-directory.md) | Session execution directories, durable changes, recovery, and user context | | [worktrees.md](worktrees.md) | Experimental Git branch and checkout creation under existing permissions | +| [forge.md](forge.md) | Experimental code host change requests: provider contract, shared status polling, and Session bindings | | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, the JSONL provider, `session/flush`, crash recovery, `SessionHeader` | | [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits | | [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers | @@ -51,6 +52,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures | [voice-input.md](voice-input.md) | experimental named recognizers, transient audio and revision-guarded draft insertion | | [translation.md](translation.md) | experimental anonymous text translation and explicit provider requests | | [agent-team.md](agent-team.md) | Agent Teams: shared task DAG, task ownership, and wait signals for a subagent tree | +| [liveshare.md](liveshare.md) | the opt-in LiveShare bundle: nested share modes, a fork's ceiling and durability, enforcement installation, and the constraint a shared Session's externally driven turns run under | | [claude-code-mods.md](claude-code-mods.md) | Claude Code mods through the experimental bridge: every event, `$` member, chain rule, drawing feature, and example mod that differs from Claude Code | | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` | | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` | diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md index 6e9fa95917..33ca119319 100644 --- a/docs/subsystems/README.zh.md +++ b/docs/subsystems/README.zh.md @@ -20,6 +20,7 @@ | [session.md](session.zh.md) | 完整的 `SessionEventMap` 变体目录、`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 | | [working-directory.md](working-directory.zh.md) | Session 执行目录、持久化变更、恢复与用户上下文 | | [worktrees.md](worktrees.zh.md) | 现有权限下的实验性 Git 分支与检出目录创建 | +| [forge.md](forge.zh.md) | 实验性代码托管变更请求：提供方契约、共享状态轮询与 Session 绑定 | | [persistence.md](persistence.zh.md) | 持久性 seam：`SessionPersistence`、JSONL 提供方、`session/flush`、崩溃恢复、`SessionHeader` | | [settings.md](settings.zh.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 | | [credentials.md](credentials.zh.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、提供方来源层 | @@ -51,6 +52,7 @@ | [voice-input.md](voice-input.zh.md) | 实验性具名语音识别、临时音频和受版本保护的草稿插入 | | [translation.md](translation.zh.md) | 实验性免登录文本翻译与显式 Provider 请求 | | [agent-team.md](agent-team.zh.md) | Agent Teams：子代理树共享的任务 DAG、任务归属与等待信号 | +| [liveshare.md](liveshare.zh.md) | 可选的 LiveShare bundle：嵌套分享模式、fork 的上限与持久性、上限安装，以及共享会话外部驱动轮次所受的约束 | | [claude-code-mods.md](claude-code-mods.zh.md) | 经实验性桥接运行的 Claude Code 模组：与 Claude Code 不同的每个事件、`$` 成员、链规则、绘制特性与示例模组 | | [web.md](web.zh.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` | | [spill.md](spill.zh.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` | diff --git a/docs/subsystems/attachment.i18n.yaml b/docs/subsystems/attachment.i18n.yaml index 621444176d..856a932e75 100644 --- a/docs/subsystems/attachment.i18n.yaml +++ b/docs/subsystems/attachment.i18n.yaml @@ -6,8 +6,8 @@ en: 564dfcaaca384e23 zh: 5d215635919b5bc4 /durable-attachments/identity-and-verified-metadata: - en: 96378c208b220c6f - zh: 7af93f6a79520732 + en: 3e14f535f7587b0c + zh: cbbd513a5dff5fed /durable-attachments/commit-and-verified-read-payloads: - en: f79753272bb0ec70 - zh: 61830c41021f9274 + en: db2017cdf91e260a + zh: 6ba39bbc7cef4d8f diff --git a/docs/subsystems/attachment.md b/docs/subsystems/attachment.md index 2e330672f7..bccf3c33a3 100644 --- a/docs/subsystems/attachment.md +++ b/docs/subsystems/attachment.md @@ -58,7 +58,7 @@ interface ImageAttachmentLimits { The local backend admits at most 20 images and 200 MiB of encoded source data per message. One source may use up to 50 MiB, 64,000,000 pixels, and 65,535 pixels on either side. These source limits precede the independent normalization stage, which limits the long edge to 2048 pixels and encoded data to 4 MiB by default. -The reference records intrinsic dimensions and encoded length so clients can lay out history without decoding first, while every authoritative read still re-checks digest, media signature, dimensions, and metadata against the object. +The reference records intrinsic dimensions and encoded length so clients can lay out history without decoding first. Reads verify the stored object against the supplied reference's ID, format, byte length, width, and height. Optional display names and pre-normalization dimensions are returned unchanged as caller-supplied display information, without verification against stored bytes. ## Commit and verified-read payloads @@ -173,7 +173,7 @@ interface RequestImageAttachment { } ``` -`saveImage()` prepares and atomically commits a provider-independent normalized attachment before returning its `ImageAttachmentRef`. `saveImages()` prepares every validated attachment once before publishing the batch, so validation rejection leaves no partial objects and publication does not repeat decoding or quality selection. `admitPromptContent()` accepts the complete ordered Host prompt after upload receipt resolution, replaces base64 image uploads with durable references, passes durable file references and already stored images unchanged, and counts every image toward the per-message image count and aggregate byte limits, a stored image by the bytes of its upload. `admitEncodedImages()` supports other wire entries and delegates count, aggregate-byte, and ordered batch admission to `saveImages()`. `admitEncodedFile()` gives encoded protocol adapters the same service-owned canonical-base64 admission, and `isAttachmentError()` lets those adapters recognize stable attachment failures without importing implementation helpers. `readImage()` verifies a normalized attachment from an authorized session path. `imageHostPath()` exposes only the provider-owned host object location; it does not decide whether the current tool execution world can read it. `readImageRequest()` derives and caches one deterministic request version at an exact route-chosen target size and encoded-byte target. That version contains encoded bytes and metadata but no execution-world path. New entries are fully decoded before publication, while cache hits use a bounded metadata probe. Callers use `Promise.all` over the singular method when they need an ordered batch. The local implementation lazily encodes preferred candidates, singleflights equal request identities, lets each waiter cancel independently, stops shared work when no waiter remains, and bounds all transforms with its instance-level limiter, which defaults to two simultaneous transformations. The service is retention-neutral: resumed and forked sessions may share objects, so reference-aware garbage collection is deferred rather than tied to one session's deletion. +`saveImage()` prepares and atomically commits a provider-independent normalized attachment before returning its `ImageAttachmentRef`. `saveImages()` prepares every validated attachment once before publishing the batch, so validation rejection leaves no partial objects and publication does not repeat decoding or quality selection. `admitPromptContent()` accepts the complete ordered Host prompt after upload receipt resolution, replaces base64 image uploads with durable references, passes durable file references and already stored images unchanged, and counts every image toward the per-message image count and aggregate byte limits, a stored image by the bytes of its upload. `admitEncodedImages()` supports other wire entries and delegates count, aggregate-byte, and ordered batch admission to `saveImages()`. `admitEncodedFile()` gives encoded protocol adapters the same service-owned canonical-base64 admission, and `isAttachmentError()` lets those adapters recognize stable attachment failures without importing implementation helpers. `readImage()` verifies a normalized object against the supplied complete reference without consulting Session history, then returns that reference with the bytes. Access policy belongs to the calling API; Session Controller uses the store-level [image access rule](../../.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.md). `imageHostPath()` exposes only the provider-owned host object location; it does not decide whether the current tool execution world can read it. `readImageRequest()` derives and caches one deterministic request version at an exact route-chosen target size and encoded-byte target. That version contains encoded bytes and metadata but no execution-world path. New entries are fully decoded before publication, while cache hits use a bounded metadata probe. Callers use `Promise.all` over the singular method when they need an ordered batch. The local implementation lazily encodes preferred candidates, singleflights equal request identities, lets each waiter cancel independently, stops shared work when no waiter remains, and bounds all transforms with its instance-level limiter, which defaults to two simultaneous transformations. The service is retention-neutral: resumed and forked sessions may share objects, so reference-aware garbage collection is deferred rather than tied to one session's deletion. @@ -243,8 +243,8 @@ isAttachmentError(error: unknown): error is AttachmentError abstract saveImage(input: SaveImageAttachment): Promise /** - * Read one image and verify that bytes still match the recorded reference. - * @param ref - durable reference from the session log. + * Read one image and verify its ID, format, byte length, and dimensions against the supplied reference. + * @param ref - supplied image reference; name and originalDimensions are preserved without file verification. * @param signal - optional cancellation for backend read and verification work. * @returns the verified bytes and normalized attachment reference. * @throws the signal reason when aborted, or a storage error when verification fails. @@ -282,7 +282,7 @@ saveFileStream(input: SaveFileStreamAttachment): Promise * Read and verify one verbatim stored file as bounded chunks. Providers must * not collect the complete file in memory. Backends without verbatim file * reads keep this default rejection. - * @param ref - durable reference from the session log. + * @param ref - durable file reference from the session log. * @param signal - optional cancellation for backend reads and verification work. * @returns exact file bytes in order; integrity failures reject the iteration. */ diff --git a/docs/subsystems/attachment.zh.md b/docs/subsystems/attachment.zh.md index 057ed080f4..c917947b73 100644 --- a/docs/subsystems/attachment.zh.md +++ b/docs/subsystems/attachment.zh.md @@ -58,7 +58,7 @@ interface ImageAttachmentLimits { 本地后端每条消息最多准入 20 张图片，源图编码数据总量不超过 200 MiB。单张源图不得超过 50 MiB、64,000,000 像素和单边 65,535 像素。这些源文件限制先于独立的规范化阶段执行；该阶段默认把长边限制为 2048 像素，把编码数据限制为 4 MiB。 -引用记录固有尺寸和编码长度，使客户端无需先解码即可排布历史记录；每次权威读取仍会根据对象重新校验摘要、媒体签名、尺寸和元数据。 +引用记录固有尺寸和编码长度，使客户端无需先解码即可排布历史记录。读取会把存储对象与传入引用中的 ID、格式、字节数、宽度和高度比对。可选的显示名称和规范化前尺寸作为调用方提交的显示信息原样返回，不根据存储字节校验。 ## 提交与经校验读取的数据 @@ -173,7 +173,7 @@ interface RequestImageAttachment { } ``` -`saveImage()` 准备并原子提交提供方无关的规范化附件，然后直接返回 `ImageAttachmentRef`。`saveImages()` 在发布批次前为每个成员各准备一次经过验证的附件，因此校验拒绝不会留下部分对象，发布也不会重复解码或选择质量。`admitPromptContent()` 在上传凭证解析后接收完整且有序的 Host prompt，把 base64 图片上传替换为持久引用，让持久文件引用和已存储的图片原样通过，并把每张图片计入单条消息的图片数量与总字节上限，已存储的图片按其上传的字节数计入。`admitEncodedImages()` 支持其他 wire 入口，把张数、聚合字节和有序批量准入交给 `saveImages()`。`admitEncodedFile()` 让编码协议适配器使用服务拥有的规范 base64 准入，`isAttachmentError()` 让这些适配器无需导入实现辅助函数即可识别稳定的附件错误。`readImage()` 校验来自已授权会话路径的规范化附件。`imageHostPath()` 只公开提供方所持对象的宿主位置，不判断当前工具执行环境能否读取它。`readImageRequest()` 按确切的路由目标尺寸和编码字节目标派生并缓存确定性请求版本。该版本包含编码字节和元数据，不包含执行环境路径。新条目在发布前完整解码，缓存命中只做有界元数据探测。调用方需要有序批次时，对单数方法使用 `Promise.all`。本地实现按需编码首选候选、合并相同请求身份的并发任务、允许每个等待方单独取消、没有等待方时停止共享任务，并通过实例级限流器限制全部变换，默认同时执行两项。该服务不规定保留策略：恢复和 fork 后的会话可能共享对象，因此基于引用的垃圾回收会延期实现，不与单个会话的删除绑定。 +`saveImage()` 准备并原子提交提供方无关的规范化附件，然后直接返回 `ImageAttachmentRef`。`saveImages()` 在发布批次前为每个成员各准备一次经过验证的附件，因此校验拒绝不会留下部分对象，发布也不会重复解码或选择质量。`admitPromptContent()` 在上传凭证解析后接收完整且有序的 Host prompt，把 base64 图片上传替换为持久引用，让持久文件引用和已存储的图片原样通过，并把每张图片计入单条消息的图片数量与总字节上限，已存储的图片按其上传的字节数计入。`admitEncodedImages()` 支持其他 wire 入口，把张数、聚合字节和有序批量准入交给 `saveImages()`。`admitEncodedFile()` 让编码协议适配器使用服务拥有的规范 base64 准入，`isAttachmentError()` 让这些适配器无需导入实现辅助函数即可识别稳定的附件错误。`readImage()` 把规范化对象与传入的完整引用比对，无需查询 Session 历史，随后返回该引用与字节。访问规则由调用 API 负责；Session Controller 使用存储范围的[图片访问规则](../../.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.zh.md)。`imageHostPath()` 只公开提供方所持对象的宿主位置，不判断当前工具执行环境能否读取它。`readImageRequest()` 按确切的路由目标尺寸和编码字节目标派生并缓存确定性请求版本。该版本包含编码字节和元数据，不包含执行环境路径。新条目在发布前完整解码，缓存命中只做有界元数据探测。调用方需要有序批次时，对单数方法使用 `Promise.all`。本地实现按需编码首选候选、合并相同请求身份的并发任务、允许每个等待方单独取消、没有等待方时停止共享任务，并通过实例级限流器限制全部变换，默认同时执行两项。该服务不规定保留策略：恢复和 fork 后的会话可能共享对象，因此基于引用的垃圾回收会延期实现，不与单个会话的删除绑定。 @@ -243,8 +243,8 @@ isAttachmentError(error: unknown): error is AttachmentError abstract saveImage(input: SaveImageAttachment): Promise /** - * Read one image and verify that bytes still match the recorded reference. - * @param ref - durable reference from the session log. + * Read one image and verify its ID, format, byte length, and dimensions against the supplied reference. + * @param ref - supplied image reference; name and originalDimensions are preserved without file verification. * @param signal - optional cancellation for backend read and verification work. * @returns the verified bytes and normalized attachment reference. * @throws the signal reason when aborted, or a storage error when verification fails. @@ -282,7 +282,7 @@ saveFileStream(input: SaveFileStreamAttachment): Promise * Read and verify one verbatim stored file as bounded chunks. Providers must * not collect the complete file in memory. Backends without verbatim file * reads keep this default rejection. - * @param ref - durable reference from the session log. + * @param ref - durable file reference from the session log. * @param signal - optional cancellation for backend reads and verification work. * @returns exact file bytes in order; integrity failures reject the iteration. */ diff --git a/docs/subsystems/boot.i18n.yaml b/docs/subsystems/boot.i18n.yaml index 7754efcc03..a1b1b47591 100644 --- a/docs/subsystems/boot.i18n.yaml +++ b/docs/subsystems/boot.i18n.yaml @@ -6,8 +6,8 @@ en: 962b4398c9052959 zh: 14471c340a9f6e60 /profile-management/management-records: - en: 8813788cd8a86903 - zh: 3c30cb180fc1a33d + en: 2cf6a1f62dcc1de6 + zh: b6d519b60f6f5c79 /profile-management/market-records: en: 3dfc62d837d61b9b zh: ec223be315f3dc62 diff --git a/docs/subsystems/boot.md b/docs/subsystems/boot.md index 1d127bd772..48b9b179e0 100644 --- a/docs/subsystems/boot.md +++ b/docs/subsystems/boot.md @@ -18,7 +18,7 @@ The [boot package group](../../packages/boot/README.md) owns launcher-provided p `PluginRegistries` carries the configured first registry, `null` for the one pnpm's own configuration names, the fallbacks asked after it, and `resolved`, the URL pnpm's own configuration names or `null` while unread. `InspectOptions.registry` names the registry a lookup asks first. -`ChangeResult.changed` reports a disk edit independently of `application`: `applied`, `restart-required`, `overridden` or `failed`. Optional `error` carries a localizable code and external diagnostic. `packageResult` records the pnpm exit code, bounded output, truncation flag and complete diagnostic log path, plus `timedOut` when the manager terminated a run that stopped printing. A terminated run is classified `timeout` whatever exit status the signal left behind, so installation and removal report failure instead of success and no further registry is asked. `pendingBuilds` lists undecided packages across the profile; `approvedBuilds` records the names granted permission by this operation; `registries` lists the registries an installation asked, in order; `bundle` and `version` name the package a finished installation added and its manifest version; `failedAt` says whether the last failed run could not reach the registry it asked or the host a git or tarball spec is fetched from. +`ChangeResult.changed` reports a disk edit independently of `application`: `applied`, `restart-required`, `overridden` or `failed`. Optional `error` carries a localizable code and external diagnostic. `packageResult` records the run's exit status, bounded output, truncation flag and complete diagnostic log path, plus `timedOut` when the manager terminated a run that stopped printing or the GitHub connection check hit its deadline; a terminated run records the coerced status 1 because its process returned none. A terminated run is classified `timeout` whatever exit status the signal left behind, so installation and removal report failure instead of success and no further registry is asked. `pendingBuilds` lists undecided packages across the profile; `approvedBuilds` records the names granted permission by this operation; `registries` lists the registries an installation asked, in order; `bundle` and `version` name the package a finished installation added and its manifest version; `failedAt` says whether the last failed run could not reach the registry it asked or the host a git or tarball spec is fetched from. ## Market records @@ -297,7 +297,8 @@ Manage profile files and apply their declared reload lifecycle. /** * Install a package using the same pnpm implementation as dsh plugin. GitHub * repositories get a connection check bounded by githubConnectionTimeoutMs before pnpm starts; - * only network failures or timeouts stop installation, while pnpm owns authentication and transport fallback. An + * only network failures or timeouts stop installation, and a stop streams the check's diagnostic + * as the installation's install-log run under its request id, while pnpm owns authentication and transport fallback. An * HTTP(S) Git URL on another host is installed over SSH instead when access probes bounded by gitTransportTimeoutMs * find that only SSH can read it. A run * that fails, is cancelled, or adds a package without a bundle patch restores @@ -532,11 +533,11 @@ Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin #### `plugin-manager/install-log` — emit -One chunk of a pnpm run's output, streamed as the run produces it. +One chunk of an installation run's output, streamed as the run produces it. ```ts cordis-catalog /** - * One chunk of a pnpm run's output, streamed as the run produces it. + * One chunk of an installation run's output, streamed as the run produces it. * @mode emit * @param chunk - the chunk and the run it belongs to. */ @@ -563,6 +564,23 @@ An installation moved between its Host phases. `installing` is announced once pe Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts) + + +#### `plugin-manager/operation` — parallel + +One manager invocation started or ended; subscribers run independently without delaying management. + +```ts cordis-catalog +/** + * One manager invocation started or ended; subscribers run independently without delaying management. + * @mode parallel + * @param operation - Correlated operation facts; a start without an end has an unknown outcome. + */ +'plugin-manager/operation'(operation: PluginOperation): void | Promise +``` + +Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts) + #### `plugin-manager/update-state` — emit diff --git a/docs/subsystems/boot.zh.md b/docs/subsystems/boot.zh.md index 80395ce86d..d80c05fb53 100644 --- a/docs/subsystems/boot.zh.md +++ b/docs/subsystems/boot.zh.md @@ -18,7 +18,7 @@ `PluginRegistries` 携带配置的第一个注册表（`null` 即 pnpm 自身配置指定的那个）、随后依次询问的备选注册表，以及 `resolved`——pnpm 自身配置指向的 URL，未读到时为 `null`。`InspectOptions.registry` 指定一次查询首先询问的注册表。 -`ChangeResult.changed` 报告磁盘修改，独立于 `application`：`applied`、`restart-required`、`overridden` 或 `failed`。可选的 `error` 包含可本地化的错误码和外部诊断。`packageResult` 记录 pnpm 退出码、有界输出、截断标志及完整诊断日志路径；当管理器终止了一个停止打印的运行，还记录 `timedOut`。被终止的运行不论信号留下什么退出状态都归类为 `timeout`，因此安装与删除都报告失败而非成功，也不会再询问下一个注册表。`pendingBuilds` 列出整个 profile 尚未决定的包；`approvedBuilds` 记录本次操作授予权限的包名；`registries` 按顺序列出一次安装问过的注册表；`bundle` 与 `version` 给出完成的安装新增的包及其清单版本；`failedAt` 说明最后一次失败的运行连不上的是所问的注册表，还是 git 或 tarball spec 自身拉取的主机。 +`ChangeResult.changed` 报告磁盘修改，独立于 `application`：`applied`、`restart-required`、`overridden` 或 `failed`。可选的 `error` 包含可本地化的错误码和外部诊断。`packageResult` 记录运行的退出状态、有界输出、截断标志及完整诊断日志路径；当管理器终止了一个停止打印的运行，或 GitHub 连接检查到达期限，还记录 `timedOut`；被终止的运行记录强制填入的状态 1，因为它的进程没有返回任何状态。被终止的运行不论信号留下什么退出状态都归类为 `timeout`，因此安装与删除都报告失败而非成功，也不会再询问下一个注册表。`pendingBuilds` 列出整个 profile 尚未决定的包；`approvedBuilds` 记录本次操作授予权限的包名；`registries` 按顺序列出一次安装问过的注册表；`bundle` 与 `version` 给出完成的安装新增的包及其清单版本；`failedAt` 说明最后一次失败的运行连不上的是所问的注册表，还是 git 或 tarball spec 自身拉取的主机。 ## 市场记录 @@ -297,7 +297,8 @@ Manage profile files and apply their declared reload lifecycle. /** * Install a package using the same pnpm implementation as dsh plugin. GitHub * repositories get a connection check bounded by githubConnectionTimeoutMs before pnpm starts; - * only network failures or timeouts stop installation, while pnpm owns authentication and transport fallback. An + * only network failures or timeouts stop installation, and a stop streams the check's diagnostic + * as the installation's install-log run under its request id, while pnpm owns authentication and transport fallback. An * HTTP(S) Git URL on another host is installed over SSH instead when access probes bounded by gitTransportTimeoutMs * find that only SSH can read it. A run * that fails, is cancelled, or adds a package without a bundle patch restores @@ -532,11 +533,11 @@ Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin #### `plugin-manager/install-log` — emit -One chunk of a pnpm run's output, streamed as the run produces it. +One chunk of an installation run's output, streamed as the run produces it. ```ts cordis-catalog /** - * One chunk of a pnpm run's output, streamed as the run produces it. + * One chunk of an installation run's output, streamed as the run produces it. * @mode emit * @param chunk - the chunk and the run it belongs to. */ @@ -563,6 +564,23 @@ An installation moved between its Host phases. `installing` is announced once pe Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts) + + +#### `plugin-manager/operation` — parallel + +One manager invocation started or ended; subscribers run independently without delaying management. + +```ts cordis-catalog +/** + * One manager invocation started or ended; subscribers run independently without delaying management. + * @mode parallel + * @param operation - Correlated operation facts; a start without an end has an unknown outcome. + */ +'plugin-manager/operation'(operation: PluginOperation): void | Promise +``` + +Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts) + #### `plugin-manager/update-state` — emit diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml index 6e62ff7821..58967468c2 100644 --- a/docs/subsystems/client-modules.i18n.yaml +++ b/docs/subsystems/client-modules.i18n.yaml @@ -9,8 +9,8 @@ en: 96b95cdb015c1af6 zh: 01e4144d91551c13 /client-modules/the-scan: - en: 811c0e8a3a370399 - zh: 4a49a3999d35503a + en: f4d641734c47b129 + zh: 670819fb119ae688 /client-modules/the-bundle-route-and-index-injection: en: 82c089fbd9ffd535 zh: 30ac52d01b4fc074 diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md index c7f175b9e6..5b058a2508 100644 --- a/docs/subsystems/client-modules.md +++ b/docs/subsystems/client-modules.md @@ -93,7 +93,9 @@ Initial publication and HMR derive each row's `rev` from the entry's mtime, ctim A package joins the table by declaring `dsh.client` (`platform: 'web'`, optional `inject` edges, optional `immediately`) in its package.json and exporting its built bundle at `exports["./client"]`. Each live row resolves from its own Loader specifier and owning-tree `baseUrl`, through the same `loader.internal.resolveSync` implementation that imports its Host face when available. The nearest owning package manifest supplies the browser module id, so relative source and built overlays retain the package identity. Distinct active Loader sources resolving to one package name fail composition; after one source unloads, the surviving source supplies the row without a fiber restart. -Scanning is incremental per package; there is no full-rescan code path. Every cordis `internal/plugin` emission (fiber construction or disposal) marks the fiber's entry name dirty, and a microtask flush reconciles each dirty name against the live loader entries. The activation pass seeds the same dirty set with all current entries and flushes synchronously, so first scan and steady state share one implementation — with opposite failure postures. At activation, a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud `AggregateError` listing every broken package: the fiber FAILS and the boot's fail-loud sweep reports it. In steady state, a broken package logs a warning and must not poison the others. +Package reconciliation is incremental by Loader entry name. Every Cordis `internal/plugin` emission (fiber construction or disposal) marks the fiber's entry name dirty. Each nonempty flush enumerates all Loader entries once and indexes them by name at flush start; pending names use their indexed entries, including all same-name sources, and missing names use an empty list to remove unloaded sources. Package resolution must not synchronously add or remove Loader entries during reconciliation. Activation seeds all current names and flushes synchronously; later notifications queue a microtask flush. + +At activation, malformed declarations, missing bundles, and flush enumeration failures aggregate into a composition error: the fiber fails and boot reports it. In steady state, package failures log warnings without preventing other names from being reconciled. An enumeration failure consumes the failed batch, logs one warning, and leaves package state and the published graph unchanged; each affected name waits for another notification before retrying. Each reconciliation reads the package manifest and the bundle metadata again. A fiber restart from the same source that finds the same declaration and bundle metadata keeps its row and rev and reads no bundle bytes; a changed declaration, client export, or bundle is published by that reconciliation. A bundle rebuilt without an entry restart reaches the graph through `rebuilt()`. diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md index b0a665fe9a..9b2af16fda 100644 --- a/docs/subsystems/client-modules.zh.md +++ b/docs/subsystems/client-modules.zh.md @@ -93,7 +93,9 @@ interface WebBootGraph { 包加入这张表的方式，是在自己的 package.json 中声明 `dsh.client`（`platform: 'web'`、可选的 `inject` 边、可选的 `immediately`），并在 `exports["./client"]` 导出构建好的 bundle。每个 live row 都从自己的 Loader specifier 与所属 tree `baseUrl` 解析；若 `loader.internal.resolveSync` 可用，则使用 Host face import 所用的同一个实现。最近归属的 package manifest 提供浏览器模块 id，因此相对 source 与 built overlay 仍保留包身份。若不同的 active Loader source 解析到同一包名，组合会失败；一个来源卸载后，仍存活的来源无需重启 fiber 即可提供该 row。 -扫描是单包增量的；不存在全量重扫代码路径。fiber 构造或 dispose（资源释放）时的每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。 +包按 Loader entry 名增量对账。fiber 构造或 dispose（资源释放）时的每次 Cordis `internal/plugin` 事件都会把该 fiber 的 entry 名标脏。每次非空 flush 在开始时枚举全部 Loader entries 一次并按名称建索引；待处理名称使用索引中的全部同名来源，缺失名称使用空列表移除已卸载的来源。包解析过程不得在对账期间同步添加或移除 Loader entries。激活阶段初始化全部当前名称并同步 flush；后续通知通过微任务执行 flush。 + +激活时，畸形声明、缺失 bundle 和 flush 枚举失败会聚合为组合错误：fiber 失败，由启动流程报告。稳态下，包失败只记录警告，不妨碍其他名称继续对账。枚举失败会消费失败批次、记录一条警告，并保持包状态和已发布的图不变；受影响的每个名称都要等另一次通知才会重试。 每次对账都会重新读取包 manifest 与 bundle 元数据。同一来源的 fiber 重启若读到相同的声明与 bundle 元数据，就保留其 row 与 rev，且不读取 bundle 字节；声明、client 导出或 bundle 发生变化时，由这次对账发布。没有伴随条目重启的 bundle 重建经 `rebuilt()` 到达图。 diff --git a/docs/subsystems/computer-use.i18n.yaml b/docs/subsystems/computer-use.i18n.yaml index fc82ebf720..54d4801a17 100644 --- a/docs/subsystems/computer-use.i18n.yaml +++ b/docs/subsystems/computer-use.i18n.yaml @@ -3,8 +3,8 @@ # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/computer-use.md /computer-use: - en: aff84e3ac8c41594 - zh: bee7fc09854bfa8b + en: e78e111e0debc21b + zh: 0d218fa34c63cc32 /computer-use/choose-a-provider: en: fa2e0d7b41c0450b zh: af9a799711f901e6 diff --git a/docs/subsystems/computer-use.md b/docs/subsystems/computer-use.md index bc8f1b0491..957990b09c 100644 --- a/docs/subsystems/computer-use.md +++ b/docs/subsystems/computer-use.md @@ -12,7 +12,7 @@ The CUA provider owns `ctx.cuaAccess` for system-permission status, explicit sys | Permission type | Meaning | |---|---| -| `CuaApplicationId`, `CuaApplicationGrant` | An executable/signature identity and its displayed saved decision. | +| `CuaApplicationId`, `CuaApplicationGrant` | A platform-provided application identity and its displayed saved decision. | | `CuaSystemPermission` | Accessibility or Screen Recording, selected by the human. | | `CuaPermissionProcess`, `CuaSystemPermissionState` | Native privilege checks, observed helper/parent processes, and the application identified by macOS process responsibility at helper startup. Application metadata is absent if the optional system query or application lookup is unavailable. | | `CuaApplicationState` | Saved grants, refused applications, and whether persistence is available. Session-only grants remain internal to the provider. System observations and application icons are queried separately so the page can display each result as it arrives. | @@ -85,10 +85,10 @@ Browser controls for provider-owned native permission and application decisions. @Remote async enablePersistentPtc(): Promise /** - * Read application decisions without waiting for the native helper. - * @returns Saved grants and refused applications with their persistence owner. + * Read fresh stored application decisions without issuing a native request. + * @returns Saved grants, refused applications and durable-storage availability. */ -@Remote applications(): CuaApplicationState +@Remote applications(): Promise /** * Inspect system privileges independently of application decisions and icons. @@ -98,7 +98,7 @@ Browser controls for provider-owned native permission and application decisions. /** * Load presentation icons separately from application decisions. - * @returns Optional native PNG icons keyed by executable path for saved and blocked applications. + * @returns Optional native PNG icons keyed by executable path; applications without paths are skipped. */ @Remote async applicationIcons(): Promise> diff --git a/docs/subsystems/computer-use.zh.md b/docs/subsystems/computer-use.zh.md index 1323c6b033..30d6f91ae1 100644 --- a/docs/subsystems/computer-use.zh.md +++ b/docs/subsystems/computer-use.zh.md @@ -12,7 +12,7 @@ CUA provider 通过 `ctx.cuaAccess` 提供系统权限状态、用户主动申 | 权限类型 | 含义 | |---|---| -| `CuaApplicationId`、`CuaApplicationGrant` | 可执行文件和签名身份，以及显示给用户的已保存决定。 | +| `CuaApplicationId`、`CuaApplicationGrant` | 平台提供的应用身份，以及显示给用户的已保存决定。 | | `CuaSystemPermission` | 用户选择申请的辅助功能或屏幕录制权限。 | | `CuaPermissionProcess`、`CuaSystemPermissionState` | 观测到的 helper、父进程和原生权限状态，以及 helper 启动时由 macOS 责任进程记录识别出的应用。可选系统查询或应用查找不可用时，省略应用信息。 | | `CuaApplicationState` | 持久授权、拒绝记录，以及能否持久保存。会话授权只保留在 provider 内部。系统权限和应用图标分别查询，页面在各项结果返回后分别显示。 | @@ -85,10 +85,10 @@ Browser controls for provider-owned native permission and application decisions. @Remote async enablePersistentPtc(): Promise /** - * Read application decisions without waiting for the native helper. - * @returns Saved grants and refused applications with their persistence owner. + * Read fresh stored application decisions without issuing a native request. + * @returns Saved grants, refused applications and durable-storage availability. */ -@Remote applications(): CuaApplicationState +@Remote applications(): Promise /** * Inspect system privileges independently of application decisions and icons. @@ -98,7 +98,7 @@ Browser controls for provider-owned native permission and application decisions. /** * Load presentation icons separately from application decisions. - * @returns Optional native PNG icons keyed by executable path for saved and blocked applications. + * @returns Optional native PNG icons keyed by executable path; applications without paths are skipped. */ @Remote async applicationIcons(): Promise> diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml index d0645fd805..363584a5fd 100644 --- a/docs/subsystems/core.i18n.yaml +++ b/docs/subsystems/core.i18n.yaml @@ -30,8 +30,8 @@ en: 057db6d8bf356c0f zh: 1441b39e5142b0bf /core/repo-wide-type-patterns/the-map-derived-union-pattern: - en: 84c039e929edb897 - zh: 84241bb993f23ef2 + en: 87a19311e2a97270 + zh: 8df92c72793e8275 /core/repo-wide-type-patterns/branded-ids: en: 10f8ac0f97e7c54a zh: 75cd2311aabfe464 diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md index de964e340a..15689f239c 100644 --- a/docs/subsystems/core.md +++ b/docs/subsystems/core.md @@ -450,12 +450,13 @@ declare module '@deepseek-ai/dsh-llm' { } ``` -Five canonical maps use this pattern; a plugin author extends these: +Six canonical maps use this pattern; a plugin author extends these: | Map | Package | Derives | Catalog | |---|---|---|---| | `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) | | `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) | +| `LlmRequestPurposeMap` | dsh-llm | `LlmRequestPurpose` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) | | `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) | | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) | | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) | diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md index 17cfb2d701..4878a104c9 100644 --- a/docs/subsystems/core.zh.md +++ b/docs/subsystems/core.zh.md @@ -460,12 +460,13 @@ declare module '@deepseek-ai/dsh-llm' { } ``` -五个规范 map 使用此模式；插件作者扩展它们： +六个规范 map 使用此模式；插件作者扩展它们： | Map | 包 | 派生 | 目录 | |---|---|---|---| | `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.zh.md#content-blocks-and-messages) | | `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.zh.md#content-blocks-and-messages) | +| `LlmRequestPurposeMap` | dsh-llm | `LlmRequestPurpose` | [llm-streaming.zh.md](llm-streaming.zh.md#the-model-request-and-result) | | `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.zh.md#the-model-request-and-result) | | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.zh.md) | | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.zh.md) | diff --git a/docs/subsystems/forge.i18n.yaml b/docs/subsystems/forge.i18n.yaml new file mode 100644 index 0000000000..92bc2298cd --- /dev/null +++ b/docs/subsystems/forge.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for forge.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/forge.md +/forges: + en: 1b51f9d385dafe76 + zh: 4bb73627aa69d652 +/forges/providers-and-change-requests: + en: 4ec7d1892b4067db + zh: 6bb70d21ae3d7a89 +/forges/status-polling: + en: 26ccfa2e342e3e67 + zh: fe6cc2a622757c48 +/forges/change-request-actions: + en: 87d2c81d9514267f + zh: 1daf31c5b0127a1c +/forges/session-bindings: + en: 13dfd36f2166bba0 + zh: a369434f52f04d57 +/forges/panel: + en: 9a84a26d97cb46f0 + zh: 5e1e03b7714bcbae diff --git a/docs/subsystems/forge.md b/docs/subsystems/forge.md new file mode 100644 index 0000000000..2a3cdf2087 --- /dev/null +++ b/docs/subsystems/forge.md @@ -0,0 +1,1181 @@ +# Forges + +English | [中文](forge.zh.md) + +The experimental forge capability seam reads change requests, meaning pull requests and merge requests, from code hosts. [`dsh-experimental-forge`](../../packages/experimental/forge/README.md) is the Service Definition and provides `ctx.forge`; [`dsh-experimental-forge-github`](../../packages/experimental/forge-github/README.md) is the Service Provider for GitHub hosts; [`dsh-experimental-forge-session`](../../packages/experimental/forge-session/README.md) is the Consumer that binds change requests to Sessions and provides `ctx.forgeSession`; [`dsh-experimental-client-ui-forge`](../../packages/experimental/client-ui-forge/README.md) is the GUI Consumer that provides `ctx.forgePanel`. The default-disabled [forge bundle](../../packages/experimental/forge-bundle/README.md) composes all four, with an isolated [worktree service](../../packages/experimental/worktree/README.md) for the panel, from the Plugins page; otherwise they load only through explicit composition. + +## Providers and change requests + +A provider serves one forge family, such as `github`. It maps Git remote URLs to repositories and change request URLs to references, builds canonical change request URLs, finds open change requests by head branch, and reads status in batches. `changeRequestKey` derives one case-insensitive key from a reference, so watchers of differently spelled URLs share one polling loop. + +```ts type-equiv +/** One repository on a code host, identified the way its provider addresses it. */ +interface ForgeRepository { + /** Provider family that serves the repository, such as `github`. */ + readonly forge: string + /** Lowercase host name, such as `github.com`. */ + readonly host: string + /** Owner or namespace path as the host spells it. */ + readonly owner: string + /** Repository name as the host spells it. */ + readonly name: string +} +``` + +```ts type-equiv +/** One change request (pull request or merge request) in a repository. */ +interface ChangeRequestRef { + /** Repository that holds the change request. */ + readonly repository: ForgeRepository + /** Host-assigned change request number. */ + readonly number: number +} +``` + +```ts type-equiv +/** Canonical identity of a change request across providers; built by `changeRequestKey`. */ +type ChangeRequestKey = Branded<'ChangeRequestKey'> +``` + +```ts type-equiv +/** + * Host-specific access registered with `ctx.forge`. One provider serves one + * forge family; methods that take a signal must stop work when it aborts. + */ +interface ForgeProvider { + /** Forge family name stored in every repository this provider returns. */ + readonly forge: string + /** Publish a comment or completed review. Omission declares that this provider cannot write reviews. */ + submitReview?(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise + /** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */ + repositoryFromRemote(url: string): ForgeRepository | undefined + /** Map a change request web URL to its reference, or undefined when this provider does not serve it. */ + changeRequestFromUrl(url: string): ChangeRequestRef | undefined + /** Build the canonical web URL of a change request this provider serves. */ + changeRequestUrl(ref: ChangeRequestRef): string + /** Read the status of several change requests, returning one result per requested key. */ + fetch( + refs: readonly ChangeRequestRef[], + signal: AbortSignal, + ): Promise> + /** Read all checks for one change request on demand; omission declares that only the polling preview is available. */ + fetchChecks?(ref: ChangeRequestRef, signal: AbortSignal): Promise + /** Find open change requests whose head is `branch` in `repository`, excluding the default branch and forks. */ + findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise + /** Report whether the provider can reach `host` with current credentials. */ + readiness(host: string, signal: AbortSignal): Promise + /** Mark a draft change request ready for review, resolving to undefined once the host accepted it. */ + markReady(ref: ChangeRequestRef, signal: AbortSignal): Promise + /** Merge a change request while its head is still `request.headSha`, resolving to undefined once merged. */ + merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise + /** Read the changes of a change request as the host computes them, as one unified patch with `a/` and `b/` path prefixes. */ + diff(ref: ChangeRequestRef, signal: AbortSignal): Promise + /** Read the text of `path` at `commit` in the change request's repository. */ + fileText(ref: ChangeRequestRef, commit: string, path: string, signal: AbortSignal): Promise + /** Build the web page of `path` at `commit` in the change request's repository. */ + fileUrl(ref: ChangeRequestRef, commit: string, path: string): string +} +``` + +```ts type-equiv +/** Whether a provider can reach one host with the current credentials. */ +interface ForgeReadiness { + /** `ready`, `unauthenticated` (sign-in needed), or `unavailable` (tool missing or host unreachable). */ + readonly state: 'ready' | 'unauthenticated' | 'unavailable' + /** Human-readable detail, or null when ready. */ + readonly message: string | null +} +``` + +## Status polling + +`ctx.forge.watch` shares one polling loop among the watchers of a change request and delivers every result as an update. Each forge has at most one fetch in flight. The [registry README](../../packages/experimental/forge/README.md#use-this-package) owns the poll cadence, backoff, and timeout rules. + +```ts type-equiv +/** Lifecycle state of a change request. */ +type ChangeRequestState = 'open' | 'closed' | 'merged' +``` + +```ts type-equiv +/** Normalized outcome of one status check. */ +type CheckState = 'pending' | 'success' | 'failure' | 'neutral' | 'skipped' | 'cancelled' +``` + +```ts type-equiv +/** One status check reported for the head commit of a change request. */ +interface ChangeRequestCheck { + /** Check name as the host displays it. */ + readonly name: string + /** Normalized check outcome. */ + readonly state: CheckState + /** Web page for the check, or null when the host reports none. */ + readonly url: string | null + /** Workflow that produced the check, or null when the host reports none. */ + readonly workflow: string | null + /** ISO 8601 time the check started, or null before it starts and when the host reports none. */ + readonly startedAt: string | null + /** ISO 8601 time the check completed, or null while it runs and when the host reports none. */ + readonly completedAt: string | null +} +``` + +```ts type-equiv +/** Combined outcome of all checks on the head commit. */ +type ChecksRollup = 'none' | 'pending' | 'success' | 'failure' +``` + +```ts type-equiv +/** Whether the change request can merge into its base without conflicts. */ +type Mergeability = 'mergeable' | 'conflicting' | 'unknown' +``` + +```ts type-equiv +/** Aggregate review outcome required by the host's merge rules. */ +type ReviewDecision = 'approved' | 'changes-requested' | 'review-required' | 'none' +``` + +```ts type-equiv +/** Status of one change request at the time its provider read it. */ +interface ChangeRequestSnapshot { + /** Change request the snapshot describes. */ + readonly ref: ChangeRequestRef + /** Web page of the change request. */ + readonly url: string + /** Title as the author wrote it. */ + readonly title: string + /** Lifecycle state. */ + readonly state: ChangeRequestState + /** Whether the author marked the change request as a draft. */ + readonly draft: boolean + /** Author login, or null when the host hides it. */ + readonly author: string | null + /** Branch that carries the proposed commits. */ + readonly headBranch: string + /** Commit object name at the head of the change request. */ + readonly headSha: string + /** Branch the change request merges into. */ + readonly baseBranch: string + /** Lines the change request adds. */ + readonly additions: number + /** Lines the change request deletes. */ + readonly deletions: number + /** Merge conflict status; `unknown` while the host computes it. */ + readonly mergeability: Mergeability + /** + * Whether the host would merge the change request now for the signed-in + * user: open, not a draft, and meeting the base branch's merge rules. + */ + readonly mergeReady: boolean + /** Merge methods the repository accepts, the signed-in user's usual one first. */ + readonly mergeMethods: readonly MergeMethod[] + /** Aggregate review outcome. */ + readonly reviewDecision: ReviewDecision + /** Checks on the head commit in host order. */ + readonly checks: readonly ChangeRequestCheck[] + /** Combined check outcome. */ + readonly checksRollup: ChecksRollup + /** Whether the host reported more checks than `checks` contains. */ + readonly checksTruncated: boolean + /** Number of review threads that are not resolved. */ + readonly unresolvedThreads: number + /** ISO 8601 time of the host's last update to the change request. */ + readonly updatedAt: string + /** ISO 8601 time the change request was merged or closed, or null while it is open. */ + readonly closedAt: string | null +} +``` + +```ts type-equiv +/** Why a provider could not read a change request. */ +interface ForgeFailure { + /** + * `not-found`: the host does not expose it; `unauthenticated`: credentials are missing or rejected; + * `too-large`: the host or the provider refuses an answer over its size limit, so reading again fails + * the same way; `unavailable`: any other failure. + */ + readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'unavailable' + /** Human-readable cause. */ + readonly message: string +} +``` + +```ts type-equiv +/** Latest polling result delivered to watchers of one change request. */ +type ChangeRequestUpdate = { + /** Canonical identity of the watched change request. */ + readonly key: ChangeRequestKey + /** Epoch milliseconds when the result settled. */ + readonly fetchedAt: number +} & ({ + /** Status read from the host. */ + readonly snapshot: ChangeRequestSnapshot +} | { + /** Reason the status could not be read. */ + readonly failure: ForgeFailure +}) +``` + +```ts type-equiv +/** + * Receives every polling result for one watched change request. + * @param update - the settled result. + */ +type ChangeRequestListener = (update: ChangeRequestUpdate) => void +``` + +## Change request actions + +`ctx.forge.markReady` marks a draft ready for review, and `ctx.forge.merge` merges a change request only while its head is still the commit the user confirmed. Both resolve to a `ForgeActionFailure` instead of throwing when the host refuses, and poll a watched change request at once afterwards. A snapshot's `mergeReady` and `mergeMethods` tell a consumer when to offer a merge and with which methods; the [GitHub provider README](../../packages/experimental/forge-github/README.md#use-this-package) owns how GitHub answers both. + +```ts type-equiv +/** A merge the user confirmed for the head commit they saw. */ +interface MergeRequest { + /** How the commits enter the base branch. */ + readonly method: MergeMethod + /** Commit object name the head must still have; the merge is refused once the head moves. */ + readonly headSha: string +} +``` + +```ts type-equiv +/** Why a provider could not change a change request. */ +interface ForgeActionFailure { + /** + * `unauthenticated`: credentials are missing or rejected; `stale`: the head + * moved past the confirmed commit; `failed`: the host refused or could not be reached. + */ + readonly code: 'unauthenticated' | 'stale' | 'failed' + /** Human-readable cause, usually the host's own message. */ + readonly message: string +} +``` + +`ctx.forge.submitReview` delegates an explicit comment or completed review to the provider. A provider that omits this capability returns unsupported. Consumers retain pending drafts and reconcile unknown write outcomes before resubmitting. + +```ts type-equiv +/** One inline comment addressed to the old or new side of a pull request diff. */ +interface ForgeLineComment { + readonly path: string + readonly side: 'L' | 'R' + readonly startLine: number + readonly endLine: number + readonly body: string +} +``` + +```ts type-equiv +/** A single published comment or one completed review containing all pending comments. */ +type ForgeReviewRequest = { + /** Commit the user reviewed; providers must check it before writing and address that commit explicitly. */ + readonly headSha: string +} & ( + | { readonly kind: 'comment'; readonly comment: ForgeLineComment } + | { readonly kind: 'review'; readonly event: 'comment' | 'approve' | 'request-changes'; readonly body: string; readonly comments: readonly ForgeLineComment[] } +) +``` + +```ts type-equiv +/** Result of a review write; unknown outcomes must be checked on the host before another submission. */ +type ForgeReviewResult = + | { readonly ok: true; readonly url: string } + | { readonly ok: false; readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown'; readonly message: string } +``` + +## Session bindings + +`ctx.forgeSession` derives each Session's bindings from its own log: `gh pr create` results bind the URLs they print, `gh pr view`, `gh pr edit`, and `gh pr checkout` calls bind the change request they act on, and `git push` results trigger head-branch discovery through `ctx.forge`; the panel also reports the branch its checkout tracks for the same discovery. Track, dismiss, and discovery actions are `plugin:forge-session/binding` records, which stay outside the model-visible conversation. The `forgeChangeRequests` projection's client view, which the Session summary carries, lists the bindings without their status. The [Session binding README](../../packages/experimental/forge-session/README.md#use-this-package) owns the recognition and discovery rules. + +```ts type-equiv +/** + * How a change request became bound to a Session: `created` when a + * `gh pr create` result printed its URL, `referenced` when a `gh pr view`, + * `gh pr edit`, or `gh pr checkout` call named it or its result printed its + * own URL, `discovered` when a lookup found it for a branch the Session pushed + * or works on, `tracked` when a caller bound it by URL. + */ +type BindingOrigin = 'created' | 'referenced' | 'discovered' | 'tracked' +``` + +```ts type-equiv +/** Payload of the `plugin:forge-session/binding` record. */ +interface BindingRecord { + /** + * `track` binds or restores, `dismiss` hides, `discover` binds a branch lookup, + * and `reference` binds a CLI selector lookup without restoring dismissed entries. + */ + readonly action: 'track' | 'dismiss' | 'discover' | 'reference' + /** Web URL of the change request. */ + readonly url: string +} +``` + +```ts type-equiv +/** One change request bound to a Session and not dismissed, with its latest polling result. */ +interface SessionChangeRequest { + /** Web URL as first recorded. */ + readonly url: string + /** How the change request became bound. */ + readonly origin: BindingOrigin + /** Parsed reference, or null when no registered provider serves the URL. */ + readonly ref: ChangeRequestRef | null + /** Latest polling result, or null before the first poll and without a provider. */ + readonly update: ChangeRequestUpdate | null +} +``` + +```ts type-equiv +/** + * Receives the complete visible list after a binding or provider change, or a polling result. + * @param changeRequests - every visible binding of the watched Session, in first-recorded order. + */ +type SessionChangeRequestsListener = (changeRequests: readonly SessionChangeRequest[]) => void +``` + +## Panel + +`ctx.forgePanel` is the Host Remote of the [forge panel](../../packages/experimental/client-ui-forge/README.md#use-this-package). Following a Session streams a `ForgePanelState`: a read-only Git inspection of the Session's current directory in its execution world, the code host recognized from the upstream remote or `origin`, the sign-in state of that host, the Session's bindings with their polled status and last snapshot, and its worktree request. Its actions list base branches, bind and hide URLs, refresh, mark a bound draft ready or merge a bound change request, request or withdraw a worktree, stop a running creation, and restore a removed worktree or leave it for the source checkout. A request is a `plugin:client-ui-forge/worktree` record. When a message enters a Session's inbox while its Agent is idle, the panel holds the message's turn with maintenance of the [Agent](../../packages/core/agent/README.md), started before the delivery wakes the Agent: it creates the worktree of an open request through `ctx.worktrees` and, after a failed or stopped attempt, waits for another attempt or the request's withdrawal; for a Session that works in its created worktree it checks that worktree and, when it is gone, waits until it is restored or left. The panel state names what a message waits for and the last failed attempt. The first step proposal creates the worktree for a message no hold took. Requests after the first turn starts are ignored. Changes to a Session's checkout run as maintenance of its Agent, so a message from another client waits for them. + +```ts type-equiv +/** Git facts for the checkout that contains the Session's current directory. */ +interface ForgeCheckout { + /** Top-level directory of the checkout. */ + readonly root: string + /** Checked-out branch, or null when HEAD is detached. */ + readonly branch: string | null + /** Whether the checkout is a linked worktree of another checkout's repository. */ + readonly linked: boolean + /** Abbreviated commit HEAD names, or null while the checked-out branch has no commit. */ + readonly commit: string | null +} +``` + +```ts type-equiv +/** Inspection result for the Session's current directory. */ +type ForgeCheckoutState = + /** The first inspection has not finished. */ + | { readonly state: 'pending' } + /** The current directory is not inside a Git checkout. */ + | { readonly state: 'none' } + /** Git could not run or reported an error. */ + | { readonly state: 'failed'; readonly message: string } + /** The checkout facts. */ + | { readonly state: 'ready'; readonly checkout: ForgeCheckout } +``` + +```ts type-equiv +/** The worktree the panel created and entered for a Session before its first step. */ +interface ForgeSessionWorktree { + /** Canonical checkout directory. */ + readonly path: string + /** Branch created for the checkout. */ + readonly branch: string + /** Requested base branch, or null when the checkout started from HEAD of the source checkout. */ + readonly from: string | null + /** Commit object name the branch started from. */ + readonly baseCommit: string + /** Canonical root of the source checkout. */ + readonly repositoryRoot: string +} +``` + +```ts type-equiv +/** Payload of the `plugin:client-ui-forge/worktree` record. */ +type WorktreeRecord = + /** Create a worktree before the Session's first step, starting from `from`, or from HEAD when it is null. */ + | { readonly action: 'request'; readonly from: string | null } + /** Withdraw the open request. */ + | { readonly action: 'cancel' } + /** The requested worktree was created and became the Session's working directory. */ + | { readonly action: 'created'; readonly worktree: ForgeSessionWorktree } + /** Restoration started; the checkout stays unavailable until restoration completes. */ + | { readonly action: 'restoring' } + /** The recorded worktree was completely restored. */ + | { readonly action: 'restored' } +``` + +```ts type-equiv +/** One open worktree request. */ +interface ForgeWorktreeRequest { + /** Base branch, or null for HEAD of the source checkout. */ + readonly from: string | null +} +``` + +```ts type-equiv +/** Why the Session's checkout cannot host a new worktree. */ +type ForgeWorktreeBlocker = + /** The current directory is not inside a Git checkout. */ + | 'not-git' + /** The Session's sandbox cannot write the checkout or its Git directory, as for a linked worktree outside the writable root. */ + | 'outside-writable-root' + /** The Session runs read-only. */ + | 'read-only' +``` + +```ts type-equiv +/** One running worktree creation. */ +interface ForgeWorktreeCreation { + /** Running step: `prepare` validates and creates the branch, then `checkout` writes the files. */ + readonly phase: 'prepare' | 'checkout' + /** Branch the attempt creates. */ + readonly branch: string + /** Base branch, or null for HEAD. */ + readonly from: string | null + /** + * Whether a message waits for the creation before its turn starts. Only + * such a creation can be stopped, after which the message keeps waiting; a + * creation at the first step serves a message the Session already holds. + */ + readonly held: boolean +} +``` + +```ts type-equiv +/** One running restoration of the removed worktree a Session works in. */ +interface ForgeWorktreeRestoration { + /** Running step: `prepare` registers the checkout again, creating a missing branch, then `checkout` writes the files. */ + readonly phase: 'prepare' | 'checkout' +} +``` + +```ts type-equiv +/** The last attempt to create the requested worktree for a message, which failed. */ +interface ForgeWorktreeFailure { + /** Branch the attempt created, or null when it failed before naming one. */ + readonly branch: string | null + /** Base branch of the attempt, or null for HEAD. */ + readonly from: string | null + /** Step that failed. */ + readonly phase: 'prepare' | 'checkout' + /** Failure text. */ + readonly message: string +} +``` + +```ts type-equiv +/** + * What a message waits for before its turn starts: the creation of the + * requested worktree, or the restoration or leaving of the removed worktree + * the Session works in. + */ +type ForgeWorktreeWaiting = 'creation' | 'restoration' +``` + +```ts type-equiv +/** The recorded worktree whose directory is missing, invalid, or incompletely restored. */ +interface ForgeMissingWorktree { + /** Whether its branch exists, or null when an incomplete restoration cannot inspect it. */ + readonly branchExists: boolean | null +} +``` + +```ts type-equiv +/** Worktree facts of one Session in the panel state. */ +interface ForgePanelWorktree { + /** + * Whether the Session can still request or withdraw a worktree: a worktree + * service is mounted, no turn has started, and none was created. + */ + readonly editable: boolean + /** Why the checkout cannot host a worktree, or null when it can, before the first inspection, and after a failed one. */ + readonly blocker: ForgeWorktreeBlocker | null + /** Open request, or null without one. */ + readonly request: ForgeWorktreeRequest | null + /** Created worktree, or null before creation. */ + readonly created: ForgeSessionWorktree | null + /** Running creation, or null. */ + readonly creation: ForgeWorktreeCreation | null + /** + * The last failed attempt of the creation a message waits for, or null. It + * clears when another attempt starts, when the request changes or is + * withdrawn, and when the wait ends. + */ + readonly failure: ForgeWorktreeFailure | null + /** The created worktree the Session works in when its directory is gone, or null. */ + readonly missing: ForgeMissingWorktree | null + /** Running restoration of the removed worktree, or null. */ + readonly restoration: ForgeWorktreeRestoration | null + /** What a message of the Session waits for before its turn starts, or null while none waits. */ + readonly waiting: ForgeWorktreeWaiting | null +} +``` + +```ts type-equiv +/** One bound change request in the panel state. */ +interface ForgePanelChangeRequest extends SessionChangeRequest { + /** Latest snapshot a poll returned, kept while later polls fail, or null before the first successful poll. */ + readonly snapshot: ChangeRequestSnapshot | null +} +``` + +```ts type-equiv +/** Everything the panel shows for one Session. */ +interface ForgePanelState { + /** Current working directory of the Session. */ + readonly directory: string + /** Inspection result for `directory`. */ + readonly checkout: ForgeCheckoutState + /** Code host repository of the checkout's upstream remote or `origin`, or null when no provider serves them. */ + readonly repository: ForgeRepository | null + /** Sign-in state for the repository's host, or null before the first probe and without a repository. */ + readonly readiness: ForgeReadiness | null + /** Visible change request bindings with their latest polling results, in first-recorded order. */ + readonly changeRequests: readonly ForgePanelChangeRequest[] + /** Worktree request and creation state. */ + readonly worktree: ForgePanelWorktree + /** + * Files the `branch` scope changes, or null before the first inspection, + * outside a checkout, and without a fork point. + */ + readonly local: ForgeLocalChanges | null +} +``` + +```ts type-equiv +/** Local branches offered as the base of a new worktree. */ +interface ForgeBranches { + /** Checked-out branch, or null when HEAD is detached. */ + readonly current: string | null + /** Local branch names, `current` first and then most recently committed first, at most `maxBranches`. */ + readonly branches: readonly string[] +} +``` + +The Session list reads through the same Remote. `changeRequestStates` streams `ForgeChangeRequestStatesFrame` values: a `baseline` with the last known `ForgeChangeRequestListState` of every change request that a listed Session the caller may read binds, then the states that change. One Host run serves every stream; it takes the bindings of loaded Sessions from `ctx.forgeSession` and those of other Sessions from their cached Session summary without loading them, keeps each bound change request subscribed, including closed requests polled at the idle cadence to detect reopening, and stores every change, so a restart shows the last known states before the next poll. The Session summary also carries the `forgeWorktree` projection's client view: the created worktree while the Session's directory is that worktree or lies below it, else null. + +```ts type-equiv +/** + * The last polled state of one change request that a listed Session binds, as + * the Session list shows it. + */ +type ForgeChangeRequestListState = Pick< + ChangeRequestSnapshot, 'url' | 'title' | 'state' | 'draft' | 'checksRollup' | 'reviewDecision' | 'mergeability' +> & { + /** Change request number on its code host. */ + readonly number: number +} +``` + +```ts type-equiv +/** + * One frame of `forgePanel.changeRequestStates`: the known state of every + * change request the reader may see first, then the states that changed or + * became visible since the previous frame. + */ +type ForgeChangeRequestStatesFrame = + | { readonly type: 'baseline'; readonly states: readonly ForgeChangeRequestListState[] } + | { readonly type: 'changed'; readonly states: readonly ForgeChangeRequestListState[] } +``` + +The changes view reads through the same Remote. `localDiff` reads one `ForgeLocalScope` of the Session's checkout, and `changeRequestDiff` reads a bound change request at the head of its latest status through the provider's `diff`; both return files that the Host parsed into `ForgeDiffFile` hunks. `localText` and `changeRequestText` read the new side of one file, which supplies the unchanged lines between hunks. Each inspection also sizes the `branch` scope as `ForgePanelState.local` for the panel's local changes card. + +```ts type-equiv +/** Which local changes a diff covers; each reads the Session's checkout through Git. */ +type ForgeLocalScope = + /** + * The working tree and untracked files against the fork point: the base commit of the worktree the + * Session created, else the merge base of HEAD with the default branch of the code host remote. + */ + | { readonly kind: 'branch' } + /** The working tree and untracked files against HEAD. */ + | { readonly kind: 'uncommitted' } + /** The working tree and untracked files against the index. */ + | { readonly kind: 'unstaged' } + /** The index against HEAD. */ + | { readonly kind: 'staged' } +``` + +```ts type-equiv +/** One hunk of a file diff. */ +interface ForgeDiffHunk { + /** First old line the hunk covers, or the old line it comes before when it covers none. */ + readonly oldStart: number + /** Old lines the hunk covers. */ + readonly oldLines: number + /** First new line the hunk covers, or the new line it comes before when it covers none. */ + readonly newStart: number + /** New lines the hunk covers. */ + readonly newLines: number + /** Lines in patch form: a leading space for context, `+` for added, `-` for deleted, and `\` for a missing final newline. */ + readonly lines: readonly string[] +} +``` + +```ts type-equiv +/** How one file changed. */ +type ForgeDiffStatus = 'added' | 'deleted' | 'modified' | 'renamed' +``` + +```ts type-equiv +/** One changed file of a diff. */ +interface ForgeDiffFile { + /** Path relative to the repository root after the change, or before it for a deleted file. */ + readonly path: string + /** Path before a rename, else null. */ + readonly previousPath: string | null + /** How the file changed. */ + readonly status: ForgeDiffStatus + /** Whether the content is binary, which carries no hunks. */ + readonly binary: boolean + /** Whether an untracked file exceeds `maxDiffBytes`, so it carries no hunks. */ + readonly oversized: boolean + /** Whether Git does not track the file yet; only local diffs list such files. */ + readonly untracked: boolean + /** Lines added. */ + readonly additions: number + /** Lines deleted. */ + readonly deletions: number + /** Hunks in file order; none for a binary file or a change of mode or name only. */ + readonly hunks: readonly ForgeDiffHunk[] +} +``` + +```ts type-equiv +/** Local changes of the Session's checkout in one scope. */ +interface ForgeLocalDiff { + /** Ref or abbreviated commit the `branch` scope compares with, such as `origin/master`; null for other scopes. */ + readonly base: string | null + /** Changed files in Git's path order, untracked files last. */ + readonly files: readonly ForgeDiffFile[] + /** Untracked files left out beyond `maxUntrackedFiles`. */ + readonly omitted: number +} +``` + +```ts type-equiv +/** Changes of a change request as its code host computes them. */ +interface ForgeChangeRequestDiff { + /** Head commit the diff describes. */ + readonly headSha: string + /** Changed files in the host's order. */ + readonly files: readonly ForgeDiffFile[] + /** + * Commits the checkout's branch has beyond the head when that branch is the change request's head + * branch and the head commit is present locally; null otherwise. + */ + readonly localAhead: number | null + /** Web page of each changed file at the head commit, by path. */ + readonly fileUrls: Readonly> +} +``` + +```ts type-equiv +/** One file the `branch` scope changes, without its hunks. */ +interface ForgeChangedFile { + /** Path relative to the repository root after the change. */ + readonly path: string + /** Lines added, or 0 for a binary file. */ + readonly additions: number + /** Lines deleted, or 0 for a binary file. */ + readonly deletions: number + /** Whether the content is binary. */ + readonly binary: boolean +} +``` + +```ts type-equiv +/** Size of the `branch` scope, which the panel's local changes card shows. */ +interface ForgeLocalChanges { + /** Ref or abbreviated commit the scope compares with. */ + readonly base: string + /** Changed files in Git's path order, untracked files last, at most `maxUntrackedFiles` of those. */ + readonly files: readonly ForgeChangedFile[] +} +``` + + + + + +## 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). + + + +### `ctx.forge` — `ForgeService` + +Registry of forge providers. Watchers of one change request share a single polling loop; each forge has at most one fetch in flight, which batches every due change request of that forge. + +```ts cordis-catalog +/** + * Register the provider of one forge family as an effect on the calling + * fiber. Watches of that forge receive an `unavailable` failure when the + * registration ends. Unregistering cancels and awaits its in-flight calls; + * results from the withdrawn registration are discarded. + * @param provider - provider to serve `provider.forge`. + * @returns the disposer that unregisters the provider and waits for its calls to finish. + * @throws when another provider already serves the same forge. + */ +register(provider: ForgeProvider): () => Promise + +/** + * Map a Git remote URL to a repository through the first provider that serves it. + * @param url - fetch or push URL as Git reports it. + * @returns the repository, or undefined when no provider serves the URL. + */ +repositoryFromRemote(url: string): ForgeRepository | undefined + +/** + * Map a change request web URL through the first provider that serves it. + * @param url - web URL of a pull or merge request. + * @returns the change request, or undefined when no provider serves the URL. + */ +changeRequestFromUrl(url: string): ChangeRequestRef | undefined + +/** + * Build the canonical web URL of a change request. + * @param ref - change request served by a registered provider. + * @returns the provider's canonical URL. + * @throws when no provider serves the change request's forge. + */ +changeRequestUrl(ref: ChangeRequestRef): string + +/** + * Find open change requests whose head is `branch`, excluding the default branch and forks. + * @param repository - repository served by a registered provider. + * @param branch - head branch name on the host. + * @param signal - cancellation for the lookup. + * @returns matching change requests, newest first as the provider reports them. + * @throws when no provider serves the repository's forge or the lookup fails. + */ +async findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise + +/** + * Report whether the provider can reach the repository's host with current credentials. + * @param repository - repository served by a registered provider. + * @param signal - cancellation for the probe. + * @returns the provider's readiness for the host. + * @throws when no provider serves the repository's forge. + */ +async readiness(repository: ForgeRepository, signal: AbortSignal): Promise + +/** + * Mark a draft change request ready for review, then poll it at once when it is watched. + * @param ref - change request served by a registered provider. + * @param signal - cancellation of the request. + * @returns undefined once the host accepted the change, or why it did not. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async markReady(ref: ChangeRequestRef, signal: AbortSignal): Promise + +/** + * Merge a change request while its head is still `request.headSha`, then + * poll it at once when it is watched. + * @param ref - change request served by a registered provider. + * @param request - merge method and the head commit the user confirmed. + * @param signal - cancellation of the request. + * @returns undefined once the host merged it, or why it did not. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise + +/** + * Read complete check details independently of periodic polling. + * @param ref - change request served by a registered provider. + * @param signal - cancellation of the detail view. + * @returns a complete snapshot or the provider's failure; unsupported providers return unavailable. + * @throws on cancellation, provider disposal, or expiry of this read's own `fetchTimeoutMs` deadline. + */ +async fetchChecks(ref: ChangeRequestRef, signal: AbortSignal): Promise + +/** + * Read the changes of a change request as its host computes them. + * @param ref - change request served by a registered provider. + * @param signal - cancellation of the read. + * @returns one unified patch with `a/` and `b/` path prefixes, or why the host did not provide it. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async diff(ref: ChangeRequestRef, signal: AbortSignal): Promise + +/** + * Publish one comment or a completed review, then refresh the watched status. + * @param ref - change request served by a registered provider. + * @param request - explicitly selected commit, comments, and review decision. + * @param signal - request cancellation. + * @returns a publication URL or a failure, including an unknown write outcome. + */ +async submitReview(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise + +/** + * Read the text of one file at a commit of a change request's repository. + * @param ref - change request served by a registered provider. + * @param commit - commit object name. + * @param path - path relative to the repository root. + * @param signal - cancellation of the read. + * @returns the text, or why the host did not provide it. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async fileText(ref: ChangeRequestRef, commit: string, path: string, signal: AbortSignal): Promise + +/** + * Build the web page of one file at a commit of a change request's repository. + * @param ref - change request served by a registered provider. + * @param commit - commit object name. + * @param path - path relative to the repository root. + * @returns the provider's URL. + * @throws when no provider serves the change request's forge. + */ +fileUrl(ref: ChangeRequestRef, commit: string, path: string): string + +/** + * Watch one change request as an effect on the calling fiber. The first + * watcher starts polling at once; listeners receive every later result, + * and `latest` returns the current one. Polling stops when the last watcher + * leaves. Listeners must not throw; a thrown error is logged and skipped. + * @param ref - change request to poll. + * @param listener - receives each polling result. + * @returns the disposer that stops this watch. + */ +watch(ref: ChangeRequestRef, listener: ChangeRequestListener): () => void + +/** + * Poll a watched change request at once, including after a terminal state. + * A fetch already in flight is followed immediately by another fetch; an + * unwatched change request is unchanged. + * @param ref - change request to poll. + */ +refresh(ref: ChangeRequestRef): void + +/** + * Read the latest polling result of a watched change request. + * @param ref - change request to read. + * @returns the latest result, or undefined before the first result or without a watch. + */ +latest(ref: ChangeRequestRef): ChangeRequestUpdate | undefined +``` + +Source: [`packages/experimental/forge/src/index.ts`](../../packages/experimental/forge/src/index.ts) + + + +### `ctx.forgePanel` — `ForgePanelController` + +Serves the forge panel. Following a Session inspects the checkout of its current directory using the Session's permissions and execution world, recognizes the code host of the upstream remote or `origin`, probes sign-in for that host, and polls the Session's bound change requests through `ctx.forge` until the last follower of that Session leaves. A worktree request makes the panel create a branch and checkout through an optional `ctx.worktrees` and enter it while the Session's first message waits in the inbox, or at the first step proposal of a message no wait took. After a failed or stopped attempt the message keeps waiting for another attempt or for the request to be withdrawn. A message also waits while the worktree the Session works in is gone, until that worktree is checked out again or left for the source checkout. Changes to a Session's checkout run as Agent maintenance, so a message that arrives meanwhile waits for them. + +```ts cordis-catalog +/** + * Stream the panel state of a Session: the current state first, then each + * later state. Intermediate states may be skipped when the reader is slower + * than the updates. The stream ends when `signal` aborts or the Remote stops. + * @param session - Session to follow. + * @param signal - ends the stream. + * @returns panel states in publication order. + */ +@Remote({ mode: 'stream' }) async *follow(session: Session, signal: AbortSignal): AsyncIterable + +/** + * Stream the last known state of every change request that a listed + * Session the caller may read binds: the stored states first, then each + * state a poll changes or a new binding reveals. Listing reads no Session + * log: loaded Sessions report their bindings, others the cached Session + * summary, and a Session without one shows nothing until it is opened. + * Closed requests are polled at the idle cadence so reopening is observed. The + * stream ends when `signal` aborts or the Remote stops. + * @param signal - ends the stream. + * @returns frames in publication order. + * @throws when the Host lacks the Session query, projection cache, storage, or Session store service. + */ +@Remote({ mode: 'stream' }) async *changeRequestStates(signal: AbortSignal): AsyncIterable + +/** + * List the local branches that can start a worktree of the Session's current checkout. + * @param session - Session whose current directory is listed. + * @param signal - request cancellation. + * @returns the checked-out branch and at most `maxBranches` local branches, the checked-out one first. + * @throws when the current directory is not inside a checkout or Git fails. + */ +@Remote async branches(session: Session, signal: AbortSignal): Promise + +/** + * Bind a change request to a Session by URL, or restore a dismissed binding. + * @param session - Session that receives the binding. + * @param url - web URL of the change request. + * @param signal - request cancellation. + * @throws `forgePanel/unrecognized-url` when no registered provider serves the URL. + */ +@Remote async track(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Hide a visible binding of a Session; other URLs leave the Session unchanged. + * @param session - Session that owns the binding. + * @param url - web URL of the change request. + * @param signal - request cancellation. + */ +@Remote async dismiss(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Reinspect a followed Session's checkout, probe sign-in again, and poll its + * change requests at once; an unfollowed Session is unchanged. + * @param session - Session whose panel refreshes. + * @param signal - request cancellation. + * @returns settles once the inspection and the sign-in probe have ended; poll results reach the panel stream later. + */ +@Remote async refresh(session: Session, signal: AbortSignal): Promise + +/** + * Read the changes one scope covers in the checkout of the Session's + * current directory, with Git using the Session's sandbox policy. + * @param session - Session whose checkout is read. + * @param scope - which changes to read. + * @param signal - request cancellation. + * @returns the files, the base of the `branch` scope, and the untracked files left out. + * @throws `forgePanel/not-a-checkout` outside a checkout; `forgePanel/no-fork-point` for the `branch` + * scope of a checkout without one; `forgePanel/filter-config-failed` when filter configuration cannot be read + * completely, before any comparison; `forgePanel/diff-too-large` over `maxDiffBytes`; the Git error when Git fails. + */ +@Remote async localDiff(session: Session, scope: ForgeLocalScope, signal: AbortSignal): Promise + +/** + * Read the new side of one changed file in a scope, which supplies the + * unchanged lines between its hunks: the index for `staged`, else the working tree. + * @param session - Session whose checkout is read. + * @param scope - the scope the diff was read in. + * @param path - path relative to the checkout's top-level directory, as the diff names it. + * @param signal - request cancellation. + * @returns the text. + * @throws `forgePanel/not-a-checkout` outside a checkout; `forgePanel/diff-too-large` over `maxDiffBytes`; + * an error for a path outside the checkout, binary content, or a failed read. + */ +@Remote async localText(session: Session, scope: ForgeLocalScope, path: string, signal: AbortSignal): Promise + +/** + * Load complete checks for the change request whose list the user opened. + * @param session - Session retaining the visible binding. + * @param url - binding URL. + * @param headSha - commit displayed by the card; a different head rejects the result. + * @param signal - cancellation when the list closes. + * @returns the complete snapshot at the displayed head. + * @throws `forgePanel/not-bound` for an invisible binding, `forgePanel/stale-head` for a moved head, + * or `forgePanel/checks-failed` when the provider cannot complete the read. + */ +@Remote async changeRequestChecks(session: Session, url: string, headSha: string, signal: AbortSignal): Promise + +/** + * Read the changes of a change request of a Session as its code host + * computes them, at the head commit of its latest status. A patch already + * read at the same head commit and base branch is reused from memory, for + * any Session, until `maxCachedDiffBytes` evicts it. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param signal - request cancellation. + * @returns the files, the head commit, each file's web page, and the commits the checkout has beyond the head. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/diff-too-large` when the host or its provider refuses the diff over a size limit; + * `forgePanel/diff-failed` before its status was read and when the host does not provide the diff otherwise. + */ +@Remote async changeRequestDiff(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Read one file of a change request's repository at a commit, which + * supplies the unchanged lines between the hunks of its diff. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param commit - commit object name, the head commit of the diff. + * @param path - path relative to the repository root. + * @param signal - request cancellation. + * @returns the text. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/diff-too-large` when the host or its provider refuses the file over a size limit; + * `forgePanel/diff-failed` when the host does not provide the file otherwise. + */ +@Remote async changeRequestText(session: Session, url: string, commit: string, path: string, signal: AbortSignal): Promise + +/** + * Publish a line comment or completed review for a visible Session binding. + * @param session - Session retaining the change request. + * @param url - visible binding URL. + * @param request - reviewed head, ranges, plain text, and explicit review decision. + * @param signal - request cancellation. + * @returns confirmed publication or a typed failure; unknown outcomes require reconciliation on the host. + */ +@Remote async submitReview(session: Session, url: string, request: ForgeReviewRequest, signal: AbortSignal): Promise + +/** + * Mark a draft change request of a Session ready for review; the change + * request is polled again once the host answers. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param signal - request cancellation. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/action-failed` with the host's reason when the host refuses or cannot be reached. + */ +@Remote async markReady(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Merge a change request of a Session while its head is still `headSha`; + * the change request is polled again once the host answers. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param method - how the commits enter the base branch. + * @param headSha - head commit the user confirmed. + * @param signal - request cancellation. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/stale-head` when the head moved past `headSha`; `forgePanel/action-failed` with the host's + * reason when the host refuses otherwise or cannot be reached. + */ +@Remote async merge(session: Session, url: string, method: MergeMethod, headSha: string, signal: AbortSignal): Promise + +/** + * Ask for a new worktree before the Session's first turn, replacing an open + * request and forgetting a failed attempt. While the next message waits in + * the inbox, or else at the first step proposal, the panel creates a branch + * from `from`, or from HEAD of the current checkout when it is null, and + * enters its checkout. A message that already waits after a failed or + * stopped attempt keeps waiting for {@link ForgePanelController.retryWorktree}. + * @param session - Session without a started turn. + * @param from - local base branch, or null for HEAD. + * @param signal - request cancellation. + * @throws `forgePanel/invalid-branch` when `from` is empty; `forgePanel/worktrees-unavailable` + * without a worktree service; `forgePanel/session-started` after a turn started or the worktree was + * created; `forgePanel/session-busy` while the worktree is being created. + */ +@Remote async requestWorktree(session: Session, from: string | null, signal: AbortSignal): Promise + +/** + * Withdraw the open worktree request of a Session with its failed attempt, + * which lets a waiting message go on in the current checkout; without a + * request the Session is unchanged. Withdrawing needs no worktree service. + * @param session - Session without a started turn. + * @param signal - request cancellation. + * @throws `forgePanel/session-started` after a turn started or the worktree was created; + * `forgePanel/session-busy` while the worktree is being created. + */ +@Remote async cancelWorktree(session: Session, signal: AbortSignal): Promise + +/** + * Stop the creation a message of the Session waits for; the message keeps + * waiting with the request still open. Without such a creation the Session + * is unchanged. + * @param session - Session whose creation stops. + * @param signal - request cancellation. + */ +@Remote async stopCreation(session: Session, signal: AbortSignal): Promise + +/** + * Make another attempt, with a new branch name, at the worktree a message + * of the Session waits for after a failed or stopped attempt. + * @param session - Session whose message waits. + * @param signal - request cancellation. + * @throws `forgePanel/not-waiting` when no message waits or an attempt is running. + */ +@Remote async retryWorktree(session: Session, signal: AbortSignal): Promise + +/** + * Check out the created worktree of a Session again at its recorded + * directory when that directory is gone: its branch when the branch still + * exists, otherwise a new branch of the same name at the base commit. Changes + * that were never committed are not recovered. Runs as Agent maintenance, + * inside the wait of a message that waits for the restoration, which then + * goes on; without a missing directory the Session is unchanged. + * @param session - Session whose worktree directory is gone. + * @param signal - request cancellation, which aborts the restoration. + * @throws `forgePanel/no-worktree` without a created worktree; `forgePanel/worktrees-unavailable` + * without a worktree service; `forgePanel/session-busy` while the Session's Agent is not loaded or + * has other work; `forgePanel/restore-failed` when Git fails. + */ +@Remote async restoreWorktree(session: Session, signal: AbortSignal): Promise + +/** + * Move a Session from its created worktree to the source checkout the + * worktree came from; the Session no longer works in the worktree. Runs as + * Agent maintenance, inside the wait of a message that waits for the removed + * worktree, which then goes on. + * @param session - Session with a created worktree. + * @param signal - request cancellation. + * @throws `forgePanel/no-worktree` without a created worktree; `forgePanel/session-busy` while the + * Session's Agent is not loaded or has other work; the working-directory service's error when the + * source checkout no longer exists. + */ +@Remote async continueInProject(session: Session, signal: AbortSignal): Promise +``` + +Types: [Session](session.md) + +Source: [`packages/experimental/client-ui-forge/src/index.ts`](../../packages/experimental/client-ui-forge/src/index.ts) + + + +### `ctx.forgeSession` — `ForgeSessionService` + +Session-scoped change request bindings. The `forgeChangeRequests` projection derives them from `gh pr create`, `gh pr view`, `gh pr edit`, `gh pr checkout`, and `git push` results and from `plugin:forge-session/binding` records. After each push result, and when a caller reports the branch a Session works on, the service looks up open change requests whose head is that branch and records the unbound ones as discovered. Watching a Session polls its visible change requests through `ctx.forge`. + +```ts cordis-catalog +/** + * List the change requests bound to a Session and not dismissed. + * @param session - Session whose bindings are read. + * @returns visible bindings in first-recorded order, each with its latest polling result. + */ +changeRequests(session: Session): SessionChangeRequest[] + +/** + * Bind a change request to a Session by URL, or restore a dismissed binding. + * Appends a `track` record with the provider's canonical URL unless the + * change request is already visible. + * @param session - Session that receives the binding. + * @param url - web URL of the change request. + * @throws when no registered provider recognizes the URL. + */ +track(session: Session, url: string): void + +/** + * Look up open change requests whose head is a branch the Session works on, + * and record the unbound ones as discovered, as after a push of that branch. + * A remote that no provider recognizes changes nothing; a failed lookup is + * logged and changes nothing. + * @param session - Session that receives the bindings. + * @param remote - URL of the remote that holds the branch. + * @param branch - branch name on that remote. + * @returns resolves once the lookup has recorded its bindings or failed. + */ +discoverBranch(session: Session, remote: string, branch: string): Promise + +/** + * Hide a visible binding. Appends a `dismiss` record; a URL that is not + * visibly bound leaves the log unchanged. Discovery never restores a + * dismissed binding; `track` does. + * @param session - Session that owns the binding. + * @param url - web URL of the change request. + */ +dismiss(session: Session, url: string): void + +/** + * Watch a Session's visible change requests as an effect on the calling + * fiber. Every visible change request that a provider recognizes is polled + * through `ctx.forge` while the Session has a watcher. Listeners receive the + * complete list after each later binding or provider change, or polling result; read the + * current list with {@link changeRequests}. Listeners must not throw; a + * thrown error is logged and skipped. + * @param session - Session to watch. + * @param listener - receives the complete visible list. + * @returns the disposer that stops this watch. + */ +watch(session: Session, listener: SessionChangeRequestsListener): () => void +``` + +Types: [Session](session.md) + +Source: [`packages/experimental/forge-session/src/index.ts`](../../packages/experimental/forge-session/src/index.ts) + + + +### `forge/*` events + + + +#### `forge/providers-changed` — parallel + +Announces a provider registration or withdrawal after the registry changes. Listener failures are logged without preventing other listeners from running. + +```ts cordis-catalog +/** + * Announces a provider registration or withdrawal after the registry changes. + * Listener failures are logged without preventing other listeners from running. + * @param forge - family whose provider changed. + * @mode parallel + */ +'forge/providers-changed'(forge: string): void | Promise +``` + +Source: [`packages/experimental/forge/src/index.ts`](../../packages/experimental/forge/src/index.ts) + diff --git a/docs/subsystems/forge.zh.md b/docs/subsystems/forge.zh.md new file mode 100644 index 0000000000..5c78d7bb02 --- /dev/null +++ b/docs/subsystems/forge.zh.md @@ -0,0 +1,1181 @@ +# Forges + +[English](forge.md) | 中文 + +实验性的 forge 能力 seam 从代码托管平台读取变更请求（change request，即 pull request 与 merge request）。[`dsh-experimental-forge`](../../packages/experimental/forge/README.zh.md) 是 Service Definition，提供 `ctx.forge`；[`dsh-experimental-forge-github`](../../packages/experimental/forge-github/README.zh.md) 是服务 GitHub 主机的 Service Provider；[`dsh-experimental-forge-session`](../../packages/experimental/forge-session/README.zh.md) 是把变更请求绑定到 Session 的 Consumer，提供 `ctx.forgeSession`；[`dsh-experimental-client-ui-forge`](../../packages/experimental/client-ui-forge/README.zh.md) 是提供 `ctx.forgePanel` 的 GUI Consumer。默认禁用的 [forge Bundle](../../packages/experimental/forge-bundle/README.zh.md) 可从插件页面组合这四个包，并为面板附带一个隔离的 [worktree 服务](../../packages/experimental/worktree/README.zh.md)；除此之外，它们只能通过显式组合加载。 + +## 提供方与变更请求 + +一个提供方服务一个 forge 家族，例如 `github`。它把 Git 远端 URL 映射为仓库，把变更请求 URL 映射为引用，构造规范的变更请求 URL，按 head 分支查找打开状态的变更请求，并批量读取状态。`changeRequestKey` 从引用派生一个不区分大小写的键，因此 URL 拼写不同的监听方共享同一个轮询循环。 + +```ts type-equiv +/** One repository on a code host, identified the way its provider addresses it. */ +interface ForgeRepository { + /** Provider family that serves the repository, such as `github`. */ + readonly forge: string + /** Lowercase host name, such as `github.com`. */ + readonly host: string + /** Owner or namespace path as the host spells it. */ + readonly owner: string + /** Repository name as the host spells it. */ + readonly name: string +} +``` + +```ts type-equiv +/** One change request (pull request or merge request) in a repository. */ +interface ChangeRequestRef { + /** Repository that holds the change request. */ + readonly repository: ForgeRepository + /** Host-assigned change request number. */ + readonly number: number +} +``` + +```ts type-equiv +/** Canonical identity of a change request across providers; built by `changeRequestKey`. */ +type ChangeRequestKey = Branded<'ChangeRequestKey'> +``` + +```ts type-equiv +/** + * Host-specific access registered with `ctx.forge`. One provider serves one + * forge family; methods that take a signal must stop work when it aborts. + */ +interface ForgeProvider { + /** Forge family name stored in every repository this provider returns. */ + readonly forge: string + /** Publish a comment or completed review. Omission declares that this provider cannot write reviews. */ + submitReview?(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise + /** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */ + repositoryFromRemote(url: string): ForgeRepository | undefined + /** Map a change request web URL to its reference, or undefined when this provider does not serve it. */ + changeRequestFromUrl(url: string): ChangeRequestRef | undefined + /** Build the canonical web URL of a change request this provider serves. */ + changeRequestUrl(ref: ChangeRequestRef): string + /** Read the status of several change requests, returning one result per requested key. */ + fetch( + refs: readonly ChangeRequestRef[], + signal: AbortSignal, + ): Promise> + /** Read all checks for one change request on demand; omission declares that only the polling preview is available. */ + fetchChecks?(ref: ChangeRequestRef, signal: AbortSignal): Promise + /** Find open change requests whose head is `branch` in `repository`, excluding the default branch and forks. */ + findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise + /** Report whether the provider can reach `host` with current credentials. */ + readiness(host: string, signal: AbortSignal): Promise + /** Mark a draft change request ready for review, resolving to undefined once the host accepted it. */ + markReady(ref: ChangeRequestRef, signal: AbortSignal): Promise + /** Merge a change request while its head is still `request.headSha`, resolving to undefined once merged. */ + merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise + /** Read the changes of a change request as the host computes them, as one unified patch with `a/` and `b/` path prefixes. */ + diff(ref: ChangeRequestRef, signal: AbortSignal): Promise + /** Read the text of `path` at `commit` in the change request's repository. */ + fileText(ref: ChangeRequestRef, commit: string, path: string, signal: AbortSignal): Promise + /** Build the web page of `path` at `commit` in the change request's repository. */ + fileUrl(ref: ChangeRequestRef, commit: string, path: string): string +} +``` + +```ts type-equiv +/** Whether a provider can reach one host with the current credentials. */ +interface ForgeReadiness { + /** `ready`, `unauthenticated` (sign-in needed), or `unavailable` (tool missing or host unreachable). */ + readonly state: 'ready' | 'unauthenticated' | 'unavailable' + /** Human-readable detail, or null when ready. */ + readonly message: string | null +} +``` + +## 状态轮询 + +`ctx.forge.watch` 让同一变更请求的所有监听方共享一个轮询循环，并把每次结果作为更新送达。每个 forge 同时最多只有一次读取在进行。轮询节奏、退避与超时规则见[注册表 README](../../packages/experimental/forge/README.zh.md#use-this-package)。 + +```ts type-equiv +/** Lifecycle state of a change request. */ +type ChangeRequestState = 'open' | 'closed' | 'merged' +``` + +```ts type-equiv +/** Normalized outcome of one status check. */ +type CheckState = 'pending' | 'success' | 'failure' | 'neutral' | 'skipped' | 'cancelled' +``` + +```ts type-equiv +/** One status check reported for the head commit of a change request. */ +interface ChangeRequestCheck { + /** Check name as the host displays it. */ + readonly name: string + /** Normalized check outcome. */ + readonly state: CheckState + /** Web page for the check, or null when the host reports none. */ + readonly url: string | null + /** Workflow that produced the check, or null when the host reports none. */ + readonly workflow: string | null + /** ISO 8601 time the check started, or null before it starts and when the host reports none. */ + readonly startedAt: string | null + /** ISO 8601 time the check completed, or null while it runs and when the host reports none. */ + readonly completedAt: string | null +} +``` + +```ts type-equiv +/** Combined outcome of all checks on the head commit. */ +type ChecksRollup = 'none' | 'pending' | 'success' | 'failure' +``` + +```ts type-equiv +/** Whether the change request can merge into its base without conflicts. */ +type Mergeability = 'mergeable' | 'conflicting' | 'unknown' +``` + +```ts type-equiv +/** Aggregate review outcome required by the host's merge rules. */ +type ReviewDecision = 'approved' | 'changes-requested' | 'review-required' | 'none' +``` + +```ts type-equiv +/** Status of one change request at the time its provider read it. */ +interface ChangeRequestSnapshot { + /** Change request the snapshot describes. */ + readonly ref: ChangeRequestRef + /** Web page of the change request. */ + readonly url: string + /** Title as the author wrote it. */ + readonly title: string + /** Lifecycle state. */ + readonly state: ChangeRequestState + /** Whether the author marked the change request as a draft. */ + readonly draft: boolean + /** Author login, or null when the host hides it. */ + readonly author: string | null + /** Branch that carries the proposed commits. */ + readonly headBranch: string + /** Commit object name at the head of the change request. */ + readonly headSha: string + /** Branch the change request merges into. */ + readonly baseBranch: string + /** Lines the change request adds. */ + readonly additions: number + /** Lines the change request deletes. */ + readonly deletions: number + /** Merge conflict status; `unknown` while the host computes it. */ + readonly mergeability: Mergeability + /** + * Whether the host would merge the change request now for the signed-in + * user: open, not a draft, and meeting the base branch's merge rules. + */ + readonly mergeReady: boolean + /** Merge methods the repository accepts, the signed-in user's usual one first. */ + readonly mergeMethods: readonly MergeMethod[] + /** Aggregate review outcome. */ + readonly reviewDecision: ReviewDecision + /** Checks on the head commit in host order. */ + readonly checks: readonly ChangeRequestCheck[] + /** Combined check outcome. */ + readonly checksRollup: ChecksRollup + /** Whether the host reported more checks than `checks` contains. */ + readonly checksTruncated: boolean + /** Number of review threads that are not resolved. */ + readonly unresolvedThreads: number + /** ISO 8601 time of the host's last update to the change request. */ + readonly updatedAt: string + /** ISO 8601 time the change request was merged or closed, or null while it is open. */ + readonly closedAt: string | null +} +``` + +```ts type-equiv +/** Why a provider could not read a change request. */ +interface ForgeFailure { + /** + * `not-found`: the host does not expose it; `unauthenticated`: credentials are missing or rejected; + * `too-large`: the host or the provider refuses an answer over its size limit, so reading again fails + * the same way; `unavailable`: any other failure. + */ + readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'unavailable' + /** Human-readable cause. */ + readonly message: string +} +``` + +```ts type-equiv +/** Latest polling result delivered to watchers of one change request. */ +type ChangeRequestUpdate = { + /** Canonical identity of the watched change request. */ + readonly key: ChangeRequestKey + /** Epoch milliseconds when the result settled. */ + readonly fetchedAt: number +} & ({ + /** Status read from the host. */ + readonly snapshot: ChangeRequestSnapshot +} | { + /** Reason the status could not be read. */ + readonly failure: ForgeFailure +}) +``` + +```ts type-equiv +/** + * Receives every polling result for one watched change request. + * @param update - the settled result. + */ +type ChangeRequestListener = (update: ChangeRequestUpdate) => void +``` + +## 变更请求操作 + +`ctx.forge.markReady` 把草稿标记为可评审，`ctx.forge.merge` 只在 head 仍是用户确认的提交时合并变更请求。主机拒绝时，两者都 resolve 为 `ForgeActionFailure` 而不是抛错，并在结束后立即轮询被监听的变更请求。快照的 `mergeReady` 与 `mergeMethods` 告诉消费方何时提供合并、可用哪些合并方式；GitHub 如何给出这两项由 [GitHub 提供方 README](../../packages/experimental/forge-github/README.zh.md#use-this-package) 说明。 + +```ts type-equiv +/** A merge the user confirmed for the head commit they saw. */ +interface MergeRequest { + /** How the commits enter the base branch. */ + readonly method: MergeMethod + /** Commit object name the head must still have; the merge is refused once the head moves. */ + readonly headSha: string +} +``` + +```ts type-equiv +/** Why a provider could not change a change request. */ +interface ForgeActionFailure { + /** + * `unauthenticated`: credentials are missing or rejected; `stale`: the head + * moved past the confirmed commit; `failed`: the host refused or could not be reached. + */ + readonly code: 'unauthenticated' | 'stale' | 'failed' + /** Human-readable cause, usually the host's own message. */ + readonly message: string +} +``` + +`ctx.forge.submitReview` 将明确指定的评论或完整评审交给 provider；未实现此能力的 provider 返回不支持。消费者保存待提交草稿，并在再次提交前核对结果不明的写操作。 + +```ts type-equiv +/** One inline comment addressed to the old or new side of a pull request diff. */ +interface ForgeLineComment { + readonly path: string + readonly side: 'L' | 'R' + readonly startLine: number + readonly endLine: number + readonly body: string +} +``` + +```ts type-equiv +/** A single published comment or one completed review containing all pending comments. */ +type ForgeReviewRequest = { + /** Commit the user reviewed; providers must check it before writing and address that commit explicitly. */ + readonly headSha: string +} & ( + | { readonly kind: 'comment'; readonly comment: ForgeLineComment } + | { readonly kind: 'review'; readonly event: 'comment' | 'approve' | 'request-changes'; readonly body: string; readonly comments: readonly ForgeLineComment[] } +) +``` + +```ts type-equiv +/** Result of a review write; unknown outcomes must be checked on the host before another submission. */ +type ForgeReviewResult = + | { readonly ok: true; readonly url: string } + | { readonly ok: false; readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown'; readonly message: string } +``` + +## Session 绑定 + +`ctx.forgeSession` 从每个 Session 自己的日志派生其绑定：`gh pr create` 的结果绑定其输出的 URL，`gh pr view`、`gh pr edit` 与 `gh pr checkout` 调用绑定它们所操作的变更请求，`git push` 的结果通过 `ctx.forge` 触发按 head 分支的发现；面板也会报告其检出所跟踪的分支，触发同样的发现。track、dismiss 与发现操作都是 `plugin:forge-session/binding` 插件记录，位于模型可见对话之外。`forgeChangeRequests` 投影的客户端视图随 Session 摘要下发，列出绑定但不含其状态。识别与发现规则见 [Session 绑定 README](../../packages/experimental/forge-session/README.zh.md#use-this-package)。 + +```ts type-equiv +/** + * How a change request became bound to a Session: `created` when a + * `gh pr create` result printed its URL, `referenced` when a `gh pr view`, + * `gh pr edit`, or `gh pr checkout` call named it or its result printed its + * own URL, `discovered` when a lookup found it for a branch the Session pushed + * or works on, `tracked` when a caller bound it by URL. + */ +type BindingOrigin = 'created' | 'referenced' | 'discovered' | 'tracked' +``` + +```ts type-equiv +/** Payload of the `plugin:forge-session/binding` record. */ +interface BindingRecord { + /** + * `track` binds or restores, `dismiss` hides, `discover` binds a branch lookup, + * and `reference` binds a CLI selector lookup without restoring dismissed entries. + */ + readonly action: 'track' | 'dismiss' | 'discover' | 'reference' + /** Web URL of the change request. */ + readonly url: string +} +``` + +```ts type-equiv +/** One change request bound to a Session and not dismissed, with its latest polling result. */ +interface SessionChangeRequest { + /** Web URL as first recorded. */ + readonly url: string + /** How the change request became bound. */ + readonly origin: BindingOrigin + /** Parsed reference, or null when no registered provider serves the URL. */ + readonly ref: ChangeRequestRef | null + /** Latest polling result, or null before the first poll and without a provider. */ + readonly update: ChangeRequestUpdate | null +} +``` + +```ts type-equiv +/** + * Receives the complete visible list after a binding or provider change, or a polling result. + * @param changeRequests - every visible binding of the watched Session, in first-recorded order. + */ +type SessionChangeRequestsListener = (changeRequests: readonly SessionChangeRequest[]) => void +``` + +## 面板 + +`ctx.forgePanel` 是 [forge 面板](../../packages/experimental/client-ui-forge/README.zh.md#use-this-package)的宿主 Remote。跟随一个 Session 时，它以流的形式推送 `ForgePanelState`：在 Session 执行环境中对其当前目录进行的只读 Git 检查、从上游远端或 `origin` 识别出的代码托管平台、该平台的登录状态、Session 的绑定及其轮询状态与最近的快照，以及它的 worktree 请求。它的操作可以列出基准分支、绑定和隐藏 URL、刷新、把已绑定的草稿标记为可评审或合并已绑定的变更请求、请求或撤回 worktree、停止正在进行的创建，以及恢复已删除的 worktree 或离开它回到源检出。请求是一条 `plugin:client-ui-forge/worktree` 记录。消息在 Session 的 Agent 空闲时进入其收件箱，面板会在这次投递唤醒 [Agent](../../packages/core/agent/README.zh.md) 之前启动它的维护任务，暂留这条消息的这一轮：对未完成的请求，它通过 `ctx.worktrees` 创建 worktree，尝试失败或被停止后等待下一次尝试或请求被撤回；对在所创建 worktree 中工作的 Session，它检查该 worktree，已被删除时等待它被恢复或离开。面板状态说明消息在等待什么，以及最近一次失败的尝试。对于没有被暂留的消息，由第一个步骤提议创建 worktree。第一轮开始之后的请求会被忽略。对 Session 检出的改动以其 Agent 的维护任务运行，因此其他客户端发来的消息会等它们完成。 + +```ts type-equiv +/** Git facts for the checkout that contains the Session's current directory. */ +interface ForgeCheckout { + /** Top-level directory of the checkout. */ + readonly root: string + /** Checked-out branch, or null when HEAD is detached. */ + readonly branch: string | null + /** Whether the checkout is a linked worktree of another checkout's repository. */ + readonly linked: boolean + /** Abbreviated commit HEAD names, or null while the checked-out branch has no commit. */ + readonly commit: string | null +} +``` + +```ts type-equiv +/** Inspection result for the Session's current directory. */ +type ForgeCheckoutState = + /** The first inspection has not finished. */ + | { readonly state: 'pending' } + /** The current directory is not inside a Git checkout. */ + | { readonly state: 'none' } + /** Git could not run or reported an error. */ + | { readonly state: 'failed'; readonly message: string } + /** The checkout facts. */ + | { readonly state: 'ready'; readonly checkout: ForgeCheckout } +``` + +```ts type-equiv +/** The worktree the panel created and entered for a Session before its first step. */ +interface ForgeSessionWorktree { + /** Canonical checkout directory. */ + readonly path: string + /** Branch created for the checkout. */ + readonly branch: string + /** Requested base branch, or null when the checkout started from HEAD of the source checkout. */ + readonly from: string | null + /** Commit object name the branch started from. */ + readonly baseCommit: string + /** Canonical root of the source checkout. */ + readonly repositoryRoot: string +} +``` + +```ts type-equiv +/** Payload of the `plugin:client-ui-forge/worktree` record. */ +type WorktreeRecord = + /** Create a worktree before the Session's first step, starting from `from`, or from HEAD when it is null. */ + | { readonly action: 'request'; readonly from: string | null } + /** Withdraw the open request. */ + | { readonly action: 'cancel' } + /** The requested worktree was created and became the Session's working directory. */ + | { readonly action: 'created'; readonly worktree: ForgeSessionWorktree } + /** Restoration started; the checkout stays unavailable until restoration completes. */ + | { readonly action: 'restoring' } + /** The recorded worktree was completely restored. */ + | { readonly action: 'restored' } +``` + +```ts type-equiv +/** One open worktree request. */ +interface ForgeWorktreeRequest { + /** Base branch, or null for HEAD of the source checkout. */ + readonly from: string | null +} +``` + +```ts type-equiv +/** Why the Session's checkout cannot host a new worktree. */ +type ForgeWorktreeBlocker = + /** The current directory is not inside a Git checkout. */ + | 'not-git' + /** The Session's sandbox cannot write the checkout or its Git directory, as for a linked worktree outside the writable root. */ + | 'outside-writable-root' + /** The Session runs read-only. */ + | 'read-only' +``` + +```ts type-equiv +/** One running worktree creation. */ +interface ForgeWorktreeCreation { + /** Running step: `prepare` validates and creates the branch, then `checkout` writes the files. */ + readonly phase: 'prepare' | 'checkout' + /** Branch the attempt creates. */ + readonly branch: string + /** Base branch, or null for HEAD. */ + readonly from: string | null + /** + * Whether a message waits for the creation before its turn starts. Only + * such a creation can be stopped, after which the message keeps waiting; a + * creation at the first step serves a message the Session already holds. + */ + readonly held: boolean +} +``` + +```ts type-equiv +/** One running restoration of the removed worktree a Session works in. */ +interface ForgeWorktreeRestoration { + /** Running step: `prepare` registers the checkout again, creating a missing branch, then `checkout` writes the files. */ + readonly phase: 'prepare' | 'checkout' +} +``` + +```ts type-equiv +/** The last attempt to create the requested worktree for a message, which failed. */ +interface ForgeWorktreeFailure { + /** Branch the attempt created, or null when it failed before naming one. */ + readonly branch: string | null + /** Base branch of the attempt, or null for HEAD. */ + readonly from: string | null + /** Step that failed. */ + readonly phase: 'prepare' | 'checkout' + /** Failure text. */ + readonly message: string +} +``` + +```ts type-equiv +/** + * What a message waits for before its turn starts: the creation of the + * requested worktree, or the restoration or leaving of the removed worktree + * the Session works in. + */ +type ForgeWorktreeWaiting = 'creation' | 'restoration' +``` + +```ts type-equiv +/** The recorded worktree whose directory is missing, invalid, or incompletely restored. */ +interface ForgeMissingWorktree { + /** Whether its branch exists, or null when an incomplete restoration cannot inspect it. */ + readonly branchExists: boolean | null +} +``` + +```ts type-equiv +/** Worktree facts of one Session in the panel state. */ +interface ForgePanelWorktree { + /** + * Whether the Session can still request or withdraw a worktree: a worktree + * service is mounted, no turn has started, and none was created. + */ + readonly editable: boolean + /** Why the checkout cannot host a worktree, or null when it can, before the first inspection, and after a failed one. */ + readonly blocker: ForgeWorktreeBlocker | null + /** Open request, or null without one. */ + readonly request: ForgeWorktreeRequest | null + /** Created worktree, or null before creation. */ + readonly created: ForgeSessionWorktree | null + /** Running creation, or null. */ + readonly creation: ForgeWorktreeCreation | null + /** + * The last failed attempt of the creation a message waits for, or null. It + * clears when another attempt starts, when the request changes or is + * withdrawn, and when the wait ends. + */ + readonly failure: ForgeWorktreeFailure | null + /** The created worktree the Session works in when its directory is gone, or null. */ + readonly missing: ForgeMissingWorktree | null + /** Running restoration of the removed worktree, or null. */ + readonly restoration: ForgeWorktreeRestoration | null + /** What a message of the Session waits for before its turn starts, or null while none waits. */ + readonly waiting: ForgeWorktreeWaiting | null +} +``` + +```ts type-equiv +/** One bound change request in the panel state. */ +interface ForgePanelChangeRequest extends SessionChangeRequest { + /** Latest snapshot a poll returned, kept while later polls fail, or null before the first successful poll. */ + readonly snapshot: ChangeRequestSnapshot | null +} +``` + +```ts type-equiv +/** Everything the panel shows for one Session. */ +interface ForgePanelState { + /** Current working directory of the Session. */ + readonly directory: string + /** Inspection result for `directory`. */ + readonly checkout: ForgeCheckoutState + /** Code host repository of the checkout's upstream remote or `origin`, or null when no provider serves them. */ + readonly repository: ForgeRepository | null + /** Sign-in state for the repository's host, or null before the first probe and without a repository. */ + readonly readiness: ForgeReadiness | null + /** Visible change request bindings with their latest polling results, in first-recorded order. */ + readonly changeRequests: readonly ForgePanelChangeRequest[] + /** Worktree request and creation state. */ + readonly worktree: ForgePanelWorktree + /** + * Files the `branch` scope changes, or null before the first inspection, + * outside a checkout, and without a fork point. + */ + readonly local: ForgeLocalChanges | null +} +``` + +```ts type-equiv +/** Local branches offered as the base of a new worktree. */ +interface ForgeBranches { + /** Checked-out branch, or null when HEAD is detached. */ + readonly current: string | null + /** Local branch names, `current` first and then most recently committed first, at most `maxBranches`. */ + readonly branches: readonly string[] +} +``` + +会话列表经同一个 Remote 读取。`changeRequestStates` 以流的形式推送 `ForgeChangeRequestStatesFrame`：先是一个 `baseline`，包含调用方可读的已列出 Session 所绑定的每个变更请求最近一次已知的 `ForgeChangeRequestListState`，之后是发生变化的状态。宿主用一次运行服务所有流：已加载 Session 的绑定取自 `ctx.forgeSession`，其他 Session 的绑定取自缓存的 Session 摘要而不加载它们；每个已绑定的变更请求保持订阅，已关闭的按空闲间隔轮询以检测重新打开，每次变化都会存储，因此重启后在下次轮询之前就能显示最近已知的状态。Session 摘要还带有 `forgeWorktree` 投影的客户端视图：Session 的目录就是所创建的 worktree 或位于其下时为该 worktree，否则为 null。 + +```ts type-equiv +/** + * The last polled state of one change request that a listed Session binds, as + * the Session list shows it. + */ +type ForgeChangeRequestListState = Pick< + ChangeRequestSnapshot, 'url' | 'title' | 'state' | 'draft' | 'checksRollup' | 'reviewDecision' | 'mergeability' +> & { + /** Change request number on its code host. */ + readonly number: number +} +``` + +```ts type-equiv +/** + * One frame of `forgePanel.changeRequestStates`: the known state of every + * change request the reader may see first, then the states that changed or + * became visible since the previous frame. + */ +type ForgeChangeRequestStatesFrame = + | { readonly type: 'baseline'; readonly states: readonly ForgeChangeRequestListState[] } + | { readonly type: 'changed'; readonly states: readonly ForgeChangeRequestListState[] } +``` + +变更视图经同一个 Remote 读取。`localDiff` 读取 Session 检出的某个 `ForgeLocalScope`；`changeRequestDiff` 经提供方的 `diff` 读取已绑定变更请求在其最新状态 head 处的变更；两者返回的文件都已在宿主上解析为 `ForgeDiffFile` 的 hunk。`localText` 与 `changeRequestText` 读取一个文件的新版本，用来补出 hunk 之间未变更的行。每次检查还会把 `branch` 范围的规模统计为 `ForgePanelState.local`，供面板的变更卡片使用。 + +```ts type-equiv +/** Which local changes a diff covers; each reads the Session's checkout through Git. */ +type ForgeLocalScope = + /** + * The working tree and untracked files against the fork point: the base commit of the worktree the + * Session created, else the merge base of HEAD with the default branch of the code host remote. + */ + | { readonly kind: 'branch' } + /** The working tree and untracked files against HEAD. */ + | { readonly kind: 'uncommitted' } + /** The working tree and untracked files against the index. */ + | { readonly kind: 'unstaged' } + /** The index against HEAD. */ + | { readonly kind: 'staged' } +``` + +```ts type-equiv +/** One hunk of a file diff. */ +interface ForgeDiffHunk { + /** First old line the hunk covers, or the old line it comes before when it covers none. */ + readonly oldStart: number + /** Old lines the hunk covers. */ + readonly oldLines: number + /** First new line the hunk covers, or the new line it comes before when it covers none. */ + readonly newStart: number + /** New lines the hunk covers. */ + readonly newLines: number + /** Lines in patch form: a leading space for context, `+` for added, `-` for deleted, and `\` for a missing final newline. */ + readonly lines: readonly string[] +} +``` + +```ts type-equiv +/** How one file changed. */ +type ForgeDiffStatus = 'added' | 'deleted' | 'modified' | 'renamed' +``` + +```ts type-equiv +/** One changed file of a diff. */ +interface ForgeDiffFile { + /** Path relative to the repository root after the change, or before it for a deleted file. */ + readonly path: string + /** Path before a rename, else null. */ + readonly previousPath: string | null + /** How the file changed. */ + readonly status: ForgeDiffStatus + /** Whether the content is binary, which carries no hunks. */ + readonly binary: boolean + /** Whether an untracked file exceeds `maxDiffBytes`, so it carries no hunks. */ + readonly oversized: boolean + /** Whether Git does not track the file yet; only local diffs list such files. */ + readonly untracked: boolean + /** Lines added. */ + readonly additions: number + /** Lines deleted. */ + readonly deletions: number + /** Hunks in file order; none for a binary file or a change of mode or name only. */ + readonly hunks: readonly ForgeDiffHunk[] +} +``` + +```ts type-equiv +/** Local changes of the Session's checkout in one scope. */ +interface ForgeLocalDiff { + /** Ref or abbreviated commit the `branch` scope compares with, such as `origin/master`; null for other scopes. */ + readonly base: string | null + /** Changed files in Git's path order, untracked files last. */ + readonly files: readonly ForgeDiffFile[] + /** Untracked files left out beyond `maxUntrackedFiles`. */ + readonly omitted: number +} +``` + +```ts type-equiv +/** Changes of a change request as its code host computes them. */ +interface ForgeChangeRequestDiff { + /** Head commit the diff describes. */ + readonly headSha: string + /** Changed files in the host's order. */ + readonly files: readonly ForgeDiffFile[] + /** + * Commits the checkout's branch has beyond the head when that branch is the change request's head + * branch and the head commit is present locally; null otherwise. + */ + readonly localAhead: number | null + /** Web page of each changed file at the head commit, by path. */ + readonly fileUrls: Readonly> +} +``` + +```ts type-equiv +/** One file the `branch` scope changes, without its hunks. */ +interface ForgeChangedFile { + /** Path relative to the repository root after the change. */ + readonly path: string + /** Lines added, or 0 for a binary file. */ + readonly additions: number + /** Lines deleted, or 0 for a binary file. */ + readonly deletions: number + /** Whether the content is binary. */ + readonly binary: boolean +} +``` + +```ts type-equiv +/** Size of the `branch` scope, which the panel's local changes card shows. */ +interface ForgeLocalChanges { + /** Ref or abbreviated commit the scope compares with. */ + readonly base: string + /** Changed files in Git's path order, untracked files last, at most `maxUntrackedFiles` of those. */ + readonly files: readonly ForgeChangedFile[] +} +``` + + + + + +## 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). + + + +### `ctx.forge` — `ForgeService` + +Registry of forge providers. Watchers of one change request share a single polling loop; each forge has at most one fetch in flight, which batches every due change request of that forge. + +```ts cordis-catalog +/** + * Register the provider of one forge family as an effect on the calling + * fiber. Watches of that forge receive an `unavailable` failure when the + * registration ends. Unregistering cancels and awaits its in-flight calls; + * results from the withdrawn registration are discarded. + * @param provider - provider to serve `provider.forge`. + * @returns the disposer that unregisters the provider and waits for its calls to finish. + * @throws when another provider already serves the same forge. + */ +register(provider: ForgeProvider): () => Promise + +/** + * Map a Git remote URL to a repository through the first provider that serves it. + * @param url - fetch or push URL as Git reports it. + * @returns the repository, or undefined when no provider serves the URL. + */ +repositoryFromRemote(url: string): ForgeRepository | undefined + +/** + * Map a change request web URL through the first provider that serves it. + * @param url - web URL of a pull or merge request. + * @returns the change request, or undefined when no provider serves the URL. + */ +changeRequestFromUrl(url: string): ChangeRequestRef | undefined + +/** + * Build the canonical web URL of a change request. + * @param ref - change request served by a registered provider. + * @returns the provider's canonical URL. + * @throws when no provider serves the change request's forge. + */ +changeRequestUrl(ref: ChangeRequestRef): string + +/** + * Find open change requests whose head is `branch`, excluding the default branch and forks. + * @param repository - repository served by a registered provider. + * @param branch - head branch name on the host. + * @param signal - cancellation for the lookup. + * @returns matching change requests, newest first as the provider reports them. + * @throws when no provider serves the repository's forge or the lookup fails. + */ +async findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise + +/** + * Report whether the provider can reach the repository's host with current credentials. + * @param repository - repository served by a registered provider. + * @param signal - cancellation for the probe. + * @returns the provider's readiness for the host. + * @throws when no provider serves the repository's forge. + */ +async readiness(repository: ForgeRepository, signal: AbortSignal): Promise + +/** + * Mark a draft change request ready for review, then poll it at once when it is watched. + * @param ref - change request served by a registered provider. + * @param signal - cancellation of the request. + * @returns undefined once the host accepted the change, or why it did not. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async markReady(ref: ChangeRequestRef, signal: AbortSignal): Promise + +/** + * Merge a change request while its head is still `request.headSha`, then + * poll it at once when it is watched. + * @param ref - change request served by a registered provider. + * @param request - merge method and the head commit the user confirmed. + * @param signal - cancellation of the request. + * @returns undefined once the host merged it, or why it did not. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise + +/** + * Read complete check details independently of periodic polling. + * @param ref - change request served by a registered provider. + * @param signal - cancellation of the detail view. + * @returns a complete snapshot or the provider's failure; unsupported providers return unavailable. + * @throws on cancellation, provider disposal, or expiry of this read's own `fetchTimeoutMs` deadline. + */ +async fetchChecks(ref: ChangeRequestRef, signal: AbortSignal): Promise + +/** + * Read the changes of a change request as its host computes them. + * @param ref - change request served by a registered provider. + * @param signal - cancellation of the read. + * @returns one unified patch with `a/` and `b/` path prefixes, or why the host did not provide it. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async diff(ref: ChangeRequestRef, signal: AbortSignal): Promise + +/** + * Publish one comment or a completed review, then refresh the watched status. + * @param ref - change request served by a registered provider. + * @param request - explicitly selected commit, comments, and review decision. + * @param signal - request cancellation. + * @returns a publication URL or a failure, including an unknown write outcome. + */ +async submitReview(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise + +/** + * Read the text of one file at a commit of a change request's repository. + * @param ref - change request served by a registered provider. + * @param commit - commit object name. + * @param path - path relative to the repository root. + * @param signal - cancellation of the read. + * @returns the text, or why the host did not provide it. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async fileText(ref: ChangeRequestRef, commit: string, path: string, signal: AbortSignal): Promise + +/** + * Build the web page of one file at a commit of a change request's repository. + * @param ref - change request served by a registered provider. + * @param commit - commit object name. + * @param path - path relative to the repository root. + * @returns the provider's URL. + * @throws when no provider serves the change request's forge. + */ +fileUrl(ref: ChangeRequestRef, commit: string, path: string): string + +/** + * Watch one change request as an effect on the calling fiber. The first + * watcher starts polling at once; listeners receive every later result, + * and `latest` returns the current one. Polling stops when the last watcher + * leaves. Listeners must not throw; a thrown error is logged and skipped. + * @param ref - change request to poll. + * @param listener - receives each polling result. + * @returns the disposer that stops this watch. + */ +watch(ref: ChangeRequestRef, listener: ChangeRequestListener): () => void + +/** + * Poll a watched change request at once, including after a terminal state. + * A fetch already in flight is followed immediately by another fetch; an + * unwatched change request is unchanged. + * @param ref - change request to poll. + */ +refresh(ref: ChangeRequestRef): void + +/** + * Read the latest polling result of a watched change request. + * @param ref - change request to read. + * @returns the latest result, or undefined before the first result or without a watch. + */ +latest(ref: ChangeRequestRef): ChangeRequestUpdate | undefined +``` + +Source: [`packages/experimental/forge/src/index.ts`](../../packages/experimental/forge/src/index.ts) + + + +### `ctx.forgePanel` — `ForgePanelController` + +Serves the forge panel. Following a Session inspects the checkout of its current directory using the Session's permissions and execution world, recognizes the code host of the upstream remote or `origin`, probes sign-in for that host, and polls the Session's bound change requests through `ctx.forge` until the last follower of that Session leaves. A worktree request makes the panel create a branch and checkout through an optional `ctx.worktrees` and enter it while the Session's first message waits in the inbox, or at the first step proposal of a message no wait took. After a failed or stopped attempt the message keeps waiting for another attempt or for the request to be withdrawn. A message also waits while the worktree the Session works in is gone, until that worktree is checked out again or left for the source checkout. Changes to a Session's checkout run as Agent maintenance, so a message that arrives meanwhile waits for them. + +```ts cordis-catalog +/** + * Stream the panel state of a Session: the current state first, then each + * later state. Intermediate states may be skipped when the reader is slower + * than the updates. The stream ends when `signal` aborts or the Remote stops. + * @param session - Session to follow. + * @param signal - ends the stream. + * @returns panel states in publication order. + */ +@Remote({ mode: 'stream' }) async *follow(session: Session, signal: AbortSignal): AsyncIterable + +/** + * Stream the last known state of every change request that a listed + * Session the caller may read binds: the stored states first, then each + * state a poll changes or a new binding reveals. Listing reads no Session + * log: loaded Sessions report their bindings, others the cached Session + * summary, and a Session without one shows nothing until it is opened. + * Closed requests are polled at the idle cadence so reopening is observed. The + * stream ends when `signal` aborts or the Remote stops. + * @param signal - ends the stream. + * @returns frames in publication order. + * @throws when the Host lacks the Session query, projection cache, storage, or Session store service. + */ +@Remote({ mode: 'stream' }) async *changeRequestStates(signal: AbortSignal): AsyncIterable + +/** + * List the local branches that can start a worktree of the Session's current checkout. + * @param session - Session whose current directory is listed. + * @param signal - request cancellation. + * @returns the checked-out branch and at most `maxBranches` local branches, the checked-out one first. + * @throws when the current directory is not inside a checkout or Git fails. + */ +@Remote async branches(session: Session, signal: AbortSignal): Promise + +/** + * Bind a change request to a Session by URL, or restore a dismissed binding. + * @param session - Session that receives the binding. + * @param url - web URL of the change request. + * @param signal - request cancellation. + * @throws `forgePanel/unrecognized-url` when no registered provider serves the URL. + */ +@Remote async track(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Hide a visible binding of a Session; other URLs leave the Session unchanged. + * @param session - Session that owns the binding. + * @param url - web URL of the change request. + * @param signal - request cancellation. + */ +@Remote async dismiss(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Reinspect a followed Session's checkout, probe sign-in again, and poll its + * change requests at once; an unfollowed Session is unchanged. + * @param session - Session whose panel refreshes. + * @param signal - request cancellation. + * @returns settles once the inspection and the sign-in probe have ended; poll results reach the panel stream later. + */ +@Remote async refresh(session: Session, signal: AbortSignal): Promise + +/** + * Read the changes one scope covers in the checkout of the Session's + * current directory, with Git using the Session's sandbox policy. + * @param session - Session whose checkout is read. + * @param scope - which changes to read. + * @param signal - request cancellation. + * @returns the files, the base of the `branch` scope, and the untracked files left out. + * @throws `forgePanel/not-a-checkout` outside a checkout; `forgePanel/no-fork-point` for the `branch` + * scope of a checkout without one; `forgePanel/filter-config-failed` when filter configuration cannot be read + * completely, before any comparison; `forgePanel/diff-too-large` over `maxDiffBytes`; the Git error when Git fails. + */ +@Remote async localDiff(session: Session, scope: ForgeLocalScope, signal: AbortSignal): Promise + +/** + * Read the new side of one changed file in a scope, which supplies the + * unchanged lines between its hunks: the index for `staged`, else the working tree. + * @param session - Session whose checkout is read. + * @param scope - the scope the diff was read in. + * @param path - path relative to the checkout's top-level directory, as the diff names it. + * @param signal - request cancellation. + * @returns the text. + * @throws `forgePanel/not-a-checkout` outside a checkout; `forgePanel/diff-too-large` over `maxDiffBytes`; + * an error for a path outside the checkout, binary content, or a failed read. + */ +@Remote async localText(session: Session, scope: ForgeLocalScope, path: string, signal: AbortSignal): Promise + +/** + * Load complete checks for the change request whose list the user opened. + * @param session - Session retaining the visible binding. + * @param url - binding URL. + * @param headSha - commit displayed by the card; a different head rejects the result. + * @param signal - cancellation when the list closes. + * @returns the complete snapshot at the displayed head. + * @throws `forgePanel/not-bound` for an invisible binding, `forgePanel/stale-head` for a moved head, + * or `forgePanel/checks-failed` when the provider cannot complete the read. + */ +@Remote async changeRequestChecks(session: Session, url: string, headSha: string, signal: AbortSignal): Promise + +/** + * Read the changes of a change request of a Session as its code host + * computes them, at the head commit of its latest status. A patch already + * read at the same head commit and base branch is reused from memory, for + * any Session, until `maxCachedDiffBytes` evicts it. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param signal - request cancellation. + * @returns the files, the head commit, each file's web page, and the commits the checkout has beyond the head. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/diff-too-large` when the host or its provider refuses the diff over a size limit; + * `forgePanel/diff-failed` before its status was read and when the host does not provide the diff otherwise. + */ +@Remote async changeRequestDiff(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Read one file of a change request's repository at a commit, which + * supplies the unchanged lines between the hunks of its diff. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param commit - commit object name, the head commit of the diff. + * @param path - path relative to the repository root. + * @param signal - request cancellation. + * @returns the text. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/diff-too-large` when the host or its provider refuses the file over a size limit; + * `forgePanel/diff-failed` when the host does not provide the file otherwise. + */ +@Remote async changeRequestText(session: Session, url: string, commit: string, path: string, signal: AbortSignal): Promise + +/** + * Publish a line comment or completed review for a visible Session binding. + * @param session - Session retaining the change request. + * @param url - visible binding URL. + * @param request - reviewed head, ranges, plain text, and explicit review decision. + * @param signal - request cancellation. + * @returns confirmed publication or a typed failure; unknown outcomes require reconciliation on the host. + */ +@Remote async submitReview(session: Session, url: string, request: ForgeReviewRequest, signal: AbortSignal): Promise + +/** + * Mark a draft change request of a Session ready for review; the change + * request is polled again once the host answers. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param signal - request cancellation. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/action-failed` with the host's reason when the host refuses or cannot be reached. + */ +@Remote async markReady(session: Session, url: string, signal: AbortSignal): Promise + +/** + * Merge a change request of a Session while its head is still `headSha`; + * the change request is polled again once the host answers. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param method - how the commits enter the base branch. + * @param headSha - head commit the user confirmed. + * @param signal - request cancellation. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/stale-head` when the head moved past `headSha`; `forgePanel/action-failed` with the host's + * reason when the host refuses otherwise or cannot be reached. + */ +@Remote async merge(session: Session, url: string, method: MergeMethod, headSha: string, signal: AbortSignal): Promise + +/** + * Ask for a new worktree before the Session's first turn, replacing an open + * request and forgetting a failed attempt. While the next message waits in + * the inbox, or else at the first step proposal, the panel creates a branch + * from `from`, or from HEAD of the current checkout when it is null, and + * enters its checkout. A message that already waits after a failed or + * stopped attempt keeps waiting for {@link ForgePanelController.retryWorktree}. + * @param session - Session without a started turn. + * @param from - local base branch, or null for HEAD. + * @param signal - request cancellation. + * @throws `forgePanel/invalid-branch` when `from` is empty; `forgePanel/worktrees-unavailable` + * without a worktree service; `forgePanel/session-started` after a turn started or the worktree was + * created; `forgePanel/session-busy` while the worktree is being created. + */ +@Remote async requestWorktree(session: Session, from: string | null, signal: AbortSignal): Promise + +/** + * Withdraw the open worktree request of a Session with its failed attempt, + * which lets a waiting message go on in the current checkout; without a + * request the Session is unchanged. Withdrawing needs no worktree service. + * @param session - Session without a started turn. + * @param signal - request cancellation. + * @throws `forgePanel/session-started` after a turn started or the worktree was created; + * `forgePanel/session-busy` while the worktree is being created. + */ +@Remote async cancelWorktree(session: Session, signal: AbortSignal): Promise + +/** + * Stop the creation a message of the Session waits for; the message keeps + * waiting with the request still open. Without such a creation the Session + * is unchanged. + * @param session - Session whose creation stops. + * @param signal - request cancellation. + */ +@Remote async stopCreation(session: Session, signal: AbortSignal): Promise + +/** + * Make another attempt, with a new branch name, at the worktree a message + * of the Session waits for after a failed or stopped attempt. + * @param session - Session whose message waits. + * @param signal - request cancellation. + * @throws `forgePanel/not-waiting` when no message waits or an attempt is running. + */ +@Remote async retryWorktree(session: Session, signal: AbortSignal): Promise + +/** + * Check out the created worktree of a Session again at its recorded + * directory when that directory is gone: its branch when the branch still + * exists, otherwise a new branch of the same name at the base commit. Changes + * that were never committed are not recovered. Runs as Agent maintenance, + * inside the wait of a message that waits for the restoration, which then + * goes on; without a missing directory the Session is unchanged. + * @param session - Session whose worktree directory is gone. + * @param signal - request cancellation, which aborts the restoration. + * @throws `forgePanel/no-worktree` without a created worktree; `forgePanel/worktrees-unavailable` + * without a worktree service; `forgePanel/session-busy` while the Session's Agent is not loaded or + * has other work; `forgePanel/restore-failed` when Git fails. + */ +@Remote async restoreWorktree(session: Session, signal: AbortSignal): Promise + +/** + * Move a Session from its created worktree to the source checkout the + * worktree came from; the Session no longer works in the worktree. Runs as + * Agent maintenance, inside the wait of a message that waits for the removed + * worktree, which then goes on. + * @param session - Session with a created worktree. + * @param signal - request cancellation. + * @throws `forgePanel/no-worktree` without a created worktree; `forgePanel/session-busy` while the + * Session's Agent is not loaded or has other work; the working-directory service's error when the + * source checkout no longer exists. + */ +@Remote async continueInProject(session: Session, signal: AbortSignal): Promise +``` + +Types: [Session](session.zh.md) + +Source: [`packages/experimental/client-ui-forge/src/index.ts`](../../packages/experimental/client-ui-forge/src/index.ts) + + + +### `ctx.forgeSession` — `ForgeSessionService` + +Session-scoped change request bindings. The `forgeChangeRequests` projection derives them from `gh pr create`, `gh pr view`, `gh pr edit`, `gh pr checkout`, and `git push` results and from `plugin:forge-session/binding` records. After each push result, and when a caller reports the branch a Session works on, the service looks up open change requests whose head is that branch and records the unbound ones as discovered. Watching a Session polls its visible change requests through `ctx.forge`. + +```ts cordis-catalog +/** + * List the change requests bound to a Session and not dismissed. + * @param session - Session whose bindings are read. + * @returns visible bindings in first-recorded order, each with its latest polling result. + */ +changeRequests(session: Session): SessionChangeRequest[] + +/** + * Bind a change request to a Session by URL, or restore a dismissed binding. + * Appends a `track` record with the provider's canonical URL unless the + * change request is already visible. + * @param session - Session that receives the binding. + * @param url - web URL of the change request. + * @throws when no registered provider recognizes the URL. + */ +track(session: Session, url: string): void + +/** + * Look up open change requests whose head is a branch the Session works on, + * and record the unbound ones as discovered, as after a push of that branch. + * A remote that no provider recognizes changes nothing; a failed lookup is + * logged and changes nothing. + * @param session - Session that receives the bindings. + * @param remote - URL of the remote that holds the branch. + * @param branch - branch name on that remote. + * @returns resolves once the lookup has recorded its bindings or failed. + */ +discoverBranch(session: Session, remote: string, branch: string): Promise + +/** + * Hide a visible binding. Appends a `dismiss` record; a URL that is not + * visibly bound leaves the log unchanged. Discovery never restores a + * dismissed binding; `track` does. + * @param session - Session that owns the binding. + * @param url - web URL of the change request. + */ +dismiss(session: Session, url: string): void + +/** + * Watch a Session's visible change requests as an effect on the calling + * fiber. Every visible change request that a provider recognizes is polled + * through `ctx.forge` while the Session has a watcher. Listeners receive the + * complete list after each later binding or provider change, or polling result; read the + * current list with {@link changeRequests}. Listeners must not throw; a + * thrown error is logged and skipped. + * @param session - Session to watch. + * @param listener - receives the complete visible list. + * @returns the disposer that stops this watch. + */ +watch(session: Session, listener: SessionChangeRequestsListener): () => void +``` + +Types: [Session](session.zh.md) + +Source: [`packages/experimental/forge-session/src/index.ts`](../../packages/experimental/forge-session/src/index.ts) + + + +### `forge/*` events + + + +#### `forge/providers-changed` — parallel + +Announces a provider registration or withdrawal after the registry changes. Listener failures are logged without preventing other listeners from running. + +```ts cordis-catalog +/** + * Announces a provider registration or withdrawal after the registry changes. + * Listener failures are logged without preventing other listeners from running. + * @param forge - family whose provider changed. + * @mode parallel + */ +'forge/providers-changed'(forge: string): void | Promise +``` + +Source: [`packages/experimental/forge/src/index.ts`](../../packages/experimental/forge/src/index.ts) + diff --git a/docs/subsystems/liveshare.i18n.yaml b/docs/subsystems/liveshare.i18n.yaml new file mode 100644 index 0000000000..e1ba0426b4 --- /dev/null +++ b/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: 196b06ffccedbdef + zh: 0ca8df19400afc40 +/liveshare/enabling-and-visibility: + en: f6144f8e81359a9c + zh: 1924869ac7475b59 +/liveshare/share-modes: + en: 985cb7a5c20c1cbd + zh: a5f5372dddfefaa3 +/liveshare/forks-and-their-ceiling: + en: 357a2147f48f5bac + zh: a8a297603f984ede +/liveshare/retries-recovery-and-revocation: + en: 6b1346e73ab6eab9 + zh: 888cfc08c6bc8522 +/liveshare/constraining-a-shared-session: + en: 289e8955320935f6 + zh: 7038c4283a4f33c6 +/liveshare/viewer-states: + en: b5b4d4d83dbb58c2 + zh: 498f26938dc872df diff --git a/docs/subsystems/liveshare.md b/docs/subsystems/liveshare.md new file mode 100644 index 0000000000..78c59825ee --- /dev/null +++ b/docs/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) + + + +## 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 it never writes a file; 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. `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` — 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 name the surface does not list are 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. + + + +## 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. + + + + + +## 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). + + + +### `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 + +/** + * Refresh titles and Liveshare server authority, then list this host's shares. + * @returns Every share this host publishes. + */ +@Remote('list') list(): Promise + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * Check that the effective Liveshare server answers at all. + * @returns The anonymous connectivity result. + */ +@Remote('testRelay') testRelay(): Promise + +/** + * 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 +``` + +Source: [`packages/experimental/liveshare/src/host/share-remote.ts`](../../packages/experimental/liveshare/src/host/share-remote.ts) + diff --git a/docs/subsystems/liveshare.zh.md b/docs/subsystems/liveshare.zh.md new file mode 100644 index 0000000000..e794ce64cf --- /dev/null +++ b/docs/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) + + + +## 启用与可见性 + +本包随 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`，而宿主机无法确定模式的分享仍可读取，但绝不会被驱动。 + +## fork 与其上限 + +fork 创建查看者拥有的新会话，源会话保持不变。Fork 授权检查分享、其 fork 开关、有效期、查看者准入、源身份与请求的边界。`READ_ONLY_FORK_CEILING` 允许读取与检索面——`read`、`read_image`、`glob`、`grep`、`present`、`todo_write`、`skill`、`web_search`、`web_fetch`——，`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 服务端授权；缺少授权时在模型请求之前拒绝步骤。 + + + +## 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。缺少完整授权时拒绝准入；这不构成立即的分布式停止语义保证。 + + + + + +## 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). + + + +### `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 + +/** + * Refresh titles and Liveshare server authority, then list this host's shares. + * @returns Every share this host publishes. + */ +@Remote('list') list(): Promise + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * 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 + +/** + * Check that the effective Liveshare server answers at all. + * @returns The anonymous connectivity result. + */ +@Remote('testRelay') testRelay(): Promise + +/** + * 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 +``` + +Source: [`packages/experimental/liveshare/src/host/share-remote.ts`](../../packages/experimental/liveshare/src/host/share-remote.ts) + diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml index 368a82dc27..59d8d46494 100644 --- a/docs/subsystems/llm-streaming.i18n.yaml +++ b/docs/subsystems/llm-streaming.i18n.yaml @@ -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: 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 diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md index 23b7c6c2bd..565da04ff2 100644 --- a/docs/subsystems/llm-streaming.md +++ b/docs/subsystems/llm-streaming.md @@ -525,6 +525,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 +558,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 +642,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 +``` + +```ts type-equiv +/** + * A single model request, fully assembled. + * @typeParam Purpose - declared purpose keys for callers; forwarding adapters may accept `string`. + */ +interface GenerateOptions { /** Registered provider route selecting the adapter instance. */ provider: string model: string @@ -659,7 +697,7 @@ interface GenerateOptions { * map the purpose to model-hidden transport metadata. Ordinary conversation * requests leave it unset. */ - purpose?: 'compaction' | 'session-title' + purpose?: Purpose } ``` @@ -822,6 +860,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 +1212,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) + + +#### `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) + #### `llm/stream` — waterfall @@ -1193,4 +1252,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) + + + +### `llm-pi-ai/*` events + + + +#### `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) diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md index 98783a10e1..2f360b8f8f 100644 --- a/docs/subsystems/llm-streaming.zh.md +++ b/docs/subsystems/llm-streaming.zh.md @@ -531,6 +531,26 @@ interface LlmNativeAuth { } ``` +目录条目可以携带提供方编写的 `badge`，供选择器显示在模型名称旁。它只是展示数据：`resolveModelInfo` 不返回它，模型请求也不携带它。 + +```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 { @@ -544,6 +564,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 } ``` @@ -623,8 +648,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 +``` + +```ts type-equiv +/** + * A single model request, fully assembled. + * @typeParam Purpose - declared purpose keys for callers; forwarding adapters may accept `string`. + */ +interface GenerateOptions { /** Registered provider route selecting the adapter instance. */ provider: string model: string @@ -665,7 +703,7 @@ interface GenerateOptions { * map the purpose to model-hidden transport metadata. Ordinary conversation * requests leave it unset. */ - purpose?: 'compaction' | 'session-title' + purpose?: Purpose } ``` @@ -828,6 +866,10 @@ interface LlmCallConfigAdapterDefaults { [协议参考](../deepseek-llm-api-wire-extensions.zh.md)定义确切的请求标头、扩展事务、字段版本和接收方义务。随附组合会将 [`dsh_session_log`](../../packages/session/session-log-deepseek/README.zh.md) 注册为无损增量权威日志后缀，并将 [`dsh_plugin_packages`](../../packages/llm/plugin-package-inventory-deepseek/README.zh.md) 注册为完整存活 Loader 包集合。这些字段仍位于模型消息之外，也不会进入 pi-ai 适配器路径。 +## Pi-ai 请求头 + +`PiAiRequestHeaderContext` 包含已准备调用的 provider、model、解析后的模型 `baseURL`，以及可选 Session id 和辅助用途。它不可变且不含消息或认证字段，与本次请求独有的 `Headers` 一起传入同步的 `llm-pi-ai/request-headers` waterfall。[适配器的请求头文档](../../packages/llm/llm-pi-ai/README.zh.md#request-headers)定义贡献的所有权、应用标识的优先级与失败行为。此扩展点仅适用于 pi-ai 推理请求。 + ## 服务与提供方约定 `LlmAdapter` 是提供方约定：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmRuntime.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和可选的部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmRuntime.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall 的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。`ctx.llm.stream()` 与 `llm/stream` waterfall 在一个轮次中的位置见 [architecture.md](../architecture.zh.md#turn-flow)。 @@ -1176,6 +1218,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) + + +#### `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) + #### `llm/stream` — waterfall @@ -1199,4 +1258,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) + + + +### `llm-pi-ai/*` events + + + +#### `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) diff --git a/docs/subsystems/ptc-runtime.i18n.yaml b/docs/subsystems/ptc-runtime.i18n.yaml index 7c6f634157..b9a617739e 100644 --- a/docs/subsystems/ptc-runtime.i18n.yaml +++ b/docs/subsystems/ptc-runtime.i18n.yaml @@ -6,8 +6,8 @@ en: 337a6580d7571274 zh: f4ae98899120d122 /ptc-runtime/the-run-request-in-result-out: - en: 0305ed1d4f8bc618 - zh: fcfeb156574b5779 + en: 6dfa7da8b13a4f17 + zh: 09a3c8c4922239ef /ptc-runtime/bindings-host-functions-as-program-globals: en: 182147ddf388c600 zh: c0a7d77602c78bcd diff --git a/docs/subsystems/ptc-runtime.md b/docs/subsystems/ptc-runtime.md index d9ad8138a0..b1820bc264 100644 --- a/docs/subsystems/ptc-runtime.md +++ b/docs/subsystems/ptc-runtime.md @@ -19,9 +19,11 @@ interface PtcRunRequest { /** * The program source, in the runtime's {@link ../index.ts | language}. It * follows the provider's programFormat: an async function body supports - * top-level `await` and `return`; a REPL supports top-level declarations, - * `await`, and a final expression. The completion value becomes - * {@link PtcRunResult.value}. + * top-level `await` and `return`; REPL and Script programs support top-level + * declarations, `await`, and a final expression, but not top-level `return`. + * The Script provider lowers top-level await; its executionInstructions and + * documentation define retained-binding semantics. The completion value + * becomes {@link PtcRunResult.value}. */ program: string /** @@ -84,7 +86,7 @@ interface PtcRunResult { /** Applied file policy and observed denial, when the provider enforces file policy. */ sandbox?: PtcRunSandbox /** - * The program's completion value (a return or final REPL expression), when it ran to + * The program's completion value (a return or final REPL/Script expression), when it ran to * completion and the value crossed the runtime's lossless-JSON boundary. * Invalid or over-limit completions fail the run instead of substituting a * rendered string; a failed or value-less run leaves this absent. @@ -101,7 +103,12 @@ interface PtcRunResult { } ``` -`programFormat` distinguishes async function bodies from REPL statements. `stateOwner` is an in-process object identity for optional retained memory; distinct objects remain isolated. Consumers await `release(owner)` when that owner ends; cleanup failures reject that call. Omitted owners are one-shot, and stateless providers ignore ownership. The [persistent Node provider](../../packages/ptc-runtime/ptc-runtime-node/README.md#persistent-repl) defines reset and recovery behavior; no retained object enters the durable Session format. +```ts type-equiv +/** Source evaluation form, independent of retained program state. */ +type PtcProgramFormat = 'function-body' | 'repl' | 'script' +``` + +`programFormat` distinguishes async function bodies, REPL statements, and scripts. REPL and Script programs accept top-level `await`, declarations, and a final expression; top-level `return` is not supported. The Node Script provider lowers top-level await and awaits the completion value; its [declaration limitations](../../packages/ptc-runtime/ptc-runtime-node/README.md#known-limitations-and-deferred-work) apply to transformed programs. `retainsState` reports memory retention independently of source syntax. `stateOwner` is an in-process object identity for optional retained memory; distinct objects remain isolated. Consumers await `release(owner)` when that owner ends; cleanup failures reject that call. Omitted owners are one-shot, and stateless providers ignore ownership. The [persistent Node provider](../../packages/ptc-runtime/ptc-runtime-node/README.md#persistent-repl) defines reset and recovery behavior; no retained object enters the durable Session format. ## Bindings: host functions as program globals diff --git a/docs/subsystems/ptc-runtime.zh.md b/docs/subsystems/ptc-runtime.zh.md index ba747b5369..9aee80d258 100644 --- a/docs/subsystems/ptc-runtime.zh.md +++ b/docs/subsystems/ptc-runtime.zh.md @@ -19,9 +19,11 @@ interface PtcRunRequest { /** * The program source, in the runtime's {@link ../index.ts | language}. It * follows the provider's programFormat: an async function body supports - * top-level `await` and `return`; a REPL supports top-level declarations, - * `await`, and a final expression. The completion value becomes - * {@link PtcRunResult.value}. + * top-level `await` and `return`; REPL and Script programs support top-level + * declarations, `await`, and a final expression, but not top-level `return`. + * The Script provider lowers top-level await; its executionInstructions and + * documentation define retained-binding semantics. The completion value + * becomes {@link PtcRunResult.value}. */ program: string /** @@ -84,7 +86,7 @@ interface PtcRunResult { /** Applied file policy and observed denial, when the provider enforces file policy. */ sandbox?: PtcRunSandbox /** - * The program's completion value (a return or final REPL expression), when it ran to + * The program's completion value (a return or final REPL/Script expression), when it ran to * completion and the value crossed the runtime's lossless-JSON boundary. * Invalid or over-limit completions fail the run instead of substituting a * rendered string; a failed or value-less run leaves this absent. @@ -101,7 +103,12 @@ interface PtcRunResult { } ``` -`programFormat` 区分异步函数体与 REPL 语句。`stateOwner` 是标识可选保留内存的进程内对象身份；不同对象相互隔离。消费者在所有者结束时等待 `release(owner)`；清理失败时该调用拒绝。省略所有者时仅执行一次，无状态提供方忽略所有权。[持久 Node 提供方](../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)定义重置和恢复行为；保留对象不会进入持久 Session 格式。 +```ts type-equiv +/** Source evaluation form, independent of retained program state. */ +type PtcProgramFormat = 'function-body' | 'repl' | 'script' +``` + +`programFormat` 区分异步函数体、REPL 语句与脚本。REPL 与 Script 程序接受顶层 `await`、声明和末尾表达式，不支持顶层 `return`。Node Script 提供方转换顶层 await 并等待完成值；其[声明限制](../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#known-limitations-and-deferred-work)适用于转换后的程序。`retainsState` 独立于源码语法报告是否保留内存。`stateOwner` 是标识可选保留内存的进程内对象身份；不同对象相互隔离。消费者在所有者结束时等待 `release(owner)`；清理失败时该调用拒绝。省略所有者时仅执行一次，无状态提供方忽略所有权。[持久 Node 提供方](../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)定义重置和恢复行为；保留对象不会进入持久 Session 格式。 ## 绑定：宿主函数作为程序全局变量 diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml index 29991cd13f..b38666ddb4 100644 --- a/docs/subsystems/session-projection.i18n.yaml +++ b/docs/subsystems/session-projection.i18n.yaml @@ -3,8 +3,8 @@ # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/session-projection.md /session-projections: - en: 45e5f8cb8ca18d6b - zh: 4ecfad40ec9e221c + en: b2789f5257a935c5 + zh: 12d430a9cd454592 /session-projections/the-unit: en: d48814d3ab0e997f zh: d0337d8eba097a63 diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md index e56896f455..cee8103ef0 100644 --- a/docs/subsystems/session-projection.md +++ b/docs/subsystems/session-projection.md @@ -18,6 +18,13 @@ interface ProjectionHandle { * @returns the projection state at the Session's current cursor. */ stateOf(session: Session): S + /** + * Create a reader for one exact Session without reading state or preparing it. + * The reader retains this unit after unregistration and owns no disposal. + * @param session - Session whose committed events the bound reader folds. + * @returns a synchronous callback with the same state and failures as `stateOf(session)`. + */ + readerFor(session: Session): () => S /** * Unregister from global drives and snapshots without invalidating this reader. * @returns a promise that resolves when this registration is released. @@ -28,6 +35,8 @@ interface ProjectionHandle { The [compatibility rules](../../packages/session/session-projection/README.md#deprecated-plugin-compatibility) define legacy disposal, keyed reads, and their once-per-key deprecation warnings. +`ProjectionHandle.readerFor(session)` returns a `() => S` callback for one exact Session. Calling it reads the original unit and preserves borrowed state, readiness requirements and synchronous failures. Owners can compose several readers in a typed object; domain services keep them private. See [binding several states](../../packages/session/session-projection/README.md#bind-several-states-to-one-session). + ## The unit `ProjectionDefinition` carries each unit's host state type locally; registration infers `S` from `stateSchema` and returns `ProjectionHandle`. Only client-visible keys merge into `SessionProjectionMap`, which types their whole values. A `wire` block makes a unit client-visible, and rendering belongs to the slot system, never this layer: diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md index da53b76a7e..6e076a18a3 100644 --- a/docs/subsystems/session-projection.zh.md +++ b/docs/subsystems/session-projection.zh.md @@ -18,6 +18,13 @@ interface ProjectionHandle { * @returns the projection state at the Session's current cursor. */ stateOf(session: Session): S + /** + * Create a reader for one exact Session without reading state or preparing it. + * The reader retains this unit after unregistration and owns no disposal. + * @param session - Session whose committed events the bound reader folds. + * @returns a synchronous callback with the same state and failures as `stateOf(session)`. + */ + readerFor(session: Session): () => S /** * Unregister from global drives and snapshots without invalidating this reader. * @returns a promise that resolves when this registration is released. @@ -28,6 +35,8 @@ interface ProjectionHandle { [兼容规则](../../packages/session/session-projection/README.zh.md#deprecated-plugin-compatibility)规定旧释放操作、按键读取及其每个键一次的弃用警告。 +`ProjectionHandle.readerFor(session)` 为一个确切的 Session 返回 `() => S` 回调。调用它会读取原有单元，保留借用状态、就绪要求和同步失败。所有者可将多个读取函数组合成一个类型化对象；领域服务将它们保留在内部。参见[绑定多个状态](../../packages/session/session-projection/README.zh.md#bind-several-states-to-one-session)。 + ## 投影单元 `ProjectionDefinition` 在各单元内部携带宿主状态类型；注册从 `stateSchema` 推导 `S`，并返回 `ProjectionHandle`。只有客户端可见的 key 合并到 `SessionProjectionMap`，由它约束对应的全量值。`wire` 块使单元对客户端可见，渲染归 slot 体系管，永远不归本层： diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml index 53d89173b4..b4cd4bba34 100644 --- a/docs/subsystems/session.i18n.yaml +++ b/docs/subsystems/session.i18n.yaml @@ -68,3 +68,6 @@ /sessions/remote-catalog-and-workspace-opening: en: dd27307e0d7c893c zh: b77d2a749b7b641c +/sessions/session-log-upload-exclusions: + en: cfe3323aade972be + zh: 8423b490c47c5013 diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md index 4e1ef23338..fb3e56ee87 100644 --- a/docs/subsystems/session.md +++ b/docs/subsystems/session.md @@ -817,6 +817,29 @@ The backends that consume this contract are on [persistence.md](persistence.md). The optional `application` selects a registered file handler without changing the system default; `workspacePathApplications({ path })` returns current handlers, names, icons, and default selection after Host path verification. +## Session-log upload exclusions + +`ctx.sessionLogDeepSeek.registerExclusion()` registers a caller-owned predicate over `SessionLogUploadRequest`. Any match omits the log contribution and its acceptance callback before reading Session events. No match preserves normal upload eligibility. The [package README](../../packages/session/session-log-deepseek/README.md#upload-exclusions) defines failure and disposal behavior. + +```ts type-equiv +/** Request identity inspected before preparing a Session-log contribution. */ +interface SessionLogUploadRequest { + /** Live Session whose canonical log would be contributed. */ + readonly sessionId: SessionId + /** Auxiliary request classification; absent for ordinary conversation requests. */ + readonly purpose?: string +} +``` + +```ts type-equiv +/** + * Synchronous, side-effect-free upload exclusion owned by its registering plugin. + * @param request - request identity; the predicate must not mutate it. + * @returns `true` to omit the log field and acceptance callback, or `false` to keep checking eligibility. + */ +type SessionLogUploadExclusion = (request: SessionLogUploadRequest) => boolean +``` + @@ -938,8 +961,8 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | @Remote('prompt') async prompt(request: SessionPromptRequest, signal: AbortSignal): Promise /** - * Read one image proven reachable from the addressed Session log. - * @param request - Session and attachment identities used for authorization. + * Read one image from the attachment store after gateway authorization. + * @param request - image reference and gateway permission scope; Session existence is not checked. * @returns the durable attachment reference and base64-encoded bytes. */ @Remote('attachment') attachment(request: SessionAttachmentRequest): Promise @@ -960,11 +983,51 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | /** * Read one cold-safe, message-aligned Session history page. - * @param request - durable address, backward cursor, and page budget. + * @param request - durable address, optional fixed cut, backward cursor, and page budget. * @param signal - cancellation for persistence reads. - * @returns one chronological page. + * @returns one chronological page with its inclusive cursor. */ -@Remote('page') page(request: SessionPageRequest, signal: AbortSignal): Promise +@Remote events(request: SessionPageRequest, signal: AbortSignal): Promise + +/** + * Subscribe to Session events without reading a snapshot. + * @param request - Session address. + * @param signal - subscription cancellation. + * @returns readiness and subsequent events, without a snapshot. + */ +@Remote({ mode: 'stream' }) observeEvent(request: SessionObserveEventRequest, signal: AbortSignal): AsyncIterable + +/** + * Subscribe to sparse Session projection changes. + * @param request - target Session. + * @param signal - subscription cancellation. + * @returns readiness and sparse projection changes. + */ +@Remote({ mode: 'stream' }) observeProjections(request: SessionProjectionsRequest, signal: AbortSignal): AsyncIterable + +/** + * Read passive Session state. + * @param request - target Session. + * @param signal - read cancellation. + * @returns current passive state. + */ +@Remote state(request: SessionStateRequest, signal: AbortSignal): Promise + +/** + * Subscribe to complete Session state replacements. + * @param request - target Session. + * @param signal - subscription cancellation. + * @returns complete passive state replacements. + */ +@Remote({ mode: 'stream' }) observeState(request: SessionStateRequest, signal: AbortSignal): AsyncIterable + +/** + * Wait for Session quiescence or pending input with bounded assistant output. + * @param request - Session, wait bounds and output window. + * @param signal - caller cancellation. + * @returns stopping state and bounded assistant output. + */ +@Remote wait(request: SessionWaitRequest, signal: AbortSignal): Promise /** * Follow one Session log from its opening or resume cursor. @@ -981,7 +1044,7 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | * @param signal - cancellation for the Session read. * @returns a sequenced baseline, cached hints when migration is deferred, or null when absent. */ -@Remote('projections') async projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise +@Remote('projections') projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise /** * Stream a complete live-control baseline followed by replacement frames. @@ -995,6 +1058,26 @@ Types: [SessionId](core.md) · [SessionSearchRequest](session-query.md) Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/session-controller/src/index.ts) + + +### `ctx.sessionLogDeepSeek` — `SessionLogDeepSeekService` + +Incremental Session-log contributor with caller-owned upload exclusions. + +```ts cordis-catalog +/** + * Exclude matching requests before reading or preparing their log contribution. + * Any matching rule suppresses both the field and its acceptance callback. With + * no matching rules, normal upload eligibility applies. A throwing rule fails + * this contribution; the request-extension registry omits it and reports the error. + * @param exclude - synchronous, side-effect-free predicate; `true` skips this upload. + * @returns effect disposer that removes this registration when called or when the caller unloads. + */ +registerExclusion(exclude: SessionLogUploadExclusion): () => Promise +``` + +Source: [`packages/session/session-log-deepseek/src/index.ts`](../../packages/session/session-log-deepseek/src/index.ts) + ### `ctx.sessions` — `SessionStore` diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md index 57e732d08c..fb26a5105c 100644 --- a/docs/subsystems/session.zh.md +++ b/docs/subsystems/session.zh.md @@ -821,6 +821,29 @@ interface PluginRecord { 可选的 `application` 指定文件关联应用，不修改系统默认值；`workspacePathApplications({ path })` 在校验 Host 路径后返回当前关联应用、名称、图标和默认项。 +## Session 日志上传排除条件 + +`ctx.sessionLogDeepSeek.registerExclusion()` 注册归调用方所有的判断函数，输入为 `SessionLogUploadRequest`。任意条件匹配时，在读取 Session 事件前省略日志贡献与接受回调。没有条件匹配时保留普通上传资格判断。[包 README](../../packages/session/session-log-deepseek/README.zh.md#upload-exclusions) 定义失败与释放行为。 + +```ts type-equiv +/** Request identity inspected before preparing a Session-log contribution. */ +interface SessionLogUploadRequest { + /** Live Session whose canonical log would be contributed. */ + readonly sessionId: SessionId + /** Auxiliary request classification; absent for ordinary conversation requests. */ + readonly purpose?: string +} +``` + +```ts type-equiv +/** + * Synchronous, side-effect-free upload exclusion owned by its registering plugin. + * @param request - request identity; the predicate must not mutate it. + * @returns `true` to omit the log field and acceptance callback, or `false` to keep checking eligibility. + */ +type SessionLogUploadExclusion = (request: SessionLogUploadRequest) => boolean +``` + @@ -942,8 +965,8 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | @Remote('prompt') async prompt(request: SessionPromptRequest, signal: AbortSignal): Promise /** - * Read one image proven reachable from the addressed Session log. - * @param request - Session and attachment identities used for authorization. + * Read one image from the attachment store after gateway authorization. + * @param request - image reference and gateway permission scope; Session existence is not checked. * @returns the durable attachment reference and base64-encoded bytes. */ @Remote('attachment') attachment(request: SessionAttachmentRequest): Promise @@ -964,11 +987,51 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | /** * Read one cold-safe, message-aligned Session history page. - * @param request - durable address, backward cursor, and page budget. + * @param request - durable address, optional fixed cut, backward cursor, and page budget. * @param signal - cancellation for persistence reads. - * @returns one chronological page. + * @returns one chronological page with its inclusive cursor. */ -@Remote('page') page(request: SessionPageRequest, signal: AbortSignal): Promise +@Remote events(request: SessionPageRequest, signal: AbortSignal): Promise + +/** + * Subscribe to Session events without reading a snapshot. + * @param request - Session address. + * @param signal - subscription cancellation. + * @returns readiness and subsequent events, without a snapshot. + */ +@Remote({ mode: 'stream' }) observeEvent(request: SessionObserveEventRequest, signal: AbortSignal): AsyncIterable + +/** + * Subscribe to sparse Session projection changes. + * @param request - target Session. + * @param signal - subscription cancellation. + * @returns readiness and sparse projection changes. + */ +@Remote({ mode: 'stream' }) observeProjections(request: SessionProjectionsRequest, signal: AbortSignal): AsyncIterable + +/** + * Read passive Session state. + * @param request - target Session. + * @param signal - read cancellation. + * @returns current passive state. + */ +@Remote state(request: SessionStateRequest, signal: AbortSignal): Promise + +/** + * Subscribe to complete Session state replacements. + * @param request - target Session. + * @param signal - subscription cancellation. + * @returns complete passive state replacements. + */ +@Remote({ mode: 'stream' }) observeState(request: SessionStateRequest, signal: AbortSignal): AsyncIterable + +/** + * Wait for Session quiescence or pending input with bounded assistant output. + * @param request - Session, wait bounds and output window. + * @param signal - caller cancellation. + * @returns stopping state and bounded assistant output. + */ +@Remote wait(request: SessionWaitRequest, signal: AbortSignal): Promise /** * Follow one Session log from its opening or resume cursor. @@ -985,7 +1048,7 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | * @param signal - cancellation for the Session read. * @returns a sequenced baseline, cached hints when migration is deferred, or null when absent. */ -@Remote('projections') async projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise +@Remote('projections') projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise /** * Stream a complete live-control baseline followed by replacement frames. @@ -999,6 +1062,26 @@ Types: [SessionId](core.zh.md) · [SessionSearchRequest](session-query.zh.md) Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/session-controller/src/index.ts) + + +### `ctx.sessionLogDeepSeek` — `SessionLogDeepSeekService` + +Incremental Session-log contributor with caller-owned upload exclusions. + +```ts cordis-catalog +/** + * Exclude matching requests before reading or preparing their log contribution. + * Any matching rule suppresses both the field and its acceptance callback. With + * no matching rules, normal upload eligibility applies. A throwing rule fails + * this contribution; the request-extension registry omits it and reports the error. + * @param exclude - synchronous, side-effect-free predicate; `true` skips this upload. + * @returns effect disposer that removes this registration when called or when the caller unloads. + */ +registerExclusion(exclude: SessionLogUploadExclusion): () => Promise +``` + +Source: [`packages/session/session-log-deepseek/src/index.ts`](../../packages/session/session-log-deepseek/src/index.ts) + ### `ctx.sessions` — `SessionStore` diff --git a/docs/subsystems/sidebar-right.i18n.yaml b/docs/subsystems/sidebar-right.i18n.yaml index 83cd761e68..482969fe6c 100644 --- a/docs/subsystems/sidebar-right.i18n.yaml +++ b/docs/subsystems/sidebar-right.i18n.yaml @@ -15,11 +15,11 @@ en: b7b8a7b411aee94d zh: 7298c20000945d97 /right-sidebar/navigation-ctx-sidebarright: - en: 0f80b5364cbad804 - zh: db81652a5374fad1 + en: 2a2b3a33df9e0749 + zh: 629c791cd2ae50ba /right-sidebar/slots-and-owner-props: - en: f58dc6ff6b0027a7 - zh: 707722fcbd096efc + en: 6b5faaed58ab5fb1 + zh: 2118439d3403a735 /right-sidebar/document-renderers: en: 2bf47a890fce175e zh: 45f81c579b8939a8 @@ -30,8 +30,8 @@ en: 2b1b49dbba9cc9ee zh: 13d2a45224743b37 /right-sidebar/shipped-types: - en: 81cc0928abeff74b - zh: 370fcfd5bb350ed9 + en: f8f0e368701f6669 + zh: de364aaf3345d70c /right-sidebar/not-built: - en: 65e86c293eb99242 - zh: 852dfe7713848453 + en: 5cf5ab52c8007897 + zh: 346490f01e318d95 diff --git a/docs/subsystems/sidebar-right.md b/docs/subsystems/sidebar-right.md index 1342a7f938..00a0671bae 100644 --- a/docs/subsystems/sidebar-right.md +++ b/docs/subsystems/sidebar-right.md @@ -75,22 +75,23 @@ export function apply(ctx: Context): void { ## Navigation: `ctx.sidebarRight` -Two opens are the navigation controller, and every way into the column calls one of them: `openResource(address, options?)` for a `dsh-resource://` address — the conversation's file links, a tool row's line reference, a file tree's rows — and `openTab(kind, options?)` for a page — the strip's add control, a guide entry box, or an HTTP(S) link in Assistant Markdown. Both run four steps as one history entry — claim (the registry ranks the resource's types, or the named `kind`'s implementation in force answers); focus a tab already showing the same `(kind, address)`; otherwise seat a new tab; expand the column — and then record the navigation in the Tab domain ([service](../../packages/client/ui-sidebar-right/README.md#ctxsidebarright)). Content the user cannot see is not opened, so a collapsed column expands in the same step. `openResource` throws for an address outside `dsh-resource://` or one no type claims; `openTab` throws for a kind nothing registered: both are wiring mistakes, not user errors. +Two opens are the navigation controller, and every way into the column calls one of them: `openResource(address, options?)` for a `dsh-resource://` address — the conversation's file links, a tool row's line reference, a file tree's rows — and `openTab(kind, options?)` for a page — the strip's add control, a guide entry box, or an HTTP(S) link in Assistant Markdown. Both run four steps as one history entry — claim (the registry ranks the resource's types, or the named `kind`'s implementation in force answers); focus a tab already showing the same `(kind, address)`; otherwise seat a new tab; expand the column — and then record the navigation in the Tab domain ([service](../../packages/client/ui-sidebar-right/README.md#ctxsidebarright)). Content the user cannot see is not opened, so a collapsed column expands in the same step, unless the open replaces a floating tab or reveals a tab in a floating panel. A reveal of a tab already on screen makes the pane holding it glow once, for every tab type, and only while its Session is on screen; a reveal that switches tabs or expands the column does not glow. `openResource` throws for an address outside `dsh-resource://` or one no type claims; `openTab` throws for a kind nothing registered: both are wiring mistakes, not user errors. | Option | Meaning | |---|---| | `paneId` | Land a new tab in this pane; default is the active docked pane (the first docked pane while a floating pane is active). | -| `replaceTab` | Take this tab's pane and strip slot, closing it in the same step; a floating tab lends no place, so the new tab lands as if unplaced. | +| `replaceTab` | New content takes this tab's place and the tab closes in the same step: a docked tab's pane and strip slot, or a floating tab's panel, keeping its pane id and rectangle. A reveal keeps the tab open ([semantics](../../packages/client/ui-sidebar-right/README.md#ctxsidebarright)). | | `revealIfOpened` | Default `true`: a tab already showing the same `(kind, address)` is focused and handed `params`. `false` opens another tab regardless. | | `preferNewPane` | Prefer a new docked pane under the normal pane budget and room rule; fall back to the target pane when it cannot split. Ignored with `replaceTab`. | +| `destination` (`openResource` only) | `'sidebar'` or `'float'`: settle in the active docked pane (the first docked pane while a floating pane is active) or a new floating panel, ignoring the four options above. A copy already there is revealed; else a copy in the other host moves there with its tab id and body state; else a new tab opens. `'float'` leaves the column's expansion unchanged, for a new tab as for a move ([semantics](../../packages/client/ui-sidebar-right/README.md#ctxsidebarright)). | | `kind` (`openResource` only) | Name the opening type instead of ranking claims; its implementation in force opens the address, and its `canOpen` still applies. | | `params` | Navigation parameters for the body, delivered as `navigation.params`. `openResource` types them by resource type through the merge-extensible `SidebarRightResourceParamsMap` (the text preview declares `{ line?: number }`); `openTab` types them by kind through `SidebarRightTabParamsMap`, `undefined` for a kind that declares none; a body reads `SidebarRightNavigationParams`, the union of both. Values are JSON-shaped by convention and not validated at run time. | -Placement is the caller's option, never a type's property. The conversation calls `openResource(fileAddressFor(sessionId, cwd, path))` and, from a `read` tool row, adds `{ params: { line } }` from the call's 1-based `offset`; a guide entry box calls `tab.actions.openTab(entry.kind, { replaceTab: true })`; a file-tree row calls `tab.actions.openResource(address)`; the strip's add control calls `openTab('guide', { paneId, revealIfOpened: false })`. +Placement belongs to the caller, not the tab type. The [files navigator reference](../../packages/client/ui-sidebar-files/README.md#the-navigator) defines its host-owned opening callbacks; the [guide reference](../../packages/client/ui-sidebar-right/README.md#the-guide) defines guide replacement and explicit close. -`close(tabId)` closes a tab; `active()` returns the active pane's active tab; `isExpanded()` and `toggleExpanded()` read and flip the column, the flip recorded in the sequence. Reads answer for the no-Session case with `undefined` or `false`; writes need a mounted Session surface and throw without one rather than write into a surface nobody draws. +`close(tabId)` closes a tab; `hide(tabId)` closes a floating tab or collapses its docked column; `active()` returns the active pane's active tab; `isExpanded()` and `toggleExpanded()` read and flip the column, the flip recorded in the sequence. Reads answer for the no-Session case with `undefined` or `false`; writes need a mounted Session surface and throw without one rather than write into a surface nobody draws. -`focus(tabId)` makes a tab its pane's active tab; `split(paneId?)` splits the active docked pane, or the named one, and returns the new pane's id — or `undefined`, recording nothing, when the pane budget or the column's width forbids a split; `float(tabId, rect?)` lifts a tab into a floating pane; `dock(paneId)` returns a floating pane to the docked area. All four run the store's existing actions and record one history entry each; a target that does not exist or is already in the requested state is a no-op, and like `open` they throw without a mounted Session surface. `TabId`, `PaneId`, `TabRecord`, and `FloatRect` are re-exported from the package's `/client` entry so a caller needs no dockkit import. +`focus(tabId)` makes a tab its pane's active tab; `split(paneId?)` splits the active docked pane, or the named one, and returns the new pane's id — or `undefined`, recording nothing, when the pane budget or the column's width forbids a split; `float(tabId, rect?)` lifts a tab into a floating pane; `dock(paneId)` returns a floating pane to the docked area and expands the column. All four run the store's existing actions and record one history entry each; a target that does not exist or is already in the requested state is a no-op, and like `open` they throw without a mounted Session surface. `TabId`, `PaneId`, `TabRecord`, and `FloatRect` are re-exported from the package's `/client` entry so a caller needs no dockkit import. `focusedTarget(element?)` captures the visible page under live DOM focus, including an embedding iframe; outside or stale sidebar markup yields no target. `commandTarget(element?)` also permits the mounted Session's active dock pane for an open initiated outside the sidebar. A `SidebarRightTarget` captures Session, pane, host, tab occurrence, and navigation revision. `isTargetCurrent(target)` checks that identity before execution, so reopening a record or navigating it invalidates a captured action; it never retargets to another page. See the [controller methods](../../packages/client/ui-sidebar-right/src/client/service.ts) for close and placement outcomes. @@ -106,9 +107,9 @@ The Sidebar declares four extension slots; its document tab declares the additio | `sidebar.right.tab.menu.item` | list, Session scope | Content-level actions appended after the kit's own layout actions. An item that acts must call the owner's `dismiss()`. | | `sidebar.right.tab.document` | keyed by the document implementation's `id`, Session scope | The selected file renderer inside the document tab; the parent owns shared loading and toolbar controls. | -A body, title and guide replacement receive the framework-injected `useTabInfo()`. It returns `{ sidebar, panel, tab }`: `sidebar` holds `expanded` and `fullscreen`, `panel.id` names the containing pane, and `tab` contains its record fields plus `visible`, `navigation`, `signal`, and `actions`. All tabs require a foreground Session. Docked bodies also require expansion and selection; docked titles require expansion; foreground floats survive collapse. `signal` aborts when the record disappears or the plugin unloads, not on hiding or Session switching. `tab.actions` provides `openResource`, `openTab`, and `close`, bound to the tab's own Session. Open placement defaults to its current pane; `revealIfOpened` defaults to `true`, and `replaceTab: true` replaces this record in the same history entry. Menu entries retain plain `tab` and `dismiss` owner parameters. +A body, title and guide replacement receive the framework-injected `useTabInfo()`. It returns `{ sidebar, panel, tab }`: `sidebar` holds `expanded` and `fullscreen`, `panel.id` names the containing pane and the required `panel.isFloating: boolean` distinguishes a floating panel from a docked pane. Both update through the hook when a tab moves, while `tab.id` stays unchanged. `tab` also contains its other record fields plus `visible`, `navigation`, `signal`, and `actions`. All tabs require a foreground Session. Docked bodies also require expansion and selection; docked titles require expansion; foreground floats survive collapse. `signal` aborts when the record disappears or the plugin unloads, not on hiding or Session switching. `tab.actions` provides `openResource`, `openTab`, and `close`, bound to the tab's own Session. Opens return `void` and default to its current docked pane, or the active docked pane when this tab floats; `revealIfOpened` defaults to `true`, and `replaceTab: true` lets new content replace this record in the same history entry; an `openResource` with `destination` passes neither this tab's pane nor this record. Menu entries retain plain `tab` and `dismiss` owner parameters. -`navigation.revision` increments on every navigation to the tab whether or not `params` changed, so a body can act on "navigated again" alone; it is `1` for a tab opened by address and `0` for a record nobody opened by address — a seeded guide, or a tab restored by undo. The Tab domain holds one occurrence per open record: a record that appears is pinned in the resource model, so switching tabs unmounts a body without dropping its content; a record that vanishes is aborted and dropped; a record restored by undo is a new occurrence ([Tab domain](../../packages/client/ui-sidebar-right/README.md#the-tab-domain)). +`navigation.revision` increments on every navigation to the tab whether or not `params` changed, so a body can act on "navigated again" alone; it is `1` for a tab opened by address and `0` for a record nobody opened by address — a seeded guide, or a tab restored by reload or undo. The Tab domain holds one occurrence per open record: a record that appears is pinned in the resource model, so switching tabs unmounts a body without dropping its content; a record that vanishes is aborted and dropped; a record restored by undo is a new occurrence ([Tab domain](../../packages/client/ui-sidebar-right/README.md#the-tab-domain)). `tab.actions.bindCommands(commands)` contributes `SidebarRightTabCommands`, currently an optional `refresh` callback, for the mounted body. Omitted operations are unavailable; the returned disposer releases that registration without removing a newer body's commands. The tab lifetime also releases them. `tab.refreshShortcut` supplies the effective refresh catalog entry for page controls; it is optional when no entry is available. These fields are declared in the [slot owner types](../../packages/client/ui-sidebar-right/src/client/contract/slots.ts). @@ -141,15 +142,15 @@ The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote name ## Shipped types - **`guide`** — `builtin`, opened as `openTab('guide')`. A muted compass sits above one capsule per contributed `guide` entry, in `order`; short lists show registered descriptions, and every missing icon uses the shipped placeholder. Picking a capsule opens the contributing type as a page in the guide tab's place. A pane holds at most one guide tab, and the strip's add control appears only while its pane has none. A new pane receives the registered default page: the sole guide entry directly, or the guide when the entry count is not one ([guide](../../packages/client/ui-sidebar-right/README.md#the-guide)). -- **`text`** — `fallback`, `dsh-resource://file/**`, claiming Session addresses only. Document Preview observes metadata through `useResource<'file'>`, loads content through Remote callbacks, and owns renderer selection, the toolbar, per-tab refresh, scroll, and source navigation; unknown extensions render as plain text ([README](../../packages/client/ui-sidebar-documentpreview/README.md)). -- **`files`** — `builtin`, opened as `openTab('files')`. The workspace directory tree, listed lazily through `list` and watched by expanded directory, opening a file with `tab.actions.openResource(fileAddressFor(sessionId, root, path))` into its own pane ([README](../../packages/client/ui-sidebar-files/README.md)). +- **`text`** — `fallback`, `dsh-resource://file/**`, claiming Session addresses only. Document Preview observes metadata through `useResource<'file'>`, loads content through Remote callbacks, and owns renderer selection, the toolbar, per-tab refresh, scroll, and source navigation; unknown extensions render as plain text. It directly renders the files plugin's `sidebar.files.navigator` and `sidebar.files.navigator.toggle` Factories in docked and floating panes; unregistered Factories render nothing ([README](../../packages/client/ui-sidebar-documentpreview/README.md)). +- **`files`** — `builtin`, opened as `openTab('files')`. The files page and navigator share one workspace tree per pane. [The package reference](../../packages/client/ui-sidebar-files/README.md) owns lazy listings, watches, opening callbacks, and navigation-driven visibility. - **`browser`** — multi-instance `builtin`, opened as `openTab('browser', { params: { url? } })`. Chat's [link preference](../../packages/client/ui-chat/README.md) controls whether Assistant Markdown opens HTTP(S) links here. It accepts public and loopback HTTP(S) targets under the default sandbox, rejects local files in favor of Document Preview, and uses application-known iframe history ([README](../../packages/client/ui-sidebar-browser/README.md)). - **`subagentchat`** — `builtin`, `dsh-resource://subagentchat/session/?parent=&mode=`. An explicitly addressed subagent Conversation retained by the resource provider and rendered through the shared Conversation Factory ([README](../../packages/client/ui-subagent/README.md)). ## Not built -- Persistence: layout state is memory-only; a reload starts every session collapsed, and no session's tabs are visible from another. +- Cross-device layout synchronization: layouts are browser-local, with separate saved state per Session ([state](../../packages/client/ui-sidebar-right/README.md#state)). - A read-only layout snapshot or subscription on `ctx.sidebarRight`: the service exposes operations only, and dockkit's `LayoutState`/`LayoutOp` are internal. - A capability-discovery array (`features`) on the service. - An `option` priority band for tab types: nothing lists a tab type without letting it claim. diff --git a/docs/subsystems/sidebar-right.zh.md b/docs/subsystems/sidebar-right.zh.md index e7df97d11c..72c6db445f 100644 --- a/docs/subsystems/sidebar-right.zh.md +++ b/docs/subsystems/sidebar-right.zh.md @@ -75,22 +75,23 @@ export function apply(ctx: Context): void { ## 导航：`ctx.sidebarRight` -两种打开构成导航控制器，进入这一列的每条路都调用其一：`openResource(address, options?)` 打开 `dsh-resource://` 地址——会话区的文件链接、工具行的行号引用、文件树的行；`openTab(kind, options?)` 打开页面——tab 条的新增控件、引导页入口框或 Assistant Markdown 中的 HTTP(S) 链接。两者都以一条历史记录走完四步——认领（注册表为资源排候选，或点名 `kind` 的生效实现应答）；聚焦已显示同一 `(kind, address)` 的 tab；否则落一个新 tab；展开这一列——然后把导航记入 Tab 域（[服务](../../packages/client/ui-sidebar-right/README.zh.md#ctxsidebarright)）。用户看不见的内容不算打开，所以折叠的列会在同一步展开。`openResource` 对 `dsh-resource://` 之外的地址或无人认领的地址抛错；`openTab` 对无人注册的 kind 抛错：二者都是接线错误，不是用户错误。 +两种打开构成导航控制器，进入这一列的每条路都调用其一：`openResource(address, options?)` 打开 `dsh-resource://` 地址——会话区的文件链接、工具行的行号引用、文件树的行；`openTab(kind, options?)` 打开页面——tab 条的新增控件、引导页入口框或 Assistant Markdown 中的 HTTP(S) 链接。两者都以一条历史记录走完四步——认领（注册表为资源排候选，或点名 `kind` 的生效实现应答）；聚焦已显示同一 `(kind, address)` 的 tab；否则落一个新 tab；展开这一列——然后把导航记入 Tab 域（[服务](../../packages/client/ui-sidebar-right/README.zh.md#ctxsidebarright)）。用户看不见的内容不算打开，所以折叠的列会在同一步展开；替换浮动 tab、或揭示浮窗中的 tab 时除外。揭示一个已在屏幕上显示的 tab 时，存放它的格发光提示一次，对所有 tab 类型都一样，且只在其会话位于屏幕上时播放；需要切换 tab 或展开该列的揭示不发光。`openResource` 对 `dsh-resource://` 之外的地址或无人认领的地址抛错；`openTab` 对无人注册的 kind 抛错：二者都是接线错误，不是用户错误。 | 选项 | 含义 | |---|---| | `paneId` | 新 tab 落到这个 pane；缺省为活动的停靠 pane（活动的是浮窗时取第一个停靠 pane）。 | -| `replaceTab` | 占用这个 tab 的 pane 与条上位置，并在同一步关闭它；浮窗里的 tab 让不出位置，新 tab 按未指定位置落位。 | +| `replaceTab` | 新内容取代这个 tab 的位置，并在同一步关闭它：停靠 tab 让出 pane 与条上位置，浮动 tab 让出浮窗，新 tab 沿用其 pane id 与矩形。揭示时该 tab 保持打开（[语义](../../packages/client/ui-sidebar-right/README.zh.md#ctxsidebarright)）。 | | `revealIfOpened` | 缺省 `true`：已显示同一 `(kind, address)` 的 tab 被聚焦并收到 `params`。`false` 则无论如何再开一个。 | | `preferNewPane` | 在普通格数预算与空间规则下优先新建停靠格；不能分栏时回退到目标格。与 `replaceTab` 一起使用时忽略。 | +| `destination`（仅 `openResource`） | `'sidebar'` 或 `'float'`：落在活跃停靠格（活动格是浮窗时为第一个停靠格）或新浮窗，忽略上面四个选项。该处已有副本时揭示它；否则把另一宿主中的副本连同 tab id 与正文状态移过去；否则新开 tab。`'float'` 新开和移动都不改变该列的展开状态（[语义](../../packages/client/ui-sidebar-right/README.zh.md#ctxsidebarright)）。 | | `kind`（仅 `openResource`） | 点名打开类型而不排候选；该 kind 的生效实现打开地址，它的 `canOpen` 仍生效。 | | `params` | 给正文的导航参数，作为 `navigation.params` 送达。`openResource` 按资源类型经声明合并表 `SidebarRightResourceParamsMap` 定型（文本预览声明 `{ line?: number }`）；`openTab` 按 kind 经 `SidebarRightTabParamsMap` 定型，未声明的 kind 为 `undefined`；正文读到的是二者联合 `SidebarRightNavigationParams`。值按约定为 JSON 形状，运行时不校验。 | -落位是调用方的选项，从不是类型的属性。会话区调 `openResource(fileAddressFor(sessionId, cwd, path))`，`read` 工具行另加 `{ params: { line } }`（来自调用的 1 起 `offset`）；引导页入口框调 `tab.actions.openTab(entry.kind, { replaceTab: true })`；文件树的行调 `tab.actions.openResource(address)`；tab 条的新增控件调 `openTab('guide', { paneId, revealIfOpened: false })`。 +落位属于调用方，不是 tab 类型的属性。[文件导航栏参考](../../packages/client/ui-sidebar-files/README.zh.md#the-navigator)定义其宿主提供的打开回调；[引导页参考](../../packages/client/ui-sidebar-right/README.zh.md#the-guide)定义引导页替换与显式关闭。 -`close(tabId)` 关闭一个 tab；`active()` 返回活动 pane 的活动 tab；`isExpanded()` 与 `toggleExpanded()` 读取与翻转这一列，翻转记入序列。无会话时读操作返回 `undefined` 或 `false`；写操作需要已挂载的会话面，没有时抛错而不是写进没人绘制的面。 +`close(tabId)` 关闭一个 tab；`hide(tabId)` 关闭浮动 tab 或收起其停靠列；`active()` 返回活动 pane 的活动 tab；`isExpanded()` 与 `toggleExpanded()` 读取与翻转这一列，翻转记入序列。无会话时读操作返回 `undefined` 或 `false`；写操作需要已挂载的会话面，没有时抛错而不是写进没人绘制的面。 -`focus(tabId)` 让一个 tab 成为其 pane 的活动 tab；`split(paneId?)` 分割活动的停靠 pane 或点名的 pane，返回新 pane 的 id——pane 数预算或列宽不允许时返回 `undefined` 且不记账；`float(tabId, rect?)` 把一个 tab 浮出为浮窗 pane；`dock(paneId)` 把浮窗 pane 收回停靠区。四者都走 store 既有动作、各记一条历史；目标不存在或已处于目标状态时是空操作，与 `open` 一样在没有已挂载会话面时抛错。`TabId`、`PaneId`、`TabRecord`、`FloatRect` 自本包 `/client` 入口再导出，调用方无需引 dockkit。 +`focus(tabId)` 让一个 tab 成为其 pane 的活动 tab；`split(paneId?)` 分割活动的停靠 pane 或点名的 pane，返回新 pane 的 id——pane 数预算或列宽不允许时返回 `undefined` 且不记账；`float(tabId, rect?)` 把一个 tab 浮出为浮窗 pane；`dock(paneId)` 把浮窗 pane 收回停靠区并展开该列。四者都走 store 既有动作、各记一条历史；目标不存在或已处于目标状态时是空操作，与 `open` 一样在没有已挂载会话面时抛错。`TabId`、`PaneId`、`TabRecord`、`FloatRect` 自本包 `/client` 入口再导出，调用方无需引 dockkit。 `focusedTarget(element?)` 从实时 DOM 焦点（包括内嵌 iframe）捕获可见页面；侧栏外部或过期的侧栏标记不产生目标。`commandTarget(element?)` 还允许侧栏外部发起的打开操作使用已挂载 Session 的活动停靠窗格。`SidebarRightTarget` 捕获 Session、窗格、host、tab occurrence 和导航 revision。`isTargetCurrent(target)` 在执行前检查这些身份，因此重新打开记录或再次导航都会使已捕获的动作失效；它不会改为操作其他页面。关闭与落位结果见[控制器方法](../../packages/client/ui-sidebar-right/src/client/service.ts)。 @@ -106,9 +107,9 @@ Sidebar 声明四个扩展 slot；其文档 tab 另行声明下表中的 keyed | `sidebar.right.tab.menu.item` | list，会话作用域 | 追加在 kit 自身布局动作之后的内容级动作。执行了动作的条目必须调用 owner 的 `dismiss()`。 | | `sidebar.right.tab.document` | 按文档实现的 `id` keyed，会话作用域 | 文档 tab 内选中的文件渲染器；父组件拥有共享加载与工具栏控件。 | -正文、标题与引导页替换项接收框架注入的 `useTabInfo()`。它返回 `{ sidebar, panel, tab }`：`sidebar` 包含 `expanded` 与 `fullscreen`，`panel.id` 标识所属窗格，`tab` 包含记录字段以及 `visible`、`navigation`、`signal` 和 `actions`。所有 tab 都要求 Session 位于前台。停靠正文还要求展开且选中；停靠标题要求展开；前台浮窗不随整栏收起。`signal` 在记录消失或插件卸载时中止，不因隐藏或切换 Session 而中止。`tab.actions` 提供绑定到标签所属 Session 的 `openResource`、`openTab` 与 `close`。打开位置缺省为当前所属窗格；`revealIfOpened` 缺省为 `true`，`replaceTab: true` 在同一历史项中替换本记录。菜单项保留普通的 `tab` 与 `dismiss` owner 参数。 +正文、标题与引导页替换项接收框架注入的 `useTabInfo()`。它返回 `{ sidebar, panel, tab }`：`sidebar` 包含 `expanded` 与 `fullscreen`，`panel.id` 标识所属窗格，必填的 `panel.isFloating: boolean` 区分浮窗与停靠窗格。tab 移动时，两者通过 hook 更新，`tab.id` 保持不变。`tab` 还包含其他记录字段以及 `visible`、`navigation`、`signal` 和 `actions`。所有 tab 都要求 Session 位于前台。停靠正文还要求展开且选中；停靠标题要求展开；前台浮窗不随整栏收起。`signal` 在记录消失或插件卸载时中止，不因隐藏或切换 Session 而中止。`tab.actions` 提供绑定到标签所属 Session 的 `openResource`、`openTab` 与 `close`。打开操作返回 `void`，缺省落在当前所属停靠窗格，当前 tab 浮动时落在活动停靠窗格；`revealIfOpened` 缺省为 `true`，`replaceTab: true` 让新内容在同一历史项中替换本记录；带 `destination` 的 `openResource` 既不传本 tab 所在窗格，也不传本记录。菜单项保留普通的 `tab` 与 `dismiss` owner 参数。 -`navigation.revision` 在每次导航到该 tab 时递增，`params` 不变也递增，正文可仅凭「又被导航了」行动；按地址打开的 tab 为 `1`，没有人按地址打开的记录——种入的引导、撤销恢复的 tab——为 `0`。Tab 域为每条打开的记录保有一个 occurrence：记录出现即在资源模型里钉住，因此切换 tab 卸载正文也不丢内容；记录消失即中止并丢弃；撤销恢复的记录是新的 occurrence（[Tab 域](../../packages/client/ui-sidebar-right/README.zh.md#the-tab-domain)）。 +`navigation.revision` 在每次导航到该 tab 时递增，`params` 不变也递增，正文可仅凭「又被导航了」行动；按地址打开的 tab 为 `1`，没有人按地址打开的记录——种入的引导、刷新或撤销恢复的 tab——为 `0`。Tab 域为每条打开的记录保有一个 occurrence：记录出现即在资源模型里钉住，因此切换 tab 卸载正文也不丢内容；记录消失即中止并丢弃；撤销恢复的记录是新的 occurrence（[Tab 域](../../packages/client/ui-sidebar-right/README.zh.md#the-tab-domain)）。 `tab.actions.bindCommands(commands)` 为已挂载正文提供 `SidebarRightTabCommands`，目前包含可选的 `refresh` 回调。省略的操作不可用；返回的 disposer 释放本次注册，不会移除较新正文的命令。标签生命周期结束时也会释放这些命令。`tab.refreshShortcut` 为页面控件提供生效的刷新目录项；没有可用条目时该字段可省略。这些字段声明在 [slot owner 类型](../../packages/client/ui-sidebar-right/src/client/contract/slots.ts)中。 @@ -141,15 +142,15 @@ Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名 ## 内置类型 - **`guide`**——`builtin`，以 `openTab('guide')` 打开。一枚弱化的罗盘位于各类型按 `order` 贡献的入口胶囊上方；入口较少时显示已注册的描述，未提供图标的入口统一使用内置占位符。点选胶囊即在引导 tab 的位置把贡献它的类型作为页面打开。每个 pane 最多一个引导 tab，tab 条的新增控件只在本 pane 没有引导时出现。新 pane 使用已注册的默认页：只有一个引导入口时直接使用该入口，否则使用引导页（[引导](../../packages/client/ui-sidebar-right/README.zh.md#the-guide)）。 -- **`text`**——`fallback`，`dsh-resource://file/**`，只认领 Session 地址。Document Preview 通过 `useResource<'file'>` 观察元数据，经 Remote 回调加载内容，并拥有渲染器选择、工具栏、逐 tab 刷新、滚动与源码定位；未知扩展名按纯文本渲染（[README](../../packages/client/ui-sidebar-documentpreview/README.zh.md)）。 -- **`files`**——`builtin`，以 `openTab('files')` 打开。工作区目录树，经 `list` 懒加载，按展开目录建立监听，用 `tab.actions.openResource(fileAddressFor(sessionId, root, path))` 在自己所在 pane 打开文件（[README](../../packages/client/ui-sidebar-files/README.zh.md)）。 +- **`text`**——`fallback`，`dsh-resource://file/**`，只认领 Session 地址。Document Preview 通过 `useResource<'file'>` 观察元数据，经 Remote 回调加载内容，并拥有渲染器选择、工具栏、逐 tab 刷新、滚动与源码定位；未知扩展名按纯文本渲染。它在停靠与浮动窗格中直接渲染 files 插件的 `sidebar.files.navigator` 与 `sidebar.files.navigator.toggle` 两个 Factory；未注册时不绘制内容（[README](../../packages/client/ui-sidebar-documentpreview/README.zh.md)）。 +- **`files`**——`builtin`，以 `openTab('files')` 打开。文件页与导航栏共享每个分栏的一棵工作区目录树。[包参考](../../packages/client/ui-sidebar-files/README.zh.md)定义懒加载目录列表、监听、打开回调及导航驱动的可见性。 - **`browser`**——可多开的 `builtin`，以 `openTab('browser', { params: { url? } })` 打开。Chat 的[链接偏好](../../packages/client/ui-chat/README.zh.md)决定 Assistant Markdown 是否在此打开 HTTP(S) 链接。它在默认 sandbox 下接受公共与 loopback HTTP(S) 目标，本地文件改用 Document Preview，并使用应用已知的 iframe history（[README](../../packages/client/ui-sidebar-browser/README.zh.md)）。 - **`subagentchat`**——`builtin`，`dsh-resource://subagentchat/session/?parent=&mode=`。资源提供方保留一个显式寻址的 subagent Conversation，并通过共享 Conversation Factory 渲染（[README](../../packages/client/ui-subagent/README.zh.md)）。 ## 不做 -- 持久化：布局状态只在内存里；刷新后每个会话从折叠开始，任何会话的 tab 都不会出现在另一个会话里。 +- 跨设备布局同步：布局保存在浏览器本地，各 Session 独立保存状态（[状态](../../packages/client/ui-sidebar-right/README.zh.md#state)）。 - `ctx.sidebarRight` 上的只读布局快照或订阅：服务只暴露操作，dockkit 的 `LayoutState`/`LayoutOp` 是内部的。 - 服务上的能力探测数组（`features`）。 - tab 类型的 `option` 优先级档：没有「只列出、不许认领」的 tab 类型。 diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml index c4fbc992b6..b9101bbb51 100644 --- a/docs/subsystems/skills.i18n.yaml +++ b/docs/subsystems/skills.i18n.yaml @@ -9,20 +9,20 @@ en: abe338b6c6d1ebd1 zh: c604db2de10a23c4 /skills/local-discovery-priority: - en: accf8ad4c73c41ad - zh: 141294fe8dab8ecf + en: 390fc00bbccfb777 + zh: 96ff7abfbd4b911b /skills/skill-identity: en: 61295a9cf1c51588 zh: 1c4c1582688d2310 /skills/summaries-candidates-and-complete-definitions: - en: 8819c25fac497a1f - zh: 5795f0d16f09750e + en: fdc9f7c9c7f1ba0f + zh: 0ce311eb495233e6 /skills/lookup-and-configuration: en: e60215d73b0abe75 zh: a086985044324141 /skills/session-catalog-and-tool-contract: - en: 5d5c36b1843a9d7d - zh: cd92ab1545e65722 + en: 6624024d8fc01937 + zh: 79533abe482565d8 /skills/browser-session-catalog: en: 1209dc6ee65fd476 zh: af3b7ef836564d05 diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md index 3bfdbff402..0c7ab18d2b 100644 --- a/docs/subsystems/skills.md +++ b/docs/subsystems/skills.md @@ -74,7 +74,7 @@ The shipped local provider scans roots in rank order: | 500 | `user-agents` | `/skills` | | 600 | `bundled` | `Config.bundledSkillDir` when configured | -The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child. The local provider does not synthesize built-in system skills; deployments supply packaged skills through configured bundled roots or dedicated providers. +The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child. The local provider does not synthesize built-in system skills; deployments supply packaged skills through configured bundled roots or dedicated providers. A failed root contributes no candidates, so a lower-priority same-name skill from another root may supply both the catalog description and loaded body until recovery. `dsh-skill-badge` registers one immutable `bundled` candidate at `BUNDLED_SKILL_RANK` and exposes its packaged asset directory through `resourceBase`. The shipped CLI declares the plugin disabled, so enabling its composition row is an explicit opt-in. @@ -127,7 +127,7 @@ interface SkillSummary { `ctx.skills.list()` preserves all four policy combinations. `isModelInvocable(skill)` and `isUserInvocable(skill)` read the corresponding required field. A model-only skill sets `{ modelInvocable: true, userInvocable: false }`, a user-only skill sets `{ modelInvocable: false, userInvocable: true }`, and setting both fields to `false` keeps the skill available only through trusted `ctx.skills.get()` callers. The local provider reads the exact kebab-case frontmatter keys `disable-model-invocation` and `user-invocable`, defaults omitted fields to `true`, and projects every parsed skill into this normalized policy. -`SkillCatalogSnapshot` distinguishes authoritative absence from transient provider failure or a catalog that kept changing during discovery. `skills` contains the sorted invocation-neutral summaries collected in that observation; `complete` is true only when every registered provider completed without a concurrent catalog revision. Incomplete snapshots are not cached, allowing each consumer to retain its last-good filtered catalog and retry. +`SkillCatalogSnapshot` distinguishes authoritative absence from transient provider failure or a catalog that kept changing during discovery. `skills` contains the sorted invocation-neutral summaries collected in that observation; `complete` is true only when every registered provider completed without a concurrent catalog revision. Incomplete snapshots are not cached, so the next lookup retries discovery; each consumer decides how to present the partial result. ```ts type-equiv /** One catalog observation plus whether discovery completed within a stable catalog revision. */ @@ -226,9 +226,9 @@ interface Config { ## Session catalog and tool contract -`dsh-tool-skill` injects the initial durable user-role `` at the first `agent/pre-step` of a live session that observes a non-empty complete view. The catalog contains sorted skill `name` and normalized, XML-escaped `description` only; it omits bodies, paths, sources, providers, and routing hints. Discovery forwards the step's abort signal through `SkillLookupOptions`. `catalogDescriptionMaxLength` is the consumer config for the description bound, with default `500` and integer minimum `3`. +`dsh-tool-skill` injects the initial durable user-role `` at the first `agent/pre-step` of a live session that observes available skills or incomplete discovery. The catalog contains sorted skill `name` and normalized, XML-escaped `description` only; it omits bodies, paths, sources, providers, and routing hints. Discovery forwards the step's abort signal through `SkillLookupOptions`. `catalogDescriptionMaxLength` is the consumer config for the description bound, with default `500` and integer minimum `3`. -Before each later model step, the consumer applies exact tool visibility and digests the exact rendered entries between the `` tags from a complete snapshot. It derives the comparison baseline from the same entries in the newest recognizable visible catalog message sourced by the plugin. A changed digest appends a durable full replacement through `agent.inject()`; deleting every skill appends an explicit empty replacement. Incomplete snapshots preserve the last-good model view. If compaction hides every historical catalog message, the next complete snapshot re-establishes the current catalog; an empty view with no prior catalog emits nothing. These catalog messages are session history, not World State. +Before each later model step, the consumer applies exact tool visibility and compares the entries and completeness with the newest recognizable visible catalog message in the session log. A changed observation contributes a durable replacement to the pre-step decision; deleting every skill appends an explicit empty replacement. Incomplete discovery publishes the available subset with a warning and optional `incomplete: true` source metadata; absence of that flag means complete. Recovery republishes the catalog even when its entries are unchanged. If compaction hides every historical catalog message, the next observation re-establishes the current catalog; a complete empty view with no prior catalog emits nothing. These catalog messages are session history, not World State. The model-facing `skill({ name })` tool validates the kebab-case name, finds the summary in the invocation-neutral catalog, rejects it before loading unless `isModelInvocable` permits access, then rereads the complete definition for the calling agent cwd and rechecks the policy before returning content. It reports an unresolved skill as unknown or no longer available and returns a tool result containing ``, ``, and ``. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. Body-only edits therefore change later tool calls without producing catalog messages or rewriting earlier tool results. diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md index d93f8416fb..f2f84ab22d 100644 --- a/docs/subsystems/skills.zh.md +++ b/docs/subsystems/skills.zh.md @@ -74,7 +74,7 @@ interface SkillProviderControl { | 500 | `user-agents` | `/skills` | | 600 | `bundled` | 配置了 `Config.bundledSkillDir` 时使用该目录 | -项目根目录为包含 `.git` 的最近祖先目录；找不到时使用当前 cwd。当 `ctx.fs` 可用时，git-root 向上查找通过文件系统服务探测 `.git`，使远程或沙箱工作区不会回退到宿主文件系统边界。用户 DSH 根目录会跳过其 `.system` 子目录。本地提供方不会合成内置系统 skill；部署方通过已配置的 bundled 根目录或专用提供方提供随包 skill。 +项目根目录为包含 `.git` 的最近祖先目录；找不到时使用当前 cwd。当 `ctx.fs` 可用时，git-root 向上查找通过文件系统服务探测 `.git`，使远程或沙箱工作区不会回退到宿主文件系统边界。用户 DSH 根目录会跳过其 `.system` 子目录。本地提供方不会合成内置系统 skill；部署方通过已配置的 bundled 根目录或专用提供方提供随包 skill。失败的根目录不提供候选项，因此在恢复之前，其他根中较低优先级的同名 skill 可能同时提供目录描述与加载的正文。 `dsh-skill-badge` 在 `BUNDLED_SKILL_RANK` 注册一个不可变的 `bundled` 候选项，并通过 `resourceBase` 公开其随包资产目录。交付的 CLI（命令行界面）将该插件声明为禁用，因此启用其组合配置行即为显式选择加入。 @@ -127,7 +127,7 @@ interface SkillSummary { `ctx.skills.list()` 保留全部四种策略组合。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别读取对应的必填字段。仅供模型调用的 skill 设置 `{ modelInvocable: true, userInvocable: false }`，仅供用户调用的 skill 设置 `{ modelInvocable: false, userInvocable: true }`，两个字段均设为 `false` 后，该 skill 只能由受信的 `ctx.skills.get()` 调用方获取。本地提供方读取名称完全匹配的 kebab-case frontmatter 键 `disable-model-invocation` 和 `user-invocable`，将省略的字段默认为 `true`，并为每个解析出的 skill 生成这个规范化策略。 -`SkillCatalogSnapshot` 用于区分已确定的不存在与提供方的瞬时失败或发现期间持续变化的目录。`skills` 包含该次观测中收集、排序且与调用策略无关的摘要；只有每个已注册提供方都在没有并发目录修订时完成发现，`complete` 才为 true。不完整快照不会缓存，因此每个消费方可以保留上一份经过自身过滤的可用目录并重试。 +`SkillCatalogSnapshot` 用于区分已确定的不存在与提供方的瞬时失败或发现期间持续变化的目录。`skills` 包含该次观测中收集、排序且与调用策略无关的摘要；只有每个已注册提供方都在没有并发目录修订时完成发现，`complete` 才为 true。不完整快照不会缓存，因此下次查询会重试发现；各消费方自行决定如何呈现部分结果。 ```ts type-equiv /** One catalog observation plus whether discovery completed within a stable catalog revision. */ @@ -226,9 +226,9 @@ interface Config { ## 会话目录与工具约定 -`dsh-tool-skill` 在存活会话中第一个观察到非空完整视图的 `agent/pre-step` 注入初始的持久 user-role ``。目录只包含已排序的 skill `name` 和规范化、经 XML 转义的 `description`；不包含正文、路径、来源、提供方或路由提示。发现通过 `SkillLookupOptions` 转发该步骤的 abort signal。`catalogDescriptionMaxLength` 是消费方用于 description 上限的配置，默认值为 `500`，整数最小值为 `3`。 +`dsh-tool-skill` 在存活会话中第一个观察到可用 skill 或发现不完整的 `agent/pre-step` 注入初始的持久 user-role ``。目录只包含已排序的 skill `name` 和规范化、经 XML 转义的 `description`；不包含正文、路径、来源、提供方或路由提示。发现通过 `SkillLookupOptions` 转发该步骤的 abort signal。`catalogDescriptionMaxLength` 是消费方用于 description 上限的配置，默认值为 `500`，整数最小值为 `3`。 -在后续每个模型步骤之前，消费方都会应用精确的工具可见性，并对完整快照中 `` 标签之间精确渲染的条目计算 digest。它以该插件所发布、最新一条可识别且仍可见的目录消息中的相同条目作为比较基线。digest 发生变化时，会通过 `agent.inject()` 追加一条持久的完整目录替换；删除所有 skill 时会追加一条显式的空替换。不完整快照会保留上一份可用模型视图。如果压缩（compaction）隐藏了所有历史目录消息，下一份完整快照会重新建立当前目录；如果视图为空且从未发布目录，则不发送任何内容。这些目录消息属于会话历史，而非 World State。 +在后续每个模型步骤之前，消费方都会应用精确的工具可见性，并将条目与完整性同会话日志中最新一条可识别且仍可见的目录消息比较。观测变化时，会向 pre-step 决策提供一条持久的替换目录；删除所有 skill 时会追加显式的空替换。发现不完整时会发布可用子集，并附带警告和可选的 `incomplete: true` 来源元数据；缺少该标记表示完整。恢复后即使条目未变也会重新发布目录。如果压缩（compaction）隐藏了所有历史目录消息，下一次观测会重新建立当前目录；完整的空视图在从未发布目录时不发送任何内容。这些目录消息属于会话历史，而非 World State。 面向模型的 `skill({ name })` 工具校验 kebab-case 名称，在与调用策略无关的目录中查找摘要，并在加载前通过 `isModelInvocable` 拒绝无权访问的 skill；随后它根据调用方 agent 的 cwd 重新读取完整定义，并在返回内容前再次检查策略。该工具将无法解析的 skill 报告为未知或已不可用，并返回包含 ``、`` 和 `` 的工具结果。`resourceBase` 仅按需解析显式引用的脚本、参考资料和资产；加载结果不枚举 skill 目录。因此，仅修改正文会改变后续工具调用，而不会生成目录消息或改写先前工具结果。 diff --git a/docs/subsystems/slots.i18n.yaml b/docs/subsystems/slots.i18n.yaml index 17ae54903e..0a2bb60f40 100644 --- a/docs/subsystems/slots.i18n.yaml +++ b/docs/subsystems/slots.i18n.yaml @@ -9,8 +9,8 @@ en: f2d2c0d3b8f14ec7 zh: 441ed13ff3f81d2a /web-client-slots/cardinality-and-scope: - en: 5b0ada069239576b - zh: 84e1e6b253d1461e + en: cd17e3e0ff6e62ff + zh: 6e0db2cb16c41b73 /web-client-slots/component-inputs: en: 9cb70abb2e39b958 zh: cd4b6f1705d90e17 diff --git a/docs/subsystems/slots.md b/docs/subsystems/slots.md index ee31122d13..fe8589f685 100644 --- a/docs/subsystems/slots.md +++ b/docs/subsystems/slots.md @@ -65,6 +65,8 @@ The slot declaration fixes two independent axes. `priority` is a shadowing rank for `single`, `list`, and `keyed` cells and an election order for `chain`. Lower values run or render first. Ordinary additive contributions should choose a fresh list `id` or keyed `key`; intentionally reusing a shipped cell replaces its presentation. +The [context-menu plugin](../../packages/client/ui-context-menu/README.md) contributes `useContextMenu` through `provideRoot`; every scope receives the same plugin-owned trigger factory. Its prop and retained handlers retire when the provider unloads. Its root-scoped keyed `contextMenu.icon` Slot renders business-owned icons from action metadata. + ## Component inputs A registered component receives inputs assembled at its binding site. Components derive these types rather than copying their members. @@ -140,7 +142,10 @@ Factory: conversation.content [ConversationContent] │ │ ├─ conversation.chat.text-interaction [list] │ │ └─ conversation.chat.flow [ChatFlow] │ │ └─ conversation.chat.node [ChatNodeSeat dispatch] -│ │ ├─ key=user,steering [UserMessageNodeView] +│ │ ├─ key=user [UserMessageNodeView] +│ │ │ ├─ conversation.chat.user.before [chain] +│ │ │ └─ calls Factory: conversation.chat.user.content +│ │ ├─ key=steering [UserMessageNodeView] │ │ │ └─ calls Factory: conversation.chat.user.content │ │ ├─ key=assistant-step [AssistantNodeView / AssistantMarkdown] │ │ │ ├─ conversation.chat.message.images [MessageImages] diff --git a/docs/subsystems/slots.zh.md b/docs/subsystems/slots.zh.md index ca13d60008..288b4b85f1 100644 --- a/docs/subsystems/slots.zh.md +++ b/docs/subsystems/slots.zh.md @@ -67,6 +67,8 @@ Slot 声明固定两个相互独立的维度。 +[右键菜单插件](../../packages/client/ui-context-menu/README.zh.md) 通过 `provideRoot` 贡献 `useContextMenu`；每个作用域接收同一个由插件拥有的触发器工厂。提供方卸载时，注入属性与保留的处理器一并失效。其根作用域 keyed Slot `contextMenu.icon` 根据操作元数据渲染业务方提供的图标。 + ## 组件输入 注册组件会在 binding 位置收到组装后的输入。组件应从这些类型推导 props，不要重新抄写成员。 @@ -142,7 +144,10 @@ Factory: conversation.content [ConversationContent] │ │ ├─ conversation.chat.text-interaction [list] │ │ └─ conversation.chat.flow [ChatFlow] │ │ └─ conversation.chat.node [ChatNodeSeat dispatch] -│ │ ├─ key=user,steering [UserMessageNodeView] +│ │ ├─ key=user [UserMessageNodeView] +│ │ │ ├─ conversation.chat.user.before [chain] +│ │ │ └─ calls Factory: conversation.chat.user.content +│ │ ├─ key=steering [UserMessageNodeView] │ │ │ └─ calls Factory: conversation.chat.user.content │ │ ├─ key=assistant-step [AssistantNodeView / AssistantMarkdown] │ │ │ ├─ conversation.chat.message.images [MessageImages] diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml index 5f4126783c..d58a4c2f17 100644 --- a/docs/subsystems/storage.i18n.yaml +++ b/docs/subsystems/storage.i18n.yaml @@ -9,14 +9,17 @@ en: b11e06e7c0e0fd13 zh: 4585f26ff416cb41 /storage/the-backend-contract: - en: 225e25b9b4b08865 - zh: 53bd3554da610607 + en: 50afeec4e9fd3e08 + zh: e8d2892c83ad3441 /storage/declaring-a-domain: - en: 775cce941500f01f - zh: 78acbc67f48574cb + en: fa4613279da360c5 + zh: 09e7a7d63bd1774a +/storage/domain-versioning: + en: 37e40cc29f3bb898 + zh: bbd55e732bd4b83b /storage/the-open-domain: - en: b69b25bc06f1c052 - zh: 8aca58718da520c7 + en: c0787f6a496b4c46 + zh: f219b16ec96d6cb6 /storage/the-domain-facility-ctx-storagedomain: en: deed74fcd4506ef4 zh: 8e3e6e5d2dc2e989 diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md index 8dddb5818e..16c994d8b0 100644 --- a/docs/subsystems/storage.md +++ b/docs/subsystems/storage.md @@ -44,7 +44,7 @@ interface StorageBackend { } ``` -A backend owns one medium (a file-tree root, a database file) and exposes optional operation groups; `kv` is the only shipped group. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, current format version, optional compatible record versions, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `deleteRecords`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are opaque strings in the `single` layout and match `[a-zA-Z0-9_-]+` path segments in the `per-record` layout. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium; durability holds for single-record writes and whole-file publishes, while a `per-record` batch deletion relies on the filesystem persisting directory-entry updates. `deleteRecords` applies a whole batch in one call: it resolves once every listed record is absent from the readable state and the backend accepted the batch, and a rejection normally leaves the batch unapplied; a backend that cannot establish or restore the batch's state rejects with `unknown-state`, after which every later operation on that unit rejects with the same error until `close()` releases it (calls after close reject `closed`). A `single`-layout failure after the atomic replacement (a directory-fsync error) can leave the new file on the medium while the caller sees a rejection; the unit keeps its memory consistent and the next publish rewrites the file. A `single` medium stamped with a different version rejects `version-mismatch`; a `per-record` document stamped outside the accepted set reads as absent. A medium that cannot be parsed as the unit rejects `malformed-medium`. [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) checks the shared clauses against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores one document per row in one database for frequently updated data. +A backend owns one medium (a file-tree root, a database file) and exposes optional operation groups; `kv` is the only shipped group. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, current format version, optional compatible versions, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `deleteRecords`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are opaque strings in the `single` layout and match `[a-zA-Z0-9_-]+` path segments in the `per-record` layout. A unit does not serialize concurrent writes — ordering belongs to the caller — whole-document and row-store calls are atomic on the medium, while a per-record batch interrupted before resolution can be partially applied. Resolved writes are durable; per-record deletions sync directory changes on POSIX. `deleteRecords` applies a whole batch in one call: it resolves once every listed record is absent from the readable state and the backend accepted the batch, and a rejection normally leaves the batch unapplied; a backend that cannot establish or restore the batch's state rejects with `unknown-state`, after which every later operation on that unit rejects with the same error until `close()` releases it (calls after close reject `closed`). A `single`-layout failure after the atomic replacement (a directory-fsync error) can leave the new file on the medium while the caller sees a rejection; close the backend and its domains, then reopen to inspect saved state before retrying. A `single` medium stamped outside the current and declared compatible versions rejects `version-mismatch`; a `per-record` document stamped outside the accepted set reads as absent. A medium that cannot be parsed as the unit rejects `malformed-medium`. [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) checks the shared clauses against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores one document per row in one database for frequently updated data. ## Declaring a domain @@ -58,20 +58,20 @@ interface DomainSpec { /** Current domain format version; reads enforce it according to the selected layout. */ readonly version: number /** - * Medium layout for the backend unit: `single` (the default) stores the + * Document layout for the backend unit: `single` (the default) stores the * whole unit as one document; `per-record` stores each record as its own * document, for units whose records are large, sparse, or individually - * disposable — the projection cache — and scopes version checks per record - * (an unaccepted record document is discarded, never migrated). + * disposable — the projection cache — with per-record version checks. + * Row stores retain unit-wide versioning for either layout request. */ readonly layout?: 'single' | 'per-record' /** * Older domain versions whose stored records the current record schemas * also accept (the declaring owner vouches for that, typically by - * declaring the fields older records lack as optional). `per-record` backends - * read documents stamped with a listed version instead of discarding them, - * and accept a legacy whole-unit file so stamped for the one-time - * bootstrap; writes always stamp {@link version}. + * declaring the fields older records lack as optional). Ordinary reads admit + * listed versions without restamping saved data; writes stamp {@link version} + * while leaving untouched records as saved. Current schemas must therefore + * accept mixed generations even under the current unit stamp. */ readonly compatibleVersions?: readonly number[] /** @@ -94,6 +94,23 @@ interface DomainSpec { `defineDomain(spec)` pins the spec's literal types and fails loud at the owner's module load, before any medium is touched: a domain or table name outside `UNIT_NAME_RE`, a version that is not a non-negative integer, or a global schema that accepts `null` all throw (`null` is the medium's "never written" sentinel, so a stored nullable global could not round-trip). `domainTable(schema)` declares one table with a phantom compile-time key type (typically a [branded id](core.md#branded-ids)); `descriptorOf(spec)` projects the backend-facing unit descriptor. + +## Domain versioning + +`version` names the current read/write format. `compatibleVersions` lists older versions whose records and global value the owner can decode with its current schemas; only nonnegative integers below `version` are allowed. Without that declaration, reads stay exact-version. Acceptance does not weaken record validation or permit a newer unknown version. Each row's saved fields must determine its meaning unambiguously; a unit stamp cannot distinguish different meanings of identical fields in mixed rows. + +Ordinary compatible opens and reads do not restamp or normalize saved values. Whole-unit JSON publishes the current stamp and changed data in one atomic file replacement; SQLite commits its first updated unit stamp and mutation in one transaction; batch deletes always use one transaction. Deleting missing records or an empty batch does not advance the stamp. The stamp identifies an accepted format, not completion of value normalization; readers must accept mixed generations. A backend with a unit-wide stamp rejects an unsupported unit version. + +Serialization failure before publication or successful SQLite rollback preserves the previous data and stamp. An I/O failure after JSON replacement, or a failure of SQLite rollback itself, can leave the saved outcome unknown despite rejection. Stop using and close the backend and its domains, then reopen to inspect saved state before deciding whether to retry. The backend READMEs define these failure cases. + +JSON's `per-record` layout checks and stamps each document independently; an unsupported document reads as absent. Its existing whole-unit bootstrap is an exception to read-only loading: it copies accepted historical values into current-stamped documents without converting them. An existing declared table directory, even when empty, or a declared global document suppresses bootstrap. SQLite retains unit-wide version checks regardless of the layout request. See the [JSON backend](../../packages/storage/storage-json/README.md) and [SQLite backend](../../packages/storage/storage-sqlite/README.md) for layout and recovery behavior. + +For a compatible successor, bump `version`, keep all still-readable stamps in `compatibleVersions`, and extend the same schema's decoding/defaults. Consumers normalize values when rewriting selected records; Storage does not assign application record versions. Verify historical and skipped upgrades, mixed values, reads without writes, failure rollback, restart, other-unit isolation, and unknown-version refusal. Table removal and layout changes require their own retention and upgrade policy; a compatible stamp alone does not define either. + +A v2 unit may contain untouched v1 values. A v3 reader accepting stamp 2 must still decode those values; accepting stamp 1 is also necessary for users who skipped v2 entirely. Removing old decoding requires rewriting and validating every affected record, including those already under a current unit stamp. An incompatible change needs an explicit, recoverable upgrade before opening with the new schema; the storage domain has no value-migration runner. + +Keep a consistent backup before writing a new format if return to an older reader is required: that reader can refuse the new stamp after the first mutation. Lowering a saved stamp by hand does not reverse value conversion. Domain compatibility does not migrate SQLite's physical schema or JSON envelope formats, and changing a backend route does not transfer stored data. Session-format migrations and SQLite physical-layout versioning have separate owners and do not migrate domain values. + ## The open domain ```ts type-equiv @@ -123,7 +140,7 @@ interface Domain { } ``` -Reads are synchronous from authoritative in-memory state: `KvTable` exposes `get`/`entries`/`keys`/`size` (snapshot iterators that stay stable while queued writes land), and the global handle's `get()` serves the spec's `initial` until the first `set` materializes the slot on the medium. Every write — `put`, `delete`, `deleteMany`, `update`, `global.set` — queues on one per-domain chain and reaches backend durability first, then mutates memory, then emits `domain/changed`; a rejected backend write leaves memory untouched, so reads never diverge from the medium; a backend that reports `unknown-state` instead quarantines the domain, and its reads and later writes reject until `close()` releases it. `update(key, fn)` is an atomic read-modify-write at its chain slot (a missing key rejects `missing-key`); `delete` of an absent key resolves `false` with no write and no event. `deleteMany(keys)` removes the present keys as one backend batch in one chain slot, resolves the removed count, and emits one `domain/changed` per removed key; a rejected backend write leaves every record in place and emits nothing; an `unknown-state` rejection quarantines the domain. Returned records are the stored objects themselves, not copies — replace via `put`/`update`, never mutate in place. +Reads are synchronous from authoritative in-memory state: `KvTable` exposes `get`/`entries`/`keys`/`size` (snapshot iterators that stay stable while queued writes land), and the global handle's `get()` serves the spec's `initial` until the first `set` materializes the slot on the medium. Every write — `put`, `delete`, `deleteMany`, `update`, `global.set` — queues on one per-domain chain and reaches backend durability first, then mutates memory, then emits `domain/changed`; a rejected backend write does not publish a domain change; an unknown durable outcome requires reopening before further use of that snapshot; a backend that reports `unknown-state` instead quarantines the domain, and its reads and later writes reject until `close()` releases it. `update(key, fn)` is an atomic read-modify-write at its chain slot (a missing key rejects `missing-key`); `delete` of an absent key resolves `false` with no write and no event. `deleteMany(keys)` removes the present keys as one backend batch in one chain slot, resolves the removed count, and emits one `domain/changed` per removed key; a rejected backend write leaves every record in place and emits nothing; an `unknown-state` rejection quarantines the domain. Returned records are the stored objects themselves, not copies — replace via `put`/`update`, never mutate in place. ## The domain facility: `ctx.storageDomain` diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md index 7411fa632b..7c44b1cc98 100644 --- a/docs/subsystems/storage.zh.md +++ b/docs/subsystems/storage.zh.md @@ -44,7 +44,7 @@ interface StorageBackend { } ``` -一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并提供可选的操作组；`kv` 是唯一已交付的操作组。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、当前格式版本、可选的兼容记录版本、表名清单，以及是否存在全局单例 slot——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`deleteRecords`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键在 `single` 布局中是不透明字符串，在 `per-record` 布局中则是匹配 `[a-zA-Z0-9_-]+` 的路径片段。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的；单记录写入与整文件发布在 resolve 后即已持久，`per-record` 批量删除则依赖文件系统对目录项更新的持久化。`deleteRecords` 以一次调用应用整批删除：所有列出的记录都从可读状态消失且后端接受该批后才 resolve，拒绝时通常整批未应用；无法建立或恢复批次状态的批量删除会以 `unknown-state` 拒绝，之后该 unit 的所有操作都以同一错误拒绝，直到 `close()` 释放它（关闭后的调用以 `closed` 拒绝）。`single` 布局在原子替换之后失败（目录 fsync 错误）时，新文件可能已落在介质上而调用方看到拒绝；unit 的内存保持一致，下一次发布会重写该文件。`single` 介质上记录的版本不同时拒绝 `version-mismatch`；`per-record` 文档的版本在接受集合之外时读作不存在。无法按该 unit 解析的介质拒绝 `malformed-medium`。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件会针对每个后端检查共享条款。[json 后端](../../packages/storage/storage-json/README.zh.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.zh.md)在单个数据库中每行存储一份文档，用于频繁更新的数据。 +一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并提供可选的操作组；`kv` 是唯一已交付的操作组。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、当前格式版本、可选的兼容版本、表名清单，以及是否存在全局单例 slot——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`deleteRecords`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键在 `single` 布局中是不透明字符串，在 `per-record` 布局中则是匹配 `[a-zA-Z0-9_-]+` 的路径片段。unit 不对并发写入做串行化——顺序由调用方负责——整文档与行存储调用在介质上是原子的，而逐记录批次在完成前中断时可能只应用一部分。写入完成后即已持久化；逐记录删除会在 POSIX 上同步目录变更。`deleteRecords` 以一次调用应用整批删除：所有列出的记录都从可读状态消失且后端接受该批后才 resolve，拒绝时通常整批未应用；无法建立或恢复批次状态的批量删除会以 `unknown-state` 拒绝，之后该 unit 的所有操作都以同一错误拒绝，直到 `close()` 释放它（关闭后的调用以 `closed` 拒绝）。`single` 布局在原子替换之后失败（目录 fsync 错误）时，新文件可能已落在介质上而调用方看到拒绝；必须关闭后端及其领域，再重新打开以检查已存状态，然后决定是否重试。`single` 介质上的版本不在当前版本和已声明兼容版本内时拒绝 `version-mismatch`；`per-record` 文档的版本在接受集合之外时读作不存在。无法按该 unit 解析的介质拒绝 `malformed-medium`。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件会针对每个后端检查共享条款。[json 后端](../../packages/storage/storage-json/README.zh.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.zh.md)在单个数据库中每行存储一份文档，用于频繁更新的数据。 ## 声明领域 @@ -58,20 +58,20 @@ interface DomainSpec { /** Current domain format version; reads enforce it according to the selected layout. */ readonly version: number /** - * Medium layout for the backend unit: `single` (the default) stores the + * Document layout for the backend unit: `single` (the default) stores the * whole unit as one document; `per-record` stores each record as its own * document, for units whose records are large, sparse, or individually - * disposable — the projection cache — and scopes version checks per record - * (an unaccepted record document is discarded, never migrated). + * disposable — the projection cache — with per-record version checks. + * Row stores retain unit-wide versioning for either layout request. */ readonly layout?: 'single' | 'per-record' /** * Older domain versions whose stored records the current record schemas * also accept (the declaring owner vouches for that, typically by - * declaring the fields older records lack as optional). `per-record` backends - * read documents stamped with a listed version instead of discarding them, - * and accept a legacy whole-unit file so stamped for the one-time - * bootstrap; writes always stamp {@link version}. + * declaring the fields older records lack as optional). Ordinary reads admit + * listed versions without restamping saved data; writes stamp {@link version} + * while leaving untouched records as saved. Current schemas must therefore + * accept mixed generations even under the current unit stamp. */ readonly compatibleVersions?: readonly number[] /** @@ -94,6 +94,23 @@ interface DomainSpec { `defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就明确报错：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable(schema)` 声明一张表，其键类型是仅存在于编译期的 phantom 类型（通常是[品牌化 id](core.zh.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。 + +## 领域版本 + +`version` 表示当前读写格式。`compatibleVersions` 列出拥有方可用当前 schema 解码其记录和全局值的旧版本；只允许小于 `version` 的非负整数。不声明兼容版本时，读取仍要求精确版本。接受旧版本不放宽记录校验，也不允许更新的未知版本。每行已存字段必须能无歧义地确定其含义；单元版本戳无法在混合行中区分相同字段的不同含义。 + +普通兼容打开和读取不会重新盖戳或规范化已存值。整单元 JSON 用一次原子文件替换发布当前版本戳和修改后的数据；SQLite 将首次单元版本更新与修改放在同一事务中提交；批量删除始终使用一个事务。删除不存在的记录或空批次不会推进版本戳。版本戳标识可接受格式，不代表值规范化已经完成；读取器必须接受混合代际。采用单元级版本戳的后端会拒绝不支持的单元版本。 + +发布前的序列化失败或成功的 SQLite 回滚会保留原有数据与版本戳。JSON 替换后的 I/O 失败或 SQLite 回滚本身失败时，即使操作被拒绝，已存结果也可能未知。必须停止使用并关闭后端及其领域，然后重新打开检查已存状态，再决定是否重试。各后端 README 定义了这些失败情况。 + +JSON 的 `per-record` 布局独立检查和标记每份文档；不支持的文档读取为缺失。其已有整单元引导是只读加载的例外：它将接受的历史值复制到当前版本文档中，不转换其中的值。已有的已声明表目录（即使为空）或已声明全局文档会禁止引导。SQLite 无论布局请求为何都保持单元级版本检查。布局与恢复行为见 [JSON 后端](../../packages/storage/storage-json/README.zh.md)和 [SQLite 后端](../../packages/storage/storage-sqlite/README.zh.md)。 + +兼容后继版本需提升 `version`、在 `compatibleVersions` 中保留仍可读的版本戳，并扩展同一 schema 的解码和默认规则。消费者在重写选定记录时规范化值；Storage 不分配应用记录版本。验证历史版本与跨版本升级、混合值、不写入的读取、失败回滚、重启、其他单元隔离和未知版本拒绝。删表与布局变更各自需要保留及升级策略；兼容版本戳本身不定义这些策略。 + +v2 单元可能包含未改动的 v1 值。接受版本戳 2 的 v3 读取器仍须解码这些值；对于跳过 v2 的用户，还必须接受版本戳 1。移除旧解码逻辑前必须重写并验证全部受影响记录，包括已处于当前单元版本戳下的记录。不兼容变更需要在用新 schema 打开前执行明确且可恢复的升级；存储领域没有值迁移执行器。 + +如果需要回到旧读取器，必须在写入新格式前保留一致的备份：首次修改后，旧读取器可能拒绝新的版本戳。手工降低已存版本戳不会逆转值转换。领域兼容性不迁移 SQLite 物理 schema 或 JSON 外层格式，更改后端路由也不会转移已存数据。Session 格式迁移与 SQLite 物理布局版本各有拥有方，不迁移领域值。 + ## 打开的领域 ```ts type-equiv @@ -123,7 +140,7 @@ interface Domain { } ``` -读取是同步的，来自权威的内存态：`KvTable` 暴露 `get`/`entries`/`keys`/`size`（快照迭代器，在排队写入落地期间保持稳定），global 句柄的 `get()` 在第一次 `set` 将 slot 物化到介质之前一直返回 spec 的 `initial`。每次写入——`put`、`delete`、`deleteMany`、`update`、`global.set`——都在同一条逐领域写链上排队，先在后端完成持久化，再更新内存，最后发出 `domain/changed`；后端写入被拒时内存原样不动，因此读取绝不会偏离介质；若后端报告 `unknown-state`，领域会被隔离，读取与后续写入都会拒绝，直到 `close()` 释放它。`update(key, fn)` 在其写链 slot 上是一次原子的读-改-写（键缺失时拒绝 `missing-key`）；`delete` 一个不存在的键 resolve 为 `false`，不产生写入也不产生事件。`deleteMany(keys)` 在一个写链 slot 内把存在的键作为一次后端批量删除移除，resolve 为移除数量，并为每个被移除的键发一次 `domain/changed`；后端写入被拒时所有记录保持原样，也不发事件；`unknown-state` 拒绝会隔离整个领域。返回的记录就是存储的对象本身，不是副本——请经 `put`/`update` 整体替换，绝不要就地修改。 +读取是同步的，来自权威的内存态：`KvTable` 暴露 `get`/`entries`/`keys`/`size`（快照迭代器，在排队写入落地期间保持稳定），global 句柄的 `get()` 在第一次 `set` 将 slot 物化到介质之前一直返回 spec 的 `initial`。每次写入——`put`、`delete`、`deleteMany`、`update`、`global.set`——都在同一条逐领域写链上排队，先在后端完成持久化，再更新内存，最后发出 `domain/changed`；后端写入被拒时不会发布领域变更；持久化结果未知时必须重新打开后才能继续使用该快照；若后端报告 `unknown-state`，领域会被隔离，读取与后续写入都会拒绝，直到 `close()` 释放它。`update(key, fn)` 在其写链 slot 上是一次原子的读-改-写（键缺失时拒绝 `missing-key`）；`delete` 一个不存在的键 resolve 为 `false`，不产生写入也不产生事件。`deleteMany(keys)` 在一个写链 slot 内把存在的键作为一次后端批量删除移除，resolve 为移除数量，并为每个被移除的键发一次 `domain/changed`；后端写入被拒时所有记录保持原样，也不发事件；`unknown-state` 拒绝会隔离整个领域。返回的记录就是存储的对象本身，不是副本——请经 `put`/`update` 整体替换，绝不要就地修改。 ## 领域 facility：`ctx.storageDomain` diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md index 9838c8c82d..1fe31a9918 100644 --- a/docs/subsystems/typert.md +++ b/docs/subsystems/typert.md @@ -444,6 +444,8 @@ interface TypertGateway { * @returns whether an owner stream is open and has not been cancelled. */ hasLiveClient(): boolean + /** @returns detached metadata for all unsettled forwarded events in arrival order. */ + getPendingRemoteEvents(): readonly PendingRemoteEventInfo[] /** * Register the application-selected forwarded-event source. * @param source - stream factory installed by the Remote assembly. @@ -664,6 +666,12 @@ Resolve strict generated definitions or conservative SRC markers against current */ hasLiveClient(): boolean +/** + * Inspect unsettled forwarded events without changing their lifetime. + * @returns detached event names and Agent identities. + */ +getPendingRemoteEvents(): readonly PendingRemoteEventInfo[] + /** * Register the sole application-selected forwarded-event source. * @param source - stream factory installed by the Remote assembly. diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md index 2cbdaf4a2c..840825979e 100644 --- a/docs/subsystems/typert.zh.md +++ b/docs/subsystems/typert.zh.md @@ -444,6 +444,8 @@ interface TypertGateway { * @returns whether an owner stream is open and has not been cancelled. */ hasLiveClient(): boolean + /** @returns detached metadata for all unsettled forwarded events in arrival order. */ + getPendingRemoteEvents(): readonly PendingRemoteEventInfo[] /** * Register the application-selected forwarded-event source. * @param source - stream factory installed by the Remote assembly. @@ -664,6 +666,12 @@ Resolve strict generated definitions or conservative SRC markers against current */ hasLiveClient(): boolean +/** + * Inspect unsettled forwarded events without changing their lifetime. + * @returns detached event names and Agent identities. + */ +getPendingRemoteEvents(): readonly PendingRemoteEventInfo[] + /** * Register the sole application-selected forwarded-event source. * @param source - stream factory installed by the Remote assembly. diff --git a/docs/subsystems/worktrees.i18n.yaml b/docs/subsystems/worktrees.i18n.yaml index 03544fbc81..f771dd3cf2 100644 --- a/docs/subsystems/worktrees.i18n.yaml +++ b/docs/subsystems/worktrees.i18n.yaml @@ -9,5 +9,5 @@ en: 53f643c5d30e00b2 zh: ba9e52efc62c7656 /git-worktrees/request-and-result: - en: 8391b091607600eb - zh: 6c735a337d60d566 + en: fbab866bf824d6e0 + zh: 73d2a1ee350e1434 diff --git a/docs/subsystems/worktrees.md b/docs/subsystems/worktrees.md index 14db6711bc..8d4fec853a 100644 --- a/docs/subsystems/worktrees.md +++ b/docs/subsystems/worktrees.md @@ -14,7 +14,7 @@ Leaving through `working_directory({ cd: path })` retains the checkout and branc ## Request and result -The request selects only the new name and local revision. The result identifies the created checkout and exact commit; it does not change the Session's original project or write permissions. +The request selects only the new name and local revision. The result identifies the created checkout and exact commit; it does not change the Session's original project or write permissions. An optional callback receives each stage of the creation before it begins. A restoration checks a removed checkout out again at its recorded directory, from its branch or, when the branch is gone, from its base commit. ```ts type-equiv /** A new checkout from a locally available Git commit, branch, or tag. */ @@ -40,6 +40,40 @@ interface CreatedWorktree { } ``` +```ts type-equiv +/** + * Stage of one creation or restoration, reported before it begins: `prepare` + * validates the request, allocates the checkout directory, and creates the + * branch, which a restoration creates again only when it is gone; `checkout` + * writes the files and, for a creation, enters the checkout. + */ +type CreateWorktreePhase = 'prepare' | 'checkout' +``` + +```ts type-equiv +/** A removed checkout to check out again at its recorded directory. */ +interface RestoreWorktreeRequest { + /** Canonical checkout directory the worktree had. */ + path: string + /** Branch the worktree had checked out. */ + branch: string + /** Commit the branch started from; a branch that no longer exists is created again here. */ + baseCommit: string + /** Canonical root of the source checkout. */ + repositoryRoot: string +} +``` + +```ts type-equiv +/** Outcome of one restoration. */ +interface RestoredWorktree { + /** Checkout directory, present again. */ + path: string + /** Whether the branch no longer existed and was created again at the base commit, without the commits it had gained. */ + branchRecreated: boolean +} +``` + @@ -65,9 +99,26 @@ Creates retained Git worktrees under the mounted filesystem and sandbox provider * @param agent - caller whose current directory selects the source repository and file policy. * @param request - optional new name and local revision; defaults are generated name and HEAD. * @param signal - cancellation of lookup, creation, and working-directory publication. + * @param onPhase - receives each stage before it begins; it must not throw. * @returns canonical checkout path, branch name, pinned commit, and source repository root. */ -async create(agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal): Promise +async create( agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise + +/** + * Check out a removed worktree again at its recorded directory: its branch + * when the branch still exists, otherwise a new branch of the same name at + * `baseCommit`. Only the missing target's unlocked registration is removed, and an + * existing directory fails. Changes that were never committed are not + * recovered. Checkout disables configured clean, smudge, and process filters, + * as creation does. The calling Session's working directory does not change. + * Failures may retain newly allocated Git/filesystem artifacts. + * @param agent - caller whose sandbox policy confines the commands. + * @param request - recorded directory, branch, base commit, and source repository root. + * @param signal - cancellation of the restoration. + * @param onPhase - receives each stage before it begins; it must not throw. + * @returns the directory and whether the branch was created again. + */ +async restore( agent: Agent, request: RestoreWorktreeRequest, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise ``` Types: [Agent](core.md) diff --git a/docs/subsystems/worktrees.zh.md b/docs/subsystems/worktrees.zh.md index 719d99266b..e6a7c71ecc 100644 --- a/docs/subsystems/worktrees.zh.md +++ b/docs/subsystems/worktrees.zh.md @@ -14,7 +14,7 @@ ## 请求与结果 -请求只选择新名称与本地版本。结果标识创建的检出目录与确切提交；它不会改变 Session 的原始项目或写权限。 +请求只选择新名称与本地版本。结果标识创建的检出目录与确切提交；它不会改变 Session 的原始项目或写权限。可选的回调会在创建的每个阶段开始之前收到该阶段。恢复会在记录的目录重新检出已删除的检出目录：从它的分支检出；分支也已删除时，从它的基准提交检出。 ```ts type-equiv /** A new checkout from a locally available Git commit, branch, or tag. */ @@ -40,6 +40,40 @@ interface CreatedWorktree { } ``` +```ts type-equiv +/** + * Stage of one creation or restoration, reported before it begins: `prepare` + * validates the request, allocates the checkout directory, and creates the + * branch, which a restoration creates again only when it is gone; `checkout` + * writes the files and, for a creation, enters the checkout. + */ +type CreateWorktreePhase = 'prepare' | 'checkout' +``` + +```ts type-equiv +/** A removed checkout to check out again at its recorded directory. */ +interface RestoreWorktreeRequest { + /** Canonical checkout directory the worktree had. */ + path: string + /** Branch the worktree had checked out. */ + branch: string + /** Commit the branch started from; a branch that no longer exists is created again here. */ + baseCommit: string + /** Canonical root of the source checkout. */ + repositoryRoot: string +} +``` + +```ts type-equiv +/** Outcome of one restoration. */ +interface RestoredWorktree { + /** Checkout directory, present again. */ + path: string + /** Whether the branch no longer existed and was created again at the base commit, without the commits it had gained. */ + branchRecreated: boolean +} +``` + @@ -65,9 +99,26 @@ Creates retained Git worktrees under the mounted filesystem and sandbox provider * @param agent - caller whose current directory selects the source repository and file policy. * @param request - optional new name and local revision; defaults are generated name and HEAD. * @param signal - cancellation of lookup, creation, and working-directory publication. + * @param onPhase - receives each stage before it begins; it must not throw. * @returns canonical checkout path, branch name, pinned commit, and source repository root. */ -async create(agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal): Promise +async create( agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise + +/** + * Check out a removed worktree again at its recorded directory: its branch + * when the branch still exists, otherwise a new branch of the same name at + * `baseCommit`. Only the missing target's unlocked registration is removed, and an + * existing directory fails. Changes that were never committed are not + * recovered. Checkout disables configured clean, smudge, and process filters, + * as creation does. The calling Session's working directory does not change. + * Failures may retain newly allocated Git/filesystem artifacts. + * @param agent - caller whose sandbox policy confines the commands. + * @param request - recorded directory, branch, base commit, and source repository root. + * @param signal - cancellation of the restoration. + * @param onPhase - receives each stage before it begins; it must not throw. + * @returns the directory and whether the branch was created again. + */ +async restore( agent: Agent, request: RestoreWorktreeRequest, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise ``` Types: [Agent](core.zh.md) diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml index 0d5f2cf988..dd57937dc5 100644 --- a/docs/tool-catalog.i18n.yaml +++ b/docs/tool-catalog.i18n.yaml @@ -306,8 +306,8 @@ en: d5f5679abe86e316 zh: d5f5679abe86e316 /tool-schema-catalog/deepseek-ai-dsh-experimental-tool-worktree/create-worktree: - en: 3cf89e31f011ae9b - zh: 28e78b4fae2d075b + en: d8fe3c566ba2147c + zh: baf372cb9242670c /tool-schema-catalog/deepseek-ai-dsh-tool-workflow: en: bb38a9d29f46563c zh: bb38a9d29f46563c diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 5c2af1efa9..050443647b 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -2628,7 +2628,7 @@ Reads or changes the calling Session directory. Existing shells and processes re ### `create_worktree` -Create a new Git branch and worktree from a local commit, branch, or tag, then change this session's working directory to it. Defaults to HEAD and a generated name. Uncommitted files stay in the source checkout. Existing names fail. Use working_directory with cd to leave; the checkout and branch remain. +Create a new Git branch and worktree from a local commit, branch, or tag, then change this session's working directory to it. Uncommitted files stay in the source checkout. Existing names fail. Use working_directory with cd to leave; the checkout and branch remain. ```json { @@ -2636,7 +2636,7 @@ Create a new Git branch and worktree from a local commit, branch, or tag, then c "properties": { "name": { "type": "string", - "description": "New branch name, also used as the checkout directory. Omit to generate a unique name." + "description": "New branch name, also used as the checkout directory: a few lowercase words joined by hyphens that describe the task, such as fix-login-retry. Omit to generate a unique name." }, "from": { "type": "string", diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md index 35765318e9..bc40f3b788 100644 --- a/docs/tool-catalog.zh.md +++ b/docs/tool-catalog.zh.md @@ -2634,7 +2634,7 @@ todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为 ### `create_worktree` -从本地提交、分支或标签创建新的 Git 分支与工作树，再将本 Session 的工作目录切换到该位置。默认使用 HEAD 和自动生成的名称。未提交文件保留在源检出目录中。名称已存在时失败。使用 working_directory 的 cd 参数离开；检出目录与分支仍然保留。 +从本地提交、分支或标签创建新的 Git 分支与工作树，再将本 Session 的工作目录切换到该位置。未提交文件保留在源检出目录中。名称已存在时失败。使用 working_directory 的 cd 参数离开；检出目录与分支仍然保留。 ```json { @@ -2642,7 +2642,7 @@ todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为 "properties": { "name": { "type": "string", - "description": "New branch name, also used as the checkout directory. Omit to generate a unique name." + "description": "New branch name, also used as the checkout directory: a few lowercase words joined by hyphens that describe the task, such as fix-login-retry. Omit to generate a unique name." }, "from": { "type": "string", diff --git a/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.i18n.yaml new file mode 100644 index 0000000000..8249edf3c4 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md +/: + en: b0a44570cee3ac45 + zh: f68438befed14c6e +/context-menu-services-in-custom-client-compositions: + en: b2018bf0250be579 + zh: 1d8a243d09f4128f +/context-menu-services-in-custom-client-compositions/change: + en: 3eaef415166d076f + zh: 4040390d2572fc47 +/context-menu-services-in-custom-client-compositions/migration: + en: ebffe957534ac31b + zh: a33d2782f5ad0f5d diff --git a/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md b/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md new file mode 100644 index 0000000000..082e1da33f --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md @@ -0,0 +1,23 @@ +--- +kind: upgrade-guide +description: "Custom Client compositions must provide the context-menu and file-action services required by GUI plugins." +--- + +# Context menu services in custom Client compositions + +English | [中文](guide.zh.md) + +## Change + +GUI plugins now inject `contextMenus` to open shared object menus. The open-in-app plugin also injects `fileActions`, `sidebarRight`, `sidebarRightTabs`, and `remote.workspaceFiles`. Custom compositions that mount these GUI plugins without the new services cannot activate them. The shipped Web application bundle includes the providers; existing Session and tab menu Slot names remain available. + +## Migration + +1. In the package manifest that owns a custom composition, add dependencies on `@deepseek-ai/dsh-client-ui-context-menu` and `@deepseek-ai/dsh-client-ui-file-actions` at the same Harness version. +2. Add both package names as plugin rows in the custom Client composition alongside the existing locale, slots, shortcuts, sidebar, and workspace-file providers. The default `@deepseek-ai/dsh-web-app` bundle already contains these rows. +3. Rename `ctx.menus` to `ctx.contextMenus` and `MenuTargetMap` to `ContextMenuTargetMap`; neither old name has an alias. Mount the menu plugin so its `ctx.slots.provideRoot` contribution supplies `useContextMenu` to every Slot. Components call the hook once and spread `getTriggerProps(target, handlers?)` onto each element, including elements created in loops. See the [menu reference](../../../../packages/client/ui-context-menu/README.md) for handler composition and external action registration. +4. Rebuild and launch the custom profile. Confirm that GUI plugins activate, right-clicking a background Session preserves selection, and existing Session/tab Slot contributions still appear. +5. Custom Slot hosts must remove their declarations of `sidebar.workspaces.session.menu.item` and `sidebar.right.tab.menu.item`; the workspace and right-sidebar adapters now own these under `contextMenu.content`. Session rows retain the `[open, setOpen]` hook context, and tab rows receive `{ tab, dismiss }` within the clicked Session’s provider. A custom host replacing these adapters must declare the same children and supply those owners itself. Dockkit embedders using `getTabTriggerProps` own the popup and dismissal; `renderTabMenuItems` is used only by the kit popup. Supply reactive `tabMenuOpen` to suppress close-button tooltips while a custom menu prepares or remains open. + +6. Built-in Session menu items are data contributions. The legacy React Slot retains external entries together before Archive; Slot priority no longer shadows built-in actions. Use `ctx.contextMenus.register` for new actions and optional `commandId` to display an existing command’s current binding. Keep captured-target execution in `run`; no command dispatch is added. +7. Menu contributions use `icon?: ReactNode`; replace `symbol` with a glyph element and wrap icon URLs in ``. Obtain `useContextMenu` at each actual Slot entry. Plain children receive `getTriggerProps` or bound `contextMenuProps`; ToolRow uses `fileContextMenuProps` and `urlContextMenuProps`. Remove menu fields from Chat flow/node owners. The assistant entry supplies an ordinary file adapter to `forClosing()`, while Markdown adapts its target type at `MarkdownDelegateProvider.getTriggerProps`. Keep Session identity and gesture-time path resolution in the business registration. Remove imports of `contextMenuTrigger` and `menuPoint`; their independent utility package is removed. Do not add gesture exports to ui-primitives. diff --git a/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.zh.md new file mode 100644 index 0000000000..9281f9bee1 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.zh.md @@ -0,0 +1,23 @@ +--- +kind: upgrade-guide +description: "自定义 Client 组合必须提供 GUI 插件所需的右键菜单与文件动作服务。" +--- + +# 自定义 Client 组合中的右键菜单服务 + +[English](guide.md) | 中文 + +## 变更 + +GUI 插件现在注入 `contextMenus` 以打开共享对象菜单。open-in-app 插件还注入 `fileActions`、`sidebarRight`、`sidebarRightTabs` 和 `remote.workspaceFiles`。自定义组合若挂载这些 GUI 插件却没有新服务，将无法激活它们。随附 Web 应用 bundle（插件包）已包含提供方；现有 Session 和标签页菜单 Slot 名称仍可使用。 + +## 迁移 + +1. 在自定义组合所属的包清单中，添加与 Harness 版本一致的 `@deepseek-ai/dsh-client-ui-context-menu` 和 `@deepseek-ai/dsh-client-ui-file-actions` 依赖。 +2. 在自定义 Client 组合中将两个包名添加为插件行，与已有 locale、slots、shortcuts、侧栏和工作区文件提供方并列。默认 `@deepseek-ai/dsh-web-app` bundle 已包含这些行。 +3. 将 `ctx.menus` 改为 `ctx.contextMenus`，将 `MenuTargetMap` 改为 `ContextMenuTargetMap`，旧名均无兼容别名。挂载菜单插件，由其 `ctx.slots.provideRoot` 贡献向每个 Slot 提供 `useContextMenu`。组件调用一次 hook，将 `getTriggerProps(target, handlers?)` 展开到每个元素，包括循环生成的元素。处理器组合和外部动作注册见[菜单参考](../../../../packages/client/ui-context-menu/README.zh.md)。 +4. 重新构建并启动自定义 profile（配置档）。确认 GUI 插件正常激活、右键后台 Session 不改变选择，且现有 Session/标签页 Slot 贡献仍然显示。 +5. 自定义 Slot 宿主应移除对 `sidebar.workspaces.session.menu.item` 和 `sidebar.right.tab.menu.item` 的声明；现在由工作区和右侧栏适配器在 `contextMenu.content` 下拥有它们。会话行继续接收 `[open, setOpen]` hook context，标签行在所点击会话的 provider 内接收 `{ tab, dismiss }`。替换这些适配器的自定义宿主须自行声明相同的子 Slot 并提供这些 owner。使用 `getTabTriggerProps` 的 Dockkit 嵌入方负责弹窗和关闭，`renderTabMenuItems` 仅供组件自身的弹窗使用。通过响应式 `tabMenuOpen` 在自定义菜单准备或显示时禁用关闭按钮的 Tooltip。 + +6. 内置 Session 菜单项改为数据贡献。旧 React Slot 将外部条目集中显示在归档之前，Slot priority 不再覆盖内置动作。新增动作用 `ctx.contextMenus.register`，可通过 `commandId` 展示已有命令的当前绑定。针对捕获目标的执行仍放在 `run`，不增加命令调度。 +7. 菜单贡献使用 `icon?: ReactNode`：将 `symbol` 改为图标元素，并用 `` 包装图标 URL。在每个实际 Slot 入口获取 `useContextMenu`。普通子组件接收 `getTriggerProps` 或绑定后的 `contextMenuProps`；ToolRow 使用 `fileContextMenuProps` 和 `urlContextMenuProps`。删除 Chat 消息流和节点 owner 的菜单字段。助手入口向 `forClosing()` 传入普通文件适配函数，Markdown 则在 `MarkdownDelegateProvider.getTriggerProps` 处适配目标类型。业务注册保留 Session 归属和触发时路径解析。删除 `contextMenuTrigger` 和 `menuPoint` 导入，其独立工具包已删除。不要向 ui-primitives 增加手势导出。 diff --git a/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.i18n.yaml new file mode 100644 index 0000000000..385596d866 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md +/: + en: 131777d89cb23df3 + zh: 44e50f8c09b2c4b9 +/computer-use-consent-storage: + en: fb837293708860f5 + zh: 8ee31126d1faf7c7 +/computer-use-consent-storage/change: + en: 88150a92531212bf + zh: a0103c4d035a4af7 +/computer-use-consent-storage/migration: + en: c7a4989a79f4fbca + zh: 630fc23128ee0520 diff --git a/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md b/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md new file mode 100644 index 0000000000..05a0bd4011 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md @@ -0,0 +1,22 @@ +--- +kind: upgrade-guide +description: "Computer Use application consent moves from profile configuration to durable profile-scoped storage." +--- + +# Computer Use consent storage + +English | [中文](guide.zh.md) + +## Change + +Computer Use stores application consent through `storageDomain`. With the default JSON backend, each canonical profile directory has its own `$DSH_HOME/storages/cua_permissions_.json`. “Allow for this session” now follows the conversation ID across DSH restart and Computer Use disablement. It does not authorize another conversation. Unverifiable applications still require a matching native process identity; restarting that application may require new consent. + +`allowedApps` is a legacy import source. The first store access imports it once. Subsequent configuration edits do not grant or revoke access, and a revoked grant is not restored by reloading the old configuration. The permission page remains the authoring interface for grants and refusals. macOS privileges are unchanged. + +## Migration + +1. Keep the profile's existing storage services mounted. Shipped profiles already include `storageDomain` and the JSON backend; custom profiles need the same services. A profile without domain storage refuses authorization operations. +2. Enable Computer Use and open its details to initialize storage. Confirm that the always-allowed applications appear. +3. Remove `allowedApps` from the CUA entry in the profile configuration and other overlays after confirmation. Keep the remaining CUA configuration. +4. Use the permission page to revoke applications or allow asking again. Existing conversation-only grants held by an older running process cannot be recovered; grant those once after upgrading. Newly granted conversation access then survives restart. +5. Keep the storage file with that profile's state. Moving the profile to a different real directory selects a different store. File locks coordinate processes on one machine, not different machines sharing a network filesystem. diff --git a/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.zh.md new file mode 100644 index 0000000000..fb9e8f39f3 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.zh.md @@ -0,0 +1,22 @@ +--- +kind: upgrade-guide +description: "Computer Use 应用授权从 profile 配置迁移到按 profile 隔离的持久存储。" +--- + +# Computer Use 授权存储 + +[English](guide.md) | 中文 + +## 变更 + +Computer Use 通过 `storageDomain` 保存应用授权。使用默认 JSON 后端时，每个 profile 的真实目录对应独立的 `$DSH_HOME/storages/cua_permissions_.json`。“本会话允许”现在按对话 ID 跨 DSH 重启和 Computer Use 启停保留，不授权其他对话。无法验证签名的应用仍需匹配本机进程身份，应用重启后可能需要重新授权。 + +`allowedApps` 作为旧数据来源，只在首次访问存储时导入一次。此后修改配置不会授予或撤销访问权限，重新加载旧配置也不会恢复已撤销的许可。权限页继续提供授权管理和清除拒绝的操作。macOS 系统权限保持原样。 + +## 迁移 + +1. 保留 profile 的现有存储服务。随附 profile 已包含 `storageDomain` 和 JSON 后端，自定义 profile 需要挂载相同服务。有 profile 但没有域存储时，授权操作会被拒绝。 +2. 启用 Computer Use 并打开详情页，初始化存储。确认始终允许的应用显示正确。 +3. 确认后，从 profile 配置及其他覆盖层的 CUA 条目中删除 `allowedApps`，保留其他 CUA 配置。 +4. 在权限页撤销应用授权或允许再次询问。旧进程内已有的会话许可无法恢复，升级后需要重新授予一次；新授予的会话许可随后可跨重启保留。 +5. 将存储文件作为该 profile 的状态保留。把 profile 移到另一个真实目录后会使用不同存储。文件锁协调同一电脑上的进程，不支持多台电脑共用网络文件系统。 diff --git a/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.i18n.yaml new file mode 100644 index 0000000000..fdea1cb921 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md +/: + en: e3db78299cefc568 + zh: 0c1892abef438638 +/the-ui-deepseek-model-label-1017-package-is-removed: + en: 772b7e3479b2e52b + zh: 9d7a225cf77c2664 +/the-ui-deepseek-model-label-1017-package-is-removed/change: + en: 48543e623bac7b47 + zh: a22640ced4b587fa +/the-ui-deepseek-model-label-1017-package-is-removed/migration: + en: 3e366a0f2daf220c + zh: 859d6bc103213809 diff --git a/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md b/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md new file mode 100644 index 0000000000..9511ee9834 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md @@ -0,0 +1,18 @@ +--- +kind: upgrade-guide +description: "The fixed 1017 model badge package is removed; model badges come from the DeepSeek model listing." +--- +# The `ui-deepseek-model-label-1017` package is removed + +English | [中文](guide.zh.md) + +## Change + +`@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` and its `ui-deepseek-model-label-1017` row in the Web bundle are removed, and the package receives no further releases. The composer model selector shows the badge that the DeepSeek `GET /models` listing declares for a model; without a declared badge, `DeepSeek-V4.1-Flash` shows no `1017`. A profile patch that disables or edits the removed row matches no entry, so boot warns that the entry is not found and skips the patch. + +## Migration + +1. Delete the patch whose `id` is `ui-deepseek-model-label-1017`, with its `disabled` or other fields, from `$DSH_HOME/profiles//cordis.patch.yml` and from any overlay passed with `--patch`. +2. Remove `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` from the dependencies of any package that lists it. +3. To change how model names or badges render, contribute to the `conversation.input.model.label` slot; its owner props carry the catalog `model.badge` ([label extensions](../../../../packages/client/ui-model-selection/README.md#use-this-package)). +4. Restart DSH and confirm that boot reports no missing `ui-deepseek-model-label-1017` entry. diff --git a/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.zh.md new file mode 100644 index 0000000000..6106f94486 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.zh.md @@ -0,0 +1,18 @@ +--- +kind: upgrade-guide +description: "固定的 1017 模型角标包已移除，模型角标改由 DeepSeek 模型列表下发。" +--- +# `ui-deepseek-model-label-1017` 包已移除 + +[English](guide.md) | 中文 + +## 变更 + +`@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` 及其在 Web bundle 中的 `ui-deepseek-model-label-1017` 条目已移除，该包不再发布新版本。composer 模型选择器显示 DeepSeek `GET /models` 列表为模型声明的角标；列表没有声明角标时，`DeepSeek-V4.1-Flash` 不再显示 `1017`。停用或修改该条目的 profile patch 不再匹配任何条目，启动时会警告找不到该条目并跳过这条 patch。 + +## 迁移 + +1. 从 `$DSH_HOME/profiles//cordis.patch.yml` 以及通过 `--patch` 传入的 overlay 中，删除 `id` 为 `ui-deepseek-model-label-1017` 的 patch，连同其中的 `disabled` 或其他字段。 +2. 若有包在依赖中列出 `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017`，将其删除。 +3. 如需改变模型名称或角标的显示方式，向 `conversation.input.model.label` slot 注册组件；其 owner props 携带目录中的 `model.badge`（[名称扩展](../../../../packages/client/ui-model-selection/README.zh.md#use-this-package)）。 +4. 重启 DSH，确认启动输出中没有找不到 `ui-deepseek-model-label-1017` 条目的警告。 diff --git a/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.i18n.yaml new file mode 100644 index 0000000000..97b26e625d --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md +/: + en: 2503e2027c918185 + zh: ffd1bf229fdfbb7d +/handle-script-programs-and-explicit-state-retention: + en: 484afb11caae52a3 + zh: e2c5e8a365845828 +/handle-script-programs-and-explicit-state-retention/change: + en: e8631aefd51606cd + zh: 39cffa3d535b903e +/handle-script-programs-and-explicit-state-retention/migration: + en: 2f9132751d5be30e + zh: c6bc98904eff22ce diff --git a/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md b/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md new file mode 100644 index 0000000000..25a4c77a18 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "PTC programFormat includes Script syntax, and consumers read retainsState for cross-call memory." +--- + +# Handle Script programs and explicit state retention + +English | [中文](guide.zh.md) + +## Change + +The published `@deepseek-ai/dsh-ptc-runtime` service widens `PtcRuntime.programFormat` from `'function-body' | 'repl'` to include `'script'`. External consumers that exhaustively match the old union must handle the new value. `retainsState` reports whether a provider preserves memory for a `stateOwner`; its base implementation returns `false`, so custom retained providers must override it. + +Node keeps `per-call` as its default. The opt-in `executionMode: vm-script` accepts Script statements and top-level await, with `scriptPersistence` selecting cross-call memory independently. Existing Node function-body and REPL configurations remain valid. + +## Migration + +1. Import the exported `PtcProgramFormat` from `@deepseek-ai/dsh-ptc-runtime` instead of copying its union literals. Update `programFormat` switches in custom tool or workflow adapters. Handle `'script'` using statements or a final expression, without top-level `return`; consult the [Node syntax reference](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#use-this-package). +2. Replace checks that infer memory retention from `programFormat === 'repl'` with `runtime.retainsState`. If a custom `PtcRuntime` provider retains owner-scoped memory, override `retainsState` to return `true` and continue implementing `release(owner)`. +3. Rebuild external consumers against the new package declarations. Confirm that each supported format compiles and that persistence controls follow `retainsState` for both REPL and Script providers. diff --git a/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.zh.md new file mode 100644 index 0000000000..e5f28af66a --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.zh.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "PTC programFormat 新增 Script 语法，消费者通过 retainsState 判断跨调用内存保留。" +--- + +# 处理 Script 程序与显式状态保留 + +[English](guide.md) | 中文 + +## 变更 + +已发布的 `@deepseek-ai/dsh-ptc-runtime` 服务将 `PtcRuntime.programFormat` 从 `'function-body' | 'repl'` 扩展为包含 `'script'`。对旧联合类型做穷举匹配的外部消费者必须处理新值。`retainsState` 表示提供方是否为 `stateOwner` 保留内存；基类实现返回 `false`，因此自定义保留状态的提供方必须覆盖该 getter。 + +Node 仍默认使用 `per-call`。显式启用的 `executionMode: vm-script` 接受 Script 语句和顶层 await，`scriptPersistence` 独立选择是否跨调用保留内存。已有 Node 函数体和 REPL 配置仍然有效。 + +## 迁移 + +1. 从 `@deepseek-ai/dsh-ptc-runtime` 导入已导出的 `PtcProgramFormat`，不复制其联合类型字面量。更新自定义工具或工作流适配器中的 `programFormat` 分支。使用语句或末尾表达式处理 `'script'`，不使用顶层 `return`；参见 [Node 语法参考](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#use-this-package)。 +2. 将通过 `programFormat === 'repl'` 推断内存保留的检查改为读取 `runtime.retainsState`。自定义 `PtcRuntime` 提供方若按所有者保留内存，应覆盖 `retainsState` 并返回 `true`，同时继续实现 `release(owner)`。 +3. 使用新的包声明重新构建外部消费者。确认所有支持的格式均可编译，并且持久化控制对 REPL 和 Script 提供方都按 `retainsState` 判断。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.i18n.yaml new file mode 100644 index 0000000000..efe907e2eb --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.md +/: + en: 1e002ad3fd9b1e79 + zh: aeba3ee1e74fa2ae +/image-read-requests-carry-the-complete-attachment-reference: + en: df690494e7cec0b8 + zh: e21d937f2f305d8e +/image-read-requests-carry-the-complete-attachment-reference/change: + en: cca17091c60b9757 + zh: 8f300ab9d0b870d8 +/image-read-requests-carry-the-complete-attachment-reference/migration: + en: b593e623619ea508 + zh: 41714f50a249f941 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.md new file mode 100644 index 0000000000..3aac18a52f --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.md @@ -0,0 +1,23 @@ +--- +kind: upgrade-guide +description: "Image read requests require a complete attachment reference and no longer check Session membership." +--- + +# Image read requests carry the complete attachment reference + +English | [中文](guide.zh.md) + +## Change + +In 0.2.1-rc.3, `session/attachment` accepted `{ sessionId, attachmentId }` and searched the requested Session's history for the complete image reference. It now requires `{ sessionId, attachment: ref }`, where `ref` is an `ImageAttachmentRef` containing `attachmentId`, `mediaType`, `bytes`, `width`, and `height`. The Client's `session.readAttachment()` also takes the complete reference instead of an ID. + +The Host passes this reference to the existing `AttachmentStore.readImage(ref)`. It verifies the ID, actual format, byte length, width, and height against the stored object. The response remains `{ attachment, data }`, with base64 bytes in `data`. It preserves the supplied reference, including optional `name` and `originalDimensions`; those two fields are caller-supplied display information and are not verified against the file. Missing, corrupt, and mismatched objects fail explicitly. + +Connection authentication and Gateway permission checks still apply. Any identity authorized to call the endpoint for the supplied `sessionId` may read an image in the same store, including one referenced only by another Session or by no Session. The handler does not check image membership or Session existence and no longer returns `session/not-found` for an absent Session after authorization. + +## Migration + +1. Update wire calls from `{ sessionId, attachmentId: ref.attachmentId }` to `{ sessionId, attachment: ref }`, using the complete reference from the message image block. Update Client calls from `session.readAttachment(ref.attachmentId)` to `session.readAttachment(ref)`. +2. Treat returned `name` and `originalDimensions` as the caller's display information. Only the ID, media type, byte length, width, and height are checked against the stored object. +3. If your deployment depends on Session membership to isolate images, run separate Host instances with separate `DSH_HOME` directories before upgrading. The shipped composition does not select separate stores by Session within one Host. Gateway permissions govern endpoint invocation, not the image's Session membership. +4. Confirm that an allowed request with a complete reference can read an image absent from the supplied Session, including when that Session does not exist. Denied Gateway requests, missing images, and references with mismatched intrinsic metadata must fail. Existing Session logs and stored images need no migration. diff --git a/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.zh.md new file mode 100644 index 0000000000..d4d3a2e2b6 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.zh.md @@ -0,0 +1,23 @@ +--- +kind: upgrade-guide +description: "图片读取请求必须携带完整附件引用，并且不再检查 Session 关联。" +--- + +# 图片读取请求需携带完整附件引用 + +[English](guide.md) | 中文 + +## 变更 + +在 0.2.1-rc.3 中，`session/attachment` 接收 `{ sessionId, attachmentId }`，并在请求中的 Session 历史里查找完整图片引用。现在，请求必须使用 `{ sessionId, attachment: ref }`，其中 `ref` 是包含 `attachmentId`、`mediaType`、`bytes`、`width` 和 `height` 的 `ImageAttachmentRef`。Client 的 `session.readAttachment()` 也改为接收完整引用，不再只接收 ID。 + +Host 把该引用交给已有的 `AttachmentStore.readImage(ref)`，将 ID、实际格式、字节数、宽度和高度与存储对象校验。响应仍为 `{ attachment, data }`，`data` 包含 base64 字节。响应保留传入引用，包括可选的 `name` 和 `originalDimensions`；这两个字段是调用方提交的显示信息，不根据文件校验。对象缺失、损坏或与引用不符时会明确失败。 + +连接身份认证和 Gateway 权限检查仍然适用。任何有权为请求中的 `sessionId` 调用该接口的身份，都可以读取同一存储中的图片，包括仅被其他 Session 引用或未被任何 Session 引用的图片。处理函数不检查图片关联或 Session 是否存在，授权通过后不再因 Session 不存在而返回 `session/not-found`。 + +## 迁移 + +1. 把 wire 调用从 `{ sessionId, attachmentId: ref.attachmentId }` 改为 `{ sessionId, attachment: ref }`，使用消息图片块中的完整引用。把 Client 调用从 `session.readAttachment(ref.attachmentId)` 改为 `session.readAttachment(ref)`。 +2. 把返回的 `name` 和 `originalDimensions` 视为调用方的显示信息。只有 ID、媒体类型、字节数、宽度和高度会与存储对象校验。 +3. 如果部署依赖 Session 关联来隔离图片，请在升级前改用独立 Host 实例及各自的 `DSH_HOME` 目录。随附组合不会在一个 Host 内按 Session 选择独立存储。Gateway 权限约束接口调用，不约束图片的 Session 关联。 +4. 确认获准调用的请求可以凭完整引用读取其 Session 中没有记录的图片，即使该 Session 不存在也可以读取。Gateway 拒绝的请求、缺失图片和固有元数据不符的引用必须失败。已有 Session 日志和存储图片无需迁移。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.i18n.yaml new file mode 100644 index 0000000000..f8584a6842 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.md +/: + en: 23336f139ca68e47 + zh: 20ef9419a53642d5 +/authorize-the-computer-use-helper: + en: f8335f2dca7a15cf + zh: 469a0a753fea2a93 +/authorize-the-computer-use-helper/change: + en: 1552866718133b10 + zh: 1c760c5c2d5cfc0b +/authorize-the-computer-use-helper/migration: + en: a79e5995415ff456 + zh: 6f818a092e53af2c diff --git a/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.md new file mode 100644 index 0000000000..c913488785 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.md @@ -0,0 +1,21 @@ +--- +kind: upgrade-guide +description: "Computer Use needs permission for its own helper application instead of the terminal that launches DSH." +--- + +# Authorize the Computer Use helper + +English | [中文](guide.zh.md) + +## Change + +macOS Computer Use runs as `DSH Computer Use.app`, launched through LaunchServices. Accessibility and Screen Recording grants for a terminal or Desktop launcher do not grant access to this helper. Source preparation builds and signs the application; installed packages require the prepared application and its `current.json` receipt. A custom `helperPath` pointing at a bare native binary is no longer a supported native launch path. + +## Migration + +1. Computer Use now installs on demand. In **Plugins → Add plugin**, install `@deepseek-ai/dsh-cua-bundle` and enable it; profiles that previously selected the shipped copy need this installation. Restart DSH if requested. In the Computer Use plugin page, grant Accessibility and Screen Recording access to `DSH Computer Use.app` when macOS requests it. +2. Remove an obsolete `helperPath` override or `DSH_CUA_HELPER` value to use automatic preparation. For a custom build, point it to the executable at `DSH Computer Use.app/Contents/MacOS/dsh-cua-native` inside the complete application bundle. +3. Confirm that the permission page identifies `DSH Computer Use.app` and both permissions are allowed before resuming native application tasks. Target-application consent remains required. +4. If a terminal or Desktop launcher was granted these permissions only for Computer Use, revoke those obsolete grants in System Settings. Authorizing the helper does not revoke other applications’ existing permissions; programs the model runs still follow their launcher’s system permissions and the DSH sandbox policy. + +Source builds use ad-hoc signing and may need authorization again after code changes. Release packagers must preserve a stable Developer ID signing identity and notarize their distribution. See the [native build instructions](../../../../packages/experimental/cua-macos/native/README.md#build-and-service). diff --git a/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.zh.md new file mode 100644 index 0000000000..f25a4b805d --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.zh.md @@ -0,0 +1,21 @@ +--- +kind: upgrade-guide +description: "Computer Use 需要给自己的 helper 应用授权，启动 DSH 的终端授权不再适用。" +--- + +# 给 Computer Use helper 授权 + +[English](guide.md) | 中文 + +## 变更 + +macOS Computer Use 通过 LaunchServices 以 `DSH Computer Use.app` 运行。终端或 Desktop 启动器的辅助功能和屏幕录制授权不赋予 helper 权限。源码准备会构建并签名应用；安装版需要预构建的应用及 `current.json` 记录。自定义 `helperPath` 指向裸原生二进制的启动方式不再受支持。 + +## 迁移 + +1. Computer Use 改为按需安装。在“插件 → 添加插件”中安装 `@deepseek-ai/dsh-cua-bundle` 并启用；此前选中过内置副本的 profile 也需完成这次安装。按提示重启 DSH。在 Computer Use 插件页按 macOS 提示，给 `DSH Computer Use.app` 授予辅助功能和屏幕录制权限。 +2. 删除过时的 `helperPath` 覆盖配置或 `DSH_CUA_HELPER` 值，使用自动准备。使用自定义构建时，将其指向完整应用包内的 `DSH Computer Use.app/Contents/MacOS/dsh-cua-native` 可执行文件。 +3. 恢复原生应用任务前，确认权限页显示 `DSH Computer Use.app`，且两项权限均已允许。具体目标应用仍需另行许可。 +4. 若终端或 Desktop 启动器的这两项权限只用于 Computer Use，可在系统设置中撤销这些旧授权。给 helper 授权不会撤销其他应用已有的权限；模型运行的程序仍遵循启动器的系统权限和 DSH 沙箱策略。 + +源码构建使用临时签名，代码变化后可能需要重新授权。正式发布需要保持稳定的 Developer ID 签名身份，并完成分发公证。参见[原生构建说明](../../../../packages/experimental/cua-macos/native/README.zh.md#build-and-service)。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.i18n.yaml new file mode 100644 index 0000000000..c86fcc5009 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.md +/: + en: af8e19ff73adbfbd + zh: 9daf099256b07409 +/macos-computer-use-application-identity: + en: d24696e5f85e9144 + zh: 184f7ebd8b8880df +/macos-computer-use-application-identity/change: + en: 7edc0de236633686 + zh: 08afc35393c95484 +/macos-computer-use-application-identity/migration: + en: 9c13aeec5e544d36 + zh: da697d3ee5a4637f diff --git a/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.md new file mode 100644 index 0000000000..c1010bf678 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: macOS Computer Use grants use bundle identifiers and require renewed consent for old application identities. +--- + +# macOS Computer Use application identity + +English | [中文](guide.zh.md) + +## Change + +Application grants use the case-sensitive native bundle identifier. Versions and copies at different paths share permission and revocation, regardless of signing. Applications without a bundle identifier use their canonical executable path and can also receive always-allow grants. Restarting or replacing the executable at that path retains consent; moving it requires renewed consent. A valid running bundle identifier does not require an executable path. Grant records can omit executablePath, and the permission page then shows the name without a path tooltip or icon. Existing records remain readable; older versions that require this field cannot read new pathless records. The profile storage location and conversation scopes are unchanged. + +This affects macOS users with saved path/signature grants, including grants imported from the legacy `allowedApps` configuration. Those grants do not match the new identities. They remain visible and removable but do not authorize other installations automatically. Old and new records can show the same name and path; the permission page does not distinguish them. Another program declaring an approved bundle identifier or replacing an executable at an approved fallback path inherits permission; this policy does not authenticate publishers. + +## Migration + +1. In Computer Use application management, revoke every existing always-allowed entry for each affected application before selecting it again. If you already granted access after upgrading, remove all entries for that application rather than trying to distinguish old and new records. +2. Under “Applications not allowed,” use “Allow asking again” for that application so a prior refusal or revocation does not prevent the next prompt. Select the application again and approve the intended scope. “Always allow” covers all versions and copies with the same bundle identifier within the profile. +3. Select another installed copy with that bundle identifier and confirm it does not ask again within the granted scope. Revoke the shared grant to stop access for all copies. Versions with different bundle identifiers still require separate approval. diff --git a/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.zh.md new file mode 100644 index 0000000000..c3b9103501 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.zh.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: macOS Computer Use 授权改用 Bundle ID，旧应用身份需要重新授权。 +--- + +# macOS Computer Use 应用身份 + +[English](guide.md) | 中文 + +## 变更 + +应用授权使用原生应用提供的、区分大小写的 Bundle ID。不同路径的版本和副本共用许可与撤销决定，不受签名状态影响。缺少 Bundle ID 的应用使用规范化可执行路径，也可以“始终允许”。在该路径重启或替换可执行文件会沿用许可，移动文件则需重新授权。运行中的有效 Bundle ID 不依赖可执行路径。授权记录可以省略 executablePath，权限页此时显示名称，不显示路径提示或图标。已有记录仍可读取，要求该字段的旧版本无法读取缺少路径的新记录。profile 存储位置和对话范围保持不变。 + +受影响的是保存过路径和签名授权的 macOS 用户，包括通过旧 `allowedApps` 配置导入授权的用户。这些授权不匹配新身份。旧记录仍可查看和撤销，但不会自动授权其他安装副本。新旧条目可能显示相同名称和路径，权限页没有区分它们。其他程序声明已批准的 Bundle ID，或替换路径授权对应的可执行文件时，也会继承许可，这项规则不验证发布者身份。 + +## 迁移 + +1. 重新选择应用前，在 Computer Use 应用管理中撤销该应用的所有“始终允许”条目。如果升级后已经批准过，也移除该应用的全部条目，无须判断哪条是旧记录。 +2. 在“不允许访问的应用”中，对该应用点击“允许再次询问”，避免先前的拒绝或撤销阻止下次提示。重新选择应用并批准所需范围。“始终允许”覆盖当前 profile 中相同 Bundle ID 的所有版本和副本。 +3. 选择具有相同 Bundle ID 的另一个已安装副本，确认在许可范围内不再询问。需要停止所有副本的访问时，撤销共用许可。使用不同 Bundle ID 的版本仍需分别批准。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.i18n.yaml new file mode 100644 index 0000000000..9fc991fbd3 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.md +/: + en: c799b94bab92d848 + zh: 1e1f9cd572fc8665 +/update-consumers-of-generated-worktree-names: + en: 210bc140e21cc68e + zh: dccc592eec81f483 +/update-consumers-of-generated-worktree-names/change: + en: 7a7d682dde36dd7e + zh: b15e84c570d11ee2 +/update-consumers-of-generated-worktree-names/migration: + en: f87101bee9c48150 + zh: 3a79159711475af3 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.md new file mode 100644 index 0000000000..6534639f18 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "Generated worktree names replace the worktree- prefix and full UUID suffix with dsh- and Session-derived names." +--- + +# Update consumers of generated worktree names + +English | [中文](guide.zh.md) + +## Change + +In v0.2.1-rc.3, omitting `name` from `create_worktree` or `ctx.worktrees.create` generates `worktree-` by default. The next release generates `dsh--`, such as `dsh-6b1f02c4-9a3e`. A Session id without a UUID gets `dsh-`. + +Scripts and ignore rules that require the `worktree-` prefix or a full UUID suffix need updating. Explicit names, the configured checkout pool, and existing checkout directories and branches are unchanged. The `namePrefix` setting remains available, but it controls only the prefix, not the suffix format. + +## Migration + +1. Update scripts and ignore rules that recognize generated names. Prefer the returned `path` and `branch` fields over reconstructing them from the old pattern; the [worktree service reference](../../../../packages/experimental/worktree/README.md#use-this-package) describes these fields. +2. To retain the old prefix, set `config.namePrefix` to `worktree-` in the existing `@deepseek-ai/dsh-experimental-worktree` configuration row. This does not restore the full UUID suffix. Supply an explicit `name` when an integration requires a particular complete name. +3. Create a worktree with `name` omitted, inspect its returned `branch` and `path`, and confirm that the updated automation recognizes it. Existing worktrees require no renaming or data migration. diff --git a/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.zh.md new file mode 100644 index 0000000000..f754b316eb --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.zh.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "自动生成的 worktree 名称将 worktree- 前缀和完整 UUID 后缀改为 dsh- 前缀与基于 Session 的名称。" +--- + +# 更新依赖自动生成 worktree 名称的使用方 + +[English](guide.md) | 中文 + +## 变更 + +在 v0.2.1-rc.3 中，调用 `create_worktree` 或 `ctx.worktrees.create` 时省略 `name`，默认生成 `worktree-`。下一版本默认生成 `dsh--<四位随机十六进制数>`，例如 `dsh-6b1f02c4-9a3e`。Session id 不含 UUID 时，生成 `dsh-<八位随机十六进制数>`。 + +依赖 `worktree-` 前缀或完整 UUID 后缀的脚本和忽略规则需要更新。显式名称、配置的检出父目录以及已有的检出目录和分支保持不变。`namePrefix` 配置项仍然可用，但只控制前缀，不控制后缀格式。 + +## 迁移 + +1. 更新识别自动生成名称的脚本和忽略规则。优先使用返回的 `path` 与 `branch` 字段，不要按旧模式重新拼接；[worktree 服务参考](../../../../packages/experimental/worktree/README.zh.md#use-this-package)说明了这些字段。 +2. 如需保留旧前缀，在现有的 `@deepseek-ai/dsh-experimental-worktree` 配置行中将 `config.namePrefix` 设为 `worktree-`。这不会恢复完整 UUID 后缀；集成要求特定完整名称时，请显式传入 `name`。 +3. 创建一个省略 `name` 的 worktree，检查返回的 `branch` 与 `path`，确认更新后的自动化能识别它。已有 worktree 无需改名或迁移数据。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.i18n.yaml new file mode 100644 index 0000000000..50d54a9371 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.md +/: + en: 6deb73f8bd3b1b2a + zh: 8bafa6e8c6277923 +/ptc-caller-cancellation-uses-the-standard-tool-error-code: + en: c647ac85178ef0ea + zh: a6e5b76d53bbb6ef +/ptc-caller-cancellation-uses-the-standard-tool-error-code/change: + en: 1a9a455bf55e6b81 + zh: ec925abc44d7684f +/ptc-caller-cancellation-uses-the-standard-tool-error-code/migration: + en: e3bbbebda24059c0 + zh: 926e91f3ce5a8a72 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.md new file mode 100644 index 0000000000..a53b061808 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "Caller-cancelled run_code results use ABORTED instead of CODE_RUN_FAILED." +--- + +# PTC caller cancellation uses the standard tool error code + +English | [中文](guide.zh.md) + +## Change + +When a running `run_code` call is cancelled by its caller and the runtime reports `abort`, its `tool/result` error changes from `CodeRunFailedError` / `CODE_RUN_FAILED` to `AbortError` / `ABORTED`. The result content is `Error: tool call aborted`, replacing the runtime diagnostic, captured output and sandbox summary. SDK clients and Session consumers that classify these results are affected. + +The Agent continues to record the specific cancellation cause in `turn/end`, including a hook's `reason`. Runtime failures such as timeout and cleanup failure, and runtime-local cancellation without caller cancellation, retain `CODE_RUN_FAILED`. Cancellation still waits for cleanup; it does not roll back completed tool effects, and retained runtime variables may be cleared. + +## Migration + +1. In consumers of new `tool/result` events, classify caller cancellation by `data.error.code === 'ABORTED'`. Read the Agent cancellation cause from the corresponding `turn/end` event's `data.reason.reason` when `data.reason.kind === 'aborted'`. +2. Keep support for `CODE_RUN_FAILED` when reading historical PTC cancellation results. Existing Session logs are not rewritten. +3. Cancel a running `run_code` call and confirm its result has code `ABORTED`, followed by a `turn/end` event containing the original Agent cancellation cause. Confirm ordinary runtime failures still report `CODE_RUN_FAILED`. diff --git a/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.zh.md new file mode 100644 index 0000000000..fbd17773ec --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.zh.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "调用方取消的 run_code 结果使用 ABORTED，取代 CODE_RUN_FAILED。" +--- + +# PTC 调用方取消使用标准工具错误码 + +[English](guide.md) | 中文 + +## 变更 + +运行中的 `run_code` 被调用方取消且运行时报告 `abort` 时，其 `tool/result` 错误从 `CodeRunFailedError` / `CODE_RUN_FAILED` 变为 `AbortError` / `ABORTED`。结果内容为 `Error: tool call aborted`，取代运行时诊断、捕获输出和沙箱摘要。按这些结果分类的 SDK 客户端和 Session 消费方受到影响。 + +Agent 继续在 `turn/end` 中记录具体取消原因，包括 hook 的 `reason`。超时、清理失败等运行时失败，以及没有调用方取消的运行时内部取消，保留 `CODE_RUN_FAILED`。取消仍等待清理完成；它不会回滚已完成的工具操作，保留的运行时变量可能被清空。 + +## 迁移 + +1. 在新 `tool/result` 事件的消费方中，通过 `data.error.code === 'ABORTED'` 识别调用方取消。当对应 `turn/end` 事件的 `data.reason.kind === 'aborted'` 时，从 `data.reason.reason` 读取 Agent 取消原因。 +2. 读取历史 PTC 取消结果时，继续支持 `CODE_RUN_FAILED`。已有 Session 日志不会被重写。 +3. 取消运行中的 `run_code`，确认其结果错误码为 `ABORTED`，随后的 `turn/end` 事件包含原始 Agent 取消原因。确认普通运行时失败仍报告 `CODE_RUN_FAILED`。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.i18n.yaml new file mode 100644 index 0000000000..8e84c0dcab --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.md +/: + en: 789ee06aa8932a32 + zh: d465eb26824f2b4b +/request-activation-when-following-a-session: + en: 25bd54a8216b1c71 + zh: edaa12b04713528a +/request-activation-when-following-a-session/change: + en: d4021672fedcbfb7 + zh: 35d5e76a69301e4a +/request-activation-when-following-a-session/migration: + en: aa22d72ca3f91d38 + zh: ebe991eca4bf74c2 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.md new file mode 100644 index 0000000000..cb01f8e90e --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.md @@ -0,0 +1,21 @@ +--- +kind: upgrade-guide +description: "Session follow callers must explicitly request background Agent activation." +--- +# Request activation when following a Session + +English | [中文](guide.zh.md) + +## Change + +`session.follow` no longer automatically resumes a cold ordinary Agent when `activate` is omitted. It reads the opening snapshot and follows subsequent events without activation. This affects integrations that used opening a history stream to make an Agent available. The shipped Web Client sends `activate: true` explicitly and retains its opening behavior. + +With `activate: true`, activation starts once the opening snapshot is computed, before it is delivered; that snapshot does not acknowledge Agent readiness. Subagent Sessions still do not use ordinary Agent activation. + +## Migration + +1. Add `activate: true` to `session.follow` requests that must resume a cold ordinary Agent. Keep the existing `address` and history-window fields. +2. For passive viewers, omit `activate` or set it to `false`. +3. Verify that an activation-enabled stream still returns its opening snapshot, then check Agent availability separately. Do not treat receipt of the snapshot as completion of activation. + +See the [Session Controller reference](../../../../packages/api/session-controller/README.md) for history and state observation behavior. diff --git a/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.zh.md new file mode 100644 index 0000000000..5df6e523a3 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.zh.md @@ -0,0 +1,21 @@ +--- +kind: upgrade-guide +description: "Session follow 调用方必须显式请求后台 Agent 激活。" +--- +# 跟随 Session 时显式请求激活 + +[English](guide.md) | 中文 + +## 变更 + +`session.follow` 在省略 `activate` 时不再自动恢复冷普通 Agent。它只读取开场快照并跟随后续事件，不进行激活。这会影响通过打开历史流使 Agent 可用的集成。随产品提供的 Web Client 显式发送 `activate: true`，保留原有打开行为。 + +设置 `activate: true` 时，激活在开场快照计算完成后、交付之前开始；该快照不确认 Agent 已就绪。子会话仍不走普通 Agent 激活。 + +## 迁移 + +1. 为需要恢复冷普通 Agent 的 `session.follow` 请求添加 `activate: true`，保留原有 `address` 和历史窗口字段。 +2. 被动查看器可以省略 `activate` 或设为 `false`。 +3. 确认启用激活的流仍返回开场快照，再单独检查 Agent 是否可用。不要把收到快照当作激活完成。 + +历史与状态观察行为见 [Session Controller 参考](../../../../packages/api/session-controller/README.zh.md)。 diff --git a/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.i18n.yaml new file mode 100644 index 0000000000..881f6d61d6 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.md +/: + en: 25674d6a93c97ca5 + zh: ac1563eccab1b284 +/file-downloads-on-web: + en: d8fac1a37dede04d + zh: 8f132360f0553b64 +/file-downloads-on-web/change: + en: d76c6132a5e5fc9d + zh: 691b2264a37a526f +/file-downloads-on-web/migration: + en: a4365e73ae4e2de4 + zh: 8988bc1703fc5b8d diff --git a/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.md b/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.md new file mode 100644 index 0000000000..dcc26609ac --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.md @@ -0,0 +1,19 @@ +--- +kind: upgrade-guide +description: "Custom file-action menus must offer save-as only on Desktop and browser downloads on Web." +--- + +# File downloads on Web + +English | [中文](guide.zh.md) + +## Change + +The Web file-action service no longer offers save-as through a browser file picker. `canSaveAs` is always false on Web, and `save(source, 'saveAs')` rejects before reading the source. Built-in Web file and image menus offer Download and omit Save as. Desktop still offers both actions; successful saves return the absolute destination `path` instead of an opaque file ID. + +## Migration + +1. Custom Client menus should include Save as only when `ctx.fileActions.canSaveAs` is true. +2. On Web, call `ctx.fileActions.save(source, 'download')`. The browser handles the original content and suggested filename; a `requested` result means download started, not completed. Do not report a saved local path. +3. Replace `savedFile(url)` and `reveal(id)` calls with an action on the completed `saved` result, using its `path` with `session.openWorkspacePath`. Keep original-file context-menu reveal independent of saved destinations. +4. Verify that Web file and image menus expose Download without Save as, including browsers that support `showSaveFilePicker`. Verify that Desktop image menus retain both actions. See the [file-action reference](../../../../packages/client/ui-file-actions/README.md) for save results and feedback ownership. diff --git a/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.zh.md new file mode 100644 index 0000000000..d9e232845a --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.zh.md @@ -0,0 +1,19 @@ +--- +kind: upgrade-guide +description: "自定义文件动作菜单应仅在 Desktop 提供另存为，在 Web 使用浏览器下载。" +--- + +# Web 文件下载 + +[English](guide.md) | 中文 + +## 变更 + +Web 文件动作服务不再通过浏览器文件选择器提供另存为。Web 的 `canSaveAs` 始终为 false，`save(source, 'saveAs')` 会在读取来源前拒绝。内置 Web 文件和图片菜单提供「下载」，不显示「另存为」。Desktop 仍提供两种操作；保存成功后返回目标绝对路径 `path`，不再返回不透明文件 ID。 + +## 迁移 + +1. 自定义 Client 菜单仅在 `ctx.fileActions.canSaveAs` 为 true 时添加「另存为」。 +2. Web 端调用 `ctx.fileActions.save(source, 'download')`。浏览器处理原始内容和建议文件名；`requested` 结果仅表示下载已开始，不代表完成。不要报告本机保存路径。 +3. 将 `savedFile(url)` 和 `reveal(id)` 调用替换为完成后 `saved` 结果上的操作，使用其中的 `path` 调用 `session.openWorkspacePath`。原文件右键定位应独立于保存目标。 +4. 验证 Web 文件和图片菜单只有「下载」而没有「另存为」，包括支持 `showSaveFilePicker` 的浏览器；验证 Desktop 图片菜单保留两种操作。保存结果与提示的归属参见[文件动作参考](../../../../packages/client/ui-file-actions/README.zh.md)。 diff --git a/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.i18n.yaml new file mode 100644 index 0000000000..5dea1bc8a2 --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.md +/: + en: 87b8371f353630ce + zh: 545cd66ec2055405 +/model-listings-refresh-automatically: + en: f4613eb3beef2045 + zh: 7c1301d90456a6c2 +/model-listings-refresh-automatically/change: + en: 6ed436b9f0a93aef + zh: 16a09e92ba786d89 +/model-listings-refresh-automatically/migration: + en: e479027c4c4811df + zh: 7cc7cde8aa4e0135 diff --git a/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.md b/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.md new file mode 100644 index 0000000000..3455c2bbfe --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.md @@ -0,0 +1,22 @@ +--- +kind: upgrade-guide +description: "DeepSeek model listings refresh automatically after first use, and custom listing-cache owners must supply live settings and change notifications." +--- +# Model listings refresh automatically + +English | [中文](guide.zh.md) + +## Change + +DeepSeek account and API-key routes refresh their model listing automatically after first use, including while idle. `modelsMaxAgeMs` keeps its ten-minute default and now schedules background requests instead of waiting for another access. Failed refreshes retain the last successful listing, including badges. Successful refreshes replace badge metadata, including omission or `null`, and notify open Web selectors. + +`ModelListingCache` consumers must supply `settings` and `changed` callbacks. Its `dispose()` now returns a promise that settles after active loads and automatic credential lookups finish. `ListedCatalog` also requires a `badges` map, and `ModelSelectInjected` requires a `resolveText` callback. + +## Migration + +1. Keep existing `modelsMaxAgeMs` values to use the same interval for automatic refresh. Use `0` only when each access should refresh and no automatic timer should run. +2. Custom `ModelListingCache` owners must provide `settings: () => ListingSettings | undefined` for the latest route configuration and `changed: () => void` to notify catalog consumers. Return `undefined` from `settings` when the route stops following a listing. +3. Return or await `cache.dispose()` from the owning plugin's cleanup. +4. Code that constructs `ListedCatalog` must include `badges: new Map()` when it has no badges, or a map from model id to `LlmModelBadge`. Prefer `resolveListedCatalog` to construct this result from decoded listing entries. +5. Code that constructs `ModelSelectInjected` must provide `resolveText: text => ctx.locale.resolveText(text)` from its owning locale service. Test doubles can use `text => typeof text === 'string' ? text : text.en` when they intentionally render English. +6. After the next refresh, confirm that an already-open model selector displays the current badge without reloading the page. Remove the badge field or set it to `null` to clear it. diff --git a/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.zh.md b/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.zh.md new file mode 100644 index 0000000000..4999430d2f --- /dev/null +++ b/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.zh.md @@ -0,0 +1,22 @@ +--- +kind: upgrade-guide +description: "DeepSeek 模型列表首次使用后自动刷新，自定义列表缓存的持有者必须提供实时配置与变化通知。" +--- +# 模型列表自动刷新 + +[English](guide.md) | 中文 + +## 变更 + +DeepSeek 账号与 API key 路由首次使用模型列表后会自动刷新，空闲时也会刷新。`modelsMaxAgeMs` 保留十分钟默认值，现在会安排后台请求，无需等待下一次访问。刷新失败时保留上次成功加载的列表及其角标。刷新成功时替换角标元数据，省略或 `null` 也会生效，并通知已打开的 Web 选择器。 + +`ModelListingCache` 的消费方必须提供 `settings` 与 `changed` 回调。其 `dispose()` 现在返回一个 promise，等待进行中的加载与自动凭据查询结束后才完成。`ListedCatalog` 还要求提供 `badges` 映射，`ModelSelectInjected` 要求提供 `resolveText` 回调。 + +## 迁移 + +1. 保留现有 `modelsMaxAgeMs` 值即可按相同间隔自动刷新。只有需要每次访问都刷新、且不运行自动定时器时，才使用 `0`。 +2. 自定义 `ModelListingCache` 持有者必须提供 `settings: () => ListingSettings | undefined` 以读取最新路由配置，并通过 `changed: () => void` 通知目录消费方。路由停止跟随列表时，`settings` 返回 `undefined`。 +3. 在持有该缓存的插件清理函数中返回或等待 `cache.dispose()`。 +4. 构造 `ListedCatalog` 的代码在没有角标时必须提供 `badges: new Map()`，否则提供模型 id 到 `LlmModelBadge` 的映射。优先使用 `resolveListedCatalog` 从已解码的列表条目构造该结果。 +5. 构造 `ModelSelectInjected` 的代码必须通过所属的 locale 服务提供 `resolveText: text => ctx.locale.resolveText(text)`。明确使用英语渲染的测试替身可以使用 `text => typeof text === 'string' ? text : text.en`。 +6. 下一次刷新后，确认已打开的模型选择器无需重新加载页面就显示当前角标。移除角标字段或将其设为 `null` 即可清除角标。 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.i18n.yaml new file mode 100644 index 0000000000..74990defdf --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.md +/: + en: 6c606440532dfae0 + zh: 9308d72d451e12c7 +/context-menu-types-and-icons: + en: d1237d3842936881 + zh: b32fcacf82bed5f1 +/context-menu-types-and-icons/change: + en: 35faa7bd1cff539f + zh: 0dc2515e0025e3d8 +/context-menu-types-and-icons/migration: + en: e15e76d8d6a95f35 + zh: 4bf2dec8d764e5ae diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.md new file mode 100644 index 0000000000..0f33207f01 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.md @@ -0,0 +1,19 @@ +--- +kind: upgrade-guide +description: "Client plugins must use the prefixed context menu types and hooks and register keyed icon components." +--- + +# Context menu types and icons + +English | [中文](guide.zh.md) + +## Change + +The `@deepseek-ai/dsh-client-ui-context-menu/client` export `MenuTarget` is renamed to `ContextMenuTarget`, matching `ContextMenuTargetMap`. The old name has no compatibility alias. Target fields and runtime behavior are unchanged. Workspace and sidebar injections rename `menuTarget` / `useMenuTarget` to `contextMenuTarget` / `useContextMenuTarget`. Action icons accept `{ key, src? }` instead of React nodes and render through the keyed `contextMenu.icon` Slot. + +## Migration + +1. Replace `MenuTarget` imports and type references with `ContextMenuTarget`. +2. Rename injected `menuTarget` sources and `useMenuTarget` consumers to `contextMenuTarget` and `useContextMenuTarget`. +3. Replace action icon elements with `{ key: 'my-plugin.action' }`; carry a captured image URL in `src` when needed. Register the icon component under that key through `ctx.slots.inject('contextMenu.icon', ...)` and `ctx.slots.register()`. See the [menu package](../../../../packages/client/ui-context-menu/README.md#use-this-package). +4. Rebuild custom Client plugins, confirm that type checks pass, and open their menus to verify icon rendering and plugin-unload cleanup. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.zh.md new file mode 100644 index 0000000000..e6bcb0cd2c --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.zh.md @@ -0,0 +1,19 @@ +--- +kind: upgrade-guide +description: "Client 插件须使用带前缀的右键菜单类型和 hook，并注册 keyed 图标组件。" +--- + +# 右键菜单类型和图标 + +[English](guide.md) | 中文 + +## 变更 + +`@deepseek-ai/dsh-client-ui-context-menu/client` 导出的 `MenuTarget` 更名为 `ContextMenuTarget`，与 `ContextMenuTargetMap` 保持一致。旧名不保留兼容别名，目标字段和运行时行为不变。工作区与侧栏注入的 `menuTarget` / `useMenuTarget` 改为 `contextMenuTarget` / `useContextMenuTarget`。操作图标改用 `{ key, src? }`，通过 keyed Slot `contextMenu.icon` 渲染，不再接收 React 节点。 + +## 迁移 + +1. 将 `MenuTarget` 导入及类型引用替换为 `ContextMenuTarget`。 +2. 将注入源 `menuTarget` 和消费者 `useMenuTarget` 分别改为 `contextMenuTarget`、`useContextMenuTarget`。 +3. 将操作图标元素替换为 `{ key: 'my-plugin.action' }`，需要时通过 `src` 携带已捕获的图片 URL。通过 `ctx.slots.inject('contextMenu.icon', ...)` 和 `ctx.slots.register()` 在该 key 下注册图标组件，参见[菜单包](../../../../packages/client/ui-context-menu/README.zh.md#use-this-package)。 +4. 重新构建自定义 Client 插件，确认类型检查通过，并打开菜单验证图标渲染和插件卸载后的清理。 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.i18n.yaml new file mode 100644 index 0000000000..dc8f886672 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.md +/: + en: 670467a1e1ef4871 + zh: a5c49c32981a3d50 +/forge-git-query-permissions-and-content-conversion: + en: 622fa28fae275249 + zh: 75888856615bcfd3 +/forge-git-query-permissions-and-content-conversion/change: + en: d8f544395f65b663 + zh: f785a6d6f9a696b6 +/forge-git-query-permissions-and-content-conversion/migration: + en: db9ae3d66f6bb1e7 + zh: 315bfde302564a7c diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.md new file mode 100644 index 0000000000..76ac171810 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.md @@ -0,0 +1,21 @@ +--- +kind: upgrade-guide +description: "Forge Git queries use Session permissions and disable configured diff helpers." +--- +# Forge Git query permissions and content conversion + +English | [中文](guide.zh.md) + +## Change + +Forge Git queries use the Session's sandbox mode instead of forcing `read-only`. `danger-full-access` works without a sandbox backend; `workspace-write` permits writes within its configured roots. A confined mode still refuses execution when its backend is unavailable. + +On Git 2.31 or newer, local diffs and statistics disable enumerated clean/process filters for each command. Git's built-in newline, ident, and encoding conversions still apply. Materialized LFS files and other filtered files can appear changed when ordinary Git considers them clean. The panel does not request LFS downloads. Older Git or concurrently added filters can still execute helpers under Session permissions. Submodule commit changes remain visible, but internal uncommitted changes are omitted. + +Filter configuration read failures, including truncated output, report `forgePanel/filter-config-failed` before any comparison and offer a retry. They are separate from `forgePanel/diff-too-large`. + +## Migration + +1. Keep a Session in `read-only` when its Git queries require operating-system-enforced write protection. Use the existing permission picker to select the intended Session mode; no configuration keys change. +2. For repositories that require content conversion or submodule working-tree inspection, use an explicit Git command under the intended Session permissions to inspect those changes. The panel's local comparison bypasses clean/process filters on supported Git versions. +3. On a host without a sandbox backend, select Full access and refresh the Forge panel. Its checkout and ordinary local changes should load; switching to a confined mode must still report the unavailable backend. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.zh.md new file mode 100644 index 0000000000..07c4770bf3 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.zh.md @@ -0,0 +1,21 @@ +--- +kind: upgrade-guide +description: "Forge Git 查询使用 Session 权限并禁用已配置的 diff 辅助程序。" +--- +# Forge Git 查询权限与内容转换 + +[English](guide.md) | 中文 + +## 变更 + +Forge Git 查询使用 Session 的沙箱模式，不再强制 `read-only`。`danger-full-access` 无需沙箱后端；`workspace-write` 允许在其配置的根目录内写入。受限模式的后端不可用时仍拒绝执行。 + +在 Git 2.31 或更新版本中，本地 diff 与统计仅对每次命令禁用已枚举的 clean/process filter。Git 内置的换行、ident 与编码转换仍然生效。已物化的 LFS 文件及其他过滤文件可能显示为变更，即使普通 Git 认为它们未变。面板不请求下载 LFS 对象。旧 Git 或并发新增的过滤器仍可能按 Session 权限执行辅助程序。子模块提交变化仍可见，但内部未提交修改不显示。 + +过滤器配置读取失败（包括输出被截断）时，在任何比较之前报告 `forgePanel/filter-config-failed` 并提供重试，与 `forgePanel/diff-too-large` 区分。 + +## 迁移 + +1. 如果 Git 查询需要操作系统强制禁止写入，请将 Session 保持为 `read-only`。通过现有权限选择器选择所需的 Session 模式；配置键没有变化。 +2. 对于需要内容转换或检查子模块工作区的仓库，请在所需的 Session 权限下显式运行 Git 命令检查这些变化。面板的本地比较在受支持的 Git 版本中绕过 clean/process filter。 +3. 在没有沙箱后端的主机上选择“完全权限”，然后刷新 Forge 面板。检出信息和普通本地变更应可加载；切回受限模式后仍须报告后端不可用。 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.i18n.yaml new file mode 100644 index 0000000000..7bae7f2845 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.md +/: + en: 0a5cfa851101f3e9 + zh: 1c8e0e437718d4e2 +/declare-auxiliary-llm-request-purposes: + en: 5d5e1b6cb5b9c95e + zh: 11cf31babb07da28 +/declare-auxiliary-llm-request-purposes/change: + en: 0682a43eb52792fd + zh: 954b186cc66fdb08 +/declare-auxiliary-llm-request-purposes/migration: + en: eae671d1e185ecbf + zh: c042a276a1a7ad17 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.md new file mode 100644 index 0000000000..d71d8f6bef --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.md @@ -0,0 +1,29 @@ +--- +kind: upgrade-guide +description: "Auxiliary LLM request purposes require producer-owned type declarations instead of a shared fixed union." +--- + +# Declare auxiliary LLM request purposes + +English | [中文](guide.zh.md) + +## Change + +`GenerateOptions.purpose` derives from the declaration-mergeable `LlmRequestPurposeMap` exported by `@deepseek-ai/dsh-llm/types`. The shared package no longer declares `compaction` or `session-title`. Plugins that construct auxiliary requests must load the producer's declarations or declare their own purpose. Existing runtime purpose strings keep their meaning. + +## Migration + +1. Import `@deepseek-ai/dsh-compaction-basic` for direct compaction requests, or `@deepseek-ai/dsh-session-title-llm` for title requests, using a type-only import when only the declaration is needed. +2. For a plugin-owned purpose, augment `LlmRequestPurposeMap` from the plugin's public type entry. Map the purpose key to `true`: + + ```ts + import type {} from '@deepseek-ai/dsh-llm/types' + + declare module '@deepseek-ai/dsh-llm/types' { + interface LlmRequestPurposeMap { + 'my-plugin-purpose': true + } + } + ``` + +3. Compile the plugin against the new package declarations. Confirm that its request accepts the declared purpose and rejects an undeclared key. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.zh.md new file mode 100644 index 0000000000..d1fd550142 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.zh.md @@ -0,0 +1,29 @@ +--- +kind: upgrade-guide +description: "辅助 LLM 请求用途改为生产方拥有的类型声明，不再使用共享固定联合。" +--- + +# 声明辅助 LLM 请求用途 + +[English](guide.md) | 中文 + +## 变更 + +`GenerateOptions.purpose` 由 `@deepseek-ai/dsh-llm/types` 导出的可声明合并的 `LlmRequestPurposeMap` 派生。共享包不再声明 `compaction` 或 `session-title`。构造辅助请求的插件必须加载生产方的声明，或声明自己的用途。现有运行时用途字符串保持原有含义。 + +## 迁移 + +1. 直接构造压缩请求时导入 `@deepseek-ai/dsh-compaction-basic`，构造标题请求时导入 `@deepseek-ai/dsh-session-title-llm`；只需要声明时使用仅类型导入。 +2. 对插件拥有的用途，在插件公开类型入口中扩展 `LlmRequestPurposeMap`，将用途键映射到 `true`： + + ```ts + import type {} from '@deepseek-ai/dsh-llm/types' + + declare module '@deepseek-ai/dsh-llm/types' { + interface LlmRequestPurposeMap { + 'my-plugin-purpose': true + } + } + ``` + +3. 使用新包的声明编译插件，确认请求接受已声明用途，并拒绝未声明的键。 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml new file mode 100644 index 0000000000..69f284f402 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md +/: + en: 695ee5740865d684 + zh: 83cb4df5ecf20a99 +/sdk-run-accepts-native-commands: + en: 54f8a31426f4758c + zh: 283820d3f187092e +/sdk-run-accepts-native-commands/change: + en: 478742169aa04c50 + zh: 3324d99f4206d1fc +/sdk-run-accepts-native-commands/migration: + en: 0298fc31efa6466c + zh: ab99db4beaa86a14 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md new file mode 100644 index 0000000000..deb605d80e --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md @@ -0,0 +1,24 @@ +--- +kind: upgrade-guide +description: "SDK run recognizes native commands and returns RunResult after its input completes." +--- + +# SDK run accepts native commands + +English | [中文](guide.zh.md) + +## Change + +Python and TypeScript `run()` accept strings and content-block arrays through the existing entry and always return `RunResult`. Supported native commands are recognized by their definition identities and effective registered names. English and Chinese aliases follow renamed definitions; unrelated exact-name replacements remain ordinary input. See the [supported command rules](../../../../packages/sdk/server/README.md#command-input). + +`final_response` / `finalResponse` contains the final assistant text, or an empty string when the activity emits none. State-only commands return the native handler's result text. `finish_reason` / `finishReason` reports the terminal outcome. Every result retains its Session id, root events and Session-tree notifications. State-only commands finish without waiting for a model turn; `/plan ` waits for its admitted activity, including native review and any approved continuation. Goal creation and resume wait across automatic rounds until the goal stops and its closing activity ends. Low-level strict command calls still return `CommandExecution` after the native handler settles. + +Content-block arrays no longer bypass native routing. A recognized command requires one text block and optional encoded raster images; native handlers enforce image admission. `/plan off` with an image fails without changing plan state. Empty arrays and blank-only input reject before Session creation; image-only input remains accepted. Identity rejection by the strict endpoint retains its initialized Session without executing a handler or submitting a prompt. + +## Migration + +1. Keep the existing `result.final_response` / `result.finalResponse` access for prompts and commands. Inspect `finish_reason` / `finishReason` for failure; command ids and native outcomes remain in `command/run` and `command/done` events. Save the result's Session id to continue or restore it. +2. Keep the user-question callback alive for plan review. State-changing command failures appear in `RunResult`; routing, malformed protocol data and transport failures still raise or reject. A timeout or observer failure does not roll back runtime work. +3. For literal queued input, use Python `client.session_prompt(session_id, blocks)` or TypeScript `client.prompt(sessionId, blocks)`, and manage its subsequent activity. Runtime skill recognition still applies. +4. Custom `session/query` clients send `{ sessionId, contentBlocks }`. Command responses acknowledge the native handler; the matching `session.query.completed` notification carries the final input outcome. Preserve notification order and subscribe before sending. +5. Filter empty input before calling `run()`. Use an image-capable model and the existing `run([text_block, image_block])` form for images. Python malformed native command responses raise `SdkProtocolError`, preserving their validation cause; generic caller-selected response models retain their validation behavior. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md new file mode 100644 index 0000000000..3af3c36ed3 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md @@ -0,0 +1,24 @@ +--- +kind: upgrade-guide +description: "SDK run 识别原生命令，并在本次输入完成后返回 RunResult。" +--- + +# SDK run 接受原生命令 + +[English](guide.md) | 中文 + +## 变更 + +Python 和 TypeScript 的 `run()` 通过原有入口接受字符串和内容块数组，始终返回 `RunResult`。受支持原生命令按定义身份和实际注册名识别。中英文别名跟随重命名的定义；无关的同名替代命令仍作为普通输入。见[支持的命令规则](../../../../packages/sdk/server/README.zh.md#command-input)。 + +`final_response` / `finalResponse` 包含最终助手文本；活动未输出助手文本时为空字符串。仅改变状态的命令返回原生 handler 的结果文本。`finish_reason` / `finishReason` 表示结束结果。每份结果都保留 Session id、根会话事件和会话树通知。仅改变状态的命令无需等待模型 turn；`/plan ` 等待其提交的活动，包括原生审阅及获批后的后续执行。目标创建和恢复跨越自动轮次等待，直到目标停止及最后的活动结束。底层严格命令调用仍在原生 handler 完成后返回 `CommandExecution`。 + +内容块数组不再绕过原生命令路由。已识别命令要求一个文本块及可选的编码位图；原生 handler 执行图片准入。`/plan off` 带图片会失败且不改变计划状态。空数组和纯空白输入在创建 Session 前拒绝；纯图片输入仍然接受。严格端点拒绝命令身份时保留已经初始化的 Session，不执行 handler 或提交提示词。 + +## 迁移 + +1. 普通提示词和命令均继续使用 `result.final_response` / `result.finalResponse`。通过 `finish_reason` / `finishReason` 检查失败；命令 id 和原生结果保留在 `command/run` 与 `command/done` 事件中。保存结果的 Session id，以便继续或恢复会话。 +2. 计划审阅期间保持用户问题回调可用。状态变更命令的失败体现在 `RunResult` 中；路由、协议数据格式和传输失败仍抛出或拒绝。超时或观察回调失败不会回滚运行时工作。 +3. 需要按原文排队输入时，使用 Python `client.session_prompt(session_id, blocks)` 或 TypeScript `client.prompt(sessionId, blocks)`，并管理后续活动。运行时技能识别仍然适用。 +4. 自定义 `session/query` 客户端发送 `{ sessionId, contentBlocks }`。命令响应确认原生 handler 完成；对应的 `session.query.completed` 通知携带本次输入的最终结果。保持通知顺序，并在发送前订阅。 +5. 调用 `run()` 前过滤空输入。图片使用支持图片的模型及原有 `run([text_block, image_block])` 形式。Python 对格式错误的原生命令响应抛出 `SdkProtocolError`，保留校验原因；调用者自行选择的通用响应模型保留原有校验行为。 diff --git a/docs/user/guide/python-sdk.i18n.yaml b/docs/user/guide/python-sdk.i18n.yaml index f911334f40..db2d757606 100644 --- a/docs/user/guide/python-sdk.i18n.yaml +++ b/docs/user/guide/python-sdk.i18n.yaml @@ -12,8 +12,8 @@ en: c2b15716ea155625 zh: 0879be26f0afc452 /get-started-with-the-python-sdk/run-the-checked-in-example: - en: 74e1866caf573e6a - zh: 7f034b6f81decf9d + en: 23d04cd9dcb6a530 + zh: e7a9471b9493b888 /get-started-with-the-python-sdk/use-the-sdk-in-your-program: en: d1e350be0ba38196 zh: 893220ee7b12b12f @@ -24,5 +24,5 @@ en: 450d54b6e9e38469 zh: f0dc06a08c073571 /get-started-with-the-python-sdk/understand-the-minimal-profile: - en: 8ed0bfd3cc9cc967 - zh: a52dab4cb3dd09ea + en: ea2a6521cff50517 + zh: 3769760a5e40af8d diff --git a/docs/user/guide/python-sdk.md b/docs/user/guide/python-sdk.md index 438598c378..38f6a2a531 100644 --- a/docs/user/guide/python-sdk.md +++ b/docs/user/guide/python-sdk.md @@ -91,7 +91,7 @@ python python/sdk/examples/minimal.py ` ::: -The script prints the final assistant response. The selected home receives the generated `sdk-minimal` profile, installed plugins, and uncompressed JSONL session logs under `sessions/`. The example and SDK never silently read `~/.dsh`. +The script prints the final assistant response or the command result supplied by the selected profile. The selected home receives the generated `sdk-minimal` profile, installed plugins, and uncompressed JSONL session logs under `sessions/`. The example and SDK never silently read `~/.dsh`. ## Use the SDK in your program @@ -176,7 +176,7 @@ Pass `patches=("/absolute/path/to/editor.patch.yml",)` when constructing `DeepSe The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while text file tools, settings, managed credentials, OTel telemetry, Web tools, subagents, and local instruction discovery are absent. The [DeepSeek session-log contributor](../../../packages/session/session-log-deepseek/README.md) uploads unaccepted log events with DeepSeek requests by default, at most `maxBytes` (8 MiB) per request; set `session-log-deepseek.enabled: false` in a profile patch to disable it. It pins `danger-full-access`, so the platform-selected persistent shell can modify any path visible to the runtime; use a disposable checkout or container. -Image reading requires an image-capable route. Automatic compaction preserves the complete Session log; see the [bundle reference](../../../packages/bundle/sdk-minimal/README.md) for model and storage effects. SDK prompt text does not execute `/compact` or other slash commands. +Image reading requires an image-capable route. Automatic compaction preserves the complete Session log; see the [bundle reference](../../../packages/bundle/sdk-minimal/README.md) for model and storage effects. In this `sdk-minimal` composition, unsupported slash input remains ordinary prompt text. The installed wheel still packages the full `web` profile and frontend assets. Run `dsh web` against an explicit `DSH_HOME` when a Python SDK deployment also needs the browser application; `web` is a separate CLI application and cannot serve a Python SDK client. diff --git a/docs/user/guide/python-sdk.zh.md b/docs/user/guide/python-sdk.zh.md index b7a86e9860..cd321cfad6 100644 --- a/docs/user/guide/python-sdk.zh.md +++ b/docs/user/guide/python-sdk.zh.md @@ -91,7 +91,7 @@ python python/sdk/examples/minimal.py ` ::: -脚本会打印最终 assistant 响应。所选 home 会保存生成的 `sdk-minimal` profile、已安装插件，以及 `sessions/` 下的未压缩 JSONL 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。 +脚本会打印最终 assistant 响应或所选 profile 提供的命令结果。所选 home 会保存生成的 `sdk-minimal` profile、已安装插件，以及 `sessions/` 下的未压缩 JSONL 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。 ## 在程序中使用 SDK @@ -176,7 +176,7 @@ dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle 该 profile 的唯一组合包会在空根之上插入完整配置树，且不包含 `dsh-base`，因此基础 profile 以后新增的工具不会隐式出现。它包含 SDK 协议、一个由环境配置的 DeepSeek 适配器、本地执行与持久化；文本文件工具、settings、托管凭据、OTel 遥测、Web 工具、subagent、本地指令发现均不存在。[DeepSeek 会话日志贡献器](../../../packages/session/session-log-deepseek/README.zh.md)默认随 DeepSeek 请求上传未接受的日志事件，每次请求最多 `maxBytes`（8 MiB）；在 profile patch 中设置 `session-log-deepseek.enabled: false` 可将其关闭。它固定使用 `danger-full-access`，因此按平台选择的持久 shell 可以修改运行时可见的任何路径；应使用一次性 checkout 或容器。 -图片读取需要支持图片输入的路由。自动压缩保留完整 Session 日志；模型与存储影响见[组合包参考](../../../packages/bundle/sdk-minimal/README.zh.md)。SDK 提示词文本不会执行 `/compact` 或其他斜杠命令。 +图片读取需要支持图片输入的路由。自动压缩保留完整 Session 日志；模型与存储影响见[组合包参考](../../../packages/bundle/sdk-minimal/README.zh.md)。在这个 `sdk-minimal` 组合中，不支持的斜杠输入保持为普通提示词文本。 已安装 wheel 仍会打包完整 `web` profile 与前端产物。如果 Python SDK 部署还需要浏览器应用，请针对显式 `DSH_HOME` 运行 `dsh web`；`web` 是独立 CLI 应用，不能为 Python SDK client 提供服务。 diff --git a/package.json b/package.json index 368901f21a..9dccd6008b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-root", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "license": "MIT", "private": true, "type": "module", @@ -48,6 +48,7 @@ "upload:latest:mac:arm64": "pnpm --filter @deepseek-ai/dsh-desktop run upload:latest:mac:arm64", "upload:latest:mac:x64": "pnpm --filter @deepseek-ai/dsh-desktop run upload:latest:mac:x64", "upload:latest:win:x64": "pnpm --filter @deepseek-ai/dsh-desktop run upload:latest:win:x64", + "purge:latest": "pnpm --filter @deepseek-ai/dsh-desktop run purge:latest", "clean": "tsx scripts/clean.ts", "change-scope": "tsx scripts/change-scope.ts", "typecheck": "tsx scripts/build.ts --scope typecheck", @@ -301,6 +302,9 @@ "@deepseek-ai/dsh-experimental-subagent-oar": "workspace:*", "@deepseek-ai/dsh-experimental-tool-subagent-oar": "workspace:*", "@deepseek-ai/dsh-experimental-cua-macos": "workspace:*", + "@deepseek-ai/dsh-experimental-forge": "workspace:*", + "@deepseek-ai/dsh-experimental-forge-github": "workspace:*", + "@deepseek-ai/dsh-experimental-forge-session": "workspace:*", "@deepseek-ai/dsh-action-cards": "workspace:*" } } diff --git a/packages/acp/acp/package.json b/packages/acp/acp/package.json index 41962dd596..877006761a 100644 --- a/packages/acp/acp/package.json +++ b/packages/acp/acp/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-acp", "description": "Automation-only Agent Client Protocol server for driving DeepSeek Harness agents over JSON-RPC stdio", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/account-controller/package.json b/packages/api/account-controller/package.json index 30aa41c6da..1bd865aeeb 100644 --- a/packages/api/account-controller/package.json +++ b/packages/api/account-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-account-controller", "description": "Expose safe account operations over authenticated Remote", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml index a9ddbc70b5..eb3352e60d 100644 --- a/packages/api/gateway/README.i18n.yaml +++ b/packages/api/gateway/README.i18n.yaml @@ -15,8 +15,8 @@ en: d9859219cdb0f367 zh: 2a3cfa8cb786e327 /deepseek-ai-dsh-api-gateway/host-service-typertgatewayservice-ctx-key-typertgateway: - en: b35573c6707d00d9 - zh: 619bbba900b0fb8f + en: 6ee072ffebd2eb38 + zh: 6a8723d13f443d51 /deepseek-ai-dsh-api-gateway/client-service-clientremote-ctx-key-remote: en: 0916113cdbe794fb zh: 14893c2cba95bfd6 diff --git a/packages/api/gateway/README.md b/packages/api/gateway/README.md index 6518441122..fea754c891 100644 --- a/packages/api/gateway/README.md +++ b/packages/api/gateway/README.md @@ -34,6 +34,8 @@ Every call names the Peer it speaks for: `InvokeRemoteRequest.peer` and the `pee Resources are read from validated arguments: Typert-compiled codecs drop undeclared object fields, while SRC fallback checks JSON safety without stripping them; lookup and Context identities keep their wire values. For each resource kind, a reader in the method's `@Remote({ resources })` or `@RemoteScope(key, { resources })` options wins; it is called with the method's positional arguments, where lookup positions hold wire identities and the cancellation position holds the call's signal, and is read from the class metadata of the root Service instance. Otherwise every lookup parameter whose provider declares that kind through `resource` contributes its wire identity, an omitted optional one contributing none, and a Context method whose Host Context adapter declares that kind contributes its Context identity, read from the arguments before the Context is resolved. Otherwise the kind's declaration in `typert.resources` supplies either a default field or a synchronous resolver. A field reads a top-level argument of that name or, failing that, the first object argument. A resolver is called once with `{ args, parameters }`: named validated wire values and ordered parameter descriptions containing `name` and `wire`. Both defaults return one identity or `undefined`; arrays are invalid. An explicit reader may return several identities. A resolver or reader that throws, a reader returning an empty list, or an identity, including a Context identity, that is not a non-empty string makes the resolution `invalid`; a call that names no resource touches the `global` resource alone, and a call that names resources touches only those. A forwarded event carries every resource its entry declares, so there a reader returning `undefined` also makes the resolution `invalid`, while an entry without readers touches `global`. +`getPendingRemoteEvents()` returns detached event-name and Agent-ID metadata for currently unsettled forwarded events in arrival order. It neither exposes request bodies nor changes event lifetimes, and it does not provide a change notification. + A cancellation-aware Remote method declares `signal: AbortSignal` as its final Host parameter. The signal is descriptor metadata rather than a wire argument: Connection supplies it to the Gateway, and the Gateway injects it after decoded business parameters. SRC recognizes the reserved final name, while strict generation additionally requires the global `AbortSignal` type. A stream Remote uses `@Remote({ mode: 'stream' })` and returns an `Iterable` or `AsyncIterable`. `ctx.typertGateway.stream()` applies the same endpoint, argument, lookup, and cancellation checks as unary invocation, then returns a cancellation-aware iterable over the business items. The Client opens the Gateway-owned `/api/remote.mux` WebSocket when its plugin activates and keeps it connected while idle. Connection owns the retry schedule; before each retry it asks the mux to cancel any candidate or active socket and make exactly one fresh physical attempt. The Host sends Ping control frames at the configured `websocketHeartbeatIntervalMs` interval (two seconds by default), and the browser answers Pong at the WebSocket protocol layer, so idle network intermediaries see traffic without any Remote stream frame. A Pong, any received frame, or a downlink write that does not complete at once counts as peer activity; with the default `'deflate'`, a frame whose JSON text reaches the compression threshold is deflated asynchronously, so its completion always counts. A socket with no activity across two Ping intervals is terminated, so a congested link that delays the Pong behind data stays connected. With `websocketCompression` at its `'deflate'` default, an upgrade that offers `permessage-deflate` negotiates the extension, and the Host compresses its own outbound frames whose JSON text reaches 1,024 characters; shorter frames stay uncompressed, uplink frames are compressed at the peer's discretion, and `'none'` accepts the same upgrades without the extension. Independently cancellable logical streams share that socket; an in-process Connection carrier provides equivalent streams directly without opening it. diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md index 34759301dd..1dad623204 100644 --- a/packages/api/gateway/README.zh.md +++ b/packages/api/gateway/README.zh.md @@ -34,6 +34,8 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle 资源从已校验参数中读取：Typert 编译 codec 会移除未声明的对象字段，SRC fallback 只检查 JSON 安全性而不移除字段；lookup 与 Context 身份保持 wire 值。对每个资源种类，方法 `@Remote({ resources })` 或 `@RemoteScope(key, { resources })` options 中的读取函数优先；它以方法的位置参数调用（lookup 位为 wire 身份，取消参数位为调用的 signal），从根 Service 实例的类元数据读取。否则 provider 经 `resource` 声明了该种类的每个 lookup 参数贡献其 wire 身份，省略的可选 lookup 参数不贡献；Host Context adapter 声明了该种类的 Context 方法贡献其 Context 身份，在解析 Context 之前直接从参数读取。再否则使用该种类在 `typert.resources` 中登记的默认字段或同步 resolver。字段规则读取同名顶层参数，没有时读取第一个对象参数的同名字段。resolver 以 `{ args, parameters }` 调用一次：命名的已校验 wire 值，以及包含 `name`、`wire` 的有序参数描述。两种默认规则均返回单个身份或 `undefined`，数组无效。显式读取函数可以返回多个身份。resolver 或读取函数抛错、读取函数返回空列表、或某个身份（含 Context 身份）不是非空字符串时，解析结果为 `invalid`；不指明任何资源的调用只访问 `global` 资源，指明了资源的调用只访问这些资源。转发事件携带其条目声明的每个资源，因此在事件路径上读取函数返回 `undefined` 同样使解析结果为 `invalid`，而没有读取函数的条目访问 `global`。 +`getPendingRemoteEvents()` 按到达顺序返回当前未结算转发事件的独立元数据，仅含事件名和 Agent ID。它不暴露请求正文，不改变事件生命周期，也不提供变化通知。 + 支持取消的 Remote 方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。signal 是 descriptor 元数据，而不是 wire 参数：Connection 将它提供给 Gateway，Gateway 则在已解码的业务参数之后注入它。SRC 识别这个保留的末位参数名，严格生成还要求它具有全局 `AbortSignal` 类型。 流式 Remote 使用 `@Remote({ mode: 'stream' })` 并返回 `Iterable` 或 `AsyncIterable`。`ctx.typertGateway.stream()` 执行与一元调用相同的 endpoint、参数、lookup 和取消校验，再返回可取消的业务项 iterable。Client 插件激活时打开 Gateway 自有的 `/api/remote.mux` WebSocket，并让它在空闲时保持连接。Connection 拥有重试调度；每次 retry 前，它要求 mux 取消候选或活动 socket，并且只做一次全新的物理连接尝试。Host 按配置的 `websocketHeartbeatIntervalMs` 间隔（默认 2 秒）发送 Ping 控制帧，浏览器在 WebSocket 协议层自动回复 Pong，使空闲网络中间层持续看到流量，而不新增 Remote 流帧。Pong、收到的任意帧，或未一次性完成的下行写入，都视为对端活动；默认 `'deflate'` 下，JSON 文本达到压缩阈值的帧异步 deflate，因此其完成总是计入。连续两个 Ping 间隔没有活动的 socket 会被终止，因此 Pong 被数据阻塞在拥塞链路上时连接仍会保持。`websocketCompression` 保持默认的 `'deflate'` 时，携带 `permessage-deflate` 的升级会协商该扩展，Host 压缩自己发出的、JSON 文本达到 1024 个字符 的帧；更短的帧不压缩，上行帧是否压缩由对端决定，设为 `'none'` 时接受同样的升级但不带该扩展。可独立取消的逻辑流共享这条连接；进程内 Connection 载体直接提供等价的流，不打开该 WebSocket。 diff --git a/packages/api/gateway/package.json b/packages/api/gateway/package.json index 2b4183a776..f67e41c300 100644 --- a/packages/api/gateway/package.json +++ b/packages/api/gateway/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-gateway", "description": "Typert Remote Host dispatcher and Client API endpoint", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/gateway/src/client/remote-events.ts b/packages/api/gateway/src/client/remote-events.ts index eabda54e37..8e5b1c22ca 100644 --- a/packages/api/gateway/src/client/remote-events.ts +++ b/packages/api/gateway/src/client/remote-events.ts @@ -333,7 +333,7 @@ function invalidRemoteEventFrame(): never { } function privateEvents(ctx: Context): PrivateEventContext { - return ctx + return ctx.events } function toError(reason: unknown, message: string): Error { diff --git a/packages/api/gateway/src/index.ts b/packages/api/gateway/src/index.ts index 878c77cf5e..4fe2652671 100644 --- a/packages/api/gateway/src/index.ts +++ b/packages/api/gateway/src/index.ts @@ -36,6 +36,7 @@ import { } from '@deepseek-ai/dsh-typert-protocol' import type { InvokeRemoteRequest, + PendingRemoteEventInfo, TypertGateway, TypertGatewayErrorCode, TypertGatewayWireStream, @@ -70,6 +71,7 @@ import { export type { InvokeRemoteRequest, + PendingRemoteEventInfo, TypertGateway, TypertGatewayErrorCode, TypertGatewayWireStream, @@ -333,6 +335,14 @@ export class TypertGatewayService extends Service implements TypertGateway { return false } + /** + * Inspect unsettled forwarded events without changing their lifetime. + * @returns detached event names and Agent identities. + */ + getPendingRemoteEvents(): readonly PendingRemoteEventInfo[] { + return [...this.pendingRemoteEvents.values()].map(({ frame }) => ({ event: frame.event, agentId: frame.agentId })) + } + /** * Register the sole application-selected forwarded-event source. * @param source - stream factory installed by the Remote assembly. diff --git a/packages/api/gateway/src/types.ts b/packages/api/gateway/src/types.ts index 83ae7f0730..b802aba061 100644 --- a/packages/api/gateway/src/types.ts +++ b/packages/api/gateway/src/types.ts @@ -5,7 +5,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { PeerScope, RemoteUplinkWindow, TypertResourceReader } from '@deepseek-ai/dsh-typert-protocol' -import type { RemoteEventHostInfo } from './stream-protocol.ts' +import type { RemoteEventAgentId, RemoteEventHostInfo } from './stream-protocol.ts' /** One Remote method request after a carrier has decoded its envelope. */ export interface InvokeRemoteRequest { @@ -144,6 +144,12 @@ export type TypertGatewayErrorCode = | 'gateway/signature-invalid' | 'gateway/uplink-overflow' +/** Public metadata of one unsettled forwarded Remote event. */ +export interface PendingRemoteEventInfo { + readonly event: string + readonly agentId: RemoteEventAgentId +} + /** Host dispatcher consumed by Connection adapters. */ export interface TypertGateway { /** Carrier adapter shared by WebSocket and in-process transports. */ @@ -155,6 +161,9 @@ export interface TypertGateway { */ hasLiveClient(): boolean + /** @returns detached metadata for all unsettled forwarded events in arrival order. */ + getPendingRemoteEvents(): readonly PendingRemoteEventInfo[] + /** * Register the application-selected forwarded-event source. * @param source - stream factory installed by the Remote assembly. diff --git a/packages/api/gateway/tests/gateway-access.host.spec.ts b/packages/api/gateway/tests/gateway-access.host.spec.ts index 53727804ee..346f50a8be 100644 --- a/packages/api/gateway/tests/gateway-access.host.spec.ts +++ b/packages/api/gateway/tests/gateway-access.host.spec.ts @@ -730,6 +730,7 @@ describe('Gateway forwarded events for non-owner Peers', () => { await expect(ownerEvents.next()).resolves.toMatchObject({ value: { type: 'ready', host: { home: '/fixture' } } }) expect(ctx.typertGateway.hasLiveClient()).toBe(true) + expect(ctx.typertGateway.getPendingRemoteEvents()).toEqual([]) const agentCtx = ctx.extend({}) const subject = {} const settled = vi.fn() @@ -745,6 +746,10 @@ describe('Gateway forwarded events for non-owner Peers', () => { push({ event: 'fixture/shelf', args: ['s2'], resources }) push({ event: 'fixture/shelf', args: ['s1'], resources }) await expect(ownerEvents.next()).resolves.toMatchObject({ value: { type: 'waterfall', event: 'fixture/ask' } }) + const pending = ctx.typertGateway.getPendingRemoteEvents() + expect(pending).toEqual([{ event: 'fixture/ask', agentId: 'agent-1' }]) + expect(pending).not.toBe(ctx.typertGateway.getPendingRemoteEvents()) + expect(pending[0]).not.toBe(ctx.typertGateway.getPendingRemoteEvents()[0]) await expect(ownerEvents.next()).resolves.toMatchObject({ value: { type: 'emit', event: 'fixture/notice' } }) await expect(ownerEvents.next()).resolves.toMatchObject({ value: { type: 'emit', event: 'fixture/shelf', args: ['s2'] } }) await expect(ownerEvents.next()).resolves.toMatchObject({ value: { type: 'emit', event: 'fixture/shelf', args: ['s1'] } }) diff --git a/packages/api/gateway/tests/gateway.client.spec.ts b/packages/api/gateway/tests/gateway.client.spec.ts index a7e0ca2560..3807baee59 100644 --- a/packages/api/gateway/tests/gateway.client.spec.ts +++ b/packages/api/gateway/tests/gateway.client.spec.ts @@ -866,7 +866,7 @@ describe('Client Typert API', () => { const ctx = await bench(call) const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext ctx.typert.contexts.registerClient('fixture', { - identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId, + identity: candidate => 'fixtureId' in candidate ? (candidate as Context & { fixtureId?: string }).fixtureId : undefined, resolve: id => id === 'agent-2' ? agentCtx : undefined, }) const assembly = ctx.plugin(Object.assign( @@ -897,7 +897,7 @@ describe('Client Typert API', () => { const ctx = await bench(call) const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext ctx.typert.contexts.registerClient('fixture', { - identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId, + identity: candidate => 'fixtureId' in candidate ? (candidate as Context & { fixtureId?: string }).fixtureId : undefined, resolve: id => id === 'agent-2' ? agentCtx : undefined, }) const assembly = ctx.plugin(Object.assign( @@ -943,7 +943,7 @@ describe('Client Typert API', () => { const ctx = await bench(call) const agentCtx = ctx.extend({ fixtureId: 'agent-remounted' }) as FixtureContext ctx.typert.contexts.registerClient('fixture', { - identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId, + identity: candidate => 'fixtureId' in candidate ? (candidate as Context & { fixtureId?: string }).fixtureId : undefined, resolve: id => id === 'agent-remounted' ? agentCtx : undefined, }) const direct = directDescriptor() diff --git a/packages/api/gateway/tests/gateway.host.spec.ts b/packages/api/gateway/tests/gateway.host.spec.ts index 4272ee90bb..2931b3d159 100644 --- a/packages/api/gateway/tests/gateway.host.spec.ts +++ b/packages/api/gateway/tests/gateway.host.spec.ts @@ -75,14 +75,14 @@ class GoalService extends Service { return { agentId: agent.id, title: request.title, - scope: (this.ctx as MarkedContext).fixtureScope ?? 'root', + scope: 'fixtureScope' in this.ctx ? (this.ctx as MarkedContext).fixtureScope : 'root', } } @RemoteScope('gatewayFixture') rename(request: { readonly title: string }): unknown { this.calls.push('rename') - return { title: request.title, scope: (this.ctx as MarkedContext).fixtureScope ?? 'root' } + return { title: request.title, scope: 'fixtureScope' in this.ctx ? (this.ctx as MarkedContext).fixtureScope : 'root' } } @Remote diff --git a/packages/api/job-controller/package.json b/packages/api/job-controller/package.json index 40649ebff3..c550f1f912 100644 --- a/packages/api/job-controller/package.json +++ b/packages/api/job-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-job-controller", "description": "Job Remote observation stream and the reference-counted client job-output service", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/remote-access/README.i18n.yaml b/packages/api/remote-access/README.i18n.yaml index 14239cd17a..a95b536e3c 100644 --- a/packages/api/remote-access/README.i18n.yaml +++ b/packages/api/remote-access/README.i18n.yaml @@ -15,8 +15,8 @@ en: a18ecc232e3c3933 zh: b8e43580403f6d77 /deepseek-ai-dsh-api-remote-access/host-service-remoteaccessservice-ctx-key-remoteaccess: - en: 757a6bdf95e824c6 - zh: e8ae9712ad28c2f3 + en: 3d009c4a86374cbf + zh: ba3c624639ed18b9 /deepseek-ai-dsh-api-remote-access/client-face: en: d4cf8f646fdf2d39 zh: 247f643e991aa806 diff --git a/packages/api/remote-access/README.md b/packages/api/remote-access/README.md index f1ddf064d1..f888679c15 100644 --- a/packages/api/remote-access/README.md +++ b/packages/api/remote-access/README.md @@ -39,6 +39,8 @@ A role `{ name, resource, actions }` is a plain value naming an action set over The Gateway resolves resources from `@Remote` and `@RemoteScope` `resources` readers, lookup and Host Context adapter `resource` declarations, and the default field or resolver declarations in `typert.resources`, and the [API Gateway](../gateway/README.md) owns that order; this package reads no argument field. A call that names no resource touches the `global` resource alone, so only a `global` role can allow it; putting an action in a `global` role lets the principal call it on any resource the call does not name. The Gateway refuses a call whose resources are invalid with `resource-invalid` without asking `decide()`. +Policy authors must treat `session/attachment` as access to the entire attachment store: granting that action on any one Session resource lets the caller supply that `sessionId` and read images referenced by other Sessions or by none. Gateway still checks that Session resource, but the handler checks neither Session existence nor image membership. Use separate Host instances with separate `DSH_HOME` directories when readers require separate image stores; see the [image access rule](../../../.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.md). + When `bindings()`, a condition, or `explain()` throws, the decision is refused with `policy-failed`; in a snapshot, a throwing `bindings()` leaves the principal no grant and a throwing condition excludes its action. A faulty rule therefore never breaks the shared `$events` source, the snapshot stream, or page rendering. The service logger reports the first failure of each policy after each `invalidate()` and each policy registration or removal; later failures of that policy stay silent until then. A forwarded event is decided as the action `event:` on the resources its forwarding entry's readers name, or on `global` when the entry declares none, and reaches a non-owner whole or not at all; its payload is never trimmed. An event carries every resource it declares, so a reader that returns `undefined` makes the event's resources invalid, and the Gateway delivers it to no non-owner without asking `decide()`. An event names at most one resource, so collection changes travel on follow streams (`session/follow`, `session/control`, `workspace/follow`), whose methods decide each item inline through `allows()`. diff --git a/packages/api/remote-access/README.zh.md b/packages/api/remote-access/README.zh.md index bcd8e77324..ab073ed7c0 100644 --- a/packages/api/remote-access/README.zh.md +++ b/packages/api/remote-access/README.zh.md @@ -39,6 +39,8 @@ role `{ name, resource, actions }` 是普通值，表示限定一种资源种类 Gateway 依次从 `@Remote` 与 `@RemoteScope` 的 `resources` 读取函数、lookup 与 Host Context adapter 的 `resource` 声明、`typert.resources` 中的默认字段或 resolver 声明解析资源，解析顺序由 [API Gateway](../gateway/README.zh.md) 负责；本包不读取任何参数字段。不指明任何资源的调用只访问 `global` 资源，因此只有 `global` 级 role 能放行；把某个 action 放进 `global` 级 role，等于允许该 principal 在调用未指明的任何资源上调用它。资源非法的调用由 Gateway 以 `resource-invalid` 拒绝，不询问 `decide()`。 +policy 作者必须把 `session/attachment` 视为整个附件存储的读取权限：在任意一条 Session 资源上授予该 action，就允许调用方使用这个 `sessionId` 读取其他 Session 引用或未被任何 Session 引用的图片。Gateway 仍检查该 Session 资源，但处理函数既不检查 Session 是否存在，也不检查图片关联。需要让不同读者使用不同图片存储时，须使用独立 Host 实例及各自的 `DSH_HOME` 目录；见[图片访问规则](../../../.agents/notes/implemented/architecture/2026-10-23-store-scoped-image-reads.zh.md)。 + `bindings()`、condition 或 `explain()` 抛错时，本次判定以 `policy-failed` 拒绝；计算快照时，`bindings()` 抛错即该 principal 没有 grant，condition 抛错即该 action 不放行。有问题的规则因此不会破坏共享的 `$events` 事件源、快照流或页面渲染。每次 `invalidate()` 以及每次 policy 注册或撤回之后，服务日志对每个 policy 只报告第一次失败；此后该 policy 的失败不再记录，直到下一次上述变化。 转发事件按其转发条目的读取函数指明的资源（条目未声明时为 `global`）判定 action `event:`，对非 owner 整条送达或整条不送，从不裁剪 payload。事件携带其声明的每个资源，因此读取函数返回 `undefined` 时该事件的资源非法，Gateway 不询问 `decide()`，不送达任何非 owner。一个事件至多指明一个资源，因此集合类变化走 follow 类流（`session/follow`、`session/control`、`workspace/follow`），由这些方法内联经 `allows()` 逐项判定。 diff --git a/packages/api/remote-access/package.json b/packages/api/remote-access/package.json index f4e3e13975..5e81e757c2 100644 --- a/packages/api/remote-access/package.json +++ b/packages/api/remote-access/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-remote-access", "description": "Method-level Remote access control for non-owner Peers and the per-Peer access snapshot", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json index 288aabea9b..8735bc4339 100644 --- a/packages/api/remotes/package.json +++ b/packages/api/remotes/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-remotes", "description": "Remote BFF assembly for application-selected Host capabilities", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -98,6 +98,7 @@ "@deepseek-ai/dsh-office-to-pdf": "workspace:*", "@deepseek-ai/dsh-api-account-controller": "workspace:*", "@deepseek-ai/dsh-deepseek-account": "workspace:*", - "@deepseek-ai/dsh-client-product-analytics": "workspace:*" + "@deepseek-ai/dsh-client-product-analytics": "workspace:*", + "@deepseek-ai/dsh-client-ui-trajectory": "workspace:*" } } diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts index da6f814458..8a4b7dea8a 100644 --- a/packages/api/remotes/src/client/index.ts +++ b/packages/api/remotes/src/client/index.ts @@ -14,6 +14,7 @@ import scheduleRemote from '@deepseek-ai/dsh-schedule/remote' import llmRemote from '@deepseek-ai/dsh-llm/remote' import dynamicRemote from '@deepseek-ai/dsh-cordis-host-runner/remote' import pluginManagerRemote from '@deepseek-ai/dsh-plugin-manager/remote' +import toolResultsRemote from '@deepseek-ai/dsh-client-ui-trajectory/remote' import pluginRegistryProbeRemote from '@deepseek-ai/dsh-client-ui-plugin-manager/remote' import pluginMarketRemote from '@deepseek-ai/dsh-plugin-market/remote' import pluginInventoryRemote from '@deepseek-ai/dsh-host-plugin-inventory/remote' @@ -41,6 +42,7 @@ export type { } from '@deepseek-ai/dsh-plugin-manager/types' export type {} from '@deepseek-ai/dsh-plugin-manager/remote' export type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/remote' +export type {} from '@deepseek-ai/dsh-client-ui-trajectory/remote' export type {} from '@deepseek-ai/dsh-plugin-market/remote' export type { MarketCompatibility, MarketIndexSummary, MarketInstallation, MarketInstallationStatus, MarketListingEntry, MarketListingVersion, @@ -189,7 +191,7 @@ export async function apply(ctx: Context): Promise<() => Promise> { for (const contribution of [ productAnalyticsRemote, agentPresetsRemote, commandsRemote, settingsControllerRemote, accountRemote, goalsRemote, llmRemote, dynamicRemote, scheduleRemote, - pluginInventoryRemote, pluginManagerRemote, pluginMarketRemote, pluginRegistryProbeRemote, + pluginInventoryRemote, pluginManagerRemote, pluginMarketRemote, pluginRegistryProbeRemote, toolResultsRemote, messageFeedbackRemote, sessionFeedbackRemote, fileUploadsRemote, sessionReferencesRemote, permissionPresetsRemote, subagentsRemote, sessionRemote, jobRemote, workspaceRemote, workspaceFilesRemote, terminalRemote, diff --git a/packages/api/remotes/src/remote-events.ts b/packages/api/remotes/src/remote-events.ts index ef4ac40a45..38f87e99b4 100644 --- a/packages/api/remotes/src/remote-events.ts +++ b/packages/api/remotes/src/remote-events.ts @@ -44,6 +44,7 @@ export const API_REMOTE_FORWARDED_EVENTS = [ { event: 'cordis/inspect-query', mode: 'emit' }, { event: 'cordis/inspect-query-resolved', mode: 'emit' }, { event: 'llm/adapters-updated', mode: 'emit' }, + { event: 'llm/models-updated', mode: 'emit' }, { event: 'permission-presets/catalog-changed', mode: 'emit' }, { event: 'plugin-manager/changed', mode: 'emit' }, { event: 'plugin-manager/install-log', mode: 'emit' }, diff --git a/packages/api/remotes/tests/built-lib.e2e.ts b/packages/api/remotes/tests/built-lib.e2e.ts index 2c22aff84f..07d0ef5618 100644 --- a/packages/api/remotes/tests/built-lib.e2e.ts +++ b/packages/api/remotes/tests/built-lib.e2e.ts @@ -184,7 +184,7 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => { await client.plugin({ inject: plugin.inject, apply: plugin.apply }) } client.typert.contexts.registerClient('agent', { - identity: candidate => candidate.builtAgentId, + identity: candidate => 'builtAgentId' in candidate ? candidate.builtAgentId : undefined, }) const invalidResult = await client.remote.goals.create(rootAgent.id, { objective: 1 }) diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index a73004b041..fb96bac533 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -15,8 +15,8 @@ en: 1fdf707322fb6996 zh: 0204f7e9d4aa3cce /session-controller/use-this-package: - en: c434899916e46149 - zh: 477212470275c225 + en: 25c9c54037dc7971 + zh: 7fa87a380b046afb /session-controller/client-references: en: e8979a803ec3e194 zh: c567efcd971728ba diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index e6fdb9c7f1..4ce2afd480 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -33,9 +33,11 @@ History pages and follow opening snapshots carry one `{ type: 'event', event: Se The Client journal validates current Session event envelopes before publishing follow snapshots, live entries, or history pages. It reuses the browser-safe Session validators for required surface markers, exact replacement endpoints, earlier unique source seqs, embedded Assistant provider metadata, request-header omissions, and tool-error consistency. Invalid records fail without field stripping or normalization; range membership and source existence remain durable-log checks on the Host. -Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. A receipt names a staged file or a staged image, and an image receipt subjects the prompt to the same image-input check as an encoded image. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence, determined by `origin: 'subagent'`, to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent's effective working directory and scoped registry when present. Cold listing uses the projected current directory, falling back to the recorded origin and then the configured directory default. It retains the preset standing scope without activating an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` normally reads an exact baseline, including current-format cold logs, and returns `kind: sequenced`. Only a read requiring migration returns `kind: migration-required` hints without `asOfSeq`; missing keys remain absent. It returns null for a missing Session. Fork callers may set `allowMigration: false` to receive `session/migration-required` instead of starting source migration; omission retains automatic migration. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Sequenced reads and live projection frames use the same sequence ordering; cached reads fill hints without replacing sequenced values. +Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. A receipt names a staged file or a staged image, and an image receipt subjects the prompt to the same image-input check as an encoded image. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and the subagent ownership fence determined by `origin: 'subagent'` to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent's effective working directory and scoped registry when present. Cold listing uses the projected current directory, falling back to the recorded origin and then the configured directory default. It retains the preset standing scope without activating an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` normally reads an exact baseline, including current-format cold logs, and returns `kind: sequenced`. Only a read requiring migration returns `kind: migration-required` hints without `asOfSeq`; missing keys remain absent. It returns null for a missing Session. Fork callers may set `allowMigration: false` to receive `session/migration-required` instead of starting source migration; omission retains automatic migration. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Sequenced reads and live projection frames use the same sequence ordering; cached reads fill hints without replacing sequenced values. -Every Remote endpoint is access-controlled: a Peer whose principal is not the owner reaches an endpoint only when, on every resource the call touches, a binding of that principal kind's policy in [`dsh-api-remote-access`](../remote-access/README.md) grants a role listing the action ([Peer principals Agent Note](../../../.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md)). The controller injects `remoteAccess` and registers a default resolver for the `session` resource kind through `typert.resources`. It reads a named `sessionId` parameter, otherwise the first object argument's `sessionId` or `address`; unrelated string parameters name no Session. An object containing both `sessionId` and `address` is invalid, even when they name the same Session. `session/page` and `session/follow` use this resolver to read `address.sessionId` for an ordinary Session address and `address.childSessionId` for a subagent address; whether access to the parent Session covers its children is the policy's rule. `session/projections` reads the Session resource from `request.sessionId`, so a reconnecting reader reloads only the projections of Sessions it may read. `session/list`, `session/search`, and `session/control` read no resource, so their calls touch the `global` resource and need a `global` role; for a non-owner caller, `session/list` returns only the rows, `session/search` only the hits, and `session/control` only the baseline projections and projection frames, whose Session `ctx.remoteAccess.allows()` admits for the same action, so that action also belongs to a `session` role; owner results are unfiltered. `session/prompt` builds the durable `user-rpc` message source in its Remote method and records `principal` only for a non-owner caller, read through `principalOf(this.ctx.invocation)`; a source without `principal` belongs to the owner. +Every Remote endpoint is access-controlled: a Peer whose principal is not the owner reaches an endpoint only when, on every resource the call touches, a binding of that principal kind's policy in [`dsh-api-remote-access`](../remote-access/README.md) grants a role listing the action ([Peer principals Agent Note](../../../.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md)). The controller injects `remoteAccess` and registers a default resolver for the `session` resource kind through `typert.resources`. It reads a named `sessionId` parameter, otherwise the first object argument's `sessionId` or `address`; unrelated string parameters name no Session. An object containing both `sessionId` and `address` is invalid, even when they name the same Session. `session/events`, the deprecated `session/page`, `session/observeEvent`, and `session/follow` use this resolver to read `address.sessionId` for an ordinary Session address and `address.childSessionId` for a subagent address; whether access to the parent Session covers its children is the policy's rule. `session/projections`, `session/observeProjections`, `session/state`, `session/observeState`, and `session/wait` read the Session resource from `request.sessionId`, so each call and subscription names only the Sessions it may read. `session/list`, `session/search`, and `session/control` read no resource, so their calls touch the `global` resource and need a `global` role; for a non-owner caller, `session/list` returns only the rows, `session/search` only the hits, and `session/control` only the baseline projections and projection frames, whose Session `ctx.remoteAccess.allows()` admits for the same action, so that action also belongs to a `session` role; owner results are unfiltered. `session/prompt` builds the durable `user-rpc` message source in its Remote method and records `principal` only for a non-owner caller, read through `principalOf(this.ctx.invocation)`; a source without `principal` belongs to the owner. + +`events` reads one chronological page from a durable cut and returns its records, `hasMore`, and an inclusive `cursor`; omitting `throughSeq` selects the observed log end, and the compatible `page` method carries the same read with a deprecated entry point. `events`, `observeEvent`, and `follow` take an Address; projection and state operations take a Session ID. Page reads and Follow openings validate the supplied Address. Pure `observeEvent` and `observeProjections` subscriptions neither acquire an Observation nor establish existence: their `ready` frame carries no snapshot cursor. List rows carry `formatStatus` when available, so Clients can identify migration-required Sessions without requesting their projections. @@ -55,7 +57,7 @@ Accepted prompts and observed running keep their Client display conversion acros The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, `append`, and `settle-assistant` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one Turn-aligned page, and `loadThrough(seq)` — the turn-jump loader — loops Turn-aligned pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. The Web adapter explicitly opts into cursorless Assistant frames: each opening carries the active attempt's `startedAfterSeq`, `nextIndex`, and compact stream, and every stream member becomes a Client-only `assistant/live-chunk` entry ordered between durable cursors. The Host captures a follower-local arrival ordinal with that baseline and suppresses buffered frames at or before the cut; a replacement Agent may restart frame revision at one. A durable `assistant/message` or `assistant/attempt` arriving after an active opening stays staged only when its seq follows `startedAfterSeq` and its Turn and Step match; the matching end type, seq, and index releases the durable entry. A successful message retains its transient rows until the owning `step/end`, so pending tool identities remain available for dispatch. Failed or interrupted settlements retire their rows immediately; earlier same-step retries remain visible. Revision, dense-index, or settlement gaps for a known attempt reopen follow, while a controller that missed the start ignores unknown-attempt frames and publishes their durable settlement normally. An abandoned end publishes a settlement delta without a durable entry so its transient rows retire immediately. A durable gap-repair page has no Assistant baseline, so its held notification reopens follow once for a paired page and baseline. Every history record covers exactly its event seq. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces projection state instead of treating transient values as durable events. At each ready Host generation, a synchronous Client subscription clears retained projection values and watermarks before refreshing queries and restarting the control stream, including Sessions absent from the control baseline. The first control stream waits for generation readiness, so its opening values cannot precede invalidation. Outstanding list responses from the previous generation cannot republish those values. Within a generation, a delayed control baseline cannot overwrite or clear newer sequenced values, whether they arrived through a live Session's list block, a history page, or a frame; a cached list block, viewed from the projection cache for a cold Session, yields to the connected Session's baseline whatever watermark it carries. The durable `inbox` projection carries both pending lists through the same cold-read and reconnect path as other projections. Client Agent contexts provide the identity used by the independent [`fileUpload`](../../client/file-upload/README.md) service; Session objects expose lifecycle, prompt, queue, and history operations rather than file transfer. -The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The echo stores ordered image previews and durable file references. Session derives its `transcript`, `queued`, or `steering` placement from the current running state and requested delivery mode, then retains that placement until the display handoff. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, including pending messages in the `inbox` projection. Queued echoes retire one animation frame after queue acceptance; Chat echoes follow the admission rule below. Identified failures and abandonment retire unadmitted echoes immediately. Disposal preserves observed admission and fails other unsettled submissions. Each retirement fires `onRetire` exactly once; an observed retirement includes the ordered durable attachment references so the composer can release successful cards while preserving failed drafts. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. +The Session object also carries local submission echoes: `session.beginSubmission` registers one before the caller serializes and prompts, and Session publishes it in `SessionSnapshot.pendingSubmissions` once the Host has accepted the prompt, as the `prompt` receipt or an `inbox` row carrying the request id shows, whichever arrives first. A conversation UI therefore shows the message from acceptance until its durable entry renders, and Chat and QueueDock exclude the matching Inbox row from the moment it arrives. The blank-to-engaging transition happens at the same acceptance. The echo stores ordered image previews and durable file references. Session derives its `transcript`, `queued`, or `steering` placement from the current running state and requested delivery mode, then retains that placement until the display handoff. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, including pending messages in the `inbox` projection. Queued echoes retire one animation frame after queue acceptance; Chat echoes follow the admission rule below. Identified failures and abandonment retire unadmitted echoes immediately. Disposal preserves observed admission and fails other unsettled submissions. Acceptance fires `onAccept` once, in the same update that publishes the echo, so the sender can settle its composer together with the echo. Each retirement fires `onRetire` exactly once; an observed retirement includes the ordered durable attachment references so the sender can release or hand over the sent attachments. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. During uninterrupted following, transcript and steering echoes stay in Chat through Inbox acceptance and claim until their durable messages arrive. After a local Chat message is admitted, its identity remains until the Inbox watermark reaches its next-turn or next-step claim seq: Chat already renders the durable Node, while Chat and QueueDock exclude matching stale Inbox rows. Other queued messages remain visible. A replacement follow baseline withdraws receipt-confirmed echoes as observed, using their accepted attachment references; unconfirmed submissions remain pending. Host data then supplies the pending or admitted rows. Reconnecting between claim and admission can briefly omit that bubble; withdrawal confirms acceptance, not execution or failure. @@ -72,7 +74,7 @@ The Client's initial `follow`, reconnect openings, and `loadOlder()` request at Queue edits replace pending content with non-empty text only. -Attachment authorization reads declared content fields of built-in Session events and completed assistant stream blocks, including flat V4 tool-role messages. Unknown event payloads and unrelated fields cannot authorize attachment reads. +`session.attachment` receives `{ sessionId, attachment: ImageAttachmentRef }` and passes the complete reference to `AttachmentStore.readImage()`, without reading or traversing Session history. The Client supplies the message's reference through `session.readAttachment(ref)`. Connection authentication and Gateway permission checks still apply; `sessionId` selects the Session resource for the endpoint's permission check. After authorization, the handler does not check whether that Session exists and does not return `session/not-found` merely because it is absent. An authorized caller may read any image in the same store, including an image referenced only by another Session or by no Session. The response preserves the supplied reference after verifying its ID, media type, byte length, width, and height against the stored bytes. Optional `name` and `originalDimensions` pass through as caller-supplied display information and are not verified against the file. Missing or invalid objects return a terminal attachment failure. The Client's historical-image cache retains one result and browser URL per Session and attachment ID. The controller composes `ArchivedSessionGate` through `ctx.plugin`: it loads once the Agent registry, Session store, and Workspace registry exist and unwinds with the controller. Its `agent/pre-step` listener rejects a step proposed for an archived Session or for a subagent descendant of one — read through available Session headers, never a fork — so a late waking delivery ends its turn as `blocked` without a model request; unarchiving lifts the gate for the whole lineage. The Subagent runtime separately checks retained creation ancestors, covering managed descendants whose intermediate creators are offline. The work an archived Session still runs is reported and stopped by its owners through the Workspace registry's archive admission ([seam](../../workspace/workspace/README.md)): the running turn by the [Agent registry](../../core/agent/README.md), owned jobs by the [job registry seam](../../jobs/jobs/README.md), subagent descendants by the [Subagent](../../subagent/subagent/README.md) runtime, reminders by the [Schedule](../../schedule/schedule/README.md) plugin; this controller reports nothing itself. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 04bb7d89fc..0aecad0564 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -33,9 +33,11 @@ kind: "package-reference" Client journal 在发布 follow 快照、live entry 或历史页之前验证当前 Session 事件 envelope。它复用浏览器安全的 Session validator，检查必需的 surface marker、精确的 replacement endpoint、更早且唯一的 source seq、内嵌 Assistant 提供方元数据、request header 可选字段的省略规则以及工具错误一致性。无效 record 直接失败，不删除字段或归一化；范围成员与来源存在性仍由 Host 的持久日志检查。 -每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。凭证指向一个暂存文件或一张暂存图片；图片凭证与编码图片一样要经过图片输入检查。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和由 `origin: 'subagent'` 确定的 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent 的有效工作目录与限定范围内的注册表。冷态列表使用投影中的当前目录，依次回退到记录的起始目录与配置的默认目录。它保留 preset 常驻 scope，不会激活 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 正常读取准确基线，包括当前格式的冷日志，返回 `kind: sequenced`。只有需要迁移时才返回不带 `asOfSeq` 的 `kind: migration-required` 提示，缺少的键保持缺席。Session 不存在时返回 null。Fork 调用者可设置 `allowMigration: false`，在源历史需要迁移时收到 `session/migration-required`；省略则保持自动迁移。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。有序读取与实时 projection 帧使用相同的序号排序规则；缓存读取只补充提示，不替换有序值。 +每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。凭证指向一个暂存文件或一张暂存图片；图片凭证与编码图片一样要经过图片输入检查。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和由 `origin: 'subagent'` 确定的 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent 的有效工作目录与限定范围内的注册表。冷态列表使用投影中的当前目录，依次回退到记录的起始目录与配置的默认目录。它保留 preset 常驻 scope，不会激活 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 正常读取准确基线，包括当前格式的冷日志，返回 `kind: sequenced`。只有需要迁移时才返回不带 `asOfSeq` 的 `kind: migration-required` 提示，缺少的键保持缺席。Session 不存在时返回 null。Fork 调用者可设置 `allowMigration: false`，在源历史需要迁移时收到 `session/migration-required`；省略则保持自动迁移。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。有序读取与实时 projection 帧使用相同的序号排序规则；缓存读取只补充提示，不替换有序值。 -每个 Remote 端点都受访问控制：principal 不是 owner 的 Peer 只有在本次调用访问的每个资源上，该 principal kind 在 [`dsh-api-remote-access`](../remote-access/README.zh.md) 中的 policy 都有某个 binding 授予列出该 action 的 role 时，才能调用该端点（[Peer 身份属性 Agent Note](../../../.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md)）。控制器注入 `remoteAccess`，并经 `typert.resources` 为 `session` 资源种类登记默认 resolver。它读取具名 `sessionId` 参数，否则读取第一个对象参数的 `sessionId` 或 `address`；无关字符串参数不指明 Session。对象同时包含 `sessionId` 和 `address` 时无效，即使两者指向同一 Session。`session/page` 与 `session/follow` 使用该 resolver：对普通 Session 地址读 `address.sessionId`，对 subagent 地址读 `address.childSessionId`；父会话的访问权是否覆盖其子会话由 policy 决定。`session/projections` 从 `request.sessionId` 读取会话资源，因此重连的读者只会重新读取它可读的会话的 projections。`session/list`、`session/search` 与 `session/control` 不读取资源，其调用访问 `global` 资源，需要 `global` role；对非 owner 调用方，`session/list` 只返回其 Session 被 `ctx.remoteAccess.allows()` 按同一 action 允许的行，`session/search` 只返回这类 Session 的命中，`session/control` 也只返回这类 Session 的 baseline projection 与 projection 帧，因此该 action 也要列在 `session` role 中；owner 的结果不过滤。`session/prompt` 在其 Remote 方法内构造持久的 `user-rpc` 消息 source，且只为非 owner 调用方记录经 `principalOf(this.ctx.invocation)` 读取的 `principal`；不带 `principal` 的 source 属于 owner。 +每个 Remote 端点都受访问控制：principal 不是 owner 的 Peer 只有在本次调用访问的每个资源上，该 principal kind 在 [`dsh-api-remote-access`](../remote-access/README.zh.md) 中的 policy 都有某个 binding 授予列出该 action 的 role 时，才能调用该端点（[Peer 身份属性 Agent Note](../../../.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md)）。控制器注入 `remoteAccess`，并经 `typert.resources` 为 `session` 资源种类登记默认 resolver。它读取具名 `sessionId` 参数，否则读取第一个对象参数的 `sessionId` 或 `address`；无关字符串参数不指明 Session。对象同时包含 `sessionId` 和 `address` 时无效，即使两者指向同一 Session。`session/events`、已弃用的 `session/page`、`session/observeEvent` 与 `session/follow` 使用该 resolver：对普通 Session 地址读 `address.sessionId`，对 subagent 地址读 `address.childSessionId`；父会话的访问权是否覆盖其子会话由 policy 决定。`session/projections`、`session/observeProjections`、`session/state`、`session/observeState` 与 `session/wait` 从 `request.sessionId` 读取会话资源，因此每次调用与订阅都只点名它可读的会话。`session/list`、`session/search` 与 `session/control` 不读取资源，其调用访问 `global` 资源，需要 `global` role；对非 owner 调用方，`session/list` 只返回其 Session 被 `ctx.remoteAccess.allows()` 按同一 action 允许的行，`session/search` 只返回这类 Session 的命中，`session/control` 也只返回这类 Session 的 baseline projection 与 projection 帧，因此该 action 也要列在 `session` role 中；owner 的结果不过滤。`session/prompt` 在其 Remote 方法内构造持久的 `user-rpc` 消息 source，且只为非 owner 调用方记录经 `principalOf(this.ctx.invocation)` 读取的 `principal`；不带 `principal` 的 source 属于 owner。 + +`events` 从一个持久切点读取一页时间正序的记录，返回记录、`hasMore` 和包含末项的 `cursor`；省略 `throughSeq` 时选取观察到的日志末尾，兼容的 `page` 方法提供同样的读取，但入口已弃用。`events`、`observeEvent` 和 `follow` 接收 Address，投影和状态操作接收 Session ID。分页读取与 Follow 开场会校验传入的 Address。纯 `observeEvent` 和 `observeProjections` 订阅既不获取 Observation，也不确认实体存在：其 `ready` 帧不携带快照游标。 列表行在状态可用时携带 `formatStatus`，Client 无需请求其投影即可识别需要迁移的 Session。 @@ -55,7 +57,7 @@ Client 列表刷新保留未变化的行对象，并在顺序和值均相同时 Client 适配器提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend`、`append` 与 `settle-assistant` 变更，并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词：`loadOlder()` 拉一页按轮次开头对齐的历史，而 `loadThrough(seq)`——轮次跳转加载器——按轮次开头对齐页面循环拉取直到窗口覆盖目标 seq，重复调用会下调共享目标，遇到无进展的页即停止，忙碌状态复用同一个 `loadingOlder` 快照位。Web 适配器显式选择接收无 cursor 的 Assistant frame：每个 opening 携带活跃 attempt 的 `startedAfterSeq`、`nextIndex` 与紧凑 stream，每个 stream member 都成为排在持久 cursor 之间的 Client-only `assistant/live-chunk` 条目。Host 会随该 baseline 捕获 follower 本地到达序号，并抑制该 cut 及之前的 buffered frame；replacement Agent 可以从 revision 一重新开始。活跃 opening 之后到达的持久 `assistant/message` 或 `assistant/attempt` 只有在其 seq 晚于 `startedAfterSeq` 且轮次与步骤匹配时才会保持暂存；匹配的 end type、seq 与 index 会发布持久条目。成功消息的瞬态 row 保留到所属 `step/end`，让待派发工具的身份持续可用；失败或中断的 settlement 立即移除对应 row，同一步骤中更早的 retry 仍然保留。已知 attempt 的 revision、密集 index 或 settlement 缺口会重新打开 follow；若 controller 错过 start，则忽略 unknown-attempt frame，并正常发布其持久 settlement。Abandoned end 会发布不含持久条目的 settlement delta，使瞬态 row 立即退出。持久缺口修复 page 不携带 Assistant baseline，因此 held notification 会重新打开 follow 一次，以取得配对的 page 与 baseline。每条历史 record 只覆盖自身的事件 seq。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 projection 状态，而不会把瞬态值当作 durable event。每次 Host generation 就绪时，同步的 Client 订阅会先清除保留的投影值及其水位，再刷新查询并重新打开 control stream，其中也包括 control baseline 中没有列出的 Session。首次 control stream 会等待 generation 就绪，确保其 opening 值不会先于旧状态清理到达。上一代尚未完成的 list 响应无法重新发布这些值。同一 generation 内，延迟到达的 control baseline 不能覆盖或清除较新的 sequenced 值，无论它们来自活 Session 的 list block、history page 还是 frame；冷 Session 从 projection cache 看出来的 cached list block 则不论水位都让位于建连 Session 的 baseline。持久 `inbox` 投影通过与其他投影相同的冷读取和重连路径传输两份待处理列表。Client Agent 上下文提供独立 [`fileUpload`](../../client/file-upload/README.zh.md) 服务使用的身份；Session 对象提供生命周期、prompt、queue 与历史操作，不提供文件传输。 -Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与提示词之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。回显按顺序存放图片预览与持久文件引用。Session 根据当前运行状态与请求的投递模式推导其 `transcript`、`queued` 或 `steering` 位置，并保留该位置直到展示接管。提示词的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，`inbox` 投影中的待处理消息也保留同一 source。排队回显在队列接受后延迟一个动画帧退休；Chat 回显遵循下述入档规则。尚未入档的回显在带标识的提示词失败或被放弃时立即退休。销毁时保留已观察到的入档结果，其余未结算提交按 failed 退休。每次退休恰好触发一次 `onRetire`；observed 退休还会携带有序的持久附件引用，让 composer 释放成功卡片并保留失败草稿。回显只存在于 Client 内存；刷新与重连只从持久事件重建会话。 +Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与发送提示词之前登记一条回显，Host 接收该提示词后，Session 才把它公开在 `SessionSnapshot.pendingSubmissions` 中；`prompt` 的回执和带有该请求 id 的 `inbox` 行都能表明已接收，以先到者为准。因此会话 UI 从接收起显示消息，直到它的持久条目渲染出来，Chat 和 QueueDock 也从对应的 Inbox 行到达起就把它排除。新会话从空白进入 engaging 也发生在这次接收时。回显按顺序存放图片预览与持久文件引用。Session 根据当前运行状态与请求的投递模式推导其 `transcript`、`queued` 或 `steering` 位置，并保留该位置直到展示接管。提示词的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，`inbox` 投影中的待处理消息也保留同一 source。排队回显在队列接受后延迟一个动画帧退休；Chat 回显遵循下述入档规则。尚未入档的回显在带标识的提示词失败或被放弃时立即退休。销毁时保留已观察到的入档结果，其余未结算提交按 failed 退休。接收时触发一次 `onAccept`，与公开回显处于同一次更新，让发送方与回显同时结算输入框。每次退休恰好触发一次 `onRetire`；observed 退休还会携带有序的持久附件引用，让发送方释放或移交已发送的附件。回显只存在于 Client 内存；刷新与重连只从持久事件重建会话。 正常在线时，transcript 与 steering 回显在 Inbox 接受与领取期间留在 Chat，直到持久消息到达。本地 Chat 消息入档后，其身份保留到 Inbox 水位覆盖 next-turn 或 next-step 领取序号：Chat 已显示真实 Node，而 Chat 与 QueueDock 排除匹配的旧 Inbox 行。其他排队消息照常显示。新的 follow 基线会将已有接收回执的回显按 observed 撤去，使用已接受的附件引用完成结算；尚未确认接收的提交继续保留。待处理或已入档的消息随后由 Host 数据呈现。在领取与入档之间重连时，气泡可能短暂消失；撤去回显只确认接收，不代表执行或失败。 @@ -72,7 +74,7 @@ Client 的首次 `follow`、重连首屏与 `loadOlder()` 至少请求 50 条以 队列编辑仅允许用非空文本替换待处理内容。 -附件授权读取内置 Session 事件声明的内容字段与已完成的 assistant 流块，包括扁平的 V4 tool 角色消息。未知事件载荷与无关字段不能授权附件读取。 +`session.attachment` 接收 `{ sessionId, attachment: ImageAttachmentRef }`，并把完整引用交给 `AttachmentStore.readImage()`，不读取或遍历 Session 历史。Client 通过 `session.readAttachment(ref)` 传入消息中的引用。连接身份认证和 Gateway 权限检查仍然适用；`sessionId` 为该接口的权限检查指定 Session 资源。授权通过后，处理函数不检查该 Session 是否存在，也不会仅因其不存在而返回 `session/not-found`。获准调用的身份可以读取同一存储中的任意图片，包括仅被其他 Session 引用或未被任何 Session 引用的图片。响应在把 ID、媒体类型、字节数、宽度和高度与存储字节校验后，保留传入的引用。可选的 `name` 和 `originalDimensions` 作为调用方提交的显示信息原样返回，不根据文件校验。对象缺失或无效时返回明确的附件失败。Client 的历史图片缓存按 Session 和附件 ID 保留一份结果与浏览器 URL。 本控制器通过 `ctx.plugin` 组合 `ArchivedSessionGate`：在 Agent 注册表、Session store 与 Workspace 注册表就绪后加载，随控制器一起释放。它的 `agent/pre-step` 监听器会拒绝为已归档会话或其子代理子孙——沿可用的 Session header 读取，从不包括 fork——提出的步骤，因此迟到的唤醒投递会让该回合以 `blocked` 收口而不发出模型请求；取消归档即为整条血缘解除门禁。Subagent runtime 另行检查保留的创建祖先，覆盖中间创建者已离线的托管后代。已归档会话仍在跑的工作由各自的 owner 通过 Workspace 注册表的归档准入（[接缝](../../workspace/workspace/README.zh.md)）报告与停止：运行中的回合由 [Agent 注册表](../../core/agent/README.zh.md)负责，所属任务由[任务注册表接缝](../../jobs/jobs/README.zh.md)负责，子代理子孙由 [Subagent](../../subagent/subagent/README.zh.md) runtime 负责，提醒由 [Schedule](../../schedule/schedule/README.zh.md) 插件负责；本控制器自己不报告任何内容。 diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json index 0f7b7bb63e..4a7e14aa2b 100644 --- a/packages/api/session-controller/package.json +++ b/packages/api/session-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-session-controller", "description": "Session Remote commands, cold reads, and live control transport", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -73,6 +73,7 @@ "dependencies": { "@deepseek-ai/dsh-brand": "workspace:*", "@deepseek-ai/dsh-deque": "workspace:*", + "@deepseek-ai/dsh-timeout": "workspace:*", "@deepseek-ai/schemastery": "workspace:~", "mime-types": "^3.0.2", "zod": "4.4.3" @@ -131,6 +132,7 @@ "@deepseek-ai/dsh-agent-preset-registry": "workspace:*", "@deepseek-ai/dsh-api-gateway": "workspace:*", "@deepseek-ai/dsh-attachment": "workspace:*", + "@deepseek-ai/dsh-attachment-local": "workspace:*", "@deepseek-ai/dsh-client-connection": "workspace:*", "@deepseek-ai/dsh-client-file-upload": "workspace:*", "@deepseek-ai/dsh-client-store": "workspace:*", diff --git a/packages/api/session-controller/src/catalog.ts b/packages/api/session-controller/src/catalog.ts index 83ee7a8b93..842f15429f 100644 --- a/packages/api/session-controller/src/catalog.ts +++ b/packages/api/session-controller/src/catalog.ts @@ -44,6 +44,7 @@ export async function buildModelCatalog( name: model.name, ...(model.description === undefined ? {} : { description: model.description }), ...(reasoning === undefined ? {} : { reasoning }), + ...(model.badge === undefined ? {} : { badge: model.badge }), } })) return { diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts index 2c8f16c4ae..9233ac84cb 100644 --- a/packages/api/session-controller/src/client/contract/session.ts +++ b/packages/api/session-controller/src/client/contract/session.ts @@ -7,7 +7,7 @@ * must stub); implementation-internal entry points (history staging, wire-frame * dispatch) stay on the class, invisible out here. */ -import type { AttachmentIdType, FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' +import type { FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session/types' import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' @@ -36,6 +36,11 @@ export interface BeginSubmissionInput { readonly text: string /** Ordered image previews and durable file metadata matching the upcoming prompt attachments. */ readonly attachments: readonly PendingSubmissionAttachment[] + /** + * Called once when the Host accepted the prompt, in the same update that + * publishes the echo, whether the receipt or an Inbox row showed it first. + */ + readonly onAccept?: () => void /** Settlement callback fired exactly once when the echo retires. */ readonly onRetire?: (retirement: PendingSubmissionRetirement) => void } @@ -66,18 +71,24 @@ export interface ISession { /** Host-computed projection values by key (the useProjection seat). */ readonly projections: ProjectionsFace /** - * Register one local submission echo in `snapshot.pendingSubmissions`, - * synchronously, before the caller serializes and sends the prompt. The - * Chat echoes persist until durable admission; transcript identities also - * wait for the Inbox claim watermark so stale queue rows stay suppressed. - * Queued echoes retire on queue acceptance. Identified failures retire - * submissions that have not already reached durable admission. + * Register one local submission echo before the caller serializes and sends + * the prompt. The echo reconciles against Host events from then on, and + * enters `snapshot.pendingSubmissions` once the Host accepted the prompt: + * when {@link prompt} reports the receipt or an Inbox row carrying the + * request id arrives, whichever comes first. The Chat echoes persist until + * durable admission; transcript identities also wait for the Inbox claim + * watermark so stale queue rows stay suppressed. Queued echoes retire on + * queue acceptance. Identified failures retire submissions that have not + * already reached durable admission. * @param input - echo content and the optional settlement callback. * @returns the minted identity for {@link prompt} plus the pre-prompt abandon path. */ beginSubmission(input: BeginSubmissionInput): SubmissionHandle /** - * Send a prompt into the session. + * Send a prompt into the session. The Host can hold the prompt at its + * admission stage, so the call can stay open; acceptance publishes the + * prompt's echo and moves a blank Session to engaging, before the call + * returns when an Inbox row carrying the request id arrives first. * @param content - text plus browser-owned temporary image uploads. * @param mode - 'queue' appends a turn; 'steer' interrupts the running one. * @param signal - optional caller cancellation for the complete admission round-trip. @@ -91,12 +102,12 @@ export interface ISession { requestId?: SessionRequestId, ): Promise> /** - * Resolve one durable image referenced by this session. - * @param attachmentId - opaque id found in the folded session log. - * @returns the authenticated reference and decoded bytes. + * Resolve one stored image using this Session's gateway permission scope. + * @param attachment - complete image reference from the folded session log. + * @returns the supplied reference after storage verification, and decoded bytes. */ readAttachment( - attachmentId: AttachmentIdType, + attachment: ImageAttachmentRef, ): Promise> /** * Apply one edit, remove, or Steer action to a still-pending queue occurrence. diff --git a/packages/api/session-controller/src/client/contract/snapshot.ts b/packages/api/session-controller/src/client/contract/snapshot.ts index ae3f2abe9a..4912d19b16 100644 --- a/packages/api/session-controller/src/client/contract/snapshot.ts +++ b/packages/api/session-controller/src/client/contract/snapshot.ts @@ -38,10 +38,10 @@ export type PendingSubmissionAttachment = export type PendingSubmissionPlacement = 'transcript' | 'queued' | 'steering' /** - * One local prompt-submission echo: inserted synchronously when a submission - * begins, so the conversation can show the message before serialization, - * transport, and durable admission complete. Client-memory only — reload and - * reconnect rebuild the conversation from durable events alone. + * One local prompt-submission echo: registered when a submission begins and + * published once the Host accepts the prompt, so the conversation shows the + * message before its durable admission completes. Client-memory only — reload + * and reconnect rebuild the conversation from durable events alone. */ export interface PendingSubmission { /** The prompt RPC identity; the durable `user/message` source echoes it as `rpcId`. */ @@ -68,7 +68,7 @@ export interface PromptError { /** Immutable Session lifecycle and control snapshot. */ export interface SessionSnapshot { readonly sessionId: SessionId - /** Local prompt-submission echoes not yet observed as durable events or queue occurrences. */ + /** Local prompt-submission echoes the Host accepted and that are not yet observed as durable events or queue occurrences. */ readonly pendingSubmissions: readonly PendingSubmission[] readonly running: boolean readonly subagent: { diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts index 20b8532427..e74dd84422 100644 --- a/packages/api/session-controller/src/client/sessions/session.ts +++ b/packages/api/session-controller/src/client/sessions/session.ts @@ -3,7 +3,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { InboxState, InboxTarget } from '@deepseek-ai/dsh-agent/types' import { randomUUID } from '@deepseek-ai/dsh-util-crypto' -import type { AttachmentIdType, FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' +import type { FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { UserMessage } from '@deepseek-ai/dsh-llm/types' @@ -113,8 +113,8 @@ export class Session implements SessionFace { private address: SubagentAddress | undefined /** * Sticky send marker, private input of the composerPhase derivation: set - * synchronously before prompt()'s first await, never reset — the blank → - * engaging edge of the phase machine (see ComposerPhase). + * when the Host accepts a prompt, never reset — the blank → engaging edge of + * the phase machine (see ComposerPhase). */ private promptAttempted = false /** A first accepted prompt stays in the engaging phase until its turn is observable. */ @@ -124,8 +124,10 @@ export class Session implements SessionFace { private removed = false private promptError: PromptError | null = null private lastAgentError: string | null = null - /** Local submission echoes, insertion-ordered (see SessionSnapshot.pendingSubmissions). */ + /** Local submission echoes, insertion-ordered, including those the Host has not accepted yet. */ private pendingSubmissions: readonly PendingSubmission[] = [] + /** The accepted echoes, published as SessionSnapshot.pendingSubmissions; rebuilt when one is accepted or removed. */ + private acceptedSubmissions: readonly PendingSubmission[] = [] /** Per-echo settlement state; `retiring` latches the first observation so a * Inbox projection and its durable event cannot both retire one echo. */ private readonly submissionSettlements = new Map void) | undefined readonly onRetire?: ((retirement: PendingSubmissionRetirement) => void) | undefined retiring: boolean }>() @@ -215,9 +220,10 @@ export class Session implements SessionFace { // ---- Operations ---- /** - * Register one local submission echo (see the ISession declaration). - * Synchronous through markDirty: the echo is in the very next snapshot, so - * the conversation can paint it before the caller starts serializing. + * Register one local submission echo (see the ISession declaration). The + * echo reconciles against Host events from now on, but it enters the + * snapshot only once the prompt receipt or an Inbox row carrying its + * request id shows that the Host accepted it. * @param input - echo content and the optional settlement callback. * @returns the minted identity for {@link prompt} plus the pre-prompt abandon path. */ @@ -231,16 +237,17 @@ export class Session implements SessionFace { text: input.text, attachments: input.attachments, }] - this.submissionSettlements.set(requestId, { placement, onRetire: input.onRetire, retiring: false }) - // The blank → engaging edge flips here, ahead of prompt(): the composer - // docks and the echo renders on the click's own frame. - this.promptAttempted = true - this.notifier.markDirty() + this.submissionSettlements.set(requestId, { + placement, accepted: false, onAccept: input.onAccept, onRetire: input.onRetire, retiring: false, + }) return { requestId, abandon: () => { this.retireFailedSubmission(requestId) } } } /** - * Send (queue/steer passed through 1:1); failures land in the snapshot's promptError. + * Send (queue/steer passed through 1:1); failures land in the snapshot's + * promptError. The Host can hold the prompt at its admission stage, so the + * call can stay open; the echo appears and the blank → engaging edge flips + * only once the Host accepts the prompt. * @param content - text, browser-owned temporary image uploads, and staged-file receipts. * @param mode - queue appends after the current turn; steer interrupts it. * @param signal - optional caller cancellation for the complete admission round-trip. @@ -255,12 +262,9 @@ export class Session implements SessionFace { ): Promise> { this.promptError = null this.lastAgentError = null - // Synchronous, before the first await: the blank → engaging edge must be - // visible on the session area's very first frame when a caller sends - // ahead of navigation (first-send flow). - this.promptAttempted = true - if (this.blankBit) this.firstPromptPendingTurn = true - this.notifier.markDirty() + // Before the first await, so a turn observed ahead of the receipt clears it. + const firstPrompt = this.blankBit && !this.firstPromptPendingTurn + if (firstPrompt) this.firstPromptPendingTurn = true let result: RemoteResult<{ accepted: true }> if (this.address === undefined) { const clientTimeZone = resolvedClientTimeZone() @@ -294,31 +298,50 @@ export class Session implements SessionFace { result = routed.ok ? { ok: true, value: { accepted: true } } : routed } if (!result.ok) { + // Rejection must leave a first prompt blank and eligible for workspace reuse. + if (firstPrompt) this.firstPromptPendingTurn = false if (requestId !== undefined) this.retireFailedSubmission(requestId) this.promptError = { op: 'send', error: result.error } this.notifier.markDirty() return result } - // Rejection must leave a first prompt blank and eligible for workspace reuse. - if (this.blankBit) { - this.blankBit = false - this.notifier.markDirty() - } - this.options.onEngaged?.(this) + this.acceptPrompt(requestId) return result } /** - * Resolve one image referenced by this session into browser-consumable bytes. - * @param attachmentId - opaque id found in the folded session log. - * @returns the authenticated reference and decoded bytes. + * Apply the Host's acceptance of one prompt: publish its echo, move a blank + * Session to engaging, and tell the submitter. The prompt receipt and an + * Inbox row carrying the prompt's request id both prove acceptance. + * Whichever arrives first publishes the echo; a later proof for an echo + * still pending changes nothing. + * @param requestId - identity from {@link beginSubmission}; absent for a prompt sent without an echo. + */ + private acceptPrompt(requestId: SessionRequestId | undefined): void { + const settlement = requestId === undefined ? undefined : this.submissionSettlements.get(requestId) + if (settlement?.accepted === true) return + if (settlement !== undefined) { + settlement.accepted = true + this.refreshAcceptedSubmissions() + } + this.promptAttempted = true + this.blankBit = false + this.notifier.markDirty() + this.options.onEngaged?.(this) + settlement?.onAccept?.() + } + + /** + * Resolve one stored image into browser-consumable bytes using this Session's gateway permission scope. + * @param attachment - complete image reference from the folded session log. + * @returns the supplied reference after storage verification, and decoded bytes. */ async readAttachment( - attachmentId: AttachmentIdType, + attachment: ImageAttachmentRef, ): Promise> { const result = await this.remote.session.attachment({ sessionId: this.sessionId, - attachmentId, + attachment, }) if (!result.ok) return result const binary = atob(result.value.data) @@ -755,7 +778,10 @@ export class Session implements SessionFace { } } this.observeSubmissionInsertions(target, inserted, start, event.seq) - for (const message of inserted) this.observeSubmissionMessage(message, false) + // A queued echo waits for the inbox projection the queue dock renders, which can arrive after this + // event; retiring it here would empty the dock for a frame. A claim in the same projection notification + // still retires it through the durable user message. + for (const message of inserted) this.observeSubmissionMessage(message, false, false) return } if (event.type === 'request/context' || event.type === 'turn/end') { @@ -773,19 +799,24 @@ export class Session implements SessionFace { const source = message.source if (source.kind !== 'user' || !('rpcId' in source)) continue const settlement = this.submissionSettlements.get(source.rpcId) - if (settlement === undefined || settlement.placement === 'queued' - || settlement.retiring || (settlement.receipt?.seq ?? -1) > seq) continue + if (settlement === undefined || settlement.retiring || (settlement.receipt?.seq ?? -1) > seq) continue + // Either proof accepts a prompt; an Inbox row can reach the Client before the prompt receipt. Later splices + // move the recorded position, so a canceled splice that removes the row retires its echo, queued ones + // included; a queued echo otherwise leaves once the queue dock renders its row or its message is admitted. settlement.receipt = { target, seq, index: start + index, attachments: attachmentRefsIn(message.content) } + this.acceptPrompt(source.rpcId) } } - private observeSubmissionMessage(message: UserMessage, admitted: boolean): void { + private observeSubmissionMessage(message: UserMessage, admitted: boolean, retireQueued = true): void { const source = message.source if (source.kind !== 'user' || !('rpcId' in source)) return const settlement = this.submissionSettlements.get(source.rpcId) if (settlement === undefined || settlement.retiring) return if (!admitted) { - if (settlement.placement === 'queued') this.scheduleObservedRetirement(source.rpcId, attachmentRefsIn(message.content)) + if (settlement.placement === 'queued' && retireQueued) { + this.scheduleObservedRetirement(source.rpcId, attachmentRefsIn(message.content)) + } return } settlement.admitted = attachmentRefsIn(message.content) @@ -839,6 +870,11 @@ export class Session implements SessionFace { this.finishSubmission(requestId, { reason: 'failed' }) } + private refreshAcceptedSubmissions(): void { + this.acceptedSubmissions = this.pendingSubmissions + .filter(echo => this.submissionSettlements.get(echo.requestId)?.accepted === true) + } + /** Single removal point: drop the echo, publish, then notify the owner. */ private finishSubmission(requestId: SessionRequestId, retirement: PendingSubmissionRetirement): void { const settlement = this.submissionSettlements.get(requestId) @@ -846,6 +882,7 @@ export class Session implements SessionFace { if (settlement === undefined) return this.submissionSettlements.delete(requestId) this.pendingSubmissions = this.pendingSubmissions.filter(echo => echo.requestId !== requestId) + if (settlement.accepted) this.refreshAcceptedSubmissions() this.notifier.markDirty() settlement.onRetire?.(retirement) } @@ -867,7 +904,7 @@ export class Session implements SessionFace { const identity = this.projections.values().subagent return { sessionId: this.sessionId, - pendingSubmissions: this.pendingSubmissions, + pendingSubmissions: this.acceptedSubmissions, running: this.running, subagent: this.address === undefined ? null @@ -885,7 +922,8 @@ export class Session implements SessionFace { blank: this.blankBit, lastAgentError: this.lastAgentError, promptAttempted: this.promptAttempted, - awaitingFirstTurn: this.firstPromptPendingTurn, + // The flag is set before the receipt; the Session leaves blank only once the Host accepted the prompt. + awaitingFirstTurn: this.firstPromptPendingTurn && !this.blankBit, } } diff --git a/packages/api/session-controller/src/client/transport.ts b/packages/api/session-controller/src/client/transport.ts index fc2a11a0bb..554eec515e 100644 --- a/packages/api/session-controller/src/client/transport.ts +++ b/packages/api/session-controller/src/client/transport.ts @@ -178,6 +178,7 @@ export class SessionEventStream extends RemoteJournalStream< let assistantRevision: number | undefined for await (const frame of this.remote.session.follow({ address: this.address, + activate: true, assistantStream: true, ...this.repairRequest(request), }, signal)) { diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts index 22c9f8382b..d306953c8c 100644 --- a/packages/api/session-controller/src/commands.ts +++ b/packages/api/session-controller/src/commands.ts @@ -7,12 +7,12 @@ import { brandString } from '@deepseek-ai/dsh-brand' import type { Agent, ModelSelection as AgentModelSelection } from '@deepseek-ai/dsh-agent' import { AttachmentError } from '@deepseek-ai/dsh-attachment' import type { - AttachmentAdmissionPart, ImageAttachmentRef, + AttachmentAdmissionPart, } from '@deepseek-ai/dsh-attachment' import type { FileUploadReceiptId, StagedAttachment } from '@deepseek-ai/dsh-client-file-upload/types' import type {} from '@deepseek-ai/dsh-client-file-upload' import { - ReasoningEffortId, assistantStreamChunks, createUserMessage, freezeMessage, + ReasoningEffortId, createUserMessage, freezeMessage, } from '@deepseek-ai/dsh-llm' import type { MessageSource } from '@deepseek-ai/dsh-llm' import { buildForkSeed } from '@deepseek-ai/dsh-session/fork' @@ -26,7 +26,6 @@ import type { Workspace } from '@deepseek-ai/dsh-workspace' import { ApiSessionAgentController, ApiSessionCwdConflict, - ApiSessionNotFound, ApiSessionPresetConflict, ApiSessionSubagentOwnership, apiSessionSubagentOwnershipError, @@ -359,38 +358,13 @@ export class SessionCommandController { } /** - * Read one durable image after proving the Session log references it. - * @param request - Session and attachment identities used for authorization. + * Read one durable image using the supplied reference without consulting Session history. + * @param request - image reference and gateway permission scope; Session existence is not checked. * @returns the durable attachment reference and base64-encoded bytes. */ async attachment(request: SessionAttachmentRequest): Promise { - let ref: ImageAttachmentRef | undefined try { - using observation = await this.ctx.sessionQuery.observeSession(request.sessionId, { projectionMode: 'none' }) - if (observation.source === 'prepared' && observation.header.cwd === undefined) { - throw new ApiSessionNotFound(`session "${request.sessionId}" not found`) - } - ref = referencedImage(observation.events, String(request.attachmentId)) - } catch (error) { - if (error instanceof ApiSessionNotFound - || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND')) { - throw new RemoteError('session/not-found', error.message, { sessionId: request.sessionId }) - } - throw new RemoteError( - 'gateway/internal', - `attachment authorization unavailable for session "${request.sessionId}": ${String(error)}`, - {}, - ) - } - if (ref === undefined) { - throw new RemoteError( - 'session/attachment-invalid', - 'Image is not referenced by this session.', - { reason: 'ATTACHMENT_NOT_REFERENCED' }, - ) - } - try { - const stored = await this.ctx.attachments.readImage(ref) + const stored = await this.ctx.attachments.readImage(request.attachment) return { attachment: stored.ref, data: Buffer.from(stored.data).toString('base64'), @@ -578,80 +552,3 @@ function hasPromptRequest(agent: Agent, requestId: SessionRequestId): boolean { return source.kind === 'user' && 'rpcId' in source && source.rpcId === requestId }) } -function imageBlockIn( - content: unknown, - match: (ref: ImageAttachmentRef) => boolean, -): ImageAttachmentRef | undefined { - if (!Array.isArray(content)) return undefined - for (const value of content) { - if (typeof value !== 'object' || value === null || Array.isArray(value)) continue - const block = value as { readonly type?: unknown; readonly attachment?: unknown } - if (block.type === 'image' && typeof block.attachment === 'object' && block.attachment !== null) { - const ref = block.attachment as ImageAttachmentRef - if (match(ref)) return ref - } - } - return undefined -} - -/** Read only first-party declared content fields; unknown event payloads stay opaque. */ -function imageInEvent( - event: SessionEvent, - match: (ref: ImageAttachmentRef) => boolean, -): ImageAttachmentRef | undefined { - const data = event.data as { - readonly content?: unknown - readonly message?: { readonly content?: unknown } - readonly inserted?: unknown - readonly summary?: unknown - readonly rawOutput?: unknown - } - // First-party event payloads can be present without their producer plugin mounted. - const type: string = event.type - switch (type) { - case 'user/message': - case 'tool/ptc-dispatch': - return imageBlockIn(data.content, match) - case 'system/message': - case 'developer/message': - case 'tool/result': - case 'team/message/queued': - return imageBlockIn(data.message?.content, match) - case 'agent/inbox/spliced': { - const messages = data.inserted - if (!Array.isArray(messages)) return undefined - for (const message of messages as readonly unknown[]) { - if (typeof message !== 'object' || message === null || Array.isArray(message)) continue - const found = imageBlockIn((message as { readonly content?: unknown }).content, match) - if (found !== undefined) return found - } - return undefined - } - case 'compaction/summary': - return imageBlockIn(data.summary, match) ?? imageBlockIn(data.rawOutput, match) - case 'assistant/message': { - const found = imageBlockIn(data.message?.content, match) - if (found !== undefined) return found - break - } - case 'assistant/attempt': break - default: return undefined - } - const assistant = event as SessionEvent<'assistant/message' | 'assistant/attempt'> - for (const chunk of assistantStreamChunks(assistant.data.stream, 'block-end')) { - const found = imageBlockIn([chunk.block], match) - if (found !== undefined) return found - } - return undefined -} - -function referencedImage( - events: readonly SessionEvent[], - attachmentId: string, -): ImageAttachmentRef | undefined { - for (const event of events) { - const found = imageInEvent(event, ref => String(ref.attachmentId) === attachmentId) - if (found !== undefined) return found - } - return undefined -} diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts index 07fbbfe6be..91cc3508da 100644 --- a/packages/api/session-controller/src/history.ts +++ b/packages/api/session-controller/src/history.ts @@ -1,12 +1,8 @@ -/** Cold Session history pagination and live-event source. */ +/** Shared Session history pagination, address validation and wire conversion. */ -import type { Context } from '@deepseek-ai/cordis' -import { Deque } from '@deepseek-ai/dsh-deque' -import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent' import { isAppendSurfaceEvent, SessionLogOffset, - SessionSeq, } from '@deepseek-ai/dsh-session' import type { SessionEvent, @@ -15,309 +11,26 @@ import type { SessionLogOffset as SessionLogOffsetType, SessionSeqCursor, } from '@deepseek-ai/dsh-session' -import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query' +import type { SessionObservation } from '@deepseek-ai/dsh-session-query' import type {} from '@deepseek-ai/dsh-subagent' import { RemoteError } from '@deepseek-ai/dsh-typert-protocol' -import type { JsonValue } from '@deepseek-ai/dsh-util-values' import type { SessionAddress, - SessionAssistantStreamFrame, SessionEventEntry, - SessionFollowRequest, - SessionFollowFrame, SessionHistoryRecord, - SessionPage, SessionPageRequest, - SessionProjectionBaseline, - SessionProjectionValues, - SessionWireHeader, SessionWireEvent, } from './types.ts' -import { SessionAssistantStreamAccumulator } from './assistant-stream.ts' -const DEFAULT_MAX_MESSAGES = 50 +/** Message budget applied when a history request omits `maxMessages`. */ +export const DEFAULT_MAX_MESSAGES = 50 const MESSAGE_TYPES = new Set(['user/message', 'assistant/message']) -/** Implements cold-safe history operations delegated by the Session Controller. */ -export class SessionHistoryController { - private readonly closeFollowers = new Set<() => void>() - private readonly assistantStreams = new Map() - - /** - * @param ctx - Host context carrying Session query and projection services. - * @param promote - starts ordinary Session activation after snapshot delivery. - */ - constructor( - private readonly ctx: Context, - private readonly promote: (observation: SessionObservation) => void, - ) { - ctx.on('agent/assistant-stream', ({ agent, frame }) => { - let stream = this.assistantStreams.get(agent.session.id) - if (stream === undefined) { - stream = new SessionAssistantStreamAccumulator() - this.assistantStreams.set(agent.session.id, stream) - } - stream.accept(frame, cursorBeforeNext(agent.session.seq)) - }, { global: true }) - ctx.on('agent/disposed', ({ agent }) => { - this.assistantStreams.delete(agent.session.id) - }, { global: true }) - ctx.effect(() => () => { - for (const close of this.closeFollowers) close() - this.closeFollowers.clear() - }, 'session-controller.history') - } - - /** - * Read one message-aligned history page without activating an Agent. - * @param request - durable address and backwards-page cursor. - * @param signal - caller cancellation for persistence reads. - * @returns a contiguous event page. - */ - async page(request: SessionPageRequest, signal: AbortSignal): Promise { - validatePageRequest(request) - const throughSeq: SessionSeqCursor = request.throughSeq === -1 - ? -1 - : SessionSeq(request.throughSeq) - const beforeSeq = request.beforeSeq === undefined - ? undefined - : SessionLogOffset(request.beforeSeq) - using source = await this.sourceFor(request.address, signal, false) - signal.throwIfAborted() - const sourceLog = source.events - const sourceCursor: SessionSeqCursor = sourceLog.at(-1)?.seq ?? -1 - if (throughSeq > sourceCursor) { - throw new RemoteError( - 'gateway/bad-request', - `session page through seq ${String(throughSeq)} is past cursor ${String(sourceCursor)}`, - {}, - ) - } - /* v8 ignore next -- Session and persistence validation guarantee a dense zero-based event prefix. */ - if (throughSeq >= 0 && sourceLog[throughSeq]?.seq !== throughSeq) { - throw new RemoteError('gateway/internal', `session log does not contain through seq ${String(throughSeq)}`, {}) - } - const page = paginate( - sourceLog, - beforeSeq, - request.maxMessages ?? DEFAULT_MAX_MESSAGES, - throughSeq, - request.turnWindow, - ) - const records = pageRecords(page.events) - return { - records, - hasMore: page.hasMore, - } - } - - /** - * Follow events appended after an initial cursor on one durable address. - * @param request - durable address and last committed sequence already held by the caller. - * @param signal - stream cancellation owned by the Remote carrier. - * @returns a complete opening snapshot followed by gap-free durable events and opted-in assistant frames. - */ - async *follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable { - validateHistoryWindow(request) - const { address } = request - const target = addressId(address) - const buffered = new Deque< - | { readonly type: 'event'; readonly event: SessionEvent } - | { - readonly type: 'assistant-stream' - readonly frame: SessionAssistantStreamFrame - readonly ordinal: number - } - >() - let snapshotCursor: SessionSeqCursor | undefined - let assistantStreamOrdinal = 0 - let wake: (() => void) | undefined - const notify = (): void => { - const resume = wake - wake = undefined - resume?.() - } - const follower = { closed: false } - const close = (): void => { - follower.closed = true - notify() - } - this.closeFollowers.add(close) - const disposeEvent = this.ctx.on('session/event', (session, event) => { - if (session.id !== target) return - buffered.pushBack({ type: 'event', event }) - notify() - }, { global: true }) - const disposeCreated = this.ctx.on('session/created', (session) => { - if (session.id !== target) return - // Constructor seed events have no session/event notification. Normally - // only the end-seed suffix is new; if persistence advanced after the - // opening observation, replay everything beyond that snapshot cursor. - // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred. - const suffix = session.snapshotEvents(snapshotCursor === undefined - ? session.firstLiveSeq - : SessionLogOffset(snapshotCursor + 1)) - for (let index = suffix.length - 1; index >= 0; index -= 1) { - buffered.pushFront({ type: 'event', event: suffix[index] as SessionEvent }) - } - notify() - }, { global: true }) - const disposeAssistantStream = request.assistantStream !== true - ? undefined - : this.ctx.on('agent/assistant-stream', ({ agent, frame }) => { - if (agent.session.id !== target) return - buffered.pushBack({ - type: 'assistant-stream', - frame: wireAssistantStreamFrame(frame, cursorBeforeNext(agent.session.seq)), - ordinal: ++assistantStreamOrdinal, - }) - notify() - }, { global: true }) - const onAbort = (): void => { notify() } - signal.addEventListener('abort', onAbort, { once: true }) - try { - using source = await this.sourceFor(address, signal, true) - const events = source.events - signal.throwIfAborted() - const cursor = source.cursor - snapshotCursor = cursor - const page = paginate(events, undefined, request.maxMessages ?? DEFAULT_MAX_MESSAGES, cursor, request.turnWindow) - const assistantStream = request.assistantStream === true - ? this.assistantStreams.get(target)?.snapshot() ?? { revision: 0 } - : undefined - // The accumulator snapshot and this watermark are synchronous. Frames - // through the cut are represented or superseded by that baseline, - // including larger revisions from a retired Agent; later revision - // resets reach Client continuity validation. - const assistantStreamOrdinalCut = assistantStreamOrdinal - yield { - type: 'snapshot', - header: wireHeader(source.header), - cursor, - records: pageRecords(page.events), - hasMore: page.hasMore, - projections: source.projections === undefined - ? { asOfSeq: cursor, values: {} } - : projectionBlock(source.projections), - ...assistantStream === undefined ? {} : { assistantStream }, - } - if (address.kind === 'session' && source.source === 'prepared') { - const promotion = source.retain() - try { - this.promote(promotion) - } catch (error: unknown) { - promotion[Symbol.dispose]() - throw error - } - } - let nextOffset = SessionLogOffset(cursor + 1) - while (!follower.closed && !signal.aborted) { - const item = buffered.popFront() - if (item === undefined) { - await new Promise((resolve) => { wake = resolve }) - continue - } - if (item.type === 'assistant-stream') { - if (item.ordinal > assistantStreamOrdinalCut) { - yield { type: 'assistant-stream', frame: item.frame } - } - continue - } - const expectedSeq = SessionSeq(nextOffset) - if (item.event.seq < expectedSeq) continue - if (item.event.seq !== expectedSeq) { - throw new RemoteError('gateway/internal', `session event stream skipped seq ${String(expectedSeq)}`, {}) - } - nextOffset = SessionLogOffset(nextOffset + 1) - yield entryFor(item.event) - } - } finally { - this.closeFollowers.delete(close) - signal.removeEventListener('abort', onAbort) - disposeCreated() - disposeEvent() - disposeAssistantStream?.() - } - } - - private async sourceFor( - address: SessionAddress, - signal: AbortSignal, - withProjections: boolean, - ): Promise { - const sessionId = addressId(address) - try { - const observation = await this.ctx.sessionQuery.observeSession(sessionId, { - signal, - projectionMode: withProjections || address.kind === 'subagent' ? 'all' : 'none', - }) - if (observation.header.cwd === undefined) { - observation[Symbol.dispose]() - rejectNotFound(address) - } - try { - validateAddress( - address, - observation.header, - observation.inheritedEventCount, - observation.projections, - ) - } catch (error: unknown) { - observation[Symbol.dispose]() - throw error - } - return observation - } catch (error: unknown) { - if (error instanceof SessionQueryError - && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') rejectNotFound(address) - throw error - } - } - -} - -function cursorBeforeNext(nextSeq: SessionLogOffsetType): SessionSeqCursor { - return nextSeq === 0 ? -1 : SessionSeq(nextSeq - 1) -} - -function wireAssistantStreamFrame( - frame: AssistantStreamFrame, - durableCursor: SessionSeqCursor, -): SessionAssistantStreamFrame { - if (frame.type === 'start') return { ...frame, startedAfterSeq: durableCursor } - if (frame.type === 'end') return frame - return { - ...frame, - chunk: frame.chunk as JsonValue, - } -} - -function projectionBlock( - snapshot: NonNullable, -): SessionProjectionBaseline { - return { - asOfSeq: snapshot.asOfSeq, - // Projection definitions validate whole JSON values before snapshot publication. - values: snapshot.values as SessionProjectionValues, - } -} - -function validatePageRequest(request: SessionPageRequest): void { - if (!Number.isSafeInteger(request.throughSeq) - || request.throughSeq < -1 - || Object.is(request.throughSeq, -0)) { - throw new RemoteError('gateway/bad-request', 'throughSeq must be an integer greater than or equal to -1', {}) - } - if (request.beforeSeq !== undefined - && (!Number.isSafeInteger(request.beforeSeq) - || request.beforeSeq < 0 - || Object.is(request.beforeSeq, -0))) { - throw new RemoteError('gateway/bad-request', 'beforeSeq must be a non-negative safe integer', {}) - } - validateHistoryWindow(request) -} - -function validateHistoryWindow(request: Pick): void { +/** + * Reject an invalid message budget or turn window. + * @param request - history window fields. + */ +export function validateHistoryWindow(request: Pick): void { if (request.maxMessages !== undefined && (!Number.isSafeInteger(request.maxMessages) || request.maxMessages <= 0)) { throw new RemoteError('gateway/bad-request', 'maxMessages must be a positive safe integer', {}) @@ -334,11 +47,23 @@ function validateHistoryWindow(request: Pick 0 } } -/** Translate current logical Session metadata to the browser wire. */ -function wireHeader(header: SessionHeader): SessionWireHeader { - return { ...header } -} - -function entryFor(event: SessionEvent): SessionEventEntry { +/** + * Convert a committed event to its wire entry. + * @param event - committed Session event. + * @returns the wire event entry. + */ +export function entryFor(event: SessionEvent): SessionEventEntry { return { type: 'event', // Session.append validates and freezes event data as JSON before publication. @@ -439,7 +179,11 @@ function entryFor(event: SessionEvent): SessionEventEntry { } } -/** Encode one bounded logical page without changing its pagination cut. */ -function pageRecords(events: readonly SessionEvent[]): SessionHistoryRecord[] { +/** + * Encode one bounded logical page without changing its pagination cut. + * @param events - page events. + * @returns the wire records. + */ +export function pageRecords(events: readonly SessionEvent[]): SessionHistoryRecord[] { return events.map(entryFor) } diff --git a/packages/api/session-controller/src/history/assistant-stream.ts b/packages/api/session-controller/src/history/assistant-stream.ts new file mode 100644 index 0000000000..b42a0aba29 --- /dev/null +++ b/packages/api/session-controller/src/history/assistant-stream.ts @@ -0,0 +1,102 @@ +/** Assistant stream baselines and per-connection subscriptions. */ + +import type { Context } from '@deepseek-ai/cordis' +import { SessionSeq } from '@deepseek-ai/dsh-session' +import type { Session, SessionId } from '@deepseek-ai/dsh-session' +import type { JsonValue } from '@deepseek-ai/dsh-util-values' +import { SessionAssistantStreamAccumulator } from '../assistant-stream.ts' +import type { SessionAssistantStreamBaseline, SessionAssistantStreamFrame } from '../types.ts' +import { ListenerBuffer } from './listener.ts' + +/** One accumulator per live Session, shared by every subscription bound to it. */ +export class SessionAssistantStreamsListener { + private readonly streams = new Map() + + /** @param ctx - service context owning the accumulator listeners. */ + constructor(private readonly ctx: Context) { + ctx.on('agent/assistant-stream', ({ agent, frame }) => { + let stream = this.streams.get(agent.session.id) + if (stream === undefined) { + stream = new SessionAssistantStreamAccumulator() + this.streams.set(agent.session.id, stream) + } + stream.accept(frame, agent.session.seq === 0 ? -1 : SessionSeq(agent.session.seq - 1)) + }, { global: true }) + ctx.on('agent/disposed', ({ agent }) => { this.streams.delete(agent.session.id) }, { global: true }) + ctx.effect(() => () => { this.streams.clear() }, 'session-controller.assistant-streams') + } + + /** + * Bind one connection to a Session assistant stream. + * @param sessionId - Session to subscribe. + * @param signal - cancellation owned by the caller. + * @param queue - caller-owned raw notification buffer. + * @returns a listener the caller disposes. + */ + bind(sessionId: SessionId, signal: AbortSignal, + queue: Pick, 'createInput' | 'capture'>): AssistantStreamListener { + return new AssistantStreamListener(this.ctx, sessionId, signal, () => { + return this.streams.get(sessionId)?.snapshot() ?? { revision: 0 } + }, queue) + } +} + +type AssistantEntry = { type: 'assistant-stream'; frame: SessionAssistantStreamFrame } + +/** An assistant notification and its connection-local arrival position. */ +interface AssistantItem { + readonly type: 'assistant-stream' + readonly session: Session + readonly frame: SessionAssistantStreamFrame + readonly ordinal: number +} + +/** Writes assistant notifications into the connection's shared queue. */ +class AssistantStreamListener implements Disposable { + private readonly disposes: (() => void)[] = [] + private ordinal = 0 + private cut = 0 + + constructor( + ctx: Context, + sessionId: SessionId, + signal: AbortSignal, + private _snapshot: () => SessionAssistantStreamBaseline, + output: Pick, 'createInput' | 'capture'>) { + signal.throwIfAborted() + const input = output.createInput(item => this.transform(item)) + try { + this.disposes.push(ctx.on('agent/assistant-stream', ({ agent, frame }) => { + if (agent.session.id !== sessionId) return + output.capture(() => { + const wire: SessionAssistantStreamFrame = frame.type === 'start' + ? { ...frame, startedAfterSeq: agent.session.seq === 0 ? -1 : SessionSeq(agent.session.seq - 1) } + : frame.type === 'chunk' ? { ...frame, chunk: frame.chunk as JsonValue } : frame + input.append({ type: 'assistant-stream', session: agent.session, frame: wire, ordinal: ++this.ordinal }) + }) + }, { global: true })) + } catch (error: unknown) { + this[Symbol.dispose]() + throw error + } + } + + /** @returns the baseline and local arrival cut captured synchronously together. */ + snapshot(): { baseline: SessionAssistantStreamBaseline; ordinal: number } { + return { baseline: this._snapshot(), ordinal: this.ordinal } + } + + /** @param ordinal - local snapshot cut set before queue consumption. */ + setOrdinalCut(ordinal: number): void { + this.cut = ordinal + } + + private *transform(item: AssistantItem): Iterable { + if (this.disposes.length === 0 || item.ordinal <= this.cut) return + yield { type: 'assistant-stream', frame: item.frame } + } + + [Symbol.dispose](): void { + for (const dispose of this.disposes.splice(0).reverse()) dispose() + } +} diff --git a/packages/api/session-controller/src/history/controller.ts b/packages/api/session-controller/src/history/controller.ts new file mode 100644 index 0000000000..d090f0a3f7 --- /dev/null +++ b/packages/api/session-controller/src/history/controller.ts @@ -0,0 +1,256 @@ +/** Independent Session snapshots and passive event subscriptions. */ + +import type { Context } from '@deepseek-ai/cordis' +import { SessionLogOffset, SessionSeq, isAppendSurfaceEvent } from '@deepseek-ai/dsh-session' +import type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session' +import type { SessionObservation } from '@deepseek-ai/dsh-session-query' +import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol' +import { + DEFAULT_MAX_MESSAGES, paginate, pageRecords, entryFor, addressId, + validateHistoryWindow, validateAddress, rejectNotFound, +} from '../history.ts' +import { EventListener, ProjectionListener } from './listener.ts' +import { SessionAssistantStreamsListener } from './assistant-stream.ts' +import type { + SessionEventFrame, SessionEventsPage, SessionPageRequest, + SessionObserveEventRequest, SessionProjectionsRequest, SessionProjectionFrame, + SessionAddress, SessionProjectionBaseline, SessionProjectionValues, SessionProjectionsValue, SessionWaitOutput, SessionHistoryRecord, +} from '../types.ts' + + +/** Session snapshots do not share lifetime with passive subscriptions. */ +export class HistoryController { + + /** Reconnect state for this controller's assistant subscriptions. */ + readonly streamsListener: SessionAssistantStreamsListener + + /** @param ctx - Host context carrying Session reads and projections. */ + constructor(private readonly ctx: Context) { + this.streamsListener = new SessionAssistantStreamsListener(this.ctx) + } + + /** + * Read a passive page of Session events at an exact cut. + * @param request - Session identity and optional cut and page window. + * @param signal - read cancellation. + * @returns a page at the supplied cut, or the observed log end when omitted. + */ + async events(request: SessionPageRequest, signal: AbortSignal): Promise { + const spec = resolveHistoryRequest(request) + try { + return await this.usingObservation({ sessionId: addressId(request.address), projection: request.address.kind === 'subagent' }, signal, (observation) => { + validateObservationAddress(request.address, observation) + return history(observation, spec) + }) + } catch (error: unknown) { + if (remoteErrorOf(error)?.code === 'session/not-found') rejectNotFound(request.address) + throw error + } + } + + /** + * Subscribe to Session events without reading or activating the Session. + * @param request - Session address to subscribe. + * @param signal - stream cancellation. + * @returns subscription readiness followed by event frames; readiness does not establish existence. + */ + async *observeEvent(request: SessionObserveEventRequest, signal: AbortSignal): AsyncIterable { + using listener = new EventListener(this.ctx, addressId(request.address), signal) + yield { type: 'ready' } + yield* listener.events() + } + + /** + * Read exact projections or migration cache hints without activating the Session. + * @param request - Session identity whose exact projection baseline is required. + * @param signal - read cancellation. + * @returns exact sequenced values, migration cache hints, or null when absent. + */ + async projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise { + const { sessionId } = request + if (sessionId.length === 0) { + throw new RemoteError('gateway/bad-request', 'sessionId must not be empty', {}) + } + try { + signal.throwIfAborted() + const live = this.ctx.sessions.get(sessionId) + if (live !== undefined) { + const snapshot = this.ctx.sessionProjections.snapshot(live) + return { kind: 'sequenced', asOfSeq: snapshot.asOfSeq, values: snapshot.values as SessionProjectionValues } + } else { + const stored = await this.ctx.get('sessionPersistence')?.stat(sessionId, { signal }) + signal.throwIfAborted() + if (stored?.formatStatus === 'migration-required') { + const cached = this.ctx.get('sessionProjectionCache')?.cachedSnapshot(stored.header) + return { kind: 'migration-required', values: { ...cached?.values } as SessionProjectionValues } + } + return await this.usingObservation({ sessionId: request.sessionId, projection: true }, signal, observation => ({ + kind: 'sequenced' as const, + ...projections(observation), + })) + } + } catch (error: unknown) { + const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined + if (code === 'SESSION_QUERY_SESSION_NOT_FOUND' || code === 'session/not-found') { + return null + } + if (signal.aborted || code === 'SESSION_QUERY_ABORTED') { + throw new RemoteError('gateway/cancelled', 'Session projection read was cancelled', {}, { cause: error }) + } + if (remoteErrorOf(error) !== undefined) throw error + throw new RemoteError('gateway/internal', 'Session projection read failed', {}, { cause: error }) + } + } + + /** + * Subscribe to sparse projection replacements without reading a baseline. + * @param request - Session identity to subscribe without reading a baseline. + * @param signal - stream cancellation. + * @returns readiness followed by sparse per-key replacement values. + */ + async *observeProjections(request: SessionProjectionsRequest, signal: AbortSignal): AsyncIterable { + using listener = new ProjectionListener(this.ctx, request.sessionId, signal) + yield { type: 'ready' } + yield* listener.changes() + } + + /** + * Read bounded committed assistant messages through a stopping cursor. + * @param sessionId - Session whose committed assistant messages are requested. + * @param afterSeq - exclusive lower bound. + * @param throughSeq - inclusive stopping-state cursor. + * @param maxMessages - positive assistant record limit. + * @param signal - caller cancellation, independent of a completed wait deadline. + * @returns newest-first assistant messages and whether further matching records were omitted. + */ + async assistantOutput( + sessionId: SessionId, afterSeq: number, throughSeq: number, maxMessages: number, signal: AbortSignal, + ): Promise { + return this.usingObservation({ sessionId, projection: false }, signal, (observation) => { + if (throughSeq > observation.cursor) { + throw new RemoteError('gateway/internal', 'Session history no longer covers the wait cursor', {}) + } + const records: SessionHistoryRecord[] = [] + const events = observation.events + for (let index = throughSeq; index > afterSeq; index--) { + const event = events[index] as SessionEvent + if (event.type !== 'assistant/message' || !isAppendSurfaceEvent(event)) continue + if (records.length === maxMessages) return { records, truncated: true } + records.push(entryFor(event)) + } + return { records, truncated: false } + }) + } + + /** + * Acquire a read without activating a Session; projections are opt-in. + * @param request - Session identity and whether to compute projections. + * @param signal - read cancellation. + * @param callback - omitted to transfer lease ownership to the caller. + * @returns a lease the caller must dispose. + */ + usingObservation( + request: { readonly sessionId: SessionId; readonly projection: boolean }, signal: AbortSignal, callback?: undefined, + ): Promise + /** + * Keep the borrowed lease alive until the callback settles, then dispose it. + * @param request - Session identity and whether to compute projections. + * @param signal - read cancellation. + * @param callback - synchronous or asynchronous computation; retain a separate lease if it must escape. + * @returns the callback result; read and callback failures propagate. + */ + usingObservation( + request: { readonly sessionId: SessionId; readonly projection: boolean }, signal: AbortSignal, + callback: (observation: SessionObservation) => T, + ): Promise> + async usingObservation( + { sessionId, projection }: { readonly sessionId: SessionId; readonly projection: boolean }, signal: AbortSignal, + callback?: (observation: SessionObservation) => T, + ): Promise> { + let observation: SessionObservation + try { + observation = await this.ctx.sessionQuery.observeSession(sessionId, { signal, projectionMode: projection ? 'all' : 'none' }) + } catch (error: unknown) { + const code = (error as { readonly code?: unknown } | null | undefined)?.code + if (code === 'SESSION_QUERY_SESSION_NOT_FOUND') { + throw new RemoteError('session/not-found', `session "${sessionId}" not found`, { sessionId }) + } + if (code === 'SESSION_QUERY_ABORTED') { + // Keep the query's own message: cancellation detail was visible before this mapping. + throw new RemoteError('gateway/cancelled', + error instanceof Error ? error.message : 'Session read was cancelled', {}, { cause: error }) + } + throw error + } + try { + signal.throwIfAborted() + } catch (error: unknown) { + observation[Symbol.dispose]() + throw error + } + if (callback === undefined) return observation + using ownedObservation = observation + return await callback(ownedObservation) + } +} + +/** + * Validate an Address against the exact read used by a Controller. + * @param address - caller-supplied Session address. + * @param observation - borrowed read; subagent addresses require projections. + */ +export function validateObservationAddress(address: SessionAddress, observation: SessionObservation): void { + if (observation.header.cwd === undefined) rejectNotFound(address) + validateAddress(address, observation.header, observation.inheritedEventCount, observation.projections) +} + +/** + * Convert a borrowed observation to one page without acquiring or retaining it. + * @param observation - exact read cut owned by the caller. + * @param request - validated page window and optional inclusive cut. + * @returns a chronological page at the requested cut. + */ +export function history(observation: SessionObservation, request: Omit & { readonly maxMessages: number }): SessionEventsPage { + const cursor = request.throughSeq === undefined ? observation.cursor + : request.throughSeq === -1 ? -1 : SessionSeq(request.throughSeq) + if (cursor > observation.cursor) { + throw new RemoteError('gateway/bad-request', `session history cut ${String(cursor)} exceeds ${String(observation.cursor)}`, {}) + } + const page = paginate( + observation.events, + request.beforeSeq === undefined ? undefined : SessionLogOffset(request.beforeSeq), + request.maxMessages, + cursor, + request.turnWindow, + ) + return { cursor, records: pageRecords(page.events), hasMore: page.hasMore } +} + +/** + * Convert the projection baseline without acquiring or retaining its observation. + * @param observation - projected read cut owned by the caller. + * @returns the exact baseline; missing projection support fails explicitly. + */ +export function projections(observation: SessionObservation): SessionProjectionBaseline { + const snapshot = observation.projections + if (snapshot === undefined) throw new RemoteError('session/projections-unavailable', 'Session projections are unavailable', {}) + return { asOfSeq: snapshot.asOfSeq, values: snapshot.values as SessionProjectionValues } +} + +/** + * Validate and resolve the history page window. + * @param request - external history window. + * @returns the validated request with an explicit message budget. + */ +export function resolveHistoryRequest(request: SessionPageRequest): SessionPageRequest & { readonly maxMessages: number } { + if (request.throughSeq !== undefined + && (!Number.isSafeInteger(request.throughSeq) || request.throughSeq < -1 || Object.is(request.throughSeq, -0))) { + throw new RemoteError('gateway/bad-request', 'throughSeq must be an integer greater than or equal to -1', {}) + } + if (request.beforeSeq !== undefined + && (!Number.isSafeInteger(request.beforeSeq) || request.beforeSeq < 0 || Object.is(request.beforeSeq, -0))) { + throw new RemoteError('gateway/bad-request', 'beforeSeq must be a non-negative safe integer', {}) + } + validateHistoryWindow(request) + return { ...request, maxMessages: request.maxMessages ?? DEFAULT_MAX_MESSAGES } +} diff --git a/packages/api/session-controller/src/history/listener.ts b/packages/api/session-controller/src/history/listener.ts new file mode 100644 index 0000000000..a272081620 --- /dev/null +++ b/packages/api/session-controller/src/history/listener.ts @@ -0,0 +1,303 @@ +/** Passive per-Session streams; subscriptions never acquire Session observations. */ + +import type { Context } from '@deepseek-ai/cordis' +import { Deque } from '@deepseek-ai/dsh-deque' +import { SessionLogOffset } from '@deepseek-ai/dsh-session' +import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session' +import { RemoteError } from '@deepseek-ai/dsh-typert-protocol' +import type { JsonValue } from '@deepseek-ai/dsh-util-values' +import { entryFor } from '../history.ts' +import type { SessionProjectionChange, SessionEventEntry } from '../types.ts' + +/** Raw history notifications buffered before an opening cut is known. */ +export type EventItem = + | { readonly type: 'event'; readonly session: Session; readonly event: SessionEvent } + | { readonly type: 'created'; readonly session: Session; readonly end: number } + +/** A single subscription buffers before either consumption mode starts. */ +export class EventListener implements Disposable { + private readonly buffer: ListenerBuffer | undefined + private readonly disposes: (() => void)[] = [] + private firstReceivedSeq: number | undefined + private nextExpectedSeq: number | undefined + + /** + * @param ctx - context owning the event registrations. + * @param sessionId - Session whose notifications are emitted. + * @param signal - cancellation that wakes consumers. + * @param queue - optional caller-owned buffer; only an internally created buffer is disposed here. + */ + constructor(ctx: Context, sessionId: SessionId, signal: AbortSignal, + queue?: Pick, 'createInput' | 'capture'>) { + signal.throwIfAborted() + const buffer = queue ?? new ListenerBuffer(ctx, signal) + this.buffer = queue === undefined ? buffer as ListenerBuffer : undefined + const input = buffer.createInput(item => this.transform(item)) + const target = sessionId + try { + this.disposes.push(ctx.on('session/event', (session, event) => { + if (session.id !== target) return + buffer.capture(() => { + this.recordFirst(event.seq) + input.append({ type: 'event', session, event }) + }) + }, { global: true })) + this.disposes.push(ctx.on('session/created', (session) => { + if (session.id !== target) return + buffer.capture(() => { + if (session.firstLiveSeq < session.seq) this.recordFirst(session.firstLiveSeq) + input.prepend({ type: 'created', session, end: session.seq }) + }) + }, { global: true })) + this.buffer?.own(() => { this[Symbol.dispose]() }) + } catch (error: unknown) { + this[Symbol.dispose]() + throw error + } + } + + /** Consume notifications without reading history. + * @returns event frames from the first received event, without loading a baseline. */ + events(): AsyncIterable { + return this.iterate() + } + + /** Set the inclusive opening cut for buffered history notifications. + * @param cursor - snapshot cut set before consuming the queue. */ + setCursor(cursor: number): void { + this.nextExpectedSeq = cursor + 1 + } + + private *transform(item: EventItem): Iterable { + if (this.disposes.length === 0) return + this.nextExpectedSeq ??= this.firstReceivedSeq + const result = eventItem(item, this.nextExpectedSeq) + this.nextExpectedSeq = result.next + for (const event of result.events) { + if (this.disposes.length === 0) return + yield entryFor(event) + } + } + + private async *iterate(): AsyncIterable { + if (this.buffer === undefined) throw new Error('Consume the externally owned history buffer directly') + try { + yield* this.buffer.items() + } finally { + this[Symbol.dispose]() + } + } + + private recordFirst(seq: number): void { + this.firstReceivedSeq = this.firstReceivedSeq === undefined ? seq : Math.min(this.firstReceivedSeq, seq) + } + + [Symbol.dispose](): void { + for (const dispose of this.disposes.splice(0).reverse()) dispose() + this.buffer?.[Symbol.dispose]() + } +} + +/** + * Select the uncovered events represented by one notification. + * @param item - one buffered notification. + * @param next - next required seq, or undefined before the first event. + * @returns uncovered events and the next required seq without acquiring an observation. + */ +export function eventItem(item: EventItem, next?: number): { + events: readonly SessionEvent[] + next: number | undefined +} { + if (item.type === 'event') { + if (next !== undefined && item.event.seq < next) return { events: [], next } + if (next !== undefined && item.event.seq !== next) { + throw new RemoteError('gateway/internal', `session event stream skipped seq ${String(next)}`, {}) + } + return { events: [item.event], next: item.event.seq + 1 } + } + const start = next ?? item.session.firstLiveSeq + if (start >= item.end) return { events: [], next } + // oxlint-disable-next-line typescript/no-deprecated -- Existing Session-created history adaptation. + const events = item.session.snapshotEvents(SessionLogOffset(start), SessionLogOffset(item.end)) + for (const event of events) { + if (next !== undefined && event.seq !== next) { + throw new RemoteError('gateway/internal', `session event stream skipped seq ${String(next)}`, {}) + } + next = event.seq + 1 + } + return { events, next } +} + +/** Sparse projection changes retain every key, including keys sharing a seq. */ +export class ProjectionListener implements Disposable { + private readonly buffer: ListenerBuffer<{ session: Session; change: SessionProjectionChange }> + + /** + * @param ctx - context owning projection notifications. + * @param sessionId - Session whose notifications are emitted. + * @param signal - cancellation that removes registrations and wakes consumers. + */ + constructor(ctx: Context, sessionId: SessionId, signal: AbortSignal) { + this.buffer = new ListenerBuffer(ctx, signal) + const input = this.buffer.createInput<{ session: Session; change: SessionProjectionChange }>(item => [item]) + const target = sessionId + try { + this.buffer.own(ctx.sessionProjections.onChanged((session, key, value, seq) => { + if (session.id !== target) return + this.buffer.capture(() => { + input.append({ + session, change: { type: 'projection', key, value: value as JsonValue, seq } satisfies SessionProjectionChange, + }) + }) + })) + } catch (error: unknown) { + this.buffer[Symbol.dispose]() + throw error + } + } + + /** Consume sparse per-key projection replacements. + * @returns validated replacement frames; projection seqs need not be contiguous. */ + async *changes(): AsyncIterable { + try { + for await (const { change } of this.buffer.items()) { + yield change + } + } finally { + this[Symbol.dispose]() + } + } + + [Symbol.dispose](): void { + this.buffer[Symbol.dispose]() + } +} + +/** Owns buffering, callback failure and registration cleanup for one consumer. */ +export class ListenerBuffer implements Disposable { + private readonly values = new Deque() + private readonly transformIds = new Deque() + private readonly transforms: ((value: unknown) => Iterable)[] = [] + private readonly cleanup: (() => void)[] = [] + private wake: (() => void) | undefined + private closed = false + private failure: { readonly error: unknown } | undefined + private consumed = false + + constructor(ctx: Context, signal: AbortSignal) { + signal.throwIfAborted() + const close = (): void => { this[Symbol.dispose]() } + signal.addEventListener('abort', close, { once: true }) + this.own(() => { signal.removeEventListener('abort', close) }) + try { + const dispose = ctx.effect(() => close, 'session-controller.listener-buffer') + this.own(() => { void dispose() }) + } catch (error: unknown) { + this[Symbol.dispose]() + throw error + } + } + + /** + * Register cleanup, or run it immediately when already closed. + * @param dispose - synchronous cleanup. + */ + own(dispose: () => void): void { + if (this.closed) dispose() + else this.cleanup.push(dispose) + } + + /** + * Contain producer failure and wake the consumer with that failure. + * @param action - synchronous producer operation. + */ + capture(action: () => void): void { + if (this.closed) return + try { + action() + } catch (error: unknown) { + this.failure = { error } + this[Symbol.dispose]() + } + } + + /** + * Register a dequeue transform and obtain its write-only input. + * @param transform - conversion bound once and evaluated when each input is dequeued. + * @returns a write-only input sharing this buffer's storage and lifetime. + * @throws when this buffer is already closed. + */ + createInput(transform: (item: Input) => Iterable): { append(item: Input): void; prepend(item: Input): void } { + if (this.closed) throw new Error('Cannot register a transform on a closed listener buffer') + const transformId = this.transforms.length + // Only this typed input can enqueue values with its private transform id. + this.transforms.push(value => transform(value as Input)) + return { + append: (item) => { + if (this.closed) return + this.values.pushBack(item) + this.transformIds.pushBack(transformId) + this.notify() + }, + prepend: (item) => { + if (this.closed) return + this.values.pushFront(item) + this.transformIds.pushFront(transformId) + this.notify() + }, + } + } + + /** + * Consume queued values once, releasing the buffer when iteration ends. + * @returns transformed output values. + */ + async *items(): AsyncIterable { + if (this.consumed) throw new RemoteError('gateway/internal', 'Session listener already has a consumer', {}) + this.consumed = true + try { + for (;;) { + if (this.failure !== undefined) throw this.failure.error + if (this.closed) return + if (this.transformIds.size === 0) { + await new Promise((resolve) => { this.wake = resolve }) + continue + } + const transformId = this.transformIds.popFront() as number + const value = this.values.popFront() + for (const item of (this.transforms[transformId] as (value: unknown) => Iterable)(value)) { + this.throwIfFailed() + if (this.isClosed()) return + yield item + } + } + } finally { + this[Symbol.dispose]() + } + } + + private throwIfFailed(): void { + if (this.failure !== undefined) throw this.failure.error + } + + /** @returns whether disposal ended this buffer while a transform was yielding. */ + private isClosed(): boolean { + return this.closed + } + + private notify(): void { + const wake = this.wake + this.wake = undefined + wake?.() + } + + [Symbol.dispose](): void { + if (this.closed) return + this.closed = true + this.values.clear() + this.transformIds.clear() + this.transforms.length = 0 + this.notify() + for (const dispose of this.cleanup.splice(0).reverse()) dispose() + } +} diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts index 125bd1f3e3..94d08c77e3 100644 --- a/packages/api/session-controller/src/index.ts +++ b/packages/api/session-controller/src/index.ts @@ -11,7 +11,7 @@ import type {} from '@deepseek-ai/dsh-client-file-upload' import { canOpenNativePath, nativeFileManager, nativeFileApplications, openNativeFileApplication, openNativeAssociatedPath, revealNativePath } from '@deepseek-ai/dsh-native-command' import type { SessionId } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-session-projection-cache' -import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query' +import type { SessionObservation } from '@deepseek-ai/dsh-session-query' import { Remote, RemoteError, TypertRemoteService, principalOf, type TypertResourceResolveInput } from '@deepseek-ai/dsh-typert-protocol' import { canonicalClientTimeZone } from '@deepseek-ai/dsh-util-time' import { assertNever } from '@deepseek-ai/dsh-util-values' @@ -22,7 +22,9 @@ import { } from './agent.ts' import { SessionCommandController, hasPromptContent } from './commands.ts' import { SessionControlController } from './control.ts' -import { SessionHistoryController } from './history.ts' +import { HistoryController } from './history/controller.ts' +import { StateController } from './state/controller.ts' +import { WebController } from './web/controller.ts' import { SessionFileReferences } from './file-references.ts' import { ApiSessionList } from './list.ts' import { buildModelCatalog, hasProviderApiKey } from './catalog.ts' @@ -48,8 +50,8 @@ import type { SessionListValue, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, - SessionPage, - SessionPageRequest, + SessionEventsPage, SessionPageRequest, SessionEventFrame, SessionObserveEventRequest, + SessionProjectionFrame, SessionStateRequest, SessionState, SessionWaitRequest, SessionWaitValue, SessionPromptRequest, SessionPromptValue, SessionRenameRequest, @@ -60,7 +62,6 @@ import type { SessionSelectModelValue, SessionProjectionsRequest, SessionProjectionsValue, - SessionProjectionValues, SessionUpdateQueueRequest, SessionUpdateQueueValue, } from './types.ts' @@ -144,6 +145,7 @@ export class SessionController extends TypertRemoteService { 'sessionProjections', 'sessionQuery', 'typert', + 'typertGateway', 'workspaceRegistry', ] @@ -152,10 +154,13 @@ export class SessionController extends TypertRemoteService { listWorkSliceMs: z.natural().min(1).default(16), }) + private historyController!: HistoryController + private stateController!: StateController + private webController!: WebController + private agents!: ApiSessionAgentController private commands!: SessionCommandController private controlState!: SessionControlController - private history!: SessionHistoryController private listState!: ApiSessionList private readonly openPath: (path: string, signal: AbortSignal) => Promise private readonly fileApplications: typeof nativeFileApplications @@ -198,7 +203,11 @@ export class SessionController extends TypertRemoteService { ctx.effect(() => async () => { await Promise.allSettled([...this.promotions]) }, 'session-controller.promotions') - this.history = new SessionHistoryController(ctx, (observation) => { this.promote(observation) }) + // Assistant-stream observation must be live before the list read yields: an Agent's + // opening frame arriving during that await would otherwise have no listener. + this.historyController = new HistoryController(ctx) + this.stateController = new StateController(ctx, this.historyController) + this.webController = new WebController(ctx, this.historyController, (observation) => { this.promote(observation) }) this.listState = new ApiSessionList(ctx, this.listWorkSliceMs) await this.listState.initialize() ctx.plugin(SessionFileReferences) @@ -234,6 +243,10 @@ export class SessionController extends TypertRemoteService { }) } + /** + * Request background activation through the existing Session Agent controller. + * @param observation - owned lease disposed by the background task; callers retain their own lease separately. + */ private promote(observation: SessionObservation): void { const sessionId = observation.header.id const task = (async () => { @@ -476,8 +489,8 @@ export class SessionController extends TypertRemoteService { } /** - * Read one image proven reachable from the addressed Session log. - * @param request - Session and attachment identities used for authorization. + * Read one image from the attachment store after gateway authorization. + * @param request - image reference and gateway permission scope; Session existence is not checked. * @returns the durable attachment reference and base64-encoded bytes. */ @Remote('attachment') @@ -507,13 +520,80 @@ export class SessionController extends TypertRemoteService { /** * Read one cold-safe, message-aligned Session history page. - * @param request - durable address, backward cursor, and page budget. + * @deprecated Use `events`; this entry point remains for existing Web callers. + * @param request - durable address, optional fixed cut, backward cursor, and page budget. * @param signal - cancellation for persistence reads. - * @returns one chronological page. + * @returns one chronological page with its inclusive cursor; an omitted `throughSeq` selects the observed log end. */ @Remote('page') - page(request: SessionPageRequest, signal: AbortSignal): Promise { - return this.history.page(request, signal) + page(request: SessionPageRequest, signal: AbortSignal): Promise { + return this.historyController.events(request, signal) + } + + /** + * Read one cold-safe, message-aligned Session history page. + * @param request - durable address, optional fixed cut, backward cursor, and page budget. + * @param signal - cancellation for persistence reads. + * @returns one chronological page with its inclusive cursor. + */ + @Remote + events(request: SessionPageRequest, signal: AbortSignal): Promise { + return this.historyController.events(request, signal) + } + + /** + * Subscribe to Session events without reading a snapshot. + * @param request - Session address. + * @param signal - subscription cancellation. + * @returns readiness and subsequent events, without a snapshot. + */ + @Remote({ mode: 'stream' }) + observeEvent(request: SessionObserveEventRequest, signal: AbortSignal): AsyncIterable { + return this.historyController.observeEvent(request, signal) + } + + /** + * Subscribe to sparse Session projection changes. + * @param request - target Session. + * @param signal - subscription cancellation. + * @returns readiness and sparse projection changes. + */ + @Remote({ mode: 'stream' }) + observeProjections(request: SessionProjectionsRequest, signal: AbortSignal): AsyncIterable { + return this.historyController.observeProjections(request, signal) + } + + /** + * Read passive Session state. + * @param request - target Session. + * @param signal - read cancellation. + * @returns current passive state. + */ + @Remote + state(request: SessionStateRequest, signal: AbortSignal): Promise { + return this.stateController.state(request, signal) + } + + /** + * Subscribe to complete Session state replacements. + * @param request - target Session. + * @param signal - subscription cancellation. + * @returns complete passive state replacements. + */ + @Remote({ mode: 'stream' }) + observeState(request: SessionStateRequest, signal: AbortSignal): AsyncIterable { + return this.stateController.observeState(request, signal) + } + + /** + * Wait for Session quiescence or pending input with bounded assistant output. + * @param request - Session, wait bounds and output window. + * @param signal - caller cancellation. + * @returns stopping state and bounded assistant output. + */ + @Remote + wait(request: SessionWaitRequest, signal: AbortSignal): Promise { + return this.stateController.wait(request, signal) } /** @@ -525,7 +605,7 @@ export class SessionController extends TypertRemoteService { */ @Remote({ mode: 'stream' }) follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable { - return this.history.follow(request, signal) + return this.webController.follow(request, signal) } /** @@ -535,49 +615,8 @@ export class SessionController extends TypertRemoteService { * @returns a sequenced baseline, cached hints when migration is deferred, or null when absent. */ @Remote('projections') - async projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise { - const { sessionId } = request - if (sessionId.length === 0) { - throw new RemoteError('gateway/bad-request', 'sessionId must not be empty', {}) - } - try { - signal.throwIfAborted() - const live = this.liveProjections(sessionId) - if (live !== undefined) return live - const stored = await this.ctx.get('sessionPersistence')?.stat(sessionId, { signal }) - signal.throwIfAborted() - const attached = this.liveProjections(sessionId) - if (attached !== undefined) return attached - if (stored === undefined) return null - if (stored.formatStatus === 'migration-required') { - const cached = this.ctx.get('sessionProjectionCache')?.cachedSnapshot(stored.header) - return { kind: 'migration-required', values: { ...cached?.values } as SessionProjectionValues } - } - using observation = await this.ctx.sessionQuery.observeSession(sessionId, { signal }) - const projections = observation.projections - if (projections === undefined) { - throw new RemoteError('session/projections-unavailable', 'Session projections are unavailable', {}) - } - return { kind: 'sequenced', asOfSeq: projections.asOfSeq, values: projections.values as SessionProjectionValues } - } catch (error: unknown) { - if (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') { - return this.liveProjections(sessionId) ?? null - } - if (signal.aborted || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED')) { - throw new RemoteError('gateway/cancelled', 'Session projection read was cancelled', {}, { cause: error }) - } - if (error instanceof RemoteError) throw error - throw new RemoteError('gateway/internal', 'Session projection read failed', {}, { cause: error }) - } - } - - private liveProjections( - sessionId: SessionId, - ): Extract | undefined { - const session = this.ctx.sessions.get(sessionId) - if (session === undefined) return undefined - const snapshot = this.ctx.sessionProjections.snapshot(session) - return { kind: 'sequenced', asOfSeq: snapshot.asOfSeq, values: snapshot.values as SessionProjectionValues } + projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise { + return this.historyController.projections(request, signal) } /** diff --git a/packages/api/session-controller/src/state/controller.ts b/packages/api/session-controller/src/state/controller.ts new file mode 100644 index 0000000000..60b97776d9 --- /dev/null +++ b/packages/api/session-controller/src/state/controller.ts @@ -0,0 +1,221 @@ +/** Passive Session state, coalesced observations and quiescence waits. */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type {} from '@deepseek-ai/dsh-api-gateway' +import type { UserMessage } from '@deepseek-ai/dsh-llm' +import type { SessionId } from '@deepseek-ai/dsh-session' +import { deadline, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout' +import { RemoteError } from '@deepseek-ai/dsh-typert-protocol' +import type { JsonValue } from '@deepseek-ai/dsh-util-values' +import type { HistoryController } from '../history/controller.ts' +import { DEFAULT_MAX_MESSAGES, rejectNotFound } from '../history.ts' +import type { SessionPendingInput, SessionQueuedItem, SessionState, SessionStateRequest, SessionWaitRequest, SessionWaitValue } from '../types.ts' + +import { StateListener } from './listener.ts' +import type { VersionedSessionState } from './listener.ts' + +const DEFAULT_WAIT_TIMEOUT_MS = 30_000 + +/** Reads and waits without activating or cancelling Session execution. */ +export class StateController { + + /** + * @param ctx - live Session and pending Remote event services. + * @param historyController - passive read entry used for cold state and its bounded output. + */ + constructor(private readonly ctx: Context, private readonly historyController: HistoryController) {} + + /** + * Read passive execution and pending-input state. + * @param request - Session identity. + * @param signal - read cancellation. + * @returns current passive state. + */ + async state(request: SessionStateRequest, signal: AbortSignal): Promise { + return this.readState(request.sessionId, signal) + } + + /** + * Observe complete passive state replacements. + * @param request - Session identity. + * @param signal - observation cancellation. + * @returns complete state replacements, starting with the current state. + */ + async *observeState(request: SessionStateRequest, signal: AbortSignal): AsyncIterable { + using listener = this.listen(request.sessionId, signal) + for await (const { state } of listener.observeStates()) yield state + } + + /** + * Wait for quiescence, pending input, or the deadline without cancelling execution. + * @param request - Session identity, timeout and assistant output window. + * @param signal - cancellation of this wait only, never of Agent execution. + * @returns the stopping reason and last complete state; no state before timeout is an error. + */ + async wait(request: SessionWaitRequest, signal: AbortSignal): Promise { + const timeoutMs = request.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS + const afterSeq = request.afterSeq ?? -1 + const maxMessages = request.maxMessages ?? DEFAULT_MAX_MESSAGES + if (!Number.isSafeInteger(afterSeq) || afterSeq < -1 || Object.is(afterSeq, -0)) { + throw new RemoteError('gateway/bad-request', 'afterSeq must be an integer greater than or equal to -1', {}) + } + if (!Number.isSafeInteger(maxMessages) || maxMessages <= 0) { + throw new RemoteError('gateway/bad-request', 'maxMessages must be a positive safe integer', {}) + } + if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMER_DELAY_MS) { + throw new RemoteError('gateway/bad-request', 'timeoutMs must be a positive supported timer delay', {}) + } + using timer = deadline(signal, timeoutMs, 'session/wait-timeout') + using listener = this.listen(request.sessionId, timer.signal) + const sessionId = request.sessionId + const statesGenerator = listener.observeStates(1_000) + let nextStatePromise = statesGenerator.next() + let currentState: SessionState | undefined + let reason: SessionWaitValue['reason'] = 'timeout' + try { + for (;;) { + const observedState = await nextStatePromise + if (observedState.done) { + timer.signal.throwIfAborted() + throw new RemoteError('session/observation-ended', 'Session observation ended before a stopping state', {}) + } + nextStatePromise = statesGenerator.next() + // Observe rejection on immediate exits without replacing the original demand. + void nextStatePromise.catch(() => undefined) + // Only a state the listener still confirms may drive this wait; an invalidated + // sample never becomes the state a timeout reports. + if (!listener.isCurrent(observedState.value.revision)) continue + currentState = observedState.value.state + const action = computeWaitAction(currentState) + if (action === 'continue') continue + if (action === 'input-required' || action === 'idle') { + reason = action + break + } + + const agent = this.ctx.agents.get(sessionId) + if (agent === undefined || this.ctx.sessions.get(sessionId) !== agent.session) continue + if (await waitForIdleOrStateChange(agent, nextStatePromise) === 'state-changed') continue + if (!listener.isCurrent(observedState.value.revision) || this.ctx.agents.get(sessionId) !== agent + || this.ctx.sessions.get(sessionId) !== agent.session) continue + reason = 'idle' + break + } + } catch (error: unknown) { + // A caller cancellation is never a wait outcome; the deadline absorbs only the read + // it cancelled, and any other failure keeps its own error. + if (signal.aborted) throw signal.reason + if (!expired(timer.signal, error)) throw error + } finally { + // Wake/cancel a pending read before asking the generator to return. + listener[Symbol.dispose]() + await nextStatePromise.catch(() => undefined) + await statesGenerator.return(undefined) + } + signal.throwIfAborted() + if (currentState === undefined) throw new RemoteError('session/wait-timeout', 'No Session state arrived before the wait deadline', {}) + const output = await this.historyController.assistantOutput( + sessionId, afterSeq, currentState.cursor, maxMessages, signal, + ) + return { reason, state: currentState, output } + } + + private listen(sessionId: SessionId, signal: AbortSignal): StateListener { + return new StateListener(this.ctx, sessionId, signal, readSignal => this.readState(sessionId, readSignal)) + } + + /** + * @param sessionId - Session to sample. + * @param signal - read cancellation. + * @param retried - whether a live source already redirected this read once. + * @returns one passive state sample. + */ + private async readState(sessionId: SessionId, signal: AbortSignal, retried = false): Promise { + signal.throwIfAborted() + const agent = this.ctx.agents.get(sessionId) + if (agent !== undefined) { + if (agent.session.header.cwd === undefined) rejectNotFound({ kind: 'session', sessionId }) + return { + cursor: agent.session.seq - 1, + active: true, + running: agent.status === 'running', + queue: queueItems(agent), + pendingInput: this.pendingInput(agent.session.id), + } + } + const state = await this.historyController.usingObservation({ sessionId, projection: false }, signal, (observation) => { + // A live source means the Session attached during this read; report its live state + // rather than a live cursor paired with an inactive sample. + if (!retried && observation.source === 'live') return undefined + if (observation.header.cwd === undefined) rejectNotFound({ kind: 'session', sessionId }) + return { + cursor: observation.cursor, + active: false, + running: false, + queue: null, + pendingInput: this.pendingInput(observation.header.id), + } + }) + signal.throwIfAborted() + return state ?? this.readState(sessionId, signal, true) + } + + private pendingInput(sessionId: SessionId): readonly SessionPendingInput[] { + const kinds = new Set() + for (const { event, agentId } of this.ctx.typertGateway.getPendingRemoteEvents()) { + if (String(agentId) !== sessionId) continue + kinds.add(event === 'approval/request' ? 'approval' : event === 'user-questions/request' ? 'question' : 'other') + } + return [...kinds] + } +} + +/** + * @param signal - wait deadline signal. + * @param error - failure raised by the in-flight read. + * @returns whether the deadline expired and cancelled that read. + */ +function expired(signal: AbortSignal, error: unknown): boolean { + const reason = timeoutOf(signal, 'session/wait-timeout') + if (reason === undefined) return false + // Cancellation carries the deadline reason along its cause chain; any other failure does not. + let current: unknown = error + for (let depth = 0; depth < 4 && current instanceof Error; depth++) { + if (current === reason || current.cause === reason) return true + current = current.cause + } + return error === reason +} + +/** Choose the next wait action; check-idle requires the caller's whenIdle and identity checks. */ +function computeWaitAction(state: SessionState): 'input-required' | 'continue' | 'idle' | 'check-idle' { + if (state.pendingInput.length > 0) return 'input-required' + if (state.running) return 'continue' + if (!state.active) return 'idle' + return 'check-idle' +} + +/** Wait for either driver quiescence or the already-armed next state; preserve rejections from both. */ +function waitForIdleOrStateChange( + agent: Agent, + nextStatePromise: Promise>, +): Promise<'idle' | 'state-changed'> { + return Promise.race([ + agent.whenIdle().then(() => 'idle' as const), + nextStatePromise.then(() => 'state-changed' as const), + ]) +} + +function queueItems(agent: Agent): SessionQueuedItem[] { + const item = (message: UserMessage, placement: SessionQueuedItem['placement']): SessionQueuedItem => ({ + id: message.id, + placement, + ...message.source.kind === 'user' && 'rpcId' in message.source ? { rpcId: message.source.rpcId } : {}, + content: message.content as typeof message.content & readonly JsonValue[], + }) + return [ + ...agent.inbox.nextTurn.map(message => item(message, 'queued')), + ...agent.inbox.nextStep.map(message => item(message, message.source.kind === 'user' ? 'steering' : 'context')), + ] +} diff --git a/packages/api/session-controller/src/state/listener.ts b/packages/api/session-controller/src/state/listener.ts new file mode 100644 index 0000000000..15633a7cd8 --- /dev/null +++ b/packages/api/session-controller/src/state/listener.ts @@ -0,0 +1,116 @@ +/** Coalesced Session state observations with Host-local revisions. */ + +import type { Context } from '@deepseek-ai/cordis' +import type { SessionId } from '@deepseek-ai/dsh-session' +import type { SessionState } from '../types.ts' + +/** One complete state with its listener-local revision. */ +export interface VersionedSessionState { state: SessionState; revision: number } + +/** Coalesces Session/Agent invalidations with local revisions; pending events are sampled on reads. */ +export class StateListener implements Disposable { + private readonly disposes: (() => void)[] = [] + private readonly cancellation = new AbortController() + private readonly signal: AbortSignal + private revision = 0 + private resolver = createDeferredSignal() + private closed = false + + /** + * @param ctx - lifecycle notification owner. + * @param target - Session to observe. + * @param signal - caller cancellation. + * @param readState - passive complete-state reader. + */ + constructor( + ctx: Context, target: SessionId, signal: AbortSignal, + private readonly readState: (signal: AbortSignal) => Promise, + ) { + signal.throwIfAborted() + this.signal = AbortSignal.any([signal, this.cancellation.signal]) + const notify = (id: string | undefined): void => { + if (id !== target || this.closed) return + this.revision++ + const resolver = this.resolver + this.resolver = createDeferredSignal() + resolver.resolve() + } + const close = (): void => { this[Symbol.dispose]() } + signal.addEventListener('abort', close, { once: true }) + this.disposes.push(() => { signal.removeEventListener('abort', close) }) + try { + this.disposes.push(ctx.on('session/event', (session) => { notify(session.id) }, { global: true })) + this.disposes.push(ctx.on('session/created', (session) => { notify(session.id) }, { global: true })) + this.disposes.push(ctx.on('session/disposed', (session) => { notify(session.id) }, { global: true })) + this.disposes.push(ctx.on('agent/status', ({ agent }) => { notify(agent.id) }, { global: true })) + this.disposes.push(ctx.on('agent/created', ({ agent }) => { notify(agent.id) }, { global: true })) + this.disposes.push(ctx.on('agent/disposed', ({ agent }) => { notify(agent.id) }, { global: true })) + const dispose = ctx.effect(() => close, 'session-controller.state-listener') + this.disposes.push(() => { void dispose() }) + } catch (error: unknown) { + this[Symbol.dispose]() + throw error + } + } + + /** + * Check whether a completed read still represents the latest invalidation. + * @param revision - revision captured with a completed read. + * @returns whether no intervening invalidation occurred. + */ + isCurrent(revision: number): boolean { return !this.closed && revision === this.revision } + + /** + * Read coalesced state replacements with optional periodic refresh. + * @param refreshMs - optional idle recheck interval; omitted for event-only observation. + * @returns complete state replacements with internal consistency revisions. + */ + async *observeStates(refreshMs?: number): AsyncGenerator { + let lastRevision = -1 + try { + while (!this.closed) { + if (lastRevision === this.revision) { + if (refreshMs === undefined) { + await this.resolver.promise + } else { + let timer: ReturnType | undefined + try { + await Promise.race([ + this.resolver.promise, + new Promise((resolve) => { timer = setTimeout(resolve, refreshMs) }), + ]) + } finally { + clearTimeout(timer) + } + if (this.isCurrent(lastRevision)) { + this.revision++ + const resolver = this.resolver + this.resolver = createDeferredSignal() + resolver.resolve() + } + } + } + if (!this.isCurrent(this.revision)) return + lastRevision = this.revision + const state = await this.readState(this.signal) + if (this.isCurrent(lastRevision)) yield { state, revision: lastRevision } + } + } finally { + this[Symbol.dispose]() + } + } + + [Symbol.dispose](): void { + if (this.closed) return + this.closed = true + this.cancellation.abort() + this.resolver.resolve() + for (const dispose of this.disposes.splice(0).reverse()) dispose() + } +} + +function createDeferredSignal(): { promise: Promise; resolve: () => void } { + let resolve!: () => void + const promise = new Promise((settle) => { resolve = settle }) + return { promise, resolve } +} diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index 8c6da77a60..9e399d8f3b 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -3,11 +3,11 @@ import type {} from '@deepseek-ai/dsh-agent/types' import type { NativeFileApplication } from '@deepseek-ai/dsh-native-command/types' import type { - AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, + ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, } from '@deepseek-ai/dsh-attachment' import type { Branded } from '@deepseek-ai/dsh-brand' import type { LlmAttemptId, MessageId } from '@deepseek-ai/dsh-llm/brand' -import type { TextBlock } from '@deepseek-ai/dsh-llm' +import type { LlmModelBadge, TextBlock } from '@deepseek-ai/dsh-llm' import type { SessionId, SessionSeqCursor } from '@deepseek-ai/dsh-session/types' import type { SessionProjectionMap, SessionProjectionSummaryExcluded, SessionProjectionSummaryValues } from '@deepseek-ai/dsh-session-projection/types' import type { Principal } from '@deepseek-ai/dsh-typert-protocol' @@ -110,6 +110,8 @@ export interface ModelCatalogModel { readonly name: string readonly description?: string readonly reasoning?: ModelReasoning + /** Provider-authored label shown beside the name; display data only. */ + readonly badge?: LlmModelBadge } /** One provider and its successfully loaded model catalog. */ @@ -175,6 +177,10 @@ export const SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS = 240 declare module '@deepseek-ai/dsh-typert-protocol' { interface RemoteErrorDetailsMap { + /** A wait observation ended before a stopping state; the caller should reread. */ + 'session/observation-ended': Record + /** No state arrived before the deadline; a timeout after a state returns its value instead. */ + 'session/wait-timeout': Record 'session/provider-credentials-unavailable': Record 'session/provider-models-unavailable': { readonly provider: string } 'session/model-unavailable': { readonly provider: string; readonly model: string } @@ -329,12 +335,14 @@ export interface SessionPromptValue { /** Durable image read request. */ export interface SessionAttachmentRequest { + /** Gateway permission scope only; neither Session existence nor its image references are checked. */ readonly sessionId: SessionId - readonly attachmentId: AttachmentIdType + readonly attachment: ImageAttachmentRef } /** Durable image read response value. */ export interface SessionAttachmentValue { + /** Supplied reference after ID, format, byte length, and dimensions verification; display fields are preserved. */ readonly attachment: ImageAttachmentRef readonly data: string } @@ -459,8 +467,11 @@ export interface SessionWireEvent { /** One message-aligned backwards-history request. */ export interface SessionPageRequest { readonly address: SessionAddress - /** Inclusive log cut obtained from the corresponding follow opening frame. */ - readonly throughSeq: number + /** + * Inclusive log cut; omission selects the observed log end. A follow opening + * reports the cut it covered so a caller can pin the same point. + */ + readonly throughSeq?: number readonly beforeSeq?: number readonly maxMessages?: number /** Stop at a Turn start after both minima, unless maxMessages or history exhaustion wins. */ @@ -475,6 +486,8 @@ export interface SessionPageRequest { /** One live event request for a durable Session address. */ export interface SessionFollowRequest extends Pick { readonly address: SessionAddress + /** Request background activation; omission leaves the read passive. */ + readonly activate?: boolean /** Include process-local assistant presentation frames for the Web client. */ readonly assistantStream?: true } @@ -569,6 +582,84 @@ export type SessionControlFrame = | { readonly type: 'baseline'; readonly value: SessionControlBaseline } | ({ readonly type: 'projection' } & SessionProjectionUpdate) +/** One pending live-Agent inbox item, preserving placement and content order. */ +export interface SessionQueuedItem { + readonly id: MessageId + readonly placement: 'queued' | 'steering' | 'context' + readonly rpcId?: SessionRequestId + readonly content: readonly JsonValue[] +} + +/** State-owned classification of pending forwarded Remote events. */ +export type SessionPendingInput = 'approval' | 'question' | 'other' + +/** Passive Session state; a missing live Agent has no readable queue. */ +export interface SessionState { + readonly cursor: number + readonly active: boolean + readonly running: boolean + readonly queue: readonly SessionQueuedItem[] | null + /** + * Pending Remote requests sampled when this state was read. A pending change alone does not + * trigger `observeState`; `wait` refreshes on its own interval. + */ + readonly pendingInput: readonly SessionPendingInput[] +} + +/** Session identity for a passive state read or subscription. */ +export interface SessionStateRequest { + readonly sessionId: SessionId +} + +/** Wait bounds and assistant output window; timeout omission uses the fixed 30-second default. */ +export interface SessionWaitRequest extends SessionStateRequest { + readonly timeoutMs?: number + /** Exclusive output cursor; omission includes all available assistant records. */ + readonly afterSeq?: number + /** Positive assistant-record limit; omission uses the history message budget. */ + readonly maxMessages?: number +} + +/** Assistant messages after afterSeq through the stopping state's cursor, newest first. */ +export interface SessionWaitOutput { + readonly records: readonly SessionHistoryRecord[] + /** More eligible assistant messages exist in the selected interval. */ + readonly truncated: boolean +} + +/** A stopping condition, the last complete passive state and its bounded assistant output. */ +export interface SessionWaitValue { + readonly reason: 'idle' | 'input-required' | 'timeout' + readonly state: SessionState + readonly output: SessionWaitOutput +} + +/** + * One `session.events` page (or its deprecated `page` alias) with its inclusive cut: + * the supplied `throughSeq`, otherwise the log end it was read at. + */ +export interface SessionEventsPage extends SessionPage { + readonly cursor: number +} + +/** Address for a passive event subscription. */ +export interface SessionObserveEventRequest { + readonly address: SessionAddress +} + +/** Readiness confirms subscription only; event continuity starts with the first delivered event. */ +export type SessionEventFrame = + | { readonly type: 'ready' } + | SessionEventEntry + +/** One sparse per-key replacement; different keys can share a seq. */ +export type SessionProjectionChange = { readonly type: 'projection' } & Omit + +/** Subscription readiness without a baseline, followed by per-key changes. */ +export type SessionProjectionFrame = + | { readonly type: 'ready' } + | SessionProjectionChange + declare module '@deepseek-ai/cordis' { interface Events { /** diff --git a/packages/api/session-controller/src/web/controller.ts b/packages/api/session-controller/src/web/controller.ts new file mode 100644 index 0000000000..7e849e4cca --- /dev/null +++ b/packages/api/session-controller/src/web/controller.ts @@ -0,0 +1,78 @@ +/** Web opening aggregation over one observation and a shared transforming buffer. */ + +import type { Context } from '@deepseek-ai/cordis' +import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol' +import type { SessionObservation } from '@deepseek-ai/dsh-session-query' +import type { HistoryController } from '../history/controller.ts' +import { addressId, rejectNotFound } from '../history.ts' +import { EventListener, ListenerBuffer } from '../history/listener.ts' +import { history, projections, resolveHistoryRequest, validateObservationAddress } from '../history/controller.ts' +import type { SessionFollowFrame, SessionFollowRequest } from '../types.ts' + +/** Combines opening data and consumes transformed listener output from one queue. */ +export class WebController { + + /** + * @param ctx - Host context carrying Session queries and identity projections. + * @param historyController - passive reading and listener construction. + * @param promote - background activation requested before an opening snapshot is delivered. + */ + constructor( + private readonly ctx: Context, + private readonly historyController: HistoryController, + private readonly promote: (observation: SessionObservation) => void, + ) {} + + /** + * Open a history snapshot and follow uncovered history and assistant notifications. + * @param request - Session identity, page budget, assistant output and optional activation (default false). + * @param signal - cancellation for opening and streaming. + * @returns an opening snapshot followed by uncovered queued increments. + */ + async *follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable { + const sessionId = addressId(request.address) + const spec = resolveHistoryRequest(request) + using queue = new ListenerBuffer(this.ctx, signal) + using listener = new EventListener(this.ctx, sessionId, signal, queue) + const streams = this.historyController.streamsListener + using assistantListener = request.assistantStream === true + ? streams.bind(sessionId, signal, queue) + : undefined + using observation = await this.historyController.usingObservation({ sessionId, projection: true }, signal) + .catch((error: unknown) => { + if (remoteErrorOf(error)?.code === 'session/not-found') rejectNotFound(request.address) + throw error + }) + validateObservationAddress(request.address, observation) + let opening: SessionFollowFrame = { + type: 'snapshot', + header: { ...observation.header }, + projections: projections(observation), + ...history(observation, spec), + } + listener.setCursor(opening.cursor) + if (assistantListener !== undefined) { + const { baseline: assistantStream, ordinal } = assistantListener.snapshot() + opening = { ...opening, assistantStream } + assistantListener.setOrdinalCut(ordinal) + } + // Increments come from the queue, so the opening ends this lease in every branch; + // activation continues on its own retained lease. Promotion starts before the opening is + // delivered, so a consumer that stops after the snapshot still gets the activation it asked for. + if (request.activate === true && !signal.aborted + && observation.header.origin !== 'subagent' && observation.source === 'prepared') { + const promotion = observation.retain() + observation[Symbol.dispose]() + try { + this.promote(promotion) + } catch (error: unknown) { + promotion[Symbol.dispose]() + throw error + } + } else { + observation[Symbol.dispose]() + } + yield opening + yield* queue.items() + } +} diff --git a/packages/api/session-controller/tests/client-contract.client.spec.ts b/packages/api/session-controller/tests/client-contract.client.spec.ts index b2abdc2dc2..20a0f08065 100644 --- a/packages/api/session-controller/tests/client-contract.client.spec.ts +++ b/packages/api/session-controller/tests/client-contract.client.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, expectTypeOf, it, vi } from 'vitest' import type { PromptContentPart as AttachmentPromptContentPart } from '@deepseek-ai/dsh-attachment/types' -import { SessionSeq, type SessionSeqCursor } from '@deepseek-ai/dsh-session/types' +import { SessionSeq, type SessionId, type SessionSeqCursor } from '@deepseek-ai/dsh-session/types' import { MutableSessionEventSource, type SessionAssistantSettlementEntry, type SessionLiveEventEntry, type SessionTransientEventEntry, @@ -11,6 +11,7 @@ import type { ProjectionsBaseline } from '../src/client/sessions/projection-stor import { ProjectionValueStore } from '../src/client/sessions/projection-store.ts' import type { PromptContentPart as SessionPromptContentPart, SessionPageRequest } from '../src/types.ts' import { ev, plainTurn } from './event-script.client.ts' +import { history, pageRule } from './remote/session.client.ts' type RenameSuccess = Extract>, { readonly ok: true }> @@ -70,7 +71,21 @@ describe('Client Session contracts', () => { expectTypeOf().toEqualTypeOf() expectTypeOf().parameter(2).toEqualTypeOf() expectTypeOf().toEqualTypeOf() - expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + }) + + it('returns the current page cursor when throughSeq is omitted and preserves explicit cuts', async () => { + const address = { kind: 'session', sessionId: 'page-fixture' as SessionId } as const + const rule = pageRule(history(plainTurn(SessionSeq(0), 1, 'question', 'answer'))) + const current = await rule({ address }) + expect(current).toMatchObject({ ok: true, value: { cursor: 5, hasMore: false } }) + const cut = await rule({ address, throughSeq: 2 }) + expect(cut).toMatchObject({ ok: true, value: { cursor: 2, hasMore: false } }) + if (!cut.ok) throw new Error('expected a successful history page') + expect(cut.value.records.map(record => record.event.seq)).toEqual([0, 1, 2]) + await expect(rule({ address, throughSeq: -1 })).resolves.toEqual({ + ok: true, value: { cursor: -1, records: [], hasMore: false }, + }) }) it('keeps its text and image prompt parts identical to attachment intake', () => { diff --git a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts index 7d46edda4e..f575583063 100644 --- a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts +++ b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts @@ -6,19 +6,19 @@ import AgentRegistry from '@deepseek-ai/dsh-agent' import type { Agent, Inbox } from '@deepseek-ai/dsh-agent' import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' -import { createAssistantMessage, createUserMessage, MessageId } from '@deepseek-ai/dsh-llm' +import { createUserMessage, MessageId } from '@deepseek-ai/dsh-llm' import type { ContextFormed } from '@deepseek-ai/dsh-llm' import SessionStore, { - SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset, SessionSeq, + Session, SessionId, SessionLogOffset, } from '@deepseek-ai/dsh-session' -import type { SessionEvent, SessionHeader, UserMessage } from '@deepseek-ai/dsh-session' +import type { UserMessage } from '@deepseek-ai/dsh-session' import { snapshotSubagentDescriptor, SUBAGENT_DESCRIPTOR_VERSION } from '@deepseek-ai/dsh-subagent' import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts' import { describe, expect, it, vi } from 'vitest' import { ApiSessionAgentController } from '../src/agent.ts' import { SessionCommandController } from '../src/commands.ts' import { unsupportedModel, createInboxStub } from '@deepseek-ai/dsh-agent-loop-testkit' -import { installSessionReadTestServices, testSessionPersistence } from './test-remote.ts' +import { installSessionReadTestServices } from './test-remote.ts' declare module '@deepseek-ai/dsh-llm' { interface MessageSourceMap { @@ -324,277 +324,68 @@ describe('Session queue commands', () => { }) }) -function imageRef(id: string): ImageAttachmentRef { - return { - attachmentId: AttachmentId(id), - mediaType: 'image/png', - bytes: 1, - width: 1, - height: 1, - } -} - -function event(type: string, seq: SessionSeq, data: unknown): SessionEvent { - const surface = ['user/message', 'system/message', 'developer/message', 'tool/result'].includes(type) - return { type, seq, time: seq + 1, data, ...surface ? { surfaceOp: 'append' } : {} } as SessionEvent -} - -async function persistedController( - events: SessionEvent[], - readImage: (ref: ImageAttachmentRef) => Promise<{ ref: ImageAttachmentRef; data: Uint8Array }>, - workspace: Pick = { cwd: '/workspace' }, -): Promise<{ ctx: Context; controller: SessionCommandController; sessionId: SessionId }> { - const ctx = new Context() - await ctx.plugin(SessionStore) - const sessionId = SessionId('cold-attachment') - const meta: SessionHeader = { - version: SESSION_FORMAT_VERSION, - id: sessionId, - createdAt: 1, - ...workspace, - isSeeded: false, - } - ctx.provide('sessionPersistence', testSessionPersistence(ctx, { - list: () => Promise.resolve([meta]), - inspect: () => Promise.resolve({ - meta, - inheritedEventCount: SessionLogOffset(0), - events, - }), - }) as never) - installSessionReadTestServices(ctx) - ctx.provide('attachments', { readImage } as never) - const agents = { resolveAgent: vi.fn() } as unknown as ApiSessionAgentController - return { ctx, controller: new SessionCommandController(ctx, agents, '/workspace'), sessionId } -} - -describe('Session attachment authorization', () => { - it.each([ - ['system/message', 'message'], ['developer/message', 'message'], ['tool/result', 'message'], - ['team/message/queued', 'message'], ['tool/ptc-dispatch', 'content'], - ['compaction/summary', 'summary'], ['compaction/summary', 'rawOutput'], - ] as const)('reads the declared %s %s content without rewriting it', async (type, field) => { - const ref = imageRef(`${type}-${field}`) - const content = [{ type: 'image', attachment: ref }] - const message = type === 'team/message/queued' ? { content } - : type === 'tool/result' ? { - id: 'declared-message', role: 'tool', source: { kind: 'tool', callId: 'declared-call' }, - toolCallId: 'declared-call', isError: false, content, - } : { - id: 'declared-message', role: type === 'developer/message' ? 'developer' : 'system', - source: { kind: 'system-prompt' }, content, - } - const data = field === 'message' ? { message } : { [field]: content } - const events = [event(type, SessionSeq(0), data)] - const saved = JSON.stringify(events) - const readImage = vi.fn((image: ImageAttachmentRef) => Promise.resolve({ ref: image, data: Uint8Array.of(1) })) - const fixture = await persistedController(events, readImage) +describe('Session attachment reads', () => { + it.each(['commands-session', 'other-session', 'missing-session'])('reads a supplied reference without looking up history for %s', async (id) => { + const { ctx, controller, agent, resolveAgent } = await commandHarness() + const ref: ImageAttachmentRef = { + attachmentId: AttachmentId(`sha256:${'ab'.repeat(32)}`), + mediaType: 'image/png', bytes: 2, width: 1, height: 1, + } + agent.session.append('user/message', createUserMessage({ + content: [{ type: 'image', attachment: ref }], source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + const readImage = vi.fn(() => Promise.resolve({ ref, data: Uint8Array.of(1, 2) })) + ctx.provide('attachments', { readImage } as never) + const failHistory = (): never => { throw new Error('image reads must not access Session history') } + const get = vi.spyOn(ctx.sessions, 'get').mockImplementation(failHistory) + const snapshot = vi.spyOn(agent.session, 'snapshotEvents').mockImplementation(failHistory) + const observe = vi.spyOn(ctx.sessionQuery, 'observeSession').mockImplementation(failHistory) try { - await expect(fixture.controller.attachment({ sessionId: fixture.sessionId, attachmentId: ref.attachmentId })) - .resolves.toEqual({ attachment: ref, data: 'AQ==' }) + await expect(controller.attachment({ sessionId: SessionId(id), attachment: ref })) + .resolves.toEqual({ attachment: ref, data: 'AQI=' }) expect(readImage).toHaveBeenCalledExactlyOnceWith(ref) - expect(JSON.stringify(events)).toBe(saved) + expect(get).not.toHaveBeenCalled() + expect(snapshot).not.toHaveBeenCalled() + expect(observe).not.toHaveBeenCalled() + expect(resolveAgent).not.toHaveBeenCalled() } finally { - await fixture.ctx.fiber.dispose() + get.mockRestore() + snapshot.mockRestore() + observe.mockRestore() + await ctx.fiber.dispose() } }) - it('does not authorize an attachment through malformed inbox entries', async () => { - const ref = imageRef('not-referenced') - for (const value of [undefined, null, {}, [null, 1, []]]) { - const readImage = vi.fn((image: ImageAttachmentRef) => Promise.resolve({ ref: image, data: Uint8Array.of(1) })) - const fixture = await persistedController([event('agent/inbox/spliced', SessionSeq(0), { inserted: value })], readImage) - try { - await expect(fixture.controller.attachment({ sessionId: fixture.sessionId, attachmentId: ref.attachmentId })) - .rejects.toMatchObject({ code: 'session/attachment-invalid', details: { reason: 'ATTACHMENT_NOT_REFERENCED' } }) - expect(readImage).not.toHaveBeenCalled() - } finally { - await fixture.ctx.fiber.dispose() - } - } - }) - - it('ignores unrelated fields of a known message event and its content blocks', async () => { - const ref = imageRef('not-a-content-occurrence') - const content = [{ type: 'image', attachment: ref }] - const stored = event('user/message', SessionSeq(0), { - id: 'metadata', role: 'user', source: { kind: 'user' }, - content: [{ type: 'text', text: 'no image', content }, { type: 'plugin:vendor', data: { content }, content }], - message: { content }, inserted: [{ content }], - }) - const readImage = vi.fn((image: ImageAttachmentRef) => Promise.resolve({ ref: image, data: Uint8Array.of(1) })) - const fixture = await persistedController([stored], readImage) - try { - await expect(fixture.controller.attachment({ sessionId: fixture.sessionId, attachmentId: ref.attachmentId })) - .rejects.toMatchObject({ code: 'session/attachment-invalid' }) - expect(readImage).not.toHaveBeenCalled() - } finally { - await fixture.ctx.fiber.dispose() - } - }) - - it.each(['external/image-record', 'session/title-llm-request'])('denies attachment access from %s without an attachment carrier', async (type) => { - const ref = imageRef('opaque-event-image') - const content = [{ type: 'image', attachment: ref }] - const opaque = { ...event(type, SessionSeq(0), { - content, message: { content }, inserted: [{ content }], messages: [{ content }], - stream: [{ type: 'chunk', time: 1, chunk: { type: 'block-end', index: 0, block: content[0] } }], - }), ignorable: true as const } - const readImage = vi.fn((image: ImageAttachmentRef) => Promise.resolve({ ref: image, data: Uint8Array.of(1) })) - const fixture = await persistedController([opaque], readImage) - try { - await expect(fixture.controller.attachment({ sessionId: fixture.sessionId, attachmentId: ref.attachmentId })) - .rejects.toMatchObject({ code: 'session/attachment-invalid', details: { reason: 'ATTACHMENT_NOT_REFERENCED' } }) - expect(readImage).not.toHaveBeenCalled() - } finally { - await fixture.ctx.fiber.dispose() - } - }) - - it('finds references in direct, message, inserted, and streamed content', async () => { - const direct = imageRef('direct') - const message = imageRef('message') - const inserted = imageRef('inserted') - const streamed = imageRef('streamed') - const events: SessionEvent[] = [ - { ...event('user/message', SessionSeq(0), { - id: 'direct', role: 'user', source: { kind: 'user' }, - content: [null, [], { type: 'text', text: 'none' }, { type: 'image', attachment: direct }], - }), ignorable: true as const }, - { - type: 'assistant/message', seq: SessionSeq(1), time: 2, surfaceOp: 'append', - data: { - turn: 1, - step: 1, - stream: [], - message: createAssistantMessage({ - content: [{ type: 'image', attachment: message }], - source: { provider: 'fixture', model: 'fixture' }, - }), - }, - }, - event('agent/inbox/spliced', SessionSeq(2), { - target: 'next-turn', - start: 0, - inserted: [null, 1, [], { content: [] }, createUserMessage({ - content: [{ type: 'image', attachment: inserted }], - source: { kind: 'user' }, - })], - }), - event('assistant/attempt', SessionSeq(3), { - turn: 1, - step: 1, - stream: [ - { - type: 'chunk', - time: 3, - chunk: { type: 'block-start', index: 0, blockType: 'text' }, - }, - { - type: 'chunk', - time: 3, - chunk: { type: 'block-end', index: 0, block: { type: 'text', text: '' } }, - }, - ], - }), - event('assistant/attempt', SessionSeq(4), { - turn: 1, - step: 1, - stream: [{ - type: 'chunk', - time: 4, - chunk: { type: 'block-end', index: 0, block: { type: 'image', attachment: streamed } }, - }], - }), - ] - const readImage = vi.fn((ref: ImageAttachmentRef) => Promise.resolve({ ref, data: Uint8Array.of(1) })) - const { ctx, controller, sessionId } = await persistedController(events, readImage) - - for (const ref of [direct, message, inserted, streamed]) { - await expect(controller.attachment({ sessionId, attachmentId: ref.attachmentId })) - .resolves.toEqual({ attachment: ref, data: 'AQ==' }) - } - expect(readImage).toHaveBeenCalledTimes(4) - await ctx.fiber.dispose() - }) - - it('maps missing persistence identities and attachment backend failures', async () => { - const noPersistence = new Context() - await noPersistence.plugin(SessionStore) - installSessionReadTestServices(noPersistence) - const noPersistenceController = new SessionCommandController( - noPersistence, - { resolveAgent: vi.fn() } as unknown as ApiSessionAgentController, - '/workspace', - ) - await expectFailure(noPersistenceController.attachment({ - sessionId: SessionId('missing'), attachmentId: AttachmentId('att'), - }), 'session/not-found') - - const missing = new Context() - await missing.plugin(SessionStore) - missing.provide('sessionPersistence', testSessionPersistence(missing, { - list: () => Promise.resolve([]), - inspect: vi.fn(), - }) as never) - installSessionReadTestServices(missing) - const missingController = new SessionCommandController( - missing, - { resolveAgent: vi.fn() } as unknown as ApiSessionAgentController, - '/workspace', - ) - await expectFailure(missingController.attachment({ - sessionId: SessionId('missing'), attachmentId: 'att' as never, - }), 'session/not-found') - - for (const thrown of [ - new AttachmentError('stored image is unavailable', 'ATTACHMENT_NOT_FOUND'), - new Error('backend offline'), - ]) { - const ref = imageRef(`failure-${thrown.name}`) - const fixture = await persistedController( - [event('user/message', SessionSeq(0), { id: 'failure', role: 'user', source: { kind: 'user' }, content: [{ type: 'image', attachment: ref }] })], - () => Promise.reject(thrown), - ) - await expectFailure(fixture.controller.attachment({ - sessionId: fixture.sessionId, - attachmentId: ref.attachmentId, - }), thrown instanceof AttachmentError ? 'session/attachment-invalid' : 'gateway/internal') - await fixture.ctx.fiber.dispose() - } - }) - - it('rejects a cold Session without cwd before reading its referenced image', async () => { - const ref = imageRef('missing-cwd') - const readImage = vi.fn(async () => ({ ref, data: new Uint8Array([1]) })) - const fixture = await persistedController( - [event('user/message', SessionSeq(0), { id: 'image', role: 'user', source: { kind: 'user' }, content: [{ type: 'image', attachment: ref }] })], - readImage, - {}, - ) - try { - await expect(fixture.controller.attachment({ sessionId: fixture.sessionId, attachmentId: ref.attachmentId })) - .rejects.toMatchObject({ code: 'session/not-found', details: { sessionId: fixture.sessionId } }) - expect(readImage).not.toHaveBeenCalled() - } finally { - await fixture.ctx.fiber.dispose() - } - }) - - it('maps a cold observation failure to an internal authorization error', async () => { + it.each([ + 'INVALID_ATTACHMENT_REF', 'ATTACHMENT_NOT_FOUND', 'ATTACHMENT_CORRUPT', 'ATTACHMENT_READ_FAILED', + ] as const)('returns %s as an explicit attachment failure', async (reason) => { const ctx = new Context() - await ctx.plugin(SessionStore) - installSessionReadTestServices(ctx) - vi.spyOn(ctx.sessionQuery, 'observeSession').mockRejectedValue(new Error('storage offline')) - const controller = new SessionCommandController( - ctx, - { resolveAgent: vi.fn() } as unknown as ApiSessionAgentController, - '/workspace', - ) + const readImage = vi.fn(() => Promise.reject(new AttachmentError('Stored image is unavailable.', reason))) + ctx.provide('attachments', { readImage } as never) + const controller = new SessionCommandController(ctx, new ApiSessionAgentController(ctx), '/workspace') + try { + await expect(controller.attachment({ + sessionId: SessionId('unopened'), + attachment: { attachmentId: AttachmentId('requested'), mediaType: 'image/png', bytes: 1, width: 1, height: 1 }, + })) + .rejects.toMatchObject({ code: 'session/attachment-invalid', details: { reason } }) + } finally { + await ctx.fiber.dispose() + } + }) - await expectFailure(controller.attachment({ - sessionId: SessionId('unreadable'), attachmentId: AttachmentId('att'), - }), 'gateway/internal') - await ctx.fiber.dispose() + it('contains unexpected backend failures without exposing internal details', async () => { + const ctx = new Context() + ctx.provide('attachments', { readImage: () => Promise.reject(new Error('/private/storage failed')) } as never) + const controller = new SessionCommandController(ctx, new ApiSessionAgentController(ctx), '/workspace') + try { + await expect(controller.attachment({ + sessionId: SessionId('unopened'), + attachment: { attachmentId: AttachmentId('requested'), mediaType: 'image/png', bytes: 1, width: 1, height: 1 }, + })) + .rejects.toMatchObject({ code: 'gateway/internal', message: 'Unable to read image attachment.', details: {} }) + } finally { + await ctx.fiber.dispose() + } }) }) diff --git a/packages/api/session-controller/tests/controller.host.spec.ts b/packages/api/session-controller/tests/controller.host.spec.ts index a91b9a15c0..664c4f9244 100644 --- a/packages/api/session-controller/tests/controller.host.spec.ts +++ b/packages/api/session-controller/tests/controller.host.spec.ts @@ -3,7 +3,8 @@ import { Context } from '@deepseek-ai/cordis' import AgentRegistry from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { mountAgentLoopTestDependencies, mountAgentLoopTestHarness } from '@deepseek-ai/dsh-agent-loop-testkit' -import { createUserMessage } from '@deepseek-ai/dsh-llm' +import { LlmAttemptId, createUserMessage } from '@deepseek-ai/dsh-llm' +import type TypertGatewayService from '@deepseek-ai/dsh-api-gateway' import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session' import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session' import { RemoteError } from '@deepseek-ai/dsh-typert-protocol' @@ -22,6 +23,75 @@ describe('SessionController facade', () => { expect(SessionController.inject).not.toContain('tools') }) + it('keeps assistant stream observation live while list initialization awaits', async () => { + const ctx = new Context() + onTestFinished(() => ctx.fiber.dispose()) + await mountAgentLoopTestDependencies(ctx) + await mountAgentLoopTestHarness(ctx) + const gateway: Partial = { getPendingRemoteEvents: () => [] } + ctx.provide('typertGateway', gateway as TypertGatewayService) + const session = ctx.sessions.create(SessionId('assistant-interleave'), { meta: { cwd: '/workspace' } }) + const partial: Partial = { id: session.id, session, status: 'running', ctx } + const agent = partial as Agent + const entered = Promise.withResolvers() + const gate = Promise.withResolvers() + const original = ctx.sessionProjections.register.bind(ctx.sessionProjections) + let first = true + vi.spyOn(ctx.sessionProjections, 'register').mockImplementation(async (...args: Parameters) => { + if (first) { + first = false + entered.resolve(undefined) + await gate.promise + } + return original(...args) + }) + const mounting = createSessionTestController(ctx, defaults) + await entered.promise + // An Agent start racing the list read must not be lost before the controller publishes. + ctx.emit('agent/assistant-stream', { + agent, + frame: { type: 'start', attemptId: LlmAttemptId('boot-attempt'), revision: 1, turn: 1, step: 1 }, + }) + gate.resolve(undefined) + const controller = await mounting + const frames = controller.follow({ + address: { kind: 'session', sessionId: session.id }, assistantStream: true, + }, new AbortController().signal)[Symbol.asyncIterator]() + await expect(frames.next()).resolves.toMatchObject({ + value: { type: 'snapshot', assistantStream: { revision: 1 } }, + }) + await frames.return?.(undefined) + }) + + it('serves passive reads, subscriptions and waits through its plain controllers', async () => { + const ctx = new Context() + onTestFinished(() => ctx.fiber.dispose()) + await mountAgentLoopTestDependencies(ctx) + await mountAgentLoopTestHarness(ctx) + const gateway: Partial = { getPendingRemoteEvents: () => [] } + ctx.provide('typertGateway', gateway as TypertGatewayService) + const controller = await createSessionTestController(ctx, defaults) + const sessionId = SessionId('passive-facade') + ctx.sessions.create(sessionId, { meta: { cwd: '/workspace' } }) + const address = { kind: 'session' as const, sessionId } + const signal = new AbortController().signal + + await expect(controller.events({ address }, signal)).resolves.toMatchObject({ records: [], hasMore: false }) + const historyFrames = controller.observeEvent({ address }, signal)[Symbol.asyncIterator]() + await expect(historyFrames.next()).resolves.toMatchObject({ value: { type: 'ready' } }) + await historyFrames.return?.(undefined) + const projectionFrames = controller.observeProjections({ sessionId }, signal)[Symbol.asyncIterator]() + await expect(projectionFrames.next()).resolves.toMatchObject({ value: { type: 'ready' } }) + await projectionFrames.return?.(undefined) + await expect(controller.state({ sessionId }, signal)) + .resolves.toMatchObject({ active: false, running: false, queue: null }) + const stateFrames = controller.observeState({ sessionId }, signal)[Symbol.asyncIterator]() + await expect(stateFrames.next()).resolves.toMatchObject({ value: { active: false } }) + await stateFrames.return?.(undefined) + await expect(controller.wait({ sessionId, afterSeq: -1, maxMessages: 10, timeoutMs: 50 }, signal)) + .resolves.toMatchObject({ reason: 'idle' }) + }) + it('owns Host service methods and publishes Agent lifecycle projections', async () => { const ctx = new Context() onTestFinished(() => ctx.fiber.dispose()) @@ -164,6 +234,7 @@ describe('SessionController facade', () => { const abort = new AbortController() const iterator = controller.follow({ address: { kind: 'session', sessionId }, + activate: true, }, abort.signal)[Symbol.asyncIterator]() await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'snapshot' } }) @@ -216,6 +287,7 @@ describe('SessionController facade', () => { }) const iterator = controller.follow({ address: { kind: 'session', sessionId }, + activate: true, }, new AbortController().signal)[Symbol.asyncIterator]() await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'snapshot' } }) diff --git a/packages/api/session-controller/tests/event-script.client.ts b/packages/api/session-controller/tests/event-script.client.ts index 0e7eaed7d1..0d9eea291b 100644 --- a/packages/api/session-controller/tests/event-script.client.ts +++ b/packages/api/session-controller/tests/event-script.client.ts @@ -8,7 +8,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type { SessionEventEntry, - SessionPage, + SessionEventsPage, SessionWireEvent, } from '../src/types.ts' @@ -185,8 +185,9 @@ export function entries(events: readonly SessionEvent[]): SessionEventEntry[] { } /** Build one view-less history response value. */ -export function historyValue(events: readonly SessionEvent[], hasMore = false): SessionPage { +export function historyValue(events: readonly SessionEvent[], hasMore = false): SessionEventsPage { return { + cursor: events.at(-1)?.seq ?? -1, records: entries(events), hasMore, } diff --git a/packages/api/session-controller/tests/history-controller.host.spec.ts b/packages/api/session-controller/tests/history-controller.host.spec.ts new file mode 100644 index 0000000000..e3592ddbad --- /dev/null +++ b/packages/api/session-controller/tests/history-controller.host.spec.ts @@ -0,0 +1,171 @@ +import { Context } from '@deepseek-ai/cordis' +import { createMessage } from '@deepseek-ai/dsh-llm' +import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { HistoryController } from '../src/history/controller.ts' +import { WebController } from '../src/web/controller.ts' +import { installSessionReadTestServices } from './test-remote.ts' + +const roots: Context[] = [] +const aborters: AbortController[] = [] +afterEach(async () => { + for (const abort of aborters.splice(0)) abort.abort() + await Promise.all(roots.splice(0).map(ctx => ctx.fiber.dispose())) + vi.restoreAllMocks() +}) +async function fixture() { + const ctx = new Context() + roots.push(ctx) + await ctx.plugin(SessionStore) + installSessionReadTestServices(ctx) + const history = new HistoryController(ctx) + const web = new WebController(ctx, history, (observation) => { observation[Symbol.dispose]() }) + const session = ctx.sessions.create(SessionId('history-target'), { meta: { cwd: '/history-test' } }) + const abort = new AbortController() + aborters.push(abort) + const address = { kind: 'session' as const, sessionId: session.id } + return { ctx, history, web, session, abort, address } +} + +describe('HistoryController passive reads', () => { + it('subscribes without reading an Observation and emits later durable events', async () => { + const f = await fixture() + const observe = vi.spyOn(f.ctx.sessionQuery, 'observeSession') + const stream = f.history.observeEvent({ address: f.address }, f.abort.signal)[Symbol.asyncIterator]() + expect(await stream.next()).toEqual({ done: false, value: { type: 'ready' } }) + expect(observe).not.toHaveBeenCalled() + f.session.append('turn/start', { turn: 1 }) + expect(await stream.next()).toMatchObject({ value: { type: 'event', event: { seq: 0 } } }) + f.abort.abort() + expect(await stream.next()).toMatchObject({ done: true }) + }) + + it('subscribes to sparse projection changes without an Observation', async () => { + const f = await fixture() + const observe = vi.spyOn(f.ctx.sessionQuery, 'observeSession') + let receive: Parameters[0] | undefined + const dispose = vi.fn() + vi.spyOn(f.ctx.sessionProjections, 'onChanged').mockImplementation((callback) => { + receive = callback + return dispose + }) + const stream = f.history.observeProjections({ sessionId: f.session.id }, f.abort.signal)[Symbol.asyncIterator]() + expect(await stream.next()).toMatchObject({ value: { type: 'ready' } }) + receive?.(f.session, 'title', 'new title', SessionSeq(0)) + expect(await stream.next()).toMatchObject({ value: { type: 'projection', key: 'title', value: 'new title', seq: 0 } }) + expect(observe).not.toHaveBeenCalled() + f.abort.abort() + expect(await stream.next()).toMatchObject({ done: true }) + expect(dispose).toHaveBeenCalledOnce() + }) + + it('reads newest assistant messages within the exclusive/inclusive interval and detects actual truncation', async () => { + const f = await fixture() + f.session.append('turn/start', { turn: 1 }) + const first = f.session.append('assistant/message', { + turn: 1, step: 1, + message: createMessage({ role: 'assistant', content: [{ type: 'text', text: 'first' }], source: { kind: 'model', provider: 'p', model: 'm' } }), + stream: [], + }, { surfaceOp: 'append' }) + const second = f.session.append('assistant/message', { + turn: 1, step: 2, + message: createMessage({ role: 'assistant', content: [{ type: 'text', text: 'second' }], source: { kind: 'model', provider: 'p', model: 'm' } }), + stream: [], + }, { surfaceOp: 'append' }) + f.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + const observe = vi.spyOn(f.ctx.sessionQuery, 'observeSession') + const all = await f.history.assistantOutput(f.session.id, -1, 3, 2, f.abort.signal) + expect(all.records.map(record => record.event.seq)).toEqual([second.seq, first.seq]) + expect(all.truncated).toBe(false) + const limited = await f.history.assistantOutput(f.session.id, -1, 3, 1, f.abort.signal) + expect(limited.records.map(record => record.event.seq)).toEqual([second.seq]) + expect(limited.truncated).toBe(true) + const interval = await f.history.assistantOutput(f.session.id, first.seq, second.seq, 2, f.abort.signal) + expect(interval.records.map(record => record.event.seq)).toEqual([second.seq]) + expect(observe).toHaveBeenCalledWith(f.session.id, { signal: f.abort.signal, projectionMode: 'none' }) + await expect(f.history.assistantOutput(f.session.id, -1, 9, 2, f.abort.signal)).rejects.toMatchObject({ code: 'gateway/internal' }) + }) + + it('reads at the observed log end when throughSeq is omitted', async () => { + const f = await fixture() + f.session.append('turn/start', { turn: 1 }) + f.session.append('assistant/message', { + turn: 1, step: 1, + message: createMessage({ role: 'assistant', content: [{ type: 'text', text: 'latest' }], source: { kind: 'model', provider: 'p', model: 'm' } }), + stream: [], + }, { surfaceOp: 'append' }) + const page = await f.history.events({ address: f.address }, f.abort.signal) + expect(page.cursor).toBe(f.session.seq - 1) + expect(page.records.at(-1)?.event.seq).toBe(f.session.seq - 1) + }) + + it('keeps the append copy a model-facing replacement shadowed', async () => { + const f = await fixture() + f.session.append('turn/start', { turn: 1 }) + const replaced = f.session.append('assistant/message', { + turn: 1, step: 1, + message: createMessage({ role: 'assistant', content: [{ type: 'text', text: 'visible' }], source: { kind: 'model', provider: 'p', model: 'm' } }), + stream: [], + }, { surfaceOp: 'append' }) + // Compaction rewrites the model-facing surface with a replacement that shadows the original; + // the human-readable transcript keeps the shadowed append copy. + const replacement = f.session.append('user/message', createMessage({ + role: 'user', content: [{ type: 'text', text: 'compacted' }], source: { kind: 'user' }, + }), { surfaceOp: { op: 'replace', startSeq: replaced.seq, endSeq: replaced.seq }, sourceEventSeqs: [replaced.seq] }) + const output = await f.history.assistantOutput(f.session.id, -1, replacement.seq, 5, f.abort.signal) + expect(output.records.map(record => record.event.seq)).toEqual([replaced.seq]) + }) + + it('releases the opening Observation when activation has nothing to promote', async () => { + const f = await fixture() + const source = await f.ctx.sessionQuery.observeSession(f.session.id) + const dispose = vi.fn(() => { source[Symbol.dispose]() }) + vi.spyOn(f.ctx.sessionQuery, 'observeSession').mockResolvedValue({ ...source, [Symbol.dispose]: dispose }) + const stream = f.web.follow({ address: f.address, activate: true }, f.abort.signal)[Symbol.asyncIterator]() + await stream.next() + f.abort.abort() + await stream.next() + expect(dispose).toHaveBeenCalled() + }) + + it('releases an acquired Observation when caller cancellation wins its return', async () => { + const f = await fixture() + const source = await f.ctx.sessionQuery.observeSession(f.session.id) + const dispose = vi.fn(() => { source[Symbol.dispose]() }) + vi.spyOn(f.ctx.sessionQuery, 'observeSession').mockImplementation(async () => { + f.abort.abort() + return { ...source, [Symbol.dispose]: dispose } + }) + await expect(f.history.usingObservation({ sessionId: f.session.id, projection: false }, f.abort.signal)).rejects.toBeDefined() + expect(dispose).toHaveBeenCalledOnce() + }) + + it('maps a non-Error query cancellation to a cancelled Remote error', async () => { + const f = await fixture() + // A cross-realm or opaque source may reject with the code alone; the message falls back. + vi.spyOn(f.ctx.sessionQuery, 'observeSession').mockRejectedValue({ code: 'SESSION_QUERY_ABORTED' }) + await expect(f.history.events({ address: f.address }, f.abort.signal)).rejects.toMatchObject({ + code: 'gateway/cancelled', message: 'Session read was cancelled', + }) + }) + + it('maps missing subagent Follow reads through the Address error', async () => { + const f = await fixture() + const stream = f.web.follow({ address: { + kind: 'subagent', parentSessionId: f.session.id, childSessionId: SessionId('missing-child'), mode: 'continuable', + } }, f.abort.signal)[Symbol.asyncIterator]() + await expect(stream.next()).rejects.toMatchObject({ code: 'subagent/not-found' }) + }) + + it('does not promote a live Session when activation was requested', async () => { + const f = await fixture() + const promote = vi.fn() + const web = new WebController(f.ctx, f.history, promote) + const stream = web.follow({ address: f.address, activate: true }, f.abort.signal)[Symbol.asyncIterator]() + expect(await stream.next()).toMatchObject({ value: { type: 'snapshot' } }) + const pending = stream.next() + f.abort.abort() + expect(await pending).toMatchObject({ done: true }) + expect(promote).not.toHaveBeenCalled() + }) +}) diff --git a/packages/api/session-controller/tests/image-read.perf.config.ts b/packages/api/session-controller/tests/image-read.perf.config.ts new file mode 100644 index 0000000000..4b9de690db --- /dev/null +++ b/packages/api/session-controller/tests/image-read.perf.config.ts @@ -0,0 +1,16 @@ +/** Compile the diagnostic's private controller adapter; workspace services remain built package imports. */ + +import { defineConfig } from 'tsdown' + +export default defineConfig({ + entry: { 'image-read.perf': 'image-read.perf.ts' }, + outDir: '../.dsh-build/image-read', + format: 'esm', + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: true, + tsconfig: '../../../../tsconfig.base.json', + deps: { neverBundle: [/^@deepseek-ai\//], onlyBundle: false }, +}) diff --git a/packages/api/session-controller/tests/image-read.perf.ts b/packages/api/session-controller/tests/image-read.perf.ts new file mode 100644 index 0000000000..18a267131a --- /dev/null +++ b/packages/api/session-controller/tests/image-read.perf.ts @@ -0,0 +1,336 @@ +/** Threshold-free, built-runtime measurements of uncached historical image requests. */ + +import assert from 'node:assert/strict' +import { execFileSync, spawnSync } from 'node:child_process' +import { createHash } from 'node:crypto' +import { once } from 'node:events' +import { mkdtemp, rm } from 'node:fs/promises' +import { createServer } from 'node:http' +import { arch, cpus, platform, release, tmpdir } from 'node:os' +import { join } from 'node:path' +import { performance } from 'node:perf_hooks' +import { fileURLToPath } from 'node:url' +import { crc32, deflateSync } from 'node:zlib' +import { Context } from '@deepseek-ai/cordis' +import { LocalAttachmentStore } from '@deepseek-ai/dsh-attachment-local' +import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' +import { MessageId, ToolCallId } from '@deepseek-ai/dsh-llm' +import { AssistantStreamAccumulator } from '@deepseek-ai/dsh-llm/assistant-stream' +import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session' +import SessionQueryEngine from '@deepseek-ai/dsh-session-query' +import { ApiSessionAgentController } from '../src/agent.ts' +import { SessionCommandController } from '../src/commands.ts' +import type { SessionAttachmentValue } from '../src/types.ts' + +const WORKLOADS = { + typical: { turns: 120, images: 8 }, + tail: { turns: 2_000, images: 32 }, +} as const +const SAMPLES = 5 +const WIDTH = 1024 +const HEIGHT = 768 + +interface Timings { + historyObservations: number + historyQueries: number + historySnapshots: number + observationMs: number + snapshotMs: number + beforeStoreMs: number + storeMs: number + storeFinished: number + started: number +} + +/** Production point reads; full-text search is outside this diagnostic. */ +class ImageReadSessionQuery extends SessionQueryEngine { + override searchSessions(): Promise { + return Promise.reject(new Error('image read diagnostic does not search sessions')) + } + + override searchEvents(): Promise { + return Promise.reject(new Error('image read diagnostic does not search events')) + } +} + +function image(ordinal: number): Uint8Array { + const pixels = Buffer.alloc((WIDTH * 3 + 1) * HEIGHT) + let seed = ordinal + 1 + for (let y = 0; y < HEIGHT; y++) { + for (let x = 0; x < WIDTH; x++) { + seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0 + const offset = y * (WIDTH * 3 + 1) + 1 + x * 3 + const value = x < WIDTH / 4 ? seed >>> 24 : (Math.floor(x / 16) + Math.floor(y / 16) + ordinal) % 256 + pixels[offset] = value + pixels[offset + 1] = (value + ordinal * 17) % 256 + pixels[offset + 2] = (value + y) % 256 + } + } + const chunk = (name: string, data: Buffer): Buffer => { + const output = Buffer.alloc(data.length + 12) + output.writeUInt32BE(data.length) + output.write(name, 4) + data.copy(output, 8) + output.writeUInt32BE(crc32(output.subarray(4, -4)), output.length - 4) + return output + } + const header = Buffer.alloc(13) + header.writeUInt32BE(WIDTH) + header.writeUInt32BE(HEIGHT, 4) + header[8] = 8 + header[9] = 2 + return Buffer.concat([ + Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), + chunk('IHDR', header), chunk('IDAT', deflateSync(pixels)), chunk('IEND', Buffer.alloc(0)), + ]) +} + +function populate(session: Session, turns: number, refs: readonly ImageAttachmentRef[]): void { + for (let turn = 1; turn <= turns; turn++) { + const imageIndex = refs.findIndex((_, ordinal) => Math.floor(ordinal * turns / refs.length) + 1 === turn) + const ref = refs[imageIndex] + session.append('turn/start', { turn }) + session.append('step/start', { turn, step: 1 }) + session.append('user/message', { + id: MessageId(`input-${turn}`), role: 'user', source: { kind: 'user' }, + content: [ + { type: 'text', text: `Inspect synthetic module ${turn}. ` + 'Describe the visible result. '.repeat(8) }, + ...(ref === undefined ? [] : [{ type: 'image' as const, attachment: ref }]), + ], + }, { surfaceOp: 'append' }) + const callId = ToolCallId(`call-${turn}`) + const call = session.append('tool/call', { turn, step: 1, callId, name: 'synthetic_read', arguments: '{}' }) + session.append('tool/result', { + turn, step: 1, + message: { id: MessageId(`result-${turn}`), role: 'tool', toolCallId: callId, isError: false, + source: { kind: 'tool', callId }, content: [{ type: 'text', text: `module ${turn}\n` + 'export const value = 42;\n'.repeat(80) }] }, + }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] }) + const block = { type: 'text' as const, text: `Result ${turn}. ` + 'Synthetic response. '.repeat(40) } + const stream = new AssistantStreamAccumulator() + stream.push({ time: 1_700_000_000_000 + turn, chunk: { type: 'block-start', index: 0, blockType: 'text' } }) + for (let offset = 0; offset < block.text.length; offset += 32) { + stream.push({ time: 1_700_000_000_001 + turn + offset, chunk: { type: 'text-delta', index: 0, text: block.text.slice(offset, offset + 32) } }) + } + stream.push({ time: 1_700_000_001_000 + turn, chunk: { type: 'block-end', index: 0, block } }) + stream.push({ time: 1_700_000_001_001 + turn, chunk: { type: 'finish', reason: { kind: 'stop' } } }) + session.append('assistant/message', { + turn, step: 1, stream: [...stream.snapshot()], + message: { id: MessageId(`reply-${turn}`), role: 'assistant', content: [block], source: { kind: 'model', provider: 'synthetic', model: 'synthetic' } }, + }, { surfaceOp: 'append' }) + session.append('step/end', { turn, step: 1 }) + session.append('turn/end', { turn, reason: { kind: 'completed' } }) + } +} + +function memory(): { heapUsedBytes: number; rssBytes: number; peakRssBytes: number } { + assert.ok(global.gc, 'run the diagnostic with --expose-gc') + global.gc() + const usage = process.memoryUsage() + return { heapUsedBytes: usage.heapUsed, rssBytes: usage.rss, peakRssBytes: process.resourceUsage().maxRSS * 1024 } +} + +async function transfer(payloads: readonly string[]): Promise { + let index = 0 + const server = createServer((_request, response) => { + response.setHeader('content-type', 'application/json') + response.end(payloads[index++]) + }) + try { + server.listen(0, '127.0.0.1') + await once(server, 'listening') + const address = server.address() + assert.ok(address !== null && typeof address !== 'string') + const samples: number[] = [] + for (const payload of payloads) { + const start = performance.now() + const response: Response = await fetch(`http://127.0.0.1:${address.port}`, { signal: AbortSignal.timeout(15_000) }) + const received: string = await response.text() + samples.push(performance.now() - start) + assert.equal(received, payload) + } + return samples + } finally { + server.closeAllConnections() + if (server.listening) await new Promise((resolve, reject) => { + server.close((error) => { if (error === undefined) resolve(); else reject(error) }) + }) + } +} + +async function measure(workload: keyof typeof WORKLOADS) { + const root = await mkdtemp(join(tmpdir(), 'dsh-image-read-perf-')) + const ctx = new Context() + try { + await ctx.plugin(SessionStore) + await ctx.plugin(ImageReadSessionQuery) + await ctx.plugin(LocalAttachmentStore, { dshHome: root }) + const refs: ImageAttachmentRef[] = [] + for (let ordinal = 0; ordinal < WORKLOADS[workload].images; ordinal++) { + refs.push(await ctx.attachments.saveImage({ data: image(ordinal), mediaType: 'image/png' })) + } + const session = ctx.sessions.create(SessionId('synthetic-image-history'), { meta: { cwd: '/synthetic-image-history' } }) + populate(session, WORKLOADS[workload].turns, refs) + let timing: Timings = { + historyObservations: 0, historyQueries: 0, historySnapshots: 0, + observationMs: 0, snapshotMs: 0, beforeStoreMs: 0, + storeMs: 0, storeFinished: 0, started: 0, + } + let traversedEvents = 0 + let countEvents = false + const observeSession = ctx.sessionQuery.observeSession.bind(ctx.sessionQuery) + ctx.sessionQuery.observeSession = async (...args) => { + timing.historyObservations++ + const start = performance.now() + try { + return await observeSession(...args) + } finally { + timing.observationMs += performance.now() - start + } + } + const getSession = ctx.sessions.get.bind(ctx.sessions) + ctx.sessions.get = (id) => { + timing.historyQueries++ + const found = getSession(id) + return found === undefined ? undefined : new Proxy(found, { + get(target, key) { + const member: unknown = Reflect.get(target, key, target) + if (key !== 'snapshotEvents' || typeof member !== 'function') return member + return (...args: unknown[]) => { + timing.historySnapshots++ + const start = performance.now() + const events = Reflect.apply(member as (...args: unknown[]) => readonly unknown[], target, args) + timing.snapshotMs += performance.now() - start + if (!countEvents) return events + return new Proxy(events, { get(array, property) { + if (property !== Symbol.iterator) { + const value: unknown = Reflect.get(array, property, array) + return value + } + return function* () { for (const event of array) { traversedEvents++; yield event } } + } }) + } + }, + }) + } + const attachments = ctx.attachments + const observedAttachments = new Proxy(attachments, { + get(target, key) { + const member: unknown = Reflect.get(target, key, target) + if (key !== 'readImage' || typeof member !== 'function') return member + return async (...args: unknown[]) => { + const start = performance.now() + timing.beforeStoreMs = start - timing.started + const result: unknown = await Reflect.apply(member, target, args) + timing.storeFinished = performance.now() + timing.storeMs = timing.storeFinished - start + return result + } + }, + }) + const observedContext = new Proxy(ctx, { + get(target, key) { + if (key === 'attachments') return observedAttachments + const value: unknown = Reflect.get(target, key, target) + return value + }, + }) + const controller = new SessionCommandController(observedContext, new ApiSessionAgentController(ctx), '/synthetic-image-history') + const baselineMemory = memory() + const outputs: SessionAttachmentValue[] = [] + const samples = [] + for (const ref of refs) { + timing = { + historyObservations: 0, historyQueries: 0, historySnapshots: 0, + observationMs: 0, snapshotMs: 0, beforeStoreMs: 0, + storeMs: 0, storeFinished: 0, started: performance.now(), + } + const cpu = process.cpuUsage() + const value = await controller.attachment({ sessionId: session.id, attachment: ref }) + const completed = performance.now() + const usedCpu = process.cpuUsage(cpu) + assert.deepEqual(value.attachment, ref) + assert.equal(`sha256:${createHash('sha256').update(Buffer.from(value.data, 'base64')).digest('hex')}`, ref.attachmentId) + samples.push({ + controllerMs: completed - timing.started, + controllerCpuMs: (usedCpu.user + usedCpu.system) / 1000, + historyObservations: timing.historyObservations, + historyQueries: timing.historyQueries, historySnapshots: timing.historySnapshots, + observationMs: timing.observationMs, snapshotMs: timing.snapshotMs, + scanAndDispatchMs: timing.beforeStoreMs - timing.observationMs - timing.snapshotMs, + storeMs: timing.storeMs, base64AndReturnMs: completed - timing.storeFinished, + }) + outputs.push(value) + } + const retainedMemory = memory() + const jsonMs: number[] = [] + const payloads = outputs.map((value) => { + const start = performance.now() + const text = JSON.stringify(value) + jsonMs.push(performance.now() - start) + return text + }) + const loopbackTransferMs = await transfer(payloads) + countEvents = true + timing.historyObservations = 0 + timing.historyQueries = 0 + timing.historySnapshots = 0 + for (const ref of refs) await controller.attachment({ sessionId: session.id, attachment: ref }) + const workCounts = { + historyObservations: timing.historyObservations, historyQueries: timing.historyQueries, + historySnapshots: timing.historySnapshots, traversedEvents, + } + if (process.argv.includes('--expect-no-history')) { + assert.deepEqual(workCounts, { historyObservations: 0, historyQueries: 0, historySnapshots: 0, traversedEvents: 0 }) + } + return { + workload, fixture: { ...WORKLOADS[workload], events: session.seq, width: WIDTH, height: HEIGHT, + imageBytes: refs.map(ref => ref.bytes), attachmentIds: refs.map(ref => ref.attachmentId), + fullReferenceRequestJsonBytes: refs.map(attachment => Buffer.byteLength(JSON.stringify({ sessionId: session.id, attachment }))), + idOnlyRequestJsonBytes: refs.map(ref => Buffer.byteLength(JSON.stringify({ + sessionId: session.id, attachmentId: ref.attachmentId, + }))), + responseJsonBytes: payloads.map(text => Buffer.byteLength(text)) }, + samples, jsonMs, loopbackTransferMs, workCounts, baselineMemory, retainedMemory, + } + } finally { + await ctx.fiber.dispose() + await rm(root, { recursive: true, force: true }) + } +} + +for (const specifier of [ + '@deepseek-ai/cordis', '@deepseek-ai/dsh-attachment-local', '@deepseek-ai/dsh-session', '@deepseek-ai/dsh-session-query', +]) { + assert.match(import.meta.resolve(specifier), /\/lib\/.*\.js$/, `${specifier} must resolve to built JavaScript`) +} +assert.ok(import.meta.url.endsWith('.js'), 'compile this diagnostic before running it') +assert.ok(process.execArgv.every(value => !value.includes('tsx')), 'do not use a TypeScript loader') + +const workload = process.argv[3] +if (process.argv[2] === '--sample') { + assert.ok(workload === 'typical' || workload === 'tail') + process.stdout.write(`${JSON.stringify(await measure(workload))}\n`) +} else { + const samples: unknown[] = [] + for (const name of Object.keys(WORKLOADS)) { + for (let sample = 0; sample < SAMPLES; sample++) { + const child = spawnSync(process.execPath, ['--expose-gc', fileURLToPath(import.meta.url), '--sample', name, + ...process.argv.includes('--expect-no-history') ? ['--expect-no-history'] : []], { + encoding: 'utf8', timeout: 60_000, maxBuffer: 16 * 1024 * 1024, + env: { ...process.env, NODE_OPTIONS: '', TSX_TSCONFIG_PATH: '' }, + }) + if (child.error !== undefined) throw child.error + assert.equal(child.signal, null, child.stderr) + assert.equal(child.status, 0, child.stderr) + const report: unknown = JSON.parse(child.stdout) + samples.push(report) + } + } + process.stdout.write(JSON.stringify({ + revision: execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(), + node: process.version, platform: platform(), release: release(), arch: arch(), cpu: cpus()[0]?.model, + clock: 'Fresh child per sample; loaded Session; first uncached request per image; OS file cache may be warm from fixture writes. Store includes file I/O, digest and header validation. observationMs measures the production SessionQuery point observation; snapshotMs measures its lazy event-array acquisition. scanAndDispatchMs is the residual before store entry after subtracting observation and snapshot acquisition. JSON and loopback HTTP transfer are separate measurements over retained responses. Gateway, browser, remote network, upload and model inference are excluded.', + memory: 'GC after setup and after all image responses; Session and all base64 responses remain reachable. Process peak RSS includes fixture creation. No retained-memory budget.', + samples, + }, null, 2) + '\n') +} diff --git a/packages/api/session-controller/tests/listeners.host.spec.ts b/packages/api/session-controller/tests/listeners.host.spec.ts new file mode 100644 index 0000000000..34207efb3c --- /dev/null +++ b/packages/api/session-controller/tests/listeners.host.spec.ts @@ -0,0 +1,263 @@ +import { Context } from '@deepseek-ai/cordis' +import type { Agent, AssistantStreamFrame } from '@deepseek-ai/dsh-agent' +import { LlmAttemptId } from '@deepseek-ai/dsh-llm' +import SessionStore, { SessionId, SessionSeq } from '@deepseek-ai/dsh-session' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { EventListener, ListenerBuffer, ProjectionListener, eventItem } from '../src/history/listener.ts' +import { SessionAssistantStreamsListener } from '../src/history/assistant-stream.ts' +import type { SessionFollowFrame, SessionEventEntry } from '../src/types.ts' +import { installSessionReadTestServices } from './test-remote.ts' + +const roots: Context[] = [] +const aborts: AbortController[] = [] +function cancellation() { + const abort = new AbortController() + aborts.push(abort) + return abort +} +afterEach(async () => { + for (const abort of aborts.splice(0)) abort.abort() + await Promise.all(roots.splice(0).map(ctx => ctx.fiber.dispose())) + vi.restoreAllMocks() +}) +async function fixture() { + const ctx = new Context() + roots.push(ctx) + await ctx.plugin(SessionStore) + installSessionReadTestServices(ctx) + const session = ctx.sessions.create(SessionId('listener-target'), { meta: { cwd: '/listeners' } }) + const abort = cancellation() + const partial: Partial = { id: session.id, session } + const agent = partial as Agent + const emit = (frame: AssistantStreamFrame) => { ctx.emit('agent/assistant-stream', { agent, frame }) } + return { ctx, session, abort, emit, agent } +} +const start = (revision = 1): AssistantStreamFrame => ({ type: 'start', attemptId: LlmAttemptId('attempt'), revision, turn: 1, step: 1 }) + +describe('ListenerBuffer', () => { + it('orders heterogeneous inputs lazily, supports prepend, and admits only one consumer', async () => { + const { ctx, abort } = await fixture() + using buffer = new ListenerBuffer(ctx, abort.signal) + const convert = vi.fn((value: number) => [`n:${value}`]) + const numbers = buffer.createInput(convert) + const words = buffer.createInput(value => [value]) + numbers.append(2) + words.prepend('first') + expect(convert).not.toHaveBeenCalled() + const values = buffer.items()[Symbol.asyncIterator]() + expect(await values.next()).toEqual({ done: false, value: 'first' }) + expect(await values.next()).toEqual({ done: false, value: 'n:2' }) + await expect(buffer.items()[Symbol.asyncIterator]().next()).rejects.toMatchObject({ code: 'gateway/internal' }) + const waiting = values.next() + numbers.append(3) + expect(await waiting).toMatchObject({ value: 'n:3' }) + await values.return?.() + const action = vi.fn() + buffer.capture(action) + numbers.append(4) + words.prepend('closed') + expect(action).not.toHaveBeenCalled() + buffer.own(action) + expect(action).toHaveBeenCalledOnce() + expect(() => buffer.createInput(value => [value])).toThrow('closed') + }) + + it('propagates captured failure both before and during transformation', async () => { + const { ctx, abort } = await fixture() + using first = new ListenerBuffer(ctx, abort.signal) + first.capture(() => { throw new Error('captured') }) + await expect(first.items()[Symbol.asyncIterator]().next()).rejects.toThrow('captured') + using second = new ListenerBuffer(ctx, abort.signal) + const input = second.createInput(function* (value) { + second.capture(() => { throw new Error('transform failure') }) + yield value + }) + input.append(1) + await expect(second.items()[Symbol.asyncIterator]().next()).rejects.toThrow('transform failure') + }) + + it('does not emit after transformation closes its own buffer', async () => { + const { ctx, abort } = await fixture() + using buffer = new ListenerBuffer(ctx, abort.signal) + buffer.createInput(function* (value) { buffer[Symbol.dispose](); yield value }).append(1) + expect(await buffer.items()[Symbol.asyncIterator]().next()).toEqual({ done: true, value: undefined }) + }) + + it('releases abort registration when effect installation fails', async () => { + const { ctx, abort } = await fixture() + const remove = vi.spyOn(abort.signal, 'removeEventListener') + vi.spyOn(ctx, 'effect').mockImplementation(() => { throw new Error('effect failure') }) + expect(() => new ListenerBuffer(ctx, abort.signal)).toThrow('effect failure') + expect(remove).toHaveBeenCalledWith('abort', expect.any(Function)) + }) +}) + +describe('EventListener', () => { + it('starts at the first notification without acquiring a snapshot', async () => { + const { ctx, session, abort } = await fixture() + using listener = new EventListener(ctx, session.id, abort.signal) + const event = session.append('turn/start', { turn: 1 }) + const values = listener.events()[Symbol.asyncIterator]() + expect(await values.next()).toMatchObject({ value: { type: 'event', event } }) + abort.abort() + expect(await values.next()).toMatchObject({ done: true }) + }) + + it('subscribes before an empty Session is created and follows its first later event', async () => { + const { ctx, abort } = await fixture() + const id = SessionId('created-after-bind') + using listener = new EventListener(ctx, id, abort.signal) + const session = ctx.sessions.create(id) + const values = listener.events()[Symbol.asyncIterator]() + const waiting = values.next() + const event = session.append('turn/start', { turn: 1 }) + expect(await waiting).toMatchObject({ value: { event } }) + await values.return?.() + }) + + it('filters buffered events through a supplied cursor', async () => { + const { ctx, session, abort } = await fixture() + using listener = new EventListener(ctx, session.id, abort.signal) + session.append('turn/start', { turn: 1 }) + const event = session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + listener.setCursor(0) + const values = listener.events()[Symbol.asyncIterator]() + expect(await values.next()).toMatchObject({ value: { event } }) + await values.return?.() + }) + + it('leaves an external buffer open and drops notifications after listener disposal', async () => { + const { ctx, session, abort } = await fixture() + using queue = new ListenerBuffer(ctx, abort.signal) + const listener = new EventListener(ctx, session.id, abort.signal, queue) + session.append('turn/start', { turn: 1 }) + await expect(listener.events()[Symbol.asyncIterator]().next()).rejects.toThrow('externally owned') + listener[Symbol.dispose]() + const values = queue.items()[Symbol.asyncIterator]() + const next = values.next() + abort.abort() + expect(await next).toMatchObject({ done: true }) + }) + + it('stops within a creation batch when its binding is disposed', async () => { + const { ctx, session, abort } = await fixture() + session.append('turn/start', { turn: 1 }) + session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + using queue = new ListenerBuffer(ctx, abort.signal) + const listener = new EventListener(ctx, session.id, abort.signal, queue) + listener.setCursor(-1) + ctx.emit('session/created', session) + const values = queue.items()[Symbol.asyncIterator]() + expect(await values.next()).toMatchObject({ value: { event: { seq: 0 } } }) + listener[Symbol.dispose]() + const waiting = values.next() + abort.abort() + expect(await waiting).toMatchObject({ done: true }) + }) + + it('cleans a partially installed registration when a later one fails', async () => { + const { ctx, session, abort } = await fixture() + const on = ctx.on.bind(ctx) + let count = 0 + vi.spyOn(ctx, 'on').mockImplementation((...args) => { + if (++count === 2) throw new Error('registration failure') + return on(...args) + }) + expect(() => new EventListener(ctx, session.id, abort.signal)).toThrow('registration failure') + }) + + it('handles raw events and rejects a noncontiguous supplied creation prefix', async () => { + const { session } = await fixture() + const event = session.append('turn/start', { turn: 1 }) + expect(eventItem({ type: 'event', session, event })).toEqual({ events: [event], next: 1 }) + expect(eventItem({ type: 'created', session, end: 0 })).toEqual({ events: [], next: undefined }) + vi.spyOn(session, 'snapshotEvents').mockReturnValue([{ ...event, seq: SessionSeq(1) }]) + expect(() => eventItem({ type: 'created', session, end: 2 }, 0)).toThrow('skipped seq') + expect(eventItem({ type: 'created', session, end: 2 })).toMatchObject({ next: 2 }) + }) +}) + +describe('ProjectionListener', () => { + it('emits sparse changes only for the selected Session', async () => { + const { ctx, session, abort } = await fixture() + let receive!: Parameters[0] + const dispose = vi.fn() + vi.spyOn(ctx.sessionProjections, 'onChanged').mockImplementation((listener) => { receive = listener; return dispose }) + using listener = new ProjectionListener(ctx, session.id, abort.signal) + const other = ctx.sessions.create(SessionId('other')) + receive(other, 'subagent', null, SessionSeq(0)) + receive(session, 'subagent', null, SessionSeq(1)) + const changes = listener.changes()[Symbol.asyncIterator]() + expect(await changes.next()).toMatchObject({ value: { type: 'projection', key: 'subagent', value: null, seq: 1 } }) + abort.abort() + expect(await changes.next()).toMatchObject({ done: true }) + expect(dispose).toHaveBeenCalledOnce() + }) + + it('releases its buffer when projection subscription fails', async () => { + const { ctx, session, abort } = await fixture() + const remove = vi.spyOn(abort.signal, 'removeEventListener') + vi.spyOn(ctx.sessionProjections, 'onChanged').mockImplementation(() => { throw new Error('projection subscribe failed') }) + expect(() => new ProjectionListener(ctx, session.id, abort.signal)).toThrow('projection subscribe failed') + expect(remove).toHaveBeenCalled() + }) +}) + +describe('AssistantStreamListener', () => { + it('cuts baseline-covered arrivals and clears reconnect state on Agent disposal', async () => { + const { ctx, session, abort, emit, agent } = await fixture() + const streams = new SessionAssistantStreamsListener(ctx) + using queue = new ListenerBuffer(ctx, abort.signal) + using listener = streams.bind(session.id, abort.signal, queue) + expect(listener.snapshot()).toEqual({ baseline: { revision: 0 }, ordinal: 0 }) + emit(start()) + expect(listener.snapshot()).toMatchObject({ baseline: { revision: 1 }, ordinal: 1 }) + listener.setOrdinalCut(1) + const frames = queue.items()[Symbol.asyncIterator]() + const end: AssistantStreamFrame = { type: 'end', attemptId: LlmAttemptId('attempt'), revision: 2, index: 0, outcome: { kind: 'abandoned' } } + emit(end) + expect(await frames.next()).toMatchObject({ value: { type: 'assistant-stream', frame: end } }) + ctx.emit('agent/disposed', { agent }) + expect(listener.snapshot()).toEqual({ baseline: { revision: 0 }, ordinal: 2 }) + abort.abort() + expect(await frames.next()).toMatchObject({ done: true }) + }) + + it('records the durable cursor for an attempt started after a committed event', async () => { + const { ctx, session, abort, emit } = await fixture() + session.append('turn/start', { turn: 1 }) + const streams = new SessionAssistantStreamsListener(ctx) + using queue = new ListenerBuffer(ctx, abort.signal) + using listener = streams.bind(session.id, abort.signal, queue) + emit(start()) + listener.setOrdinalCut(0) + const frames = queue.items()[Symbol.asyncIterator]() + expect(await frames.next()).toMatchObject({ value: { frame: { type: 'start', startedAfterSeq: 0 } } }) + await frames.return?.() + }) + + it('leaves queue ownership intact and drops notifications after unbinding', async () => { + const { ctx, session, abort, emit } = await fixture() + const streams = new SessionAssistantStreamsListener(ctx) + using queue = new ListenerBuffer(ctx, abort.signal) + const listener = streams.bind(session.id, abort.signal, queue) + emit(start()) + listener[Symbol.dispose]() + const next = queue.items()[Symbol.asyncIterator]().next() + abort.abort() + expect(await next).toMatchObject({ done: true }) + }) + + it('propagates registration failure without closing the shared queue', async () => { + const { ctx, session, abort } = await fixture() + const streams = new SessionAssistantStreamsListener(ctx) + using queue = new ListenerBuffer(ctx, abort.signal) + vi.spyOn(ctx, 'on').mockImplementation(() => { throw new Error('assistant subscribe failed') }) + expect(() => streams.bind(session.id, abort.signal, queue)).toThrow('assistant subscribe failed') + // The failed binding leaves the shared queue usable for the rest of the connection. + const input = queue.createInput(value => [value]) + const event = session.append('turn/start', { turn: 1 }) + input.append({ type: 'event', event }) + await expect(queue.items()[Symbol.asyncIterator]().next()).resolves.toMatchObject({ value: { type: 'event', event } }) + }) +}) diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts index 282e1bc27c..88bed83626 100644 --- a/packages/api/session-controller/tests/manager.client.spec.ts +++ b/packages/api/session-controller/tests/manager.client.spec.ts @@ -860,7 +860,7 @@ describe('subagent catalogs', () => { childSessionId: S2, mode: 'continuable', }, - assistantStream: true, + activate: true, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 }, }, @@ -955,7 +955,7 @@ describe('subagent catalogs', () => { if (source === 'control') { manager.handleControlFrame({ type: 'baseline', value: { projections: { [S1]: baseline } } }) } else { - mock.stream(FOLLOW, followScript(ok({ records: [], hasMore: false, projections: baseline }))) + mock.stream(FOLLOW, followScript(ok({ cursor: baseline.asOfSeq, records: [], hasMore: false, projections: baseline }))) await session.open() } @@ -980,7 +980,7 @@ describe('subagent catalogs', () => { if (source === 'control') { manager.handleControlFrame({ type: 'baseline', value: { projections: { [S1]: baseline } } }) } else { - mock.stream(FOLLOW, followScript(ok({ records: [], hasMore: false, projections: baseline }))) + mock.stream(FOLLOW, followScript(ok({ cursor: baseline.asOfSeq, records: [], hasMore: false, projections: baseline }))) await manager.get(S1).open() } response.resolve(ok({ kind: 'migration-required', values: { @@ -1495,6 +1495,7 @@ describe('connected generation', () => { it('refreshes query baselines without rebuilding independently resumed Session sources', async ({ mock, remote, start }) => { mock.stream(FOLLOW, followScript(ok({ + cursor: 5, records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[], hasMore: false, modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' }, diff --git a/packages/api/session-controller/tests/projection-discovery.host.spec.ts b/packages/api/session-controller/tests/projection-discovery.host.spec.ts index 150b82d415..539962a622 100644 --- a/packages/api/session-controller/tests/projection-discovery.host.spec.ts +++ b/packages/api/session-controller/tests/projection-discovery.host.spec.ts @@ -239,7 +239,7 @@ describe('Session projection discovery', () => { kind: 'sequenced', asOfSeq: 0, values: { subagentCatalog: [{ id: 'current-child', mode: 'continuable', label: 'worker' }] }, }) - expect(observe).toHaveBeenCalledWith(parent.header.id, { signal }) + expect(observe).toHaveBeenCalledWith(parent.header.id, { signal, projectionMode: 'all' }) expect(open).toHaveBeenCalledWith(parent.header.id, 'read', { signal }) expect(fixture.ctx.sessions.get(parent.header.id)).toBeUndefined() expect(fixture.ctx.agents.get(parent.header.id)).toBeUndefined() @@ -310,7 +310,7 @@ describe('Session projection discovery', () => { .rejects.toMatchObject({ code: 'session/projections-unavailable' }) }) - it.each([false, true])('rechecks live history when the stored source disappears after preflight (attached: %s)', async (attached) => { + it.each([false, true])('returns the observation not-found result without a second live lookup (attached: %s)', async (attached) => { const fixture = await harness() const parent = await stored(fixture, SessionId('missing-after-preflight')) const snapshot = await fixture.ctx.sessionPersistence.stat(parent.header.id) @@ -322,9 +322,8 @@ describe('Session projection discovery', () => { }) const result = await fixture.controller.projections({ sessionId: parent.header.id }, new AbortController().signal) - expect(result).toEqual(attached - ? { kind: 'sequenced', ...fixture.ctx.sessionProjections.snapshot(fixture.ctx.sessions.get(parent.header.id)!) } - : null) + expect(result).toBeNull() + expect(fixture.ctx.sessions.get(parent.header.id) !== undefined).toBe(attached) }) it('serves the live registry cut instead of a conflicting cached hint', async () => { @@ -342,7 +341,7 @@ describe('Session projection discovery', () => { expect(cached).not.toHaveBeenCalled() }) - it.each([true, false])('prefers a Session attached during stat (stored header present: %s)', async (present) => { + it.each([true, false])('uses migration preflight before observing a Session attached during stat (stored header present: %s)', async (present) => { const fixture = await harness() const parent = await stored(fixture, SessionId('stat-race'), {}, 3) const snapshot = await fixture.ctx.sessionPersistence.stat(parent.header.id) @@ -358,7 +357,9 @@ describe('Session projection discovery', () => { const live = fixture.ctx.sessions.create(parent.header.id, { meta: parent.header }) live.append('turn/start', { turn: 1 }) finish.resolve(present ? snapshot : undefined) - await expect(operation).resolves.toEqual({ kind: 'sequenced', ...fixture.ctx.sessionProjections.snapshot(live) }) + await expect(operation).resolves.toEqual(present + ? { kind: 'migration-required', values: {} } + : { kind: 'sequenced', ...fixture.ctx.sessionProjections.snapshot(live) }) } finally { finish.resolve(undefined) await Promise.allSettled([operation]) diff --git a/packages/api/session-controller/tests/projection-store.client.spec.ts b/packages/api/session-controller/tests/projection-store.client.spec.ts index 40e1f3c95f..ab1e185744 100644 --- a/packages/api/session-controller/tests/projection-store.client.spec.ts +++ b/packages/api/session-controller/tests/projection-store.client.spec.ts @@ -214,7 +214,7 @@ describe('Session tail-page seeding', () => { it('treats a blockless response as no reset: pushed values survive', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - mock.stream(FOLLOW, followScript(ok({ records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[], hasMore: false }))) + mock.stream(FOLLOW, followScript(ok({ cursor: 5, records: entries(plainTurn(SessionSeq(0), 0, 'a', 'b')) as never[], hasMore: false }))) await session.open() session.projections.apply('test/marks', { marks: ['pushed'] }, SessionSeq(9)) await session.resync() diff --git a/packages/api/session-controller/tests/reference-ownership.client.spec.ts b/packages/api/session-controller/tests/reference-ownership.client.spec.ts index 16de92ef02..b0563eb879 100644 --- a/packages/api/session-controller/tests/reference-ownership.client.spec.ts +++ b/packages/api/session-controller/tests/reference-ownership.client.spec.ts @@ -21,7 +21,7 @@ declare module '@deepseek-ai/dsh-api-session-controller/client' { const viewSource: SessionReferenceSource = 'referenceTestView' const workSource: SessionReferenceSource = 'referenceTestWork' const ID = SessionId('reference-session') -const EMPTY_HISTORY = ok({ records: [], hasMore: false }) +const EMPTY_HISTORY = ok({ cursor: -1, records: [], hasMore: false }) const it = createClientTest({ roster: webApp.closure(['@deepseek-ai/dsh-api-gateway']) }) async function bench(mock: RemoteMock, start: () => Promise, listed = true) { diff --git a/packages/api/session-controller/tests/remote-access.host.spec.ts b/packages/api/session-controller/tests/remote-access.host.spec.ts index e15b7b3fb1..8be0dac78e 100644 --- a/packages/api/session-controller/tests/remote-access.host.spec.ts +++ b/packages/api/session-controller/tests/remote-access.host.spec.ts @@ -8,6 +8,7 @@ */ import { Context } from '@deepseek-ai/cordis' +import { AttachmentId } from '@deepseek-ai/dsh-attachment' import type { Agent } from '@deepseek-ai/dsh-agent' import { mountAgentLoopTestDependencies, mountAgentLoopTestHarness } from '@deepseek-ai/dsh-agent-loop-testkit' import TypertGatewayService from '@deepseek-ai/dsh-api-gateway' @@ -268,6 +269,34 @@ describe('Session Controller access', () => { ]) }) + it('keeps gateway permission checks while allowing an image referenced only by another Session', async () => { + const { ctx, hidden } = await harness() + await ctx.plugin(TypertGatewayService) + const bindings = guestPolicy(ctx) + const ref = { + attachmentId: AttachmentId(`sha256:${'ab'.repeat(32)}`), + mediaType: 'image/png' as const, bytes: 2, width: 1, height: 1, + } + hidden.session.append('user/message', createUserMessage({ + content: [{ type: 'image', attachment: ref }], source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + const readImage = vi.fn(() => Promise.resolve({ ref, data: Uint8Array.of(1, 2) })) + ctx.attachments.readImage = readImage + const read = (sessionId: SessionId): Promise => guestCall(ctx, 'attachment', { + request: { sessionId, attachment: ref }, + }) + await expect(read(SHARED)).rejects.toMatchObject({ code: 'remote-access/denied' }) + expect(readImage).not.toHaveBeenCalled() + bindings.push({ + role: { name: 'test:attachment-reader', resource: 'session', actions: ['session/attachment'] }, + resource: { kind: 'session', id: SHARED }, + }) + await expect(read(SHARED)).resolves.toEqual({ attachment: ref, data: 'AQI=' }) + expect(readImage).toHaveBeenCalledExactlyOnceWith(ref) + await expect(read(PRIVATE)).rejects.toMatchObject({ code: 'remote-access/denied' }) + expect(readImage).toHaveBeenCalledTimes(1) + }) + it('lets a non-owner read projections only in a Session its Session role names', async () => { const { ctx } = await harness() await ctx.plugin(TypertGatewayService) diff --git a/packages/api/session-controller/tests/remote/history.client.ts b/packages/api/session-controller/tests/remote/history.client.ts index e954f89a2b..080571b09d 100644 --- a/packages/api/session-controller/tests/remote/history.client.ts +++ b/packages/api/session-controller/tests/remote/history.client.ts @@ -1,7 +1,7 @@ /** Pure history response builders for assembled Session tests. */ import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session/types' import type { - SessionAssistantStreamBaseline, SessionFollowFrame, SessionFollowRequest, SessionPage, SessionProjectionBaseline, + SessionAssistantStreamBaseline, SessionFollowFrame, SessionFollowRequest, SessionPage, SessionEventsPage, SessionProjectionBaseline, } from '../../src/types.ts' import { historyRecordLastSeq } from '../../src/client/sessions/history-records.ts' @@ -11,8 +11,8 @@ import { historyRecordLastSeq } from '../../src/client/sessions/history-records. * @param throughSeq - inclusive final sequence. * @returns the page without records beyond the cursor. */ -export function pageThrough(page: SessionPage, throughSeq: number): SessionPage { - return { ...page, records: page.records.filter(record => historyRecordLastSeq(record) <= throughSeq) } +export function pageThrough(page: SessionPage, throughSeq: number): SessionEventsPage { + return { ...page, cursor: throughSeq, records: page.records.filter(record => historyRecordLastSeq(record) <= throughSeq) } } /** diff --git a/packages/api/session-controller/tests/remote/session.client.ts b/packages/api/session-controller/tests/remote/session.client.ts index 8b65358dc4..c4d8049177 100644 --- a/packages/api/session-controller/tests/remote/session.client.ts +++ b/packages/api/session-controller/tests/remote/session.client.ts @@ -12,7 +12,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol' import type { SessionAssistantStreamBaseline, SessionFollowFrame, SessionFollowRequest, - SessionPage, SessionPageRequest, + SessionEventsPage, SessionPageRequest, } from '../../src/types.ts' import { entries, historyValue } from '../event-script.client.ts' import { followSnapshot, pageThrough } from './history.client.ts' @@ -24,7 +24,7 @@ export const FOLLOW = 'session/follow' export const PAGE = 'session/page' /** A history answer as the Host returns it, possibly still pending. */ -export type HistoryAnswer = RemoteResult | Promise> +export type HistoryAnswer = RemoteResult | Promise> /** A history answer, or a function of the request that produces one. */ export type HistorySource = HistoryAnswer | ((request: Request) => HistoryAnswer) @@ -43,7 +43,7 @@ export function err(error: RemoteFailure): RemoteResult { * @param hasMore - whether older history exists. * @returns the success result. */ -export function history(events: readonly SessionEvent[], hasMore = false): RemoteResult { +export function history(events: readonly SessionEvent[], hasMore = false): RemoteResult { return ok(historyValue(events, hasMore)) } @@ -102,11 +102,11 @@ export function followScript( */ export function pageRule( history: HistorySource, -): UnaryRuleFn>> { +): UnaryRuleFn>> { return async (page) => { const result = await answer(history, page) if (!result.ok) return result - return ok(pageThrough(result.value, page.throughSeq)) + return ok(pageThrough(result.value, page.throughSeq ?? result.value.cursor)) } } @@ -144,12 +144,12 @@ export const sessionWorld: RemoteTable = { attachment: { attachmentId: 'a', mediaType: 'image/png', bytes: 1, width: 1, height: 1 }, data: 'AA==', }), - 'session/page': pageRule(ok({ records: [], hasMore: false })), + 'session/page': pageRule(ok({ cursor: -1, records: [], hasMore: false })), 'session/projections': ok({ kind: 'sequenced', asOfSeq: -1, values: { subagentCatalog: [] } }), 'subagents/prompt': ok({ messageId: 'fake-message' }), 'subagents/interruptByUser': ok({ accepted: true }), }, stream: { - 'session/follow': followScript(ok({ records: [], hasMore: false })), + 'session/follow': followScript(ok({ cursor: -1, records: [], hasMore: false })), }, } diff --git a/packages/api/session-controller/tests/session-cold.host.spec.ts b/packages/api/session-controller/tests/session-cold.host.spec.ts index bf54e13543..e5f721d37d 100644 --- a/packages/api/session-controller/tests/session-cold.host.spec.ts +++ b/packages/api/session-controller/tests/session-cold.host.spec.ts @@ -11,7 +11,6 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import SessionStore from '@deepseek-ai/dsh-session' import AgentRegistry from '@deepseek-ai/dsh-agent' -import { SessionHistoryController } from '@deepseek-ai/dsh-api-session-controller/src/history.ts' import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts' import TypertRegistry from '@deepseek-ai/dsh-typert-registry' import { createUserMessage, MessageId } from '@deepseek-ai/dsh-llm' @@ -574,10 +573,7 @@ describe('subagent ownership fence', () => { const remote = await createSessionTestRemote(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp' }) await ctx.sessionProjections.register(subagentIdentityProjectionDefinition) - const history = await new SessionHistoryController( - ctx, - (observation) => { observation[Symbol.dispose]() }, - ).page({ + const history = await ctx.sessionController.events({ address: { kind: 'subagent', parentSessionId: meta.parentSession as SessionId, diff --git a/packages/api/session-controller/tests/session-history-journal.host.spec.ts b/packages/api/session-controller/tests/session-history-journal.host.spec.ts index f1954ed935..328e797677 100644 --- a/packages/api/session-controller/tests/session-history-journal.host.spec.ts +++ b/packages/api/session-controller/tests/session-history-journal.host.spec.ts @@ -8,7 +8,8 @@ import SessionStore from '@deepseek-ai/dsh-session' import { LlmAttemptId, ToolCallId, createMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm' import type { MessageSource } from '@deepseek-ai/dsh-llm' import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session' -import { SessionHistoryController } from '@deepseek-ai/dsh-api-session-controller/src/history.ts' +import { HistoryController } from '../src/history/controller.ts' +import { WebController } from '../src/web/controller.ts' import type { SessionFollowFrame, SessionPage, SessionWireEvent } from '@deepseek-ai/dsh-api-session-controller/types' import { createSessionTestRemote, installSessionReadTestServices } from './test-remote.ts' @@ -57,6 +58,12 @@ async function harness(): Promise<{ ctx: Context }> { return { ctx } } +/** Initialize the independent snapshot owner and Web aggregation for direct journal tests. */ +async function controllers(ctx: Context): Promise<{ history: HistoryController; web: WebController }> { + const history = new HistoryController(ctx) + return { history, web: new WebController(ctx, history, (observation) => { observation[Symbol.dispose]() }) } +} + /** Drain one Session follow until `count` event frames arrive. */ async function collect( iterable: AsyncIterable, @@ -73,11 +80,11 @@ async function collect( /** Open follow and wait until its cursor is fixed before appending fixtures. */ async function openFollow( - history: SessionHistoryController, + web: WebController, sessionId: SessionId, signal: AbortSignal, ): Promise> { - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId }, }, signal)[Symbol.asyncIterator]() await expect(iterator.next()).resolves.toMatchObject({ @@ -107,9 +114,9 @@ describe('Session history raw journal', () => { it('opens an empty opted-in Assistant baseline before any live attempt exists', async () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -127,7 +134,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const originalObserve = ctx.sessionQuery.observeSession.bind(ctx.sessionQuery) const entered = Promise.withResolvers() const release = Promise.withResolvers() @@ -137,7 +144,7 @@ describe('Session history raw journal', () => { return originalObserve(...args) }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -182,7 +189,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const attemptId = LlmAttemptId('live-follow-attempt') const emit = (frame: AssistantStreamFrame): void => { ctx.emit('agent/assistant-stream', { agent, frame }) @@ -197,7 +204,7 @@ describe('Session history raw journal', () => { time: 1, chunk: firstChunk, }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -249,7 +256,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const attemptId = LlmAttemptId(`${session.id}:1`) ctx.emit('agent/assistant-stream', { agent, @@ -267,7 +274,7 @@ describe('Session history raw journal', () => { }, }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -311,7 +318,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const attemptId = LlmAttemptId('revision-gap-attempt') ctx.emit('agent/assistant-stream', { agent, @@ -329,7 +336,7 @@ describe('Session history raw journal', () => { }, }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -351,7 +358,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const attemptId = LlmAttemptId('dense-index-attempt') ctx.emit('agent/assistant-stream', { agent, @@ -369,7 +376,7 @@ describe('Session history raw journal', () => { }, }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -391,7 +398,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const attemptId = LlmAttemptId('cached-baseline-attempt') ctx.emit('agent/assistant-stream', { agent, @@ -402,12 +409,12 @@ describe('Session history raw journal', () => { }) const firstAbort = new AbortController() - const firstIterator = history.follow({ + const firstIterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, firstAbort.signal)[Symbol.asyncIterator]() const secondAbort = new AbortController() - const secondIterator = history.follow({ + const secondIterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, secondAbort.signal)[Symbol.asyncIterator]() @@ -431,9 +438,9 @@ describe('Session history raw journal', () => { it('opens an empty Assistant baseline before the target Agent emits frames', async () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -456,9 +463,9 @@ describe('Session history raw journal', () => { const target = ctx.sessions.create(undefined, { meta: { cwd: '/target' } }) const other = ctx.sessions.create(undefined, { meta: { cwd: '/other' } }) const otherAgent = { id: other.id, session: other, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: target.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -489,7 +496,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const observationStarted = Promise.withResolvers() const releaseObservation = Promise.withResolvers() const originalObserve = ctx.sessionQuery.observeSession.bind(ctx.sessionQuery) @@ -499,7 +506,7 @@ describe('Session history raw journal', () => { return await originalObserve(sessionId, options) }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -539,7 +546,7 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const attemptId = LlmAttemptId(`${session.id}:1`) ctx.emit('agent/assistant-stream', { agent, @@ -557,7 +564,7 @@ describe('Session history raw journal', () => { return await originalObserve(sessionId, options) }) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, assistantStream: true, }, abort.signal)[Symbol.asyncIterator]() @@ -613,9 +620,9 @@ describe('Session history raw journal', () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) const agent = { id: session.id, session, status: 'running', ctx } as Agent - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const iterator = history.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, }, abort.signal)[Symbol.asyncIterator]() const opening = await iterator.next() @@ -655,9 +662,9 @@ describe('Session history raw journal', () => { it('follows raw tool events and preserves result metadata without a Tools service', async () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const stream = await openFollow(history, session.id, abort.signal) + const stream = await openFollow(web, session.id, abort.signal) const collected = collect(stream, 2, abort) const call = session.append('tool/call', { turn: 1, step: 1, callId: ToolCallId('raw-call'), name: 'custom', arguments: '{malformed', @@ -684,9 +691,9 @@ describe('Session history raw journal', () => { it('follows live results without rescanning Session history', async () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const stream = await openFollow(history, session.id, abort.signal) + const stream = await openFollow(web, session.id, abort.signal) const iterator = stream[Symbol.asyncIterator]() session.append('tool/call', { @@ -957,9 +964,9 @@ describe('Session history raw journal', () => { it('follows a result after turn/end without reading the addressed Session log', async () => { const { ctx } = await harness() const session = ctx.sessions.create(undefined, { meta: { cwd: '/workspace' } }) - const history = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) + const { web } = await controllers(ctx) const abort = new AbortController() - const stream = await openFollow(history, session.id, abort.signal) + const stream = await openFollow(web, session.id, abort.signal) const iterator = stream[Symbol.asyncIterator]() session.append('turn/start', { turn: 1 }) diff --git a/packages/api/session-controller/tests/session-models.host.spec.ts b/packages/api/session-controller/tests/session-models.host.spec.ts index cda4c14e6a..f8fc4920c5 100644 --- a/packages/api/session-controller/tests/session-models.host.spec.ts +++ b/packages/api/session-controller/tests/session-models.host.spec.ts @@ -329,40 +329,6 @@ describe('Web session model selection', () => { await ctx.fiber.dispose() }) - it('authorizes attachment bytes only when the session event stream references the id', async () => { - const { ctx, agent, sessionId } = await harness() - const ref = { - attachmentId: 'att-authorized', mediaType: 'image/png' as const, bytes: 2, width: 1, height: 1, - } - const readImage = vi.fn(() => Promise.resolve({ ref, data: Uint8Array.of(1, 2) })) - ctx.provide('attachments', { readImage } as never) - const remote = await createSessionTestRemote(ctx, { - defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), - cwd: '/tmp', - }) - agent.session.append('agent/inbox/spliced', { - target: 'next-turn', - start: 0, - inserted: [{ - id: 'queued-image', role: 'user', source: { kind: 'user' }, - content: [{ type: 'image', attachment: ref }], - }], - } as never) - - const allowed = await remote.attachment(request({ - sessionId, attachmentId: 'att-authorized' as never, - })) - expect(allowed).toMatchObject({ ok: true, value: { attachment: ref, data: 'AQI=' } }) - const denied = await remote.attachment(request({ - sessionId, attachmentId: 'att-other' as never, - })) - expect(denied).toMatchObject({ - ok: false, - error: { code: 'session/attachment-invalid', details: { reason: 'ATTACHMENT_NOT_REFERENCED' } }, - }) - expect(readImage).toHaveBeenCalledOnce() - await ctx.fiber.dispose() - }) it('checks configured key references even for empty catalogs and skips profiles without keys', async () => { const ctx = new Context() await ctx.plugin(LlmRuntime) @@ -466,6 +432,7 @@ describe('Web session model selection', () => { const { ctx } = await harness() ctx.llm.registerAdapter(['plain'], new CatalogAdapter('Plain', [ { provider: 'plain', id: 'plain-model', name: 'Plain Model' }, + { provider: 'plain', id: 'badged-model', name: 'Badged Model', badge: { text: { en: 'New', zh: '新' }, tone: 'info' } }, ])) ctx.llm.registerAdapter(['described-reasoning'], new CatalogAdapter('Described Reasoning', [ { provider: 'described-reasoning', id: 'reasoning-model', name: 'Reasoning Model' }, @@ -485,7 +452,10 @@ describe('Web session model selection', () => { const catalog = await buildModelCatalog(ctx) expect(catalog.groups).toEqual(expect.arrayContaining([ - { id: 'plain', name: 'Plain', models: [{ id: 'plain-model', name: 'Plain Model' }] }, + { id: 'plain', name: 'Plain', models: [ + { id: 'plain-model', name: 'Plain Model' }, + { id: 'badged-model', name: 'Badged Model', badge: { text: { en: 'New', zh: '新' }, tone: 'info' } }, + ] }, { id: 'described-reasoning', name: 'Described Reasoning', diff --git a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts index af3c06a0b6..09b411ecdf 100644 --- a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts +++ b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts @@ -68,17 +68,43 @@ async function settleFrames(): Promise { await new Promise(resolve => setTimeout(resolve, 0)) } +type BenchSession = Awaited> + +/** Register an echo and let the Host accept its prompt, which publishes the echo. */ +async function submitAccepted( + session: BenchSession, + input: Parameters[0], +): Promise> { + const handle = session.beginSubmission(input) + const result = await session.prompt([{ type: 'text', text: input.text }], input.mode, undefined, handle.requestId) + expect(result.ok).toBe(true) + return handle +} + describe('beginSubmission', () => { - it('inserts the echo synchronously and flips the engaging edge before any prompt call', async ({ mock, start }) => { + it('publishes the echo and the engaging edge only once the Host accepts the prompt', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) expect(session.getSnapshot()).toMatchObject({ pendingSubmissions: [], promptAttempted: false }) + const onAccept = vi.fn() const handle = session.beginSubmission({ mode: 'queue', text: '你好', attachments: [{ type: 'image', value: { previewUrl: 'blob:p1', name: 'a.png', width: 4, height: 3 }, }], + onAccept, }) + expect(session.getSnapshot()).toMatchObject({ pendingSubmissions: [], promptAttempted: false }) + expect(mock.log.requests()).toEqual([]) + const receipt = Promise.withResolvers<{ ok: true; value: { accepted: true } }>() + mock.remote.session.prompt.mockImplementationOnce(() => receipt.promise) + const inFlight = session.prompt([{ type: 'text', text: '你好' }], 'queue', undefined, handle.requestId) + await Promise.resolve() + expect(session.getSnapshot()).toMatchObject({ pendingSubmissions: [], promptAttempted: false }) + expect(onAccept).not.toHaveBeenCalled() + receipt.resolve({ ok: true, value: { accepted: true } }) + expect((await inFlight).ok).toBe(true) + expect(onAccept).toHaveBeenCalledOnce() expect(session.getSnapshot().promptAttempted).toBe(true) expect(session.getSnapshot().pendingSubmissions).toMatchObject([{ requestId: handle.requestId, @@ -88,15 +114,82 @@ describe('beginSubmission', () => { type: 'image', value: { previewUrl: 'blob:p1', name: 'a.png', width: 4, height: 3 }, }], }]) - expect(mock.log.requests()).toEqual([]) }, COLD_BOOT_TIMEOUT_MS) + for (const { mode, running, target, placement } of [ + { mode: 'queue', running: false, target: 'next-turn', placement: 'transcript' }, + { mode: 'steer', running: true, target: 'next-step', placement: 'steering' }, + { mode: 'queue', running: true, target: 'next-turn', placement: 'queued' }, + ] as const) { + for (const path of ['projection', 'durable event'] as const) { + it(`accepts a ${placement} prompt once the Inbox holds it, ahead of the Host receipt (${path})`, async ({ mock, start }) => { + const onEngaged = vi.fn() + const session = await sessionBench(mock, start, SID, { onEngaged }) + await session.open() + session.handleBlank(!running) + session.handleRunning(running) + const onAccept = vi.fn() + const handle = session.beginSubmission({ mode, text: '先进收件箱', attachments: [], onAccept }) + const receipt = Promise.withResolvers<{ ok: true; value: { accepted: true } }>() + mock.remote.session.prompt.mockImplementationOnce(() => receipt.promise) + const inFlight = session.prompt([{ type: 'text', text: '先进收件箱' }], mode, undefined, handle.requestId) + const empty = { 'next-turn': [], 'next-step': [] } + // Projection faces notify in a microtask. + session.projections.apply('inbox', { ...empty, [target]: [queuedItem('another-request' as SessionRequestId)] }, -1) + await Promise.resolve() + expect(session.getSnapshot()).toMatchObject({ pendingSubmissions: [], blank: !running, promptAttempted: false }) + expect(onAccept).not.toHaveBeenCalled() + const message = queuedItem(handle.requestId) + if (path === 'projection') { + session.projections.apply('inbox', { ...empty, [target]: [message] }, SessionSeq(0)) + await Promise.resolve() + } else { + await pushEvent(mock, { + type: 'agent/inbox/spliced', seq: SessionSeq(0), time: 1, + data: { target, start: 0, inserted: [message] }, + }) + } + expect(session.getSnapshot()).toMatchObject({ + pendingSubmissions: [{ requestId: handle.requestId, placement, text: '先进收件箱' }], + blank: false, + promptAttempted: true, + ...running ? {} : { awaitingFirstTurn: true }, + }) + expect(onEngaged).toHaveBeenCalledOnce() + expect(onAccept).toHaveBeenCalledOnce() + receipt.resolve({ ok: true, value: { accepted: true } }) + expect((await inFlight).ok).toBe(true) + expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) + expect(onEngaged).toHaveBeenCalledOnce() + expect(onAccept).toHaveBeenCalledOnce() + }) + } + } + + it('never publishes an echo whose message was observed before the Host receipt', async ({ mock, start }) => { + const session = await sessionBench(mock, start, SID) + await session.open() + const retirements: PendingSubmissionRetirement[] = [] + const handle = session.beginSubmission({ + mode: 'queue', text: '先到', attachments: [], onRetire: retirement => retirements.push(retirement), + }) + const receipt = Promise.withResolvers<{ ok: true; value: { accepted: true } }>() + mock.remote.session.prompt.mockImplementationOnce(() => receipt.promise) + const inFlight = session.prompt([{ type: 'text', text: '先到' }], 'queue', undefined, handle.requestId) + await pushEvent(mock, promptEvent(SessionSeq(0), handle.requestId)) + await settleFrames() + expect(retirements).toEqual([{ reason: 'observed', attachments: [] }]) + receipt.resolve({ ok: true, value: { accepted: true } }) + expect((await inFlight).ok).toBe(true) + expect(session.getSnapshot().pendingSubmissions).toEqual([]) + }) + it('derives and captures the echo placement from running state and delivery mode', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - session.beginSubmission({ mode: 'queue', text: '空闲', attachments: [] }) + await submitAccepted(session, { mode: 'queue', text: '空闲', attachments: [] }) session.handleRunning(true) - session.beginSubmission({ mode: 'queue', text: '排队', attachments: [] }) - session.beginSubmission({ mode: 'steer', text: '纠偏', attachments: [] }) + await submitAccepted(session, { mode: 'queue', text: '排队', attachments: [] }) + await submitAccepted(session, { mode: 'steer', text: '纠偏', attachments: [] }) session.handleRunning(false) expect(session.getSnapshot().pendingSubmissions.map(({ text, placement }) => ({ text, placement }))).toEqual([ { text: '空闲', placement: 'transcript' }, @@ -107,12 +200,12 @@ describe('beginSubmission', () => { it('keeps rapid ordinary submissions in Chat until the running update arrives', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - for (const text of ['A', 'B', 'C']) session.beginSubmission({ mode: 'queue', text, attachments: [] }) + for (const text of ['A', 'B', 'C']) await submitAccepted(session, { mode: 'queue', text, attachments: [] }) expect(session.getSnapshot().pendingSubmissions.map(input => input.placement)).toEqual([ 'transcript', 'transcript', 'transcript', ]) session.handleRunning(true) - session.beginSubmission({ mode: 'queue', text: 'D', attachments: [] }) + await submitAccepted(session, { mode: 'queue', text: 'D', attachments: [] }) expect(session.getSnapshot().pendingSubmissions.map(input => input.placement)).toEqual([ 'transcript', 'transcript', 'transcript', 'queued', ]) @@ -161,8 +254,8 @@ describe('prompt-coupled retirement', () => { it('an unidentified prompt failure leaves registered echoes alone', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) + await submitAccepted(session, { mode: 'queue', text: '还在', attachments: [] }) mock.remote.session.prompt.mockResolvedValue(err(new RemoteError('session/agent-busy', '忙', { reason: 'busy' }))) - session.beginSubmission({ mode: 'queue', text: '还在', attachments: [] }) await session.prompt([{ type: 'text', text: '另一个' }], 'queue') expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) }) @@ -173,7 +266,7 @@ describe('observed retirement', () => { const session = await sessionBench(mock, start, SID) await session.open() const retirements: PendingSubmissionRetirement[] = [] - const handle = session.beginSubmission({ + const handle = await submitAccepted(session, { mode: 'queue', text: '发送', attachments: [{ type: 'image', value: { previewUrl: 'blob:p1' } }], @@ -193,7 +286,7 @@ describe('observed retirement', () => { const session = await sessionBench(mock, start, SID) await session.open() const onRetire = vi.fn() - const handle = session.beginSubmission({ mode: 'steer', text: 'accepted', attachments: [], onRetire }) + const handle = await submitAccepted(session, { mode: 'steer', text: 'accepted', attachments: [], onRetire }) const refs = [imageRef('claimed-image')] const message = queuedItem(handle.requestId, refs) session.projections.apply('inbox', { 'next-turn': [], 'next-step': [message] }, SessionSeq(0)) @@ -229,7 +322,7 @@ describe('observed retirement', () => { vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => frames.push(callback)) const onRetire = vi.fn() session.handleRunning(mode === 'steer') - const handle = session.beginSubmission({ mode, text: 'local input', attachments: [], onRetire }) + const handle = await submitAccepted(session, { mode, text: 'local input', attachments: [], onRetire }) const refs = [imageRef('idle-image'), fileRef('idle-file')] const message = queuedItem(handle.requestId, refs) const queued = { 'next-turn': [], 'next-step': [], [target]: [message] } @@ -277,10 +370,10 @@ describe('observed retirement', () => { const normalRetired = vi.fn() const queueRetired = vi.fn() const steerRetired = vi.fn() - const normal = session.beginSubmission({ mode: 'queue', text: 'opening', attachments: [], onRetire: normalRetired }) + const normal = await submitAccepted(session, { mode: 'queue', text: 'opening', attachments: [], onRetire: normalRetired }) session.handleRunning(true) - const queued = session.beginSubmission({ mode: 'queue', text: 'queued', attachments: [], onRetire: queueRetired }) - const steer = session.beginSubmission({ mode: 'steer', text: 'steering', attachments: [], onRetire: steerRetired }) + const queued = await submitAccepted(session, { mode: 'queue', text: 'queued', attachments: [], onRetire: queueRetired }) + const steer = await submitAccepted(session, { mode: 'steer', text: 'steering', attachments: [], onRetire: steerRetired }) const normalMessage = queuedItem(normal.requestId, [fileRef('opening-file')]) const queuedMessage = queuedItem(queued.requestId, [imageRef('queued-image')]) const steerMessage = queuedItem(steer.requestId, [imageRef('steer-image'), fileRef('steer-file')]) @@ -292,8 +385,11 @@ describe('observed retirement', () => { await pushEvent(mock, { type: 'agent/inbox/spliced', seq: SessionSeq(1), time: 2, data: { target: 'next-step', start: 0, inserted: [steerMessage] } }) flush() - expect(pending()).toEqual(['opening', 'steering']) - expect(queueRetired).toHaveBeenCalledExactlyOnceWith({ reason: 'observed', attachments: [imageRef('queued-image')] }) + // A queued echo waits for the inbox projection the queue dock renders, not the history event. + expect(pending()).toEqual(projectionFirst ? ['opening', 'steering'] : ['opening', 'queued', 'steering']) + if (projectionFirst) { + expect(queueRetired).toHaveBeenCalledExactlyOnceWith({ reason: 'observed', attachments: [imageRef('queued-image')] }) + } else expect(queueRetired).not.toHaveBeenCalled() await pushEvent(mock, ev.turnStart(SessionSeq(2), 1)) await pushEvent(mock, { type: 'agent/inbox/spliced', seq: SessionSeq(3), time: 4, data: { target: 'next-step', start: 0, removedCount: 1, inserted: [] } }) @@ -304,15 +400,17 @@ describe('observed retirement', () => { await pushEvent(mock, ev.stepStart(SessionSeq(5), 1, 1)) await pushEvent(mock, { type: 'user/message', seq: SessionSeq(6), time: 7, surfaceOp: 'append', data: steerMessage }) flush() - expect(pending()).toEqual(projectionFirst ? ['opening'] : ['opening', 'steering']) + expect(pending()).toEqual(projectionFirst ? ['opening'] : ['opening', 'queued', 'steering']) expect(normalRetired).not.toHaveBeenCalled() if (!projectionFirst) expect(steerRetired).not.toHaveBeenCalled() await pushEvent(mock, { type: 'user/message', seq: SessionSeq(7), time: 8, surfaceOp: 'append', data: normalMessage }) flush() if (!projectionFirst) { - expect(pending()).toEqual(['opening', 'steering']) + expect(pending()).toEqual(['opening', 'queued', 'steering']) session.projections.apply('inbox', accepted, SessionSeq(1)) + await Promise.resolve() flush() + expect(queueRetired).toHaveBeenCalledExactlyOnceWith({ reason: 'observed', attachments: [imageRef('queued-image')] }) expect(normalRetired).not.toHaveBeenCalled() session.projections.apply('inbox', claimed, SessionSeq(4)) await Promise.resolve() @@ -342,7 +440,7 @@ describe('observed retirement', () => { await session.open() session.handleRunning(true) const onRetire = vi.fn() - const handle = session.beginSubmission({ mode: 'steer', text: 'accepted', attachments: [], onRetire }) + const handle = await submitAccepted(session, { mode: 'steer', text: 'accepted', attachments: [], onRetire }) const refs = [imageRef('steer-image')] const message = queuedItem(handle.requestId, refs) const echo = session.getSnapshot().pendingSubmissions[0] @@ -369,16 +467,21 @@ describe('observed retirement', () => { expect(onRetire).toHaveBeenCalledExactlyOnceWith({ reason: 'observed', attachments: refs }) }) - for (const target of ['next-step', 'next-turn'] as const) { - it(`retires canceled or unadmitted ${target} input without removing still-pending input`, async ({ mock, start }) => { + for (const { target, running, mode, placement } of [ + { target: 'next-step', running: true, mode: 'steer', placement: 'steering' }, + { target: 'next-turn', running: false, mode: 'steer', placement: 'transcript' }, + { target: 'next-turn', running: true, mode: 'queue', placement: 'queued' }, + ] as const) { + it(`retires canceled or unadmitted ${placement} input without removing still-pending input`, async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) await session.open() - session.handleRunning(target === 'next-step') + session.handleRunning(running) const canceled = vi.fn() const rejected = vi.fn() - const first = session.beginSubmission({ mode: 'steer', text: 'cancel', attachments: [], onRetire: canceled }) - const second = session.beginSubmission({ mode: 'steer', text: 'reject', attachments: [], onRetire: rejected }) - const unclaimed = session.beginSubmission({ mode: 'steer', text: 'later', attachments: [] }) + const first = await submitAccepted(session, { mode, text: 'cancel', attachments: [], onRetire: canceled }) + const second = await submitAccepted(session, { mode, text: 'reject', attachments: [], onRetire: rejected }) + const unclaimed = await submitAccepted(session, { mode, text: 'later', attachments: [] }) + expect(session.getSnapshot().pendingSubmissions.map(echo => echo.placement)).toEqual([placement, placement, placement]) const foreign = createUserMessage({ source: { kind: 'user' }, content: [] }) await pushEvent(mock, { type: 'agent/inbox/spliced', seq: SessionSeq(0), time: 1, @@ -469,7 +572,7 @@ describe('observed retirement', () => { await session.open() session.handleRunning(target === 'next-step') const onRetire = vi.fn() - const handle = session.beginSubmission({ mode: 'steer', text: 'accepted', attachments: [], onRetire }) + const handle = await submitAccepted(session, { mode: 'steer', text: 'accepted', attachments: [], onRetire }) const refs = [imageRef('steer-image'), fileRef('steer-file')] const message = queuedItem(handle.requestId, refs) if (target === 'next-turn') { @@ -481,7 +584,7 @@ describe('observed retirement', () => { data: { target, start: 0, inserted: [message] }, }) } - const unconfirmed = session.beginSubmission({ mode: 'steer', text: 'not accepted yet', attachments: [] }) + const unconfirmed = await submitAccepted(session, { mode: 'steer', text: 'not accepted yet', attachments: [] }) const inbox = { 'next-turn': [], 'next-step': [], [target]: pending ? [message] : [] } const replacement = { ...historyValue([ev.turnEnd(SessionSeq(10), 2)], true), @@ -572,7 +675,7 @@ describe('observed retirement', () => { frames.push(fn) return frames.length }) - const handle = session.beginSubmission({ mode: 'queue', text: '帧', attachments: [] }) + const handle = await submitAccepted(session, { mode: 'queue', text: '帧', attachments: [] }) await pushEvent(mock, promptEvent(SessionSeq(0), handle.requestId)) expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) expect(frames).toHaveLength(1) diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts index 8980cd1f1e..e118ef29e5 100644 --- a/packages/api/session-controller/tests/session.client.spec.ts +++ b/packages/api/session-controller/tests/session.client.spec.ts @@ -15,7 +15,7 @@ import { ok, type RemoteMock } from '@deepseek-ai/dsh-remote-mock' import { createClientTest, type TestClient, webApp } from '@deepseek-ai/dsh-client-test-runtime/src/assembly/index.ts' import { Session } from '../src/client/sessions/session.ts' import { SessionEventStream } from '../src/client/transport.ts' -import type { SessionFollowRequest, SessionPage, SessionPageRequest } from '../src/types.ts' +import type { SessionFollowRequest, SessionEventsPage, SessionPageRequest } from '../src/types.ts' import { entries, ev, historyValue, plainTurn } from './event-script.client.ts' import { sessionBench } from './remote/bench.client.ts' import { @@ -122,7 +122,7 @@ describe('Session open', () => { it('stitches live frames landing right behind the opening snapshot, dropping the page overlap', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - const gate = Promise.withResolvers() + const gate = Promise.withResolvers() const page = plainTurn(SessionSeq(10), 0, '早', '安') mock.stream(FOLLOW, async ([request], stream) => { stream.push(followSnapshot(await gate.promise, request as SessionFollowRequest)) @@ -243,7 +243,7 @@ describe('paging', () => { mock.stream(FOLLOW, followScript(history(newest, true))) await session.open() - const gate = Promise.withResolvers>() + const gate = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule(request => (request.beforeSeq === 12 ? history(middle, true) : history(oldest)))) mock.remote.session.page.mockReturnValueOnce(gate.promise) const jump = session.loadThrough(SessionSeq(0)) @@ -279,7 +279,7 @@ describe('paging', () => { mock.stream(FOLLOW, followScript(history(newest, true))) await session.open() const secondRequested = Promise.withResolvers() - const lastPage = Promise.withResolvers>() + const lastPage = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule((request) => { if (request.beforeSeq === 12) return history(middle, true) secondRequested.resolve(undefined) @@ -334,7 +334,7 @@ describe('paging', () => { mock.stream(FOLLOW, followScript(history(newest, true))) await session.open() const secondRequested = Promise.withResolvers() - const lastPage = Promise.withResolvers>() + const lastPage = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule((request) => { if (request.beforeSeq === 12) return history(plainTurn(SessionSeq(6), 1, 'middle', 'answer'), true) secondRequested.resolve(undefined) @@ -360,7 +360,7 @@ describe('paging', () => { mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(12), 2, 'e', 'f'), true))) await session.open() - const gate = Promise.withResolvers>() + const gate = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule(history(oldest))) mock.remote.session.page.mockReturnValueOnce(gate.promise) const first = session.loadThrough(SessionSeq(6)) @@ -381,7 +381,7 @@ describe('paging', () => { await session.open() // A plain single-page pull holds the busy flag while the jump is refused. - const gate = Promise.withResolvers>() + const gate = Promise.withResolvers>() mock.remote.session.page.mockReturnValueOnce(gate.promise) const older = session.loadOlder() await session.loadThrough(SessionSeq(0)) // refused: must not park seq 0 anywhere @@ -409,7 +409,7 @@ describe('paging', () => { mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(12), 2, 'x', 'y'), true))) await session.open() - const gate = Promise.withResolvers>() + const gate = Promise.withResolvers>() mock.remote.session.page.mockReturnValueOnce(gate.promise) const jump = session.loadThrough(SessionSeq(0)) // The address is rebuilt while the first page is in flight; the same follow script serves the new generation. @@ -459,7 +459,7 @@ describe('paging', () => { const session = await sessionBench(mock, start, SID) mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(6), 1, 'x', 'y'), true))) await session.open() - const gate = Promise.withResolvers>() + const gate = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule(gate.promise)) const first = session.loadOlder() const second = session.loadOlder() @@ -484,7 +484,7 @@ describe('prompt and cancel errors', () => { expect(steered).toEqual({ ok: true, value: { accepted: true } }) expect(cancelled).toEqual({ ok: true, value: { accepted: true } }) expect(mock.log.requests(FOLLOW)).toEqual([ - { address: { kind: 'subagent', ...CHILD }, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, + { address: { kind: 'subagent', ...CHILD }, activate: true, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, ]) expect(mock.log.requests(PAGE)).toEqual([]) // The prompt mode crosses the wire as the request's delivery. @@ -592,7 +592,7 @@ describe('prompt and cancel errors', () => { expect(mock.log.requests('subagents/prompt')).toMatchObject([{ childSessionId: SID }]) expect(mock.log.calls('subagents/interruptByUser').map(call => call.args)).toEqual([[SID]]) expect(mock.log.requests(FOLLOW)).toEqual([ - { address: { kind: 'subagent', ...CHILD, mode: 'one-shot' }, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, + { address: { kind: 'subagent', ...CHILD, mode: 'one-shot' }, activate: true, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, ]) expect(mock.log.requests(PAGE)).toEqual([]) expect(mock.log.requests('session/cancel')).toEqual([]) @@ -612,15 +612,17 @@ describe('prompt and cancel errors', () => { ]) }) - it('publishes the first-prompt lifecycle synchronously before the Remote settles', async ({ mock, start }) => { + it('publishes the first-prompt lifecycle once the Host accepts the prompt', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) session.handleBlank(true) expect(session.getSnapshot()).toMatchObject({ blank: true, promptAttempted: false, awaitingFirstTurn: false, }) const inFlight = session.prompt([{ type: 'text', text: '要发的' }], 'queue') + // An unrelated update rebuilds the snapshot while the Host has not answered yet. + session.handleAgentError('unrelated live failure') expect(session.getSnapshot()).toMatchObject({ - blank: true, promptAttempted: true, awaitingFirstTurn: true, + blank: true, promptAttempted: false, awaitingFirstTurn: false, lastAgentError: 'unrelated live failure', }) const result = await inFlight expect(result.ok).toBe(true) @@ -641,9 +643,22 @@ describe('prompt and cancel errors', () => { const session = await sessionBench(mock, start, SID) session.handleBlank(false) const inFlight = session.prompt([{ type: 'text', text: '继续' }], 'queue') - expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: true, awaitingFirstTurn: false }) + expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: false, awaitingFirstTurn: false }) expect((await inFlight).ok).toBe(true) - expect(session.getSnapshot()).toMatchObject({ blank: false, awaitingFirstTurn: false }) + expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: true, awaitingFirstTurn: false }) + }) + + it('does not await a first turn that started before the Host receipt arrived', async ({ mock, start }) => { + const session = await sessionBench(mock, start, SID) + session.handleBlank(true) + const receipt = Promise.withResolvers<{ ok: true; value: { accepted: true } }>() + mock.remote.session.prompt.mockImplementationOnce(() => receipt.promise) + const inFlight = session.prompt([{ type: 'text', text: '很快' }], 'queue') + session.handleRunning(true) + session.handleRunning(false) + receipt.resolve({ ok: true, value: { accepted: true } }) + expect((await inFlight).ok).toBe(true) + expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: true, awaitingFirstTurn: false }) }) it('keeps an accepted first prompt converted when a later prompt is rejected', async ({ mock, start }) => { @@ -661,7 +676,7 @@ describe('prompt and cancel errors', () => { }) }) - it('keeps the attempted-first-prompt state when the Host rejects the prompt', async ({ mock, start }) => { + it('keeps a first prompt the Host rejects blank and unattempted', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) session.handleBlank(true) mock.remote.session.prompt.mockResolvedValue(err(new RemoteError('session/agent-busy', 'busy', { reason: 'x' }))) @@ -669,7 +684,7 @@ describe('prompt and cancel errors', () => { expect(result.ok).toBe(false) expect(session.getSnapshot().promptError).toMatchObject({ op: 'send', error: { code: 'session/agent-busy' } }) expect(session.getSnapshot()).toMatchObject({ - blank: true, promptAttempted: true, awaitingFirstTurn: true, + blank: true, promptAttempted: false, awaitingFirstTurn: false, }) }) @@ -683,9 +698,11 @@ describe('prompt and cancel errors', () => { expect(session.getSnapshot().promptError).toMatchObject({ op: 'stop', error: { code: 'gateway/internal' } }) }) - it('reads session-authorized attachment bytes and keeps the opaque id on the wire', async ({ mock, start }) => { + it('sends the complete image reference and decodes the gateway response', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - const result = await session.readAttachment('attachment-1' as never) + const attachment = { attachmentId: AttachmentId('attachment-1'), mediaType: 'image/png' as const, + bytes: 1, width: 1, height: 1, name: 'picture.png', originalDimensions: { width: 2, height: 2 } } + const result = await session.readAttachment(attachment) expect(result).toEqual({ ok: true, value: { @@ -694,7 +711,7 @@ describe('prompt and cancel errors', () => { }, }) expect(mock.log.requests('session/attachment')).toEqual([{ - sessionId: SID, attachmentId: 'attachment-1', + sessionId: SID, attachment, }]) }) @@ -702,7 +719,9 @@ describe('prompt and cancel errors', () => { const session = await sessionBench(mock, start, SID) const failure = new RemoteError('gateway/internal', 'attachment unavailable', {}) mock.remote.session.attachment.mockResolvedValueOnce(err(failure)) - await expect(session.readAttachment(AttachmentId('missing'))).resolves.toMatchObject({ ok: false, error: failure }) + await expect(session.readAttachment({ + attachmentId: AttachmentId('missing'), mediaType: 'image/png', bytes: 1, width: 1, height: 1, + })).resolves.toMatchObject({ ok: false, error: failure }) }) it('reports an unmatched command and forwards execution failures without opening history', async ({ mock, start }) => { @@ -873,7 +892,7 @@ describe('remaining branches', () => { const session = await sessionBench(mock, start, SID) mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(0), 0, 'a', 'b')))) await session.open() - const gate = Promise.withResolvers>() + const gate = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule(gate.promise)) await pushEvent(mock, ev.user(SessionSeq(9), '洞一')) await pushEvent(mock, ev.user(SessionSeq(10), '洞二')) @@ -886,7 +905,7 @@ describe('remaining branches', () => { it('drops a stale opening without replacing the new generation error state', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - const stale = Promise.withResolvers>() + const stale = Promise.withResolvers>() mock.stream(FOLLOW, followScript(() => stale.promise)) const opening = session.open() mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(0), 0, 'a', 'b')))) @@ -898,7 +917,7 @@ describe('remaining branches', () => { it('drops a stale doOpen whose history resolved successfully after resync superseded it', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - const stale = Promise.withResolvers>() + const stale = Promise.withResolvers>() mock.stream(FOLLOW, followScript(() => stale.promise)) const opening = session.open() mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(6), 1, '新', '代')))) @@ -912,7 +931,7 @@ describe('remaining branches', () => { const session = await sessionBench(mock, start, SID) mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(0), 0, 'a', 'b')))) await session.open() - const repairPull = Promise.withResolvers>() + const repairPull = Promise.withResolvers>() mock.remote.session.page.mockImplementation(pageRule(repairPull.promise)) await pushEvent(mock, ev.user(SessionSeq(9), '洞')) await vi.waitFor(() => { expect(mock.log.requests(PAGE)).toHaveLength(1) }) @@ -954,7 +973,7 @@ describe('resync', () => { mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(0), 0, '旧', '窗')))) await session.open() const oldWindow = session.eventSource.getSnapshot() - const replacement = Promise.withResolvers() + const replacement = Promise.withResolvers() // The reconnect generation: its snapshot is gated, then two live frames land out of order right behind it. mock.stream(FOLLOW, async ([request], stream) => { stream.push(followSnapshot(await replacement.promise, request as SessionFollowRequest)) @@ -1013,7 +1032,7 @@ describe('resync', () => { it('drops a stale in-flight open superseded by resync (generation guard)', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) - const stale = Promise.withResolvers>() + const stale = Promise.withResolvers>() mock.stream(FOLLOW, followScript(() => stale.promise)) const firstOpen = session.open() mock.stream(FOLLOW, followScript(history(plainTurn(SessionSeq(6), 1, '新', '代')))) diff --git a/packages/api/session-controller/tests/sessions-service.client.spec.ts b/packages/api/session-controller/tests/sessions-service.client.spec.ts index f43e32e64e..212320fdf6 100644 --- a/packages/api/session-controller/tests/sessions-service.client.spec.ts +++ b/packages/api/session-controller/tests/sessions-service.client.spec.ts @@ -12,7 +12,7 @@ import { createClientTest, webApp } from '@deepseek-ai/dsh-client-test-runtime/s import { ClientSessions, SessionCreateError, SessionForkError } from '../src/client/sessions/service.ts' import { scopeOf } from '../src/client/scope.ts' import type { - SessionAssistantStreamBaseline, SessionFollowFrame, SessionFollowRequest, + SessionAssistantStreamBaseline, SessionFollowFrame, SessionFollowRequest, SessionHistoryRecord, } from '../src/types.ts' import { FOLLOW, err, followScript, sessionWorld } from './remote/session.client.ts' @@ -174,7 +174,7 @@ describe('scope tree', () => { it('opens a conversation from follow projections without a second projection request', async ({ bench }) => { const b = bench() b.mock.stream(FOLLOW, followScript(ok({ - records: [], hasMore: false, + cursor: 0, records: [], hasMore: false, projections: { asOfSeq: 0, values: { subagentCatalog: [{ id: sid('child'), createdAt: 1, mode: 'one-shot', }] } }, @@ -277,7 +277,7 @@ describe('scope tree', () => { it('replaces an active assistant baseline on reconnect without duplicate chunks', async ({ bench }) => { const b = bench() const attemptId = LlmAttemptId('reconnect-attempt') - let records: never[] = [] + let records: SessionHistoryRecord[] = [] let assistantStreamBaseline: SessionAssistantStreamBaseline = { revision: 2, activeAttempt: { @@ -287,7 +287,7 @@ describe('scope tree', () => { }, } b.mock.stream(FOLLOW, followScript( - () => ok({ records, hasMore: false }), + () => ok({ cursor: records.at(-1)?.event.seq ?? -1, records, hasMore: false }), { assistantStream: () => assistantStreamBaseline }, )) await feedList(b, [{ id: 's1' }]) @@ -361,6 +361,7 @@ describe('scope tree', () => { }, } const history = ok({ + cursor: priorMessage.event.seq, records: [priorMessage] as never[], hasMore: false, }) @@ -437,7 +438,7 @@ describe('scope tree', () => { surfaceOp: 'append' as const, }, } - let records = [prior] as never[] + let records: SessionHistoryRecord[] = [prior] let assistantStreamBaseline: SessionAssistantStreamBaseline = { revision: 2, activeAttempt: { @@ -450,7 +451,7 @@ describe('scope tree', () => { }, } b.mock.stream(FOLLOW, followScript( - () => ok({ records, hasMore: false }), + () => ok({ cursor: records.at(-1)?.event.seq ?? -1, records, hasMore: false }), { assistantStream: () => assistantStreamBaseline }, )) await feedList(b, [{ id: 's1' }]) diff --git a/packages/api/session-controller/tests/state-controller.host.spec.ts b/packages/api/session-controller/tests/state-controller.host.spec.ts new file mode 100644 index 0000000000..5fc74006ff --- /dev/null +++ b/packages/api/session-controller/tests/state-controller.host.spec.ts @@ -0,0 +1,480 @@ +import { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { createInboxStub } from '@deepseek-ai/dsh-agent-loop-testkit' +import { brandString } from '@deepseek-ai/dsh-brand' +import type AgentRegistry from '@deepseek-ai/dsh-agent' +import type TypertGatewayService from '@deepseek-ai/dsh-api-gateway' +import type { PendingRemoteEventInfo } from '@deepseek-ai/dsh-api-gateway' +import { createUserMessage } from '@deepseek-ai/dsh-llm' +import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session' +import type { SessionHeader } from '@deepseek-ai/dsh-session' +import type { SessionObservation } from '@deepseek-ai/dsh-session-query' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { HistoryController } from '../src/history/controller.ts' +import { RemoteError } from '@deepseek-ai/dsh-typert-protocol' +import { StateController } from '../src/state/controller.ts' +import { StateListener } from '../src/state/listener.ts' +import type { SessionState, SessionRequestId } from '../src/types.ts' +import { installSessionReadTestServices } from './test-remote.ts' + +const roots: Context[] = [] +const aborters: AbortController[] = [] +const operations: Promise[] = [] +function cancellation(): AbortController { + const abort = new AbortController() + aborters.push(abort) + return abort +} +function tracked(promise: Promise): Promise { + operations.push(promise) + void promise.catch(() => undefined) + return promise +} +function deferred() { + let resolve!: (value: T) => void + const promise = new Promise((settle) => { resolve = settle }) + return { promise, resolve } +} +afterEach(async () => { + for (const abort of aborters.splice(0)) abort.abort() + await Promise.allSettled(operations.splice(0)) + await Promise.all(roots.splice(0).map(ctx => ctx.fiber.dispose())) + vi.restoreAllMocks() + vi.useRealTimers() +}) + +async function fixture() { + const ctx = new Context() + roots.push(ctx) + await ctx.plugin(SessionStore) + installSessionReadTestServices(ctx) + const session = ctx.sessions.create(SessionId('state-target'), { meta: { cwd: '/state-test' } }) + let agent: Agent | undefined + const get = vi.fn(() => agent) + const agents: Partial = { get } + ctx.provide('agents', agents as AgentRegistry) + const pending: PendingRemoteEventInfo[] = [] + const pendingRead = vi.fn(() => pending) + const gateway: Partial = { getPendingRemoteEvents: pendingRead } + ctx.provide('typertGateway', gateway as TypertGatewayService) + const history = new HistoryController(ctx) + const output = vi.spyOn(history, 'assistantOutput').mockResolvedValue({ records: [], truncated: false }) + const controller = new StateController(ctx, history) + const abort = cancellation() + const request = { sessionId: session.id } + const live = (status: Agent['status'] = 'running', idle = Promise.resolve(undefined)) => { + const value = { + id: session.id, session, status, + inbox: createInboxStub(), + whenIdle: vi.fn(() => idle), + } + const partial: Partial = value + agent = partial as Agent + return value + } + const addPending = (event: string, id = session.id) => { + pending.push({ event, agentId: brandString(id) }) + } + return { + ctx, session, controller, history, output, abort, request, live, get, pending, pendingRead, addPending, + setAgent: (value: Agent | undefined) => { agent = value }, + } +} +const emptyState: SessionState = { cursor: -1, active: false, running: false, queue: null, pendingInput: [] } + +describe('StateController', () => { + it('re-reads a state whose cold read turned live', async () => { + const f = await fixture() + const agent = f.live('running') + // The first lookup misses; the Session is a live source by the time the cold read runs. + let lookups = 0 + f.get.mockImplementation(() => (lookups++ === 0 ? undefined : agent as never)) + const state = await f.controller.state(f.request, new AbortController().signal) + expect(state).toMatchObject({ active: true, running: true, queue: [] }) + expect(state.cursor).toBe(f.session.seq - 1) + expect(lookups).toBeGreaterThan(1) + }) + + it('rejects a live state read whose Session records no cwd', async () => { + const f = await fixture() + const session = f.ctx.sessions.create(SessionId('no-cwd-live')) + const partial: Partial = { + id: session.id, session, status: 'idle', inbox: createInboxStub(), whenIdle: vi.fn(() => Promise.resolve(undefined)), + } + f.setAgent(partial as Agent) + await expect(f.controller.state({ sessionId: session.id }, new AbortController().signal)) + .rejects.toMatchObject({ code: 'session/not-found' }) + }) + + it('rejects a cold state read whose stored header records no cwd', async () => { + const f = await fixture() + const header: SessionHeader = { + version: SESSION_FORMAT_VERSION, id: f.session.id, createdAt: 1, isSeeded: false, + } + const observation: SessionObservation = { + source: 'prepared', + header, + inheritedEventCount: SessionLogOffset(0), + events: [], + cursor: -1, + projections: { asOfSeq: -1, values: {} }, + retain: () => observation, + [Symbol.dispose]: () => {}, + } + vi.spyOn(f.history, 'usingObservation').mockImplementation(async (_request, _signal, callback) => + callback?.(observation)) + await expect(f.controller.state(f.request, new AbortController().signal)) + .rejects.toMatchObject({ code: 'session/not-found' }) + }) + + it('reads cold state without projections and reports classified, deduplicated pending input', async () => { + const f = await fixture() + const read = vi.spyOn(f.history, 'usingObservation') + f.addPending('approval/request') + f.addPending('user-questions/request') + f.addPending('fixture/request') + f.addPending('approval/request') + f.addPending('ignored', SessionId('other')) + expect(await f.controller.state(f.request, f.abort.signal)).toEqual({ ...emptyState, pendingInput: ['approval', 'question', 'other'] }) + expect(read).toHaveBeenCalledWith({ sessionId: f.session.id, projection: false }, f.abort.signal, expect.any(Function)) + }) + + it('preserves live queues, RPC identities and steering versus context placement', async () => { + const f = await fixture() + const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } }) + const steering = createUserMessage({ content: [{ type: 'text', text: 'steer' }], source: { kind: 'user', rpcId: 'rpc' as SessionRequestId } }) + const context = createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'user-approval' } }) + const agent = f.live() + agent.inbox.append('next-turn', queued) + agent.inbox.append('next-step', steering) + agent.inbox.append('next-step', context) + expect(await f.controller.state(f.request, f.abort.signal)).toEqual({ + cursor: -1, active: true, running: true, pendingInput: [], + queue: [ + { id: queued.id, placement: 'queued', content: queued.content }, + { id: steering.id, placement: 'steering', content: steering.content, rpcId: 'rpc' }, + { id: context.id, placement: 'context', content: context.content }, + ], + }) + }) + + it('rejects already cancelled state reads', async () => { + const f = await fixture() + f.abort.abort(new Error('cancelled')) + await expect(f.controller.state(f.request, f.abort.signal)).rejects.toThrow('cancelled') + }) + + it('observes complete replacements and closes a pending read on cancellation', async () => { + const f = await fixture() + const states = f.controller.observeState(f.request, f.abort.signal)[Symbol.asyncIterator]() + expect(await states.next()).toMatchObject({ value: emptyState }) + f.live() + const next = tracked(states.next()) + f.session.append('turn/start', { turn: 1 }) + expect(await next).toMatchObject({ value: { active: true, running: true, cursor: 0 } }) + const end = tracked(states.next()) + f.abort.abort() + expect(await end).toEqual({ done: true, value: undefined }) + await states.return?.() + }) + + it('returns inactive idle state and delegates the exact output window with caller signal', async () => { + const f = await fixture() + const result = await f.controller.wait({ ...f.request, afterSeq: 3, maxMessages: 2 }, f.abort.signal) + expect(result).toEqual({ reason: 'idle', state: emptyState, output: { records: [], truncated: false } }) + expect(f.output).toHaveBeenCalledWith(f.session.id, 3, -1, 2, f.abort.signal) + }) + + it('stops immediately for pending input even while the Agent runs', async () => { + const f = await fixture() + f.live() + f.addPending('approval/request') + expect(await f.controller.wait(f.request, f.abort.signal)).toMatchObject({ reason: 'input-required' }) + }) + + it('confirms an active idle Agent with whenIdle', async () => { + const f = await fixture() + const agent = f.live('idle') + expect(await f.controller.wait(f.request, f.abort.signal)).toMatchObject({ reason: 'idle', state: { active: true } }) + expect(agent.whenIdle).toHaveBeenCalledOnce() + }) + + it('polls pending input after one second without Gateway notifications', async () => { + const f = await fixture() + vi.useFakeTimers() + f.live() + const result = tracked(f.controller.wait(f.request, f.abort.signal)) + await vi.advanceTimersByTimeAsync(0) + expect(f.pendingRead).toHaveBeenCalledTimes(1) + f.addPending('user-questions/request') + await vi.advanceTimersByTimeAsync(999) + expect(f.pendingRead).toHaveBeenCalledTimes(1) + await vi.advanceTimersByTimeAsync(1) + expect(await result).toMatchObject({ reason: 'input-required', state: { pendingInput: ['question'] } }) + expect(vi.getTimerCount()).toBe(0) + }) + + it('uses the latest accepted state on timeout and still reads output with the caller signal', async () => { + const f = await fixture() + vi.useFakeTimers() + f.live() + const result = tracked(f.controller.wait({ ...f.request, timeoutMs: 1500 }, f.abort.signal)) + await vi.advanceTimersByTimeAsync(1500) + expect(await result).toMatchObject({ reason: 'timeout', state: { running: true } }) + expect(f.output).toHaveBeenCalledWith(f.session.id, -1, -1, 50, f.abort.signal) + expect(f.abort.signal.aborted).toBe(false) + expect(vi.getTimerCount()).toBe(0) + }) + + it('responds to a standard event before the polling tick and races idle against new state', async () => { + const f = await fixture() + vi.useFakeTimers() + const idle = deferred() + f.live('idle', idle.promise) + const result = tracked(f.controller.wait(f.request, f.abort.signal)) + await vi.advanceTimersByTimeAsync(0) + f.addPending('approval/request') + f.session.append('turn/start', { turn: 1 }) + await vi.advanceTimersByTimeAsync(0) + expect(await result).toMatchObject({ reason: 'input-required', state: { cursor: 0 } }) + idle.resolve(undefined) + expect(vi.getTimerCount()).toBe(0) + }) + + it('propagates cancellation while waiting and cleans periodic reads', async () => { + const f = await fixture() + vi.useFakeTimers() + f.live() + const result = tracked(f.controller.wait(f.request, f.abort.signal)) + await vi.advanceTimersByTimeAsync(0) + f.abort.abort(new Error('caller cancelled')) + await expect(result).rejects.toThrow('caller cancelled') + expect(f.output).not.toHaveBeenCalled() + expect(vi.getTimerCount()).toBe(0) + }) + + it('propagates an idle-driver failure without treating it as a deadline', async () => { + const f = await fixture() + const idle = deferred() + const agent = f.live('idle', idle.promise) + agent.whenIdle.mockImplementation(() => Promise.reject(new Error('driver failed'))) + await expect(f.controller.wait(f.request, f.abort.signal)).rejects.toThrow('driver failed') + idle.resolve(undefined) + }) + + it('propagates a structured read failure raised before the deadline', async () => { + const f = await fixture() + const failure = deferred() + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + await failure.promise + throw new RemoteError('gateway/internal', 'persistent read failed', {}) + }) + const result = tracked(f.controller.wait({ ...f.request, timeoutMs: 5_000 }, f.abort.signal)) + failure.resolve(undefined) + await expect(result).rejects.toMatchObject({ code: 'gateway/internal' }) + }) + + it('keeps a structured read failure raised after the deadline', async () => { + const f = await fixture() + vi.useFakeTimers() + let rejectRead!: (error: Error) => void + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + await new Promise((_resolve, reject) => { rejectRead = reject }) + yield* [] + }) + const result = tracked(f.controller.wait({ ...f.request, timeoutMs: 20 }, f.abort.signal)) + await vi.advanceTimersByTimeAsync(20) + rejectRead(new RemoteError('gateway/internal', 'persistent read failed', {})) + await expect(result).rejects.toMatchObject({ code: 'gateway/internal' }) + expect(vi.getTimerCount()).toBe(0) + }) + + it('reports timeout when its first cold read never yields a state', async () => { + const f = await fixture() + vi.useFakeTimers() + vi.spyOn(f.ctx.sessionQuery, 'observeSession').mockImplementation((_id, options) => new Promise((_resolve, reject) => { + const abort = options?.signal + abort?.addEventListener('abort', () => { + const reason: unknown = abort.reason + reject(Object.assign(new Error('session observation was aborted'), { + code: 'SESSION_QUERY_ABORTED', cause: reason, + })) + }, { once: true }) + })) + const result = tracked(f.controller.wait({ ...f.request, timeoutMs: 20 }, f.abort.signal)) + await vi.advanceTimersByTimeAsync(20) + await expect(result).rejects.toMatchObject({ code: 'session/wait-timeout' }) + expect(f.output).not.toHaveBeenCalled() + expect(vi.getTimerCount()).toBe(0) + }) + + it('rejects a state stream that ends before a stopping observation', async () => { + const f = await fixture() + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () {}) + await expect(f.controller.wait(f.request, f.abort.signal)).rejects.toMatchObject({ code: 'session/observation-ended' }) + }) + + it('settles an already-armed failed read when the preceding observation stops the wait', async () => { + const f = await fixture() + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + yield { state: emptyState, revision: 0 } + throw new Error('next read failed') + }) + expect(await f.controller.wait(f.request, f.abort.signal)).toMatchObject({ reason: 'idle' }) + }) + + it('ignores a yielded state invalidated before wait accepts it', async () => { + const f = await fixture() + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + yield { state: { ...emptyState, running: true }, revision: 0 } + yield { state: emptyState, revision: 1 } + }) + vi.spyOn(StateListener.prototype, 'isCurrent').mockReturnValueOnce(false).mockReturnValue(true) + expect(await f.controller.wait(f.request, f.abort.signal)).toMatchObject({ reason: 'idle', state: emptyState }) + }) + + it('times out with the last accepted state, not a later invalidated sample', async () => { + const f = await fixture() + vi.useFakeTimers() + const accepted = { ...emptyState, running: true } + const stale = { ...emptyState, running: true, cursor: 7 } + const never = deferred() + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + yield { state: accepted, revision: 0 } + yield { state: stale, revision: 0 } + await never.promise + yield* [] + }) + vi.spyOn(StateListener.prototype, 'isCurrent').mockReturnValueOnce(true).mockReturnValue(false) + const result = tracked(f.controller.wait({ ...f.request, timeoutMs: 20 }, f.abort.signal)) + await vi.advanceTimersByTimeAsync(20) + never.resolve(undefined) + await expect(result).resolves.toMatchObject({ reason: 'timeout', state: { cursor: -1 } }) + }) + + it.each(['missing-agent', 'different-session'] as const)('retries active state when its owner is %s', async (condition) => { + const f = await fixture() + const agent = f.live('idle') + if (condition === 'missing-agent') f.setAgent(undefined) + else Object.assign(agent, { session: f.ctx.sessions.create(SessionId('replacement')) }) + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + yield { state: { ...emptyState, active: true, queue: [] }, revision: 0 } + yield { state: emptyState, revision: 0 } + }) + expect(await f.controller.wait(f.request, f.abort.signal)).toMatchObject({ reason: 'idle', state: emptyState }) + expect(agent.whenIdle).not.toHaveBeenCalled() + }) + + it.each(['revision', 'agent', 'session'] as const)('rechecks %s after the idle promise settles', async (changed) => { + const f = await fixture() + const idle = deferred() + const entered = deferred() + const next = deferred() + const agent = f.live('idle', idle.promise) + agent.whenIdle.mockImplementation(() => { entered.resolve(undefined); return idle.promise }) + vi.spyOn(StateListener.prototype, 'observeStates').mockImplementation(async function* () { + yield { state: { ...emptyState, active: true, queue: [] }, revision: 0 } + await next.promise + yield { state: emptyState, revision: 0 } + }) + const rechecked = deferred() + let checks = 0 + vi.spyOn(StateListener.prototype, 'isCurrent').mockImplementation(() => { + checks++ + if (checks === 2) rechecked.resolve(undefined) + return !(changed === 'revision' && checks === 2) + }) + const result = tracked(f.controller.wait(f.request, f.abort.signal)) + try { + await entered.promise + if (changed === 'agent') f.setAgent(undefined) + if (changed === 'session') Object.assign(agent, { session: f.ctx.sessions.create(SessionId('new-session')) }) + idle.resolve(undefined) + await rechecked.promise + next.resolve(undefined) + expect(await result).toMatchObject({ reason: 'idle', state: emptyState }) + } finally { + idle.resolve(undefined) + next.resolve(undefined) + f.abort.abort() + await Promise.allSettled([result]) + } + }) + + it.each([ + { afterSeq: -2 }, { afterSeq: -0 }, { afterSeq: 1.5 }, + { maxMessages: 0 }, { maxMessages: 1.5 }, + { timeoutMs: 0 }, { timeoutMs: 2147483648 }, { timeoutMs: 1.5 }, + ])('rejects unsupported wait bounds %j', async (bounds) => { + const f = await fixture() + await expect(f.controller.wait({ ...f.request, ...bounds }, f.abort.signal)).rejects.toMatchObject({ code: 'gateway/bad-request' }) + }) +}) + +describe('StateListener', () => { + it('discards an async stale read and coalesces repeated invalidations', async () => { + const f = await fixture() + const first = deferred() + const reading = deferred() + const read = vi.fn() + .mockImplementationOnce(() => { reading.resolve(undefined); return first.promise }) + .mockResolvedValue({ ...emptyState, cursor: 1 }) + using listener = new StateListener(f.ctx, f.session.id, f.abort.signal, read) + const states = listener.observeStates() + const pending = tracked(states.next()) + await reading.promise + f.session.append('turn/start', { turn: 1 }) + f.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) + first.resolve(emptyState) + expect(await pending).toEqual({ done: false, value: { state: { ...emptyState, cursor: 1 }, revision: 2 } }) + expect(read).toHaveBeenCalledTimes(2) + expect(listener.isCurrent(0)).toBe(false) + expect(listener.isCurrent(2)).toBe(true) + await states.return(undefined) + expect(listener.isCurrent(2)).toBe(false) + }) + + it('ignores other Sessions and ends when its Context is disposed', async () => { + const f = await fixture() + const read = vi.fn(async () => emptyState) + const listener = new StateListener(f.ctx, f.session.id, f.abort.signal, read) + const states = listener.observeStates() + await states.next() + const pending = tracked(states.next()) + f.ctx.sessions.create(SessionId('unrelated')) + expect(read).toHaveBeenCalledOnce() + await f.ctx.fiber.dispose() + expect(await pending).toEqual({ done: true, value: undefined }) + listener[Symbol.dispose]() + }) + + it('invalidates for each Agent lifecycle notification', async () => { + const f = await fixture() + f.live('idle') + const agent = f.get()! + using listener = new StateListener(f.ctx, f.session.id, f.abort.signal, async () => emptyState) + const states = listener.observeStates() + await states.next() + for (const emit of [ + () => { f.ctx.emit('agent/status', { agent, status: 'running' }) }, + () => { f.ctx.emit('agent/created', { agent, source: 'startup' }) }, + () => { f.ctx.emit('agent/disposed', { agent }) }, + ]) { + const pending = tracked(states.next()) + emit() + expect(await pending).toMatchObject({ done: false, value: { state: emptyState } }) + } + await states.return(undefined) + }) + + it('rejects cancelled construction and contains setup failure by removing abort listeners', async () => { + const f = await fixture() + f.abort.abort() + expect(() => new StateListener(f.ctx, f.session.id, f.abort.signal, async () => emptyState)).toThrow() + const abort = cancellation() + const remove = vi.spyOn(abort.signal, 'removeEventListener') + vi.spyOn(f.ctx, 'on').mockImplementation(() => { throw new Error('registration failed') }) + expect(() => new StateListener(f.ctx, f.session.id, abort.signal, async () => emptyState)).toThrow('registration failed') + expect(remove).toHaveBeenCalledWith('abort', expect.any(Function)) + }) +}) diff --git a/packages/api/session-controller/tests/subagent-catalog.host.spec.ts b/packages/api/session-controller/tests/subagent-catalog.host.spec.ts index 9534b8b66d..36216a1f1c 100644 --- a/packages/api/session-controller/tests/subagent-catalog.host.spec.ts +++ b/packages/api/session-controller/tests/subagent-catalog.host.spec.ts @@ -105,7 +105,7 @@ describe('SessionController subagent catalog', () => { kind: 'sequenced', values: { subagentCatalog: [{ id: CHILD, mode: 'continuable', label: 'worker' }] }, }) expect(stat).toHaveBeenCalledWith(PARENT, { signal }) - expect(observe).toHaveBeenCalledWith(PARENT, { signal }) + expect(observe).toHaveBeenCalledWith(PARENT, { signal, projectionMode: 'all' }) expect(open).toHaveBeenCalledWith(PARENT, 'read', { signal }) expect(resume).not.toHaveBeenCalled() expect(ctx.sessions.get(PARENT)).toBeUndefined() diff --git a/packages/api/session-controller/tests/test-remote.ts b/packages/api/session-controller/tests/test-remote.ts index 114e15734d..145b48f5c3 100644 --- a/packages/api/session-controller/tests/test-remote.ts +++ b/packages/api/session-controller/tests/test-remote.ts @@ -51,7 +51,7 @@ import type { SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionWorkspacePathApplication, - SessionPage, + SessionEventsPage, SessionPageRequest, SessionPromptRequest, SessionPromptValue, @@ -66,7 +66,7 @@ import type { SessionUpdateQueueValue, } from '../src/types.ts' -/** Direct test face matching the generated `ctx.remote.session` unary methods. */ +/** Direct test face for the generated `ctx.remote.session` unary methods these tests exercise. */ export interface TestSessionRemote { workspacePathApplications( request: { readonly path: string }, signal?: AbortSignal, @@ -87,7 +87,7 @@ export interface TestSessionRemote { request: SessionOpenWorkspacePathRequest, signal?: AbortSignal, ): Promise> - page(request: SessionPageRequest, signal?: AbortSignal): Promise> + page(request: SessionPageRequest, signal?: AbortSignal): Promise> projections(request: SessionProjectionsRequest, signal?: AbortSignal): Promise> follow(request: SessionFollowRequest, signal?: AbortSignal): AsyncIterable control(signal?: AbortSignal): AsyncIterable @@ -388,6 +388,7 @@ export async function createSessionTestRemote( signal, ), page: (request, signal = new AbortController().signal) => remoteResult( + // oxlint-disable-next-line typescript/no-deprecated -- Test face keeps the legacy page entry covered. () => direct.page(request, signal), signal, ), diff --git a/packages/api/session-controller/tests/transport.client.spec.ts b/packages/api/session-controller/tests/transport.client.spec.ts index 0ab001db89..5b798792e2 100644 --- a/packages/api/session-controller/tests/transport.client.spec.ts +++ b/packages/api/session-controller/tests/transport.client.spec.ts @@ -25,7 +25,7 @@ import type { SessionFollowFrame, SessionFollowRequest, SessionHistoryRecord, - SessionPage, + SessionEventsPage, SessionPageRequest, SessionWireEvent, } from '../src/types.ts' @@ -44,8 +44,8 @@ function entry(seq: number): SessionEventEntry { return { type: 'event', event: { type: 'turn/start', seq, time: seq, data: { turn: seq } } } } -function page(records: readonly SessionHistoryRecord[], hasMore = false): SessionPage { - return { records, hasMore } +function page(records: readonly SessionHistoryRecord[], hasMore = false): SessionEventsPage { + return { cursor: records.at(-1)?.event?.seq ?? -1, records, hasMore } } function snapshot( @@ -102,7 +102,7 @@ class ScriptedSessionRemote implements SessionTransportRemote { constructor( private readonly generations: FollowGeneration[], - private readonly pages: RemoteResult[], + private readonly pages: RemoteResult[], private readonly controlFrames: readonly SessionControlFrame[] = [], private readonly holdControl = true, ) {} @@ -126,7 +126,7 @@ class ScriptedSessionRemote implements SessionTransportRemote { } } - page(request: SessionPageRequest): Promise> { + page(request: SessionPageRequest): Promise> { this.pageRequests.push(request) const result = this.pages.shift() if (result === undefined) throw new Error('no scripted Session page') @@ -326,7 +326,7 @@ describe('Session Client stream adapters', () => { await stream.open({}) await vi.waitFor(() => { expect(changes).toHaveLength(2) }) - expect(remote.followRequests).toEqual([{ address: ADDRESS, assistantStream: true }]) + expect(remote.followRequests).toEqual([{ address: ADDRESS, activate: true, assistantStream: true }]) expect(changes).toMatchObject([ { type: 'replace', page: { assistantStream: baseline } }, { type: 'assistant-stream', frame }, @@ -382,7 +382,7 @@ describe('Session Client stream adapters', () => { code: 'gateway/internal', message: 'session event stream emitted an entry before its opening cursor', }) - expect(remote.followRequests).toEqual([{ address: ADDRESS, assistantStream: true }]) + expect(remote.followRequests).toEqual([{ address: ADDRESS, activate: true, assistantStream: true }]) } finally { await stream.dispose() } @@ -547,7 +547,7 @@ describe('Session Client stream adapters', () => { await stream.prepend({ beforeSeq: 2, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }) expect(remote.followRequests).toEqual([{ - address: ADDRESS, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 }, + address: ADDRESS, activate: true, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 }, }]) expect(remote.pageRequests).toEqual([ { address: ADDRESS, throughSeq: 4, beforeSeq: 2, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, @@ -585,8 +585,8 @@ describe('Session Client stream adapters', () => { await vi.waitFor(() => { expect(remote.followRequests).toHaveLength(2) }) expect(remote.followRequests).toEqual([ - { address: ADDRESS, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, - { address: ADDRESS, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, + { address: ADDRESS, activate: true, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, + { address: ADDRESS, activate: true, assistantStream: true, maxMessages: 500, turnWindow: { minMessages: 50, minTurns: 2 } }, ]) expect(remote.pageRequests).toEqual([]) expect(changes.map(change => change.type)).toEqual(['replace', 'append', 'replace']) @@ -616,8 +616,8 @@ describe('Session Client stream adapters', () => { finish.resolve(undefined) await vi.waitFor(() => { expect(remote.followRequests).toHaveLength(2) }) expect(remote.followRequests).toEqual([ - { address: ADDRESS, assistantStream: true }, - { address: ADDRESS, assistantStream: true }, + { address: ADDRESS, activate: true, assistantStream: true }, + { address: ADDRESS, activate: true, assistantStream: true }, ]) expect(remote.pageRequests).toEqual([]) await stream.dispose() diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts index e48b114c91..8a3df2ae43 100644 --- a/packages/api/session-controller/tests/transport.host.spec.ts +++ b/packages/api/session-controller/tests/transport.host.spec.ts @@ -5,8 +5,9 @@ import type { Session, SessionEvent, SessionHeader, SurfaceIntent } from '@deeps import type { SessionObservation } from '@deepseek-ai/dsh-session-query' import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent' import { subagentIdentityProjectionDefinition } from '@deepseek-ai/dsh-subagent/src/projection.ts' -import { describe, expect, it, vi } from 'vitest' -import { SessionHistoryController } from '../src/history.ts' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { HistoryController } from '../src/history/controller.ts' +import { WebController } from '../src/web/controller.ts' import { installSessionReadTestServices, testSessionPersistence } from './test-remote.ts' const signal = (): AbortSignal => new AbortController().signal @@ -72,22 +73,39 @@ function deferred(): Deferred { return { promise, resolve } } -async function setup(): Promise<{ ctx: Context; transport: SessionHistoryController }> { +const roots = new Set() +afterEach(async () => { + await Promise.all([...roots].map(ctx => ctx.fiber.dispose())) + roots.clear() +}) + +function controllers( + ctx: Context, promote: (observation: SessionObservation) => void = (observation) => { observation[Symbol.dispose]() }, +): { + history: HistoryController + web: WebController +} { + roots.add(ctx.root) + installSessionReadTestServices(ctx) + const history = new HistoryController(ctx) + return { history, web: new WebController(ctx, history, promote) } +} + +async function setup(): Promise<{ ctx: Context; history: HistoryController; web: WebController }> { const ctx = new Context() await ctx.plugin(SessionStore) installSessionReadTestServices(ctx) await ctx.sessionProjections.register(subagentIdentityProjectionDefinition) - const transport = new SessionHistoryController(ctx, (observation) => { observation[Symbol.dispose]() }) - return { ctx, transport } + return { ctx, ...controllers(ctx) } } -describe('SessionHistoryController', () => { +describe('Session history and Web follow', () => { it('opens at the current cursor and follows later events from an ordinary Session', async () => { - const { ctx, transport } = await setup() + const { ctx, history, web } = await setup() const session = ctx.sessions.create(SessionId('ordinary'), { meta: { cwd: '/workspace' } }) session.append('turn/start', { turn: 1 }) const abort = new AbortController() - const iterator = transport.follow( + const iterator = web.follow( { address: { kind: 'session', sessionId: session.id } }, abort.signal, )[Symbol.asyncIterator]() @@ -99,7 +117,7 @@ describe('SessionHistoryController', () => { value: { type: 'event', event: { type: 'turn/end', seq: 1 } }, }) - const page = await transport.page( + const page = await history.events( { address: { kind: 'session', sessionId: session.id }, throughSeq: 1 }, new AbortController().signal, ) @@ -113,16 +131,16 @@ describe('SessionHistoryController', () => { const ctx = new Context() await ctx.plugin(SessionStore) installSessionReadTestServices(ctx) - let transport!: SessionHistoryController + let web!: WebController const owner = ctx.plugin(Object.assign( (inner: Context) => { - transport = new SessionHistoryController(inner, (observation) => { observation[Symbol.dispose]() }) + web = controllers(inner).web }, { inject: ['sessions', 'sessionQuery'] }, )) await owner.await() const session = ctx.sessions.create(SessionId('controller-unload'), { meta: { cwd: '/workspace' } }) - const iterator = transport.follow( + const iterator = web.follow( { address: { kind: 'session', sessionId: session.id } }, new AbortController().signal, )[Symbol.asyncIterator]() @@ -138,13 +156,13 @@ describe('SessionHistoryController', () => { }) it('reconnects with a complete replacement snapshot before later live events', async () => { - const { ctx, transport } = await setup() + const { ctx, web } = await setup() const session = ctx.sessions.create(SessionId('resume'), { meta: { cwd: '/workspace' } }) session.append('turn/start', { turn: 1 }) session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) session.append('turn/start', { turn: 2 }) const abort = new AbortController() - const iterator = transport.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, }, abort.signal)[Symbol.asyncIterator]() @@ -168,7 +186,7 @@ describe('SessionHistoryController', () => { }) it('subscribes before a cold read and ignores unrelated and replayed buffered events', async () => { - const { ctx, transport } = await setup() + const { ctx, web } = await setup() const sessionId = SessionId('cold-race') const header: SessionHeader = { version: SESSION_FORMAT_VERSION, @@ -187,7 +205,7 @@ describe('SessionHistoryController', () => { inspect: () => inspected.promise, }) as never) const abort = new AbortController() - const iterator = transport.follow({ address: { kind: 'session', sessionId } }, abort.signal) + const iterator = web.follow({ address: { kind: 'session', sessionId } }, abort.signal) [Symbol.asyncIterator]() const opening = iterator.next() @@ -220,9 +238,9 @@ describe('SessionHistoryController', () => { } const observed = deferred() ctx.provide('sessionQuery', { observeSession: () => observed.promise } as never) - const transport = new SessionHistoryController(ctx, vi.fn()) + const { web } = controllers(ctx, vi.fn()) const abort = new AbortController() - const iterator = transport.follow({ address: { kind: 'session', sessionId } }, abort.signal) + const iterator = web.follow({ address: { kind: 'session', sessionId } }, abort.signal) [Symbol.asyncIterator]() const opening = iterator.next() @@ -256,11 +274,11 @@ describe('SessionHistoryController', () => { const ctx = new Context() await ctx.plugin(SessionStore) installSessionReadTestServices(ctx) - let transport!: SessionHistoryController + let web!: WebController let agentCtx!: Context await ctx.plugin(Object.assign( (inner: Context) => { - transport = new SessionHistoryController(inner, (observation) => { observation[Symbol.dispose]() }) + web = controllers(inner).web }, { inject: ['sessions', 'sessionQuery'] }, )) @@ -279,7 +297,7 @@ describe('SessionHistoryController', () => { const seed = [event('fixture/start', SessionSeq(0))] cold(ctx, header, seed) const abort = new AbortController() - const iterator = transport.follow({ address: { kind: 'session', sessionId } }, abort.signal) + const iterator = web.follow({ address: { kind: 'session', sessionId } }, abort.signal) [Symbol.asyncIterator]() await expect(iterator.next()).resolves.toMatchObject({ done: false, value: { type: 'snapshot', cursor: 0 } }) @@ -322,7 +340,7 @@ describe('SessionHistoryController', () => { isSeeded: false, } cold(replay.ctx, replayHeader, [event('fixture/start', SessionSeq(0)), event('fixture/gap', SessionSeq(2))]) - const replayed = replay.transport.follow({ + const replayed = replay.web.follow({ address: { kind: 'session', sessionId: replayId }, }, signal())[Symbol.asyncIterator]() await expect(replayed.next()).rejects.toMatchObject({ code: 'SESSION_QUERY_CORRUPT_SESSION' }) @@ -331,7 +349,7 @@ describe('SessionHistoryController', () => { const session = live.ctx.sessions.create(SessionId('live-gap'), { meta: { cwd: '/workspace' } }) append(session, 'fixture/start', {}) live.ctx.provide('agents', { get: () => ({ id: session.id }) } as never) - const followed = live.transport.follow({ + const followed = live.web.follow({ address: { kind: 'session', sessionId: session.id }, }, signal())[Symbol.asyncIterator]() await expect(followed.next()).resolves.toMatchObject({ done: false, value: { type: 'snapshot', cursor: 0 } }) @@ -345,21 +363,21 @@ describe('SessionHistoryController', () => { }) it('opens an empty source at cursor -1', async () => { - const { ctx, transport } = await setup() + const { ctx, history, web } = await setup() const session = ctx.sessions.create(SessionId('empty-follow'), { meta: { cwd: '/workspace' } }) const abort = new AbortController() - const iterator = transport.follow({ + const iterator = web.follow({ address: { kind: 'session', sessionId: session.id }, }, abort.signal)[Symbol.asyncIterator]() await expect(iterator.next()).resolves.toMatchObject({ done: false, value: { type: 'snapshot', cursor: -1 } }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'session', sessionId: session.id }, throughSeq: -1, }, signal())).resolves.toMatchObject({ records: [], hasMore: false }) abort.abort() await expect(iterator.next()).resolves.toMatchObject({ done: true }) }) - it('publishes an empty projection baseline when the query has no registry', async () => { + it('fails explicitly when a projected observation omits its baseline', async () => { const ctx = new Context() await ctx.plugin(SessionStore) const sessionId = SessionId('projectionless-follow') @@ -380,19 +398,83 @@ describe('SessionHistoryController', () => { retain: vi.fn(), [Symbol.dispose]: vi.fn(), } satisfies SessionObservation), } as never) - const history = new SessionHistoryController(ctx, vi.fn()) + const { web } = controllers(ctx, vi.fn()) const abort = new AbortController() - const iterator = history.follow({ address: { kind: 'session', sessionId } }, abort.signal) + const iterator = web.follow({ address: { kind: 'session', sessionId } }, abort.signal) [Symbol.asyncIterator]() - await expect(iterator.next()).resolves.toMatchObject({ - value: { type: 'snapshot', projections: { asOfSeq: -1, values: {} } }, - }) + await expect(iterator.next()).rejects.toMatchObject({ code: 'session/projections-unavailable' }) abort.abort() await expect(iterator.next()).resolves.toMatchObject({ done: true }) await ctx.fiber.dispose() }) + it('does not activate a prepared Session when the request omits activate', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + const sessionId = SessionId('passive-activation-default') + const header: SessionHeader = { + version: SESSION_FORMAT_VERSION, id: sessionId, createdAt: 1, cwd: '/workspace', isSeeded: false, + } + const disposeSource = vi.fn() + const source: SessionObservation = { + source: 'prepared', + header, + inheritedEventCount: SessionLogOffset(0), + events: [], + cursor: -1, + projections: { asOfSeq: -1, values: {} }, + retain: () => source, + [Symbol.dispose]: disposeSource, + } + ctx.provide('sessionQuery', { observeSession: () => Promise.resolve(source) } as never) + const promote = vi.fn() + const { web } = controllers(ctx, promote) + const abort = new AbortController() + const iterator = web.follow({ address: { kind: 'session', sessionId } }, abort.signal)[Symbol.asyncIterator]() + await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'snapshot' } }) + expect(promote).not.toHaveBeenCalled() + abort.abort() + await expect(iterator.next()).resolves.toMatchObject({ done: true }) + expect(disposeSource).toHaveBeenCalled() + await ctx.fiber.dispose() + }) + + it('starts activation for a consumer that stops after the opening snapshot', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + const sessionId = SessionId('activation-after-opening') + const header: SessionHeader = { + version: SESSION_FORMAT_VERSION, id: sessionId, createdAt: 1, cwd: '/workspace', isSeeded: false, + } + const disposed: string[] = [] + const promotion: SessionObservation = { + source: 'prepared', + header, + inheritedEventCount: SessionLogOffset(0), + events: [], + cursor: -1, + projections: { asOfSeq: -1, values: {} }, + retain: vi.fn(), + [Symbol.dispose]: () => { disposed.push('promotion') }, + } + const source: SessionObservation = { + ...promotion, + retain: () => promotion, + [Symbol.dispose]: () => { disposed.push('source') }, + } + ctx.provide('sessionQuery', { observeSession: () => Promise.resolve(source) } as never) + const promote = vi.fn((observation: SessionObservation) => { observation[Symbol.dispose]() }) + const { web } = controllers(ctx, promote) + const iterator = web.follow({ address: { kind: 'session', sessionId }, activate: true }, signal()) + [Symbol.asyncIterator]() + await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'snapshot' } }) + await iterator.return?.(undefined) + expect(promote).toHaveBeenCalledOnce() + expect(disposed).toContain('promotion') + await ctx.fiber.dispose() + }) + it('disposes a retained promotion when background activation rejects synchronously', async () => { const ctx = new Context() await ctx.plugin(SessionStore) @@ -412,18 +494,17 @@ describe('SessionHistoryController', () => { ctx.provide('sessionQuery', { observeSession: () => Promise.resolve(source), } as never) - const history = new SessionHistoryController(ctx, () => { throw new Error('activation failed') }) - const iterator = history.follow({ address: { kind: 'session', sessionId } }, signal()) + const { web } = controllers(ctx, () => { throw new Error('activation failed') }) + const iterator = web.follow({ address: { kind: 'session', sessionId }, activate: true }, signal()) [Symbol.asyncIterator]() - await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'snapshot' } }) await expect(iterator.next()).rejects.toThrow('activation failed') expect(disposePromotion).toHaveBeenCalledOnce() await ctx.fiber.dispose() }) it('requires the durable parent and mode for a direct subagent address', async () => { - const { ctx, transport } = await setup() + const { ctx, history } = await setup() const parentSessionId = SessionId('parent') const childSessionId = SessionId('child') ctx.sessions.create(parentSessionId, { meta: { cwd: '/workspace' } }) @@ -437,7 +518,7 @@ describe('SessionHistoryController', () => { })) const signal = new AbortController().signal - await expect(transport.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId, @@ -448,17 +529,17 @@ describe('SessionHistoryController', () => { }, signal)).resolves.toMatchObject({ records: [{ type: 'event', event: { type: 'subagent/descriptor' } }], }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId, childSessionId, mode: 'unknown' }, throughSeq: 0, }, signal)).resolves.toMatchObject({ records: [{ type: 'event', event: { type: 'subagent/descriptor' } }], }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId: SessionId('other-parent'), childSessionId, mode: 'unknown' }, throughSeq: 0, }, signal)).rejects.toMatchObject({ code: 'subagent/unauthorized' }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId: SessionId('other-parent'), @@ -467,7 +548,7 @@ describe('SessionHistoryController', () => { }, throughSeq: 0, }, signal)).rejects.toMatchObject({ code: 'subagent/unauthorized' }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId, @@ -476,14 +557,14 @@ describe('SessionHistoryController', () => { }, throughSeq: 0, }, signal)).rejects.toMatchObject({ code: 'subagent/unauthorized' }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'session', sessionId: childSessionId }, throughSeq: 0, }, signal)).rejects.toMatchObject({ code: 'session/agent-busy' }) }) it('preserves a cold inspection failure for the Gateway error branch', async () => { - const { ctx, transport } = await setup() + const { ctx, history } = await setup() const sessionId = SessionId('corrupt-cold') const failure = new Error('cold log is corrupt') const header: SessionHeader = { version: SESSION_FORMAT_VERSION, id: sessionId, createdAt: 1, isSeeded: false, cwd: '/workspace' } @@ -492,7 +573,7 @@ describe('SessionHistoryController', () => { inspect: () => Promise.reject(failure), }) as never) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'session', sessionId }, throughSeq: -1, }, new AbortController().signal)).rejects.toMatchObject({ @@ -502,7 +583,7 @@ describe('SessionHistoryController', () => { }) it('rejects malformed page and follow cursors at the service boundary', async () => { - const { ctx, transport } = await setup() + const { ctx, history, web } = await setup() const session = ctx.sessions.create(SessionId('validation'), { meta: { cwd: '/workspace' } }) const address = { kind: 'session' as const, sessionId: session.id } for (const request of [ @@ -521,9 +602,9 @@ describe('SessionHistoryController', () => { { address, throughSeq: -1, turnWindow: { minMessages: 50, minTurns: 0 } }, { address, throughSeq: -1, turnWindow: { minMessages: 50, minTurns: 1.5 } }, ]) { - await expect(transport.page(request, signal())).rejects.toMatchObject({ code: 'gateway/bad-request' }) + await expect(history.events(request, signal())).rejects.toMatchObject({ code: 'gateway/bad-request' }) } - await expect(transport.page({ address, throughSeq: 0 }, signal())) + await expect(history.events({ address, throughSeq: 0 }, signal())) .rejects.toMatchObject({ code: 'gateway/bad-request' }) const corrupt = await setup() @@ -533,11 +614,11 @@ describe('SessionHistoryController', () => { { version: SESSION_FORMAT_VERSION, id: corruptId, createdAt: 1, cwd: '/workspace', isSeeded: false }, [event('fixture/start', SessionSeq(0)), event('fixture/gap', SessionSeq(2))], ) - await expect(corrupt.transport.page({ + await expect(corrupt.history.events({ address: { kind: 'session', sessionId: corruptId }, throughSeq: 1, }, signal())).rejects.toMatchObject({ code: 'SESSION_QUERY_CORRUPT_SESSION' }) for (const maxMessages of [0, 0.5]) { - const iterator = transport.follow({ address, maxMessages }, signal())[Symbol.asyncIterator]() + const iterator = web.follow({ address, maxMessages }, signal())[Symbol.asyncIterator]() await expect(iterator.next()).rejects.toMatchObject({ code: 'gateway/bad-request' }) } for (const turnWindow of [ @@ -547,15 +628,15 @@ describe('SessionHistoryController', () => { { minMessages: 50, minTurns: 0 }, { minMessages: 50, minTurns: 1.5 }, ]) { - const iterator = transport.follow({ address, turnWindow }, signal())[Symbol.asyncIterator]() + const iterator = web.follow({ address, turnWindow }, signal())[Symbol.asyncIterator]() await expect(iterator.next()).rejects.toMatchObject({ code: 'gateway/bad-request' }) } }) it('reports missing ordinary and subagent sources without fabricating inspection failures', async () => { - const { ctx, transport } = await setup() + const { ctx, history } = await setup() const ordinary = { kind: 'session' as const, sessionId: SessionId('missing') } - await expect(transport.page({ address: ordinary, throughSeq: -1 }, signal())) + await expect(history.events({ address: ordinary, throughSeq: -1 }, signal())) .rejects.toMatchObject({ code: 'session/not-found' }) const inspect = vi.fn(() => Promise.resolve(undefined)) @@ -565,9 +646,9 @@ describe('SessionHistoryController', () => { stat, inspect, }) as never) - await expect(transport.page({ address: ordinary, throughSeq: -1 }, signal())) + await expect(history.events({ address: ordinary, throughSeq: -1 }, signal())) .rejects.toMatchObject({ code: 'session/not-found' }) - await expect(transport.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId: SessionId('parent'), @@ -594,7 +675,7 @@ describe('SessionHistoryController', () => { events: [], }), }) as never) - await expect(first.transport.page({ address, throughSeq: -1 }, signal())) + await expect(first.history.events({ address, throughSeq: -1 }, signal())) .rejects.toMatchObject({ code: 'session/not-found' }) const second = await setup() @@ -608,7 +689,7 @@ describe('SessionHistoryController', () => { events: [], }), }) as never) - await expect(second.transport.page({ address, throughSeq: -1 }, signal())) + await expect(second.history.events({ address, throughSeq: -1 }, signal())) .rejects.toMatchObject({ code: 'session/not-found' }) }) @@ -623,7 +704,7 @@ describe('SessionHistoryController', () => { isSeeded: false, } cold(ordinaryBench.ctx, ordinaryHeader, [event('turn/start', SessionSeq(0), { turn: 1 })]) - await expect(ordinaryBench.transport.page({ + await expect(ordinaryBench.history.events({ address: { kind: 'session', sessionId: ordinaryId }, throughSeq: 0, }, signal())).resolves.toMatchObject({ @@ -649,18 +730,18 @@ describe('SessionHistoryController', () => { } const missing = await setup() cold(missing.ctx, childHeader, []) - await expect(missing.transport.page({ address: childAddress, throughSeq: -1 }, signal())) + await expect(missing.history.events({ address: childAddress, throughSeq: -1 }, signal())) .rejects.toMatchObject({ code: 'subagent/catalog-diagnostic', details: { reason: 'corrupt' } }) const corrupt = await setup() cold(corrupt.ctx, childHeader, [event('subagent/descriptor', SessionSeq(0), { version: 'bad' })]) - await expect(corrupt.transport.page({ address: childAddress, throughSeq: 0 }, signal())) + await expect(corrupt.history.events({ address: childAddress, throughSeq: 0 }, signal())) .rejects.toMatchObject({ code: 'subagent/catalog-diagnostic', details: { reason: 'corrupt' } }) const ordinaryChild = await setup() const { origin: _origin, ...ordinaryChildHeader } = childHeader cold(ordinaryChild.ctx, ordinaryChildHeader, []) - await expect(ordinaryChild.transport.page({ address: childAddress, throughSeq: -1 }, signal())) + await expect(ordinaryChild.history.events({ address: childAddress, throughSeq: -1 }, signal())) .rejects.toMatchObject({ code: 'subagent/unauthorized' }) }) @@ -689,9 +770,9 @@ describe('SessionHistoryController', () => { retain: vi.fn(), [Symbol.dispose]: vi.fn(), } as unknown as SessionObservation), } as never) - const history = new SessionHistoryController(ctx, vi.fn()) + const { history } = controllers(ctx, vi.fn()) - await expect(history.page({ + await expect(history.events({ address: { kind: 'subagent', parentSessionId, @@ -710,7 +791,7 @@ describe('SessionHistoryController', () => { const session = ordinary.ctx.sessions.create(SessionId('projected'), { meta: { cwd: '/workspace' } }) session.append('turn/start', { turn: 1 }) const ordinarySnapshot = vi.spyOn(ordinary.ctx.sessionProjections, 'snapshot') - const ordinaryPage = await ordinary.transport.page({ + const ordinaryPage = await ordinary.history.events({ address: { kind: 'session', sessionId: session.id }, throughSeq: 0, }, signal()) @@ -727,7 +808,7 @@ describe('SessionHistoryController', () => { mode: 'continuable', provider: 'test', label: 'child', })) const childSnapshot = vi.spyOn(child.ctx.sessionProjections, 'snapshot') - const page = await child.transport.page({ + const page = await child.history.events({ address: { kind: 'subagent', parentSessionId, @@ -741,7 +822,7 @@ describe('SessionHistoryController', () => { }) it('keeps message-aligned pagination contiguous across replacement source-event references', async () => { - const { ctx, transport } = await setup() + const { ctx, history } = await setup() const session = ctx.sessions.create(SessionId('pagination'), { meta: { cwd: '/workspace' } }) session.append('turn/start', { turn: 1 }) append(session, 'user/message', { content: [], source: { kind: 'user' } }, { surfaceOp: 'append' }) @@ -754,27 +835,27 @@ describe('SessionHistoryController', () => { sourceEventSeqs: [SessionSeq(1), firstReply.seq, SessionSeq(3), SessionSeq(4), summary.seq], }) - const page = await transport.page({ + const page = await history.events({ address: { kind: 'session', sessionId: session.id }, throughSeq: replacement.seq, maxMessages: 2, }, signal()) expect(page.records.map(entry => entry.event.seq)) .toEqual([3, 4, 5, replacement.seq]) expect(page.hasMore).toBe(true) - const before = await transport.page({ + const before = await history.events({ address: { kind: 'session', sessionId: session.id }, throughSeq: replacement.seq, beforeSeq: 3, maxMessages: 1, }, signal()) expect(before.records.map(entry => entry.event.seq)).toEqual([2]) }) it('keeps cited source events in the page that owns their appended message', async () => { - const { ctx, transport } = await setup() + const { ctx, history } = await setup() const session = ctx.sessions.create(SessionId('pagination-sources'), { meta: { cwd: '/workspace' } }) const source = append(session, 'fixture/source', {}) append(session, 'user/message', { content: [], source: { kind: 'plugin' } }, { surfaceOp: 'append', sourceEventSeqs: [source.seq], }) - const page = await transport.page({ + const page = await history.events({ address: { kind: 'session', sessionId: session.id }, throughSeq: 1, maxMessages: 1, }, signal()) expect(page.records.map(entry => entry.event.seq)).toEqual([0, 1]) diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json index 8a5fa75166..acadf82099 100644 --- a/packages/api/session-controller/tsconfig.host.json +++ b/packages/api/session-controller/tsconfig.host.json @@ -16,12 +16,24 @@ "src/control.ts", "src/file-references.ts", "src/history.ts", + "src/history/controller.ts", + "src/history/listener.ts", + "src/history/assistant-stream.ts", + "src/state/controller.ts", + "src/state/listener.ts", + "src/web/controller.ts", "src/list.ts", "src/media-references.ts", "src/archived-session-gate.ts", "src/skill-catalog.ts" ], "references": [ + { + "path": "../gateway/tsconfig.host.json" + }, + { + "path": "../../util/timeout" + }, { "path": "../../../vendor/cordis" }, diff --git a/packages/api/settings-controller/package.json b/packages/api/settings-controller/package.json index 1a01d513c4..e424a9e808 100644 --- a/packages/api/settings-controller/package.json +++ b/packages/api/settings-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-settings-controller", "description": "Remote owner for the configuration surfaces over the settings-domain seams", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/terminal-controller/package.json b/packages/api/terminal-controller/package.json index a7e7ca3a0e..84a53b5df6 100644 --- a/packages/api/terminal-controller/package.json +++ b/packages/api/terminal-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-terminal-controller", "description": "Session-owned interactive terminals with shell discovery, screen recovery and typed Remote control", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/workspace-controller/package.json b/packages/api/workspace-controller/package.json index 802e26fb0e..8a7363da4f 100644 --- a/packages/api/workspace-controller/package.json +++ b/packages/api/workspace-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-workspace-controller", "description": "Workspace Remote commands and reconnect-safe state transport", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/api/workspace-files/package.json b/packages/api/workspace-files/package.json index 4d1e0ca86a..5170995310 100644 --- a/packages/api/workspace-files/package.json +++ b/packages/api/workspace-files/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-workspace-files", "description": "Workspace file service and Client resource provider: bounded reads, directory listing, and live metadata over the workspaceFiles Remote namespace", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/attachment/attachment-local/README.i18n.yaml b/packages/attachment/attachment-local/README.i18n.yaml index be08b2fdbd..2caf5e3785 100644 --- a/packages/attachment/attachment-local/README.i18n.yaml +++ b/packages/attachment/attachment-local/README.i18n.yaml @@ -36,8 +36,8 @@ en: dcd9857653645420 zh: a27259a09f17465d /deepseek-ai-dsh-attachment-local/understand-the-implementation/write-and-read-paths: - en: 62ea104a00a7fdb8 - zh: b08575274ca244b4 + en: 4cbbe8a1466ed46f + zh: 49d2d118501867d3 /deepseek-ai-dsh-attachment-local/understand-the-implementation/source-map: en: 05af85aa85934d01 zh: 1c89e80d496dc0a3 diff --git a/packages/attachment/attachment-local/README.md b/packages/attachment/attachment-local/README.md index 4844be3670..b27ac0c75a 100644 --- a/packages/attachment/attachment-local/README.md +++ b/packages/attachment/attachment-local/README.md @@ -83,6 +83,8 @@ This section explains the durability and verification design behind the storage, Objects land at `/attachments/v1/objects//`; equal bytes deduplicate to one object and one `sha256:` id. Before the first write, the process syncs every ancestor directory of the home down to the filesystem root once, so a directory another process created but has not yet synced is never mistaken for a safe boundary. Writes then stage bytes in `v1/tmp`, sync the temporary file, publish with an atomic exclusive hard link, and sync the publication directories — on Windows, filesystem metadata journaling owns entry durability. Once the save resolves, the reported reference is durable. +Image reads receive a complete reference with a canonical `sha256:` ID, derive the object path within this storage tree, verify the complete digest, and probe the image header. The actual format, byte length, width, and height must match the supplied reference. The returned reference preserves optional `name` and `originalDimensions` as caller-supplied display information; these fields are not verified against the object. Reads neither consult Session history nor reapply admission limits; a missing object or failed verification rejects the read. + Admission accepts up to 20 images and 200 MiB of source bytes per message; one source may use up to 50 MiB, 64 million pixels, and 65,535 pixels per side. It applies orientation, removes metadata and color profiles, and normalizes under a 2048×2048 total-pixel budget, an 8192-pixel long edge, and a 4 MiB encoded-byte target. Extreme aspect ratios therefore retain their short-edge resolution. Clean single-frame 8-bit sRGB/sRGBA PNG, JPEG, or WebP input already within those limits passes through byte-identically; GIF, animation, metadata, orientation, 16-bit PNG, and incompatible color spaces force conversion. Request versions live below `/cache/attachments/request-images/`, resolved by `dshCachePath`; an explicit `dshHome` setting applies to both cache and durable storage. Clearing this cache between requests preserves durable attachments, and later reads regenerate the variants. `readImageRequest` scales without enlargement to the route-chosen target, resizing by the long edge only so the encoder derives the short edge as the route predicts, then applies a separate encoded-byte target through the same alpha routing and quality ladder. Its cache identity includes the attachment id, transform version, target dimensions, byte target, and fixed encoder settings; cached bytes are header-probed for format, 8-bit sRGB/sRGBA, dimensions, and alpha facts, and a mismatch regenerates the entry. Concurrent callers share one transform and cache write, while cancellation stops shared work only when no waiter remains. `imageHostPath` derives the normalized object's host path, and the mounted filesystem may map that path into its execution world without writing it to durable history. diff --git a/packages/attachment/attachment-local/README.zh.md b/packages/attachment/attachment-local/README.zh.md index a079785984..a0663aaebe 100644 --- a/packages/attachment/attachment-local/README.zh.md +++ b/packages/attachment/attachment-local/README.zh.md @@ -83,6 +83,8 @@ kind: "package-reference" 对象存放在 `/attachments/v1/objects//`；相同字节会去重为同一个对象和同一个 `sha256:` 标识符。首次写入前，进程会把 home 的每个祖先目录逐级同步到文件系统根目录，因此绝不会把另一个进程已创建但尚未同步的目录误认为安全边界。随后，写入过程把字节暂存到 `v1/tmp`、同步临时文件、以原子且排他的硬链接发布，并同步发布目录——在 Windows 上，文件系统元数据日志负责目录项持久性。保存操作完成后，返回的引用已具备持久性。 +图片读取接收包含规范 `sha256:` ID 的完整引用，在该存储目录内推导对象路径，校验完整摘要，并探测图片文件头。实际格式、字节数、宽度和高度必须与传入引用一致。返回的引用把可选的 `name` 和 `originalDimensions` 作为调用方提交的显示信息原样保留，不根据对象校验这两个字段。读取不查询 Session 历史，也不重新应用准入限制；对象缺失或校验失败都会拒绝读取。 + 准入允许每条消息最多 20 张图片与 200 MiB 源字节；单个源图最多 50 MiB、6400 万像素与单边 65,535 像素。系统应用方向、移除元数据与色彩配置，并把规范化结果限制在 2048×2048 总像素预算、8192 像素长边和 4 MiB 编码字节目标内，因此，即使宽高比极端，图片也会保留短边分辨率。已经满足限制的干净、单帧、8-bit sRGB/sRGBA PNG、JPEG 或 WebP 会逐字节直通；GIF、动画、元数据、方向、16-bit PNG 与不兼容色彩空间会触发转换。 请求版本位于由 `dshCachePath` 解析的 `/cache/attachments/request-images/`；显式 `dshHome` 设置同时适用于缓存与持久存储。在两次请求之间清空此缓存会保留持久附件，后续读取会重新生成请求版本。`readImageRequest` 在不放大的前提下缩放到路由选定的目标尺寸，缩放只按长边给定，短边由编码器按路由预测的方式推出，随后通过相同的 alpha 路由与质量阶梯应用独立编码字节目标。缓存身份包含附件 id、变换版本、目标尺寸、字节目标与固定编码参数；缓存字节会先通过文件头探测格式、8-bit sRGB/sRGBA、尺寸与 alpha 信息，不匹配时重新生成。并发调用方共享一次变换与缓存写入，且只在没有等待方时由取消停止共享工作。`imageHostPath` 派生规范化对象的宿主路径，挂载的文件系统可以把该路径映射进执行世界，而不会写入持久历史。 diff --git a/packages/attachment/attachment-local/package.json b/packages/attachment/attachment-local/package.json index 6ad5b54083..8e7071c71d 100644 --- a/packages/attachment/attachment-local/package.json +++ b/packages/attachment/attachment-local/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-attachment-local", "description": "Private content-addressed DSH_HOME attachment storage", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/attachment/attachment-local/src/store.ts b/packages/attachment/attachment-local/src/store.ts index 7fab679e34..88ab2c9d27 100644 --- a/packages/attachment/attachment-local/src/store.ts +++ b/packages/attachment/attachment-local/src/store.ts @@ -423,7 +423,7 @@ export async function saveImageFile( /** * Read and verify one content-addressed image. * @param root - absolute `DSH_HOME/attachments/v1` root. - * @param ref - reference recorded in the session log. + * @param ref - supplied image reference; display fields are returned unchanged. * @param signal - optional cancellation for filesystem and verification work. * @returns verified bytes and reference. * @throws the signal reason when aborted, or an AttachmentError when verification fails. diff --git a/packages/attachment/attachment-local/tests/store.spec.ts b/packages/attachment/attachment-local/tests/store.spec.ts index 82c2b9f3ba..6e7ff4b011 100644 --- a/packages/attachment/attachment-local/tests/store.spec.ts +++ b/packages/attachment/attachment-local/tests/store.spec.ts @@ -148,6 +148,21 @@ describe('local attachment store', () => { await expect(readImageFile(storageRoot, first)).resolves.toEqual({ ref: first, data: PNG }) }) + it.each([ + { mediaType: 'image/jpeg' }, { bytes: PNG.byteLength + 1 }, { width: 2 }, { height: 2 }, + ] as const)('rejects supplied metadata that differs from stored bytes: %j', async (mismatch) => { + const storageRoot = await root() + const saved = await saveImageFile(storageRoot, { data: PNG, mediaType: 'image/png' }, LIMITS, POLICY) + await expect(readImageFile(storageRoot, { ...saved, ...mismatch })).rejects.toMatchObject({ code: 'ATTACHMENT_CORRUPT' }) + }) + + it('preserves supplied display fields while verifying stored image facts', async () => { + const storageRoot = await root() + const saved = await saveImageFile(storageRoot, { data: PNG, mediaType: 'image/png' }, LIMITS, POLICY) + const supplied = { ...saved, name: 'display.png', originalDimensions: { width: 8, height: 8 } } + await expect(readImageFile(storageRoot, supplied)).resolves.toEqual({ ref: supplied, data: PNG }) + }) + it('rejects publication when the supplied digest does not match the staged bytes', async () => { const storageRoot = await root() const target = join(storageRoot, 'objects', '00', 'mismatch') diff --git a/packages/attachment/attachment/README.i18n.yaml b/packages/attachment/attachment/README.i18n.yaml index b2b7ba57ad..125d96125d 100644 --- a/packages/attachment/attachment/README.i18n.yaml +++ b/packages/attachment/attachment/README.i18n.yaml @@ -27,8 +27,8 @@ en: 8a0fa64e84aa4450 zh: ed2ac44ef20250d4 /deepseek-ai-dsh-attachment/use-this-package/reuse-images-across-the-session: - en: c99e4e088be92c4f - zh: 34997ecb9a420d08 + en: ede9266988e20f19 + zh: 6264c601ec62975d /deepseek-ai-dsh-attachment/use-this-package/what-can-go-wrong: en: b35e2f7f17269ae1 zh: 57cf0ef9fee6c7e1 @@ -36,8 +36,8 @@ en: 25d9c7d6c0899d23 zh: ad8380d14810ff1c /deepseek-ai-dsh-attachment/understand-the-implementation/design-decisions: - en: af7deef72fd2fa93 - zh: f217d52ce3971135 + en: 6315b2d1fb12f0ca + zh: c3f99f4c0850fb44 /deepseek-ai-dsh-attachment/understand-the-implementation/service-operations: en: b94d13fe133d8ce6 zh: dd4064d20d510afc diff --git a/packages/attachment/attachment/README.md b/packages/attachment/attachment/README.md index 2acdc13c42..0e0c2bc05f 100644 --- a/packages/attachment/attachment/README.md +++ b/packages/attachment/attachment/README.md @@ -45,7 +45,7 @@ Commands declaring attachment input receive images and generic files in selectio ### Reuse images across the session -Saved normalized images stay in conversation history and are projected into deterministic, route-sized request versions in later turns; after a restart, a resumed session shows and reuses the same images. When the current execution filesystem maps the stored host object, the request descriptor also carries a read-only process path that the model can inspect. When history or a request version is read back, the stored bytes are checked against what was recorded, so a missing, corrupted, or swapped image surfaces as an error rather than wrong bytes. +Saved normalized images stay in conversation history and are projected into deterministic, route-sized request versions in later turns; after a restart, a resumed session shows and reuses the same images. When the current execution filesystem maps the stored host object, the request descriptor also carries a read-only process path that the model can inspect. History image reads and request projections verify the stored object against the full image reference, including its digest, format, byte length, and dimensions. Missing, corrupted, or swapped images fail explicitly. ### What can go wrong @@ -65,7 +65,7 @@ This section explains the design decisions behind the seam and the service opera - **Normalize and persist before event.** Every source is prepared and verified before the batch publishes in order, so the session log never references a partial or failed normalization. - **Immutable and retention-neutral.** Objects are immutable once published; resumed and forked sessions may share them, so reference-aware garbage collection is deferred rather than tied to any one session's deletion. -- **Verify on read.** Reads check bytes and metadata against the logged reference before returning them, and request projections fully decode cached bytes, so a missing, corrupted, or swapped object fails closed. +- **Verify on read.** Reads verify the immutable object against the supplied reference without consulting a Session. Optional display names and pre-normalization dimensions pass through as caller-supplied display information; the stored bytes do not verify these fields. - **Role-neutral image blocks.** The `ImageBlock` content block in `dsh-llm` carries an `ImageAttachmentRef`; provider adapters resolve it into deterministic request versions at an explicit route-chosen target size and byte target, while execution filesystems may map the immutable host object to a model-readable process path. - **Error routing by code.** `AttachmentError` re-implements the `HarnessError` shape instead of extending it because the base lives in `dsh-llm`, which depends on this package; consumers use `isAttachmentError` and route on `code`, never on the prototype chain. - **Files are verbatim, images are normalized.** `saveFile` commits an existing byte array, `saveFileStream` commits bounded chunks with backpressure and cancellation, `readFileStream` verifies and returns bounded chunks, and `fileHostPath` locates the stored object for read-on-demand projection; neither file write path applies admission limits. The image path keeps its separate normalization, limits, and request-version pipeline. The `FileBlock` content block in `dsh-llm` carries a `FileAttachmentRef`, and request assembly projects it to deterministic handle text for every route. diff --git a/packages/attachment/attachment/README.zh.md b/packages/attachment/attachment/README.zh.md index 06cbe5631a..9c9d2c7fb5 100644 --- a/packages/attachment/attachment/README.zh.md +++ b/packages/attachment/attachment/README.zh.md @@ -45,7 +45,7 @@ kind: "package-reference" ### 在整个会话中复用图片 -已保存的规范化图片会保留在对话历史中，并在后续轮次投影为确定性的路由尺寸请求版本；重启后，恢复的会话会显示并复用相同的图片。当前执行文件系统可以映射已存宿主对象时，请求描述符还会携带模型可检查的只读进程路径。回读历史或请求版本时，已存储的字节会与记录的内容比对，因此缺失、损坏或被替换的图片会以错误形式呈现，而不是错误的字节。 +已保存的规范化图片会保留在对话历史中，并在后续轮次投影为确定性的路由尺寸请求版本；重启后，恢复的会话会显示并复用相同的图片。当前执行文件系统可以映射已存宿主对象时，请求描述符还会携带模型可检查的只读进程路径。历史图片读取和请求投影会把存储对象与完整图片引用中的摘要、格式、字节数和尺寸比对。图片缺失、损坏或被替换时会明确失败。 ### 可能出什么问题 @@ -65,7 +65,7 @@ kind: "package-reference" - **事件前完成规范化与持久化。** 每个源图都会在批次按序发布前完成准备与校验，因此会话日志绝不会引用部分完成或规范化失败的对象。 - **不可变且保留策略中立。** 对象一经发布即不可变；恢复和 fork 后的会话可能共享它们，因此引用感知的垃圾回收被推迟，而不是与任何单个会话的删除绑定。 -- **读取时校验。** 读取在返回前把字节和元数据与记录的引用比对，请求投影还会完整解码缓存字节，因此缺失、损坏或被替换的对象不会通过校验。 +- **读取时校验。** 读取会把不可变对象与传入引用比对，无需查询 Session。可选的显示名称和规范化前尺寸作为调用方提交的显示信息原样返回；存储字节不校验这两个字段。 - **角色无关的图片块。** `dsh-llm` 中的 `ImageBlock` 内容块携带 `ImageAttachmentRef`；提供方适配器按路由显式选定的目标尺寸与字节目标把引用解析为确定性请求版本，执行文件系统则可以把不可变宿主对象映射为模型可读的进程路径。 - **按错误码路由。** `AttachmentError` 重新实现 `HarnessError` 的结构而不是继承它，因为基类位于 `dsh-llm`，而后者依赖本包；消费方用 `isAttachmentError` 识别错误并按 `code` 路由，绝不依赖原型链。 - **文件原样，图片规范化。**`saveFile` 提交已有字节数组，`saveFileStream` 以背压和取消语义提交有界分块，`readFileStream` 校验并返回有界分块，`fileHostPath` 定位存储对象供按需读取投影；两种文件写入路径都不设准入限制。图片路径保留其独立的规范化、限额与请求版本流水线。`dsh-llm` 中的 `FileBlock` 内容块承载 `FileAttachmentRef`，请求组装会为每条路由将其投影为确定性的句柄文本。 diff --git a/packages/attachment/attachment/package.json b/packages/attachment/attachment/package.json index 7ef5c29d66..650a98b1ae 100644 --- a/packages/attachment/attachment/package.json +++ b/packages/attachment/attachment/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-attachment", "description": "Durable immutable attachment storage seam for the DeepSeek Harness", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/attachment/attachment/src/index.ts b/packages/attachment/attachment/src/index.ts index ba7f567884..802df0cb6b 100644 --- a/packages/attachment/attachment/src/index.ts +++ b/packages/attachment/attachment/src/index.ts @@ -186,8 +186,8 @@ export abstract class AttachmentStore extends Service { abstract saveImage(input: SaveImageAttachment): Promise /** - * Read one image and verify that bytes still match the recorded reference. - * @param ref - durable reference from the session log. + * Read one image and verify its ID, format, byte length, and dimensions against the supplied reference. + * @param ref - supplied image reference; name and originalDimensions are preserved without file verification. * @param signal - optional cancellation for backend read and verification work. * @returns the verified bytes and normalized attachment reference. * @throws the signal reason when aborted, or a storage error when verification fails. @@ -240,7 +240,7 @@ export abstract class AttachmentStore extends Service { * Read and verify one verbatim stored file as bounded chunks. Providers must * not collect the complete file in memory. Backends without verbatim file * reads keep this default rejection. - * @param ref - durable reference from the session log. + * @param ref - durable file reference from the session log. * @param signal - optional cancellation for backend reads and verification work. * @returns exact file bytes in order; integrity failures reject the iteration. */ diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml index 0fe0cc80c5..9ce0beae8e 100644 --- a/packages/boot/app-boot/README.i18n.yaml +++ b/packages/boot/app-boot/README.i18n.yaml @@ -24,8 +24,8 @@ en: 65bf2834b81f87da zh: c864ac60a3005b99 /deepseek-ai-dsh-app-boot/use-this-package/profiles: - en: 284f006f3304a32e - zh: b52ccef70e00114c + en: a9c82cd220ae8d59 + zh: 8c7c1c97efcdfc25 /deepseek-ai-dsh-app-boot/use-this-package/previewing-the-effective-configuration: en: 646a0ccdd7881ad1 zh: e3696acb1573dd7b @@ -42,8 +42,8 @@ en: f4a2695cb4c8a570 zh: 89837235d2f376cf /deepseek-ai-dsh-app-boot/understand-the-implementation/design-notes: - en: 9ecb744556705fd1 - zh: d83aaf2ebb91d0fc + en: 6eba01e24a2a68ab + zh: 64af424489087ec7 /deepseek-ai-dsh-app-boot/understand-the-implementation/helper-behavior: en: 6fa850d1bb000d0e zh: aa83a40a9d3db295 diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md index 4f0793c034..4d30457f81 100644 --- a/packages/boot/app-boot/README.md +++ b/packages/boot/app-boot/README.md @@ -53,7 +53,7 @@ Before a profile imports a plugin, DSH checks its declared DSH requirement again Admission happens only at composition boundaries DSH owns, and a denied row is denied in the launcher's own copy of the composition: no profile patch layer, dependency manifest, or bundle list changes. `prepareProfilePatches` composes over the launcher's empty profile root and runs while the root Include is mounted and on every profile recomposition, so a denied plugin never imports its module. `prepareProfileEntries` does the same for a preset's rows. A denied ordinary row becomes a detached `disabled: true` row; a native group stays mounted and its denied children do not load; a native Include that reaches a denied plugin is omitted whole, because its file is never rewritten. A row denied by policy keeps its configured `disabled` value in the profile, and every refusal is reported with the package, versions, and risk. A bundle is not a row, so `loadProfileDirectory` checks each bundle's own DSH requirement when it loads the profile's bundle layers, at startup and on every recomposition; an incompatible bundle without an exemption is skipped like an unreadable one and listed in `skippedBundles`. These boundaries do not cover plugins another embedder mounts through its own `ctx.plugin` call. Two edits made directly to files during a session are judged only at the next recomposition or startup: a running plugin's own `package.json` DSH requirement, and an entry-list file the Loader reads itself, such as the launcher's root config or a nested `cordis:include` file. `--dump-config` reports the configured composition, so a denied plugin row still appears there while a denied bundle contributes no rows, and `--dump-config-schema` imports each composed module to read its schema; run it only against a profile whose plugins you already trust. -Exact-version exemptions live in the profile's own `compatibility.json`, not in its `package.json`, so an exemption write never touches the dependency manifest, the bundle list, or Cordis patch files. It maps exact `package-name@version` keys to lists of exact DSH runtime versions; neither a plugin upgrade nor a DSH upgrade inherits permission. A missing file means no exemptions. A malformed one never stops the profile from starting: records the reader accepts still apply, each rejected record is reported on stderr beside the plugin denials, and the file is then treated as read-only, so a grant or revocation refuses and asks the user to repair it by hand instead of overwriting their content. [Plugin Manager](../plugin-manager/README.md#version-compatibility-and-exemptions) owns the grant, revocation, and risk confirmation each change requires. +Exact-version exemptions live in the profile's own `compatibility.json`, not in its `package.json`, so an exemption write never touches the dependency manifest, the bundle list, or Cordis patch files. It maps exact `package-name@version` keys to lists of exact DSH runtime versions; neither a plugin upgrade nor a DSH upgrade inherits permission. A missing file means no exemptions. A malformed one never stops the profile from starting: records the reader accepts still apply, each rejected record is reported on stderr beside the plugin denials, and the file is then treated as read-only, so a grant or revocation refuses and asks the user to repair it by hand instead of overwriting their content. [Plugin Manager](../plugin-manager/README.md#version-compatibility-and-exemptions) owns the grant, revocation, and risk confirmation each change requires. `validatePluginVersionExemption(packageVersion, runtimeVersion)` validates canonical exact identities without granting permission; invalid identities throw. A bundle may declare `dsh.bundle.platforms` as a nonempty list of Node Host platform names, such as `["darwin"]`. The launcher validates this declaration before reading the bundle patch. An unsupported Host skips the entire layer, retains its saved selection, and reports the reason through `skippedBundles`; other layers remain effective. Omission permits every platform. Values must be Node platform names; aliases such as `macos` are invalid. Browser clients do not determine Host support. @@ -145,7 +145,9 @@ This section explains how the outcomes above are realized and points at the code - **One rejection checkpoint.** `inactiveEntries` keeps the exact reasons it folds into the boot diagnostic visible through the next process rejection checkpoint, so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal. - **Two-stage failure labels.** Outside startup audit failures, `boot()` distinguishes `host preparation failed` — `prepare` threw before any config-tree entry mounted — from `plugin tree failed to load`, and appends the deepest plugin error's stack. Plugin diagnostics retain nested causes and aggregate member failures; cyclic causes stop traversal without replacing the original error. -The startup error also retains inactive-entry metadata and raw startup warning/error records without retaining the Loader tree. Its `entries` and `startup` fields are non-enumerable: direct access and full diagnostic reports retain them, while ordinary error inspection omits them. Pending-only failures have no `cause`; failures with recorded errors retain their original values in an `AggregateError`. Import errors are collected through the logger before the Loader mounts because no failed Fiber exists for those imports. The temporary exporter is removed when boot settles. +The startup error also retains inactive-entry metadata and raw startup warning/error records without retaining the Loader tree. Its `entries`, `startup`, and `composition` fields are non-enumerable: direct access and full diagnostic reports retain them, while ordinary error inspection omits them. Pending-only failures have no `cause`; failures with recorded errors retain their original values in an `AggregateError`. Import errors are collected through the logger before the Loader mounts because no failed Fiber exists for those imports. The temporary exporter is removed when boot settles. + +The package exports `StartupCompositionDiagnostic`, `StartupPluginState`, and `StartupServiceState` for typed consumers. Before disposal, `composition` captures up to 256 configured plugin rows and 256 missing-service observations, with omission counts. Rows include module, available package version, state and Loader source URL; configuration values are excluded. Registered providers include their state and whether their scope matches the consumer. An empty provider list means ownership is unknown: disabled or failed plugins may never have registered. The Loader source does not identify which overlay last changed a row. Metadata lookup failures leave the version unknown; snapshot failure preserves the original startup error. ### Helper behavior diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md index 36e03ac63c..a4d8554ca5 100644 --- a/packages/boot/app-boot/README.zh.md +++ b/packages/boot/app-boot/README.zh.md @@ -53,7 +53,7 @@ profile 导入插件前，DSH 会将其声明的 DSH 版本要求与 `getDshRunt 检查只发生在 DSH 自己持有的组合入口，改写的是启动器自己的那份组合：profile 的 patch 层、依赖清单与组合包列表都不会改变。`prepareProfilePatches` 在启动器的空 profile 根之上组合，并在挂载根 Include 时以及每次 profile 重新组合时执行，因此被拒绝的插件永远不会导入其模块；`prepareProfileEntries` 对 preset 行做同样的事。被拒绝的普通行会变成游离的 `disabled: true` 行；原生 group 保持挂载，其被拒绝的子行不会加载；若某个原生 Include 会到达被拒绝的插件，则整体省略该 Include，因为它的文件不会被改写。被策略拒绝的行在 profile 中保留其配置的 `disabled` 值，每次拒绝都会报告包名、版本与风险。组合包本身不是行，因此 `loadProfileDirectory` 在启动和每次重新组合加载 profile 的组合包层时，检查每个组合包自己声明的 DSH 版本要求；没有豁免的不兼容组合包会像无法读取的组合包一样被跳过，并列入 `skippedBundles`。这些入口不覆盖其他嵌入方通过自己的 `ctx.plugin` 调用挂载的插件。会话中直接改文件的两类编辑只在下一次重新组合或启动时才被判定：正在运行的插件自己的 `package.json` DSH 版本要求，以及 Loader 自己读取的入口清单文件（如启动器的根配置或嵌套的 `cordis:include` 文件）。`--dump-config` 报告的是配置出的组合，因此被拒绝的插件行仍会出现在其中，而被拒绝的组合包不提供任何行；`--dump-config-schema` 会导入每个组合模块以读取其 schema，请只对已经信任其插件的 profile 运行。 -精确版本豁免保存在 profile 自己的 `compatibility.json` 中，而不是 `package.json`，因此写豁免不会触及依赖清单、组合包列表或 Cordis patch 文件。它把精确的 `package-name@version` 键映射到精确 DSH 运行时版本列表；插件升级和 DSH 升级都不继承授权。文件缺失表示没有豁免。文件损坏绝不会阻止 profile 启动：读取器接受的记录仍然生效，每条被拒绝的记录会与插件拒绝信息一起输出到 stderr，此后该文件被视为只读，因此授予或撤销会拒绝执行并要求用户手工修复，而不是覆盖用户的内容。[插件管理器](../plugin-manager/README.zh.md#version-compatibility-and-exemptions)负责每次变更所需的授权、撤销与风险确认。 +精确版本豁免保存在 profile 自己的 `compatibility.json` 中，而不是 `package.json`，因此写豁免不会触及依赖清单、组合包列表或 Cordis patch 文件。它把精确的 `package-name@version` 键映射到精确 DSH 运行时版本列表；插件升级和 DSH 升级都不继承授权。文件缺失表示没有豁免。文件损坏绝不会阻止 profile 启动：读取器接受的记录仍然生效，每条被拒绝的记录会与插件拒绝信息一起输出到 stderr，此后该文件被视为只读，因此授予或撤销会拒绝执行并要求用户手工修复，而不是覆盖用户的内容。[插件管理器](../plugin-manager/README.zh.md#version-compatibility-and-exemptions)负责每次变更所需的授权、撤销与风险确认。`validatePluginVersionExemption(packageVersion, runtimeVersion)` 校验规范的精确身份而不授予权限；身份非法时抛出错误。 组合包可以用 `dsh.bundle.platforms` 声明非空的 Node Host 平台名称列表，例如 `["darwin"]`。启动器在读取组合包 patch 前验证此声明。Host 不受支持时会跳过整个配置层，保留已保存的选择，并通过 `skippedBundles` 报告原因；其他配置层继续生效。省略此字段时允许所有平台。值必须是 Node 平台名，`macos` 等别名无效。浏览器所在机器的平台不决定 Host 是否受支持。 @@ -145,7 +145,9 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如 - **单一 rejection 检查点。** `inactiveEntries` 把折入启动诊断的确切原因保持到下一个进程级 rejection 检查点可见，使 `installFailLoud` 能合并 Loader 的重复通知，而所有无关的未处理 rejection 仍然致命。 - **两阶段失败标签。** 除启动审计失败外，`boot()` 区分 `host preparation failed`（`prepare` 在任何配置树条目挂载前抛出）与 `plugin tree failed to load`，并追加最深层插件错误的堆栈。插件诊断保留嵌套原因和聚合错误中的各项失败；原因链出现循环时会停止遍历，但不会替换原始错误。 -启动错误还保留未激活条目的元数据和原始启动警告、错误记录，不保留 Loader tree。其 `entries` 和 `startup` 字段不可枚举：直接访问和完整诊断报告保留这些字段，常规错误检查输出则省略它们。只有等待条目时没有 `cause`；存在已记录错误时，`AggregateError` 保留其原始值。收集器在 Loader 挂载前通过 logger 收集导入错误，因为这些导入尚无 failed Fiber。启动结算后会移除临时 exporter。 +启动错误还保留未激活条目的元数据和原始启动警告、错误记录，不保留 Loader tree。其 `entries`、`startup` 和 `composition` 字段不可枚举：直接访问和完整诊断报告保留这些字段，常规错误检查输出则省略它们。只有等待条目时没有 `cause`；存在已记录错误时，`AggregateError` 保留其原始值。收集器在 Loader 挂载前通过 logger 收集导入错误，因为这些导入尚无 failed Fiber。启动结算后会移除临时 exporter。 + +包导出 `StartupCompositionDiagnostic`、`StartupPluginState` 和 `StartupServiceState`，供消费者按名引用。释放前，`composition` 捕获最多 256 个配置插件条目和 256 个缺失服务观测，并记录省略数量。条目包含模块、可取得的包版本、状态和 Loader 来源 URL，不含配置值。已注册提供者包含其状态及作用域是否与消费者一致。提供者列表为空表示归属未知：被禁用或失败的插件可能从未注册服务。Loader 来源不代表最后修改该条目的 overlay。元数据查询失败时版本标为未知；快照失败保留原始启动错误。 ### Helper 行为 diff --git a/packages/boot/app-boot/package.json b/packages/boot/app-boot/package.json index 07e9757746..6bcc5fa3d2 100644 --- a/packages/boot/app-boot/package.json +++ b/packages/boot/app-boot/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-app-boot", "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts index 6269685a58..b89eb3632a 100644 --- a/packages/boot/app-boot/src/index.ts +++ b/packages/boot/app-boot/src/index.ts @@ -9,6 +9,8 @@ import { pathToFileURL } from 'node:url' import { readFileSync } from 'node:fs' import { inspect, parseEnv } from 'node:util' +import { captureStartupComposition, type StartupCompositionDiagnostic } from './startup-diagnostics.ts' +export type { StartupCompositionDiagnostic, StartupPluginState, StartupServiceState } from './startup-diagnostics.ts' import { basename, dirname, isAbsolute, resolve } from 'node:path' import * as yaml from 'js-yaml' import { Context, type Fiber, type FiberState } from '@deepseek-ai/cordis' @@ -22,7 +24,7 @@ export { sanitizeProfile } from './profile-sanitize.ts' export { getDshRuntimeVersion, evaluatePluginCompatibility, pluginCompatibilityWarning, type PluginCompatibility } from './plugin-compatibility.ts' export { PROFILE_COMPATIBILITY_FILENAME, readProfileCompatibility, readProfileVersionExemptions, - setProfileVersionExemption, type ProfileCompatibility, + setProfileVersionExemption, validatePluginVersionExemption, type ProfileCompatibility, } from './profile-compatibility.ts' import { prepareProfilePatches } from './compatibility-preflight.ts' import { ProfileRuntimeResolution, type RuntimeResolution } from './profile.ts' @@ -338,9 +340,7 @@ async function recompose( diagnostic: failure.entry.fiber?.uid ? reloadDiagnostic(failure) : undefined, })) // Removed entries leave the Loader store before their async disposers finish. - const previousFibers = [...ctx.loader.entries()].flatMap(row => row.fiber === undefined ? [] : [{ - fiber: row.fiber, failed: row.fiber.state === FIBER_FAILED || row.fiber.state === FIBER_DISPOSED, - }]) + const previousFibers = [...ctx.loader.entries()].flatMap(row => row.fiber === undefined ? [] : [row.fiber]) const { patches: previous = [], ...includeConfig } = entry.options.config as Include.Config const current = withResolution ? ctx.get('pluginPackages')?.resolution : undefined // A plain-data resolution has no inputs to recompute from. @@ -384,12 +384,15 @@ async function recompose( const prepared = prepareProfilePatches(ctx, patches, parentURL, binName) applying = true const retried = [...new Set([...running, ...withResolution ? [...ctx.loader.entries()].filter(importFailed) : []])] + // Group.update replaces its data array and attempts every row it still lists, including failed imports. + const priorData = new Map(retried.map(row => [row, row.parent.data])) try { await entry.update({ config: { ...includeConfig, patches: prepared } }) } finally { - await resume(ctx, retried) + // Only rows whose Group did not update still need an explicit retry after the awaited update. + await resume(ctx, retried.filter(row => row.parent.data === priorData.get(row))) } - const results = await Promise.allSettled(previousFibers.map(({ fiber }) => fiber.await())) + await Promise.allSettled(previousFibers.map(fiber => fiber.await())) await ctx.loader.await() const failures = await inactiveEntries(ctx) const introduced = failures.filter((failure) => { @@ -401,9 +404,6 @@ async function recompose( return !previousFailures.some(previous => sameFailure(previous, failure)) }) if (introduced.length > 0) throw new Error(activationDiagnostic(binName, introduced, false).trimEnd()) - for (const [index, result] of results.entries()) { - if (result.status === 'rejected' && !previousFibers[index]?.failed) throw result.reason - } ctx.emit('app-boot/config-reload') return { warnings: failures.map(reloadDiagnostic) } } finally { @@ -1003,6 +1003,8 @@ interface StartupLogRecord { /** Startup audit failure with non-enumerable metadata and original failures as its cause. */ export class StartupError extends Error { + /** Plugin states captured before disposal, excluding configuration values. */ + composition?: StartupCompositionDiagnostic /** Root configuration and startup logs, attached by boot after disposal. */ startup?: { configurationPath: string; messages: readonly StartupLogRecord[] } @@ -1016,6 +1018,7 @@ export class StartupError extends Error { Object.defineProperties(this, { entries: { enumerable: false }, startup: { enumerable: false }, + composition: { enumerable: false }, }) } } @@ -1219,11 +1222,6 @@ export async function boot( try { ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/' ctx.provide('dshHomePath', dshHomePath) - // Fiber.update() discards the restart promise. Observe it before the - // waterfall returns; activation audits still report the failed fiber. - ctx.on('internal/update', (_config, _noSave, next: () => unknown) => { - void Promise.resolve(next()).catch((error: unknown) => { ctx.logger.error(error) }) - }, { global: true, prepend: true }) await ctx.plugin(Loader) await prepare?.(ctx) stage = 'plugin tree failed to load' @@ -1238,6 +1236,11 @@ export async function boot( await auditStartupEntries(ctx, binName) return ctx } catch (cause) { + if (cause instanceof StartupError) { + try { cause.composition = captureStartupComposition(ctx) } catch (error) { + ctx.logger.warn('Startup composition diagnostic unavailable', error) + } + } // Root-fiber disposal contains cleanup failures per observer (Cordis // fiber.ts hardening) and a repeated call returns the settled single-shot // result, so this await cannot reject and replace `cause`. diff --git a/packages/boot/app-boot/src/startup-diagnostics.ts b/packages/boot/app-boot/src/startup-diagnostics.ts new file mode 100644 index 0000000000..c9fe729935 --- /dev/null +++ b/packages/boot/app-boot/src/startup-diagnostics.ts @@ -0,0 +1,104 @@ +/** Configuration-free snapshots captured before a failed startup disposes its plugins. */ + +import { Context, type FiberState } from '@deepseek-ai/cordis' +import type { Entry } from '@deepseek-ai/cordis-plugin-loader' +import type {} from './profile-resolution/service.ts' + +/** One configured entry at the time startup failed. */ +export interface StartupPluginState { + readonly id: string + readonly module: string + readonly version: string + readonly state: 'disabled' | 'active' | 'pending' | 'failed' | 'disposed' | 'loading' | 'unloading' + /** Loader source URL; individual overlay ownership may be unavailable. */ + readonly source: string + readonly missing: readonly string[] +} + +/** Observed registrations for one service missing from a consumer. */ +export interface StartupServiceState { + readonly consumer: string + readonly service: string + /** Empty means no registration was observed, not that no configured plugin can provide it. */ + readonly providers: readonly { + readonly entry: string + readonly state: string + readonly visibility: 'same-scope' | 'other-scope' + }[] +} + +/** Bounded startup state without plugin config, service values, or logger arguments. */ +export interface StartupCompositionDiagnostic { + readonly plugins: readonly StartupPluginState[] + readonly services: readonly StartupServiceState[] + readonly omittedPlugins: number + readonly omittedServices: number +} + +function stateName(state: FiberState): StartupPluginState['state'] { + const names: Record = { + 0: 'pending', 1: 'loading', 2: 'active', 3: 'failed', 4: 'disposed', 5: 'unloading', + } + return names[state] +} + +function pluginState(ctx: Context, entry: Entry): StartupPluginState { + let state: StartupPluginState['state'] + try { + state = entry.disabled ? 'disabled' : entry.fiber === undefined ? 'failed' : stateName(entry.fiber.state) + } catch (_error) { + // The activation diagnostic owns the disabled-expression error. + state = 'failed' + } + let version = 'unknown' + const source = entry.parent.tree.ctx.baseUrl + try { + if (source !== undefined) version = ctx.get('pluginPackages')?.packageOf(entry.options.name, source)?.version ?? 'unknown' + } catch (_error) { + // Missing or damaged metadata must not replace the startup failure. + } + const fiber = entry.fiber + return { + id: entry.id, module: entry.options.name, version, state, source: source ?? 'unknown', + missing: state === 'pending' && fiber !== undefined + ? Object.keys(fiber.inject).filter(name => fiber.ctx.get(name) === undefined) : [], + } +} + +/** + * Capture Loader state and registered service ownership before teardown. + * Providers that never registered cannot be inferred from their package names. + * @param ctx - Live application context with its Loader still mounted. + * @returns At most 256 plugin rows and 256 missing-service observations, with omission counts. + */ +export function captureStartupComposition(ctx: Context): StartupCompositionDiagnostic { + const entries = [...ctx.loader.entries()] + const rows = entries.map(entry => ({ entry, state: pluginState(ctx, entry) })) + // Inactive rows precede healthy rows so bounded reports retain the failure context. + rows.sort((a, b) => Number(a.state.state === 'active') - Number(b.state.state === 'active')) + const services: StartupServiceState[] = [] + let omittedServices = 0 + const store = ctx.reflect.store + for (const { entry, state } of rows) { + const fiber = entry.fiber + if (fiber === undefined) continue + for (const service of state.missing) { + if (services.length === 256) { omittedServices++; continue } + const scope = fiber.ctx[Context.isolate][service] + const providers: StartupServiceState['providers'][number][] = [] + for (const key of Object.getOwnPropertySymbols(store)) { + const impl = store[key] + if (impl?.name !== service) continue + providers.push({ + entry: impl.ctx.fiber.entry?.id ?? 'unknown', state: stateName(impl.ctx.fiber.state), + visibility: key === scope ? 'same-scope' : 'other-scope', + }) + } + services.push({ consumer: state.id, service, providers }) + } + } + return { + plugins: rows.slice(0, 256).map(row => row.state), services, + omittedPlugins: Math.max(0, rows.length - 256), omittedServices, + } +} diff --git a/packages/boot/app-boot/tests/startup-diagnostics.spec.ts b/packages/boot/app-boot/tests/startup-diagnostics.spec.ts new file mode 100644 index 0000000000..9d55d4808b --- /dev/null +++ b/packages/boot/app-boot/tests/startup-diagnostics.spec.ts @@ -0,0 +1,133 @@ +import { mkdtemp, writeFile, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, expect, expectTypeOf, it } from 'vitest' +import { boot, StartupError, type StartupCompositionDiagnostic, type StartupPluginState, type StartupServiceState } from '../src/index.ts' +import { captureStartupComposition } from '../src/startup-diagnostics.ts' + +const roots: string[] = [] +afterEach(async () => { + await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))) +}) + +async function configuration(): Promise { + const root = await mkdtemp(join(tmpdir(), 'dsh-startup-diagnostic-')) + roots.push(root) + await writeFile(join(root, 'consumer.mjs'), 'export const inject = ["agents"]; export function apply() {}\n') + await writeFile(join(root, 'provider.mjs'), 'export function apply(ctx) { ctx.provide("agents", {}) }\n') + await writeFile(join(root, 'cordis.yml'), [ + '- id: agent', ' name: ./provider.mjs', ' disabled: true', + ' config:', ' privateValue: do-not-export-this', + '- id: agent-loop', ' name: ./consumer.mjs', '', + ].join('\n')) + return join(root, 'cordis.yml') +} + +it('retains disabled and waiting entries after the real Loader has been disposed', async () => { + const error: unknown = await boot('diagnostic-test', await configuration()).catch((failure: unknown) => failure) + expect(error).toBeInstanceOf(StartupError) + if (!(error instanceof StartupError)) throw error + expect(error.composition?.plugins).toEqual(expect.arrayContaining([ + expect.objectContaining({ module: './provider.mjs', state: 'disabled', version: 'unknown' }), + expect.objectContaining({ module: './consumer.mjs', state: 'pending', missing: ['agents'] }), + ])) + expect(error.composition?.services).toEqual([ + expect.objectContaining({ service: 'agents', providers: [] }), + ]) + expect(JSON.stringify(error.composition)).not.toContain('do-not-export-this') +}) + +it('preserves the startup failure when the Loader is already unavailable to diagnostic capture', async () => { + const failure = new StartupError('startup was interrupted', []) + const result: unknown = await boot('diagnostic-test', await configuration(), undefined, async (ctx) => { + await ctx.fiber.dispose() + throw failure + }).catch((error: unknown) => error) + expect(result).toBe(failure) + expect(failure.composition).toBeUndefined() + expect(failure.startup?.messages.some(message => message.args[0] === 'Startup composition diagnostic unavailable')).toBe(true) +}) + +it('identifies a registered provider that is isolated from the waiting consumer', async () => { + const error: unknown = await boot('diagnostic-test', await configuration(), undefined, async (ctx) => { + await ctx.isolate('agents').plugin({ + name: 'isolated-agent-provider', + apply(provider) { provider.reflect.provide('agents', {}) }, + }) + }).catch((failure: unknown) => failure) + expect(error).toBeInstanceOf(StartupError) + if (!(error instanceof StartupError)) throw error + expect(error.composition?.services).toEqual([ + expect.objectContaining({ service: 'agents', providers: [{ entry: 'unknown', state: 'active', visibility: 'other-scope' }] }), + ]) +}) + +it('reports omitted plugin and missing-service counts instead of silently dropping rows', async () => { + const config = await configuration() + const root = roots.at(-1)! + const services = Array.from({ length: 257 }, (_, index) => `missing${index}`) + await writeFile(join(root, 'consumer.mjs'), `export const inject = ${JSON.stringify(services)}; export function apply() {}\n`) + await writeFile(config, [ + '- id: agent-loop\n name: ./consumer.mjs', + ...Array.from({ length: 257 }, (_, index) => `- id: disabled-${index}\n name: ./provider.mjs\n disabled: true`), '', + ].join('\n')) + const error: unknown = await boot('diagnostic-test', config).catch((failure: unknown) => failure) + if (!(error instanceof StartupError)) throw error + expect(error.composition?.plugins).toHaveLength(256) + expect(error.composition?.omittedPlugins).toBeGreaterThanOrEqual(2) + expect(error.composition?.services).toHaveLength(256) + expect(error.composition?.omittedServices).toBe(1) +}) + +it('reports a registered same-scope provider whose value is unavailable', async () => { + const config = await configuration() + await writeFile(join(roots.at(-1)!, 'provider.mjs'), 'export function apply(ctx) { ctx.provide("agents", undefined) }\n') + await writeFile(join(roots.at(-1)!, 'consumer.mjs'), 'export const inject = ["agents", "unprovided"]; export function apply() {}\n') + await writeFile(config, '- id: agent\n name: ./provider.mjs\n- id: agent-loop\n name: ./consumer.mjs\n') + const error: unknown = await boot('diagnostic-test', config) + .catch((failure: unknown) => failure) + if (!(error instanceof StartupError)) throw error + expect(error.composition?.services[0]?.providers).toMatchObject([ + { state: 'active', visibility: 'same-scope' }, + ]) + expect(error.composition?.services[0]?.providers[0]?.entry).toContain('agent') +}) + +it('retains the Loader disablement after disposal and reports missing source metadata', async () => { + const config = await configuration() + await writeFile(config, '- id: agent\n name: ./provider.mjs\n') + const ctx = await boot('diagnostic-test', config) + try { + const entry = [...ctx.loader.entries()].find(row => row.options.id === 'agent')! + await entry.fiber!.dispose() + Object.defineProperty(entry.parent.tree.ctx, 'baseUrl', { value: undefined, configurable: true }) + const snapshot = captureStartupComposition(ctx) + expect(snapshot.plugins).toContainEqual(expect.objectContaining({ module: './provider.mjs', state: 'disabled', source: 'unknown' })) + } finally { + await ctx.fiber.dispose() + } +}) + +it.each(['same-scope', 'other-scope'] as const)('attributes a nested %s provider to its Loader entry', async (visibility) => { + const config = await configuration() + const parent = visibility === 'same-scope' ? 'ctx' : 'ctx.isolate("agents")' + await writeFile(join(roots.at(-1)!, 'consumer.mjs'), 'export const inject = ["agents", "unprovided"]; export function apply() {}\n') + await writeFile(join(roots.at(-1)!, 'provider.mjs'), `export async function apply(ctx) { await ${parent}.plugin({ name: "nested-provider", apply(child) { child.provide("agents", undefined) } }) }\n`) + await writeFile(config, '- id: agent\n name: ./provider.mjs\n- id: agent-loop\n name: ./consumer.mjs\n') + const failure: unknown = await boot('diagnostic-test', config).then(async (ctx) => { + await ctx.fiber.dispose() + throw new Error('Expected the missing service to prevent startup') + }, (error: unknown) => error) + if (!(failure instanceof StartupError)) throw failure + const owner = failure.composition?.plugins.find(plugin => plugin.module === './provider.mjs') + expect(owner).toBeDefined() + expect(failure.composition?.services[0]?.providers).toEqual([ + { entry: owner!.id, state: 'active', visibility }, + ]) +}) + +it('exports the named types used by startup composition diagnostics', () => { + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() +}) diff --git a/packages/boot/app-boot/tests/user-patches.spec.ts b/packages/boot/app-boot/tests/user-patches.spec.ts index 63e0af5ea6..5b0257aac1 100644 --- a/packages/boot/app-boot/tests/user-patches.spec.ts +++ b/packages/boot/app-boot/tests/user-patches.spec.ts @@ -254,6 +254,11 @@ describe('Loader config interpolation', () => { await provider?.update({ config: { value: 'recovered' } }) await provider?.update({ disabled: false }) await ctx.loader.await() + // rc.11 keeps a failed fiber failed after its dependency recovers; recovery requires an explicit update. + const failed = reader?.fiber + if (failed === undefined) throw new Error('reader entry has no fiber') + await expect(failed.await()).rejects.toThrow('rejected provider') + await failed.update(failed.rawConfig, true) expect(ctx.get('readerResult')).toEqual({ value: 'recovered' }) } finally { await ctx.fiber.dispose() @@ -360,7 +365,7 @@ describe('profile reconciliation settlement', () => { onTestFinished(() => ctx.fiber.dispose()) const entry = [...ctx.loader.entries()].find(row => row.options.id === 'candidate') if (entry === undefined) throw new Error('candidate entry missing') - await entry.update({ config: { fail: true } }) + await expect(entry.update({ config: { fail: true } })).rejects.toThrow('candidate activation failed') await ctx.loader.await() await reconcileProfilePatches(ctx, [], NAME) expect([...ctx.loader.entries()].some(row => row.options.id === 'candidate')).toBe(false) @@ -379,7 +384,7 @@ describe('profile reconciliation settlement', () => { .rejects.toThrow('candidate activation failed') }) - it('reports an activation failure that settles while its entry is being removed', async () => { + it('logs a superseded activation failure without failing removal', async () => { const dir = tmp() const entered = Promise.withResolvers() const release = Promise.withResolvers() @@ -390,11 +395,19 @@ describe('profile reconciliation settlement', () => { }) onTestFinished(async () => { release.resolve(undefined); await ctx.fiber.dispose() }) const entry = [...ctx.loader.entries()].find(row => row.options.id === 'candidate')! - await entry.update({ config: { fail: true } }) + const updating = entry.update({ config: { fail: true } }) await entered.promise - const result = expect(reconcileProfilePatches(ctx, [], NAME)).rejects.toThrow('in-flight failure') + const stopped = Promise.withResolvers() + ctx.on('internal/plugin', (fiber) => { + if (fiber.uid === null && fiber.entry === entry) stopped.resolve(undefined) + }) + const removing = reconcileProfilePatches(ctx, [], NAME) + await stopped.promise release.resolve(undefined) - await result + await Promise.all([updating, removing]) + expect([...ctx.loader.entries()].some(row => row.options.id === 'candidate')).toBe(false) + expect(ctx.logger.buffer.some(message => message.type === 'error' + && message.args.some(value => String(value).includes('in-flight failure')))).toBe(true) }) it('waits for a removed plugin to release its resources', async () => { diff --git a/packages/boot/cmdline/package.json b/packages/boot/cmdline/package.json index 804bb2bc11..04f5f23be1 100644 --- a/packages/boot/cmdline/package.json +++ b/packages/boot/cmdline/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-cmdline", "description": "Immutable command-line handoff from a dsh launcher to any app plugin that injects cmdlineArgs", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/boot/config-editor/package.json b/packages/boot/config-editor/package.json index d8bfc04659..783ce890db 100644 --- a/packages/boot/config-editor/package.json +++ b/packages/boot/config-editor/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-config-editor", "description": "Persist plugin configuration through profile patches and Loader reconciliation", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/boot/hmr/package.json b/packages/boot/hmr/package.json index 93fa7fb127..eeba988bfb 100644 --- a/packages/boot/hmr/package.json +++ b/packages/boot/hmr/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-hmr", "description": "Coordinated module and profile configuration hot reload", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/boot/hmr/src/index.ts b/packages/boot/hmr/src/index.ts index 709524d741..36c16ba6ac 100644 --- a/packages/boot/hmr/src/index.ts +++ b/packages/boot/hmr/src/index.ts @@ -678,10 +678,12 @@ class Hmr extends Service { activated: Fiber[] = [], ) => { for (const [previousFiber, implementation] of replacements.getActiveImplementations(this.ctx, plugin, fibers)) { - const fiber = previousFiber.fiber.parent.registry.plugin(implementation, previousFiber.config, this.getOuterStack).ctx.fiber + const wrapper = previousFiber.fiber.parent.registry.plugin(implementation, previousFiber.config, this.getOuterStack) + const fiber = wrapper.ctx.fiber if (previousFiber.entry !== undefined) { fiber.entry = previousFiber.entry - previousFiber.entry.fiber = fiber + // Like Loader activation, store the registry wrapper; identity checks compare `.ctx.fiber`. + previousFiber.entry.fiber = wrapper } activated.push(fiber) } @@ -831,7 +833,7 @@ class Hmr extends Service { const owner = (fiber: Fiber): Entry | undefined => { for (let current = fiber; current.uid !== 0; current = current.parent.fiber) { const entry = current.entry - if (entry?.fiber === current && managed.has(entry) && affectedFibers.has(current)) return entry + if (entry?.fiber?.ctx.fiber === current && managed.has(entry) && affectedFibers.has(current)) return entry } return undefined } diff --git a/packages/boot/hmr/tests/coordination.spec.ts b/packages/boot/hmr/tests/coordination.spec.ts index b3660828e9..e0dceccb99 100644 --- a/packages/boot/hmr/tests/coordination.spec.ts +++ b/packages/boot/hmr/tests/coordination.spec.ts @@ -218,7 +218,7 @@ it('rebinds configuration handlers when its provider is reconfigured within a re }) await binding.await() await hmr.runExclusive(async () => { - provider.update({ root: [], ignored: [], debounce: 1 }) + await provider.update({ root: [], ignored: [], debounce: 1 }) await provider.await() await binding.await() }) diff --git a/packages/boot/plugin-manager/README.i18n.yaml b/packages/boot/plugin-manager/README.i18n.yaml index 64f0952fc3..2b95a68b06 100644 --- a/packages/boot/plugin-manager/README.i18n.yaml +++ b/packages/boot/plugin-manager/README.i18n.yaml @@ -15,8 +15,8 @@ en: 87679c51aa3693f5 zh: 11684a48a5806afb /deepseek-ai-dsh-plugin-manager/use-this-package: - en: 4bda68030a6999e0 - zh: 5ae0b9825341c05e + en: ae0905aa47cc971d + zh: b22fc6e831fac136 /deepseek-ai-dsh-plugin-manager/use-this-package/version-compatibility-and-exemptions: en: 483285658e267dd5 zh: 846bec2daac59a96 @@ -27,8 +27,8 @@ en: 99b084ff497011d2 zh: 6c047796c1991784 /deepseek-ai-dsh-plugin-manager/understand-the-implementation: - en: 495dadf79c48c43c - zh: 9884dd04a5bb49dc + en: c224bfcb3eb3dbd2 + zh: 8b9c96970a90dccc /deepseek-ai-dsh-plugin-manager/further-exploration: en: c6538243d8702a0d zh: 04a82d923353c75f diff --git a/packages/boot/plugin-manager/README.md b/packages/boot/plugin-manager/README.md index 16d2273cb7..a06788d42a 100644 --- a/packages/boot/plugin-manager/README.md +++ b/packages/boot/plugin-manager/README.md @@ -28,9 +28,9 @@ Manage the current profile's plugins without editing configuration by hand. Enab ## Use this package -Base-backed profiles provide the manager. In Web, the sidebar's **Plugins** page ([ui-plugin-manager](../../client/ui-plugin-manager/README.md)) manages the profile's bundles and their uniquely addressable rows; the Settings Plugin list stays read-only. Agent-preset rows remain read-only. The `plugin_manager` tool exposes the same operations and is enabled in the Standard and Creator presets. Other presets keep it disabled by default. Every tool action requires `danger-full-access` or approval for that call. Under lower sandbox modes, `ask` requests approval; `never`, rejection, cancellation, or an unavailable approval channel prevents execution. An approval leaves the session permission mode unchanged. Profile changes persist across sessions, and installed Host code executes in-process outside the workspace sandbox. Dependency build-script approval remains separate. +Base-backed profiles provide the manager. In Web, the sidebar's **Plugins** page ([ui-plugin-manager](../../client/ui-plugin-manager/README.md)) manages the profile's bundles and their uniquely addressable rows; the Settings Plugin list stays read-only. Agent-preset rows remain read-only. The `plugin_manager` tool exposes the same operations and is enabled in the Standard and Creator presets. Other Web presets keep it disabled by default. The full SDK profile enables it at profile scope in native/PTC mode; without HMR, saved changes return `restart-required` with `no-hmr` and apply after the runtime restarts. Every tool action requires `danger-full-access` or approval for that call. Under lower sandbox modes, `ask` requests approval; `never`, rejection, cancellation, or an unavailable approval channel prevents execution. An approval leaves the session permission mode unchanged. Profile changes persist across sessions, and installed Host code executes in-process outside the workspace sandbox. Dependency build-script approval remains separate. -For a deployment without agent presets, enable the tool in the profile patch. Preset-backed sessions use their preset’s `tool-plugin-manager` entry. +For a deployment without agent presets other than the full SDK profile, enable the tool in the profile patch. Package installation/removal requires pnpm on `PATH` or an explicit `pnpmCommand`; a launcher-provided package manager takes precedence. Preset-backed sessions use their preset’s `tool-plugin-manager` entry. ```yaml - id: tool-plugin-manager @@ -57,7 +57,7 @@ Official on-demand installs call the same `installBundle` operation as other bun `updateBundle(name, version, options)` replaces an updatable bundle with an exact newer version; an older version is refused. The target is first viewed over the same plan as `listVersions`, and a version that is missing, declares no bundle, or whose `engines.dsh` or DSH peers reject the running DSH stops the update at `step: 'check'` with the profile unchanged. With HMR the update removes the installed version, so its plugins stop, then installs `name@version` with `saveExact` and the current selection from the registry that answered. When that installation fails, is cancelled, or installs but cannot start, the target is removed if it stayed and the removed version is installed again from the registry it was installed from in this process, else over the configured plan as its removal asks, and reported as `restore`; a reinstallation that also fails leaves the package uninstalled. A removal or installation that rejects, for example on a lock timeout, is reported as that step's failure. Without HMR the target is installed over the running version and the result reports `restart-required`. `plugin-manager/update-state` announces `checking`, `removing`, `installing`, and `restoring` under the caller's `requestId`; the target's installation streams its logs and accepts `cancelInstall` under the same id, while the reinstallation carries none, so a cancellation cannot stop it. -`installBundle` checks GitHub repositories with `git ls-remote` before starting pnpm, using the profile directory and the installer's Git and proxy configuration. `githubConnectionTimeoutMs` defaults to 5000 ms and limits only this check, not package download or builds. The check disables credential helpers and prompts; only network failures and timeouts stop installation, reporting `failedAt: 'spec-host'` with the existing failure kind and diagnostic log. Authentication, repository lookup and other failures are left to pnpm, including its HTTPS-to-SSH fallback. Cancellation and manager disposal stop the check and its descendants. Registry packages, paths, tarballs and other Git hosts skip this check. A reachable repository can still fail during download or bundle validation. +`installBundle` checks GitHub repositories with `git ls-remote` before starting pnpm, using the profile directory and the installer's Git and proxy configuration. `githubConnectionTimeoutMs` defaults to 5000 ms and limits only this check, not package download or builds. The check disables credential helpers and prompts; only network failures and timeouts stop installation, reporting `failedAt: 'spec-host'` with the existing failure kind and diagnostic log. A stopped installation streams that failure under its `requestId` as the installation's only `plugin-manager/install-log` run, named by the `git ls-remote` command line with any URL user information removed; a timed-out check reports no exit code. The answer's `packageResult` stays a plain result, without the command line. Authentication, repository lookup and other failures are left to pnpm, including its HTTPS-to-SSH fallback. Cancellation and manager disposal stop the check and its descendants. Registry packages, paths, tarballs and other Git hosts skip this check. A reachable repository can still fail during download or bundle validation. An HTTP(S) Git URL on a host for which pnpm has no HTTPS-to-SSH fallback, that is, any host `hosted-git-info` does not know, such as a self-hosted GitLab, is probed with `git ls-remote` before pnpm starts. The probe uses the installer's Git configuration and credential helpers with Git's terminal and askpass prompts disabled; on POSIX it also has no controlling terminal, so SSH cannot prompt. When HTTP(S) cannot read the repository and `ssh://git@/` can, pnpm installs that SSH URL with the original fragment, and the profile records it. Otherwise the spec is installed unchanged. Each probe is bounded by `gitTransportTimeoutMs`, 5000 ms by default; cancellation and manager disposal stop it. URLs with credentials or a query skip the probe. @@ -65,7 +65,7 @@ Registries are asked in turn. The plan starts at `options.registry`, else the co The browser-safe `@deepseek-ai/dsh-plugin-manager/registry` entry exports `OFFICIAL_NPM_REGISTRY` and `NPMMIRROR_REGISTRY` for consumers that identify those public registries. -`installBundle` accepts a caller-generated `requestId`, under which `plugin-manager/install-log` streams each pnpm run's output and `plugin-manager/install-state` announces `installing`, `cancelling`, and `applying`; `installing` is announced once per registry asked, with the `attempt`'s registry, position, and the plan's length. The install asks the same plan as the lookup, from `options.registry`, running `pnpm add` with `--registry` and restoring the profile files between attempts; it moves on for the failures another registry can change and stops at any other, and at a failure whose error line names the host a git or tarball spec is fetched from, which no registry stands in for; `failedAt` says which of the two the last failed run could not reach. `cancelInstall(requestId)` stops the run and answers `cancelled` only after the Git check or pnpm exited and the files are back, `too-late` once the bundle is being applied, and `not-running` for any other id; the install call then reports `application: 'cancelled'`. A run that fails, is cancelled, or adds a package without a bundle patch restores `package.json` and `pnpm-lock.yaml` as they were; `packageResult.kind` classifies the last run from its exit and output, `registries` names every registry asked, `bundle` names the package a finished run added, and `version` its manifest version, which can differ from the version `inspect` read, for example when pnpm's `minimumReleaseAge` holds back a recent release. `listBundles` carries each bundle's one-liner (the package `description`), the rows its patch declares with their live entries, and the built-in rows it overrides; it lists the profile's own bundles, the bundles the installation supplies, and a selected name without a bundle patch as a `not-bundle` problem, while an unselected plain dependency is left out. A bundle the launcher's `OPTIONAL_BUNDLES` names is `optional`: shipped switched off for the person to turn on, never removable, and selected by no shipped template ([rationale](../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md)). Every completed operation emits `plugin-manager/changed`; a patch generation applied outside the manager, by HMR's watcher after a CLI or hand edit, announces nothing, so the page learns of it on its next read. +`installBundle` accepts a caller-generated `requestId`, under which `plugin-manager/install-log` streams each pnpm run's output and `plugin-manager/install-state` announces `installing`, `cancelling`, and `applying`; a pnpm run that fails without printing streams the diagnostic its log carries, so the details panel is not left empty. `installing` is announced once per registry asked, with the `attempt`'s registry, position, and the plan's length. The install asks the same plan as the lookup, from `options.registry`, running `pnpm add` with `--registry` and restoring the profile files between attempts; it moves on for the failures another registry can change and stops at any other, and at a failure whose error line names the host a git or tarball spec is fetched from, which no registry stands in for; `failedAt` says which of the two the last failed run could not reach. `cancelInstall(requestId)` stops the run and answers `cancelled` only after the Git check or pnpm exited and the files are back, `too-late` once the bundle is being applied, and `not-running` for any other id; the install call then reports `application: 'cancelled'`. A run that fails, is cancelled, or adds a package without a bundle patch restores `package.json` and `pnpm-lock.yaml` as they were; `packageResult.kind` classifies the last run from its exit and output, `registries` names every registry asked, `bundle` names the package a finished run added, and `version` its manifest version, which can differ from the version `inspect` read, for example when pnpm's `minimumReleaseAge` holds back a recent release. `listBundles` carries each bundle's one-liner (the package `description`), the rows its patch declares with their live entries, and the built-in rows it overrides; it lists the profile's own bundles, the bundles the installation supplies, and a selected name without a bundle patch as a `not-bundle` problem, while an unselected plain dependency is left out. A bundle the launcher's `OPTIONAL_BUNDLES` names is `optional`: shipped switched off for the person to turn on, never removable, and selected by no shipped template ([rationale](../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md)). Every completed operation emits `plugin-manager/changed`; a patch generation applied outside the manager, by HMR's watcher after a CLI or hand edit, announces nothing, so the page learns of it on its next read. `waitForInstall(requestId)` lets a client recover a lost response by waiting for the active installation, including its non-cancellable application phase. It returns the same outcome as the original call, or `null` if the request is not active. Completed results are not retained; `null` establishes neither success nor cancellation. @@ -129,6 +129,10 @@ A service run whose captured output stays silent for `idleTimeoutMs` is terminat Results contain the last attempted stage, target, saved-state change, application status and error codes. Web dictionaries render management text; pnpm and Loader diagnostics remain unmodified. Unrelated pre-existing inactive entries return warnings; new or changed failures and inactive explicit enablement targets fail the operation. A failed or cancelled package run, or failed bundle validation, restores the manifest and lockfile snapshotted before pnpm ran ([rationale](../../../.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.md)); later failures retain saved changes as described in [Failure behavior](#failure-behavior). Installations are tracked by request id until their call settles, so a cancellation names one run and joins its settlement without taking the profile lock. The CLI inherits authentication variables and terminal descriptors; service operations use a scrubbed environment and captured output. +The `plugin-manager/operation` event correlates each service invocation with its start and observed result, or an unknown outcome when an exception escapes result construction. Installation targets retain only parsed registry package names; bundle toggles and removals require the exact package name without a version range or surrounding whitespace. Plugin targets retain only known entry IDs. Recorded targets need not be installed; operations that require their files still refuse missing packages. Version-exemption records retain the validated package name and exact exemption version, not the currently installed version. If either the package or runtime identity is invalid, target is null and version is omitted. Exemptions reuse reason `bundle`, stage `enable`, and the exemption's `enabled` value; when the exemption version matches the installed version, their records cannot distinguish an exemption change from a bundle toggle. Versions describe request-time observations before locking or the resolved installation; invalid or oversized metadata is omitted without losing the operation. Platform refusals retain the `unsupported-platform` error code. Raw specs and error text are excluded. Subscribers run independently without delaying management; synchronous throws and asynchronous rejections do not starve later subscribers or change the result. Direct CLI package operations do not emit this service event. + +The `@deepseek-ai/dsh-plugin-manager/diagnostic` entry supplies Desktop Host and shell readers with run IDs, operation records and a parser that retains only whitelisted fields. Malformed or oversized records are rejected; readers report omissions and truncation. The shell accepts records only for the run ID announced by its Host. Diagnostic consumers own persistence and delivery limits; missing records never imply successful operations. + ----- diff --git a/packages/boot/plugin-manager/README.zh.md b/packages/boot/plugin-manager/README.zh.md index 67462df04a..db1c756fae 100644 --- a/packages/boot/plugin-manager/README.zh.md +++ b/packages/boot/plugin-manager/README.zh.md @@ -28,9 +28,9 @@ kind: "package-reference" ## 使用本包 -基于 base 的 profile 提供管理服务。在 Web 中，侧边栏的**插件**页（[ui-plugin-manager](../../client/ui-plugin-manager/README.zh.md)）管理 profile 的组合包及其能唯一定位的行；设置页的插件列表保持只读。Agent 预设条目保持只读。`plugin_manager` 工具提供相同操作，在标准和 Creator 预设中启用。其他预设仍默认禁用。每个工具操作都要求 `danger-full-access` 或本次调用的批准。在较低沙箱模式下，`ask` 会请求审批；`never`、拒绝、取消或审批渠道不可用时均不执行。批准不改变会话的权限模式。profile 变更跨会话持久化，已安装的 Host 代码在宿主进程内运行，不受工作区沙箱限制。依赖构建脚本仍需单独批准。 +基于 base 的 profile 提供管理服务。在 Web 中，侧边栏的**插件**页（[ui-plugin-manager](../../client/ui-plugin-manager/README.zh.md)）管理 profile 的组合包及其能唯一定位的行；设置页的插件列表保持只读。Agent 预设条目保持只读。`plugin_manager` 工具提供相同操作，在标准和 Creator 预设中启用。其他 Web 预设仍默认禁用。完整 SDK profile 在 profile 作用域为 native/PTC 模式启用此工具；没有 HMR 时，保存的变更返回 `restart-required` 和 `no-hmr`，在运行时重启后应用。每个工具操作都要求 `danger-full-access` 或本次调用的批准。在较低沙箱模式下，`ask` 会请求审批；`never`、拒绝、取消或审批渠道不可用时均不执行。批准不改变会话的权限模式。profile 变更跨会话持久化，已安装的 Host 代码在宿主进程内运行，不受工作区沙箱限制。依赖构建脚本仍需单独批准。 -未使用 Agent 预设的部署在 profile patch 中启用工具；使用预设的会话由其预设中的 `tool-plugin-manager` 条目控制。 +除完整 SDK profile 外，未使用 Agent 预设的部署在 profile patch 中启用工具；安装/移除包要求 PATH 中有 pnpm，或显式配置 `pnpmCommand`，启动器提供的包管理器优先；使用预设的会话由其预设中的 `tool-plugin-manager` 条目控制。 ```yaml - id: tool-plugin-manager @@ -57,7 +57,7 @@ kind: "package-reference" `updateBundle(name, version, options)` 把可更新的组合包替换为一个更新的确切版本；更旧的版本会被拒绝。目标版本先按与 `listVersions` 相同的计划查询，版本不存在、未声明组合包，或其 `engines.dsh` 或 DSH peer 拒绝当前 DSH 时，更新停在 `step: 'check'`，profile 保持不变。有 HMR 时，更新先移除已安装版本，使其插件停止，再以 `saveExact` 和当前的选中状态从作答的注册表安装 `name@version`。该安装失败、被取消，或已安装但无法启动时，先移除仍留下的目标版本，再从本进程安装被移除版本所用的注册表重新安装它，没有记录时按配置的计划安装，与移除的做法一致，结果以 `restore` 报告；重新安装也失败时，包处于未安装状态。移除或安装被拒绝（例如锁等待超时）时，报告为该步骤失败。没有 HMR 时，目标版本直接安装在运行中的版本之上，结果报告 `restart-required`。`plugin-manager/update-state` 以调用方的 `requestId` 通告 `checking`、`removing`、`installing` 与 `restoring`；目标版本的安装以同一 id 流式输出日志并接受 `cancelInstall`，重新安装不带 id，因此取消无法中止它。 -`installBundle` 在启动 pnpm 前通过 `git ls-remote` 检查 GitHub 仓库，使用 profile 目录及安装器的 Git 与代理配置。`githubConnectionTimeoutMs` 默认为 5000 毫秒，只限制这次检查，不限制包下载或构建。检查禁用凭据助手和认证提示；只有网络失败与超时会停止安装，通过现有失败类型与诊断日志返回，并标记 `failedAt: 'spec-host'`。认证、仓库查找及其他失败继续交给 pnpm，包括其 HTTPS 到 SSH 的回退。取消安装或销毁管理器会停止检查及其子进程。注册表包、本地路径、压缩包和其他 Git 主机跳过此检查。仓库可达后，下载或组合包验证仍可能失败。 +`installBundle` 在启动 pnpm 前通过 `git ls-remote` 检查 GitHub 仓库，使用 profile 目录及安装器的 Git 与代理配置。`githubConnectionTimeoutMs` 默认为 5000 毫秒，只限制这次检查，不限制包下载或构建。检查禁用凭据助手和认证提示；只有网络失败与超时会停止安装，通过现有失败类型与诊断日志返回，并标记 `failedAt: 'spec-host'`。被停止的安装会以调用方的 `requestId` 把该失败转发为这次安装唯一的 `plugin-manager/install-log` 运行，其命令行是去掉 URL 用户信息的 `git ls-remote`；因超时结束的检查不报告退出码。应答中的 `packageResult` 仍是普通结果，不含该命令行。认证、仓库查找及其他失败继续交给 pnpm，包括其 HTTPS 到 SSH 的回退。取消安装或销毁管理器会停止检查及其子进程。注册表包、本地路径、压缩包和其他 Git 主机跳过此检查。仓库可达后，下载或组合包验证仍可能失败。 HTTP(S) Git URL 指向 pnpm 没有 HTTPS 到 SSH 回退的主机（即 `hosted-git-info` 不认识的任何主机，例如自托管 GitLab）时，在启动 pnpm 前通过 `git ls-remote` 探测。探测使用安装器的 Git 配置与凭据助手，并禁用 Git 的终端与 askpass 提示；在 POSIX 上探测也没有控制终端，因此 SSH 无法提示。HTTP(S) 无法读取仓库而 `ssh://git@/` 可以读取时，pnpm 以该 SSH URL 加上原片段安装，profile 也记录该 URL。否则按原 spec 安装。每次探测受 `gitTransportTimeoutMs` 限制，默认为 5000 毫秒；取消安装或销毁管理器会停止探测。带凭据或查询串的 URL 跳过探测。 @@ -65,7 +65,7 @@ HTTP(S) Git URL 指向 pnpm 没有 HTTPS 到 SSH 回退的主机（即 `hosted-g 可在浏览器使用的 `@deepseek-ai/dsh-plugin-manager/registry` 入口导出 `OFFICIAL_NPM_REGISTRY` 和 `NPMMIRROR_REGISTRY`，供消费方识别这两个公共注册表。 -`installBundle` 接受调用方生成的 `requestId`，`plugin-manager/install-log` 在其下流式转发每次 pnpm 运行的输出，`plugin-manager/install-state` 通告 `installing`、`cancelling` 与 `applying`；每问一个注册表通告一次 `installing`，`attempt` 带上这次的注册表、序号和计划长度。安装沿用查询的计划，从 `options.registry` 开始，以 `--registry` 运行 `pnpm add`，两次尝试之间恢复 profile 文件；换一个注册表能改变的失败才转问下一个，其他失败即停，错误行点名 git 或 tarball spec 自身拉取主机的失败也停，因为没有注册表能替代那台主机；`failedAt` 说明最后一次失败的运行连不上的是二者中的哪一个。`cancelInstall(requestId)` 停止运行，只在 Git 检查或 pnpm 退出且文件恢复后答复 `cancelled`，组合包已在应用时答复 `too-late`，其他 id 答复 `not-running`；安装调用随后报告 `application: 'cancelled'`。失败、被取消或装入了没有组合包 patch 的包的运行，会把 `package.json` 与 `pnpm-lock.yaml` 恢复原样；`packageResult.kind` 按退出方式与输出对最后一次运行分类，`registries` 列出问过的每个注册表，`bundle` 给出完成的运行新增的包，`version` 给出它的清单版本，它可能与 `inspect` 读到的版本不同，例如 pnpm 的 `minimumReleaseAge` 暂缓了最近的发布。`listBundles` 携带每个组合包的一句话简介（包的 `description`）、其 patch 声明的行及其存活条目，以及它覆盖的内置行；它列出 profile 自己的组合包、安装提供的组合包，以及被选中却没有组合包 patch 的名字（作为 `not-bundle` 问题），未选中的普通依赖不列出。启动器的 `OPTIONAL_BUNDLES` 点名的组合包是 `optional`：随安装提供、默认关闭、由用户开启，永不可卸载，也不被任何随附模板选中（[理由](../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.zh.md)）。每个完成的操作都会发出 `plugin-manager/changed`；在管理器之外应用的一代 patch（HMR 监视到 CLI 或手工编辑后）不发通知，页面要到下一次读取才知道。 +`installBundle` 接受调用方生成的 `requestId`，`plugin-manager/install-log` 在其下流式转发每次 pnpm 运行的输出，`plugin-manager/install-state` 通告 `installing`、`cancelling` 与 `applying`；未打印任何输出就失败的 pnpm 运行转发其日志中的诊断，详情面板因而不会为空。每问一个注册表通告一次 `installing`，`attempt` 带上这次的注册表、序号和计划长度。安装沿用查询的计划，从 `options.registry` 开始，以 `--registry` 运行 `pnpm add`，两次尝试之间恢复 profile 文件；换一个注册表能改变的失败才转问下一个，其他失败即停，错误行点名 git 或 tarball spec 自身拉取主机的失败也停，因为没有注册表能替代那台主机；`failedAt` 说明最后一次失败的运行连不上的是二者中的哪一个。`cancelInstall(requestId)` 停止运行，只在 Git 检查或 pnpm 退出且文件恢复后答复 `cancelled`，组合包已在应用时答复 `too-late`，其他 id 答复 `not-running`；安装调用随后报告 `application: 'cancelled'`。失败、被取消或装入了没有组合包 patch 的包的运行，会把 `package.json` 与 `pnpm-lock.yaml` 恢复原样；`packageResult.kind` 按退出方式与输出对最后一次运行分类，`registries` 列出问过的每个注册表，`bundle` 给出完成的运行新增的包，`version` 给出它的清单版本，它可能与 `inspect` 读到的版本不同，例如 pnpm 的 `minimumReleaseAge` 暂缓了最近的发布。`listBundles` 携带每个组合包的一句话简介（包的 `description`）、其 patch 声明的行及其存活条目，以及它覆盖的内置行；它列出 profile 自己的组合包、安装提供的组合包，以及被选中却没有组合包 patch 的名字（作为 `not-bundle` 问题），未选中的普通依赖不列出。启动器的 `OPTIONAL_BUNDLES` 点名的组合包是 `optional`：随安装提供、默认关闭、由用户开启，永不可卸载，也不被任何随附模板选中（[理由](../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.zh.md)）。每个完成的操作都会发出 `plugin-manager/changed`；在管理器之外应用的一代 patch（HMR 监视到 CLI 或手工编辑后）不发通知，页面要到下一次读取才知道。 `waitForInstall(requestId)` 让客户端在响应丢失后等待活动安装的结果，包括不可取消的应用阶段。它返回与原调用相同的结果，请求不在活动中时返回 `null`。已完成的结果不保留；`null` 不表示成功或已取消。 @@ -129,6 +129,10 @@ service 运行若在 `idleTimeoutMs` 内没有任何捕获输出即被终止， 结果包含最后尝试的阶段、目标、磁盘变化、应用状态和错误码。Web 词典呈现管理文案；pnpm 与 Loader 的诊断保持原样。无关的已有故障作为警告返回；新出现、配置变化后的故障，以及显式启用目标未激活，都会使操作失败。包管理运行失败或被取消，或组合包校验失败时，会恢复 pnpm 运行前快照的 manifest 与 lockfile（[理由](../../../.agents/notes/implemented/architecture/2026-09-15-guided-plugin-installation.zh.md)）；后续失败按[失败行为](#failure-behavior)所述保留已保存的改动。安装按 request id 跟踪到调用结束，因此取消只针对一次运行，并且不取 profile 锁就能等待它结束。CLI 继承认证环境和终端描述符；service 使用清理后的环境并捕获输出。管理器直接读取文件和 Loader 状态，不维护第二份目标状态注册表，因此不发布单独的运行时不变式伴生入口。 +`plugin-manager/operation` 事件关联每次服务调用的开始和已观察到的结果；若异常使结果无法构造，则记录结果未知。安装目标仅保留解析出的 registry 包名；启停或移除包的目标必须与包名完全一致，不能含版本范围或首尾空格；插件目标仅保留已知条目 ID。记录的目标不要求已安装；需要读取包文件的操作仍会拒绝不存在的包。版本豁免记录保留已校验的包名和精确豁免版本，而不是当前安装版本。包或运行时任一身份非法时，目标记为 null，版本省略。豁免复用 reason `bundle`、stage `enable` 和豁免的 `enabled` 值；豁免版本与安装版本相同时，记录无法区分豁免变更与 bundle 开关。版本表示加锁前请求时观察到的值或安装解析出的值；非法或过长的元数据被省略，不丢弃操作记录。平台拒绝保留 `unsupported-platform` 错误码。事件不包含原始 spec 和错误文本。订阅者独立执行，不延迟管理操作；同步抛错和异步拒绝都不会阻断后续订阅者或改变结果。直接执行的 CLI 包操作不发送此服务事件。 + +`@deepseek-ai/dsh-plugin-manager/diagnostic` 入口为 Desktop Host 和壳读取器提供运行 ID、操作记录及仅保留白名单字段的解析器。格式错误或超限记录会被拒绝；读取器报告遗漏和截断。壳仅接受其 Host 已声明运行 ID 对应的记录。诊断消费者负责持久化和传输限额；缺失记录不能说明操作成功。 + ----- diff --git a/packages/boot/plugin-manager/package.json b/packages/boot/plugin-manager/package.json index 3822c32f62..cee821053b 100644 --- a/packages/boot/plugin-manager/package.json +++ b/packages/boot/plugin-manager/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-plugin-manager", "description": "Current-profile plugin and bundle management shared by dsh CLI, Web and agent tools", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -45,7 +45,11 @@ "default": "./lib/types/tools.js" }, "./tools/locale/*.json": "./locale/tools/*.json", - "./locale/*.json": "./locale/*.json" + "./locale/*.json": "./locale/*.json", + "./diagnostic": { + "types": "./lib/types/diagnostic.d.ts", + "default": "./lib/types/diagnostic.js" + } }, "files": [ "locale/*.json", diff --git a/packages/boot/plugin-manager/src/diagnostic.ts b/packages/boot/plugin-manager/src/diagnostic.ts new file mode 100644 index 0000000000..aa79fe5527 --- /dev/null +++ b/packages/boot/plugin-manager/src/diagnostic.ts @@ -0,0 +1,85 @@ +/** Whitelisted operation records shared by diagnostic transport and durable readers. */ +import { z } from 'zod' +import type { Branded } from '@deepseek-ai/dsh-brand' +import type { ChangeResult, ManagementError, PluginChange, PluginOperation, PluginOperationId, RestartReason } from './types.ts' + +/** Identifies the process lifetime which observed management operations. */ +export type PluginOperationRunId = Branded<'PluginOperationRunId'> + +/** One diagnostic event; omissions and unknown outcomes must not be interpreted as successful operations. */ +export interface PluginOperationRecord { + readonly runId: PluginOperationRunId + readonly operation: PluginOperation + readonly transportDropped: number +} + +const fields = { + id: z.uuid().transform(value => value as PluginOperationId), + time: z.iso.datetime(), + reason: z.enum({ + 'plugin': 'plugin', + 'bundle': 'bundle', + 'install': 'install', + 'remove': 'remove', + } satisfies { [K in PluginChange['reason']]: K }), + target: z.string().max(256).nullable(), + stage: z.enum({ + 'install': 'install', + 'enable': 'enable', + 'remove': 'remove', + } satisfies { [K in ChangeResult['stage']]: K }), + enabled: z.boolean().optional(), + version: z.string().max(128).optional(), +} +const operation: z.ZodType = z.discriminatedUnion('phase', [ + z.object({ ...fields, phase: z.literal('started') }), + z.object({ ...fields, phase: z.literal('unknown') }), + z.object({ ...fields, phase: z.literal('settled'), + application: z.enum({ + 'applied': 'applied', + 'restart-required': 'restart-required', + 'overridden': 'overridden', + 'failed': 'failed', + 'cancelled': 'cancelled', + } satisfies { [K in ChangeResult['application']]: K }), + changed: z.boolean(), + errorCode: z.enum({ + 'management-required': 'management-required', + 'unaddressable': 'unaddressable', + 'unknown-plugin': 'unknown-plugin', + 'invalid-spec': 'invalid-spec', + 'already-installed': 'already-installed', + 'ambiguous-install': 'ambiguous-install', + 'not-bundle': 'not-bundle', + 'not-removable': 'not-removable', + 'stop-profile': 'stop-profile', + 'bundle-in-use': 'bundle-in-use', + 'stale-approval': 'stale-approval', + 'incompatible-version': 'incompatible-version', + 'unsupported-platform': 'unsupported-platform', + 'operation-error': 'operation-error', + } satisfies { [K in ManagementError['code']]: K }).optional(), + restartReason: z.enum({ + 'no-hmr': 'no-hmr', + 'package-moved': 'package-moved', + 'host-module': 'host-module', + 'unmanaged-plugin': 'unmanaged-plugin', + 'module-comparison': 'module-comparison', + } satisfies { [K in RestartReason]: K }).optional(), + }), +]) +const record = z.object({ + runId: z.uuid().transform(value => value as PluginOperationRunId), + operation, + transportDropped: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER), +}) + +/** + * Validate transport/file data and discard fields outside the diagnostic whitelist. + * @param value - Untrusted decoded JSON. + * @returns A bounded record, or undefined for malformed, oversized or unsupported records. + */ +export function parsePluginOperationRecord(value: unknown): PluginOperationRecord | undefined { + const parsed = record.safeParse(value) + return parsed.success ? parsed.data : undefined +} diff --git a/packages/boot/plugin-manager/src/github-connection.ts b/packages/boot/plugin-manager/src/github-connection.ts index 99b64fd73c..e2d349c734 100644 --- a/packages/boot/plugin-manager/src/github-connection.ts +++ b/packages/boot/plugin-manager/src/github-connection.ts @@ -4,9 +4,21 @@ import { join } from 'node:path' import { execa } from 'execa' import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess' import { classifyInstallFailure } from './install-failure.ts' -import type { ParsedInstallSpec } from './install-spec.ts' +import { HTTP_USER_INFO, type ParsedInstallSpec } from './install-spec.ts' import type { PackageResult } from './types.ts' +/** + * A failed check, with the Git command line the install dialog shows as the installation's only run. + * The returned result itself stays a plain {@link PackageResult}: the command line never joins the wire fields. + */ +export interface GithubConnectionFailure extends PackageResult { + /** + * The `git` command line the check ran, with the user information of an http(s) repository URL removed: + * `git -c credential.helper= ls-remote -- HEAD`. + */ + readonly argv: readonly string[] +} + /** Deadline, diagnostics and cancellation for one read-only GitHub check. */ export interface GithubConnectionOptions { timeoutMs: number @@ -23,11 +35,12 @@ export interface GithubConnectionOptions { * @param spec The parsed installation address; npm packages, local paths and other hosts are not checked. * @param dir The profile directory where installation runs. * @param options The connection deadline, output bound and operation cancellation. - * @returns A failed check with bounded output and a complete log at logPath, or undefined for a reachable repository or an unhandled spec. + * @returns A failed check carrying the command line it ran (without URL user information) and its bounded output, with a + * complete log at logPath, or undefined for a reachable repository or an unhandled spec. */ export async function checkGithubConnection( spec: ParsedInstallSpec, dir: string, options: GithubConnectionOptions, -): Promise { +): Promise { if (spec.kind !== 'git') return undefined const host = spec.host.toLowerCase().replace(/:.*$/, '') if (host !== 'github.com' && !host.endsWith('.github.com')) return undefined @@ -40,8 +53,12 @@ export async function checkGithubConnection( const logDir = await mkdtemp(join(logRoot, 'github-connection-')) const logPath = join(logDir, 'git.log') const log = await open(logPath, 'ax+', 0o600) + const argv = ['git', '-c', 'credential.helper=', 'ls-remote', '--', repository, 'HEAD'] as const + // The executed command keeps any credentials the spec names; the recorded one drops them before it is displayed. + const recordedArgv = argv.map(argument => argument.replace(HTTP_USER_INFO, '$1')) + const [command, ...args] = argv try { - const result = await execa('git', ['-c', 'credential.helper=', 'ls-remote', '--', repository, 'HEAD'], { + const result = await execa(command, args, { cwd: dir, env: { ...scrubbedParentEnv(), ...options.env, LC_ALL: 'C', GIT_TERMINAL_PROMPT: '0', @@ -58,9 +75,13 @@ export async function checkGithubConnection( const bytes = Buffer.alloc(Math.min(size, options.outputBytes)) await log.read(bytes, 0, bytes.length, size - bytes.length) const output = bytes.toString('utf8') + // `PackageResult.exitCode` is a status number, so a Git the deadline stopped records the status its failure is read + // as. The run streamed for the same failure reports no exit code, because that process ended without one. return { - exitCode: result.exitCode ?? (result.code === 'ENOENT' ? 127 : 1), output, truncated: size > options.outputBytes, logPath, + argv: recordedArgv, exitCode: result.exitCode ?? (result.code === 'ENOENT' ? 127 : 1), + output, truncated: size > options.outputBytes, logPath, kind: classifyInstallFailure({ log: output, timedOut: result.timedOut }), + ...result.timedOut ? { timedOut: true } : {}, } } finally { await log.close() diff --git a/packages/boot/plugin-manager/src/index.ts b/packages/boot/plugin-manager/src/index.ts index 0d138d9996..ceb82aac47 100644 --- a/packages/boot/plugin-manager/src/index.ts +++ b/packages/boot/plugin-manager/src/index.ts @@ -21,7 +21,7 @@ import { readPluginMeta, readProfileManifest, resolveBundleDir, loadOverlayPatches, composeEntries, readProfilePatches, bundlePatchPaths, evaluatePluginCompatibility, readProfileCompatibility, readProfileVersionExemptions, - setProfileVersionExemption, PROFILE_COMPATIBILITY_FILENAME, + setProfileVersionExemption, validatePluginVersionExemption, PROFILE_COMPATIBILITY_FILENAME, getDshRuntimeVersion, ResolutionRestartRequired, assertBundlePlatform, UnsupportedBundlePlatformError, } from '@deepseek-ai/dsh-app-boot' @@ -36,7 +36,7 @@ import { attributeFailure, normalizeRegistry, NPMMIRROR_REGISTRY, registryPlan } import { flatten, writePluginEnabled } from './patch.ts' import { incompatiblePlugin, ManagementFailure } from './failure.ts' import { approveBuilds, recordPendingBuilds } from './build-approval.ts' -import { checkGithubConnection } from './github-connection.ts' +import { checkGithubConnection, type GithubConnectionFailure } from './github-connection.ts' import { chooseGitTransport, sshGitSpec } from './git-transport.ts' import { newerVersions, VERSION_FIELDS, VERSION_LIST_FIELDS, versionFacts } from './versions.ts' import type { @@ -44,6 +44,7 @@ import type { PackageResult, PluginChange, PluginEntryId, PluginInfo, PluginInstallCancellation, PluginInstallProgress, PluginInstallRequestId, PluginRegistries, PluginSpecInspection, PluginUpdateResult, PluginUpdateStep, PluginVersion, PluginVersionList, Registry, RegistryAttempt, UpdateBundleOptions, + PluginOperation, PluginOperationId, } from './types.ts' export type * from './types.ts' export { classifyInstallFailure, type InstallFailureFacts } from './install-failure.ts' @@ -278,6 +279,28 @@ function parsedForRegistry(spec: string): ParsedInstallSpec { } } +/** Only registry package names are retained before installation resolves its target. */ +function installOperationTarget(spec: string): string | null { + let parsed: ParsedInstallSpec + try { parsed = parseInstallSpec(spec) } + catch (_error) { return null /* Invalid specs remain private; installation owns their refusal. */ } + return parsed.kind === 'registry' ? parsed.name : null +} + +/** Exemption facts use canonical package identity, never the raw request or installed version. */ +function exemptionOperationIdentity(packageVersion: string, runtimeVersion: string): Pick { + try { validatePluginVersionExemption(packageVersion, runtimeVersion) } + catch (_error) { return { target: null } /* The operation still owns validation failure reporting. */ } + const separator = packageVersion.lastIndexOf('@') + return { target: installOperationTarget(packageVersion.slice(0, separator)), + version: diagnosticVersion(packageVersion.slice(separator + 1)) } +} + +/** Unusable file metadata must not discard the rest of an operation record. */ +function diagnosticVersion(value: unknown): string | undefined { + return typeof value === 'string' && value.length <= 128 ? value : undefined +} + declare module '@deepseek-ai/cordis' { interface Context { /** Persistent management of the current profile's composition and packages. */ @@ -432,7 +455,7 @@ export class PluginManager extends TypertRemoteService { return this.change(result => this.configure(async () => { await setProfileVersionExemption(this.profile.dir, packageVersion, runtimeVersion, enabled, acceptRisk === true) Object.assign(result, await this.reload()) - }), { stage: 'enable', target: packageVersion, enabled }, 'bundle') + }), { stage: 'enable', target: packageVersion, enabled }, 'bundle', exemptionOperationIdentity(packageVersion, runtimeVersion)) } /** Read current plugins, including why a row cannot be changed through the profile patch. @@ -499,6 +522,7 @@ export class PluginManager extends TypertRemoteService { catch (error) { platformError = managementError(error) } const error = platformError ?? targetError ?? (enabled ? { code: 'not-bundle' as const } : undefined) bundles.push({ name, official, availability: 'missing', ...catalogMeta, ...target, enabled, installed, optional, + ...offered.listedByDefault === undefined ? {} : { listedByDefault: offered.listedByDefault }, ...platformError?.code === 'unsupported-platform' ? { listedByDefault: false } : {}, removable: enabled, rows: [], overrides: [], ...error === undefined ? {} : { error } }) @@ -834,7 +858,8 @@ export class PluginManager extends TypertRemoteService { /** * Install a package using the same pnpm implementation as dsh plugin. GitHub * repositories get a connection check bounded by githubConnectionTimeoutMs before pnpm starts; - * only network failures or timeouts stop installation, while pnpm owns authentication and transport fallback. An + * only network failures or timeouts stop installation, and a stop streams the check's diagnostic + * as the installation's install-log run under its request id, while pnpm owns authentication and transport fallback. An * HTTP(S) Git URL on another host is installed over SSH instead when access probes bounded by gitTransportTimeoutMs * find that only SSH can read it. A run * that fails, is cancelled, or adds a package without a bundle patch restores @@ -878,13 +903,23 @@ export class PluginManager extends TypertRemoteService { timeoutMs: this.githubConnectionTimeoutMs, outputBytes: this.outputBytes, signal, ...env, }) this.packageOperations.add(connection) - let connectionFailure: PackageResult | undefined + let connectionFailure: GithubConnectionFailure | undefined try { connectionFailure = await connection } finally { this.packageOperations.delete(connection) } if (stopped()) throw new InstallCancelledError() if (connectionFailure?.kind === 'network' || connectionFailure?.kind === 'timeout') { - result.packageResult = connectionFailure + // The answer keeps a plain PackageResult; the check's command line is only streamed as the run below. + const { argv, ...packageResult } = connectionFailure + result.packageResult = packageResult result.failedAt = 'spec-host' + // pnpm never runs, so the check is the installation's only run: stream its failure into the install log. + // A timed-out Git reports no exit code of its own, unlike the result, which records the status it is read as. + if (requestId !== undefined) { + this.ownerContext.emit('plugin-manager/install-log', { + requestId, jobId: randomUUID(), argv, cwd: this.profile.dir, stream: 'stderr', + text: connectionFailure.output, exitCode: connectionFailure.timedOut === true ? null : connectionFailure.exitCode, + }) + } throw new Error(connectionFailure.output) } const transport = chooseGitTransport(parsed, this.profile.dir, { timeoutMs: this.gitTransportTimeoutMs, signal, ...env }) @@ -1226,30 +1261,86 @@ export class PluginManager extends TypertRemoteService { operation: (result: ChangeResult) => Promise, request: Pick, reason: PluginChange['reason'], + identity?: Pick, ): Promise { - return withFileLock(join(this.profile.dir, 'package.json'), async () => { - this.abort.signal.throwIfAborted() - const before = this.diskState() - const result: ChangeResult = { ...request, changed: false, - ...this.ownerContext.get('hmr') !== undefined ? { application: 'applied' } : { application: 'restart-required', restartReason: 'no-hmr' } } - try { - const outcome = await operation(result) - if (outcome !== undefined) result.application = outcome - // A reload that waits for a restart leaves the change saved but not applied. - else if (result.application === 'applied' && result.restartReason !== undefined) result.application = 'restart-required' - } catch (error) { - if (error instanceof InstallCancelledError) { - result.application = 'cancelled' - } else { - result.application = 'failed' - result.error = managementError(error) + const id = randomUUID() as PluginOperationId + const target = identity === undefined ? this.operationTarget(reason, request.target) : identity.target + const version = identity === undefined ? this.operationVersion(reason, reason === 'plugin' ? request.target : target) : identity.version + const facts = { id, reason, stage: request.stage, + target, + ...version === undefined ? {} : { version }, + ...request.enabled === undefined ? {} : { enabled: request.enabled } } + this.reportOperation({ ...facts, time: new Date().toISOString(), phase: 'started' }) + let settled: ChangeResult + try { + settled = await withFileLock(join(this.profile.dir, 'package.json'), async () => { + this.abort.signal.throwIfAborted() + const before = this.diskState() + const result: ChangeResult = { ...request, changed: false, + ...this.ownerContext.get('hmr') !== undefined ? { application: 'applied' } : { application: 'restart-required', restartReason: 'no-hmr' } } + try { + const outcome = await operation(result) + if (outcome !== undefined) result.application = outcome + // A reload that waits for a restart leaves the change saved but not applied. + else if (result.application === 'applied' && result.restartReason !== undefined) result.application = 'restart-required' + } catch (error) { + if (error instanceof InstallCancelledError) { + result.application = 'cancelled' + } else { + result.application = 'failed' + result.error = managementError(error) + } } - } - if (result.application !== 'restart-required') delete result.restartReason - result.changed = before !== this.diskState() - this.ownerContext.emit('plugin-manager/changed', { reason }) - return result - }, { waitMs: this.lockWaitMs }) + if (result.application !== 'restart-required') delete result.restartReason + result.changed = before !== this.diskState() + this.ownerContext.emit('plugin-manager/changed', { reason }) + return result + }, { waitMs: this.lockWaitMs }) + } catch (error) { + this.reportOperation({ ...facts, time: new Date().toISOString(), phase: 'unknown' }) + throw error + } + const refusedVersion = reason === 'install' + ? settled.error?.incompatible?.find(plugin => plugin.name === facts.target)?.version + : undefined + const observedVersion = diagnosticVersion(settled.version ?? refusedVersion) + this.reportOperation({ ...facts, time: new Date().toISOString(), phase: 'settled', + stage: settled.stage, target: settled.bundle === undefined ? facts.target : installOperationTarget(settled.bundle), + application: settled.application, changed: settled.changed, + ...observedVersion === undefined ? {} : { version: observedVersion }, + ...settled.error === undefined ? {} : { errorCode: settled.error.code }, + ...settled.restartReason === undefined ? {} : { restartReason: settled.restartReason } }) + return settled + } + + private reportOperation(operation: PluginOperation): void { + void this.ownerContext.parallel('plugin-manager/operation', operation).catch((_error: unknown) => { + // All subscribers run; diagnostic failures cannot change the management result. + console.error('dsh plugin-manager: operation diagnostic delivery failed') + }) + } + + private operationTarget(reason: PluginChange['reason'], target: string): string | null { + if (reason !== 'plugin') { + const name = installOperationTarget(target) + return reason === 'install' || name === target ? name : null + } + return target.length <= 256 && [...this.ctx.loader.entries()].some(entry => entry.id === target) ? target : null + } + + /** Read the request-time package version without preventing recovery from damaged metadata. */ + private operationVersion(reason: PluginChange['reason'], target: string | null): string | undefined { + if (reason === 'install' || target === null) return undefined + try { + if (reason !== 'plugin') return diagnosticVersion(bundleManifest(target, this.profile.dir, this.profile.installAnchor)?.version) + const entry = [...this.ctx.loader.entries()].find(row => row.id === target) + const source = entry?.parent.tree.ctx.baseUrl + if (entry === undefined || source === undefined) return undefined + return diagnosticVersion(this.ownerContext.get('pluginPackages')?.packageOf(entry.options.name, source)?.version) + } catch (_error) { + // Disabling or removing a broken package must not depend on diagnostic metadata being readable. + return undefined + } } private diskState(): string { diff --git a/packages/boot/plugin-manager/src/install-spec.ts b/packages/boot/plugin-manager/src/install-spec.ts index 4b76f1925e..2fb6b64cca 100644 --- a/packages/boot/plugin-manager/src/install-spec.ts +++ b/packages/boot/plugin-manager/src/install-spec.ts @@ -94,7 +94,7 @@ export function parseInstallSpec(raw: string): ParsedInstallSpec { /** A recorded dependency value pnpm resolves outside a registry: a protocol other than a registry alias, or an scp-like git address. */ const NON_REGISTRY_VALUE = /^(?!(?:npm|jsr|workspace|catalog):)[a-z][a-z0-9+.-]*:|^[^@/:\s]+@[^:/\s]+:/i /** The user information of an http(s) URL, up to the last `@` before the path, which holds a password or access token when present. */ -const HTTP_USER_INFO = /^((?:git\+)?https?:\/\/)[^/]*@/i +export const HTTP_USER_INFO = /^((?:git\+)?https?:\/\/)[^/]*@/i /** * The spec `pnpm add` accepts for a dependency the profile manifest records. A git address, URL, or other diff --git a/packages/boot/plugin-manager/src/operations.ts b/packages/boot/plugin-manager/src/operations.ts index e7b761ad3c..d0ab1dccab 100644 --- a/packages/boot/plugin-manager/src/operations.ts +++ b/packages/boot/plugin-manager/src/operations.ts @@ -470,6 +470,8 @@ export async function runProfilePnpm( if (result.failed && output.length === 0) { const diagnostic = result.shortMessage ?? 'pnpm failed' await log.write(diagnostic) + // The run printed nothing, so this diagnostic is the whole of its captured output; stream it as such. + options.onOutput?.(diagnostic, 'stderr') truncated = Buffer.byteLength(diagnostic) > options.outputBytes output = Buffer.from(diagnostic).subarray(0, options.outputBytes) } diff --git a/packages/boot/plugin-manager/src/types.ts b/packages/boot/plugin-manager/src/types.ts index 1e72222e81..221607f1e8 100644 --- a/packages/boot/plugin-manager/src/types.ts +++ b/packages/boot/plugin-manager/src/types.ts @@ -139,13 +139,18 @@ export type PluginInstallFailureKind = /** Package operation completion, including Git checks and a retrieval path for unabridged diagnostics. */ export interface PackageResult { + /** The status the run is read as having ended with; a run the manager terminated records the coerced status 1. */ exitCode: number output: string truncated: boolean logPath: string /** Present when the run failed: what kind of failure its exit and output describe. */ kind?: PluginInstallFailureKind - /** The manager terminated the run after it printed nothing for its silence bound; `exitCode` still reports how it ended. */ + /** + * The run outlived its bound: the manager terminated it after it printed nothing for its silence bound, or the GitHub + * connection check hit its deadline. Such a run reports no exit status of its own, so `exitCode` records the status + * its failure is read as rather than a status the process returned. + */ timedOut?: boolean /** Present when a compatibility check refused the run: the packages the running DSH version rejects. */ incompatible?: IncompatiblePlugin[] @@ -344,19 +349,19 @@ export interface PluginInstallCancellation { readonly status: 'cancelled' | 'too-late' | 'not-running' } -/** One chunk of a pnpm run's output, as the run produces it. */ +/** One chunk of an installation run's output: a pnpm run, or the GitHub connection check that stopped it. */ export interface PluginInstallLogChunk { /** The installation the run belongs to, when its caller supplied a request id. */ readonly requestId?: PluginInstallRequestId /** The run the chunk belongs to. */ readonly jobId: string - /** The command line the run executes: pnpm's command name, then its arguments. */ + /** The command line the run executes: its command name, then its arguments. */ readonly argv: readonly string[] /** The directory the run executes in: the profile directory. */ readonly cwd: string readonly stream: 'stdout' | 'stderr' readonly text: string - /** Present on the run's last chunk: pnpm's exit code, null when it ended without one. */ + /** Present on the chunk that ends a run: its exit code, null when the run ended without one. */ readonly exitCode?: number | null } @@ -382,8 +387,41 @@ export interface PluginChange { readonly reason: 'plugin' | 'bundle' | 'install' | 'remove' } +/** Identifies one manager invocation, including time spent waiting for its profile lock. */ +export type PluginOperationId = Branded<'PluginOperationId'> + +/** Management facts for diagnostic consumers; recent operations do not establish a crash's cause. */ +export type PluginOperation = { + readonly id: PluginOperationId + readonly time: string + readonly reason: PluginChange['reason'] + /** Known entry id or parsed registry package name; unrecognized targets and raw specs are omitted. */ + readonly target: string | null + readonly stage: ChangeResult['stage'] + readonly enabled?: boolean | undefined + /** Request-time or resolved package version; absence means unusable or unavailable, never the latest registry version. */ + readonly version?: string | undefined +} & ( + | { readonly phase: 'started' } + | { + readonly phase: 'settled' + readonly application: ChangeResult['application'] + readonly changed: boolean + readonly errorCode?: ManagementError['code'] | undefined + readonly restartReason?: RestartReason | undefined + } + /** An exception escaped the operation result; persisted or applied changes cannot be inferred. */ + | { readonly phase: 'unknown' } +) + declare module '@deepseek-ai/cordis' { interface Events { + /** + * One manager invocation started or ended; subscribers run independently without delaying management. + * @mode parallel + * @param operation - Correlated operation facts; a start without an end has an unknown outcome. + */ + 'plugin-manager/operation'(operation: PluginOperation): void | Promise /** * The profile's plugins, bundles, or composition changed: a manager * operation completed. A patch generation applied outside the manager, @@ -393,7 +431,7 @@ declare module '@deepseek-ai/cordis' { */ 'plugin-manager/changed'(change: PluginChange): void /** - * One chunk of a pnpm run's output, streamed as the run produces it. + * One chunk of an installation run's output, streamed as the run produces it. * @mode emit * @param chunk - the chunk and the run it belongs to. */ diff --git a/packages/boot/plugin-manager/tests/diagnostic.spec.ts b/packages/boot/plugin-manager/tests/diagnostic.spec.ts new file mode 100644 index 0000000000..351e4d9556 --- /dev/null +++ b/packages/boot/plugin-manager/tests/diagnostic.spec.ts @@ -0,0 +1,34 @@ +import { expect, it } from 'vitest' +import { parsePluginOperationRecord } from '../src/diagnostic.ts' + +const input = { + runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, + operation: { id: 'c254ab28-97c9-4382-95e6-2db9c66f98c9', time: '2026-10-19T00:00:00.000Z', + reason: 'plugin', phase: 'settled', target: 'managed', stage: 'enable', changed: true, application: 'restart-required' }, +} + +it('keeps only diagnostic fields at both record levels', () => { + expect(parsePluginOperationRecord({ ...input, credential: 'secret', operation: { + ...input.operation, diagnostic: 'raw secret output', packageResult: { output: 'raw output' }, + } })).toEqual(input) +}) + +it('rejects unsupported phases, oversized identifiers and invalid result fields', () => { + for (const patch of [{ phase: 'future' }, { id: 'invalid' }, { target: 'x'.repeat(257) }, + { time: 'not a time' }, { changed: 'yes' }, { application: 'unknown-success' }, { errorCode: 'raw-message' }]) { + expect(parsePluginOperationRecord({ ...input, operation: { ...input.operation, ...patch } })).toBeUndefined() + } + expect(parsePluginOperationRecord({ ...input, transportDropped: -1 })).toBeUndefined() + expect(parsePluginOperationRecord({ ...input, runId: '' })).toBeUndefined() +}) + +it('retains an observed version before an operation settles', () => { + const started = { ...input, operation: { ...input.operation, phase: 'started', version: '1.2.3' } } + expect(parsePluginOperationRecord(started)?.operation).toMatchObject({ phase: 'started', version: '1.2.3' }) + expect(parsePluginOperationRecord({ ...started, operation: { ...started.operation, version: 'x'.repeat(129) } })).toBeUndefined() +}) + +it('retains platform refusals in settled operation records', () => { + const record = { ...input, operation: { ...input.operation, application: 'failed', changed: false, errorCode: 'unsupported-platform' } } + expect(parsePluginOperationRecord(record)).toEqual(record) +}) diff --git a/packages/boot/plugin-manager/tests/git-transport.spec.ts b/packages/boot/plugin-manager/tests/git-transport.spec.ts index 36d043b6b8..31fc22e6a0 100644 --- a/packages/boot/plugin-manager/tests/git-transport.spec.ts +++ b/packages/boot/plugin-manager/tests/git-transport.spec.ts @@ -26,7 +26,8 @@ const SSH_SPEC = `git+ssh://git@git.example/team/sub/plugin.git#${'a'.repeat(40) async function fixture() { const dir = await mkdtemp(join(tmpdir(), 'dsh-git-transport-')) - onTestFinished(() => rm(dir, { recursive: true, force: true })) + // Retry Windows directory-busy errors after awaited probe cleanup. + onTestFinished(() => rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })) const config = join(dir, 'git.config') await writeFile(config, '') const env = { GIT_CONFIG_GLOBAL: config, GIT_CONFIG_NOSYSTEM: '1' } diff --git a/packages/boot/plugin-manager/tests/github-connection.spec.ts b/packages/boot/plugin-manager/tests/github-connection.spec.ts index 33dd34e067..e87ac53b8c 100644 --- a/packages/boot/plugin-manager/tests/github-connection.spec.ts +++ b/packages/boot/plugin-manager/tests/github-connection.spec.ts @@ -43,6 +43,9 @@ async function fixture() { return { dir, config, controller, check, env } } +/** The exact command line a check runs for one repository URL. */ +const checkArgv = (repository: string): string[] => ['git', '-c', 'credential.helper=', 'ls-remote', '--', repository, 'HEAD'] + async function proxy(config: string, fail: boolean) { const sockets = new Set() const connected = Promise.withResolvers() @@ -93,7 +96,9 @@ it('reports an immediate transport failure without waiting for the deadline', as const transport = await proxy(config, true) const result = await check('https://github.com/acme/plugin.git') await transport.connected - expect(result).toMatchObject({ exitCode: 128, kind: 'network', truncated: false }) + expect(result).toMatchObject({ + exitCode: 128, kind: 'network', truncated: false, argv: checkArgv('https://github.com/acme/plugin.git'), + }) expect(await readFile(result!.logPath, 'utf8')).toBe(result!.output) await transport.disconnected expect(transport.sockets.size).toBe(0) @@ -106,6 +111,8 @@ it('ends a silent proxy connection and its Git child at the connection deadline' await transport.connected const result = await running expect(result?.kind).toBe('timeout') + // The result records the status the terminated Git is read as; only the streamed run reports no exit code. + expect(result).toMatchObject({ exitCode: 1, timedOut: true, argv: checkArgv('https://github.com/acme/plugin.git') }) expect(result!.output).toContain('connection to github.com timed out after 3000ms') await transport.disconnected expect(transport.sockets.size).toBe(0) @@ -128,12 +135,15 @@ it.each([undefined, 'Git could not start'])('retains a diagnostic when Git write const run = vi.spyOn(subprocess, 'execa').mockResolvedValue({ failed: true, shortMessage } as Awaited>) onTestFinished(() => { run.mockRestore() }) const result = await check('github:acme/plugin') - expect(result).toMatchObject({ exitCode: 1, kind: 'unknown', output: shortMessage ?? 'GitHub connection check failed' }) + expect(result).toMatchObject({ + exitCode: 1, kind: 'unknown', output: shortMessage ?? 'GitHub connection check failed', + argv: checkArgv('https://github.com/acme/plugin'), + }) expect(await readFile(result!.logPath, 'utf8')).toBe(result!.output) }) it('bounds returned diagnostics while retaining Git stderr in the operation log', async () => { - const { check } = await fixture() + const { check, dir } = await fixture() const run = vi.spyOn(subprocess, 'execa').mockImplementation((...args: unknown[]) => { const options = args[2] as { stderr: { file: string } } appendFileSync(options.stderr.file, '0123456789') @@ -141,10 +151,24 @@ it('bounds returned diagnostics while retaining Git stderr in the operation log' }) onTestFinished(() => { run.mockRestore() }) const result = await check('github:acme/plugin', 3000, 4) - expect(result).toMatchObject({ output: '6789', truncated: true }) + expect(result).toMatchObject({ output: '6789', truncated: true, argv: checkArgv('https://github.com/acme/plugin') }) + // The recorded command line is the one Git actually ran. + expect(run).toHaveBeenCalledWith('git', checkArgv('https://github.com/acme/plugin').slice(1), expect.objectContaining({ cwd: dir })) expect(await readFile(result!.logPath, 'utf8')).toBe('0123456789') }) +it('keeps URL user information out of the recorded command line', async () => { + const { check } = await fixture() + const run = vi.spyOn(subprocess, 'execa').mockResolvedValue({ + failed: true, exitCode: 128, shortMessage: 'fatal: unable to access the repository', + } as Awaited>) + onTestFinished(() => { run.mockRestore() }) + const result = await check('https://user:token@github.com/acme/plugin.git') + // Git runs the address as typed so its own credentials keep working, while the recorded line is safe to display. + expect(run).toHaveBeenCalledWith('git', checkArgv('https://user:token@github.com/acme/plugin.git').slice(1), expect.anything()) + expect(result?.argv).toEqual(checkArgv('https://github.com/acme/plugin.git')) +}) + it('reports a missing Git executable without classifying it as a network failure', async () => { const { check } = await fixture() const run = vi.spyOn(subprocess, 'execa').mockResolvedValue({ failed: true, code: 'ENOENT', shortMessage: 'spawn git ENOENT' } as Awaited>) diff --git a/packages/boot/plugin-manager/tests/manager.spec.ts b/packages/boot/plugin-manager/tests/manager.spec.ts index f2eb46af9a..207f34291f 100644 --- a/packages/boot/plugin-manager/tests/manager.spec.ts +++ b/packages/boot/plugin-manager/tests/manager.spec.ts @@ -17,6 +17,7 @@ import { } from '@deepseek-ai/dsh-app-boot' import { OPTIONAL_BUNDLES, OFFICIAL_ON_DEMAND_CATALOG } from '@deepseek-ai/dsh-official-bundles' import PluginManager, { type Config, type PluginChange, type PluginInstallLogChunk, type PluginInstallProgress, type PluginInstallRequestId } from '../src/index.ts' +import type { PluginEntryId, PluginOperation } from '../src/types.ts' import Hmr from '@deepseek-ai/dsh-hmr' import Timer from '@deepseek-ai/cordis-plugin-timer' import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include' @@ -126,24 +127,50 @@ it('allows supported bundle activation and permits deselecting an unsupported sa }) it.each(['network', 'timeout'] as const)('stops a GitHub %s before pnpm and attributes it to the repository', async (kind) => { - const { manager, dir, connection } = await fixture() + const { ctx, manager, dir, connection } = await fixture() + const chunks: PluginInstallLogChunk[] = [] + ctx.on('plugin-manager/install-log', (chunk) => { chunks.push(chunk) }) const before = readFileSync(join(dir, 'package.json'), 'utf8') - const failure = { exitCode: 1, output: 'GitHub check failed', truncated: false, logPath: join(dir, 'git.log'), kind } - connection.mockResolvedValue(failure) + const argv = ['git', '-c', 'credential.helper=', 'ls-remote', '--', 'https://github.com/acme/dsh-plugin.git', 'HEAD'] + const checked = { + argv, exitCode: 1, output: 'GitHub check failed', truncated: false, logPath: join(dir, 'git.log'), kind, + ...kind === 'timeout' ? { timedOut: true } : {}, + } + connection.mockResolvedValue(checked) const pnpm = vi.spyOn(operations, 'runProfilePnpm') onTestFinished(() => { pnpm.mockRestore() }) - expect(await manager.installBundle('https://github.com/acme/dsh-plugin.git')).toMatchObject({ - application: 'failed', changed: false, stage: 'install', failedAt: 'spec-host', packageResult: failure, + const requestId = '824103ec-bc45-489d-bb85-5b4fe0aefc78' as PluginInstallRequestId + const result = await manager.installBundle('https://github.com/acme/dsh-plugin.git', { requestId }) + expect(result).toMatchObject({ + application: 'failed', changed: false, stage: 'install', failedAt: 'spec-host', + packageResult: { exitCode: 1, output: 'GitHub check failed', truncated: false, logPath: join(dir, 'git.log'), kind }, }) + // The command line belongs to the streamed run only; the answer stays a plain package result. + expect(result.packageResult).not.toHaveProperty('argv') expect(pnpm).not.toHaveBeenCalled() expect(connection).toHaveBeenCalledWith(expect.objectContaining({ host: 'github.com' }), dir, expect.objectContaining({ timeoutMs: 5000 })) expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(before) + // The check is the installation's only run, so its diagnostic reaches the details panel. A timed-out Git has no exit + // code of its own, so its chunk reports none instead of the status the timeout coerced. + expect(chunks).toEqual([{ + requestId, jobId: expect.any(String) as string, argv, cwd: dir, stream: 'stderr', text: 'GitHub check failed', + exitCode: kind === 'timeout' ? null : 1, + }]) + // Without a request id there is no installation to stream the failed check under. + chunks.length = 0 + expect(await manager.installBundle('https://github.com/acme/dsh-plugin.git')).toMatchObject({ failedAt: 'spec-host' }) + expect(chunks).toEqual([]) }) it('leaves non-network GitHub errors to pnpm and forwards profile Git environment and deadline', async () => { const env = { GIT_CONFIG_GLOBAL: '/application/git.config' } - const { manager, connection } = await fixture('live', false, undefined, { githubConnectionTimeoutMs: 8000 }, { command: 'pnpm', args: [], env }) - connection.mockResolvedValue({ exitCode: 128, output: 'fatal: Authentication failed', truncated: false, logPath: 'git.log', kind: 'unknown' }) + const { ctx, manager, connection } = await fixture('live', false, undefined, { githubConnectionTimeoutMs: 8000 }, { command: 'pnpm', args: [], env }) + const chunks: PluginInstallLogChunk[] = [] + ctx.on('plugin-manager/install-log', (chunk) => { chunks.push(chunk) }) + connection.mockResolvedValue({ + argv: ['git', '-c', 'credential.helper=', 'ls-remote', '--', 'https://github.com/acme/private-plugin', 'HEAD'], + exitCode: 128, output: 'fatal: Authentication failed', truncated: false, logPath: 'git.log', kind: 'unknown', + }) const failure = { exitCode: 1, output: 'pnpm owns authentication', truncated: false, logPath: 'pnpm.log', kind: 'unknown' as const } const pnpm = vi.spyOn(operations, 'runProfilePnpm').mockResolvedValue(failure) onTestFinished(() => { pnpm.mockRestore() }) @@ -153,6 +180,8 @@ it('leaves non-network GitHub errors to pnpm and forwards profile Git environmen expect(pnpm).toHaveBeenCalledOnce() expect(result.failedAt).toBeUndefined() expect(connection).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({ timeoutMs: 8000, env })) + // A check failure pnpm may resolve streams no run of its own. + expect(chunks.filter(chunk => chunk.argv[0] === 'git')).toEqual([]) }) it('cancels an active GitHub check before starting pnpm', async () => { @@ -161,7 +190,10 @@ it('cancels an active GitHub check before starting pnpm', async () => { connection.mockImplementation(async (_spec, _dir, options) => { entered.resolve(undefined) await new Promise((resolve) => { options.signal.addEventListener('abort', () => { resolve() }, { once: true }) }) - return { exitCode: 1, output: 'cancelled', truncated: false, logPath: 'git.log', kind: 'unknown' } + return { + argv: ['git', '-c', 'credential.helper=', 'ls-remote', '--', 'https://github.com/acme/dsh-plugin', 'HEAD'], + exitCode: 1, output: 'cancelled', truncated: false, logPath: 'git.log', kind: 'unknown', + } }) const pnpm = vi.spyOn(operations, 'runProfilePnpm') onTestFinished(() => { pnpm.mockRestore() }) @@ -243,7 +275,10 @@ it('disposal waits for an active GitHub check to stop', async () => { entered.resolve(undefined) await new Promise((resolve) => { options.signal.addEventListener('abort', () => { resolve() }, { once: true }) }) released.resolve(undefined) - return { exitCode: 1, output: 'cancelled', truncated: false, logPath: 'git.log', kind: 'unknown' } + return { + argv: ['git', '-c', 'credential.helper=', 'ls-remote', '--', 'https://github.com/acme/addon', 'HEAD'], + exitCode: 1, output: 'cancelled', truncated: false, logPath: 'git.log', kind: 'unknown', + } }) const pnpm = vi.spyOn(operations, 'runProfilePnpm') onTestFinished(() => { pnpm.mockRestore() }) @@ -554,6 +589,112 @@ it.each([ }) }) +it('correlates diagnostic operation starts with persisted toggle results', async () => { + const { manager, ctx, dir } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + await manager.setBundleEnabled('extra', false) + expect(readProfileManifest('test', dir).dsh?.profile?.bundles).not.toContain('extra') + expect(facts).toHaveLength(2) + expect(facts[0]).toMatchObject({ phase: 'started', reason: 'bundle', target: 'extra', enabled: false, version: '1.0.0' }) + expect(facts[1]).toMatchObject({ id: facts[0]!.id, phase: 'settled', changed: true, application: 'restart-required', version: '1.0.0' }) + await manager.setBundleEnabled('extra', true) + expect(facts[2]!.id).not.toBe(facts[0]!.id) +}) + +it.each(['{', ...[null, 12, {}, 'x'.repeat(129)].map(version => JSON.stringify({ version, dsh: { bundle: { patch: './cordis.patch.yml' } } }))])('retains an observed version for a refused removal and leaves damaged metadata unknown: %s', async (manifest) => { + const { manager, ctx, dir } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + expect(await manager.removeBundle('extra')).toMatchObject({ application: 'failed', error: { code: 'stop-profile' } }) + expect(facts).toEqual([ + expect.objectContaining({ phase: 'started', reason: 'remove', version: '1.0.0' }), + expect.objectContaining({ phase: 'settled', reason: 'remove', version: '1.0.0', application: 'failed' }), + ]) + writeFileSync(join(dir, 'node_modules', 'extra', 'package.json'), manifest) + expect(await manager.setBundleEnabled('extra', false)).toMatchObject({ changed: true, application: 'restart-required' }) + expect(facts[2]).not.toHaveProperty('version') + expect(facts[3]).not.toHaveProperty('version') +}) + +it('excludes raw install specs and error diagnostics from operation facts', async () => { + const { manager, ctx } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + await manager.installBundle('--https://user:secret@example.invalid/private?token=secret') + expect(facts).toHaveLength(2) + expect(facts[1]).toMatchObject({ phase: 'settled', target: null, application: 'failed', errorCode: 'invalid-spec' }) + expect(JSON.stringify(facts)).not.toMatch(/secret|example|diagnostic|packageResult/) +}) + +it('keeps credential-bearing tarball addresses out of failed installation facts', async () => { + const { manager, ctx } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + const install = vi.spyOn(operations, 'runProfilePnpm').mockRejectedValue(new Error('private download failed')) + onTestFinished(() => { install.mockRestore() }) + expect(await manager.installBundle('https://user:secret@example.invalid/private/archive.tgz')) + .toMatchObject({ application: 'failed' }) + expect(facts).toHaveLength(2) + expect(facts.map(event => event.target)).toEqual([null, null]) + expect(JSON.stringify(facts)).not.toMatch(/user|secret|example|private|archive/) +}) + +it.each(['bundle', 'remove', 'plugin'] as const)('excludes credential-bearing targets from %s diagnostics', async (reason) => { + const { manager, ctx } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + const target = 'https://user:secret@example.invalid/private?token=secret' + if (reason === 'bundle') await manager.setBundleEnabled(target, false) + else if (reason === 'remove') await manager.removeBundle(target) + else await manager.setPluginEnabled(target as PluginEntryId, false) + expect(facts).toHaveLength(2) + expect(facts.map(event => event.target)).toEqual([null, null]) + expect(JSON.stringify(facts)).not.toMatch(/user|secret|example|private/) +}) + +it.each(['extra@9.9.9', ' extra', 'extra '])('does not attribute a non-name target %j to an installed bundle', async (target) => { + const { manager, ctx } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + await manager.setBundleEnabled(target, false) + await manager.removeBundle(target) + expect(facts).toHaveLength(4) + for (const event of facts) { + expect(event.target).toBeNull() + expect(event).not.toHaveProperty('version') + } +}) + +it('reports unknown outcomes when profile inspection rejects before a result exists', async () => { + const { manager, ctx, dir } = await fixture('startup') + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + const patch = join(dir, 'cordis.patch.yml') + rmSync(patch, { force: true }) + mkdirSync(patch) + await expect(manager.setBundleEnabled('extra', false)).rejects.toThrow() + expect(facts.map(event => event.phase)).toEqual(['started', 'unknown']) + expect(facts[1]!.id).toBe(facts[0]!.id) + expect(facts[1]).not.toHaveProperty('changed') +}) + +it.each(['throw', 'reject'])('delivers diagnostics to later subscribers when an earlier subscriber fails: %s', async (failure) => { + const { manager, ctx, dir } = await fixture('startup') + const errors = vi.spyOn(console, 'error').mockImplementation(() => {}) + onTestFinished(() => { errors.mockRestore() }) + ctx.on('plugin-manager/operation', () => { + if (failure === 'reject') return Promise.reject(new Error('diagnostic sink unavailable')) + throw new Error('diagnostic sink unavailable') + }) + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + expect(await manager.setBundleEnabled('extra', false)).toMatchObject({ changed: true, application: 'restart-required' }) + expect(readProfileManifest('test', dir).dsh?.profile?.bundles).not.toContain('extra') + expect(facts.map(event => event.phase)).toEqual(['started', 'settled']) + await vi.waitFor(() => { expect(errors).toHaveBeenCalledWith('dsh plugin-manager: operation diagnostic delivery failed') }) +}) + it('turns a plugin off and on without leaving a patch override the bundle already implies', async () => { const { manager, dir } = await fixture() const id = (await manager.listPlugins()).find(row => row.patchId === 'managed')!.entryId @@ -1594,6 +1735,8 @@ it.each(['live', 'startup'] as const)('requires exact risk acknowledgement and p expect(await manager.setVersionExemption('extra@1.0.0', runtime, true)).toMatchObject({ changed: false, application: 'failed' }) expect(manager.listVersionExemptions()).toEqual({ exemptions: {}, warnings: [] }) expect(existsSync(join(dir, 'compatibility.json'))).toBe(false) + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) expect(await manager.setVersionExemption('extra@1.0.0', runtime, true, true)).toMatchObject({ changed: true, application: mode === 'live' ? 'applied' : 'restart-required', }) @@ -1606,21 +1749,31 @@ it.each(['live', 'startup'] as const)('requires exact risk acknowledgement and p if (mode === 'live') expect(managed()?.fiber?.state).toBe(2) else expect(managed()).toBeUndefined() expect(await manager.setVersionExemption('extra@1.0.0', runtime, false)).toMatchObject({ changed: true }) + expect(facts.map(({ phase, target, version }) => ({ phase, target, version }))).toEqual([ + { phase: 'started', target: 'extra', version: '1.0.0' }, + { phase: 'settled', target: 'extra', version: '1.0.0' }, + { phase: 'started', target: 'extra', version: '1.0.0' }, + { phase: 'settled', target: 'extra', version: '1.0.0' }, + ]) expect(manager.listVersionExemptions()).toEqual({ exemptions: {}, warnings: [] }) expect(JSON.parse(readFileSync(join(dir, 'compatibility.json'), 'utf8'))).toEqual({}) if (mode === 'live') expect(managed()).toBeUndefined() }) -it('reports a package run refused for compatibility as a typed refusal', async () => { - const { manager } = await fixture() +it.each(['dsh-x', 'dsh-x@^2.0.0'])('retains the refused package identity for %s', async (spec) => { + const { manager, ctx } = await fixture() + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) const incompatible = [{ name: 'dsh-x', version: '2.0.0', runtimeVersion: getDshRuntimeVersion(), requirements: { '@deepseek-ai/dsh': '999.0.0' } }] const install = vi.spyOn(operations, 'runProfilePnpm').mockResolvedValue({ exitCode: 1, output: 'dsh: installation rejected', truncated: false, logPath: 'pnpm.log', kind: 'unknown', incompatible, }) onTestFinished(() => { install.mockRestore() }) - const result = await manager.installBundle('dsh-x') + const result = await manager.installBundle(spec) expect(result).toMatchObject({ application: 'failed', changed: false, error: { code: 'incompatible-version', incompatible } }) expect(install).toHaveBeenCalledTimes(1) + expect(facts[0]).toMatchObject({ phase: 'started', target: 'dsh-x' }) + expect(facts[1]).toMatchObject({ phase: 'settled', target: 'dsh-x', version: '2.0.0', errorCode: 'incompatible-version' }) }) it.each([false, true])('rechecks installed bundle peers before accepting a disabled installation (exempted=%s)', async (exempted) => { @@ -1654,9 +1807,13 @@ it('lists absent Official entries offline without resolving their packages or co onTestFinished(() => { resolve.mockRestore(); registry.mockRestore() }) const bundles = await manager.listBundles() for (const entry of OFFICIAL_ON_DEMAND_CATALOG) { - expect(bundles.filter(bundle => bundle.name === entry.packageName)).toEqual([{ + expect(bundles.filter(bundle => bundle.name === entry.packageName)).toHaveLength(1) + expect(bundles.filter(bundle => bundle.name === entry.packageName)).toMatchObject([{ name: entry.packageName, official: true, availability: 'missing', enabled: false, installed: false, optional: false, removable: false, updatable: false, rows: [], overrides: [], meta: entry.meta, + ...entry.listedByDefault === undefined ? {} : { listedByDefault: entry.listedByDefault }, + ...entry.platforms !== undefined && !entry.platforms.includes(process.platform) + ? { listedByDefault: false, error: { code: 'unsupported-platform' } } : {}, installTarget: { spec: `${entry.packageName}@${getDshRuntimeVersion()}`, version: getDshRuntimeVersion() }, }]) expect(resolve.mock.calls.some(([name]) => name === entry.packageName)).toBe(false) @@ -2113,3 +2270,52 @@ it('installs over the running version without HMR and reports the restart', asyn expect(steps).toEqual(['checking', 'installing']) expect(pnpm.mock.calls.map(call => call[1])).toEqual([['add', 'extra@1.2.0', '--save-exact']]) }) + +it.each(['extra@^1.0.0', ' extra@1.0.0 ', 'https://user:secret@example.com/pkg'])('omits invalid exemption identity for %s', async (input) => { + const { manager, ctx } = await fixture() + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + expect(await manager.setVersionExemption(input, getDshRuntimeVersion(), true, true)).toMatchObject({ application: 'failed' }) + expect(facts).toHaveLength(2) + for (const fact of facts) { + expect(fact.target).toBeNull() + expect(fact.version).toBeUndefined() + } + expect(JSON.stringify(facts)).not.toContain(input) + expect(JSON.stringify(facts)).not.toContain('secret') +}) + +it.each(['disable', 'enable', 'remove'] as const)('retains exact uninstalled bundle names when attempting %s', async (operation) => { + const { manager, ctx } = await fixture() + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + const result = operation === 'remove' ? await manager.removeBundle('absent') + : await manager.setBundleEnabled('absent', operation === 'enable') + if (operation !== 'disable') expect(result.application).toBe('failed') + expect(facts).toHaveLength(2) + for (const fact of facts) { + expect(fact.target).toBe('absent') + expect(fact.version).toBeUndefined() + } +}) + +it.each(['extra', '@scope/extra'])('records the exemption version independently of installed metadata for %s', async (name) => { + const { manager, ctx } = await fixture() + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + await manager.setVersionExemption(`${name}@2.0.0`, getDshRuntimeVersion(), false) + expect(facts).toHaveLength(2) + for (const fact of facts) expect(fact).toMatchObject({ target: name, version: '2.0.0', enabled: false }) +}) + +it('omits exemption identity when only the runtime version is invalid', async () => { + const { manager, ctx } = await fixture() + const facts: PluginOperation[] = [] + ctx.on('plugin-manager/operation', (event) => { facts.push(event) }) + expect(await manager.setVersionExemption('extra@1.0.0', '^1.0.0', true, true)).toMatchObject({ application: 'failed' }) + expect(facts).toHaveLength(2) + for (const fact of facts) { + expect(fact.target).toBeNull() + expect(fact.version).toBeUndefined() + } +}) diff --git a/packages/boot/plugin-manager/tests/operations.spec.ts b/packages/boot/plugin-manager/tests/operations.spec.ts index c54260d214..b6a87a6475 100644 --- a/packages/boot/plugin-manager/tests/operations.spec.ts +++ b/packages/boot/plugin-manager/tests/operations.spec.ts @@ -874,10 +874,16 @@ it.each([ ])('reports launch failures with a complete log: $code', async ({ code, shortMessage, expected }) => { const { context } = fixture() command.run.mockImplementationOnce(() => result(undefined, '', () => {}, { code, ...shortMessage === undefined ? {} : { shortMessage } })) - const outcome = await runProfilePnpm(context, ['root'], { execution: 'service', outputBytes: 4, signal: new AbortController().signal }) + const messages: string[] = [] + const outcome = await runProfilePnpm(context, ['root'], { + execution: 'service', outputBytes: 4, signal: new AbortController().signal, + onOutput: (text) => { messages.push(text) }, + }) expect(outcome.exitCode).toBe(expected) expect(outcome.truncated).toBe(true) expect(readFileSync(outcome.logPath, 'utf8')).toBe(shortMessage ?? 'pnpm failed') + // A run that printed nothing still streams the diagnostic its log carries. + expect(messages).toEqual([shortMessage ?? 'pnpm failed']) }) it('cancels and settles package output when the output consumer fails', async () => { diff --git a/packages/boot/plugin-market/package.json b/packages/boot/plugin-market/package.json index 863b4300b3..86c97b79b7 100644 --- a/packages/boot/plugin-market/package.json +++ b/packages/boot/plugin-market/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-plugin-market", "description": "Configured plugin market indexes for the Web Discover page and the plugin_market agent tool", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/browser-use/browser-use/package.json b/packages/browser-use/browser-use/package.json index a32c90047e..5a67143621 100644 --- a/packages/browser-use/browser-use/package.json +++ b/packages/browser-use/browser-use/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-browser-use", "description": "Exclusive named browser-use provider registration", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/bundle/acp-app/package.json b/packages/bundle/acp-app/package.json index 0d3500d904..d48b0bf711 100644 --- a/packages/bundle/acp-app/package.json +++ b/packages/bundle/acp-app/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-acp-app", "description": "The dsh ACP profile bundle: automation-only JSON-RPC stdio and process lifecycle over dsh-base", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json index 6d9a89c883..9ec5046994 100644 --- a/packages/bundle/base/package.json +++ b/packages/bundle/base/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-base", "description": "The shared dsh core as a profile bundle: the first patch layer of base-backed profiles, inserting core rows over the empty profile root", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/bundle/headless/package.json b/packages/bundle/headless/package.json index d54cb3bb06..dd523037fe 100644 --- a/packages/bundle/headless/package.json +++ b/packages/bundle/headless/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-headless", "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/bundle/sdk-app/README.i18n.yaml b/packages/bundle/sdk-app/README.i18n.yaml index ed528810fc..623f6546a0 100644 --- a/packages/bundle/sdk-app/README.i18n.yaml +++ b/packages/bundle/sdk-app/README.i18n.yaml @@ -15,8 +15,8 @@ en: 4e53164159b5ce41 zh: 89582dc0294d0776 /deepseek-ai-dsh-sdk-app/use-this-package: - en: b9a0e01492ffe278 - zh: 7c6ffd1f9e9c0906 + en: 63aa871622cea3af + zh: 8f00a69640caadc5 /deepseek-ai-dsh-sdk-app/model-experience: en: 215e7ba838619b7b zh: a311da3843709f90 @@ -24,17 +24,17 @@ en: 4f88e647c6df4f42 zh: 2bd3e4b0bdfe9412 /deepseek-ai-dsh-sdk-app/model-experience/sdk-model-context/what-the-model-sees: - en: 0cce2b88aae3a0e5 - zh: fcb31314096ef15e + en: 6b46520441d75a00 + zh: 04851fd123960847 /deepseek-ai-dsh-sdk-app/model-experience/sdk-model-context/token-effect: - en: 0d4a38b2448396b3 - zh: e63408a146bf0100 + en: cef8efe97fe1ff16 + zh: c052ab3e6706efa6 /deepseek-ai-dsh-sdk-app/model-experience/sdk-model-context/kv-cache-effect: - en: 0503df0971e5f8d7 - zh: 18cae8c6e25cda04 + en: b1169743449b2272 + zh: 98d465d802bf55c1 /deepseek-ai-dsh-sdk-app/known-limitations-and-deferred-work: - en: 451497677de7e6b9 - zh: dcfdc671c38d54d4 + en: d1d4567b7d2b9d8d + zh: c1618617d1562d8b /deepseek-ai-dsh-sdk-app/known-limitations-and-deferred-work/dev-note: - en: e67f633dc6fe7773 - zh: e88aeb617ffb74ea + en: b9b4e27513ebba78 + zh: 51b123ac60ff28c6 diff --git a/packages/bundle/sdk-app/README.md b/packages/bundle/sdk-app/README.md index d1be289939..60d1db572e 100644 --- a/packages/bundle/sdk-app/README.md +++ b/packages/bundle/sdk-app/README.md @@ -35,6 +35,8 @@ The startup provider binds stdin EOF to the launcher's bounded successful shutdo The SDK uses the base `read`, `write`, and `edit` defaults. To add `str_replace_editor`, use the explicit insertion patch in the [base configuration guide](../base/README.md#use-this-package). The standalone `sdk-minimal` profile owns its separate tool selection. +The model can use [`plugin_manager`](../../boot/plugin-manager/README.md) in native and PTC modes. Every action, including listing, requires full access or approval for that call. The default workspace-write/ask policy needs a client approval responder: enable `approvalRequests` and handle `approval/request` through `harness.client.onRequest()`, or supply an approver in the composition. Without one, the operation is refused as unavailable. For Python package installation/removal, explicitly prepare Node and pnpm with `download_primary_runtime()` before starting the runtime; the packaged launcher then supplies them to plugin management without requiring system pnpm. Without a selected payload, package operations need `pnpm` on `PATH` or an explicit `plugin-manager.pnpmCommand`. See the [interactive approval example](../../../python/sdk/examples/manage_plugins.py). Saved profile changes report `restart-required` with `no-hmr`; the current runtime and its sessions retain their tools until the caller closes and starts the runtime again. Set `tool-plugin-manager.disabled: true` through a profile patch to hide this tool. The standalone `sdk-minimal` profile does not include it. + The Python runtime exposes explicitly downloaded authoring resources and Office sidecars to this profile. `DSH_PRIMARY_RUNTIME` overrides the authoring payload; an empty value disables its query. Office skills can use either resource independently. Profile patches can disable `skill-office` or replace its `assetRoot` independently of `workspace-dependencies`; filesystem skills with the same name take precedence. See the [runtime package](../../../python/sdk-runtime/README.md) for downloads and configuration. ----- @@ -46,15 +48,15 @@ The Python runtime exposes explicitly downloaded authoring resources and Office #### What the model sees -The profile inherits the base system prompt, including the `You are an AI agent powered by DeepSeek Harness.` identity, and adds the same model-interpolated coding persona as the Web and headless profiles. Each Session receives its current directory in required user-role context from [`dsh-working-directory`](../../session/working-directory/README.md). Default file tool schemas include `read`, `write`, and `edit`; they omit `str_replace_editor`. The model also receives `present`, `ask_user_question`, schedule tools, shared file-reference guidance, and time context. Child agents cannot use schedule tools. The [`time-context`](../../context/time-context/README.md) row accepts a fallback time zone. Skills use the configured resources described above. +The profile inherits the base system prompt, including the `You are an AI agent powered by DeepSeek Harness.` identity, and adds the same model-interpolated coding persona as the Web and headless profiles. Each Session receives its current directory in required user-role context from [`dsh-working-directory`](../../session/working-directory/README.md). Default file tool schemas include `read`, `write`, and `edit`; they omit `str_replace_editor`. The model also receives `present`, `ask_user_question`, `plugin_manager`, schedule tools, shared file-reference guidance, and time context. Child agents cannot use schedule tools. The [`time-context`](../../context/time-context/README.md) row accepts a fallback time zone. Skills use the configured resources described above. #### Token effect -The profile adds a coding-persona sentence, the mounted tool definitions and guidance, and logged runtime-context and time messages. +The profile adds a coding-persona sentence, the mounted tool definitions and guidance, and logged runtime-context and time messages. The `plugin_manager` description and parameter schema add input tokens even when an operation cannot be approved; an embedding that does not use plugin management can disable its row. #### KV Cache effect -The static prefix is stable for a fixed profile, provider, model, and tool roster. Runtime values append to logged user context. Profile changes take effect on the next process because the shipped SDK profile uses startup-only patches. +Enabling `plugin_manager` changes the tool-schema prefix from earlier SDK versions. The static prefix is stable for a fixed profile, provider, model, and tool roster. Runtime values append to logged user context. Profile changes take effect on the next process because the shipped SDK profile uses startup-only patches. ## Known Limitations and Deferred Work @@ -66,6 +68,7 @@ The static prefix is stable for a fixed profile, provider, model, and tool roste - **Schedules share the runtime lifetime** — delivery needs a running process and its persistent Session storage. - **A profile can omit the SDK server** — a custom profile selected by the TypeScript client must retain this bundle or another `dsh-sdk-jsonrpc-server` row; client initialization fails when no peer answers. - **User plugins can violate stdout purity** — profile and per-launch patches are trusted application composition. The shipped bundle writes no non-protocol stdout, but it cannot contain an arbitrary inserted plugin. +- **Plugin changes share a profile** — saved changes affect `/profiles/sdk` and other embeddings using that home on their next launch; use separate `dshHome` directories for independent compositions. The Python launcher uses Node/pnpm from its selected downloaded runtime; without that payload or an external pnpm, package operations fail. - **Configuration changes require restart** — the `sdk-app` bundle disables HMR in YAML so one stdio connection never observes a replacement server or Agent dependency. @@ -75,6 +78,6 @@ The static prefix is stable for a fixed profile, provider, model, and tool roste
Working context for maintainers — click to expand -None. +The [SDK/Desktop tool comparison](../../../apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts) runs without API credentials in `test:expected`, included in the required PR consumer job. It covers standard/PTC root sessions with Team disabled; Team parity is deferred to #7172. After building, run `CI=true pnpm run test:expected apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts`. Maintain exact, reasoned differences in the adjacent `tool-parity.ts`; resolved differences invalidate their exceptions. Existing SDK session snapshots and installed-runtime smokes independently check model output and packaging.
diff --git a/packages/bundle/sdk-app/README.zh.md b/packages/bundle/sdk-app/README.zh.md index 70523123d7..eee5f3522c 100644 --- a/packages/bundle/sdk-app/README.zh.md +++ b/packages/bundle/sdk-app/README.zh.md @@ -35,6 +35,8 @@ kind: "package-bundle" SDK 使用 base 默认提供的 `read`、`write` 和 `edit`。要添加 `str_replace_editor`，请使用 [base 配置指南](../base/README.zh.md#use-this-package)中的显式插入 patch。独立的 `sdk-minimal` profile 自行决定其工具选择。 +模型可以在 native 和 PTC 模式下使用 [`plugin_manager`](../../boot/plugin-manager/README.zh.md)。每个操作（包括列举）都要求完整权限或本次调用的批准。默认 workspace-write/ask 策略需要客户端审批应答方：启用 `approvalRequests`，并通过 `harness.client.onRequest()` 处理 `approval/request`，或在组合中提供审批器。没有应答方时，操作因 unavailable 被拒绝。Python 安装/移除包时，先显式调用 `download_primary_runtime()` 准备 Node 和 pnpm，再启动运行时；打包启动器会将它们提供给插件管理，无需系统 pnpm。未选择载荷时，包操作仍要求 `PATH` 中有 `pnpm`，或显式配置 `plugin-manager.pnpmCommand`。可运行的接入方式见[交互审批示例](../../../python/sdk/examples/manage_plugins.py)。保存的 profile 变更返回 `restart-required` 和 `no-hmr`；当前运行时及其会话保留原有工具，直到调用方关闭并重新启动运行时。通过 profile patch 设置 `tool-plugin-manager.disabled: true` 可隐藏此工具。独立的 `sdk-minimal` profile 不包含它。 + Python 运行时向本 profile 提供显式下载的创作资源和 Office sidecar。`DSH_PRIMARY_RUNTIME` 覆盖创作载荷；空值禁用其查询。Office skills 可独立使用任一种资源。Profile patch 可独立于 `workspace-dependencies` 禁用 `skill-office` 或替换其 `assetRoot`；同名文件系统 skills 优先。下载与配置见[运行时包](../../../python/sdk-runtime/README.zh.md)。 ----- @@ -46,15 +48,15 @@ Python 运行时向本 profile 提供显式下载的创作资源和 Office sidec #### 模型看到什么 -profile 继承 base 系统提示词，包括 `You are an AI agent powered by DeepSeek Harness.` 身份说明，并添加与 Web 和 headless profile 相同、按当前模型插值的 coding persona。每个 Session 通过 [`dsh-working-directory`](../../session/working-directory/README.zh.md) 提供的必需 user-role 上下文接收当前目录。默认文件工具 schema 包含 `read`、`write` 和 `edit`，不包含 `str_replace_editor`。模型还会收到 `present`、`ask_user_question`、定时任务工具、共用文件引用说明和时间上下文。子 agent 不能使用定时任务工具。[`time-context`](../../context/time-context/README.zh.md) 配置项接受回退时区。Skills 使用上述配置的资源。 +profile 继承 base 系统提示词，包括 `You are an AI agent powered by DeepSeek Harness.` 身份说明，并添加与 Web 和 headless profile 相同、按当前模型插值的 coding persona。每个 Session 通过 [`dsh-working-directory`](../../session/working-directory/README.zh.md) 提供的必需 user-role 上下文接收当前目录。默认文件工具 schema 包含 `read`、`write` 和 `edit`，不包含 `str_replace_editor`。模型还会收到 `present`、`ask_user_question`、`plugin_manager`、定时任务工具、共用文件引用说明和时间上下文。子 agent 不能使用定时任务工具。[`time-context`](../../context/time-context/README.zh.md) 配置项接受回退时区。Skills 使用上述配置的资源。 #### Token 影响 -此 profile 添加一句 coding persona、所挂载的工具定义与说明，以及记录在日志中的运行时上下文和时间消息。 +此 profile 添加一句 coding persona、所挂载的工具定义与说明，以及记录在日志中的运行时上下文和时间消息。 即使操作无法获批，`plugin_manager` 的描述和参数 schema 仍增加输入 token；不使用插件管理的嵌入方可禁用该条目。 #### KV Cache 影响 -对固定 profile、提供方、模型与工具清单，静态前缀保持稳定。运行时值追加到已记录的 user 上下文中。由于随附 SDK profile 使用仅启动时 patch，profile 变化会在下一个进程生效。 +启用 `plugin_manager` 会改变早期 SDK 版本的工具 schema 前缀。对固定 profile、提供方、模型与工具清单，静态前缀保持稳定。运行时值追加到已记录的 user 上下文中。由于随附 SDK profile 使用仅启动时 patch，profile 变化会在下一个进程生效。 ## 已知限制与延期工作 @@ -66,6 +68,7 @@ profile 继承 base 系统提示词，包括 `You are an AI agent powered by Dee - **定时任务依赖运行时生命周期**：投递需要运行中的进程及其持久化 Session 存储。 - **profile 可能省略 SDK server**：TypeScript client 选择的自定义 profile 必须保留本组合包或另一个 `dsh-sdk-jsonrpc-server` 配置项；没有 peer 响应时，client 初始化会失败。 - **用户插件可以破坏 stdout 纯净性**：profile 与逐次启动 patch 属于受信任应用组合。随附组合包不会向 stdout 写入非协议内容，但无法约束任意插入插件。 +- **插件变更共享 profile** — 保存的变更影响 `/profiles/sdk`，以及使用同一 home 的其他嵌入方的下次启动；独立组合应使用不同的 `dshHome` 目录。Python 启动器使用所选下载运行时中的 Node/pnpm；没有该载荷或外部 pnpm 时，包操作会失败。 - **配置变化需要重启**：`sdk-app` 组合包在 YAML 中禁用 HMR，因此一个 stdio 连接不会观察到 server 或 agent 依赖被替换。 @@ -75,6 +78,6 @@ profile 继承 base 系统提示词，包括 `You are an AI agent powered by Dee
维护者工作上下文——点击展开 -无。 +[SDK/Desktop 工具比较](../../../apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts) 在 `test:expected` 中无需 API 凭据运行，并纳入 PR 必需的 consumer 作业。检查覆盖关闭 Team 的 standard/PTC 主会话；Team 对齐暂由 #7172 跟踪。构建后运行 `CI=true pnpm run test:expected apps/cli/tests/profiles/sdk/desktop-tools.expected.e2e.ts`。在相邻的 `tool-parity.ts` 中维护精确、带理由的差异；差异消除后，对应例外会使检查失败。已有 SDK 会话快照和安装后运行时 smoke 分别检查模型输出和打包结果。
diff --git a/packages/bundle/sdk-app/cordis.patch.yml b/packages/bundle/sdk-app/cordis.patch.yml index afcbfd2c0d..15a5245ade 100644 --- a/packages/bundle/sdk-app/cordis.patch.yml +++ b/packages/bundle/sdk-app/cordis.patch.yml @@ -23,6 +23,9 @@ - id: hmr disabled: true +- id: tool-plugin-manager + disabled: false + # The packaged carrier supplies a default; DSH_PRIMARY_RUNTIME overrides it, # including an empty-string opt-out. Each row can be patched independently. - insert: diff --git a/packages/bundle/sdk-app/package.json b/packages/bundle/sdk-app/package.json index 9734be57f2..7be81f2b9c 100644 --- a/packages/bundle/sdk-app/package.json +++ b/packages/bundle/sdk-app/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-sdk-app", "description": "The dsh SDK profile bundle: stdio JSON-RPC serving and process lifecycle over dsh-base", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/bundle/sdk-app/tests/sdk-app.spec.ts b/packages/bundle/sdk-app/tests/sdk-app.spec.ts index 2e040c2487..6ab9bd10ff 100644 --- a/packages/bundle/sdk-app/tests/sdk-app.spec.ts +++ b/packages/bundle/sdk-app/tests/sdk-app.spec.ts @@ -8,7 +8,7 @@ import { describe, expect, it } from 'vitest' import { entryListSchema } from '@deepseek-ai/cordis-plugin-include' describe('dsh-sdk-app bundle', () => { - it('declares startup-gated JSON-RPC serving without overriding base HMR policy', () => { + it('enables plugin management while keeping JSON-RPC dependencies stable until restart', () => { const root = fileURLToPath(new URL('..', import.meta.url)) const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')) as { dependencies?: Record @@ -21,6 +21,7 @@ describe('dsh-sdk-app bundle', () => { { schema: entryListSchema }, ) as Array<{ id?: string; disabled?: boolean; insert?: Array<{ id?: string; inject?: string[]; name?: string }> }> expect(patches.find(patch => patch.id === 'hmr')).toMatchObject({ disabled: true }) + expect(patches.find(patch => patch.id === 'tool-plugin-manager')).toMatchObject({ disabled: false }) expect(patches.find(patch => patch.id === 'session-title-llm')).toMatchObject({ disabled: true }) expect(patches.find(patch => patch.id === 'system-prompt')).toMatchObject({ config: { personaPrefix: 'You are a coding agent powered by the {{model}} model.' }, diff --git a/packages/bundle/sdk-minimal/package.json b/packages/bundle/sdk-minimal/package.json index c7b1195003..499aad21e4 100644 --- a/packages/bundle/sdk-minimal/package.json +++ b/packages/bundle/sdk-minimal/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-sdk-minimal", "description": "The standalone minimal SDK profile bundle: JSON-RPC, one DeepSeek adapter, persistent shell, and JSONL sessions", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index 9552b1eab9..623f3fd1c1 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -77,6 +77,10 @@ iconTimeoutMs: 10000 launchWatchMs: 1000 + - id: ui-file-actions + name: '@deepseek-ai/dsh-client-ui-file-actions' + - id: ui-context-menu + name: '@deepseek-ai/dsh-client-ui-context-menu' - id: ui-open-in-app name: '@deepseek-ai/dsh-client-ui-open-in-app' @@ -413,9 +417,6 @@ - id: ui-model-selection name: '@deepseek-ai/dsh-client-ui-model-selection' - - id: ui-deepseek-model-label-1017 - name: '@deepseek-ai/dsh-client-ui-deepseek-model-label-1017' - - id: ui-permission name: '@deepseek-ai/dsh-client-ui-permission-presets' diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index aee3da55b1..9ecc295724 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-web-app", "description": "The dsh browser-surface bundle: the web patch layer over dsh-base plus the runtime glue plugin (frontend dist serving, bash runtime variables, URL line)", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -91,7 +91,6 @@ "@deepseek-ai/dsh-client-ui-layout": "workspace:*", "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:*", "@deepseek-ai/dsh-client-ui-model-selection": "workspace:*", - "@deepseek-ai/dsh-client-ui-deepseek-model-label-1017": "workspace:*", "@deepseek-ai/dsh-client-ui-open-in-app": "workspace:*", "@deepseek-ai/dsh-client-ui-permission-presets": "workspace:*", "@deepseek-ai/dsh-client-ui-plan": "workspace:*", @@ -192,7 +191,9 @@ "@deepseek-ai/dsh-client-ui-settings-session-log": "workspace:*", "@deepseek-ai/dsh-harness-dev-context": "workspace:*", "@deepseek-ai/dsh-deliverable-file-references": "workspace:*", - "@deepseek-ai/dsh-client-ui-file-drag": "workspace:*" + "@deepseek-ai/dsh-client-ui-file-drag": "workspace:*", + "@deepseek-ai/dsh-client-ui-context-menu": "workspace:*", + "@deepseek-ai/dsh-client-ui-file-actions": "workspace:*" }, "peerDependencies": { "@deepseek-ai/cordis": "workspace:~", diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml index 500bb30266..301bb6ffba 100644 --- a/packages/client/README.i18n.yaml +++ b/packages/client/README.i18n.yaml @@ -15,8 +15,8 @@ en: 1eb35b015a6c423f zh: a8a3dceee2c9e943 /client-web-gui-browser-half/packages: - en: 3cae9938f3a11040 - zh: 8ed2edf0ffe6eed0 + en: d988c73b3bf44a97 + zh: ba5bab5652214c66 /client-web-gui-browser-half/related-documentation: en: d1d506e68fab7333 zh: 1a90fe6f3f8f24a9 diff --git a/packages/client/README.md b/packages/client/README.md index 428498b221..cfdd7f44ed 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -49,7 +49,7 @@ The kernel packages boot and serve the page; the UI feature packages present it. | [`ui-sidebar-documentpreview/`](ui-sidebar-documentpreview/README.md) | Displays documents in right Sidebar tabs | `ctx.documentPreviews` | | [`ui-sidebar-browser/`](ui-sidebar-browser/README.md) | Browses sandboxed HTTP(S) pages, including loopback services, in right-Sidebar tabs | — | | [`resources/`](resources/README.md) | Unified resource model: protocol providers behind the `useResource` session standard hook | `ctx.resources` | -| [`ui-sidebar-files/`](ui-sidebar-files/README.md) | Right-Sidebar workspace file tree tab type | — | +| [`ui-sidebar-files/`](ui-sidebar-files/README.md) | The workspace files page and one workspace tree per pane beside docked and floating previews | — | | [`ui-brand-official/`](ui-brand-official/README.md) | Fills the generic browser-brand slots with the official name and marks | — | | [`ui-workspace/`](ui-workspace/README.md) | Provides workspace selection and creation surfaces | — | | [`ui-conversation/`](ui-conversation/README.md) | Presents the active conversation and its input surface | — | @@ -68,7 +68,6 @@ The kernel packages boot and serve the page; the UI feature packages present it. | [`ui-jobs/`](ui-jobs/README.md) | Lists this session's background jobs with on-demand streaming record panels | — | | [`ui-schedule/`](ui-schedule/README.md) | Lists the current Session's active reminders in a read-only header catalog | — | | [`ui-model-selection/`](ui-model-selection/README.md) | Provides model selection in conversation surfaces | — | -| [`ui-deepseek-model-label-1017/`](ui-deepseek-model-label-1017/README.md) | Adds the temporary 1017 badge to official DeepSeek Flash model labels | — | | [`ui-permission-presets/`](ui-permission-presets/README.md) | Configures default permissions and switches the current session's access | — | | [`ui-plan/`](ui-plan/README.md) | Presents active plan-mode status and its exit control | — | | [`ui-settings-plugins/`](ui-settings-plugins/README.md) | Owns the Built-in plugins settings section shell and its tab extension point | — | diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md index c9912d944f..9228b50257 100644 --- a/packages/client/README.zh.md +++ b/packages/client/README.zh.md @@ -49,7 +49,7 @@ kind: "package-group" | [`ui-sidebar-documentpreview/`](ui-sidebar-documentpreview/README.zh.md) | 在右侧 Sidebar 的 tab 中显示文档 | `ctx.documentPreviews` | | [`ui-sidebar-browser/`](ui-sidebar-browser/README.zh.md) | 在右侧 Sidebar tab 中浏览 sandboxed HTTP(S) 页面，包括 loopback 服务 | — | | [`resources/`](resources/README.zh.md) | 统一资源模型：`useResource` 会话标准钩子背后的协议提供方 | `ctx.resources` | -| [`ui-sidebar-files/`](ui-sidebar-files/README.zh.md) | 右侧 Sidebar 的工作区文件树 tab 类型 | — | +| [`ui-sidebar-files/`](ui-sidebar-files/README.zh.md) | 工作区文件页，以及停靠与浮动文件预览旁每个分栏一棵的工作区目录树 | — | | [`ui-brand-official/`](ui-brand-official/README.zh.md) | 用官方名称与标记填充通用浏览器品牌 slot | — | | [`ui-workspace/`](ui-workspace/README.zh.md) | 提供工作区选择与创建界面 | — | | [`ui-conversation/`](ui-conversation/README.zh.md) | 展示当前对话及其输入界面 | — | @@ -68,7 +68,6 @@ kind: "package-group" | [`ui-jobs/`](ui-jobs/README.zh.md) | 列出本会话的后台任务，并提供按需展开的流式输出面板 | — | | [`ui-schedule/`](ui-schedule/README.zh.md) | 在只读标题栏目录中列出当前会话中生效的提醒 | — | | [`ui-model-selection/`](ui-model-selection/README.zh.md) | 在对话界面中提供模型选择 | — | -| [`ui-deepseek-model-label-1017/`](ui-deepseek-model-label-1017/README.zh.md) | 为官方 DeepSeek Flash 模型名称添加临时的 1017 角标 | — | | [`ui-permission-presets/`](ui-permission-presets/README.zh.md) | 配置默认权限并切换当前会话的访问模式 | — | | [`ui-plan/`](ui-plan/README.zh.md) | 展示生效中的 plan mode 状态及其退出控件 | — | | [`ui-settings-plugins/`](ui-settings-plugins/README.zh.md) | 负责「内置插件」设置分区壳及其标签页扩展点 | — | diff --git a/packages/client/connection/package.json b/packages/client/connection/package.json index 3392544e2d..22f21df125 100644 --- a/packages/client/connection/package.json +++ b/packages/client/connection/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-connection", "description": "Authenticated RPC transport and generation lifecycle", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/file-upload/package.json b/packages/client/file-upload/package.json index ff5eb04d4e..d91c931e21 100644 --- a/packages/client/file-upload/package.json +++ b/packages/client/file-upload/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-file-upload", "description": "Agent-scoped browser file upload, streaming intake, and staged receipt service", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/hmr/package.json b/packages/client/hmr/package.json index 2e64b3e705..0ad8192ce6 100644 --- a/packages/client/hmr/package.json +++ b/packages/client/hmr/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-hmr", "description": "Web client graph synchronization and rebuilt-bundle reload transport", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/locale/package.json b/packages/client/locale/package.json index 023f018f5e..44227c6ebe 100644 --- a/packages/client/locale/package.json +++ b/packages/client/locale/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-locale", "description": "Locale plugin: Host-backed preference, extensible language catalog, browser fallback, and typed built-in dictionaries", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/locale/tests/language-row.client.spec.tsx b/packages/client/locale/tests/language-row.client.spec.tsx index ecf23dd6e9..d94b2a195b 100644 --- a/packages/client/locale/tests/language-row.client.spec.tsx +++ b/packages/client/locale/tests/language-row.client.spec.tsx @@ -1,4 +1,5 @@ // @vitest-environment jsdom +import { contextMenuHook } from '@deepseek-ai/dsh-client-test-runtime' import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots' import { afterEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render, screen } from '@testing-library/react' @@ -45,6 +46,7 @@ function mount(active = 'en') { usePanelInfo, useSessionRetainInfo: () => undefined, useResource, useWorkspaces: emptyWorkspaces(), ...allowAllAccess, + useContextMenu: contextMenuHook(), useStore: bindSnapshotSelector(store), actions: store.actions, t: (key: string) => key === 'language.title' ? 'Language' : key, diff --git a/packages/client/modules/README.i18n.yaml b/packages/client/modules/README.i18n.yaml index eb264da002..8f9a9d597f 100644 --- a/packages/client/modules/README.i18n.yaml +++ b/packages/client/modules/README.i18n.yaml @@ -48,8 +48,8 @@ en: 6d16b74acb333e3b zh: fcb3a20cc8c39e4a /deepseek-ai-dsh-client-modules/understand-the-implementation/incremental-composition: - en: d2c42ee89ca84f7b - zh: 70ee9dd5e6aa5327 + en: 99483432e6390ca4 + zh: f92c018273aa07e4 /deepseek-ai-dsh-client-modules/understand-the-implementation/boot-manifest-injection: en: 253d9f265cd83ed0 zh: 9d0f8df84d9d3ac9 diff --git a/packages/client/modules/README.md b/packages/client/modules/README.md index 6048a73939..a27f4271fd 100644 --- a/packages/client/modules/README.md +++ b/packages/client/modules/README.md @@ -78,7 +78,9 @@ Executing a plugin bundle only registers its factory; every module-body side eff ### Incremental composition -The Node half scans incrementally per package — no full-rescan path. Every `internal/plugin` emission marks the fiber's entry name dirty; a microtask flush reconciles each dirty name against the live loader entries, and the activation pass seeds the same dirty set and flushes synchronously, so first scan and steady state share one implementation. Each reconciliation reads the package manifest and the bundle metadata again, so an entry that restarts after its package was reinstalled, upgraded, or moved publishes its current `dsh.client` declaration and client export; a reconciliation that finds the same manifest and bundle metadata publishes nothing and reads no bundle bytes, and an unchanged bundle keeps its revision, so the browser keeps the loaded plugin. The resolved manifest package name identifies the browser module. Distinct active Loader sources resolving to one package name are rejected; removing the conflict promotes the remaining source without requiring its fiber to restart. A bundle rebuilt without an entry restart reaches the graph through `rebuilt()` (the HMR hook). +The Node half reconciles packages by Loader entry name. Every `internal/plugin` emission marks the fiber's entry name dirty. Each nonempty flush, including the synchronous activation flush, traverses all Loader entries once to build a temporary index by entry name, then looks up the pending names for reconciliation. Package resolution must not synchronously add or remove Loader entries during that reconciliation. A pending name absent from the index is reconciled with an empty entry list to remove unloaded sources; all same-name entries remain available for source deduplication and conflict checks. The activation pass seeds the same pending names and flushes synchronously, so initial activation and steady state share one implementation. Each reconciliation reads the package manifest and the bundle metadata again, so an entry that restarts after its package was reinstalled, upgraded, or moved publishes its current `dsh.client` declaration and client export; a reconciliation that finds the same manifest and bundle metadata publishes nothing and reads no bundle bytes, and an unchanged bundle keeps its revision, so the browser keeps the loaded plugin. The resolved manifest package name identifies the browser module. Distinct active Loader sources resolving to one package name are rejected; removing the conflict promotes the remaining source without requiring its fiber to restart. A bundle rebuilt without an entry restart reaches the graph through `rebuilt()` (the HMR hook). + +If Loader enumeration fails during a flush, the registry consumes the failed batch without changing package state or the published graph. Activation reports the failure through its composition error; steady state logs a warning. Another entry notification is required to retry that name. The Node half snapshots each `client.js` entry before publication and creates combo descriptors without building response bodies. It groups resources into combo route keys (`/plugins/??...&rev=...`), with one bootstrap combo for the modules row and one or more application combos for the other rows; each phase is partitioned before a URL exceeds 3 KiB. The graph and batch descriptors carry the app-directory-relative form of the same key (`plugins/??...&rev=...`), which a browser document resolves under its own mount, while the response table stays keyed by the absolute route; the source-map trailer is resolved against the combo script's own directory. A script body is combined once on its first `GET` and ends with its map reference. The corresponding map files are read, validated, and combined separately on the first map `GET`; `HEAD` materializes neither body. The Host does not scan or preload sibling chunks: an exact `/plugins//client..js?rev=` request reads that script through the asynchronous file API, so a filesystem that materializes files on first asynchronous read can supply it, and caches it; its map remains uncomputed until the map URL is requested. The chunk reference the browser derives from its owner row is document-relative as well (`plugins//client..js?rev=`), and a chunk script's map trailer is the bare `client..js.map?rev=` name, which resolves against the script's own directory. Every combo or chunk map is Indexed Source Map v3 and uses an authored section when available or an identity section for the packaged bundle. Initial publication and HMR derive per-plugin revisions from the entry's `mtimeMs`, `ctimeMs`, and size, without hashing artifact contents. Status-change time distinguishes rewrites that preserve mtime and size. Unchanged artifacts therefore retain their revisions across Host restarts, so SSE reconnection does not replace their browser plugins. The shared preset stamps `client.js` after every package output is written, so a chunk-only rebuild changes the owner revision without a Host-side chunk scan. Combo revisions derive from the ordered row revisions. Advertised combo responses and requested chunk responses remain immutable across unrelated graph recomposition, and an unknown resource or revision returns 404. diff --git a/packages/client/modules/README.zh.md b/packages/client/modules/README.zh.md index 1d97be97de..ab6fe609b3 100644 --- a/packages/client/modules/README.zh.md +++ b/packages/client/modules/README.zh.md @@ -79,7 +79,9 @@ application combo 脚本只携带每个插件的 `client.js` 入口，并在启 ### 增量组合 -Node 半侧逐包增量扫描——没有全量重扫路径。每次发出 `internal/plugin` 事件时，系统都会把该 fiber 的 entry 名标脏；微任务 flush 会把每个脏名与当前 loader 条目对账，激活 pass 会初始化同一个脏集合并同步 flush，因此首次扫描与稳态共用同一实现。每次对账都会重新读取包 manifest 与 bundle 元数据，因此包在重新安装、升级或移动之后重启的条目会发布其当前的 `dsh.client` 声明与客户端导出；读到相同 manifest 与 bundle 元数据的对账不发布任何内容，也不读取 bundle 字节；未变化的 bundle 保留其 revision，因此浏览器会保留已加载的插件。解析出的 manifest 包名作为浏览器模块身份。若不同的 active Loader source 解析到同一包名，组合会失败；移除冲突来源后，剩余来源无需重启 fiber 即可接替。没有伴随条目重启的 bundle 重建经 `rebuilt()`（HMR 钩子）进入图。 +Node 半侧按 Loader entry 名对包进行对账。每次发出 `internal/plugin` 事件时，系统都会把该 fiber 的 entry 名标脏。每次非空 flush（包括同步执行的激活 flush）遍历全部 Loader entries 一次，按 entry 名构建临时索引，再查询待处理名称进行对账。包解析过程不得在对账期间同步添加或移除 Loader entries。待处理名称若不在索引中，则以空 entry 列表对账，移除已卸载的来源；所有同名 entry 都保留，用于来源去重与冲突检查。激活 pass 初始化同一组待处理名称并同步 flush，因此首次激活与稳态共用同一实现。每次对账都会重新读取包 manifest 与 bundle 元数据，因此包在重新安装、升级或移动之后重启的条目会发布其当前的 `dsh.client` 声明与客户端导出；读到相同 manifest 与 bundle 元数据的对账不发布任何内容，也不读取 bundle 字节；未变化的 bundle 保留其 revision，因此浏览器会保留已加载的插件。解析出的 manifest 包名作为浏览器模块身份。若不同的 active Loader source 解析到同一包名，组合会失败；移除冲突来源后，剩余来源无需重启 fiber 即可接替。没有伴随条目重启的 bundle 重建经 `rebuilt()`（HMR 钩子）进入图。 + +如果 flush 期间 Loader 枚举失败，注册表会消费失败批次，但不修改包状态或已发布的图。激活阶段通过组合错误报告失败；稳态下记录警告。只有收到该名称的另一次条目通知后，才会重试。 Node 半侧会在发布前快照每个 `client.js` 入口，并在不构建响应 body 的情况下创建 combo descriptor。它把资源分组为 combo 路由键（`/plugins/??...&rev=...`）：modules row 使用一个 bootstrap combo，其余 row 使用一个或多个 application combo；每个阶段都会在 URL 超过 3 KiB 之前分区。启动图与批次描述符携带同一路由键的应用目录相对形式（`plugins/??...&rev=...`），浏览器文档会按其自身挂载解析它，而响应表仍以绝对路由为键；source-map trailer 则相对该 combo 脚本自身目录解析。脚本 body 在首次 `GET` 时只组合一次，并以对应的 map 引用结尾；map 文件则在首次 map `GET` 时单独读取、校验并组合，`HEAD` 不会物化任一 body。Host 不扫描也不预加载同级 chunk：精确的 `/plugins//client..js?rev=` 请求会通过异步文件 API 读取该脚本并缓存，因此首次异步读取时才物化文件的文件系统也能提供它；其 map 仍会等到 map URL 被请求后才计算。浏览器从所属 row 派生出该 chunk 引用，因此它同样是文档相对形式（`plugins//client..js?rev=`）；chunk 脚本携带的 map trailer 则是裸文件名 `client..js.map?rev=`，由该脚本自身目录解析。每个 combo 或 chunk map 都是 Indexed Source Map v3，并在可用时使用作者提供的 section，否则为已打包 bundle 生成 identity section。首次发布与 HMR 都从入口的 `mtimeMs`、`ctimeMs` 和大小派生逐插件 revision，不对产物内容求哈希。状态变更时间用于区分保留 mtime 和大小的重写。未变化的产物因此会跨 Host 重启保持 revision，SSE 重连不会替换其浏览器插件。共享预设会在该包所有输出写完后标记 `client.js`，因此仅 chunk 发生重建也会更换 owner revision，无需 Host 扫描 chunk。combo revision 从有序 row revision 派生。已公告的 combo 响应与已请求的 chunk 响应会跨无关图重组保持不可变；未知资源或 revision 返回 404。 diff --git a/packages/client/modules/package.json b/packages/client/modules/package.json index 0ad5561a70..558dc133e9 100644 --- a/packages/client/modules/package.json +++ b/packages/client/modules/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-modules", "description": "Client module system, dual-face: node half composes the __DSH_BOOT__ entry graph (incremental dsh.client scan, bundle route, index tap, webPlugins service); browser half is the lazy-CJS module table the vendored cordis Loader consumes as its internal seam", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/modules/src/client/entries.ts b/packages/client/modules/src/client/entries.ts index 587d3ffdd0..e33d0055f8 100644 --- a/packages/client/modules/src/client/entries.ts +++ b/packages/client/modules/src/client/entries.ts @@ -236,7 +236,8 @@ export class ClientEntries { } else if (entry.fiber === undefined) { await this.replace(entry, row.id, row.rev, generation) } else if (entry.fiber.state === FAILED) { - entry.fiber.update(entry.options.config) + // A retry with unchanged config is not a configuration change to persist. + await entry.fiber.update(entry.options.config, true) } } catch (error) { failures.push({ id: row.id, message: String(error) }) diff --git a/packages/client/modules/src/index.ts b/packages/client/modules/src/index.ts index c87f28d4b8..2bfda74d5f 100644 --- a/packages/client/modules/src/index.ts +++ b/packages/client/modules/src/index.ts @@ -10,17 +10,19 @@ * `clientModules` service (the HMR node half's registration/notification * face). * - * Scanning is incremental per package — there is no full-rescan code path. + * Package reconciliation is incremental by Loader entry name. * Every cordis `internal/plugin` emission (fiber construction/disposal) marks * the fiber's entry name dirty; a microtask flush reconciles each dirty name - * against the live loader entries. The activation pass seeds the same dirty - * set with all current entries and flushes synchronously, so first scan and - * steady state share one implementation. Each reconciliation reads the - * package manifest and the bundle metadata again, so an entry that restarts - * after its package was reinstalled or moved publishes them as they are now; - * an unchanged result publishes nothing and does not read the bundle. The - * manifest package name identifies the browser module; distinct active Loader - * sources for that package are a composition error. Bundle rebuilds outside + * against the Loader entries indexed at the start of that flush. Synchronous + * package resolution must not add or remove Loader entries during reconciliation. + * The activation pass seeds the same pending names and flushes synchronously, + * so initial activation and steady state share one implementation. Each + * reconciliation reads the package manifest and the bundle metadata again, + * so an entry that restarts after its package was reinstalled or moved + * publishes them as they are now; an unchanged result publishes nothing and + * does not read the bundle. The manifest package name identifies the browser + * module; distinct active Loader sources for that package are a composition + * error. Bundle rebuilds outside * an entry restart reach the graph through {@link ClientModuleRegistry.rebuilt}. * @module @deepseek-ai/dsh-client-modules */ @@ -1031,11 +1033,17 @@ export class ClientModuleRegistry extends Service { } } - /** Reconcile one entry name against the live Loader sources. @returns whether the table changed. */ - private processOne(entryName: string, onError: (err: Error) => void): boolean { + /** + * Reconcile one entry name against its sources at flush start. + * @param entryName - Loader entry name being reconciled. + * @param entries - same-name entries collected at flush start. + * @param onError - receives package reconciliation failures. + * @returns whether the table changed. + */ + private processOne(entryName: string, entries: readonly Entry[], onError: (err: Error) => void): boolean { const nextSources = new Map() - for (const entry of this.ctx.loader.entries()) { - if (entry.options.name !== entryName || entry.fiber === undefined || entry.disabled) continue + for (const entry of entries) { + if (entry.fiber === undefined || entry.disabled) continue const source = this.resolveSource(entry) if (source !== undefined) nextSources.set(source.sourceKey, source) } @@ -1108,11 +1116,26 @@ export class ClientModuleRegistry extends Service { } private flush(onError: (err: Error) => void): void { + if (this.dirty.size === 0) return + const entriesByName = new Map() + try { + for (const entry of this.ctx.loader.entries()) { + const name = entry.options.name + const entries = entriesByName.get(name) + if (entries) entries.push(entry) + else entriesByName.set(name, [entry]) + } + } catch (error) { + // No package state changed; consume this failed batch and retain the published graph. + this.dirty.clear() + onError(error instanceof Error ? error : new Error(String(error))) + return + } let changed = false for (const entryName of [...this.dirty]) { this.dirty.delete(entryName) try { - if (this.processOne(entryName, onError)) changed = true + if (this.processOne(entryName, entriesByName.get(entryName) ?? [], onError)) changed = true } catch (error) { // Steady state: one broken package must not poison the others; the // activation pass aggregates these into a loud throw instead. diff --git a/packages/client/modules/tests/node-half.client.spec.ts b/packages/client/modules/tests/node-half.client.spec.ts index 283383149c..8ef1d6c89a 100644 --- a/packages/client/modules/tests/node-half.client.spec.ts +++ b/packages/client/modules/tests/node-half.client.spec.ts @@ -164,6 +164,7 @@ function constructWithRoute( contextBaseUrl?: string entryBaseUrl?: string internal?: NonNullable + onEntries?: () => void } = {}, ): { context: Context; service: ClientModuleRegistry; route: Promise } { const ctx = new Context() @@ -173,6 +174,7 @@ function constructWithRoute( ctx.provide('loader', { internal: options.internal, *entries() { + options.onEntries?.() for (const packageName of packageNames) { yield { options: { name: packageName }, @@ -329,6 +331,148 @@ describe('HTML bootstrap facade', () => { }) describe('client bundle activation', () => { + it('enumerates Loader entries once per dirty-name batch and skips empty batches', async () => { + const names = ['@fixture/scan-first', '@fixture/scan-second', '@fixture/scan-retained'] + for (const name of names) writeBuiltPackage(name, {}) + const scans = vi.fn() + const { context, service } = constructWithRoute(names, { onEntries: scans }) + + expect(scans).toHaveBeenCalledTimes(2) + expect(service.graph().entries).toHaveLength(3) + scans.mockClear() + + const removed = names.splice(0, 2) + for (const name of [...removed, removed[0]!]) emitLoaderEntryChange(context, name) + await Promise.resolve() + + expect(scans).toHaveBeenCalledTimes(1) + expect(service.graph().entries.map(entry => entry.id)).toEqual(names) + for (const name of removed) expect(service.clientPath(name)).toBeUndefined() + + scans.mockClear() + context.emit('internal/plugin', context.fiber) + await Promise.resolve() + expect(scans).not.toHaveBeenCalled() + + const emptyScans = vi.fn() + const empty = constructWithRoute([], { onEntries: emptyScans }) + expect(empty.service.graph().entries).toEqual([]) + expect(emptyScans).toHaveBeenCalledTimes(1) + }) + + it('keeps a shared source until its last same-name Loader entry unloads', async () => { + const name = '@fixture/shared-source-owners' + writeBuiltPackage(name, {}) + const names = [name, name] + const { context, service } = constructWithRoute(names) + const initial = service.graph() + + names.pop() + emitLoaderEntryChange(context, name) + await Promise.resolve() + expect(service.graph()).toBe(initial) + expect(service.clientPath(name)).toBeDefined() + + names.pop() + emitLoaderEntryChange(context, name) + await Promise.resolve() + expect(service.graph().entries).toEqual([]) + expect(service.clientPath(name)).toBeUndefined() + }) + + it('reports an activation flush enumeration failure as a composition error', () => { + const name = '@fixture/failed-activation-scan' + writeBuiltPackage(name, {}) + const scans = vi.fn() + .mockImplementationOnce(() => undefined) + .mockImplementationOnce(() => { throw new Error('Loader enumeration failed') }) + expect(() => constructWithRoute([name], { onEntries: scans })).toThrow(AggregateError) + }) + + it.each([new Error('Loader enumeration failed'), 'Loader enumeration failed'])( + 'retains the graph and consumes the failed batch when Loader enumeration throws %s', + async (failure) => { + const names = ['@fixture/failed-scan-first', '@fixture/failed-scan-second', '@fixture/failed-scan-retained'] + for (const name of names) writeBuiltPackage(name, {}) + const scans = vi.fn() + const { context, service, route } = constructWithRoute(names, { onEntries: scans }) + await route + const initial = service.graph() + const warning = vi.spyOn(context.logger, 'warn').mockImplementation(() => undefined) + const removed = names.splice(0, 2) + scans.mockImplementationOnce(() => { throw failure }) + const callbacks: VoidFunction[] = [] + const enqueue = vi.spyOn(globalThis, 'queueMicrotask').mockImplementation(callback => callbacks.push(callback)) + try { + for (const name of removed) emitLoaderEntryChange(context, name) + expect(callbacks).toHaveLength(1) + expect(callbacks[0]!).not.toThrow() + } finally { + enqueue.mockRestore() + } + expect(warning).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ message: 'Loader enumeration failed' })) + expect(service.graph()).toBe(initial) + for (const name of removed) expect(service.clientPath(name)).toBeDefined() + + emitLoaderEntryChange(context, names[0]!) + await Promise.resolve() + expect(service.graph()).toBe(initial) + + for (const name of removed) emitLoaderEntryChange(context, name) + await Promise.resolve() + expect(service.graph().entries.map(entry => entry.id)).toEqual(names) + for (const name of removed) expect(service.clientPath(name)).toBeUndefined() + }, + ) + + it.each(['processing', 'processed'] as const)('consumes pending names once when a %s name is marked again', async (timing) => { + const firstName = '@fixture/reentrant-first' + const secondName = '@fixture/reentrant-second' + const thirdName = '@fixture/reentrant-third' + const names = [firstName, secondName, thirdName] + const hostUrls = new Map() + for (const name of names) { + writeBuiltPackage(name, {}) + const hostPath = join(root!, 'node_modules', ...name.split('/'), 'lib', 'index.js') + writeFileSync(hostPath, 'export default {}\n') + hostUrls.set(name, pathToFileURL(hostPath).href) + } + const resolved: string[] = [] + let duringResolve = (_name: string) => {} + const internal = { + version: 'v2' as const, + resolveSync: (_baseUrl: string, { specifier }: { specifier: string }) => { + resolved.push(specifier) + duringResolve(specifier) + return { format: 'module' as const, url: hostUrls.get(specifier)! } + }, + } + const { context, service } = constructWithRoute(names, { + internal: internal as NonNullable, + }) + const initial = service.graph() + resolved.length = 0 + duringResolve = (name) => { + if (name === firstName) { + emitLoaderEntryChange(context, secondName) + emitLoaderEntryChange(context, thirdName) + if (timing === 'processing') emitLoaderEntryChange(context, firstName) + } else if (name === secondName) { + if (timing === 'processed') emitLoaderEntryChange(context, firstName) + duringResolve = () => {} + } + } + + emitLoaderEntryChange(context, firstName) + emitLoaderEntryChange(context, secondName) + await Promise.resolve() + expect(resolved.splice(0)).toEqual([firstName, secondName]) + + await Promise.resolve() + expect(resolved).toEqual([thirdName, firstName]) + expect(service.graph()).toBe(initial) + }) + it.each(['v1', 'v2'] as const)( 'resolves %s package metadata from the owning entry tree', (version) => { diff --git a/packages/client/product-analytics/package.json b/packages/client/product-analytics/package.json index e73a62160b..9848ca3c08 100644 --- a/packages/client/product-analytics/package.json +++ b/packages/client/product-analytics/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-product-analytics", "description": "Desktop product event collection and authenticated Host reporting", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/resources/package.json b/packages/client/resources/package.json index 944f8f8092..fd54263983 100644 --- a/packages/client/resources/package.json +++ b/packages/client/resources/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-resources", "description": "Unified client resource model: protocol-registered providers turn URL addresses into live values, consumed through the useResource global standard hook", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/shortcuts/package.json b/packages/client/shortcuts/package.json index 77316c991f..8ae1eb16a2 100644 --- a/packages/client/shortcuts/package.json +++ b/packages/client/shortcuts/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-shortcuts", "description": "Application keyboard command registry and physical-key routing", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/store/package.json b/packages/client/store/package.json index 70f255823e..81ce31353c 100644 --- a/packages/client/store/package.json +++ b/packages/client/store/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-store", "description": "React-free observable and snapshot-store contracts with the shared Zustand/Immer engine", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts index ca7bbc4154..5f1cbd355e 100644 --- a/packages/client/tsdown.client.ts +++ b/packages/client/tsdown.client.ts @@ -82,7 +82,7 @@ function styleInjectionModule( * Everything else under @deepseek-ai/* is either a module-table entry * (external) or a leak the purity gate rejects. */ -export const INLINE_SAFE = /^(?:@deepseek-ai\/dsh-(?:file-reference|session|llm|tools|brand|official-bundles|deque|output-retention|typert-protocol|util-crypto|util-values|util-workspace-path)(?:\/|$)|@deepseek-ai\/dsh-util-file-drag$|@deepseek-ai\/dsh-token-meter\/client$|@deepseek-ai\/dsh-native-command\/types$|@deepseek-ai\/dsh-host-open-in-app\/shared$|@deepseek-ai\/dsh-plugin-manager\/registry$|@deepseek-ai\/dsh-agent-preset-registry\/display$|@deepseek-ai\/dsh-api-workspace-controller\/default-workspace$|@deepseek-ai\/dsh-spill-policy\/notice$)/ +export const INLINE_SAFE = /^(?:@deepseek-ai\/dsh-(?:file-reference|session|llm|tools|brand|official-bundles|deque|output-retention|typert-protocol|util-crypto|util-values|util-workspace-path)(?:\/|$)|@deepseek-ai\/dsh-util-file-drag$|@deepseek-ai\/dsh-token-meter\/client$|@deepseek-ai\/dsh-commands\/builtin$|@deepseek-ai\/dsh-native-command\/types$|@deepseek-ai\/dsh-host-open-in-app\/shared$|@deepseek-ai\/dsh-plugin-manager\/registry$|@deepseek-ai\/dsh-agent-preset-registry\/display$|@deepseek-ai\/dsh-api-workspace-controller\/default-workspace$|@deepseek-ai\/dsh-spill-policy\/notice$)/ /** * Vendored framework libraries: rescoped into @deepseek-ai, so the gate below diff --git a/packages/client/ui-agent-preset/package.json b/packages/client/ui-agent-preset/package.json index d370dff454..18982db48e 100644 --- a/packages/client/ui-agent-preset/package.json +++ b/packages/client/ui-agent-preset/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-ui-agent-preset", "description": "Agent-preset surfaces: the default for later sessions, this session's seat, and the composition editor", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/ui-agent-preset/tests/create-plugin-menu-item.client.spec.tsx b/packages/client/ui-agent-preset/tests/create-plugin-menu-item.client.spec.tsx index 578234c898..83ea649c80 100644 --- a/packages/client/ui-agent-preset/tests/create-plugin-menu-item.client.spec.tsx +++ b/packages/client/ui-agent-preset/tests/create-plugin-menu-item.client.spec.tsx @@ -1,4 +1,5 @@ // @vitest-environment jsdom +import { contextMenuHook } from '@deepseek-ai/dsh-client-test-runtime' import { useState, type ComponentProps } from 'react' import { act, cleanup, fireEvent, render, screen } from '@testing-library/react' import { afterEach, describe, expect, it, vi } from 'vitest' @@ -30,6 +31,7 @@ function view(roster: Partial = {}, inMenu = false) { usePanelInfo: unusedHook, useSessions: unusedHook, useSessionStatus: unusedHook, useSessionRetainInfo: unusedHook, useWorkspaces: unusedHook, useResource: unusedHook, ...allowAllAccess, + useContextMenu: contextMenuHook(), load, startCreatorDraft, onDismiss, } function TestMenu() { diff --git a/packages/client/ui-agent-preset/tests/section.client.spec.tsx b/packages/client/ui-agent-preset/tests/section.client.spec.tsx index 1ea42a6af1..59f2bf5842 100644 --- a/packages/client/ui-agent-preset/tests/section.client.spec.tsx +++ b/packages/client/ui-agent-preset/tests/section.client.spec.tsx @@ -1,4 +1,5 @@ // @vitest-environment jsdom +import { contextMenuHook } from '@deepseek-ai/dsh-client-test-runtime' import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react' import { afterEach, expect, it, vi } from 'vitest' import { allowAllAccess, bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime' @@ -24,6 +25,7 @@ function view(partial: Partial = {}, startCreatorDraft? usePanelInfo: unusedHook, useSessions: unusedHook, useSessionStatus: unusedHook, useSessionRetainInfo: unusedHook, useWorkspaces: unusedHook, useResource: unusedHook, ...allowAllAccess, + useContextMenu: contextMenuHook(), useAgentPresetSection: bindSnapshotSelector(store), useDeveloperTools: bindSnapshotSelector(developerTools), t: key => translations.get(key) ?? key } diff --git a/packages/client/ui-approval/package.json b/packages/client/ui-approval/package.json index 9ab90c9d66..a1a6a8e7c2 100644 --- a/packages/client/ui-approval/package.json +++ b/packages/client/ui-approval/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-ui-approval", "description": "Approval composer takeover over the scoped Remote Event waterfall", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/ui-attachment/README.i18n.yaml b/packages/client/ui-attachment/README.i18n.yaml index 65b551434d..fe9e9182e5 100644 --- a/packages/client/ui-attachment/README.i18n.yaml +++ b/packages/client/ui-attachment/README.i18n.yaml @@ -15,8 +15,8 @@ en: d152484eb41ac6b4 zh: 09388d293f9be9cb /deepseek-ai-dsh-client-ui-attachment/use-this-package: - en: df47b6abd789dcb5 - zh: 7e17c7f18631a572 + en: 02870b565a595b51 + zh: c31d02d76d78094b /deepseek-ai-dsh-client-ui-attachment/use-this-package/draft-attachments: en: 8246cb3c470e3fc5 zh: 7028cf466a832b99 @@ -30,8 +30,8 @@ en: 07204b7d538b7434 zh: 705cc6b0c9387cce /deepseek-ai-dsh-client-ui-attachment/further-exploration: - en: 733ac3e4df52d6e9 - zh: 98a6a8cac7d66645 + en: 661e8285abb71b5d + zh: 0c421325537cdcda /deepseek-ai-dsh-client-ui-attachment/model-experience: en: 25566605d7b38667 zh: 927d3ea272893296 diff --git a/packages/client/ui-attachment/README.md b/packages/client/ui-attachment/README.md index 29e7f3aba0..7b3158b50b 100644 --- a/packages/client/ui-attachment/README.md +++ b/packages/client/ui-attachment/README.md @@ -25,7 +25,7 @@ This package renders everything the conversation UI shows about attachments: one ## Use this package -Image drag actions and the composer’s original-file reader arrive through slot injection from [ui-file-drag](../ui-file-drag/README.md). The image gallery Factory also receives these actions through its declared inject face; custom Factory replacements must supply that face. +Image drag actions and the composer’s original-file reader arrive through slot injection from [ui-file-drag](../ui-file-drag/README.md). The image gallery Factory also receives these actions through its declared inject face; custom Factory replacements must supply that face. `MessageImage` and `ImageGallery` require the ordinary `getTriggerProps` factory; they bind each original image once and pass the same `contextMenuProps` to its thumbnail and lightbox. Mount this plugin alongside [`ui-conversation`](../ui-conversation/README.md) and [`ui-tool`](../ui-tool/README.md) when tool results need an image gallery. It waits for their slot declarations and registers its components into them. Users then see the mixed draft-attachment rail, DeepSeek Web file cards with upload controls, the drop overlay with its limits line, message images sized by count, the tool card's gallery, and the Escape/mask/close lightbox. @@ -82,6 +82,8 @@ Read these pages when the attachment surface is not enough. They move from the s ----- +Message images and original previews forward context gestures through the shared gallery to [ui-context-menu](../ui-context-menu/README.md). Original authorized URLs and MIME metadata remain independent from thumbnail presentation. + ## Model Experience diff --git a/packages/client/ui-attachment/README.zh.md b/packages/client/ui-attachment/README.zh.md index 80db6ae928..7391553fe2 100644 --- a/packages/client/ui-attachment/README.zh.md +++ b/packages/client/ui-attachment/README.zh.md @@ -25,7 +25,7 @@ kind: "package-reference" ## 使用本包 -图片拖放回调与输入框的原图读取回调通过 slot 注入从 [ui-file-drag](../ui-file-drag/README.zh.md) 获取。图片图库 Factory 也通过声明的注入接口接收回调；自定义 Factory 替换实现必须提供该接口。 +图片拖放回调与输入框的原图读取回调通过 slot 注入从 [ui-file-drag](../ui-file-drag/README.zh.md) 获取。图片图库 Factory 也通过声明的注入接口接收回调；自定义 Factory 替换实现必须提供该接口。 `MessageImage` 和 `ImageGallery` 必须接收普通 `getTriggerProps` 函数，每张原图绑定一次，将同一份 `contextMenuProps` 传给缩略图和灯箱。 与 [`ui-conversation`](../ui-conversation/README.zh.md) 一起挂载本插件，工具结果需要图片图库时也要挂载 [`ui-tool`](../ui-tool/README.zh.md)。插件等待这些 slot 的声明，并把组件注册进去。用户会看到混合草稿附件栏、带上传控件的 DeepSeek Web 文件卡、带限制说明的拖放遮罩、按数量定尺寸的消息图片、工具卡片图库，以及支持 Escape、遮罩和关闭按钮的灯箱。 @@ -82,6 +82,8 @@ Trajectory 附件行使用 48px 方形缩略图，完整缩放图片而不裁剪 ----- +消息图片和原图预览通过共享图片库将右键手势转发给 [ui-context-menu](../ui-context-menu/README.zh.md)。原始授权 URL 与 MIME 元数据独立于缩略图展示。 + ## 模型体验 diff --git a/packages/client/ui-attachment/package.json b/packages/client/ui-attachment/package.json index b63d7f9ce2..2f5d2d5d93 100644 --- a/packages/client/ui-attachment/package.json +++ b/packages/client/ui-attachment/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-ui-attachment", "description": "Dynamic attachment presentation plugin for conversation input, message-image, and trajectory image slots", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -35,7 +35,8 @@ "@deepseek-ai/dsh-client-ui-renderer", "@deepseek-ai/dsh-client-ui-trajectory", "@deepseek-ai/dsh-client-ui-tool", - "@deepseek-ai/dsh-client-ui-file-drag" + "@deepseek-ai/dsh-client-ui-file-drag", + "@deepseek-ai/dsh-client-ui-context-menu" ], "platform": "web" } @@ -60,7 +61,8 @@ "@deepseek-ai/dsh-client-ui-tool": "workspace:*", "clsx": "^2.0.0", "@deepseek-ai/dsh-client-ui-file-drag": "workspace:*", - "@deepseek-ai/dsh-util-file-drag": "workspace:*" + "@deepseek-ai/dsh-util-file-drag": "workspace:*", + "@deepseek-ai/dsh-client-ui-context-menu": "workspace:*" }, "files": [ "locale/*.json", diff --git a/packages/client/ui-attachment/src/MessageImage.tsx b/packages/client/ui-attachment/src/MessageImage.tsx index 4cce54baa5..7afdb8b245 100644 --- a/packages/client/ui-attachment/src/MessageImage.tsx +++ b/packages/client/ui-attachment/src/MessageImage.tsx @@ -1,3 +1,4 @@ +import type { ContextMenuBindings } from '@deepseek-ai/dsh-client-ui-context-menu/client' import { useCallback, useEffect, useMemo, useState } from 'react' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import { IconLoadingOutlineRegular, IconRefreshOutlineRegular, DraggableImage, ImageLightbox, type FileDragActions } from '@deepseek-ai/dsh-client-ui-primitives' @@ -6,7 +7,7 @@ import css from './MessageImage.module.css' export type { MessageImageLabels } from '@deepseek-ai/dsh-client-ui-conversation/client' -/** Loads a session-authorized durable image URL and may expose a cached URL synchronously. */ +/** Loads a Gateway-authorized durable image URL and may expose a cached URL synchronously. */ export type ImageLoader = ((attachment: ImageAttachmentRef) => Promise) & { peek?: (attachment: ImageAttachmentRef) => string | undefined } @@ -62,17 +63,18 @@ function dimensionsOf(image: MessageImageSpec): { readonly width: number; readon * List thumbnails use status icons with localized tooltips and accessible names. * * @param props.image - the durable reference to load, or the local preview to display. - * @param props.load - session-authorized URL loader for the durable arm. + * @param props.load - Gateway-authorized URL loader for the durable arm. * @param props.variant - lone image, cropped gallery tile, or uncropped list thumbnail. * @param props.labels - resolved strings (tooltip, loading, retry, lightbox). * @returns the bounded thumbnail button, or the retry control on failure. */ -export function MessageImage({ image, load, variant, labels, fileDrag }: { +export function MessageImage({ image, load, variant, labels, fileDrag, getTriggerProps }: { image: MessageImageSpec load: ImageLoader variant: 'single' | 'tile' | 'thumbnail' fileDrag: FileDragActions labels: MessageImageLabels + getTriggerProps: ContextMenuBindings['getTriggerProps'] }) { const preview = 'preview' in image ? image.preview : undefined const attachment = 'attachment' in image ? image.attachment : undefined @@ -110,6 +112,9 @@ export function MessageImage({ image, load, variant, labels, fileDrag }: { const src = preview?.url ?? loaded const label = ('attachment' in image ? image.label : undefined) ?? preview?.name ?? attachment?.name ?? labels.image + const contextMenuProps = getTriggerProps(src === null ? undefined : { kind: 'image', value: { + url: src, name: label, ...(attachment === undefined ? {} : { mediaType: attachment.mediaType }), + } }) const loadingThumbnail = variant === 'thumbnail' && src === null if (error) return ( - {open && src !== null && } + {open && src !== null && } ) } /** Wrapping image group shared by user and assistant history: a lone image * renders large unless its owner requests compact tiles or contained list thumbnails. */ -export function ImageGallery({ images, load, align, compact = false, thumbnail = false, labels, fileDrag }: { +export function ImageGallery({ images, load, align, compact = false, thumbnail = false, labels, fileDrag, getTriggerProps }: { images: readonly MessageImageSpec[] load: ImageLoader align: 'start' | 'end' @@ -161,6 +168,7 @@ export function ImageGallery({ images, load, align, compact = false, thumbnail = thumbnail?: boolean fileDrag: FileDragActions labels: MessageImageLabels + getTriggerProps: ContextMenuBindings['getTriggerProps'] }) { if (images.length === 0) return null const variant = thumbnail ? 'thumbnail' : compact || images.length > 1 ? 'tile' : 'single' @@ -174,6 +182,7 @@ export function ImageGallery({ images, load, align, compact = false, thumbnail = variant={variant} fileDrag={fileDrag} labels={labels} + getTriggerProps={getTriggerProps} /> ))} diff --git a/packages/client/ui-attachment/src/client/MessageImages.tsx b/packages/client/ui-attachment/src/client/MessageImages.tsx index 0a95ddc66d..176940777f 100644 --- a/packages/client/ui-attachment/src/client/MessageImages.tsx +++ b/packages/client/ui-attachment/src/client/MessageImages.tsx @@ -12,11 +12,12 @@ type MessageImagesProps = MessageImagesOwnerProps & PropsRenderFactories * @param props - image sources, authorized loader, layout hints, optional labels, and Factory locale seat. * @returns the official gallery; no Session binding is needed by this component. */ -export function MessageImagesContent({ images, loadImage, align, compact = false, thumbnail = false, labels, t, fileDrag }: +export function MessageImagesContent({ images, loadImage, align, compact = false, thumbnail = false, labels, t, fileDrag, useContextMenu }: FactoryComponentPropsOf<'conversation.images.content'>) { + const { getTriggerProps } = useContextMenu() const resolved = useMemo(() => labels ?? messageImageLabels(t), [labels, t]) return + compact={compact} thumbnail={thumbnail} labels={resolved} fileDrag={fileDrag} getTriggerProps={getTriggerProps} /> } /** diff --git a/packages/client/ui-attachment/src/client/index.ts b/packages/client/ui-attachment/src/client/index.ts index 7ef44e1dd8..ef0f496a78 100644 --- a/packages/client/ui-attachment/src/client/index.ts +++ b/packages/client/ui-attachment/src/client/index.ts @@ -1,5 +1,7 @@ +import type {} from '@deepseek-ai/dsh-client-ui-context-menu/client' /** Browser attachment plugin: composer entries and independently replaceable image galleries. */ import type { Context as ClientContext } from '@deepseek-ai/cordis' +import type { SlotFactoryMap } from '@deepseek-ai/dsh-client-ui-slots' import type {} from '@deepseek-ai/dsh-client-ui-chat/client' import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' @@ -9,6 +11,8 @@ import type {} from '@deepseek-ai/dsh-client-ui-file-drag/client' import { ComposerAttachments, type ComposerAttachmentsInjected } from './ComposerAttachments.tsx' import { MessageImages, MessageImagesContent } from './MessageImages.tsx' +type MessageImagesInjected = SlotFactoryMap['conversation.images.content']['inject'] + /** Slot registry required by the attachment presentation plugin. */ export const inject = ['slots', 'fileDrag'] @@ -19,7 +23,9 @@ export const inject = ['slots', 'fileDrag'] export function apply(ctx: ClientContext): void { ctx.slots.registerFactory({ name: 'conversation.images.content', scope: 'root', locale: 'conversation', - inject: () => ({ fileDrag: ctx.fileDrag.actions }), + inject: (): MessageImagesInjected => ({ + fileDrag: ctx.fileDrag.actions, + }), }, MessageImagesContent) ctx.slots.inject('conversation.input.attachments', () => ctx.slots.register({ name: 'conversation.input.attachments', diff --git a/packages/client/ui-attachment/tests/image-slot-isolation.client.spec.tsx b/packages/client/ui-attachment/tests/image-slot-isolation.client.spec.tsx index 09f0db62cb..98f3d923a3 100644 --- a/packages/client/ui-attachment/tests/image-slot-isolation.client.spec.tsx +++ b/packages/client/ui-attachment/tests/image-slot-isolation.client.spec.tsx @@ -1,6 +1,7 @@ // @vitest-environment jsdom /** Independent domain image positions with one shared official gallery Factory. */ import * as fileDragPlugin from '@deepseek-ai/dsh-client-ui-file-drag/client' +import { contextMenuHook } from '@deepseek-ai/dsh-client-test-runtime' import { act, cleanup, within } from '@testing-library/react' import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest' import { AttachmentId } from '@deepseek-ai/dsh-attachment' @@ -29,6 +30,10 @@ async function bench() { runtime.slots.installLocale(locale) new UiConversation(runtime.ctx, runtime.sessions) await runtime.mount(fileDragPlugin) + runtime.ctx.provide('contextMenus', { open: vi.fn() } as never) + runtime.slots.provideRoot({ props: { + useContextMenu: contextMenuHook((target, point) => { runtime.ctx.contextMenus.open(target, point) }), + } }) await runtime.mount(attachmentPlugin) await runtime.sessions.add({ id: 'image-domains' }) const session = runtime.sessions.retainFor(runtime.ctx, SessionId('image-domains')) diff --git a/packages/client/ui-attachment/tests/message-image.client.spec.tsx b/packages/client/ui-attachment/tests/message-image.client.spec.tsx index 7d0ee96bea..68cf23a7c8 100644 --- a/packages/client/ui-attachment/tests/message-image.client.spec.tsx +++ b/packages/client/ui-attachment/tests/message-image.client.spec.tsx @@ -1,4 +1,5 @@ // @vitest-environment jsdom +import { contextMenuHook } from '@deepseek-ai/dsh-client-test-runtime' import { useState } from 'react' import type { PropsRenderFactories, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' @@ -39,15 +40,17 @@ describe('MessageImage', () => { const load = Object.assign(vi.fn(() => new Promise(() => {})), { peek: vi.fn(() => 'blob:seeded'), }) - const view = render() + const view = render() expect(view.queryByText('图片加载中…')).toBeNull() expect((view.getByAltText('history.png') as HTMLImageElement).src).toContain('blob:seeded') expect(load).toHaveBeenCalledWith(attachment) }) - it('loads a session-authorized URL, bounds the thumbnail, and clicks into the original', async () => { + it('loads a Gateway-authorized URL, bounds the thumbnail, and clicks into the original', async () => { const load = vi.fn().mockResolvedValue('blob:history') - const view = render() + const view = render() const frame = view.getByRole('button', { name: 'history.png，点击查看原图' }) expect(frame.getAttribute('style')).toContain('width: 240px') expect(frame.getAttribute('style')).toContain('height: 120px') @@ -62,7 +65,8 @@ describe('MessageImage', () => { it('ignores a click while the thumbnail is still loading', () => { const load = vi.fn(() => new Promise(() => {})) - const view = render() + const view = render() const frame = view.getByRole('button', { name: 'history.png，点击查看原图' }) expect(view.getByText('图片加载中…')).toBeTruthy() fireEvent.click(frame) @@ -72,7 +76,8 @@ describe('MessageImage', () => { it('falls back to the image label for an unnamed attachment', async () => { const { name: _named, ...unnamed } = attachment const load = vi.fn().mockResolvedValue('blob:unnamed') - const view = render() + const view = render() await waitFor(() => { expect(view.getByAltText('图片')).toBeTruthy() }) expect(view.getByRole('button', { name: '图片，点击查看原图' })).toBeTruthy() }) @@ -82,7 +87,8 @@ describe('MessageImage', () => { .mockRejectedValueOnce(new Error('offline')) .mockRejectedValueOnce(new Error('still offline')) .mockResolvedValueOnce('blob:retry') - const view = render() + const view = render() const retry = await view.findByRole('button', { name: '图片加载失败，点击重试' }) fireEvent.click(retry) const retryAgain = await view.findByRole('button', { name: '图片加载失败，点击重试' }) @@ -94,7 +100,8 @@ describe('MessageImage', () => { it('clamps extreme aspect ratios and anchors the crop toward the informative edge', async () => { const load = vi.fn().mockResolvedValue('blob:ratio') const tall = render( - , + , ) const tallFrame = tall.getByRole('button', { name: 'history.png，点击查看原图' }) expect(tallFrame.getAttribute('style')).toContain('width: 60px') @@ -103,7 +110,8 @@ describe('MessageImage', () => { expect(tall.getByAltText('history.png').style.objectPosition).toBe('center top') tall.unmount() const wide = render( - , + , ) const wideFrame = wide.getByRole('button', { name: 'history.png，点击查看原图' }) expect(wideFrame.getAttribute('style')).toContain('width: 240px') @@ -112,7 +120,8 @@ describe('MessageImage', () => { expect(wide.getByAltText('history.png').style.objectPosition).toBe('left center') wide.unmount() const small = render( - , + , ) const smallFrame = small.getByRole('button', { name: 'history.png，点击查看原图' }) expect(smallFrame.getAttribute('style')).toContain('width: 100px') @@ -121,7 +130,8 @@ describe('MessageImage', () => { it('renders a tile at the fixed square without inline sizing', () => { const load = vi.fn(() => new Promise(() => {})) - const view = render() + const view = render() const frame = view.getByRole('button', { name: 'history.png，点击查看原图' }) expect(frame.getAttribute('data-variant')).toBe('tile') expect(frame.getAttribute('style')).toBeNull() @@ -129,7 +139,9 @@ describe('MessageImage', () => { it.each(['tile', 'thumbnail'] as const)('keeps the %s variant on the failed-load retry control', async (variant) => { const load = vi.fn().mockRejectedValue(new Error('offline')) - const view = render() + const view = render() const retry = await view.findByRole('button', { name: '图片加载失败，点击重试' }) expect(retry.getAttribute('data-variant')).toBe(variant) }) @@ -140,7 +152,8 @@ describe('MessageImage', () => { ] as const)('labels thumbnail status icons and retries a failed read in %s', async (_locale, statusLabels) => { const pending = Promise.withResolvers() const load = vi.fn().mockReturnValueOnce(pending.promise).mockResolvedValue('blob:retry') - const view = render() + const view = render() const loading = view.getByRole('button', { name: statusLabels.loading }) expect(loading.getAttribute('title')).toBe(statusLabels.loading) expect(loading.getAttribute('aria-busy')).toBe('true') @@ -164,7 +177,8 @@ describe('MessageImage', () => { it('uses the owner display name for an unnamed thumbnail and its original-image viewer', async () => { const { name: _name, ...unnamed } = attachment const load = vi.fn().mockRejectedValueOnce(new Error('offline')).mockResolvedValue('blob:thumbnail') - const view = render() + const view = render() fireEvent.click(await view.findByRole('button', { name: labels.loadFailed })) const image = await view.findByAltText('Image 2') expect(image.closest('button')?.getAttribute('data-variant')).toBe('thumbnail') @@ -182,13 +196,15 @@ describe('MessageImage', () => { it('ignores a load settling after unmount', async () => { let resolve: ((url: string) => void) | undefined const load = vi.fn(() => new Promise((r) => { resolve = r })) - const view = render() + const view = render() view.unmount() resolve?.('blob:late') await Promise.resolve() let reject: ((error: Error) => void) | undefined const failing = vi.fn(() => new Promise((_r, rej) => { reject = rej })) - const second = render() + const second = render() second.unmount() reject?.(new Error('late failure')) await Promise.resolve() @@ -199,7 +215,7 @@ describe('MessageImage preview arm', () => { it('displays a local preview immediately, without the loader, sized by its probed dimensions', () => { const load = vi.fn() const view = render( - { it('sizes an unprobed lone preview as a square crop and falls back to the image label', () => { const load = vi.fn() const view = render( - , + , ) const img = view.getByAltText('图片') as HTMLImageElement const frame = img.closest('button') as HTMLButtonElement @@ -227,7 +244,8 @@ describe('MessageImage preview arm', () => { it('opens the lightbox from a preview thumbnail', () => { const view = render( - '')} variant="tile" labels={labels} />, + '')} variant="tile" labels={labels} />, ) fireEvent.click(view.getByRole('button', { name: '图片，点击查看原图' })) expect(view.getByRole('dialog', { name: '原图预览' })).toBeTruthy() @@ -237,10 +255,11 @@ describe('MessageImage preview arm', () => { describe('ImageGallery', () => { it('renders nothing without images and an aligned wrapping group with them', async () => { const load = vi.fn().mockResolvedValue('blob:gallery') - const empty = render() + const empty = render() expect(empty.container.firstChild).toBeNull() const view = render( - { it('renders a lone image large and compact or grouped images as square tiles', () => { const load = vi.fn(() => new Promise(() => {})) - const lone = render() + const lone = render() expect(lone.container.querySelectorAll('[data-variant="single"]')).toHaveLength(1) lone.unmount() const compact = render( - , + , ) expect(compact.container.querySelectorAll('[data-variant="tile"]')).toHaveLength(1) compact.unmount() const several = render( - , + , ) expect(several.container.querySelectorAll('[data-variant="tile"]')).toHaveLength(3) }) @@ -277,6 +299,10 @@ describe('ImageGallery', () => { runtime.ctx.provide('locale', locale) runtime.slots.installLocale(locale) runtime.ctx.provide('fileDrag', { actions: fileDrag, read: () => undefined }) + runtime.ctx.provide('contextMenus', { open: vi.fn() } as never) + runtime.slots.provideRoot({ props: { + useContextMenu: contextMenuHook((target, point) => { runtime.ctx.contextMenus.open(target, point) }), + } }) await runtime.mount(attachmentPlugin) const images = [{ preview: { url: 'blob:labels', name: 'preview.png' } }] const loadImage = vi.fn(async () => 'blob:unused') @@ -291,10 +317,14 @@ describe('ImageGallery', () => { }) const view = runtime.renderRoot() const image = view.getByAltText('preview.png') + fireEvent.contextMenu(image, { clientX: 7, clientY: 8 }) + expect(vi.spyOn(runtime.ctx.contextMenus, 'open')).toHaveBeenCalledWith({ kind: 'image', value: { url: 'blob:labels', name: 'preview.png' } }, { x: 7, y: 8 }) const frame = view.getByRole('button', { name: 'preview.png，点击查看原图' }) expect(frame.getAttribute('title')).toBe(labels.open) fireEvent.click(frame) expect(view.getByRole('dialog', { name: labels.lightbox.dialog })).toBeTruthy() + fireEvent.contextMenu(view.getByRole('dialog').querySelector('img')!, { clientX: 13, clientY: 14 }) + expect(vi.spyOn(runtime.ctx.contextMenus, 'open')).toHaveBeenLastCalledWith({ kind: 'image', value: { url: 'blob:labels', name: 'preview.png' } }, { x: 13, y: 14 }) fireEvent.click(view.getByRole('button', { name: labels.lightbox.close })) fireEvent.click(view.getByRole('button', { name: 'Default labels' })) const defaultFrame = view.getByRole('button', { name: 'preview.png, click to view original' }) @@ -318,6 +348,10 @@ describe('ImageGallery', () => { runtime.slots.installLocale(locale) await runtime.declare({ 'conversation.chat.message.images': { kind: 'single', scope: 'session' } }) runtime.ctx.provide('fileDrag', { actions: fileDrag, read: () => undefined }) + runtime.ctx.provide('contextMenus', { open: vi.fn() } as never) + runtime.slots.provideRoot({ props: { + useContextMenu: contextMenuHook((target, point) => { runtime.ctx.contextMenus.open(target, point) }), + } }) await runtime.mount(attachmentPlugin) await runtime.sessions.add({ id: 'message-images-test' }) const session = runtime.sessions.retainFor(runtime.ctx, SessionId('message-images-test')) @@ -330,6 +364,8 @@ describe('ImageGallery', () => { expect(view.getByRole('button', { name: 'history.png，点击查看原图' })).toBeTruthy() expect(container.querySelector('[data-align="end"]')).not.toBeNull() expect(loadImage).toHaveBeenCalledWith(attachment) + fireEvent.contextMenu(view.getByAltText('history.png'), { clientX: 9, clientY: 10 }) + expect(vi.spyOn(runtime.ctx.contextMenus, 'open')).toHaveBeenCalledWith({ kind: 'image', value: { url: 'blob:slot-image', name: 'history.png', mediaType: 'image/png' } }, { x: 9, y: 10 }) expect(view.getByRole('button', { name: 'history.png，点击查看原图' }).getAttribute('data-variant')).toBe('single') for (const [compact, thumbnail, variant] of [ [true, false, 'tile'], @@ -346,3 +382,16 @@ describe('ImageGallery', () => { }) const fileDrag = { prepare: vi.fn(async () => ({ start: () => true, release: () => {} })), reportFailure: vi.fn() } + +it('opens image menus from the thumbnail and lightbox using the original source', async () => { + const openImageMenu = vi.fn() + const view = render( 'blob:original')} + variant="single" labels={labels} />) + const image = await view.findByAltText('history.png') + fireEvent.contextMenu(image, { clientX: 18, clientY: 29 }) + expect(openImageMenu).toHaveBeenLastCalledWith({ kind: 'image', value: { url: 'blob:original', name: 'history.png', mediaType: attachment.mediaType } }, { x: 18, y: 29 }) + fireEvent.click(image) + fireEvent.contextMenu(view.getByRole('dialog').querySelector('img')!, { clientX: 31, clientY: 42 }) + expect(openImageMenu).toHaveBeenLastCalledWith({ kind: 'image', value: { url: 'blob:original', name: 'history.png', mediaType: attachment.mediaType } }, { x: 31, y: 42 }) +}) diff --git a/packages/client/ui-attachment/tests/plugin.client.spec.ts b/packages/client/ui-attachment/tests/plugin.client.spec.ts index a14099543e..706dc4531b 100644 --- a/packages/client/ui-attachment/tests/plugin.client.spec.ts +++ b/packages/client/ui-attachment/tests/plugin.client.spec.ts @@ -21,6 +21,7 @@ async function bench() { await ctx.fiber.dispose() }) ctx.provide('sessions', sessions) + ctx.provide('contextMenus', { open: vi.fn() } as never) ctx.provide('locale', new LocaleRuntime(ctx)) await ctx.plugin(SlotRegistry).await() ctx.slots.register({ @@ -33,11 +34,13 @@ async function bench() { 'tool.call.images': { kind: 'single', scope: 'session' }, }, } as never, () => null) - ctx.provide('fileDrag', { actions: fileDrag, read: () => undefined }) + const readFileDrag = vi.fn(() => undefined) + ctx.provide('fileDrag', { actions: fileDrag, read: readFileDrag }) + const register = vi.spyOn(ctx.slots, 'register') const registerFactory = vi.spyOn(ctx.slots, 'registerFactory') const fiber = ctx.plugin({ inject: [...inject], apply }) await fiber.await() - return { ctx, fiber, registerFactory } + return { ctx, fiber, register, registerFactory, readFileDrag } } describe('attachment plugin', () => { @@ -46,7 +49,7 @@ describe('attachment plugin', () => { }) it('registers all entries and removes them with the plugin fiber', async () => { - const { ctx, fiber, registerFactory } = await bench() + const { ctx, fiber, register, registerFactory, readFileDrag } = await bench() expect(inject).toEqual(['slots', 'fileDrag']) expect(registerFactory.mock.calls[0]?.[0]).toMatchObject({ name: 'conversation.images.content', scope: 'root', locale: 'conversation', @@ -57,6 +60,10 @@ describe('attachment plugin', () => { expect(ctx.slots.entries('conversation.input.attachments')).toMatchObject([{ locale: 'conversation', component: ComposerAttachments, }]) + const composer = register.mock.calls.find(([options]) => options.name === 'conversation.input.attachments')! + const injectComposer = composer[0].inject as () => { readFileDrag: () => undefined } + injectComposer().readFileDrag() + expect(readFileDrag).toHaveBeenCalledOnce() for (const name of IMAGE_SLOTS) { expect(ctx.slots.entries(name)).toMatchObject([{ component: MessageImages, options: { priority: 100 } }]) } diff --git a/packages/client/ui-attachment/tsconfig.json b/packages/client/ui-attachment/tsconfig.json index 1b7d6e0129..853d6a70e2 100644 --- a/packages/client/ui-attachment/tsconfig.json +++ b/packages/client/ui-attachment/tsconfig.json @@ -27,7 +27,7 @@ "path": "../ui-tool" }, { - "path": "../ui-trajectory" + "path": "../ui-trajectory/tsconfig.client.json" }, { "path": "../ui-slots" @@ -43,6 +43,9 @@ }, { "path": "../../util/file-drag" + }, + { + "path": "../ui-context-menu" } ] } diff --git a/packages/client/ui-brand-official/package.json b/packages/client/ui-brand-official/package.json index e70b38f4d2..468dd1613d 100644 --- a/packages/client/ui-brand-official/package.json +++ b/packages/client/ui-brand-official/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-ui-brand-official", "description": "Official DeepSeek Harness brand occupants for the Web client's sidebar slots", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml index 2ff8f221ce..5b652c5425 100644 --- a/packages/client/ui-chat/README.i18n.yaml +++ b/packages/client/ui-chat/README.i18n.yaml @@ -15,14 +15,14 @@ en: 41cd21266011d571 zh: 3172d1a2acbb27b7 /deepseek-ai-dsh-client-ui-chat/reference-previews: - en: a05d85ff4949b526 - zh: 7261ffc98665e9e7 + en: 9386791a9e5efa00 + zh: 7cb9f3bbc42319d6 /deepseek-ai-dsh-client-ui-chat/hidden-chat-rows: - en: cbf1f0a2205046a5 - zh: 2e59d0815351349f + en: b0c4e6711d69d2f8 + zh: 09add0ea1a243922 /deepseek-ai-dsh-client-ui-chat/command-and-failure-rows: - en: 41dcd70e14ebe9cc - zh: ededead572b59037 + en: be90c24392fb021b + zh: 992b8745b385f9ab /deepseek-ai-dsh-client-ui-chat/turn-token-usage: en: cfdfe3d99d3f4e09 zh: 9330bad3d3f7a689 @@ -36,8 +36,8 @@ en: 3afad0b4c6bf9ce0 zh: d8179ba4ee9fcd61 /deepseek-ai-dsh-client-ui-chat/scroll-ownership: - en: 009ecb4fecd4ee9e - zh: ec2714337a1102c5 + en: dd4e69828096c3a0 + zh: 2a9bc370f44efcd7 /deepseek-ai-dsh-client-ui-chat/model-experience: en: c17b4dd43a61c569 zh: f7414309810c3a08 diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md index ceeae1d086..56b30d271b 100644 --- a/packages/client/ui-chat/README.md +++ b/packages/client/ui-chat/README.md @@ -37,13 +37,15 @@ Image drag actions arrive through the image entry’s inject face from [ui-file- Sent generic-file attachments retain the draft's [file-card radius](../../../docs/ui-radius.md#radius-scale). -`ChatView` supplies file and HTTP(S) navigation through the existing `MarkdownDelegateProvider` around its node list, passing `requestOpenFile`, `openExternalLink`, and `fileImages` directly. Its file opener retains Chat's failure feedback and retry handling. Assistant Markdown file links open in the right Sidebar after the message settles, including references to unmodified files. Relative paths resolve in the viewed Session's workspace; absolute paths retain the same Session's filesystem access. `#L24` and `#L24-L30` navigate to the first specified line and reuse an existing file tab. Missing files show the preview's error state. +`ChatView` supplies file and HTTP(S) navigation through the existing `MarkdownDelegateProvider` around its node list, passing `requestOpenFile`, `openExternalLink`, and `fileImages` directly. Its file opener retains Chat's failure feedback and retry handling. Assistant Markdown file links open in the right Sidebar after the message settles, including references to unmodified files. Relative paths resolve in the viewed Session's workspace; absolute paths retain the same Session's filesystem access. [Supported Markdown line references](../ui-primitives/README.md#rendering-agent-output) navigate to the first specified line and reuse an existing file tab. Missing files show the preview's error state. Native message images use separate user and output positions. The `conversation.chat.user.content` Factory declares `conversation.chat.user.images`, which `UserContent` renders; the Assistant node registration declares `conversation.chat.message.images`, which `AssistantMarkdown` renders. Both receive image sources, the authorized `loadImage`, and layout options through explicit props. Their official `MessageImages` entries call the shared root-scoped `conversation.images.content` Factory. Each position can be replaced independently without duplicating the gallery implementation. The session-scoped `conversation.chat.user.content` Factory renders only the user content stack: text, extra blocks, image/file attachments in input order, and reference summaries. Its [`UserContentInput`](src/client/contract/slots.ts) carries prepared `content`, transform `facts`, display props, and explicit `loadImage`; node-owned injections provide reference actions. It calls the shared `conversation.user.text` Factory for text and its own image Slot for images. Direct callers need a Session binding and supply their own row wrapper. -`UserStyleBubble` and the [source-specific wrappers]() retain the user row, keys, pending/echo markers, timestamps, copy controls, and other message actions. The content Factory reads neither source-specific models nor private Context, and is not a global user-content override entry point. +`UserStyleBubble` and the [source-specific wrappers]() retain the user row, keys, pending/echo markers, timestamps, copy controls, and other message actions. The content Factory reads neither source-specific models nor private Context, and is not a global user-content override entry point. + +The official user and steering renderer declares the session-scoped `conversation.chat.user.before` chain slot at its `user` registration and renders it directly above the bubble with `renderSlotChain`; the `steering` registration shares the renderer without owning the seat. Owner props carry the durable message `source` and row `kind`; each entry’s `select` matches its own sources, and the first non-null result reaches the elected component as `matched`. No match displays no content. Entries own their markup and copy; Chat does not interpret message sources. Standalone Markdown images show contained previews and open the shared image lightbox; local paths resolve against the viewed workspace after settlement. Image file links keep their sidebar activation and show a thumbnail after hover dwell or keyboard focus. Escape dismisses the thumbnail. Failed images retain a localized status and their description; no duplicate-image filtering is applied. @@ -56,11 +58,15 @@ Chat omits system-prompt, ordinary Context injection, and `permission` command r When an Assistant attempt retires without a visible message, Chat hides its already-published Node instead of removing its key. A retry in the same Step reuses that key when visible content returns. This also applies when the loaded window lacks the Step start. +Text and reasoning contribute to Assistant visibility only when they contain a non-whitespace character. Streaming appends reuse each block's visibility; block replacement and finalized messages recalculate it while preserving the original text. + ## Command and failure rows Generic command rows retain the ordinary command glyph in every lifecycle state; failure remains explicit through the row state and summary. Every terminal Turn failure renders its inline red-dot row; a quota failure's row states the neutral `message.failure.quota` copy instead of the provider message. The transient notice for a newly appended `QUOTA` or `ACCOUNT_QUOTA` comes from this package's frame-wide entry in `shell.overlay`, which outlives the Chat panel: it offers the one live notice to the `shell.quota-notice` chain and falls back to its own warning Toast, while an entry that claims the code replaces that fallback. Only Sessions this Client has bound and materialized publish; quota failures in Sessions it never opened do not. A newer notice replaces the current one unless a claiming entry retains it with `keepOpen()`: that call returns a release the caller owns and must run on unmount, any live hold keeps the claiming entry mounted and drops later notices, and releasing resumes later notices without replaying the dropped ones. The fallback Toast has no deferral of its own: while the Desktop account's opaque native Platform page covers the document, it still runs underneath and its display timer may elapse unseen, dismissing the notice itself, so only the persistent failure row remains. A release drops only its own hold, so one that runs after a dismissal or a newer hold leaves that newer hold intact. Dismissal and sign-out clear every hold, and dropped notices are not queued while their persistent failure rows still render. History replacement and pagination never publish a notice. Intermediate retries do not create a terminal row; output-token limits use the amber warning dot. A Turn that restart recovery closed as `interrupted` renders a localized stopped row stating that the DSH process exited mid-Turn, without a code chip, and its process summary reads Stopped. +Chat adapts Markdown targets at `MarkdownDelegateProvider.getTriggerProps`. The assistant-node Slot obtains `useContextMenu` directly and passes a file-path adapter to the optional mention service; intermediate flow and node owners carry no menu callbacks. Paths resolve against the originating Session’s current working directory when the gesture begins. Menus retain that captured path and line even if focus changes. Undeclared plugin links keep native behavior. + ----- @@ -134,7 +140,7 @@ Process rows share one text and icon color in every Work details mode: tertiary Chat waits for initial history before automatic content, scroll, or size updates initialize reading state. Running Sessions restore their initial visibility and position before fold animations become eligible. -Chat restores semantic anchors across history prepend and renderer remounts, with browser scroll anchoring disabled on its scrollport only while following the tail. Pinned scroll deliveries without reader movement, and reader input that reaches the floor within subpixel rounding, update follow ownership immediately, before subsequent layout changes can invalidate their floor. Other reader movement remains pending until the sampling interval or `scrollend`, even inside the follow threshold, so layout growth cannot erase small scroll gestures. Under completion-time folding, submitting transcript input or steering immediately restores tail following and clears an older pending reader sample. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn. Turn-rail previews paint above sticky Markdown code-block banners, while the rail frame remains inside the transcript band above the composer. +Chat restores semantic anchors across history prepend and renderer remounts, with browser scroll anchoring disabled on its scrollport only while following the tail. Pinned scroll deliveries without reader movement, and reader input that reaches the floor within subpixel rounding, update follow ownership immediately, before subsequent layout changes can invalidate their floor. Other reader movement remains pending until the sampling interval or `scrollend`, even inside the follow threshold, so layout growth cannot erase small scroll gestures. Under completion-time folding, submitting transcript input or steering immediately restores tail following and clears an older pending reader sample. Under next-message folding, transcript input that no fold batch carries lands on one native animation; steering lands at once under either timing, because the running Turn keeps streaming above its echo. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn. Turn-rail previews paint above sticky Markdown code-block banners, while the rail frame remains inside the transcript band above the composer. The turn rail and back-to-bottom button sit outside the clipped transcript. They use the shared conversation scrollport for sticky positioning, or the Chat frame for absolute positioning when Chat owns its scrollport. The rail hides when the transcript's available width, excluding its horizontal padding, is at most 900px; the browser viewport width is not the criterion. @@ -142,7 +148,9 @@ The transcript root uses `overflow-x: visible; overflow-y: clip`: vertical overf Outer transcript following and each open capped group's following are independent. Native animation progress retains follow intent; only that scrollport's own `scrollend` settles its animation. Browsers without `scrollend` may retain the native follow target until a later bottom-aligned update or reader gesture. A reader gesture interrupts the animation, and actual movement determines whether following remains enabled. Scroll chaining can move the outer transcript, which then applies its own distance threshold. The back-to-bottom button restores only outer following. -Next-message folding moves every batch of closing rows and the scrollport on one frame clock, with browser scroll anchoring disabled during the fold; there is no separate reserve-then-follow path. A row that starts closing or revealing while a batch runs keeps its size until that batch settles and then changes in the next batch; a batch continues each row from the size it already has. The batch lands at the tail when this client's own input caused it (including a subagent child's continuation) or when the reader was following; otherwise the reader's visible content stays still, whoever sent the message. Content above the reading line never slides back down: when the retained answer and the new content cannot fill the viewport, only that deficit remains as bottom space, and new content fills it before following advances again. Reader gestures cancel the automatic target and active native following; resize cannot revive it in the same fold, but new submitted input can. Acknowledged scrolling releases only space that can be removed without clamping the reader. Unloading Chat cancels waiting callbacks and row transitions. Reduced-motion users receive immediate visibility and positioning changes. +Next-message folding moves every batch of closing rows and the scrollport on one frame clock, with browser scroll anchoring disabled during the fold; there is no separate reserve-then-follow path. A row that starts closing or revealing while a batch runs keeps its size until that batch settles and then changes in the next batch; a batch continues each row from the size it already has. The batch lands at the tail when this client's own input caused it (including a subagent child's continuation) or when the reader was following; otherwise the reader's visible content stays still, whoever sent the message. When a batch takes over following because content changed, such as a Turn ending while a next input waits, content that grew outside the batch since the last paint moves the scroll position before the first frame, as following does for streaming growth, so the batch animates only its own rows; growth that arrives with the reader's own input lands on the batch's animation. Content above the reading line never slides back down: when the retained answer and the new content cannot fill the viewport, only that deficit remains as bottom space, and new content fills it before following advances again. Reader gestures cancel the automatic target and active native following; resize cannot revive it in the same fold, but new submitted input can. Acknowledged scrolling releases only space that can be removed without clamping the reader. Unloading Chat cancels waiting callbacks and row transitions. Reduced-motion users receive immediate visibility and positioning changes. + +Completion-time folding closes a Turn's work rows at once. When the reader follows the tail, the first row visible before the close keeps its screen position, or, when that row closed, the first surviving row that followed it on screen, else the nearest surviving row above it; bottom space fills the gap, at most half the scrollport, and later growth takes that space before following advances. Changing Work details clears reserved bottom space after active folds finish and reconciles the scroll range with the selected mode. Readers already following the tail stay at the new bottom; other readers are not forced to follow. @@ -180,6 +188,8 @@ The Chat view detects selection and context-menu gestures on business nodes mark `ctx.uiConversation.interactions` dispatches eligible gestures to plugin registrations and supplies their component to the Chat view. The action surface is absolutely positioned inside the existing Chat column, above the composer seat and its dock. Its wrapper preserves the component's outer stroke and shadow; components own internal scrolling. Scrolling the selection outside that visible region temporarily hides the surface; returning restores it. Chat owns viewport visibility, placement, outside pointer presses, Escape, new selections, source invalidation, and disposal; explicit dismissal preserves browser selection and layout changes do not reopen the surface. [Message quotes](../../session/message-quotes/README.md) owns quotation eligibility and insertion. +Markdown files, links, images, reference chips, and tool-file controls forward explicit right-click targets to [ui-context-menu](../ui-context-menu/README.md). File targets retain their working directory and line; ordinary link clicks retain the configured opening preference. + ## Model Experience diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md index 9113ed2f81..1cc14f917a 100644 --- a/packages/client/ui-chat/README.zh.md +++ b/packages/client/ui-chat/README.zh.md @@ -37,13 +37,15 @@ kind: "package-reference" 已发送的普通文件附件保留草稿中的[文件卡片圆角](../../../docs/ui-radius.zh.md#radius-scale)。 -`ChatView` 通过节点列表外围既有的 `MarkdownDelegateProvider` 提供文件及 HTTP(S) 导航，直接传入 `requestOpenFile`、`openExternalLink` 和 `fileImages`。文件打开动作保留 Chat 的失败反馈与重试处理。Assistant Markdown 文件链接在消息落定后可于右侧栏打开，包括未修改文件的引用。相对路径基于当前查看的 Session 工作区解析；绝对路径仍使用同一 Session 的文件系统访问。`#L24` 和 `#L24-L30` 定位到指定起始行，并复用现有文件标签。文件缺失时显示预览错误状态。 +`ChatView` 通过节点列表外围既有的 `MarkdownDelegateProvider` 提供文件及 HTTP(S) 导航，直接传入 `requestOpenFile`、`openExternalLink` 和 `fileImages`。文件打开动作保留 Chat 的失败反馈与重试处理。Assistant Markdown 文件链接在消息落定后可于右侧栏打开，包括未修改文件的引用。相对路径基于当前查看的 Session 工作区解析；绝对路径仍使用同一 Session 的文件系统访问。[支持的 Markdown 行号引用](../ui-primitives/README.zh.md#rendering-agent-output)定位到指定起始行，并复用现有文件标签。文件缺失时显示预览错误状态。 原生消息图片使用独立的用户与输出位置。`conversation.chat.user.content` Factory 声明 `conversation.chat.user.images`，由 `UserContent` 渲染；Assistant 节点注册声明 `conversation.chat.message.images`，由 `AssistantMarkdown` 渲染。两者通过显式 props 接收图片来源、授权 `loadImage` 和布局参数。官方 `MessageImages` 条目调用共享的 root 作用域 `conversation.images.content` Factory。每个位置均可独立替换，无需复制画廊实现。 Session 作用域的 `conversation.chat.user.content` Factory 只渲染用户内容区域：文本、额外内容块、按输入顺序排列的图片／文件附件及引用摘要。[`UserContentInput`](src/client/contract/slots.ts) 携带预处理的 `content`、变换 `facts`、显示 props 和显式 `loadImage`；引用动作由节点自己的 Injection 提供。正文调用共享 `conversation.user.text` Factory，图片调用自身拥有的图片 Slot。直接调用需要 Session 绑定，行包装层由调用方提供。 -`UserStyleBubble` 和[各来源包装层]() 保留用户行、key、pending／echo 标记、时间、复制控件及其他消息操作。内容 Factory 不读取来源专属模型或私有 Context，也不是全局用户内容替换入口。 +`UserStyleBubble` 和[各来源包装层]() 保留用户行、key、pending／echo 标记、时间、复制控件及其他消息操作。内容 Factory 不读取来源专属模型或私有 Context，也不是全局用户内容替换入口。 + +官方 user 与 steering 共用的渲染器在 `user` 注册项上声明 session-scoped `conversation.chat.user.before` chain slot，并在气泡上方直接通过 `renderSlotChain` 渲染；`steering` 注册项复用该渲染器但不拥有该槽位。owner props 携带 Session 记录的持久化消息 `source` 与行 `kind`；各条目的 `select` 匹配自己负责的来源，首个非 null 结果作为 `matched` 交给获选组件。无匹配时不显示内容。条目自行拥有标记和文案；Chat 不解析消息来源。 独立的 Markdown 图片以内嵌预览显示，点击打开共享图片浮层；本地路径在消息落定后基于当前查看的工作区解析。图片文件链接保持点击打开侧栏，鼠标停留或键盘聚焦时显示缩略图，Esc 关闭缩略图。图片加载失败时保留本地化状态与图片说明；不执行重复图片过滤。 @@ -56,11 +58,15 @@ Chat 在所有工作步骤展示模式下都不显示系统提示词行、普通 Assistant 尝试结束且没有可见消息时，Chat 隐藏已发布的 Node，不移除其 key。同一 Step 的重试再次产生可见内容时，复用该 key。已加载窗口缺少 Step 起点时也遵循此规则。 +只有包含非空白字符的文本和推理块才计入 Assistant 的可见内容。流式追加复用每个块的可见状态；块替换和最终消息重新计算可见性，同时保留原始文本。 + ## 指令与失败行 通用指令行在所有生命周期状态中都保留普通指令图标；失败仍通过行状态与摘要表达。每个终止轮次都渲染自己的红点行；欠费失败的行使用中立的 `message.failure.quota` 文案，而不是提供方消息。新追加的 `QUOTA` 或 `ACCOUNT_QUOTA` 产生的瞬时提示来自本包注册在 `shell.overlay` 的全局条目，它不随 Chat 面板消失：该条目把唯一一条实时提示交给 `shell.quota-notice` 链，并在无人接管时回退到自己的警告 Toast，接管该错误码的条目会替换该回退。只有本 Client 已绑定并已物化的 Session 会发布提示；它从未打开的 Session 中的欠费不会发布。更新的提示会替换当前提示，除非认领条目用 `keepOpen()` 保持住当前提示：该调用返回一个由调用方持有、必须在卸载时调用的释放函数，只要存在保持，认领条目就继续挂载，后续提示被丢弃，释放后恢复后续提示但不重放已丢弃的提示。回退 Toast 自身没有延后策略：当 Desktop 账号的不透明原生 Platform 页盖住本页时，它仍会在下方运行，其显示计时器可能在不可见时走完并自行撤下提示，因此只留下持久化失败行。释放只移除自己的保持，因此它在关闭或更新的保持之后执行时不会影响更新的保持。关闭与退出登录会清空所有保持；被丢弃的提示不排队，其对应的持久化失败行仍会渲染。历史替换和分页不会发布提示。中间重试不会创建终止行；输出 token 上限使用琥珀色警告点。重启恢复以 `interrupted` 结束的轮次会渲染本地化的停止行，说明 DSH 进程在轮次中途退出，不显示代码标签，其过程摘要显示“已停止”。 +Chat 在 `MarkdownDelegateProvider.getTriggerProps` 接入处适配 Markdown 目标。助手节点 Slot 直接获取 `useContextMenu`，向可选的文件引用服务传入路径适配函数；消息流和节点中间层不再携带菜单回调。手势发生时按原始 Session 的当前工作目录解析路径，菜单保留捕获的路径和行号，不受焦点变化影响。未声明的插件链接保留原生行为。 + ----- @@ -134,7 +140,7 @@ Chat 节点 slot 为推理与工具注入绑定重置来源的 `useDisclosure` Chat 等待初始历史就绪后，才允许自动内容、滚动或尺寸更新初始化阅读状态。进行中的 Session 先恢复初始显隐和位置，再允许折叠动画。 -Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点，并且只在跟随底部时禁用自己滚动区域的浏览器自动锚定。没有读者移动的贴底滚动事件，以及到达底部（容许小于 1px 的取整误差）的读者输入，会立即更新跟随归属，避免后续布局变化使其底部位置失效。其他读者移动即使位于跟随阈值内，也保持待处理直到采样周期或 `scrollend`，防止布局增长抵消小幅滚动操作。采用完成时收起时，提交正文输入或 steering 会立即恢复跟随底部，并清除先前待处理的读者滚动采样。读者跟随底部时，`ResizeObserver` 追随新的底部，并且无需读取行几何就选中最后一个已加载轮次；读者离开底部后，高度变化会保持顶部位置，再由阅读线几何选择活跃轮次。轮次导航预览位于 Markdown 代码块粘性头栏上方，而导航外框始终处于 composer 上方的 transcript 区域内。 +Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点，并且只在跟随底部时禁用自己滚动区域的浏览器自动锚定。没有读者移动的贴底滚动事件，以及到达底部（容许小于 1px 的取整误差）的读者输入，会立即更新跟随归属，避免后续布局变化使其底部位置失效。其他读者移动即使位于跟随阈值内，也保持待处理直到采样周期或 `scrollend`，防止布局增长抵消小幅滚动操作。采用完成时收起时，提交正文输入或 steering 会立即恢复跟随底部，并清除先前待处理的读者滚动采样。采用下次消息时收起时，没有折叠批次承载的正文输入用一次原生动画落到底部；steering 在两种时机下都立即落到底部，因为运行中的 Turn 仍在其回显上方持续输出。读者跟随底部时，`ResizeObserver` 追随新的底部，并且无需读取行几何就选中最后一个已加载轮次；读者离开底部后，高度变化会保持顶部位置，再由阅读线几何选择活跃轮次。轮次导航预览位于 Markdown 代码块粘性头栏上方，而导航外框始终处于 composer 上方的 transcript 区域内。 轮次轨道与回到底部按钮位于正文裁剪层外。它们相对共享会话滚动容器做 sticky 定位；Chat 自己持有滚动容器时，则相对 Chat 外框做 absolute 定位。正文扣除水平内边距后的可用宽度不超过 900px 时，隐藏轮次轨道；判断依据不是浏览器视口宽度。 @@ -142,7 +148,9 @@ Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点，并且 外层文本记录与每个已展开限高组的跟随状态彼此独立。原生动画的中间滚动保留跟随意图；只有该滚动容器自身的 `scrollend` 才结束其动画。不支持 `scrollend` 的浏览器可能保留原生跟随目标，直到后续贴底更新或读者手势将其结束。读者手势中断动画，是否继续跟随由实际位移决定。滚动传递可以带动外层，外层再按自身离底距离判断。回到底部按钮只恢复外层跟随。 -下次消息触发的折叠中，每一批收起行与滚动容器在同一个帧时钟上推进，折叠期间禁用浏览器滚动锚定；不存在「先预留、再跟随」的另一条路径。批次运行期间开始收起或展开的行先保持当前尺寸，等当前批次落定后在下一批中变化；批次从每一行已有的尺寸继续。由本客户端自己的输入（包括子代理会话的 continuation）触发、或读者原本在跟尾时，这一批落到底部；其余情况下，无论消息由谁发出，读者正在看的内容保持不动。阅读线以上的内容不会回滑：保留的正文和新内容填不满视口时，只把差额保留为底部空间，后续新增内容先填满它，再继续跟尾。读者手势取消自动目标及进行中的原生跟随；同一次折叠中的尺寸变化不能恢复它，但新提交的输入可以。已确认的滚动只释放不会造成位置钳制的多余空间。卸载 Chat 时取消等待回调和行过渡。启用减少动态效果偏好时，可见性和定位立即变化。 +下次消息触发的折叠中，每一批收起行与滚动容器在同一个帧时钟上推进，折叠期间禁用浏览器滚动锚定；不存在「先预留、再跟随」的另一条路径。批次运行期间开始收起或展开的行先保持当前尺寸，等当前批次落定后在下一批中变化；批次从每一行已有的尺寸继续。由本客户端自己的输入（包括子代理会话的 continuation）触发、或读者原本在跟尾时，这一批落到底部；其余情况下，无论消息由谁发出，读者正在看的内容保持不动。批次因内容变化接管跟随时（例如下一条输入在等待时一轮结束），上次绘制以来批次之外的内容增长在第一帧之前由滚动位置吸收，与跟随吸收流式增长的方式相同，批次只为自己的行做动画；随读者自己的输入到达的增长则随批次动画落定。阅读线以上的内容不会回滑：保留的正文和新内容填不满视口时，只把差额保留为底部空间，后续新增内容先填满它，再继续跟尾。读者手势取消自动目标及进行中的原生跟随；同一次折叠中的尺寸变化不能恢复它，但新提交的输入可以。已确认的滚动只释放不会造成位置钳制的多余空间。卸载 Chat 时取消等待回调和行过渡。启用减少动态效果偏好时，可见性和定位立即变化。 + +完成时收起会一次性收起一轮的工作行。读者跟随底部时，收起前第一个可见行保持屏幕位置；若该行本身被收起，则由收起前在屏幕上位于其后的第一个保留行保持不动，没有这样的行时才由其上方最近的保留行保持不动。底部空间填补空缺，最多半个滚动区域高度，后续增长先占用这部分空间，跟随才继续前进。 切换工作步骤展示档位时，当前折叠结束后清空底部预留空间，并按所选档位调整滚动范围。原本跟随底部的读者保持在新的底部；其他读者不会被强制拉回底部。 @@ -180,6 +188,8 @@ Chat view 在标记了 `data-text-interaction-source` 的业务节点上检测 `ctx.uiConversation.interactions` 将有效手势分发给插件注册项，并把对应组件交给 Chat view。操作展示位置在已有 Chat 列内绝对定位，限制在 composer seat 及其 dock 上方。外层容器保留组件的外描边与阴影，内部滚动由组件负责。选区滚出该可见范围时暂时隐藏操作，滚回后恢复。Chat 负责视口可见性、定位、外部指针按下、Escape、新选区、来源失效与卸载清理；主动关闭保留浏览器选区，布局变化不会重新打开操作。[Message quotes](../../session/message-quotes/README.zh.md) 负责引用的接管条件和插入。 +Markdown 文件、链接、图片、引用 chip 和工具文件控件将明确的右键目标转发给 [ui-context-menu](../ui-context-menu/README.zh.md)。文件目标保留工作目录和行号；普通链接点击仍遵循配置的打开偏好。 + ## 模型体验 diff --git a/packages/client/ui-chat/package.json b/packages/client/ui-chat/package.json index ed088904bf..c8a468b48c 100644 --- a/packages/client/ui-chat/package.json +++ b/packages/client/ui-chat/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-client-ui-chat", "description": "Chat Conversation target, node definitions, renderers, and details surface", - "version": "0.2.1-rc.3", + "version": "0.2.2-alpha.2", "publishConfig": { "access": "public" }, @@ -42,7 +42,8 @@ "@deepseek-ai/dsh-client-ui-settings", "@deepseek-ai/dsh-client-ui-sidebar-right", "@deepseek-ai/dsh-client-ui-workspace", - "@deepseek-ai/dsh-client-ui-file-drag" + "@deepseek-ai/dsh-client-ui-file-drag", + "@deepseek-ai/dsh-client-ui-context-menu" ], "platform": "web" } @@ -97,7 +98,8 @@ "react-dom": "^18.2.0", "@deepseek-ai/dsh-settings": "workspace:*", "@deepseek-ai/dsh-client-product-analytics": "workspace:*", - "@deepseek-ai/dsh-client-ui-file-drag": "workspace:*" + "@deepseek-ai/dsh-client-ui-file-drag": "workspace:*", + "@deepseek-ai/dsh-client-ui-context-menu": "workspace:*" }, "dependencies": { "@deepseek-ai/schemastery": "workspace:~" diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts index fbabf95903..d3a6df8b96 100644 --- a/packages/client/ui-chat/src/client/apply.ts +++ b/packages/client/ui-chat/src/client/apply.ts @@ -1,3 +1,4 @@ +import type {} from '@deepseek-ai/dsh-client-ui-context-menu/client' /** Register the Chat Conversation target, renderers, stats, and details surface. */ import type {} from '@deepseek-ai/dsh-client-ui-file-drag/client' import type {} from '@deepseek-ai/dsh-client-product-analytics/client' @@ -25,11 +26,12 @@ import type {} from '@deepseek-ai/dsh-client-ui-workspace/client' import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client' import type { ChatFlowDataInjected, ChatFlowInjected, ChatNodeInjected, ChatScrollPosition, ChatViewInjected, - QuotaNoticeInjected, QuotaNoticeState, TurnTailOwnerProps, + QuotaNoticeInjected, QuotaNoticeState, } from './contract/slots.ts' import type { ChatSnapshot } from './contract/snapshot.ts' import { EMPTY_CHAT_SNAPSHOT } from './contract/snapshot.ts' import { ApprovalCommand } from './chat/ApprovalCommand.tsx' +import { sessionFilePath } from './file-path.ts' import { ChatView } from './chat/ChatView.tsx' import { ChatFlow } from './chat/ChatFlow.tsx' import { registerChatNodeRenderers } from './chat/register-node-renderers.ts' @@ -253,7 +255,6 @@ export function apply(ctx: Context): void { fileDrag: ctx.fileDrag.actions, hooks: { presentation, interactionIds: ctx.uiConversation.interactions }, dispatchInteraction: gesture => ctx.uiConversation.interactions.dispatch(sessionId, gesture), - fileMentions: (owner: TurnTailOwnerProps) => ctx.get('chatFileMentions')?.forClosing(owner, sessionId), // Files open in the right Sidebar, not in a desktop application: the // content stays in the product, beside the conversation that produced // it. A relative path resolves from the Session's working directory @@ -276,6 +277,7 @@ export function apply(ctx: Context): void { else ctx.sidebarRight.openResource(url, { params: { line: options.line } }) await Promise.resolve() }, + resolveFilePath: sessionFilePath(ctx, sessionId), openExternalLink: (url) => { if (linkOpening.getSnapshot() === 'sidebar' && ctx.get('sidebarRightTabs')?.get('browser') !== undefined) { ctx.sidebarRight.openTab('browser', { params: { url } }) diff --git a/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx b/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx index 455f90f9a2..ad5963c093 100644 --- a/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx +++ b/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx @@ -1,16 +1,28 @@ import { memo, useCallback, useMemo } from 'react' import type { InjectFace, PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots' -import type { ChatNodeViewProps, PresentationInjected, TurnTailOwnerProps } from '../contract/slots.ts' +import type { ChatFileMentions, ChatNodeViewProps, PresentationInjected, TurnTailOwnerProps } from '../contract/slots.ts' import { AssistantMarkdown } from './AssistantMarkdown.tsx' -type AssistantNodeViewProps = ChatNodeViewProps<'assistant-step'> & InjectFace +/** Business readers owned by the assistant renderer's existing Slot registration. */ +export interface AssistantNodeInjected extends PresentationInjected { + /** Resolve against the live Session directory. @param path - Recorded path. @returns Host path. */ + resolveFilePath: (path: string) => string + /** Resolve closing-Turn mentions with the supplied ordinary file gesture callback. */ + fileMentions: (owner: TurnTailOwnerProps, getFileTriggerProps: NonNullable[2]>) => ReturnType +} + +type AssistantNodeViewProps = ChatNodeViewProps<'assistant-step'> & InjectFace & PropsRenderSlots<'conversation.chat.reasoning.body' | 'conversation.chat.message.images'> /** Streaming, settled, and interrupted Assistant states share one keyed renderer instance. */ export const AssistantNodeView = memo(function AssistantNodeView({ node, groupPart, useDisclosure, useGroupAction, useTurnData, turnProcess, openFile, loadImage, fileMentions, - usePresentation, renderSlot, t, + usePresentation, renderSlot, t, sessionId, useContextMenu, resolveFilePath, }: AssistantNodeViewProps) { + const { getTriggerProps } = useContextMenu() + const getFileTriggerProps = useCallback((path: string) => getTriggerProps(() => ({ + kind: 'file', value: { sessionId, path: resolveFilePath(path) }, + })), [getTriggerProps, sessionId, resolveFilePath]) const data = node.data const turn = node.location.kind === 'turn' || node.location.kind === 'step' ? node.location.turn @@ -22,8 +34,8 @@ export const AssistantNodeView = memo(function AssistantNodeView({ return { turn, seq: data.finalNode.seq, openFile } }, [data.finalNode, openFile, tail, turn]) const mentions = useMemo( - () => owner === undefined ? undefined : fileMentions(owner), - [fileMentions, owner], + () => owner === undefined ? undefined : fileMentions(owner, getFileTriggerProps), + [fileMentions, owner, getFileTriggerProps], ) const keepReplies = usePresentation(policy => policy.foldedReplies === 'all') // A kept reply row stays visible while the folded Turn hides its inline reasoning. diff --git a/packages/client/ui-chat/src/client/chat/ChatFlow.tsx b/packages/client/ui-chat/src/client/chat/ChatFlow.tsx index 561632a671..d83a3043cc 100644 --- a/packages/client/ui-chat/src/client/chat/ChatFlow.tsx +++ b/packages/client/ui-chat/src/client/chat/ChatFlow.tsx @@ -27,7 +27,7 @@ export const ChatFlow = memo(function ChatFlow({ entries, pendingInputs, lastInputTurn, deferCollapse, useSession, useChat, useChatNode, useChatNodeBottom, useChatNodeProcess, useChatGroup, usePresentation, useConnectionState, useStore, actions, renderSlot, renderFactorySlot, t, useGroupAction, useGroupHeaderAction, - cwd, openFile, inspectCall, forkAt, loadImage, fileMentions, + cwd, openFile, inspectCall, forkAt, loadImage, }: ChatFlowSlotProps) { const nodeStore = useChat(snapshot => snapshot.nodes) const running = useSession(snapshot => snapshot.running) @@ -39,10 +39,15 @@ export const ChatFlow = memo(function ChatFlow({ ? location.turn.status === 'open' ? location.turn.start?.time : undefined : undefined }) + const latestTurnOpen = useChatNode(latestTurnAnchor ?? '', (node) => { + const location = node?.location + return (location?.kind === 'turn' || location?.kind === 'step') && location.turn.status === 'open' + }) + const holding = !running && latestTurnOpen const seatProps = { nodeStore, useChatNode, useChatNodeBottom, useChatNodeProcess, usePresentation, useStore, actions, renderSlot, t, useGroupAction, deferCollapse, - cwd, openFile, inspectCall, forkAt, loadImage, fileMentions, + cwd, openFile, inspectCall, forkAt, loadImage, } const rows = entries.map((entry) => { switch (entry.kind) { @@ -83,10 +88,13 @@ export const ChatFlow = memo(function ChatFlow({ && node.location.turn.status === 'open' && node.location.turn.turn !== lastInputTurn) { rows.splice(rows.length - 1, 0, ...leadingRows.splice(0)) } - // Rows enter before the keyed status and echoes after it, so React never moves its DOM node. + // Rows enter before the keyed status and echoes after it, so React never moves its DOM node. The + // running bit and the Turn's end arrive separately: after the bit clears, an open latest Turn keeps + // the status slot (hidden) until its actions row takes the slot in the same commit. return [ ...rows, ...leadingRows, ...openingRows, - ...running ? [] : [], + ...running || holding ? [] : [], ...pendingRows, ] }) diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx index 6db2f75821..4efdb94142 100644 --- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx +++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx @@ -50,7 +50,7 @@ function turnOf(node: ChatNode | undefined): number | undefined { export const ChatNodeSeat = memo(function ChatNodeSeat({ nodeKey, groupPart, useChatNode, useChatNodeProcess, usePresentation, cwd, openFile, inspectCall, forkAt, - loadImage, fileMentions, useStore, actions, renderSlot, t, useChatNodeBottom, deferCollapse, useGroupAction, + loadImage, useStore, actions, renderSlot, t, useChatNodeBottom, deferCollapse, useGroupAction, }: ChatNodeSeatProps) { const bottom = useChatNodeBottom(nodeKey) const node = useChatNode(nodeKey) @@ -138,11 +138,10 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({ inspectCall, forkAt, loadImage, - fileMentions, turnProcess, }, [ node, groupPart, cwd, openFile, inspectCall, forkAt, - loadImage, fileMentions, turnProcess, + loadImage, turnProcess, ]) if (routedNode === undefined || owner === null) return null // Runtime dispatch owns the correlation: every Node's discriminant is the diff --git a/packages/client/ui-chat/src/client/chat/ChatView.module.css b/packages/client/ui-chat/src/client/chat/ChatView.module.css index f05bad098f..5f640dbbad 100644 --- a/packages/client/ui-chat/src/client/chat/ChatView.module.css +++ b/packages/client/ui-chat/src/client/chat/ChatView.module.css @@ -115,6 +115,13 @@ transition: none; } +/* A Turn's duration control renders empty until the Turn closes; its gap appears with it in the same + frame, so the layout below changes once instead of sliding after the control's own height. */ +.column[data-chat-motion] > [data-chat-flow-kind="turn-process"], +.column[data-chat-motion] > :global([data-slot="conversation.chat.flow"]) > [data-chat-flow-kind="turn-process"] { + transition: none; +} + @media (prefers-reduced-motion: reduce) { .column[data-chat-motion] > :not([data-chat-motion]), .column[data-chat-motion] > :global([data-slot="conversation.chat.flow"]) > :not([data-chat-motion]) { @@ -163,6 +170,15 @@ :where(.column > :global([data-slot="conversation.chat.flow"]) > .flowItem[data-chat-flow-kind="steering"]) + .running { animation: running-enters-slot 140ms cubic-bezier(0.2, 0.8, 0.2, 1); } + + /* An input fold runs the entrance at zero duration. The switch only changes + the duration of an entrance its structural change already created, as if + the entrance had it from its start: lifting the switch never replays an + entrance older than its duration, and setting it completes a running one. + The structural rule is wrapped in :where() so this rule outranks it. */ + .column[data-input-fold] .running { + animation-duration: 0s; + } } @keyframes running-enters-slot { @@ -175,66 +191,6 @@ } } -/* While the running Step has no output, the status sits directly below the - input. When the first output row appears, the status enters its slot below - that row from where it stood: it travels the row's gap plus one 24px row, - which follows the content font size. The gap is 4px for a process row or - group header (the default declared on `.running`), 12px for a response, and - 16px after the running Turn's process control, which renders empty until the - Turn closes, so it precedes a new Turn's first output. The default sits on - the single-class `.running` selector so both variants outrank it. Later - output keeps the same animation and does not restart it. */ -:is(.column, :global([data-slot="conversation.chat.flow"])) > :nth-last-child(2 of :not([hidden]):not([data-pending-steering]):not(.flowItem:is(:empty, :has(> [data-slot="conversation.chat.node"]:empty))))[data-chat-group-part="response"] ~ .running { - --dsh-running-follow: calc(12px + 24px + var(--dsh-content-font-delta, 0px)); -} - -:is(.column, :global([data-slot="conversation.chat.flow"])) > [data-chat-flow-kind="turn-process"] + :nth-last-child(2 of :not([hidden]):not([data-pending-steering]):not(.flowItem:is(:empty, :has(> [data-slot="conversation.chat.node"]:empty)))) ~ .running { - --dsh-running-follow: calc(16px + 24px + var(--dsh-content-font-delta, 0px)); -} - -@media (prefers-reduced-motion: no-preference) { - :where(.column > :global([data-slot="conversation.chat.flow"]) > :nth-last-child(2 of :not([hidden]):not([data-pending-steering]):not(.flowItem:is(:empty, :has(> [data-slot="conversation.chat.node"]:empty)))):is( - .flowItem:not([data-chat-flow-kind="user"]):not([data-chat-flow-kind="steering"]):not([data-chat-flow-kind="turn-trigger"]), - [data-chat-group-key] - )) ~ .running { - animation: running-follows-output 110ms cubic-bezier(0.4, 0, 0.2, 1); - } - - /* Switches only change the duration of a move its structural change already - created. A duration change applies as if the move had it from its start, so - turning a switch off never replays a move whose structural change is older - than the move's duration, and plays the remainder of one that is younger; - turning a switch on completes a running move at once. The structural rules - above are wrapped in :where() so these rules outrank them. An input fold - runs both moves at zero duration. */ - - .column[data-input-fold] .running { - animation-duration: 0s; - } - - /* While the tail is pinned, following scrolls absorb output growth and the - status keeps its on-screen position, so the first-output slide runs at zero - duration. Admitted steering still passes its pending echo below the status, - so the steering entrance keeps its duration. */ - - .column[data-chat-tail-pinned] > :global([data-slot="conversation.chat.flow"]) > :nth-last-child(2 of :not([hidden]):not([data-pending-steering]):not(.flowItem:is(:empty, :has(> [data-slot="conversation.chat.node"]:empty)))):is( - .flowItem:not([data-chat-flow-kind="user"]):not([data-chat-flow-kind="steering"]):not([data-chat-flow-kind="turn-trigger"]), - [data-chat-group-key] - ) ~ .running { - animation-duration: 0s; - } -} - -@keyframes running-follows-output { - from { - opacity: 0; - translate: 0 calc(-1 * var(--dsh-running-follow)); - } - 40% { - opacity: 1; - } -} - /* Empty Seats, including retained empty slot anchors, preserve Turn lookup without contributing height or the sibling gap. */ .flowItem:is(:empty, :has(> [data-slot="conversation.chat.node"]:empty)) { @@ -260,13 +216,19 @@ flex-direction: column; align-items: flex-start; --dsh-chat-flow-gap: 12px; - --dsh-running-follow: calc(4px + 24px + var(--dsh-content-font-delta, 0px)); --dsw-alias-label-shimmer: var(--dsw-alias-label-deep-diving-shimmer); color: var(--dsw-alias-label-deep-diving); font-size: calc(var(--dsh-content-font-size, 14px) - 2px); line-height: calc(22px + var(--dsh-content-font-delta, 0px)); } +/* After the Session stops running and before the Turn's actions row arrives, the status keeps its slot + unseen so the tail does not shrink for that interval. */ +.running[data-holding] { + visibility: hidden; + opacity: 0; +} + /* The last visible row before the status must contain output, not an input. Hidden and empty seats do not separate a user message from the status, and the steering/Inbox echoes after the status are outside the count. */ diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx index f1a0556b9f..e265ab635f 100644 --- a/packages/client/ui-chat/src/client/chat/ChatView.tsx +++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx @@ -8,7 +8,7 @@ import type { import type { InboxState } from '@deepseek-ai/dsh-agent/types' import type { PendingSubmission } from '@deepseek-ai/dsh-api-session-controller/client' import { - Button, IconChevronDownOutlineRegular, MarkdownDelegateProvider, Modal, + Button, IconChevronDownOutlineRegular, MarkdownDelegateProvider, Modal, type MarkdownMenuTarget, } from '@deepseek-ai/dsh-client-ui-primitives' import { isAtOrOutside } from '../contract/group-tree.ts' import type { ChatFlowHookContext, ChatViewSlotProps, OpenFileOptions } from '../contract/slots.ts' @@ -60,9 +60,22 @@ const MOTION_TAIL_MS = 800 */ export function ChatView({ useSession, useChat, useConversation, useSessions, renderSlot, - sessionId, openFile, openExternalLink, loadOlder, loadThrough, loadImage, inspectCall, chatScroll, forkAt, fileMentions, + sessionId, openFile, openExternalLink, resolveFilePath, useContextMenu, + loadOlder, loadThrough, loadImage, inspectCall, chatScroll, forkAt, usePresentation, useProjection, useInteractionIds, dispatchInteraction, t, fileDrag, }: ChatViewSlotProps) { + const { getTriggerProps } = useContextMenu() + const getMarkdownTriggerProps = useCallback((target: MarkdownMenuTarget) => getTriggerProps(() => { + switch (target.kind) { + case 'file': return { kind: 'file', value: { sessionId, path: resolveFilePath(target.path), + ...(target.line === undefined ? {} : { line: target.line }) } } + case 'url': return { kind: 'url', value: { sessionId, url: target.url } } + case 'image': return { kind: 'image', value: { sessionId, url: target.url, + ...(target.name === undefined ? {} : { name: target.name }), + ...(target.mediaType === undefined ? {} : { mediaType: target.mediaType }), + ...(target.path === undefined ? {} : { path: resolveFilePath(target.path) }) } } + } + }), [getTriggerProps, resolveFilePath, sessionId]) const order = useChat(s => s.order) const groupedEntries = useConversation(snapshot => snapshot.views.grouped('chat')?.entries) const entries = useMemo(() => groupedEntries @@ -192,6 +205,7 @@ export function ChatView({ lastIsUser: lastKey !== null && nodeStore.get(lastKey)?.kind === 'user', steeringId, submissionId: visibleSubmissions.at(-1)?.requestId ?? null, + submissionSteers: visibleSubmissions.at(-1)?.placement === 'steering', loadedTurns: turnNavigationItems, transcriptView, }) @@ -229,10 +243,15 @@ export function ChatView({ )} - + {renderSlot('conversation.chat.flow', { entries, pendingInputs, lastInputTurn, deferCollapse, - cwd, openFile: requestOpenFile, inspectCall, forkAt, loadImage, fileMentions, + cwd, openFile: requestOpenFile, inspectCall, forkAt, loadImage, }, { hookContext: flowContext })}
['renderSlotChain'] = () => null + /** Right-aligned bubble shared by user and steering rows. */ function UserStyleBubble({ - content, loadImage, renderFactorySlot, actions, pending = false, echo = false, batchStart = false, + node, renderSlotChain, content, loadImage, renderFactorySlot, actions, + pending = false, echo = false, batchStart = false, referenceLabels, skillNames, previewAttachments, facts: inputFacts = EMPTY_TEXT_FACTS, interactive = false, }: { content: readonly unknown[] renderFactorySlot: PropsRenderFactories['renderFactorySlot'] /** Optional IconActions (or similar) below the bubble; receives the joined text. */ actions?: (text: string) => ReactNode + /** Row whose durable source the message-source seat elects above this bubble. */ + node: DecoratedRow + /** Seat renderer; rows that do not own the seat pass {@link NO_MESSAGE_SOURCE}. */ + renderSlotChain: PropsRenderSlots<'conversation.chat.user.before'>['renderSlotChain'] /** Whether this is the Host-authoritative pre-admission steering projection. */ pending?: boolean /** Whether this is a local submission echo (invisible marker; the echo renders exactly like its durable replacement). */ @@ -203,6 +223,7 @@ function UserStyleBubble({ data-submission-echo={echo || undefined} data-chat-steering-batch={batchStart ? 'start' : undefined} > + {renderSlotChain('conversation.chat.user.before', { source: node.data.source, kind: node.kind }, { fallback: null })} {renderFactorySlot('conversation.chat.user.content', { content: prepared, loadImage, @@ -227,6 +248,8 @@ export function PendingSteeringBubble({ content, loadImage, renderFactorySlot, t } & Pick): ReactNode { return ( ) { + node, renderFactorySlot, loadImage, renderSlotChain, t, +}: ChatNodeViewProps<'user' | 'steering'> & { + /** Bound by the `user` keyed registration, the only entry that declares the seat. */ + renderSlotChain: PropsRenderSlots<'conversation.chat.user.before'>['renderSlotChain'] +}) { const data = node.data return (