Merge remote-tracking branch 'origin/master' into feat/mcp-manager-core
# Conflicts: # docs/event-producer-consumer.i18n.yaml # docs/event-producer-consumer.md # docs/event-producer-consumer.zh.md
This commit is contained in:
commit
eaefd91ac7
732 files changed
+12195
-2298
No files matched your search
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
|
||||
2026-07-25-web-input-machine-and-slash-pipeline.md: 200761cc9e648eea80bdae9d7b363246c816e5d1
|
||||
2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 673d0ee4bd0916b20ee74226f50240e3904fe06c
|
||||
2026-07-25-web-input-machine-and-slash-pipeline.md: 1b9e9d95b5a30efbf297be5fc5f788f9a1ac77c4
|
||||
2026-07-25-web-input-machine-and-slash-pipeline.zh.md: c9bee217da1dbffaeff69dfe5a2dcf8f0e8e3cb0
|
||||
+2
-2
@@ -67,8 +67,8 @@ skill/@subagent references skip the placeholder + occurrence identity chain —
|
||||
|
||||
- PickOutcome gains a `{text}` arm; the new scoped bail event `slash/input-insert-text` `{text, span}` (the same contract as the other three: draftRev CAS, returning true ⟺ an actual rewrite); facade.insertText goes through setDraft concatenation — zero machine changes.
|
||||
- Sources get an optional `lexicon?(session)` hook: a synchronous hot-snapshot name roster, with `undefined` = data not warm — zero decoration, never triggering a fetch (the render path stays synchronous and side-effect-free); the paired optional `subscribeLexicon?(session, listener)` hook is the invalidation channel for rolls that change after warm (catalog settles, children spawn/exit). The controller aggregates the rolls into its `lexicon` snapshot store (re-polling on each source notification); sources registered after scope birth are warmed and folded in via the service's live-controller broadcast.
|
||||
- `decorations.scanTextRefs`: a word-boundary scan of the draft (`/name`, `@name` at line start / after whitespace; `x/name` never hits) against the roster; a hit becomes a `TextRefNode` entity in the Lexical tree (the claim decoration has precedence on the leading-token seat — [the Lexical composer note](2026-08-20-web-composer-lexical-editor.md)); an edit breaking the match shape reverts the entity to plain text.
|
||||
- Sending is the literal text (no more `<skill>` serialization); on the bubble side MessageItem decorates both shapes (the legacy `<skill>` tag + plain-text tokens).
|
||||
- `decorations.scanTextRefs`: a word-boundary scan of the draft (`/name`, `@name` at line start / after whitespace; `x/name` never hits; a `/name` token also ends at whitespace or the draft end — the whitespace-bounded shape of the host skill gesture, so `/nfs-hg/xxx` is a path and `/plan。` is prose; the sent-text projection `projectUserText` in ui-primitives applies the same shape) against the roster; a hit becomes a `TextRefNode` entity in the Lexical tree (the claim decoration has precedence on the leading-token seat — [the Lexical composer note](2026-08-20-web-composer-lexical-editor.md)); an edit breaking the match shape reverts the entity to plain text.
|
||||
- Sending is the literal text (no more `<skill>` serialization); on the bubble side `projectUserText` decorates a plain-text `/name` token only when the same step logged a `skill-invocation` injection for that name — ui-chat's `SkillNameProjector` attaches the step's injected names to the direct message Node, the way the recall projector attaches session labels — so `/123` or a stray `/word` stays plain; a command-input bubble (ui-goal) names its executed command the same way and renders the token as a `command` chip; `@name` tokens still decorate by shape.
|
||||
- Decoration reactivity: the shell subscribes to the controller's lexicon store and re-scans the document on each roll change, so a roll that settles after the scope-birth prewarm lights existing draft tokens up without any menu interaction or unrelated re-render.
|
||||
|
||||
### Per-session provide contributions and the private keyboard surface
|
||||
|
||||
+2
-2
@@ -67,8 +67,8 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引
|
||||
|
||||
- PickOutcome 增 `{text}` arm;新 scoped bail 事件 `slash/input-insert-text` `{text, span}`(与另三个同约定:draftRev CAS、返回 true ⟺ 实际改写);facade.insertText 走 setDraft 拼接,机器零改动。
|
||||
- source 可选 `lexicon?(session)` 钩子:同步热快照名录,`undefined` = 数据未热——零装饰、永不触发 fetch(渲染路径保持同步无副作用);配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化(目录 settle、子代生灭)时的失效通道。controller 把各名录聚合进自己的 `lexicon` 快照 store(每次 source 通知重拉);scope 出生后才注册的 source 由服务广播给活 controller,补 warm 并并入名录。
|
||||
- `decorations.scanTextRefs`:词边界扫描 draft(行首/空白后的 `/name`、`@name`,`x/name` 永不命中)对照名录,命中即成为 Lexical 树中的 `TextRefNode` 实体(claim 装饰对行首 token 席位有优先权——见 [Lexical composer note](2026-08-20-web-composer-lexical-editor.zh.md));编辑破坏匹配形状时实体还原为普通文本。
|
||||
- 发送即原文(不再 `<skill>` 序列化);气泡侧 MessageItem 双形状装饰(legacy `<skill>` 标签 + 纯文本 token)。
|
||||
- `decorations.scanTextRefs`:词边界扫描 draft(行首/空白后的 `/name`、`@name`,`x/name` 永不命中;`/name` token 还必须止于空白或 draft 末尾——与宿主 skill gesture 同样以空白为界,因此 `/nfs-hg/xxx` 是路径、`/plan。` 是普通文本;ui-primitives 中已发送文本的投影 `projectUserText` 采用同一形状)对照名录,命中即成为 Lexical 树中的 `TextRefNode` 实体(claim 装饰对行首 token 席位有优先权——见 [Lexical composer note](2026-08-20-web-composer-lexical-editor.zh.md));编辑破坏匹配形状时实体还原为普通文本。
|
||||
- 发送即原文(不再 `<skill>` 序列化);气泡侧 `projectUserText` 只在同一步骤记录了该名字的 `skill-invocation` 注入时才装饰纯文本 `/name` token——ui-chat 的 `SkillNameProjector` 把该步骤注入的 skill 名挂到直接消息节点上,与 recall 投影挂会话标签的方式相同——因此 `/123` 或随手敲的 `/词` 保持普通文本;指令输入气泡(ui-goal)以同样方式指明其已执行的指令,把 token 渲染为 `command` chip;`@name` token 仍按形状装饰。
|
||||
- 装饰响应性:shell 订阅 controller 的 lexicon store,每次名录变化重扫全文档,scope 出生预热后才 settle 的名录会直接点亮已有 draft token,无需菜单交互或无关重渲染。
|
||||
|
||||
### 每会话供数贡献与键盘私面
|
||||
|
||||
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
|
||||
2026-08-09-client-conversation-node-assembly.md: 425975944f7b23575c4f716dee8754dc6b3ab54c
|
||||
2026-08-09-client-conversation-node-assembly.zh.md: 96439fa951cdc1d6abe397ee37661291c0f954a7
|
||||
2026-08-09-client-conversation-node-assembly.md: 50e11b04d6461e99cdddb8e5e2d94bf864228841
|
||||
2026-08-09-client-conversation-node-assembly.zh.md: 7be1cd1b7f356caf51b8003821369771b0a6e269
|
||||
+2
-2
@@ -278,7 +278,7 @@ Page size, record packing, the number of history loads, and RAF coalescing affec
|
||||
|---|---|---|---|
|
||||
| Inbox | `none` | No Node | Recompute next-step ID state along the Reader chain when prepend supplies earlier splices; next-turn creates no Chat Context |
|
||||
| Message | Immediate by default | `user`, `steering`, or `context` | Window-gap repair can reclassify the same message key |
|
||||
| Request Prompt | Immediate by default | One `system-prompt` for every header carrying a non-empty system field | A step's first header anchors before its request messages; a later same-step series anchors after its surface rewrite; prepend of the preceding header can correct a partial-window anchor |
|
||||
| Request Prompt | Immediate by default | One non-empty `system-prompt` for the initial request, each explicit series, or a real system change | A step's first header anchors before its request messages; prepend can hide a conservatively rendered resume after its preceding header proves the system unchanged |
|
||||
| Assistant | RAF for scalar chunks and packed runs, immediate for final, none for pure usage/finish | Same-key `assistant-step` with running/settled/interrupted status | Scalar and packed reducers are equivalent; Matches support fallback without `step/start`; Location close produces interruption presentation |
|
||||
| Tool | Immediate by default | One recursive `tool-call` root containing all `subCalls` | A result-only history window supports fallback; running→settled retains its key |
|
||||
| Command | Immediate by default | Ordinary `command` or integrated `manual-compaction` | Checkpoint arrival may change the anchor without changing the Context key |
|
||||
@@ -291,7 +291,7 @@ Page size, record packing, the number of history loads, and RAF coalescing affec
|
||||
|
||||
Inbox demonstrates that every Event can be a start-only instantaneous-state Context; not every business requires a start/update pair. Reader links each next-step state to the prior same-kind Context instead of inventing a lifecycle ID for the entire Inbox. The state itself shares immutable pending splice nodes and one current claimed-batch Set, while unconsumed next-turn input remains outside Conversation because no Chat or Trajectory classification reads it.
|
||||
|
||||
Request Prompt demonstrates shared pure interpretation without shared target State: Chat and Trajectory call `inspectRequestPrompt()` from their own Definitions. The function canonicalizes the full header and classifies model-visible system/tool differences; each target then chooses its own output. Chat materializes every header carrying a non-empty system field, including `series` snapshots that repeat an unchanged header for an explicitly declared series or a post-replacement request, while Trajectory retains the complete request fact and its change classification. Ordinary append-only later Turns do not write another unchanged header. The first header in a Step follows the provider envelope rather than the header Event position: step one uses the owning Turn start and later steps use their Step start, placing the system field before the request's user-role messages; a later header in the same Step stays at its own Event after the surface rewrite that began the new series. When the preceding header is outside a partial window, a non-`initial` header stays at its own Event until prepend supplies that predecessor. Every header is a full snapshot, so a first loaded `resume`, `change`, or `series` header can render its system field without fabricating a comparison to unloaded history.
|
||||
Request Prompt demonstrates shared pure interpretation without shared target State: Chat and Trajectory call `inspectRequestPrompt()` from their own Definitions. The function canonicalizes the full header and classifies model-visible system/tool differences; each target then chooses its own output. Chat materializes a non-empty initial system field, a real system change, and each `series` snapshot that explicitly begins a message series or follows a surface replacement. An unchanged `resume` remains in Trajectory and reconstruction state but does not repeat the visible Chat row once its predecessor is loaded. Ordinary append-only later Turns do not write another unchanged header. The first header in a Step follows the provider envelope rather than the header Event position: step one uses the owning Turn start and later steps use their Step start, placing the system field before the request's user-role messages; a later header in the same Step stays at its own Event after the surface rewrite that began the new series. When the preceding header is outside a partial window, a non-`initial` header stays at its own Event and renders conservatively. Prepending an identical predecessor hides an unchanged resume without withdrawing its stable Node key; a real change remains visible. Every header is a full snapshot, so a first loaded `resume`, `change`, or `series` header can render its system field without fabricating a comparison to unloaded history ([resume presentation decision](../bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.md)).
|
||||
|
||||
Retry, Assistant, and Turn Tail demonstrate independent claims on one Event. Each Definition updates only its own State and produces its own atomic Chat Node.
|
||||
|
||||
|
||||
+2
-2
@@ -278,7 +278,7 @@ Chat `order` 的结构性变化仍可能重排当前可见 key;纯 data 更新
|
||||
|---|---|---|---|
|
||||
| Inbox | `none` | 不生成 Node | prepend 补前序 splice 时沿 Reader 链重算 next-step ID state;next-turn 不创建 Chat Context |
|
||||
| Message | 默认 immediate | `user`、`steering` 或 `context` | window gap 修复可让同一 message key 重新分类 |
|
||||
| Request Prompt | 默认 immediate | 每条带非空 system 字段的 header 都生成一个 `system-prompt` | Step 首条 header 锚定在请求消息之前;同 step 后续序列锚定在表层改写之后;prepend 补入前序 header 后可纠正部分窗口的锚点 |
|
||||
| Request Prompt | 默认 immediate | 初始请求、每个显式序列或真实 system 变化各生成一个非空 `system-prompt` | Step 首条 header 锚定在请求消息之前;prepend 补入前序 header 并证明 system 未变后,可隐藏此前保守渲染的 resume |
|
||||
| Assistant | scalar chunk 与 packed run 为 RAF,final immediate,纯 usage/finish 为 none | 同 key `assistant-step`,状态为 running/settled/interrupted | scalar 与 packed reducer 等价;缺 `step/start` 可先用 Matches fallback;Location close 生成中断表现 |
|
||||
| Tool | 默认 immediate | 一个递归 `tool-call` root,包含全部 `subCalls` | result-only 历史窗口可 fallback;running→settled 保持 key |
|
||||
| Command | 默认 immediate | 普通 `command` 或集成 `manual-compaction` | checkpoint 到达可改变 anchor,但不改变 Context key |
|
||||
@@ -291,7 +291,7 @@ Chat `order` 的结构性变化仍可能重排当前可见 key;纯 data 更新
|
||||
|
||||
Inbox 展示了“每条 Event 都是一个 start-only 瞬间态 Context”,不是所有业务都需要 start/update 配对。每个 next-step state 通过 Reader 与前一个同 kind Context 形成连续 fold,而非给整个 Inbox 人工制造生命周期 ID。state 自身共享不可变 pending splice 节点和一个当前 claimed-batch Set;未消费的 next-turn input 不进入 Conversation,因为 Chat 与 Trajectory 都不读取它来分类。
|
||||
|
||||
Request Prompt 展示了如何在不共享 target State 的前提下共用纯解释逻辑:Chat 与 Trajectory 各自在自己的 Definition 中调用 `inspectRequestPrompt()`。该函数规范化完整 header,并判定面向模型的 system/tool 差异;随后每个 target 自行选择产物。Chat 会物化每条带非空 system 字段的 header,包括为显式声明的序列或表层替换后的请求重复未变 header 的 `series` 快照;Trajectory 则保留完整请求事实及其变化分类。普通的仅追加后续 Turn 不会再次写入未变 header。一个 Step 中的首条 header 遵循提供方信封,而不是 header Event 位置:step one 使用所属 Turn start,后续 step 使用各自的 Step start,把 system 字段放到该请求的 user-role 消息之前;同一 Step 的后续 header 保留在开启新序列的表层改写之后。部分窗口未包含前序 header 时,非 `initial` header 会保留在自身 Event,直到 prepend 补入该前序 header。每条 header 都是完整快照,因此已加载窗口中的首条 `resume`、`change` 或 `series` header 无需凭空构造与未加载历史的比较,也能渲染其 system 字段。
|
||||
Request Prompt 展示了如何在不共享 target State 的前提下共用纯解释逻辑:Chat 与 Trajectory 各自在自己的 Definition 中调用 `inspectRequestPrompt()`。该函数规范化完整 header,并判定面向模型的 system/tool 差异;随后每个 target 自行选择产物。Chat 会物化非空的初始 system 字段、真实 system 变化,以及每个显式开启消息序列或紧随表层替换的 `series` 快照。未变化的 `resume` 会留在 Trajectory 和重建状态中,但前序 header 已加载时不会重复可见的 Chat 行。普通的仅追加后续 Turn 不会再次写入未变 header。一个 Step 中的首条 header 遵循提供方信封,而不是 header Event 位置:step one 使用所属 Turn start,后续 step 使用各自的 Step start,把 system 字段放到该请求的 user-role 消息之前;同一 Step 的后续 header 保留在开启新序列的表层改写之后。部分窗口未包含前序 header 时,非 `initial` header 会保留在自身 Event 并保守渲染。prepend 补入相同的前序 header 后,内容未变的 resume 会隐藏但不撤回其稳定 Node key;真实变化仍然可见。每条 header 都是完整快照,因此已加载窗口中的首条 `resume`、`change` 或 `series` header 无需凭空构造与未加载历史的比较,也能渲染其 system 字段([resume 展示决策](../bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md))。
|
||||
|
||||
Retry、Assistant 和 Turn Tail 展示了同一 Event 被多个 Definition 独立认领。每个 Definition 只更新自己的 State,最终分别生成原子 Chat Node。
|
||||
|
||||
|
||||
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
|
||||
2026-08-18-session-history-and-event-transport.md: 10fdd9b256c27aadada97195c8dc5516b4485a43
|
||||
2026-08-18-session-history-and-event-transport.zh.md: bf110b5f1a2bea99f9aa086c66a616eddaa0a50e
|
||||
2026-08-18-session-history-and-event-transport.md: acb6321937ce1b1c67933752f3b93ac82ddcfe0d
|
||||
2026-08-18-session-history-and-event-transport.zh.md: 3828eb5cfe6c496c3d5c2d7085ac550fe94f3101
|
||||
+1
-1
@@ -64,7 +64,7 @@ The browser's Client Remote plugin starts `RemoteStreamMuxClient` idempotently o
|
||||
|
||||
The Host sends one RFC 6455 Ping control frame to every open mux socket at the configured `websocketHeartbeatIntervalMs` interval (two seconds by default). The browser replies with Pong at the protocol layer; neither control frame enters the Remote stream JSON union or changes Connection generation state. Before each Ping, the Host marks the socket as awaiting Pong and terminates it at the next interval if no Pong arrived.
|
||||
|
||||
After an initial connection failure or the loss of a connected socket, open logical streams end their current physical generation with `RemoteStreamCarrierError`. `ConnectionController` owns the bounded exponential retry schedule; each attempt asks the mux to replace any candidate or active socket exactly once before reopening `$events`. A user-requested reconnect resets the attempt sequence and bypasses the delay through the same path ([decision](../feature/2026-08-28-web-connection-recovery-control.md)).
|
||||
After an initial connection failure or the loss of a connected socket, open logical streams end their current physical generation with `RemoteStreamCarrierError`. `ConnectionController` owns the continuous exponential retry schedule with a capped delay; each attempt asks the mux to replace any candidate or active socket exactly once before reopening `$events`. A user-requested reconnect resets the attempt sequence and bypasses the delay through the same path ([decision](../feature/2026-08-28-web-connection-recovery-control.md)).
|
||||
|
||||
The browser's network-status events are inputs to the same Controller. `offline` withdraws the Connection generation and suspends automatic retries; the next `online` transition restarts the base backoff. These events never establish connectivity: only a fresh `$events` ready frame publishes a Connection generation.
|
||||
|
||||
|
||||
+1
-1
@@ -64,7 +64,7 @@ API Proxy 不拥有 Session 或 Workspace Remote namespace,也不拥有 Host
|
||||
|
||||
Host 按配置的 `websocketHeartbeatIntervalMs` 间隔(默认 2 秒)向每条已打开的 mux socket 发送一个 RFC 6455 Ping 控制帧;浏览器在协议层回复 Pong。两种控制帧都不进入 Remote stream JSON union,也不改变 Connection generation 状态。每次 Ping 前,Host 把 socket 标记为等待 Pong;若到下一间隔仍未收到 Pong,Host 会终止该 socket。
|
||||
|
||||
首次建连失败或已连接 socket 丢失后,已打开的 logical stream 会以 `RemoteStreamCarrierError` 结束当前物理 generation。`ConnectionController` 拥有有界的指数 retry 调度;每次尝试都要求 mux 恰好一次替换候选或活动 socket,再重开 `$events`。用户要求的重连通过同一路径重置 attempt 序列并跳过等待(见[决策](../feature/2026-08-28-web-connection-recovery-control.zh.md))。
|
||||
首次建连失败或已连接 socket 丢失后,已打开的 logical stream 会以 `RemoteStreamCarrierError` 结束当前物理 generation。`ConnectionController` 拥有持续且间隔封顶的指数 retry 调度;每次尝试都要求 mux 恰好一次替换候选或活动 socket,再重开 `$events`。用户要求的重连通过同一路径重置 attempt 序列并跳过等待(见[决策](../feature/2026-08-28-web-connection-recovery-control.zh.md))。
|
||||
|
||||
浏览器网络状态事件是同一 Controller 的输入。`offline` 会撤回 Connection generation 并暂停自动 retry;下一次 `online` 转换会从基础退避档重新开始。这些事件不会建立连接;只有新的 `$events` ready 帧才会发布 Connection generation。
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-26-local-submission-echoes.md
|
||||
2026-08-26-local-submission-echoes.md: 258df8f3f4bdd0441b714c7602273897d2d79fc7
|
||||
2026-08-26-local-submission-echoes.zh.md: 57a9523a1eaa399e596f0c8eb6f8913545976f87
|
||||
2026-08-26-local-submission-echoes.md: 0fdb6b65e6e682a955fab770a543e82715d56d90
|
||||
2026-08-26-local-submission-echoes.zh.md: e6ca68578507bf9dd6c7cc0e95f17b597f7a5a80
|
||||
@@ -14,6 +14,8 @@ A multi-image prompt spent seconds in client serialization plus host admission b
|
||||
|
||||
**Retirement is observation-driven with a one-frame delay; display dedupe is render-time and declarative.** The Session marks an echo observed when a durable `user/message` or queue occurrence with its rpcId arrives (append, window install, or control frame) and removes it one animation frame later — after the conversation assembly's frame, which was scheduled first. ChatView independently hides any echo whose rpcId appears among rendered user/steering nodes or queue rows, so within every render exactly one of echo/durable is visible regardless of store update order. An identified prompt failure, `abandon()`, or disposal retires the echo immediately as failed; the first settlement wins.
|
||||
|
||||
**Queue actions require the observed Host identity.** Queued echoes display a sending status and disabled edit, remove, and steer buttons in the same positions as admitted rows. The collapsed dock retains that status in its header. Prompt acknowledgement alone carries no queue-item identity, so only the correlated Host row enables its applicable actions. This keeps slow admission visible without treating a local request id as a mutable Host queue item.
|
||||
|
||||
**The composer commits optimistically.** Enter clears the draft, occurrence table, and undo history in one machine transaction and keeps phase `plain`; the send runs as a detached attempt (concurrent sends allowed; the single frozen in-flight slot remains command-only). Failed detached sends are restored together in submission order while the composer is empty or still contains the preceding automatic restoration; a user edit ends that restoration sequence. Draft images remain owned by the detached attempt through echo retirement, so Session scope disposal can release them after they have left the rail. An observed echo gives each preview URL to `HistoricalImageCache.seed` under the admitted reference. The cache exposes that preview synchronously, fetches the durable attachment, replaces the preview with the canonical URL, and revokes both URLs with their respective lifetimes. Direct subagent continuations do not register echoes because their transport assigns a different RPC identity and image input is unsupported.
|
||||
|
||||
Client image encoding switched from the synchronous chunked-`btoa` loop to `FileReader.readAsDataURL` (native encode). The browser→host transport still ships one base64 JSON envelope; that remaining #2885 transport work is out of scope here.
|
||||
|
||||
@@ -14,6 +14,8 @@
|
||||
|
||||
**退休由观察驱动并延迟一帧;显示去重是渲染期的声明式规则。**Session 在带其 rpcId 的 durable `user/message` 或 queue occurrence 到达时(append、窗口安装或 control frame)标记回显为已观察,并在一个动画帧之后移除,晚于先注册的会话组装帧。ChatView 独立地隐藏 rpcId 出现在已渲染 user/steering 节点或 queue 行中的回显,因此无论 store 更新顺序如何,每一次渲染中回显与 durable 恰有一个可见。带标识的 prompt 失败、`abandon()` 或销毁使回显立即按 failed 退休;先到的 settlement 生效。
|
||||
|
||||
**队列操作要求观察到 Host 身份。**排队回显显示发送状态,并在正式队列行的相同位置显示禁用的编辑、删除和插话按钮。折叠后的队列在标题栏保留该状态。单独的 prompt 确认不携带队列项身份,因此只有关联的 Host 队列行到达后才启用适用的操作。这使缓慢受理的状态可见,同时避免把本地请求 id 当作可修改的 Host 队列项。
|
||||
|
||||
**Composer 乐观提交。**Enter 在一个 machine 事务里清空草稿、occurrence 表和撤销历史,phase 保持 `plain`;发送作为 detached attempt 运行,允许并发发送,唯一的冻结 in-flight 槽只留给命令。多个 detached 发送失败时,只要 composer 为空或仍是上一次自动还原的内容,就按提交顺序合并还原;用户编辑后停止这一轮自动还原。草稿图片由 detached attempt 持有到回显退休,因此图片离开 rail 后销毁 Session scope 仍能释放它们。回显以 observed 退休时,`HistoricalImageCache.seed` 把每个预览 URL 挂到 admitted 引用名下。缓存同步公开预览 URL,同时读取 durable 附件;读取完成后用规范化 URL 替换预览,并按各自生命周期撤销两个 URL。直接 subagent continuation 不注册回显,因为它的 transport 会分配另一个 RPC id,而且不支持图片输入。
|
||||
|
||||
客户端图片编码从同步分块 `btoa` 循环换成 `FileReader.readAsDataURL`(原生编码)。browser→host 传输仍是一个 base64 JSON 整包;#2885 剩余的传输改造不在本决定范围内。
|
||||
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# 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-03-resume-headers-do-not-repeat-system-prompts.md
|
||||
2026-09-03-resume-headers-do-not-repeat-system-prompts.md: de5e509c9e57af35bc36c24004457f02b63fd99d
|
||||
2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md: 008e25d8d507aac8fbaec7230bad433732f0efd0
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# Agent Note: Resume headers do not repeat system prompts
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Forking a Session copies the source history into the child. The child's first model request then records a `request/header` with reason `resume`, even when its system field is identical to the preceding copied header. Chat treated every resume header as a new display point, so continuing the fork showed a second `System prompt` row and suggested that the system prompt had been injected twice. The provider request still carried the system field once; the duplicate existed only in Chat presentation.
|
||||
|
||||
## Decision
|
||||
|
||||
The durable resume header records the request boundary needed for exact Session reconstruction. Chat compares that full header with the preceding loaded Request Prompt and displays a non-empty system prompt only for the initial request, an explicit message-series start, or a real system-field change. An unchanged resume does not create a visible repetition.
|
||||
|
||||
A partial history window may begin with a non-initial header and lack the predecessor needed for comparison. Chat renders that system prompt conservatively. If prepend later supplies an identical predecessor, the existing request-prompt Node becomes hidden instead of being withdrawn; its key and page-lifetime anchor stay stable. A different system field remains visible.
|
||||
|
||||
Trajectory exposes every request header and its classified changes. Chat presentation does not alter provider requests, Session events, or reconstruction.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Omit unchanged resume headers from the Session log.** Rejected: resume is a real request boundary, and removing it would make exact reconstruction depend on process history that the durable log does not contain.
|
||||
|
||||
**Special-case only forked Sessions.** Rejected: an ordinary process resume has the same presentation semantics, and the request headers already contain the system fields needed for a direct comparison.
|
||||
|
||||
**Keep the duplicate row as a lifecycle marker.** Rejected: `System prompt` describes model-visible request content, so using it to mark a loop restart incorrectly implies another prompt injection. Request lifecycle evidence remains available in Trajectory.
|
||||
|
||||
## Consequences
|
||||
|
||||
Continuing a fork or resuming a process with an unchanged system field leaves one visible `System prompt` row for the current message series. Explicit series starts and real system changes still repeat the row. A partial window can initially show a conservative row and hide it after older history loads, while retaining the same materialized Node.
|
||||
|
||||
The unit regression covers initial, series, unchanged resume, system-change, and prepend cases. The Web recorded-session scenario contains an unchanged resume header and asserts that the settled Chat renders exactly one `System prompt` control.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# Agent Note: Resume header 不重复系统提示词
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-09-03-resume-headers-do-not-repeat-system-prompts.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
fork Session 会把源会话历史复制到子会话。即使 system 字段与前一条被复制的 header 完全相同,子会话的第一个模型请求仍会记录一条 reason 为 `resume` 的 `request/header`。Chat 把每条 resume header 都视作新的展示点,因此继续 fork 会显示第二行`系统提示词`,让人误以为系统提示词被注入了两次。提供方请求实际仍只携带一次 system 字段;重复仅存在于 Chat 展示中。
|
||||
|
||||
## 决策
|
||||
|
||||
持久化 resume header 记录精确重建 Session 所需的请求边界。Chat 会把完整 header 与前一条已加载 Request Prompt 比较,只在初始请求、显式消息序列起点或真实 system 字段变化时显示非空系统提示词。内容未变的 resume 不创建可见的重复行。
|
||||
|
||||
部分历史窗口可能以非初始 header 开头,因缺少前序 header 而无法比较。Chat 会保守渲染该系统提示词。如果 prepend 随后补入相同的前序 header,既有 request-prompt Node 会转为隐藏而不是被撤回;其 key 和页面生命周期内的 anchor 保持稳定。不同的 system 字段仍然可见。
|
||||
|
||||
Trajectory 会展示每一条请求 header 及其变化分类。Chat 展示不会改变提供方请求、Session event 或重建行为。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**从 Session log 省略未变化的 resume header。** 否决:resume 是真实的请求边界,移除后精确重建将依赖持久日志未记录的进程历史。
|
||||
|
||||
**只对 fork Session 做特殊处理。** 否决:普通进程恢复具有相同的展示语义,请求 header 已经包含可直接比较的 system 字段。
|
||||
|
||||
**把重复行保留为生命周期标记。** 否决:`系统提示词`描述模型可见的请求内容,用它标记 loop 重启会错误暗示再次注入提示词。请求生命周期证据仍可在 Trajectory 中查看。
|
||||
|
||||
## 后果
|
||||
|
||||
继续 fork 或在 system 字段未变时恢复进程,当前消息序列只保留一行可见的`系统提示词`。显式序列起点与真实 system 变化仍会重复该行。部分窗口起初可以显示保守行,并在更早历史加载后将其隐藏,同时保留同一个已物化 Node。
|
||||
|
||||
单元回归覆盖初始请求、显式序列、未变化 resume、system 变化与 prepend 场景。Web 录制会话场景包含一条未变化的 resume header,并断言稳定后的 Chat 只渲染一个`系统提示词`控件。
|
||||
+3
-3
@@ -1,6 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-17-command-image-attachment-envelope.md
|
||||
2026-08-17-command-image-attachment-envelope.md: 328a3fffa1d8db3ac9be42983965ef7f9578dec9
|
||||
2026-08-17-command-image-attachment-envelope.zh.md: 9de197d06692523b7b5bca4f7aac36ce9f44b105
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-05-continuous-client-recovery.md
|
||||
2026-09-05-continuous-client-recovery.md: 3a017f69d78f9155dd513d44eb87e4bf0bdc1f9d
|
||||
2026-09-05-continuous-client-recovery.zh.md: bc8b12d2ae4143ddb397334a76cdd65b49c32d96
|
||||
@@ -0,0 +1,37 @@
|
||||
# Agent Note: Continuous Client connection recovery
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-09-05-continuous-client-recovery.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A generation source can remain pending without reporting readiness or carrier failure. A warning alone leaves the Client waiting indefinitely. Finite automatic retries also leave a page disconnected after the Host recovers from a longer outage, even though the browser's network status never changes.
|
||||
|
||||
## Decision
|
||||
|
||||
[`ConnectionController`](../../../../packages/client/connection/src/client/connection.ts) owns both the readiness deadline and the continuous retry schedule. A handshake reports a slow Host after three seconds and aborts after fifteen seconds by default. The warning gives early feedback without discarding a Host that needs several seconds to become ready; the deadline bounds each attempt and logs the timeout when it cancels the generation. Warning and cancellation times are independent, so a shorter hard deadline does not require changing both fields; a warning scheduled after settlement is cancelled. Cancellation reaches the generation source, which must release its resources and settle before another source starts. A cancelled source's late ready callback cannot establish a generation.
|
||||
|
||||
Retry caps grow from 500ms through 1s, 2s, 4s, and 8s to 10s, with the existing 50–100% jitter. Failures at the maximum cap continue retrying. Separating a maximum delay from a retry-count limit follows the distinction in [Socket.IO's Client options](https://socket.io/docs/v4/client-options/#reconnectionattempts), while DSH retains its existing Remote stream protocol and single scheduler. Gateway replaces the physical socket once for each Controller-requested attempt. Both a pending WebSocket candidate and an open socket without an opening ready frame can recover this way.
|
||||
|
||||
The Host Connection plugin validates `recovery` in its configuration and injects the resolved, non-secret timing into each page through `webserver/index-inject`. The Client validates that bootstrap input before providing Connection; direct loop options may override it. Timer values must be positive integers within the browser timer range, and the backoff factor must be finite and at least one. The shared resolver explicitly rejects `NaN`, which range comparisons alone cannot exclude. A factor of one selects continuous fixed-cap retries. Changes to Host timing apply to subsequently loaded pages.
|
||||
|
||||
The Settings indicator labels active recovery **Reconnecting** and keeps **Reconnect now** available. This decision supersedes the terminal retry policy in [Web connection recovery control](../feature/2026-08-28-web-connection-recovery-control.md). That note still owns manual recovery, browser offline suspension, the single-scheduler rule, and indicator presentation. A fresh `$events` ready frame alone establishes connectivity; domain streams retain their own baseline and cursor recovery.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Only reject the readiness wait.** The Controller still waits for source settlement before retrying. The deadline must cancel the source as well, otherwise the same pending work blocks recovery.
|
||||
|
||||
**Cancel every handshake after three seconds.** This conflates slow-Host feedback with failure and repeatedly discards legitimate slower handshakes. Separate configurable warning and cancellation times preserve a bounded opportunity to finish.
|
||||
|
||||
**Stop after a finite retry sequence.** A page cannot discover later Host recovery without another user or browser event. Capping the interval limits traffic while preserving automatic recovery.
|
||||
|
||||
**Start another source without awaiting cancellation cleanup.** Overlapping generations can retain listeners and deliver obsolete events. The source's cancellation contract requires settlement; abandoning it does not establish cleanup.
|
||||
|
||||
## Consequences
|
||||
|
||||
Long outages retain one retry schedule and produce bounded-rate connection traffic until recovery, explicit stop, or browser offline suspension. A permanently invalid credential still requires user action; connection retries do not refresh credentials or replay unary mutations. Immediate readiness continues to reset backoff, and browser offline remains authoritative for suspension; stable-connection reset windows and local-transport exceptions are separate policy changes.
|
||||
|
||||
## Testing
|
||||
|
||||
Controller tests cover recovery beyond the former final tier, fixed-cap retries, slow readiness, deadline cancellation, delayed cleanup, late ready callbacks, and manual reconnect or stop during a handshake. Host and Client tests cover timing propagation, invalid input, and injection disposal. Gateway tests use the real Controller and event pump with scripted WebSockets to verify both stalled opening phases, physical replacement, and one recovery reset. The recorded-session Web lifecycle scenario covers automatic recovery past the former stop point, manual replacement of a stalled handshake, and localized recovery presentation.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Agent Note: Client 连接持续恢复
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-09-05-continuous-client-recovery.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
generation source 可能一直挂起,既不报告就绪,也不报告载体失败。仅告警会让 Client 无限等待。有限次数的自动重试还会使页面在 Host 从较长中断恢复后继续保持断连,即使浏览器网络状态从未变化。
|
||||
|
||||
## 决策
|
||||
|
||||
[`ConnectionController`](../../../../packages/client/connection/src/client/connection.ts) 同时拥有握手就绪期限和持续重试调度。默认情况下,握手在三秒后报告 Host 响应缓慢,在十五秒后中止。告警提供早期反馈,同时保留需要数秒才能就绪的 Host;硬期限限制每次尝试的时长,并在取消 generation 时记录超时。告警与取消时间相互独立,因此缩短硬期限不需要同时修改两个字段;排定在握手结束之后的告警会被取消。取消会传到 generation source,后者必须释放资源并结束,下一 source 才能启动。已取消 source 迟到的 ready 回调不能建立 generation。
|
||||
|
||||
重试上限从 500ms 开始,经过 1s、2s、4s、8s 增长到 10s,保留现有 50–100% 抖动。达到最大上限后失败仍继续重试。把最大延迟与重试次数上限分开,与 [Socket.IO Client 选项](https://socket.io/docs/v4/client-options/#reconnectionattempts)的区分一致;DSH 保留自身的 Remote stream 协议和唯一调度器。Controller 每要求一次尝试,Gateway 就替换一次物理 socket。仍在等待打开的 WebSocket 候选,以及已打开但未收到首个 ready 帧的 socket,都能通过此路径恢复。
|
||||
|
||||
Host Connection 插件校验配置中的 `recovery`,通过 `webserver/index-inject` 把已解析且不含秘密的时序数据注入每个页面。Client 在提供 Connection 之前校验启动输入;直接传给循环的选项可覆盖这些值。定时器值必须是浏览器定时器范围内的正整数,退避因子必须是至少为一的有限数。共享解析器显式拒绝仅靠范围比较无法排除的 `NaN`。一表示以固定上限持续重试。Host 时序配置的变更适用于随后加载的页面。
|
||||
|
||||
Settings 指示器把活动恢复标为**自动重连中**,并始终提供**立即重连**。本决策取代[Web 连接恢复控制](../feature/2026-08-28-web-connection-recovery-control.zh.md)中的终态重试策略。该记录仍拥有手动恢复、浏览器离线暂停、唯一调度器规则与指示器展示。只有新的 `$events` ready 帧才能建立连接状态;各域的 stream 保留各自的 baseline 与 cursor 恢复方式。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**仅拒绝就绪等待。** Controller 仍会等待 source 结束才重试。硬期限必须同时取消 source,否则同一个挂起的工作仍会阻塞恢复。
|
||||
|
||||
**三秒后取消每次握手。** 这会把 Host 响应缓慢的反馈等同于失败,反复丢弃合法的较慢握手。分别配置告警与取消时间,可在有界时长内保留完成机会。
|
||||
|
||||
**有限序列结束后停止重试。** 没有后续用户或浏览器事件,页面就无法发现 Host 已恢复。对间隔封顶可以限制流量,同时保留自动恢复。
|
||||
|
||||
**不等待取消清理就启动另一个 source。** 重叠的 generation 可能保留 listener 并投递过时事件。source 的取消契约要求它结束;放弃等待不能证明清理完成。
|
||||
|
||||
## 后果
|
||||
|
||||
长时间中断期间保留唯一重试调度,并以有界频率产生连接流量,直到恢复、显式停止或浏览器离线暂停。永久无效的凭据仍需用户处理;连接重试不会刷新凭据,也不会重放一元修改操作。立即就绪仍会重置退避,浏览器离线仍决定暂停;稳定连接后的重置窗口和本地载体例外属于独立策略变更。
|
||||
|
||||
## 测试
|
||||
|
||||
Controller 测试覆盖超过原终档后的恢复、固定上限重试、慢就绪、期限取消、延迟清理、迟到 ready,以及握手期间手动重连或停止。Host 和 Client 测试覆盖时序传递、无效输入及注入销毁。Gateway 测试使用真实 Controller 和事件 pump,配合可编排的 WebSocket,验证两个握手挂起阶段、物理替换及唯一恢复 reset。录制 Session 的 Web 生命周期场景覆盖超过原停止点后的自动恢复、手动替换挂起握手,以及本地化恢复展示。
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
|
||||
2026-07-23-web-assistant-markdown.md: d2b8e30d779656636f70b05524c96796a254b57b
|
||||
2026-07-23-web-assistant-markdown.zh.md: c1542d75faf1b484160f98b4217164b5df4e4b99
|
||||
2026-07-23-web-assistant-markdown.md: 4063ad647c485be295a55087247681a494dbeabf
|
||||
2026-07-23-web-assistant-markdown.zh.md: 6b062e155c88bc8c3f3cf048ec463f3db0b4f7bc
|
||||
@@ -10,7 +10,7 @@ The Web conversation preserves assistant Markdown source through session events,
|
||||
|
||||
## Decision
|
||||
|
||||
`@deepseek-ai/dsh-client-ui-primitives` exports `MarkdownText` as the untrusted assistant-text renderer, and `ui-conversation` selects it only for assistant `text` blocks. Finalized history, the streaming tail, and interrupted partials already share `AssistantMarkdown`, so they receive the same renderer without changing events or snapshots. User and steering messages keep `MessageText` and remain literal.
|
||||
`@deepseek-ai/dsh-client-ui-primitives` exports `MarkdownText` as the untrusted assistant-text renderer, and `ui-conversation` selects it only for assistant `text` blocks. Finalized history, the streaming tail, and interrupted partials already share `AssistantMarkdown`, so they receive the same renderer without changing events or snapshots. User and steering messages render through `projectUserText` (inline plain runs plus reference chips) and remain literal.
|
||||
|
||||
`MarkdownText` parses with `mdast-util-from-markdown` plus the GFM micromark extensions and renders the mdast tree through the package's own renderer, parsing incrementally while a turn streams (the [incremental AST renderer note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) owns that mechanism and its DOM-parity contract). It covers CommonMark blocks plus GFM tables, task lists, strikethrough, and autolinks without raw-HTML parsing. A micromark attention extension reuses the CommonMark resolver while letting runs of at least two asterisks close after Unicode punctuation when followed immediately by CJK text. This exception covers punctuation-terminated strong emphasis in whitespace-free CJK prose during streaming and after settlement; single-asterisk emphasis, non-CJK adjacency, escaped source, code, and math retain upstream parsing. Fenced code routes through the shared `CodeBlock`, which highlights registered grammars with the client's shiki singleton (`--shiki-*` tokens) and falls back to plain monospace otherwise. While a turn streams, fences highlight incrementally: each chunk tokenizes newly completed text from a saved grammar state plus the still-growing last line, excluding the completed prefix from repeated work (the [streaming fence-highlight note](2026-08-20-web-streaming-fence-highlight.md) owns that mechanism).
|
||||
|
||||
@@ -28,7 +28,7 @@ Fenced code and GFM tables own horizontal overflow so long content cannot widen
|
||||
|
||||
**Promote the existing mdast and micromark development dependencies and maintain a custom React walker.** This avoids a new parser family but makes the product own every node mapping, GFM extension, and security-sensitive rendering branch. The dedicated React renderer keeps that traversal upstream while preserving an AST-to-React path. *Later reversed on new evidence — incremental streaming parsing needs AST-level input the string-only wrapper cannot provide; the [incremental AST renderer note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) owns that decision.*
|
||||
|
||||
**Replace `MessageText` with Markdown rendering.** This formats user prompts and steering as a side effect. Those authored inputs remain literal until the product chooses that behavior explicitly.
|
||||
**Render user prompts and steering as Markdown too.** This formats authored input as a side effect. Those authored inputs remain literal until the product chooses that behavior explicitly.
|
||||
|
||||
**Parse Markdown into session snapshots.** This would make React nodes or presentation ASTs durable runtime state and reintroduce a final-versus-streaming mode boundary. Parsing stays at the presentation leaf instead.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd
|
||||
|
||||
## 决策
|
||||
|
||||
`@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`,用作不受信任的 assistant 文本渲染器;`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`,因此无需更改事件或快照,它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`,并保持按字面渲染。
|
||||
`@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`,用作不受信任的 assistant 文本渲染器;`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`,因此无需更改事件或快照,它们便会采用同一渲染器。用户消息与 steering 消息经 `projectUserText` 渲染(行内普通片段加引用 chip),并保持按字面渲染。
|
||||
|
||||
`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析,并经包内自有渲染器渲染 mdast 树,轮次流式输出期间增量解析([增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md) 拥有该机制及其 DOM 一致性约定)。它覆盖 CommonMark 块,以及 GFM 表格、任务列表、删除线与自动链接,且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver,同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合,前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体;单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由;该组件用客户端的 shiki 单例(`--shiki-*` token)高亮已注册语法,否则回退为纯等宽文本。轮次流式输出期间,围栏增量高亮:每个分片从保存的 grammar state 出发 tokenize 新完成的文本以及仍在增长的最后一行,不重复处理已完成的前缀([流式围栏高亮 Note](2026-08-20-web-streaming-fence-highlight.zh.md) 拥有该机制)。
|
||||
|
||||
@@ -28,7 +28,7 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
|
||||
|
||||
**将现有的 mdast 与 micromark 开发依赖提升为正式依赖,并维护自定义 React walker。**此方案避免引入新的解析器体系,但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护,同时保留 AST 到 React 的处理路径。*后因新证据被推翻——增量流式解析需要纯字符串封装无法提供的 AST 级输入;该决策由[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md) 拥有。*
|
||||
|
||||
**将 `MessageText` 替换为 Markdown 渲染。**这会产生格式化用户提示词与 steering 的副作用。在产品明确选择此行为之前,这些输入仍按字面渲染。
|
||||
**把用户提示词与 steering 也按 Markdown 渲染。**这会产生格式化用户输入的副作用。在产品明确选择此行为之前,这些输入仍按字面渲染。
|
||||
|
||||
**将 Markdown 解析为会话快照。**这会让 React 节点或呈现层 AST 成为持久的运行时状态,并重新引入最终输出与流式输出之间的模式边界。解析仍留在呈现层的叶节点中。
|
||||
|
||||
|
||||
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md
|
||||
2026-08-04-web-slash-command-fuzzy-discovery.md: 8d7fe88f8d19a6edc7b51e63578c468df085c238
|
||||
2026-08-04-web-slash-command-fuzzy-discovery.zh.md: a96f9c984e32dd777950b9f9d8594b3a9c8b7c17
|
||||
2026-08-04-web-slash-command-fuzzy-discovery.md: 17ba1a1cba4876140bada74e65ba1b10ed5fdd76
|
||||
2026-08-04-web-slash-command-fuzzy-discovery.zh.md: fe23dcb5d3c14a492a5882b5bad4c84e256ef064
|
||||
@@ -6,13 +6,13 @@ English | [中文](2026-08-04-web-slash-command-fuzzy-discovery.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The web command menu required a command-name prefix, so discovery failed when a user remembered the significant letters but not their exact positions. Broadening menu matching could make discovery easier, but command execution must remain exact and deterministic: an approximate line must never execute a nearby command.
|
||||
The web command menu required a command-name prefix, so discovery failed when a user remembered the significant letters but not their exact positions. The skill source of the same `/` menu later kept a case-sensitive prefix filter, so the two groups of one menu answered the same keystrokes differently. Broadening menu matching could make discovery easier, but command execution must remain exact and deterministic: an approximate line must never execute a nearby command.
|
||||
|
||||
## Decision
|
||||
|
||||
The `/` command source fuzzy-matches the typed query against command names as a case-insensitive ordered subsequence. Exact prefixes form the highest ranking class. Within each class, the strongest alignment score rewards separator boundaries and adjacent characters while penalizing leading characters and gaps; equal scores retain the host-directory and client-contribution order. Position filtering still removes argument-taking commands from inline menus before ranking.
|
||||
The `/` menu's command and skill sources fuzzy-match the typed query against candidate names as a case-insensitive ordered subsequence through one ranker, `rankByName` in ui-primitives, the narrow static owner for shared browser code ([client rules](../../../../packages/client/AGENTS.md)). Exact prefixes form the highest ranking class. Within each class, the strongest alignment score rewards separator boundaries and adjacent characters while penalizing leading characters and gaps; equal scores retain the host catalog and client-contribution order. Position filtering still removes argument-taking commands from inline menus before ranking.
|
||||
|
||||
The scorer uses dynamic programming in `O(query length × name length)` time and `O(name length)` memory per candidate. Candidate scoring stays client-side and examines names only; descriptions do not affect matching. Menu selection still dispatches the selected exact name, while space and Enter adjudication continue to require an exact command token.
|
||||
The scorer uses dynamic programming in `O(query length × name length)` time and `O(name length)` memory per candidate. Candidate scoring stays client-side and examines names only; descriptions do not affect matching. Menu selection still dispatches the selected exact name, the skill source still lands the literal `/name ` text the host resolves exactly, and space and Enter adjudication continue to require an exact command token.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -22,6 +22,8 @@ The scorer uses dynamic programming in `O(query length × name length)` time and
|
||||
|
||||
**Use a general fuzzy-search dependency.** Rejected because this surface needs one constrained subsequence rule over a small command catalog; a configurable search index would add bundle weight and ranking behavior not used by the product.
|
||||
|
||||
**Export the ranker from the command plugin or the trigger pipeline.** Rejected because a feature plugin exports no values beyond what cordis loading needs and never runtime-imports another feature plugin; peer agent products that share one matcher between commands and skills (Claude Code, Pi, Kimi Code) keep it in a shared library for the same reason.
|
||||
|
||||
## Consequences
|
||||
|
||||
Users can discover a command from remembered in-order letters, and ranking remains stable across identical catalogs. The score is deliberately heuristic: a separator-aligned match can outrank a match with a shorter raw span. Package tests pin each ranking factor and stable ties, while the assembled Web replay snapshot pins `/cpt` resolving to `/compact`. Exact execution semantics are unchanged.
|
||||
Users can discover a command or a skill from remembered in-order letters, and ranking remains stable across identical catalogs. The score is deliberately heuristic: a separator-aligned match can outrank a match with a shorter raw span. ui-primitives tests pin each ranking factor and stable ties, the command and skill sources pin that they rank through the shared ranker, and the assembled Web goldens pin `/cpt` resolving to `/compact` and a subsequence query resolving to one skill. Exact execution semantics are unchanged.
|
||||
+6
-4
@@ -6,13 +6,13 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
Web 命令菜单要求按命令名前缀匹配,因此用户只记得关键字母却不记得其准确位置时,就无法发现命令。扩大菜单的匹配范围可使命令更易发现,但命令执行仍必须保持精确匹配和确定性:近似输入行绝不能执行相近命令。
|
||||
Web 命令菜单要求按命令名前缀匹配,因此用户只记得关键字母却不记得其准确位置时,就无法发现命令。同一 `/` 菜单的 skill source 后来仍保留区分大小写的前缀过滤,同一菜单的两个分组对同样的按键给出不同答案。扩大菜单的匹配范围可使命令更易发现,但命令执行仍必须保持精确匹配和确定性:近似输入行绝不能执行相近命令。
|
||||
|
||||
## 决策
|
||||
|
||||
`/` 命令 source 将键入的查询作为不区分大小写的有序子序列,与命令名进行模糊匹配。精确前缀构成排名最高的一类匹配。在每类匹配中,对齐分数越高越优先:分隔符边界和相邻字符会提高分数,前导字符和间隔会降低分数;分数相同则保持 host 目录和 client contribution 的顺序。位置过滤仍会在排名前从行内菜单中移除接收参数的命令。
|
||||
`/` 菜单的命令 source 与 skill source 将键入的查询作为不区分大小写的有序子序列,与候选名进行模糊匹配,二者共用一个排序器:ui-primitives 中的 `rankByName`,即共享浏览器代码的窄静态归属方([client 规则](../../../../packages/client/AGENTS.md))。精确前缀构成排名最高的一类匹配。在每类匹配中,对齐分数越高越优先:分隔符边界和相邻字符会提高分数,前导字符和间隔会降低分数;分数相同则保持 host 目录和 client contribution 的顺序。位置过滤仍会在排名前从行内菜单中移除接收参数的命令。
|
||||
|
||||
评分器对每个候选项使用动态规划,时间复杂度为 `O(query length × name length)`,空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名;命令描述不影响匹配。菜单选择仍派发所选的精确名称,而空格键和 Enter 键的判定逻辑仍要求命令 token 精确匹配。
|
||||
评分器对每个候选项使用动态规划,时间复杂度为 `O(query length × name length)`,空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名;命令描述不影响匹配。菜单选择仍派发所选的精确名称,skill source 仍落下由宿主精确解析的字面 `/name ` 文本,而空格键和 Enter 键的判定逻辑仍要求命令 token 精确匹配。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
@@ -22,6 +22,8 @@ Web 命令菜单要求按命令名前缀匹配,因此用户只记得关键字
|
||||
|
||||
**使用通用模糊搜索依赖。** 否决,因为该界面只需对小型命令目录使用一种受限的子序列规则;可配置搜索索引会增加 bundle 体积,并引入产品未使用的排名行为。
|
||||
|
||||
**从命令插件或触发管线导出排序器。** 否决,因为特性插件除 cordis 加载所需之外不导出任何值,也绝不运行时导入另一个特性插件;在命令与 skill 之间共用一个匹配器的同行产品(Claude Code、Pi、Kimi Code)出于同样的原因把它放在共享库中。
|
||||
|
||||
## 后果
|
||||
|
||||
用户可以凭按顺序记得的字母发现命令;只要目录相同,排名就保持稳定。评分刻意采用启发式规则:与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。包测试固定各项排名因素以及同分时的稳定顺序,组装后的 Web 回放快照固定 `/cpt` 解析为 `/compact` 的行为。精确执行语义保持不变。
|
||||
用户可以凭按顺序记得的字母发现命令或 skill;只要目录相同,排名就保持稳定。评分刻意采用启发式规则:与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。ui-primitives 的测试固定各项排名因素以及同分时的稳定顺序,命令 source 与 skill source 的测试固定二者经共享排序器排名,组装后的 Web golden 固定 `/cpt` 解析为 `/compact`、以及一个子序列查询解析为唯一 skill 的行为。精确执行语义保持不变。
|
||||
@@ -1,46 +0,0 @@
|
||||
# Agent Note: Command image-attachment envelope
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-17-command-image-attachment-envelope.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The Web composer submits one envelope — draft text, attached images, and delivery mode — but the two submission planes consumed it asymmetrically. A plain message rode `defaultSink → conversation.sendSession`, which serialized the images into prompt content and cleared them on success. A claimed slash command rode `claim.submit(args, actx)`, a text-only transaction: `/goal rebuild the cathedral` with four reference photos executed the command, cleared the draft, and silently stranded the images in the composer rail. The model never saw them, and no surface said so. The defect was contract-level, not a missed call site: nothing in the claim, the adjudication, or the host executor modeled attachments, so any command could consume the text half of a submission and drop the rest.
|
||||
|
||||
Merging the two planes was not on the table — the [plugin command registration Agent Note](2026-07-19-plugin-command-registration.md) deliberately keeps human commands out of the model plane, and that separation is correct. The gap was that the envelope fractured at the plane fork.
|
||||
|
||||
## Decision
|
||||
|
||||
The submission envelope is modeled end to end, and every command route either consumes it whole or refuses it loudly.
|
||||
|
||||
**Declaration.** `CommandDefinition.input.images: boolean` (absent = false) declares whether composer images may accompany an invocation. The flag rides the frozen `CommandDescriptor` through `commands/list` to every client, onto the minted `CommandClaim` (`images: true`), and into the input machine's published claim snapshot.
|
||||
|
||||
**Generic identity, image-specific payload.** Browser drafts and durable references already use `DraftAttachmentId` and `AttachmentId`; the command RPC carries encoded bytes rather than an image identifier. The wire remains `EncodedImageAttachment[]`, and the declaration remains `input.images`, while images are the only non-text attachment with defined admission and model-block semantics.
|
||||
|
||||
**Executor enforcement.** `CommandRuntime.execute(agent, line, images, signal)` carries the submission's base64 images (`EncodedImageAttachment` from `@deepseek-ai/dsh-attachment/types`). The executor — not the composer — enforces the declaration: images to a non-declaring command, an absent attachment store, and an exceeded batch limit each settle as a logged `command/done` error before the handler runs. Admission goes through the attachment package's `admitEncodedImages` — the shared wire entry that enforces canonical base64 and delegates batch admission (limits, validation, ordered commit) to `AttachmentStore.saveImages` — so both wire endpoints (prompt RPC and command executor) share one sequence and a rejected batch publishes no durable object. An admitted batch reaches the handler as frozen ordered `ImageBlock`s on `invocation.attachments`.
|
||||
|
||||
**Producer-owned model visibility.** The registry never schedules the images itself. `/goal` submits one `agent.followup` user message — image blocks plus the fixed text `Reference images for the goal objective.` — after a successful create or edit, so later goal rounds read the images from ordinary session history and the goal domain stores no attachment state. `/plan <message>` folds the images into its steered text message, while bare `/plan` steers an image-only user message because the images may contain the whole task. Producer control forms with no model input (`/goal pause`, `/plan off`) return a direct error and keep the composer's images in place. The plan projection treats `command/run` as a candidate and drops it on a paired `command/done` error, so a rejected image-carrying `/plan off` cannot leave a pending exit.
|
||||
|
||||
**Composer refusal is a visible banner, everything retained.** ui-commands' `matchEnter` receives a `SubmitEnvelope` (image count) from adjudication and throws a localized `notice.imagesUnsupported` refusal for every enter route that cannot consume images: contribution popups, decorated popups, non-declaring claims, and bare detached executes. The input machine publishes one error notice, which the composer renders through its transient Toast banner with draft and images untouched. A pre-claimed submit (space/menu claim) is gated in the facade with the same copy from the `conversation` namespace. On the accepting path the facade serializes the draft images through the hub's `commandImages` plumbing, passes them to `claim.submit`, and clears plus releases them only on a success outcome; an error result (including a producer grammar rejection) keeps them.
|
||||
|
||||
## Testing
|
||||
|
||||
Registry executor enforcement, admission failure settlement, and frozen invocation attachments are covered in `packages/interaction/commands/tests/commands.spec.ts`; batch admission ordering and limits in `packages/attachment/attachment/tests/admission.spec.ts`; producer behavior in `packages/goal/command-goal/tests/command-goal.spec.ts` and `packages/plan/plan-mode/tests/plan-mode.spec.ts`; client refusal and consumption paths in the ui-commands, ui-conversation, and ui-input-trigger client suites; and the assembled-application flow in the apps/web keyless lanes.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Block commands whenever images are attached (no acceptance path)** — rejected: predictable, but `/goal` with reference images is the motivating use case; the user's images would have no route to the model at all.
|
||||
- **Auto-send stranded images as a follow-up user message after any command** — rejected: surprising for host-state commands (`/model`, `/compact`), and it moves the message contract from the producer to the composer, against the command registry's "producer owns model-visible work" rule.
|
||||
- **Store attachment references in the goal domain and render them into round prompts** — rejected: requires durable goal schema changes and either duplicates image blocks into every round prompt or adds round-one-only prompt shape; the round-prompt invariant would need attachment state. One ordinary logged user message achieves the same model visibility.
|
||||
- **Consume images on any command success regardless of grammar** — rejected: `/goal pause` with images attached would silently discard them, recreating the original defect one layer deeper. Consumption is tied to the producer's explicit success, and grammar misfits return errors.
|
||||
- **Keep enforcement client-side only** — rejected: schema omission is not enforcement; direct RPC callers could bypass the composer. The executor settles the declaration itself.
|
||||
- **Generalize the command wire to a multimedia identifier** — rejected: the two identifiers are already attachment-generic, while the wire transports bytes and its image-specific fields state the admission rules the Host enforces. Files and videos lack shared admission and model-visible semantics, and an untagged multimedia identifier would not supply them. A second supported attachment kind is the reintroduction condition; the command envelope then widens to a tagged attachment union and commands declare the accepted kinds while retaining `AttachmentId`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- No command route can consume a submission's text and strand its images: the contract forces whole-envelope consumption or a visible refusal, for current and future commands alike.
|
||||
- The commands package now depends on `dsh-attachment` and `dsh-llm`, and `commands/execute` carries a required `images` wire parameter — every caller states its envelope explicitly.
|
||||
- `/goal` and `/plan` gain reference-image input at the cost of one extra logged user message (goal) and image blocks in the steered message (plan), including an image-only message for bare `/plan`; all are billed like any image prompt.
|
||||
- Menu-pick popup flows do not consult the envelope: picking a popup command from the menu while images are attached leaves the images visibly in the rail rather than refusing the interaction. Enter-submission is the enforced envelope boundary.
|
||||
- "A rejected batch publishes no durable object" covers exactly the pre-admission settlements (declaration, missing store, batch limit). A handler-level grammar rejection (`/goal pause` with images) and a post-admission cancellation settle AFTER the batch committed, leaving content-addressed objects without a referencing session event — harmless under sha256 dedup and the attachment store's deferred reference-aware GC, but not "no object was written".
|
||||
@@ -1,46 +0,0 @@
|
||||
# Agent Note: Command image-attachment envelope
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-17-command-image-attachment-envelope.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
Web composer 的一次提交是一个信封——草稿文本、已附加图片、投递模式——但两条提交平面对它的消费是不对称的。普通消息走 `defaultSink → conversation.sendSession`,图片被序列化进 prompt 内容并在成功后清除。被 claim 的斜杠命令走 `claim.submit(args, actx)`,一个纯文本事务:`/goal rebuild the cathedral` 带四张参考照片时,命令执行、草稿清空,图片却静默滞留在 composer 附件栏。模型从未看到它们,也没有任何界面提示。这个缺陷在契约层面而非某个漏掉的调用点:claim、裁决、宿主执行器都没有建模附件,因此任何命令都可能消费提交的文本一半而丢弃其余部分。
|
||||
|
||||
合并两个平面从未在考虑范围内——[插件命令注册 Agent Note](2026-07-19-plugin-command-registration.zh.md)刻意让人类命令留在模型平面之外,这个分离是正确的。问题在于信封在平面分叉处被拆散了。
|
||||
|
||||
## Decision
|
||||
|
||||
提交信封被端到端建模,每条命令路径要么整体消费它,要么响亮拒绝。
|
||||
|
||||
**声明。**`CommandDefinition.input.images: boolean`(缺省为 false)声明 composer 图片是否可以随调用提交。该标志随冻结的 `CommandDescriptor` 经 `commands/list` 到达每个客户端,进入铸造出的 `CommandClaim`(`images: true`),再进入输入状态机发布的 claim 快照。
|
||||
|
||||
**通用标识,图片专用载荷。**浏览器草稿与持久化引用已经使用 `DraftAttachmentId` 和 `AttachmentId`;命令 RPC 传输的是编码字节,而非图片标识。图片仍是唯一已经定义准入规则和模型块语义的非文本附件,因此 wire 保持 `EncodedImageAttachment[]`,声明保持 `input.images`。
|
||||
|
||||
**执行器强制。**`CommandRuntime.execute(agent, line, images, signal)` 携带本次提交的 base64 图片(来自 `@deepseek-ai/dsh-attachment/types` 的 `EncodedImageAttachment`)。强制执行声明的是执行器而非 composer:把图片发给未声明的命令、附件存储缺失、批量超限,都会在处理器运行前以记录在案的 `command/done` 错误结算。准入经由 attachment 包的 `admitEncodedImages`——共享 wire 入口,强制执行规范 base64 并把批量准入(限额、校验、有序提交)委托给 `AttachmentStore.saveImages`——使两个 wire 端点(prompt RPC 与命令执行器)共享同一序列,被拒绝的批量不会发布任何持久化对象。通过准入的批量以冻结的有序 `ImageBlock` 数组挂在 `invocation.attachments` 上交给处理器。
|
||||
|
||||
**模型可见性由生产方负责。**注册表自身绝不调度这些图片。`/goal` 在 create 或 edit 成功后通过 `agent.followup` 提交一条用户消息——图片块加固定文本 `Reference images for the goal objective.`——后续 Goal Round 从普通会话历史读取图片,goal 领域不存储附件状态。`/plan <message>` 把图片并入其 steer 的文本消息;不带参数的 `/plan` 则 steer 一条只含图片的用户消息,因为图片可能包含全部任务内容。不会发送模型输入的控制形式(`/goal pause`、`/plan off`)会直接返回错误,composer 的图片原地保留。plan 投影会把 `command/run` 视为候选选择,并在配对的 `command/done` 报错时丢弃它,因此被拒绝的带图 `/plan off` 不会留下待退出状态。
|
||||
|
||||
**composer 的拒绝是可见横幅,一切保留。**ui-commands 的 `matchEnter` 从裁决收到 `SubmitEnvelope`(图片数量),对每条无法消费图片的回车路径抛出本地化的 `notice.imagesUnsupported` 拒绝:contribution 弹窗、decoration 弹窗、未声明的 claim、bare 分离执行。输入状态机发布一条错误通知,composer 通过瞬态 Toast 横幅呈现它,草稿与图片不动。已 claim 状态下的提交(空格或菜单 claim)由 facade 用 `conversation` 命名空间的同款文案把关。接受路径上,facade 经 hub 的 `commandImages` 管道序列化草稿图片、传给 `claim.submit`,仅在成功 outcome 后清除并释放;错误结果(包括生产方的语法拒绝)保留它们。
|
||||
|
||||
## Testing
|
||||
|
||||
注册表执行器强制、准入失败结算、冻结的调用附件由 `packages/interaction/commands/tests/commands.spec.ts` 覆盖;批量准入顺序与限额在 `packages/attachment/attachment/tests/admission.spec.ts`;生产方行为在 `packages/goal/command-goal/tests/command-goal.spec.ts` 与 `packages/plan/plan-mode/tests/plan-mode.spec.ts`;客户端拒绝与消费路径在 ui-commands、ui-conversation、ui-input-trigger 客户端套件;组装后应用流程在 apps/web 的 keyless 通道。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **附加图片时一律拦截命令(没有接受路径)**——被拒绝:可预测,但带参考图的 `/goal` 正是驱动这次修复的用例,用户的图片将完全没有通往模型的路径。
|
||||
- **任何命令后把滞留图片自动作为后续用户消息发送**——被拒绝:对宿主状态命令(`/model`、`/compact`)令人意外,且把消息契约从生产方挪到 composer,违反命令注册表「生产方负责模型可见工作」的规则。
|
||||
- **在 goal 领域存储附件引用并渲染进 Round 提示词**——被拒绝:需要持久化 goal schema 变更,且要么把图片块复制进每轮提示词,要么引入仅首轮的提示词形态;round 提示词不变量将需要附件状态。一条普通的已记录用户消息达到同样的模型可见性。
|
||||
- **只要命令成功就消费图片,不管语法**——被拒绝:`/goal pause` 带图会把图片静默丢弃,在更深一层重演原始缺陷。消费与生产方的显式成功绑定,语法不匹配返回错误。
|
||||
- **只在客户端强制**——被拒绝:schema 省略不是强制执行;直接 RPC 调用方可以绕过 composer。执行器自己结算声明。
|
||||
- **把命令 wire 泛化成多媒体标识**——被拒绝:两个标识已经是附件通用类型,wire 传输的是字节,其图片专用字段明确表达了 Host 强制执行的准入规则。文件和视频尚无共同的准入规则与模型可见语义,一个不带类型标记的多媒体标识也无法提供这些信息。出现第二种受支持附件时再引入泛化:命令信封扩展为带类型标记的附件联合类型,命令声明接受的类型,`AttachmentId` 保持不变。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 任何命令路径都不可能消费提交的文本而滞留图片:契约强制整信封消费或可见拒绝,对现有与未来命令一体适用。
|
||||
- commands 包新增对 `dsh-attachment` 与 `dsh-llm` 的依赖,`commands/execute` 携带必填的 `images` wire 参数——每个调用方都显式陈述其信封。
|
||||
- `/goal` 与 `/plan` 获得参考图输入,代价是一条额外的已记录用户消息(goal)与 steer 消息中的图片块(plan),其中不带参数的 `/plan` 会产生只含图片的消息;所有这些输入的计费都与常规图片提示词相同。
|
||||
- 菜单点选的弹窗流程不查询信封:附有图片时从菜单点选弹窗命令,图片会可见地留在附件栏,而不是拒绝该交互。回车提交是被强制执行的信封边界。
|
||||
- 「被拒绝的批量不发布任何持久化对象」只覆盖准入前的三种结算(声明、存储缺失、批量超限)。handler 级语法拒绝(如 `/goal pause` 带图)与准入后取消发生在批量已提交之后,会留下没有会话事件引用的内容寻址对象——在 sha256 去重与附件存储延后的引用感知 GC 下无害,但并非「未写入任何对象」。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-26-generic-file-upload.md
|
||||
2026-08-26-generic-file-upload.md: d8643f5f1a3e0dcdfdc7fc8b79cbb156b07f4402
|
||||
2026-08-26-generic-file-upload.zh.md: 38de46a424e3f02b7c0293e15835d096b108f071
|
||||
@@ -0,0 +1,50 @@
|
||||
# Agent Note: Generic file upload
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-26-generic-file-upload.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Sessions accepted pasted or dropped images as durable attachments, but no other file kind could enter a conversation: the composer refused non-image bytes, and the only file affordance was the `@` path mention, which requires the file to already be readable from the host workspace. A user could not hand the agent a PDF, a data file, or an archive from a browser, and DeepSeek Chat users expect the paperclip-and-file-card upload flow (#2984).
|
||||
|
||||
The command plane had already established a whole-envelope rule for images: a command consumes the text and attachments together or visibly refuses the submission. Its `input.images` declaration and image-only RPC payload made generic files a separate refusal path even after ordinary messages could carry them. Plan and goal entry therefore needed the same attachment vocabulary without weakening executor enforcement or silently clearing a draft.
|
||||
|
||||
## Decision
|
||||
|
||||
Files and images use separate storage schemes and one ordered message attachment list. Images keep their normalized-attachment pipeline unchanged. Other picked files enter one FIFO background-upload queue and are stored byte-for-byte with no type or size limits, then staged in-process for the same Session. Equal bytes have one canonical object under `DSH_HOME/attachments/v1/file-objects/<digest-prefix>/<digest>`; each read-only model-facing path at `DSH_HOME/attachments/v1/files/<digest-prefix>/<digest>/<name>` is a hard link, so different display names do not duplicate content. The configurable queue defaults to two active transfers. The independent dual-face `file-upload` Cordis package owns transfer and staging. Its Client `fileUpload` service accepts the owning Session identity together with a `Blob`, exact bytes, or a one-shot `ReadableStream<Uint8Array>`; it uses that identity to assemble the raw route request or invoke the generated Remote directly. Its Host `fileUploads` service owns the streaming route, encoded Remote fallback, command receipt resolver, and receipt tables keyed by the receiving Agent's Session object. Encoded admission and attachment-error recognition go through `ctx.attachments`, whose provider owns byte storage. Session Controller registers the resolver for cold ordinary Agents and consumes receipts during prompt admission; Session objects do not expose file transfer. Served Web pages hand each active body to a dedicated upload Worker: Blob bodies use XMLHttpRequest for total-aware byte progress, while streams transfer ownership and feed Fetch incrementally. Worker-hosted pages transfer the body through their page-owned Fetch carrier to the Host Worker, which reads bounded chunks. The page thread never reads, base64-encodes, or JSON-serializes generic file bytes. The authenticated Host route opts into Connection's streaming request mode, so the bridge dispatches before consuming the body and the local store hashes and writes bounded chunks to a private staging object. Completion atomically publishes the content-addressed object; cancellation or failure removes the staging file. Upload operations and draft state belong to the resident conversation root, so navigation to another Session does not stop the transfer; returning to the original Session shows the same card and progress. Removing the file card skips its queued transfer or aborts its active transfer. The sent message carries a structured `FileBlock` (`{ name, bytes, attachmentId }`) inside `user/message`; no new session event type exists. Request assembly in `LlmRuntime` projects every file block, including nested tool-result occurrences, to one deterministic handle naming the file and its saved read-only path. The handle tells a main agent to include that path when delegating file work and to report when the child's execution environment cannot see it. No provider receives file bytes; the model reads the stored copy with existing file tools on demand.
|
||||
|
||||
Default mode, active Plan Mode, and an active goal share ordinary queue, follow-up, and steer attachment admission. `/goal` create and edit and `/plan` entry accept the same ordered image and file batches; attachment-bearing control subcommands reject before changing state. Command submissions cite completed staged-file receipts, so generic file bytes are not read or copied again. Session Controller resolves every file receipt to a durable reference before `ctx.attachments.admitPromptContent()` receives the complete ordered content list; attachment admission persists images and passes file references unchanged. The Host rejects upload completion after the original Agent is disposed and deduplicates prompt retries already identified by `rpcId`. Prompt receipts remain available through failure recovery, then retire after the accepted queue or history occurrence is observed; command-only receipts remain until Session disposal. Submission echoes register through `beginSubmission` before serialization, carry mixed attachments through `pendingSubmissions`, correlate by `rpcId`, retire once after queue or history observation, and keep drafts on failure. Before submission, the composer presents the ordered batch in one non-wrapping horizontal rail: images use 64 by 64 pixel thumbnails and generic files use 240 by 64 pixel cards with a 16 pixel radius, blue document glyph, filename plus extension and size, and a hover or keyboard removal action. QueueDock uses the same order with compact thumbnails and file cards. After submission, Chat presents the ordered batch in one right-aligned wrapping attachment flow. A lone image retains the large gallery presentation; a message with multiple attachments uses 64 by 64 pixel image tiles and 240 by 64 pixel file cards, so files and images share each row until the available width forces a wrap. Trajectory keeps the user-message preview compact and adds a localized generic-file count. Paperclip, drag, and paste classify by MIME; send waits for every file upload. Continuable subagent composers disable attachment intake, and the Host rejects any file block received for a child session.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Store uploads in the project root** (the OpenHands / ChatGPT `/mnt/data` shape). Rejected: files in the user's tree can be edited, moved, or deleted, which breaks the session log's stable reference, pollutes `git status`, and requires a workspace to exist. `DSH_HOME` keeps frozen read-only bytes with content addressing; execution-world visibility is served by the projected path and can gain a copy-into-workspace step later.
|
||||
- **A dedicated `read_file` tool.** Rejected: the handle line points at an ordinary path, so the existing `read` tool (and the model's other file tools) already covers it; a second read tool would split model behavior without adding capability.
|
||||
- **Eager content injection into the prompt.** Rejected for files exactly as it was for `@` mentions ([web file references](2026-07-27-web-file-and-session-references.md)): relevance is unknown at attach time, and lazy tool reads keep every content access logged.
|
||||
- **Type whitelist and size caps.** Rejected for now: DeepSeek Chat's whitelist exists because its server parses uploads, while this harness only stores bytes and lets the model read them. The streaming carrier and store keep memory proportional to bounded chunks, so a cap would govern disk and transfer policy rather than request safety.
|
||||
- **A new attachment/file session event.** Rejected: the block-inside-`user/message` pattern images already use satisfies model-visible ⟺ logged without widening the event vocabulary.
|
||||
- **Block every command while attachments are present.** Rejected: `/goal` objectives and `/plan` entry need reference files, so a global refusal would leave those files with no command route to the model.
|
||||
- **Automatically send attachments after any successful command.** Rejected: state commands such as `/model` and `/compact` do not imply model-visible input. The command producer owns whether an admitted batch becomes a user message.
|
||||
- **Store objective attachments in the goal domain.** Rejected: one ordinary logged user message gives later goal rounds the same history without widening the goal schema or duplicating attachments into round prompts.
|
||||
- **Consume attachments on any command success.** Rejected: `/goal pause` or `/plan off` would clear unrelated cards. Consumption follows the producer's explicit success; grammar forms that cannot use attachments return an error.
|
||||
- **Enforce declarations only in the client.** Rejected: direct RPC callers can bypass the composer. `CommandRuntime` enforces declaration, store availability, same-Session file-receipt resolution, image base64 admission, and image limits before entering the handler.
|
||||
- **Expose uploads through `ctx.connection` and pass that object through Session constructors.** Rejected: Connection does not own file transfer, and the intermediate object layers do not use the dependency. The independent upload service accepts an explicit Session identity and lets browser and Worker-hosted pages replace the carrier without widening Connection or Session.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Uploaded bytes are never deleted and carry no size limit, so `DSH_HOME` growth is unbounded; garbage collection stays deferred with the image-retention question.
|
||||
- The projected path is execution-environment-local: a sandboxed or remote filesystem that cannot map `DSH_HOME` yields an explicit no-path handle, and the model reports that it cannot read the file. A store-backed read fallback is deferred.
|
||||
- Staged uploads live in Host memory per Session; a Host restart between upload and send surfaces `FILE_NOT_STAGED` and the client re-adds the file.
|
||||
- The browser-to-Host transfer is one streaming HTTP request without resumable offsets; retrying after connection or Host failure retransmits the file from byte zero.
|
||||
- A `ReadableStream` upload consumes and transfers the stream once; retrying requires a newly created stream, and progress cannot report a total unless the producer supplies length through a future API.
|
||||
- The browser upload Worker is emitted from the string form of a self-contained function. Runtime imports require a standalone Worker entry bundled by tsdown.
|
||||
- Commands must declare attachment acceptance. Rejected commands preserve the text draft and every attachment card for retry.
|
||||
- Subagents do not upload files independently. A main agent delegates with the saved path; only same-machine or inherited-history children whose execution environment maps that path can read it.
|
||||
- Uploaded files do not appear in `@` completion yet; that integration is a planned later phase.
|
||||
- The command registry admits a tagged `CommandSubmitAttachment` union whose file member carries a staged receipt, then hands handlers one frozen ordered `ImageBlock | FileBlock` array. The registry never schedules model input; `/goal` adds one logged follow-up and `/plan` steers the ordered blocks.
|
||||
- Menu popup selection does not submit the composer envelope. Attachments remain visible until the user submits a command line or removes them.
|
||||
- Declaration, missing-store, unknown-receipt, and image-limit rejections occur before handler entry. A producer grammar rejection and cancellation after image admission may leave unreferenced content-addressed objects for deferred attachment garbage collection.
|
||||
|
||||
## Testing
|
||||
|
||||
Unit and integration coverage pins verbatim and streamed storage, name sanitization, a declared 2.19 GiB request passing through the streaming bridge without aggregate buffering, raw and RPC wire admission, Blob and transferable `ReadableStream` carriers, bounded background-upload concurrency, progress and cancellation, cross-Session upload residency, command file-receipt submission without a second byte read, native and PTC projection under read-only and workspace-write permissions, upload staging, ordered queue and steer submission, queue-to-steer conversion, pending echo retirement and failure recovery, active plan and goal intake, `/plan` and `/goal` mixed attachments, subagent refusal, composer and Chat attachment layouts, and Trajectory file summaries. The keyless `file-upload-round` snapshot records the browser upload, model file read, and rendered answer.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Agent Note: 通用文件上传
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-26-generic-file-upload.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
会话可以把粘贴或拖入的图片作为持久附件接收,但其他任何文件都进不了对话:composer 拒绝非图片字节,唯一与文件相关的入口是 `@` 路径引用,而它要求文件本来就能从宿主工作区读到。用户无法从浏览器把 PDF、数据文件或压缩包交给智能体,而 DeepSeek Chat 用户期待回形针加文件卡的上传交互(#2984)。
|
||||
|
||||
命令平面已经为图片建立了完整提交规则:命令必须同时消费文本与附件,或明确拒绝整次提交。`input.images` 声明和只支持图片的 RPC 载荷使通用文件在普通消息可用后仍走独立拒绝路径。Plan 和 goal 入口需要使用同一附件词汇,同时保留执行器强制规则,不能静默清除草稿。
|
||||
|
||||
## 决定
|
||||
|
||||
文件与图片使用不同存储方案,并进入同一个有序消息附件列表。图片的规范化附件流水线保持不变。其他被选中的文件进入同一个先进先出的后台上传队列,按字节原样保存且不设类型与大小限制,再在本进程内按同一 Session 暂存。相同字节在 `DSH_HOME/attachments/v1/file-objects/<digest-prefix>/<digest>` 下只有一个规范对象;每条模型可见的只读路径 `DSH_HOME/attachments/v1/files/<digest-prefix>/<digest>/<name>` 都是硬链接,因此不同显示名称不会复制内容。该队列可以配置,默认同时运行两项传输。独立的双端 `file-upload` Cordis 包拥有传输与暂存。其 Client `fileUpload` 服务同时接收所属 Session 标识与 `Blob`、精确字节或只能使用一次的 `ReadableStream<Uint8Array>`;它使用该标识组装原始路由请求,或直接调用生成的 Remote。其 Host `fileUploads` 服务拥有流式路由、编码 Remote 兜底、命令凭证解析器,以及以接收方 Agent 的 Session 对象为键的凭证表。编码准入和附件错误识别通过 `ctx.attachments` 完成,字节存储由附件提供方拥有。Session Controller 注册用于休眠普通 Agent 的解析器,并在 prompt 准入时消费凭证;Session 对象不公开文件传输。普通 Web 页面把每个活动请求体交给专用上传 Worker:Blob 请求体通过 XMLHttpRequest 发送并报告包含总量的字节进度,stream 则转移所有权并增量传入 Fetch。Worker-hosted 页面通过页面自有 Fetch 载体把请求体转交给 Host Worker,后者读取有界分片。页面线程不读取通用文件字节,也不做 base64 编码或 JSON 序列化。经过认证的 Host 路由显式使用 Connection 的流式请求模式,因此 bridge 会在消费请求体前分发,本地存储则把有界分片写入私有暂存对象并同时计算摘要。接收完成后,内容寻址对象以原子方式发布;取消或失败会移除暂存文件。上传任务和草稿状态属于常驻的 conversation 根,因此切到另一条 Session 不会停止传输,返回原 Session 时仍显示同一张文件卡和当前进度。移除文件卡会跳过排队中的传输或中止正在运行的传输。发送的消息在 `user/message` 里携带结构化的 `FileBlock`(`{ name, bytes, attachmentId }`),不新增会话事件类型。`LlmRuntime` 的请求组装把每个文件块,包括嵌套工具结果中的文件块,投影成确定性 handle 文本,指出文件与其只读保存路径。handle 会要求主 agent 委派文件任务时附上该路径,并在子级执行环境看不到路径时明确报告。提供方不会收到文件字节,模型在需要时用现有文件工具读取存储副本。
|
||||
|
||||
默认模式、激活的 Plan Mode 与 active goal 共用普通 queue、follow-up 和 steer 的附件准入。`/goal` create 和 edit 以及 `/plan` 进入接受同一套有序图片与文件批量;携带附件的控制子命令会在状态变更前拒绝。命令提交引用已完成暂存的文件凭证,不会再次读取或复制通用文件字节。Session Controller 先把每个文件凭证解析为持久引用,再由 `ctx.attachments.admitPromptContent()` 接收完整有序内容列表;附件准入会持久化图片,并让文件引用原样通过。原 Agent 已销毁时,Host 会拒绝发布上传完成凭证,并按 `rpcId` 去重已经存在的 prompt 重试。prompt 凭证在失败恢复期间保持可用,已接受的 queue 或历史 occurrence 被观察后才退休;只被命令使用的凭证保留到 Session 销毁。提交回显在序列化前经 `beginSubmission` 注册,通过 `pendingSubmissions` 携带混合附件,以 `rpcId` 关联,在 queue 或历史观察后只退休一次,并在失败时保留草稿。发送前,composer 把有序附件放进同一条不换行的横向附件栏:图片使用 64 乘 64 像素缩略图,通用文件使用 240 乘 64 像素卡片,带 16 像素圆角、蓝色文档图标、文件名加扩展名与大小,以及悬停或键盘操作时可用的移除按钮。QueueDock 使用相同顺序以及紧凑的缩略图和文件卡。发送后,Chat 把有序附件放进同一个右对齐、可换行的附件区域。只有一张图片时保留图片画廊的大图样式;一条消息含有多个附件时,图片使用 64 乘 64 像素缩略图,文件使用 240 乘 64 像素卡片,文件与图片在可用宽度内共用一行,空间不足时再换行。Trajectory 保持紧凑的用户消息预览,并增加本地化的通用文件数量。回形针、拖拽和粘贴按 MIME 分类;发送会等待每个文件上传完成。continuable 子代理 composer 禁用附件入口,Host 会拒绝收到的任何子会话文件块。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
- **把上传存进项目根目录**(OpenHands / ChatGPT `/mnt/data` 的形态)。拒绝:用户目录里的文件可能被编辑、移动或删除,会打断会话日志的稳定引用,污染 `git status`,还要求工作区必须存在。`DSH_HOME` 用内容寻址保存冻结的只读字节;执行世界可见性由投影路径提供,之后还可以补一步拷贝进工作区。
|
||||
- **专用的 `read_file` 工具。** 拒绝:handle 文本指向一条普通路径,现有 `read` 工具(以及模型的其他文件工具)已经覆盖它;再加一个读工具只会分裂模型行为而不增加能力。
|
||||
- **把内容急切注入提示词。** 对文件的拒绝理由与当年对 `@` 引用完全相同([web 文件引用](2026-07-27-web-file-and-session-references.zh.md)):附加时相关性未知,惰性工具读取让每次内容访问都留在日志里。
|
||||
- **类型白名单与大小上限。** 现阶段拒绝:DeepSeek Chat 的白名单存在是因为其服务端要解析上传,而本 harness 只存字节、让模型自己读。流式载体和存储让内存占用与有界分块大小相关,因此上限属于磁盘与传输策略,不用于保证请求安全。
|
||||
- **新增 attachment/file 会话事件。** 拒绝:图片已经采用的「块内联在 `user/message`」模式即可满足模型可见 ⟺ 可日志重建,无需扩大事件词汇。
|
||||
- **有附件时阻止所有命令。** 拒绝:`/goal` 目标与 `/plan` 进入需要参考文件,统一拒绝会使这些文件没有进入模型的命令路径。
|
||||
- **任何命令成功后自动发送附件。** 拒绝:`/model` 与 `/compact` 等状态命令不表示模型可见输入。附件是否成为用户消息由命令生产方负责。
|
||||
- **把目标附件存进 goal 领域。** 拒绝:一条普通的已记录用户消息就能让后续 Goal Round 获得相同历史,无需扩大 goal schema 或把附件复制进 Round 提示词。
|
||||
- **任何命令成功都消费附件。** 拒绝:`/goal pause` 或 `/plan off` 会清除无关卡片。只有生产方明确成功才消费附件;无法使用附件的语法形式返回错误。
|
||||
- **只在客户端执行声明。** 拒绝:直接 RPC 调用方可以绕过 composer。`CommandRuntime` 在处理器运行前强制检查声明、存储可用性、同一 Session 的文件凭证解析、图片 base64 准入与图片限制。
|
||||
- **通过 `ctx.connection` 暴露上传并沿 Session 构造器传递该对象。** 拒绝:Connection 不拥有文件传输,中间对象层也不使用这项依赖。独立上传服务直接接收 Session 标识,并允许普通浏览器与 Worker-hosted 页面替换载体,无需扩大 Connection 或 Session。
|
||||
|
||||
## 后果
|
||||
|
||||
- 上传字节永不删除且没有大小上限,`DSH_HOME` 的增长无界;垃圾回收与图片保留问题一同继续挂起。
|
||||
- 投影路径只在对应执行环境中有效:无法映射 `DSH_HOME` 的沙箱或远程文件系统会得到显式的无路径 handle,模型会报告无法读取该文件。基于存储的读取兜底被推迟。
|
||||
- 暂存上传按 Session 存在 Host 内存里;上传与发送之间 Host 重启会出现 `FILE_NOT_STAGED`,客户端重新添加文件即可。
|
||||
- 浏览器到 Host 的传输使用一次不带断点续传偏移的流式 HTTP 请求;连接或 Host 失败后的重试会从第一个字节重新传输整个文件。
|
||||
- `ReadableStream` 上传只消费并转移一次 stream;重试必须重新创建 stream,而且在未来 API 允许生产方提供长度前,进度不能报告总量。
|
||||
- 浏览器上传 Worker 由自包含函数的字符串形式生成。需要运行时 import 时,必须改用由 tsdown 打包的独立 Worker 入口。
|
||||
- 命令必须声明接受附件。命令拒绝时保留文本草稿与全部附件卡,供用户重试。
|
||||
- 子代理不独立上传文件。主 agent 委派时传递保存路径;只有同机或继承父级历史且执行环境能映射该路径的子级可以读取。
|
||||
- 上传的文件尚未进入 `@` 补全;该联动是计划中的后续阶段。
|
||||
- 命令注册表准入带类型标记的 `CommandSubmitAttachment` 联合类型,其中的文件成员携带暂存凭证,再向处理器提供一个冻结的有序 `ImageBlock | FileBlock` 数组。注册表不安排模型输入;`/goal` 增加一条已记录 follow-up,`/plan` steer 有序附件块。
|
||||
- 从菜单选择弹窗命令不会提交 composer 的整套内容。附件保持可见,直到用户提交命令行或移除附件。
|
||||
- 声明、存储缺失、未知凭证与图片限制拒绝发生在处理器运行前。生产方语法拒绝和图片准入后的取消可能留下无引用的内容寻址对象,由后续附件垃圾回收处理。
|
||||
|
||||
## 测试
|
||||
|
||||
单元与集成覆盖原样与流式存储、文件名清洗、声明为 2.19 GiB 的请求通过流式 bridge 且不发生总量缓冲、原始字节与 RPC wire 准入、Blob 与可转移 `ReadableStream` 载体、后台上传并发上限、进度与取消、跨 Session 上传常驻、命令通过文件凭证提交且不再次读取字节、read-only 与 workspace-write 权限下的 native 和 PTC 投影、上传暂存、有序 queue 与 steer 提交、队列转 steer、pending 回显退休与失败恢复、active plan 和 goal 的附件入口、`/plan` 与 `/goal` 混合附件、子代理拒绝、composer 与 Chat 附件布局,以及 Trajectory 文件摘要。keyless `file-upload-round` 快照记录浏览器上传、模型读取文件与答案呈现。
|
||||
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.md
|
||||
2026-08-28-web-connection-recovery-control.md: 6fec265c8e166836a5ab9413f1612cdaa6461a1d
|
||||
2026-08-28-web-connection-recovery-control.zh.md: e45119b272c297a783a650b71743e4f81c1a1565
|
||||
2026-08-28-web-connection-recovery-control.md: 649c840b20450d0282d707b50902c5d82317f54c
|
||||
2026-08-28-web-connection-recovery-control.zh.md: 5d68c6acff96b23960f0ec60f54b56a98e70e74f
|
||||
@@ -10,17 +10,17 @@ The Web Client automatically rebuilt its Remote event generation and physical We
|
||||
|
||||
## Decision
|
||||
|
||||
The Host sends WebSocket Ping control frames every two seconds by default through the existing validated `websocketHeartbeatIntervalMs` configuration. Before each Ping it marks the socket as awaiting Pong; a socket still awaiting Pong at the next interval is terminated. `ConnectionController` is the sole retry scheduler. Online transport failures enter jittered exponential backoff whose cap starts at 500ms, doubles through 1s, 2s, 4s, and 8s, and stops growing at 10s; the actual delay is 50–100% of the cap. The failed retry in the 10s tier ends automatic recovery and publishes `disconnected`. Each physical retry publishes `connecting`, writes one `retry #N` warning, asks Gateway mux to replace any candidate or active socket exactly once, and reopens the internal `$events` stream.
|
||||
The Host sends WebSocket Ping control frames every two seconds by default through the existing validated `websocketHeartbeatIntervalMs` configuration. Before each Ping it marks the socket as awaiting Pong; a socket still awaiting Pong at the next interval is terminated. `ConnectionController` is the sole retry scheduler. Online transport failures enter jittered exponential backoff whose cap starts at 500ms, doubles through 1s, 2s, 4s, and 8s, and stops growing at 10s; the actual delay is 50–100% of the cap. The [continuous recovery decision](../bug-fix/2026-09-05-continuous-client-recovery.md) supersedes this note's finite retry policy: attempts continue at the capped interval, and handshake readiness has a hard deadline. Each physical retry publishes `connecting`, writes one `retry #N` warning, asks Gateway mux to replace any candidate or active socket exactly once, and reopens the internal `$events` stream.
|
||||
|
||||
The Client Connection service exposes the identity-stable `ctx.connection.state` observable and `ctx.connection.reconnect()`. Its snapshot is undefined until the first connection outcome, then carries `disconnected`, `connecting`, or `connected`; equivalent states do not notify. Manual reconnect interrupts the current generation or retry delay, resets the attempt number, and starts retry 1 immediately through the same physical and logical path as automatic recovery. The browser's `offline` event immediately aborts active connection work, publishes `disconnected`, and suspends automatic retries. The next `online` transition publishes `connecting`, resets the attempt number, and starts again at the 500ms backoff tier; duplicate events do not create another loop. A fresh `$events` ready frame, rather than `navigator.onLine`, proves Host connectivity. Logical streams continue to own their baseline, cursor, and replay semantics after the replacement generation.
|
||||
|
||||
The [Web Client architecture](../architecture/2026-07-19-gui-web-client-architecture.md), [Remote event delivery](../architecture/2026-08-10-remote-event-delivery.md), and [Session event transport](../architecture/2026-08-18-session-history-and-event-transport.md) retain their broader ownership decisions; this note supersedes only their former retry timing.
|
||||
|
||||
The Settings shell is a recovery-specific consumer and therefore injects Connection directly; ordinary feature code continues to use `ctx.remote`. Its private hooks compartment binds the state observable and reconnect command. The expanded sidebar renders `ConnectionIndicator` immediately to the right of Settings: `disconnected` is a pale-yellow **Disconnected** action, `connecting` stays yellow while one to three dots advance every 500ms independently of retry timing, and a recovered connection displays pale-green **Connected** for two seconds. Hover or keyboard focus on either yellow state changes only the text to **Reconnect now**; press feedback uses a small warning-color transition, and no native title tooltip is present. Every visible state reserves the widest localized label and uses fixed icon and left-aligned text columns, so state changes do not move or resize the control. Initial startup and uninterrupted healthy operation render nothing.
|
||||
The Settings shell is a recovery-specific consumer and therefore injects Connection directly; ordinary feature code continues to use `ctx.remote`. Its private hooks compartment binds the state observable and reconnect command. The expanded sidebar renders `ConnectionIndicator` immediately to the right of Settings: `disconnected` is a pale-yellow **Disconnected** action, `connecting` displays **Reconnecting** in yellow while one to three dots advance every 500ms independently of retry timing, and a recovered connection displays pale-green **Connected** for two seconds. Hover or keyboard focus on either yellow state changes only the text to **Reconnect now**; press feedback uses a small warning-color transition, and no native title tooltip is present. Every visible state reserves the widest localized label and uses fixed icon and left-aligned text columns, so state changes do not move or resize the control. Initial startup and uninterrupted healthy operation render nothing.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Retry every two seconds without a terminal state.** Rejected because a long outage would create continuous connection traffic. The retained exponential policy retries quickly at first, becomes progressively quieter, and leaves a stable recovery action after the 10s tier fails.
|
||||
**Retry every two seconds without a terminal state.** Rejected because a long outage would create continuous connection traffic. The retained exponential policy retries quickly at first, becomes progressively quieter, and retains the recovery action during retries. The continuous recovery decision governs retries after the cap is reached.
|
||||
|
||||
**Render a full-width `ConnectionBanner` at the top of the viewport.** Rejected because the status belongs beside the recovery action the user named, and a global overlay consumes unrelated page chrome. The primitive is the inline `ConnectionIndicator`; no `ConnectionBanner` compatibility export exists before the first tagged release.
|
||||
|
||||
@@ -30,7 +30,7 @@ The Settings shell is a recovery-specific consumer and therefore injects Connect
|
||||
|
||||
## Consequences
|
||||
|
||||
Idle browser connections generate more frequent heartbeat traffic than the former default, while long outages stop generating connection attempts after the capped retry fails. Deployments may override the Host Ping interval. Gateway mux owns no second retry timer, so every `retry #N` warning corresponds to one Controller-requested physical attempt.
|
||||
Idle browser connections generate more frequent heartbeat traffic than the former default, while long outages retain capped connection attempts under the continuous recovery decision. Deployments may override the Host Ping interval. Gateway mux owns no second retry timer, so every `retry #N` warning corresponds to one Controller-requested physical attempt.
|
||||
|
||||
A manual reconnect intentionally disrupts every logical Remote stream sharing the physical socket. Their existing generation supervisors restore state through fresh baselines or cursors, and one-way notifications remain non-replayed.
|
||||
|
||||
@@ -38,4 +38,4 @@ The connection state and browser-network input stay in the React-free transport
|
||||
|
||||
## Testing
|
||||
|
||||
Connection and Gateway tests pin the two-second heartbeat and Pong deadline, exponential retry limits and logs, browser offline suspension and online reset, manual sequence reset, one socket replacement per requested attempt, state deduplication, listener isolation, and disposal. Component tests pin healthy-state absence, hover/action copy, the independent dot animation, click behavior, and the two-second success state. The assembled Web test drives browser offline/online transitions, failed WebSocket attempts, stable indicator geometry, manual recovery, and the success confirmation through the shipped application.
|
||||
Connection and Gateway tests pin the two-second heartbeat and Pong deadline, exponential retry caps and logs, browser offline suspension and online reset, manual sequence reset, one socket replacement per requested attempt, state deduplication, listener isolation, and disposal. Component tests pin healthy-state absence, hover/action copy, the independent dot animation, click behavior, and the two-second success state. The assembled Web test drives browser offline/online transitions, failed WebSocket attempts, stable indicator geometry, manual recovery, and the success confirmation through the shipped application.
|
||||
@@ -10,17 +10,17 @@ Web Client 会在故障后自动重建 Remote event generation 与物理 WebSock
|
||||
|
||||
## Decision
|
||||
|
||||
Host 默认通过既有且经过校验的 `websocketHeartbeatIntervalMs` 配置,每 2 秒发送一次 WebSocket Ping 控制帧。每次 Ping 前,它把 socket 标记为等待 Pong;到下一间隔仍未收到 Pong 的 socket 会被终止。`ConnectionController` 是唯一的 retry 调度器。在线状态下的传输失败进入带抖动的指数退避:上限从 500ms 开始,依次翻倍为 1s、2s、4s、8s,最终封顶 10s;实际延迟是上限的 50%–100%。10s 档的 retry 仍失败后,自动恢复结束并发布 `disconnected`。每次物理 retry 都发布 `connecting`、写一条 `retry #N` warning、要求 Gateway mux 恰好一次替换候选或活动 socket,再重开内部 `$events` stream。
|
||||
Host 默认通过既有且经过校验的 `websocketHeartbeatIntervalMs` 配置,每 2 秒发送一次 WebSocket Ping 控制帧。每次 Ping 前,它把 socket 标记为等待 Pong;到下一间隔仍未收到 Pong 的 socket 会被终止。`ConnectionController` 是唯一的 retry 调度器。在线状态下的传输失败进入带抖动的指数退避:上限从 500ms 开始,依次翻倍为 1s、2s、4s、8s,最终封顶 10s;实际延迟是上限的 50%–100%。[持续恢复决策](../bug-fix/2026-09-05-continuous-client-recovery.zh.md)取代本笔记的有限重试策略:达到间隔上限后仍继续尝试,握手就绪设有硬期限。每次物理 retry 都发布 `connecting`、写一条 `retry #N` warning、要求 Gateway mux 恰好一次替换候选或活动 socket,再重开内部 `$events` stream。
|
||||
|
||||
Client Connection 服务暴露 identity 稳定的 `ctx.connection.state` observable 与 `ctx.connection.reconnect()`。snapshot 在首次连接结果前为 undefined,此后为 `disconnected`、`connecting` 或 `connected`;等价状态不触发通知。手动重连会中断当前 generation 或重试等待、重置 attempt 序号,并通过与自动恢复相同的物理和逻辑路径立即开始 retry 1。浏览器的 `offline` 事件会立即中断活动连接工作、发布 `disconnected` 并暂停自动 retry;下一次 `online` 转换会发布 `connecting`、重置 attempt 序号,并从 500ms 退避档重新开始;重复事件不会创建另一条循环。Host 是否可达由新的 `$events` ready 帧证明,而不是由 `navigator.onLine` 证明。替换 generation 建立后,各 logical stream 仍自行持有 baseline、cursor 与 replay 语义。
|
||||
|
||||
[Web Client 架构](../architecture/2026-07-19-gui-web-client-architecture.zh.md)、[Remote 事件投递](../architecture/2026-08-10-remote-event-delivery.zh.md)和[会话事件传输](../architecture/2026-08-18-session-history-and-event-transport.zh.md)继续持有各自更宽的所有权决策;本笔记只取代其中原有的重试时序。
|
||||
|
||||
Settings 外壳是恢复功能专用消费方,因此直接注入 Connection;普通功能代码仍使用 `ctx.remote`。它的私有 hooks compartment 绑定状态 observable 与重连命令。展开的侧边栏在 Settings 右侧渲染 `ConnectionIndicator`:`disconnected` 是浅黄色的**连接异常**操作;`connecting` 保持黄色,其中一至三个点每 500ms 前进一次,与 retry 时序无关;恢复后则以浅绿色显示**连接成功**并驻留 2 秒。鼠标悬浮或键盘聚焦任一黄色状态时只把文字改为**立即重连**;按压反馈采用轻微的警告色过渡,不使用原生 title tooltip。所有可见状态都为最宽的本地化文字预留空间,并使用固定的图标列和左对齐文字列,因此状态变化不会移动控件或改变其宽度。首次启动和未曾中断的健康连接都不渲染。
|
||||
Settings 外壳是恢复功能专用消费方,因此直接注入 Connection;普通功能代码仍使用 `ctx.remote`。它的私有 hooks compartment 绑定状态 observable 与重连命令。展开的侧边栏在 Settings 右侧渲染 `ConnectionIndicator`:`disconnected` 是浅黄色的**连接异常**操作;`connecting` 以黄色显示**自动重连中**,其中一至三个点每 500ms 前进一次,与 retry 时序无关;恢复后则以浅绿色显示**连接成功**并驻留 2 秒。鼠标悬浮或键盘聚焦任一黄色状态时只把文字改为**立即重连**;按压反馈采用轻微的警告色过渡,不使用原生 title tooltip。所有可见状态都为最宽的本地化文字预留空间,并使用固定的图标列和左对齐文字列,因此状态变化不会移动控件或改变其宽度。首次启动和未曾中断的健康连接都不渲染。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**固定每 2 秒重试且不进入终态。**不采用,因为长时间故障会持续产生连接流量。保留的指数策略先快速重试,再逐步降低频率,并在 10s 档失败后留下稳定的恢复操作。
|
||||
**固定每 2 秒重试且不进入终态。**不采用,因为长时间故障会持续产生连接流量。保留的指数策略先快速重试,再逐步降低频率,并在重试期间保留恢复操作。达到间隔上限后的重试由持续恢复决策规定。
|
||||
|
||||
**在视口顶部渲染全宽 `ConnectionBanner`。**不采用,因为状态应放在用户指定的恢复操作旁,全局覆盖层还会占用无关页面界面框架。该原语是内联 `ConnectionIndicator`;首次标签发布前不存在 `ConnectionBanner` 兼容导出。
|
||||
|
||||
@@ -30,7 +30,7 @@ Settings 外壳是恢复功能专用消费方,因此直接注入 Connection;
|
||||
|
||||
## Consequences
|
||||
|
||||
空闲浏览器连接的心跳流量会高于原默认值;长时间故障则在封顶档 retry 失败后停止产生连接尝试。部署仍可覆盖 Host Ping 间隔。Gateway mux 不拥有第二个 retry timer,因此每条 `retry #N` warning 都对应一次由 Controller 请求的物理尝试。
|
||||
空闲浏览器连接的心跳流量会高于原默认值;长时间故障则按持续恢复决策保留间隔封顶的连接尝试。部署仍可覆盖 Host Ping 间隔。Gateway mux 不拥有第二个 retry timer,因此每条 `retry #N` warning 都对应一次由 Controller 请求的物理尝试。
|
||||
|
||||
手动重连会刻意中断共享物理 socket 的全部 logical Remote stream。它们既有的 generation supervisor 会通过新 baseline 或 cursor 恢复状态;单向通知仍不重放。
|
||||
|
||||
@@ -38,4 +38,4 @@ Settings 外壳是恢复功能专用消费方,因此直接注入 Connection;
|
||||
|
||||
## Testing
|
||||
|
||||
Connection 与 Gateway 测试固定 2 秒心跳及 Pong deadline、指数 retry 上限与日志、浏览器离线暂停和在线重置、手动重置序列、每次请求只替换一个 socket、状态去重、listener 隔离与 dispose。组件测试固定健康状态下不显示、悬浮与操作文案、独立点动画、点击行为与 2 秒成功状态。组装 Web 测试通过随附浏览器应用驱动浏览器 offline/online 转换、失败的 WebSocket 尝试、稳定的指示器几何、手动恢复与成功确认。
|
||||
Connection 与 Gateway 测试固定 2 秒心跳及 Pong deadline、指数 retry 间隔上限与日志、浏览器离线暂停和在线重置、手动重置序列、每次请求只替换一个 socket、状态去重、listener 隔离与 dispose。组件测试固定健康状态下不显示、悬浮与操作文案、独立点动画、点击行为与 2 秒成功状态。组装 Web 测试通过随附浏览器应用驱动浏览器 offline/online 转换、失败的 WebSocket 尝试、稳定的指示器几何、手动恢复与成功确认。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md
|
||||
2026-09-04-web-clickable-link-styles.md: 8781990a40de30e26d0c59c0ecc1a08ba41643ac
|
||||
2026-09-04-web-clickable-link-styles.zh.md: 7b5fde4c87319f6ae34b76d1c8e712e6f9f18392
|
||||
@@ -0,0 +1,34 @@
|
||||
# Agent Note: Web clickable-link language — link alias, dotted hover underline, category glyphs
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-09-04-web-clickable-link-styles.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Clickable artifact links in the chat transcript wore four different costumes: markdown anchors and prose file mentions were business-primary blue with a solid hover underline, web search/fetch links matched that pair, produced-file chips were grey pills (label-secondary text on interactive-bg-hover, 96px max width), and workflow member links carried a resting solid underline. Nothing marked what a link opens (browser, host app, Finder, in-app view), and link color was coupled to `--dsw-alias-state-business-primary`, which also drives focus rings and state dots, so tuning link color risked unrelated surfaces.
|
||||
|
||||
## Decision
|
||||
|
||||
One link language across the transcript's clickable-link surfaces — markdown anchors (including reference links, mailto, and URL-promoted inline code), prose file mentions, web search source links and the fetch URL, produced-file chips, and workflow member links:
|
||||
|
||||
- Color comes through a dedicated `--dsw-alias-link` alias in `design-platform.css` (light `deepseek-500`, dark `deepseek-400`), decoupled from `state-business-primary`; links render at `font-weight: 500` with no underline at rest and `underline dotted` at 3px offset on hover/focus.
|
||||
- A leading category glyph — the new `LinkIcon` in ui-primitives with kinds `url` (globe), `folder`, `code`, `image`, `document`, and `other` (paper) — renders `currentColor` only; `classifyLinkPath` derives the file kinds from the extension, and code, web, and data extensions share the code glyph by design. Two anchor shapes carry no glyph: workflow member links (an in-app member view fits no file or URL category) and anchors wrapping only images (a badge or thumbnail — a dangling globe beside the picture leads no text). Inline glyphs sit at 1.1em with a −0.25em baseline offset; the flex-centered produced-file glyphs instead nudge 1.2px down because the 22px text box carries its glyphs below box center.
|
||||
- Produced-file chips drop the grey pill and the 96px cap: plain link-blue text at natural width that shrinks with ellipsis only when the row overflows; the container-query bands still budget 96px per chip when choosing how many chips to show.
|
||||
- Deliberately untouched: ToolRow's grey dotted file links, and the grey "Show in folder" action (it gains the folder glyph but keeps its grey style).
|
||||
- In the same pass, the inline-code chip tint moved from `neutral-bluish-100` to `neutral-50` (dark: `neutral-800`) and gained a 0.5px l1 border.
|
||||
|
||||
Coverage: a LinkIcon unit spec (one distinct glyph per kind, classification table), refreshed markdown-dom fixtures, and the `clickable-links-gallery` web e2e — one settled keyless turn rendering every clickable link form — registered in the host compiler face (`tsconfig.host.json`) like its other scaffold-importing siblings.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Colored Word/Excel/PPT/PDF brand glyphs.** Implemented, then removed: fixed brand fills break the icon set's currentColor-only rule, so those extensions fold into the single outline `document` glyph.
|
||||
- **Per-extension icons.** Collapsed to six categories: more glyphs than the eye can parse at 14px adds noise, and per-site favicons remain possible later behind the same `url` category.
|
||||
- **Keeping links on `state-business-primary`.** Darker link blues (blue-600/650/700 were auditioned and reverted) would have dragged focus rings and state dots along; the dedicated alias localizes any future tuning to one line.
|
||||
- **Glyphs on ToolRow path links.** Rejected: tool rows keep their quieter grey dotted affordance, and leading glyphs there would stack icons in already dense rows.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A new clickable artifact surface should consume `--dsw-alias-link` and the LinkIcon vocabulary rather than introduce another color or underline form; the rule lives in [docs/web-styling.md](../../../../docs/web-styling.md).
|
||||
- Long produced-file names take their natural width; when a row overflows, flex shrinks all chips proportionally, so several long names shrink together instead of the last one yielding first.
|
||||
- mailto links currently share the `url` globe; a distinct mail category is a one-line addition if ever wanted.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Agent Note: Web 可点击链接语言——链接别名、hover 点状下划线、分类图标
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-09-04-web-clickable-link-styles.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
会话记录里的可点击产物链接有四套互不一致的样式:Markdown 锚点和正文文件引用是 business-primary 蓝加 hover 实线下划线,网页搜索/抓取链接与之相同,产物 chips 是灰色药丸(interactive-bg-hover 底上的 label-secondary 文字,96px 最大宽度),workflow 成员链接则带常驻实线下划线。没有任何标记说明链接点开后去哪儿(浏览器、宿主应用、Finder、应用内视图),而且链接颜色耦合在 `--dsw-alias-state-business-primary` 上——它同时驱动焦点环和状态点,调链接色会波及无关表面。
|
||||
|
||||
## 决策
|
||||
|
||||
会话记录的可点击链接表面——Markdown 锚点(含引用式链接、mailto、被提升为链接的 inline code)、正文文件引用、网页搜索来源链接与抓取 URL、产物 chips、workflow 成员链接——统一为一套链接语言:
|
||||
|
||||
- 颜色经由 `design-platform.css` 中专用的 `--dsw-alias-link` 别名(亮色 `deepseek-500`,暗色 `deepseek-400`),与 `state-business-primary` 解耦;链接以 `font-weight: 500` 呈现,默认无下划线,hover/focus 时为 3px offset 的 `underline dotted`。
|
||||
- 前置分类图标——ui-primitives 新增的 `LinkIcon`,kind 为 `url`(地球)、`folder`、`code`、`image`、`document`、`other`(纸张)——只渲染 `currentColor`;`classifyLinkPath` 按扩展名推导文件类别,代码、网页、数据扩展名按设计共用 code 图形。两类锚点不带图标:workflow 成员链接(应用内成员视图不属于任何文件或 URL 类别)和只包图片的锚点(徽章或缩略图——图片旁悬着的地球没有可引导的文字)。行内图标为 1.1em、基线偏移 −0.25em;flex 居中的产物图标则下移 1.2px,因为 22px 文字盒的字形低于盒中心。
|
||||
- 产物 chips 去掉灰色药丸和 96px 上限:纯链接蓝文字按自然宽度展示,仅当整行溢出时才收缩出省略号;容器查询档位在决定展示几个 chip 时仍按每个 96px 预算。
|
||||
- 刻意不动:ToolRow 的灰色点线文件链接,以及灰色的「在文件夹中显示」操作(它获得文件夹图标但保持灰色样式)。
|
||||
- 同一批次中,inline code 底色从 `neutral-bluish-100` 换到 `neutral-50`(暗色:`neutral-800`),并新增 0.5px l1 描边。
|
||||
|
||||
覆盖:LinkIcon 单测(每个 kind 一个独立图形、分类表)、刷新后的 markdown-dom 夹具,以及 `clickable-links-gallery` web e2e——一个 settled 的 keyless 回合渲染全部可点击链接形态——像其他引 scaffold 的同类一样注册进 host 编译面(`tsconfig.host.json`)。
|
||||
|
||||
## 备选方案
|
||||
|
||||
- **彩色 Word/Excel/PPT/PDF 品牌图形。** 实现后又移除:固定品牌填充违反图标集 currentColor-only 规则,这些扩展名并入单一的 outline `document` 图形。
|
||||
- **每个扩展名一个图标。** 收敛为六个类别:14px 下超出肉眼可分辨数量的图形只会增加噪音,按站点的 favicon 以后仍可在同一 `url` 类别之下引入。
|
||||
- **链接继续用 `state-business-primary`。** 更深的链接蓝(试过 blue-600/650/700 又回退)会连带焦点环和状态点;专用别名把未来的调色收敛到一行。
|
||||
- **给 ToolRow 路径链接加图形。** 否决:工具行保持更安静的灰色点线示能,在已经很密的行里加前置图形会造成图标堆叠。
|
||||
|
||||
## 后果
|
||||
|
||||
- 新的可点击产物表面应消费 `--dsw-alias-link` 和 LinkIcon 词汇,而不是引入另一种颜色或下划线形态;规则记录在 [docs/web-styling.md](../../../../docs/web-styling.zh.md)。
|
||||
- 长产物文件名按自然宽度展示;整行溢出时 flex 按比例收缩所有 chip,几个长名字一起收缩,而不是最后一个先让位。
|
||||
- mailto 链接目前共用 `url` 地球图形;若将来需要独立的邮件类别,一行即可加上。
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@deepseek-ai/dsh",
|
||||
"description": "dsh CLI: profile boot, plugin management, and the browser UI alias",
|
||||
"version": "0.1.2-rc.1",
|
||||
"version": "0.1.3-alpha.1",
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
},
|
||||
|
||||
@@ -82,6 +82,9 @@ async function bootWeb(
|
||||
// skills test below proves it reaches preset-composed agents.
|
||||
{ id: 'skill-badge', disabled: false },
|
||||
{ id: 'modules', disabled: true },
|
||||
// The physical Connection row owns the disabled HTTP server. bootWeb
|
||||
// supplies only its in-process registries so Host services still prove
|
||||
// their shipped dependency graph without binding a port.
|
||||
{ id: 'connection', disabled: true },
|
||||
// Export owns a Connection Fetch route, so this Host-only composition
|
||||
// disables it with the transport service above.
|
||||
@@ -139,6 +142,10 @@ async function bootWeb(
|
||||
const rootConfig = join(profileDir, 'cordis.yml')
|
||||
await writeFile(rootConfig, '[]\n')
|
||||
return await boot('dsh-test', rootConfig, [...bundlePatches, ...overrides], (bootCtx) => {
|
||||
bootCtx.provide('connection', {
|
||||
fetch: { register: () => () => {} },
|
||||
rpc: { intercept: () => () => {} },
|
||||
} as never)
|
||||
provideCmdline(bootCtx, { args: [], exit: () => {} })
|
||||
})
|
||||
}
|
||||
|
||||
@@ -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.1.2-rc.1",
|
||||
"version": "0.1.3-alpha.1",
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
},
|
||||
|
||||
@@ -44,17 +44,6 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
|
||||
return page.getByRole('dialog', { name: '设置' })
|
||||
}
|
||||
|
||||
/** Tokenize the lane-owned preset root after general aria normalization. */
|
||||
function withPresetRoot(snapshot: string): string {
|
||||
const rootSuffix = `/${userRoot.split('/').pop()!}`
|
||||
return snapshot.split('\n').map((line) => {
|
||||
const rootStart = line.indexOf(rootSuffix)
|
||||
if (rootStart === -1) return line
|
||||
const pathStart = line.lastIndexOf(' ', rootStart) + 1
|
||||
return `${line.slice(0, pathStart)}{{presetRoot}}${line.slice(rootStart + rootSuffix.length)}`
|
||||
}).join('\n')
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
userRoot = await realpath(await mkdtemp(join(tmpdir(), 'dsh-web-e2e-presets-')))
|
||||
scaffold = await launchWebScaffold({
|
||||
@@ -147,8 +136,9 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
|
||||
// The copy dialog is detached, so the settings dialog is the only one
|
||||
// left (it names itself via aria-labelledby, which a CSS attribute
|
||||
// selector cannot address).
|
||||
const snapshot = withPresetRoot(
|
||||
await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd))
|
||||
const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd, {
|
||||
replacements: [[userRoot, '{{presetRoot}}']],
|
||||
})
|
||||
await compareOrRefreshGolden(CREATED_EXPECTED, snapshot, MODE)
|
||||
expect(snapshot).toContain('{{presetRoot}}/my-agent')
|
||||
|
||||
@@ -197,8 +187,9 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
|
||||
await dialog.getByRole('button', { name: 'Agent 预设' }).click()
|
||||
await dialog.getByText('加载失败').first().waitFor({ timeout: 10_000 })
|
||||
|
||||
const snapshot = withPresetRoot(
|
||||
await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd))
|
||||
const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd, {
|
||||
replacements: [[userRoot, '{{presetRoot}}']],
|
||||
})
|
||||
await compareOrRefreshGolden(DAMAGED_EXPECTED, snapshot, MODE)
|
||||
// Both damage shapes surface as marked, unselectable, uncopyable cards
|
||||
// that still carry their metadata and the discovery-reported reason.
|
||||
|
||||
@@ -173,6 +173,10 @@ describe('web e2e: long Chat interaction contract', () => {
|
||||
|
||||
it.skipIf(MODE === 'record')('keeps heterogeneous rows and their actions bound to exact semantic identities', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-chat-long-interactions'))
|
||||
await expect.poll(
|
||||
() => scaffold.ctx.agents.get(SessionId(SESSION_ID)) !== undefined,
|
||||
{ timeout: 10_000 },
|
||||
).toBe(true)
|
||||
const source = scaffold.ctx.agents.get(SessionId(SESSION_ID))
|
||||
if (source === undefined) throw new Error('seeded long-history agent is not attached')
|
||||
|
||||
|
||||
@@ -0,0 +1,431 @@
|
||||
// Web e2e gallery: every clickable link and artifact form the chat renders,
|
||||
// in one settled keyless turn — the regression anchor for unifying link
|
||||
// styles. One fixture turn produces:
|
||||
// - prose: Markdown link, reference-style link, mailto link, inline-code URL,
|
||||
// produced-file mention, plus inert contrasts (ambiguous basename, unwritten
|
||||
// file, command code, URL-with-flags code, javascript: destination,
|
||||
// footnote superscript, remote image, fenced code block with its copy chrome)
|
||||
// - artifacts: seven produced files (chips overflow into the "+N" remainder
|
||||
// and the show-in-folder affordance) with a failed write excluded
|
||||
// - tool rows: write/edit/str_replace_editor/read file links, a failure row
|
||||
// without one, and — expanded — the web-search source links (one non-http
|
||||
// source stays inert) and answer link, the web-fetch URL, the read card's
|
||||
// inert path label and fold toggle, the diff card's inert path header, the
|
||||
// grep card's fold-only file headers, a failing bash card's exit status, and
|
||||
// a generic tool card's IN/OUT surfaces.
|
||||
// Image thumbnails and subagent rows stay out: the first needs real attachment
|
||||
// bytes (image-display.expected.e2e.ts owns that route) and the second needs a
|
||||
// child session (subagent-conversation owns it).
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import type { Browser, Page } from 'playwright'
|
||||
import { chromium } 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'
|
||||
import type { JsonValue } from '@deepseek-ai/dsh-util-values'
|
||||
import type {} from '@deepseek-ai/dsh-session-title'
|
||||
import {
|
||||
assertFixtureInventory,
|
||||
captureStableAria,
|
||||
compareOrRefreshGolden,
|
||||
launchWebScaffold,
|
||||
seedSession,
|
||||
watchConsole,
|
||||
webSnapshotMode,
|
||||
type WebScaffold,
|
||||
} from './scaffold.ts'
|
||||
import { newEnglishPage, saveFailureShot } from './support.ts'
|
||||
|
||||
const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/clickable-links-gallery', import.meta.url))
|
||||
const UI_EXPECTED = fileURLToPath(new URL('./expected/clickable-links-gallery/ui.expected.md', import.meta.url))
|
||||
// The golden holds the show-in-folder affordance; pin the native-opener
|
||||
// capability so headless Linux CI and desktop developer hosts expose the same
|
||||
// UI branch (same pin as produced-files.e2e.ts, whose overlay this shares).
|
||||
const OVERLAY = fileURLToPath(new URL('./produced-files.overlay.yml', import.meta.url))
|
||||
const MODE = webSnapshotMode()
|
||||
const SEED_ID = 'clickable-links-gallery-web-e2e'
|
||||
const DONE = 'LINK_GALLERY_DONE'
|
||||
|
||||
const GUIDE_URL = 'https://docs.example.test/guide'
|
||||
const API_URL = 'https://docs.example.test/api'
|
||||
const RELEASES_URL = 'https://docs.example.test/releases'
|
||||
const MAILTO_URL = 'mailto:[email protected]'
|
||||
const SOURCE_URL = 'https://docs.example.test/links'
|
||||
const INERT_SOURCE_URL = 'ftp://mirror.example.test/spec'
|
||||
const FETCH_URL = 'https://docs.example.test/tokens'
|
||||
|
||||
/** One-part text content for a built message. */
|
||||
function text(value: string): { type: 'text'; text: string }[] {
|
||||
return [{ type: 'text', text: value }]
|
||||
}
|
||||
|
||||
/** A settled root tool call: its call event arguments plus result content/meta. */
|
||||
interface GalleryCall {
|
||||
name: string
|
||||
args: Record<string, unknown>
|
||||
result: string
|
||||
meta?: JsonValue
|
||||
isError?: true
|
||||
}
|
||||
|
||||
/** The five successful writes; docs/press.md and src/tokens.css join via other tools. */
|
||||
const WRITES = ['site/report.html', 'a/style.css', 'b/style.css', 'site/index.html', 'site/app.js']
|
||||
|
||||
/** The gallery turn's tool calls, in surface order. */
|
||||
const CALLS: GalleryCall[] = [
|
||||
...WRITES.map(path => ({
|
||||
name: 'write',
|
||||
args: { file_path: path, content: `content of ${path}\n` },
|
||||
result: `Created ${path}`,
|
||||
})),
|
||||
{
|
||||
name: 'edit',
|
||||
args: {
|
||||
file_path: 'src/tokens.css',
|
||||
old_string: '--inline-code: #EBEEF2;',
|
||||
new_string: '--inline-code: #F5F5F5;',
|
||||
},
|
||||
result: 'Edited src/tokens.css',
|
||||
meta: {
|
||||
diffs: [{
|
||||
path: 'src/tokens.css',
|
||||
oldText: '--inline-code: #EBEEF2;\n',
|
||||
newText: '--inline-code: #F5F5F5;\n',
|
||||
}],
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'str_replace_editor',
|
||||
args: { command: 'create', path: 'docs/press.md', file_text: '# Press kit\n' },
|
||||
result: 'Created docs/press.md',
|
||||
meta: { diffs: [{ path: 'docs/press.md', oldText: null, newText: '# Press kit\n' }] },
|
||||
},
|
||||
{
|
||||
name: 'write',
|
||||
args: { file_path: 'c/broken.css', content: 'nope\n' },
|
||||
result: 'permission denied: c/broken.css',
|
||||
isError: true,
|
||||
},
|
||||
{
|
||||
name: 'read',
|
||||
args: { file_path: 'docs/guide.md' },
|
||||
// The read card validates the model-facing envelope, not just the meta:
|
||||
// without <path>/<type>/<content> the row falls back to the generic card.
|
||||
result: [
|
||||
'<path>docs/guide.md</path>',
|
||||
'<type>file</type>',
|
||||
'<content>',
|
||||
...Array.from({ length: 12 }, (_, index) =>
|
||||
index === 0 ? '# Link style guide' : `guide line ${String(index + 1)}`),
|
||||
'</content>',
|
||||
].join('\n'),
|
||||
meta: {
|
||||
path: 'docs/guide.md',
|
||||
offset: 1,
|
||||
lines: Array.from({ length: 12 }, (_, index) => ({
|
||||
number: index + 1,
|
||||
text: index === 0 ? '# Link style guide' : `guide line ${String(index + 1)}`,
|
||||
})),
|
||||
totalLines: 12,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'grep',
|
||||
args: { pattern: 'linkColor' },
|
||||
result: 'nine matches across three files',
|
||||
meta: {
|
||||
shape: 'matches',
|
||||
files: ['a/style.css', 'b/style.css', 'src/tokens.css'].map(path => ({
|
||||
path,
|
||||
matches: [3, 7, 11].map(lineNumber => ({ lineNumber, line: ' color: var(--linkColor);' })),
|
||||
})),
|
||||
truncated: false,
|
||||
total: 9,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'glob',
|
||||
args: { pattern: '**/*.css' },
|
||||
result: 'a/style.css\nb/style.css\nsrc/tokens.css',
|
||||
meta: { shape: 'paths', paths: ['a/style.css', 'b/style.css', 'src/tokens.css'], truncated: false, total: 3 },
|
||||
},
|
||||
{
|
||||
name: 'bash',
|
||||
args: { command: 'ls site', description: 'List the built site' },
|
||||
result: 'report.html\nindex.html\napp.js\n',
|
||||
},
|
||||
{
|
||||
name: 'bash',
|
||||
args: { command: 'pnpm run lint', description: 'Run the lint gate', workdir: 'site' },
|
||||
result: 'style.css: unexpected hex literal\n[exit code: 1]',
|
||||
},
|
||||
{
|
||||
name: 'web_search',
|
||||
args: { queries: ['clickable link styles', 'produced files ui'] },
|
||||
result: 'Two sources found.',
|
||||
meta: {
|
||||
truncated: false,
|
||||
answer: `Unify links per [the guide](${GUIDE_URL}).`,
|
||||
sources: [
|
||||
{ url: SOURCE_URL, title: 'Link styles reference', snippet: 'One cursor token, one focus ring.' },
|
||||
{ url: INERT_SOURCE_URL, title: 'Mirror spec (non-http)', snippet: 'A non-http source renders inert.' },
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'web_fetch',
|
||||
args: { url: FETCH_URL },
|
||||
result: 'Design token reference page.',
|
||||
meta: { url: FETCH_URL, statusCode: 200, truncated: false },
|
||||
},
|
||||
{
|
||||
name: 'design_tokens_sync',
|
||||
args: { source: 'design-platform.css', dryRun: false },
|
||||
result: '{"synced":true,"tokens":12}',
|
||||
},
|
||||
]
|
||||
|
||||
/**
|
||||
* Build the settled gallery turn: every call above plus a link-dense closing prose.
|
||||
* @param imageUrl - scaffold-hosted image the prose embeds (kept same-origin so
|
||||
* the tripwire stays clean; the varying origin is tokenized in the golden).
|
||||
*/
|
||||
function galleryFixture(imageUrl: string): string {
|
||||
const session = Session.create(SessionId('clickable-links-gallery-source'))
|
||||
const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
|
||||
session.append('turn/start', { turn: 1 })
|
||||
const user = session.append('user/message', createUserMessage({
|
||||
content: text('Assemble the link gallery: write the report and styles, inspect the sources, and summarize.'),
|
||||
source: { kind: 'user' },
|
||||
}), { surfaceOp: 'append' })
|
||||
session.append('session/title', {
|
||||
title: 'Clickable links gallery',
|
||||
messageSeqs: [user.seq],
|
||||
source: { kind: 'fallback' },
|
||||
})
|
||||
session.append('step/start', { turn: 1, step: 1 })
|
||||
const calls = CALLS.map((call, index) => ({
|
||||
...call,
|
||||
callId: ToolCallId(`gallery-${String(index)}`),
|
||||
argsJson: JSON.stringify(call.args),
|
||||
}))
|
||||
session.append('assistant/message', {
|
||||
stream: [],
|
||||
turn: 1,
|
||||
step: 1,
|
||||
message: createAssistantMessage({
|
||||
content: calls.map(call => ({
|
||||
type: 'tool-call' as const,
|
||||
id: call.callId,
|
||||
name: call.name,
|
||||
arguments: call.argsJson,
|
||||
})),
|
||||
source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
|
||||
}),
|
||||
}, { surfaceOp: 'append' })
|
||||
for (const call of calls) {
|
||||
const source = session.append('tool/call', {
|
||||
turn: 1,
|
||||
step: 1,
|
||||
callId: call.callId,
|
||||
name: call.name,
|
||||
arguments: call.argsJson,
|
||||
})
|
||||
session.append('tool/result', {
|
||||
turn: 1,
|
||||
step: 1,
|
||||
message: createToolResultMessage({
|
||||
callId: call.callId,
|
||||
content: text(call.result),
|
||||
isError: call.isError === true,
|
||||
}),
|
||||
...(call.meta === undefined ? {} : { meta: call.meta }),
|
||||
}, { surfaceOp: 'append', sourceEventSeqs: [source.seq] })
|
||||
}
|
||||
session.append('step/start', { turn: 1, step: 2 })
|
||||
session.append('assistant/message', {
|
||||
stream: [],
|
||||
turn: 1,
|
||||
step: 2,
|
||||
message: createAssistantMessage({
|
||||
content: text([
|
||||
'## Link gallery',
|
||||
'',
|
||||
`Docs: [style guide](${GUIDE_URL}) and \`${API_URL}\`; see [the release notes][rel], `
|
||||
+ `contact [the maintainer](${MAILTO_URL}), and check the fine print[^1].`,
|
||||
'',
|
||||
`Inert contrasts: \`curl ${API_URL}\`, \`javascript:alert(1)\`, and \`pnpm run build\`.`,
|
||||
'',
|
||||
'Wrote `report.html` plus two `style.css` copies; `notes.md` untouched.',
|
||||
'',
|
||||
``,
|
||||
'',
|
||||
'```css',
|
||||
'--inline-code: #F5F5F5;',
|
||||
'```',
|
||||
'',
|
||||
DONE,
|
||||
'',
|
||||
`[rel]: ${RELEASES_URL}`,
|
||||
'',
|
||||
'[^1]: Footnote references stay inert superscripts.',
|
||||
].join('\n')),
|
||||
source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
|
||||
}),
|
||||
}, { surfaceOp: 'append' })
|
||||
session.append('step/end', { turn: 1, step: 2 })
|
||||
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: eventTimeOrigin + event.seq * 1_000,
|
||||
})),
|
||||
'',
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
describe('web e2e: clickable links gallery', () => {
|
||||
let scaffold: WebScaffold
|
||||
let browser: Browser
|
||||
let page: Page
|
||||
let imageUrl: string
|
||||
let tripwire: ReturnType<typeof watchConsole>
|
||||
|
||||
beforeAll(async () => {
|
||||
scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY })
|
||||
imageUrl = new URL('/favicon.svg', scaffold.baseUrl).toString()
|
||||
await seedSession(scaffold, galleryFixture(imageUrl), SEED_ID)
|
||||
browser = await chromium.launch()
|
||||
page = await newEnglishPage(browser)
|
||||
tripwire = watchConsole(page)
|
||||
await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
|
||||
await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
|
||||
}, 120_000)
|
||||
|
||||
afterAll(async () => {
|
||||
await browser?.close()
|
||||
await scaffold?.close()
|
||||
})
|
||||
|
||||
it.skipIf(MODE === 'record')('renders every clickable link and artifact form of the settled turn', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-clickable-links-gallery'))
|
||||
const groupRow = page.locator('[role="treeitem"]').first()
|
||||
await groupRow.waitFor({ timeout: 15_000 })
|
||||
await groupRow.click()
|
||||
const sessionRow = page.locator('[role="treeitem"]').nth(1)
|
||||
await sessionRow.waitFor({ timeout: 10_000 })
|
||||
await sessionRow.click()
|
||||
await expect.poll(() => page.getByText(DONE, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
|
||||
|
||||
// Markdown prose: plain, reference-style, and mailto links plus the
|
||||
// inline-code URL are anchors; the URL-with-flags code, the javascript:
|
||||
// destination, and plain command code stay inert.
|
||||
const markdown = page.locator('[class*="markdown"]')
|
||||
await expect.poll(() => markdown.locator(`a[href="${GUIDE_URL}"]`).count(), { timeout: 10_000 }).toBe(1)
|
||||
expect(await markdown.locator(`a[href="${RELEASES_URL}"]`).count()).toBe(1)
|
||||
expect(await markdown.locator(`a[href="${MAILTO_URL}"]`).count()).toBe(1)
|
||||
const inlineCodeLink = markdown.locator(`code a[href="${API_URL}"]`)
|
||||
expect(await inlineCodeLink.count()).toBe(1)
|
||||
expect(await inlineCodeLink.getAttribute('target')).toBe('_blank')
|
||||
expect(await page.getByText(`curl ${API_URL}`, { exact: true }).locator('a').count()).toBe(0)
|
||||
expect(await page.getByText('javascript:alert(1)', { exact: true }).locator('a').count()).toBe(0)
|
||||
expect(await markdown.locator(`img[src="${imageUrl}"]`).count()).toBe(1)
|
||||
|
||||
// Produced files: one unique-basename mention links; the shared basename
|
||||
// and the unwritten file stay inert code. Seven produced paths overflow
|
||||
// the chip row; the failed write joins neither surface.
|
||||
const mentions = markdown.locator('code button')
|
||||
expect(await mentions.count()).toBe(1)
|
||||
expect(await mentions.first().getAttribute('title')).toBe('site/report.html')
|
||||
expect(await page.getByText('Produced', { exact: true }).count()).toBe(1)
|
||||
expect(await page.locator('[class*="centerCol"] button[aria-label^="Open "]').count()).toBeGreaterThanOrEqual(5)
|
||||
expect(await page.locator('button[aria-label="Open c/broken.css"]').count()).toBe(0)
|
||||
|
||||
// Tool rows: five writes, the edit, and the read carry the dotted file
|
||||
// link; the failed write row does not, and neither does str_replace_editor
|
||||
// — TOOL_VARIANTS has no entry for it, so it falls to the generic row with
|
||||
// no openable path even though its create still joins the produced chips.
|
||||
expect(await page.locator('button[class*="fileLink"]').count()).toBe(7)
|
||||
|
||||
// Expanded cards. The turn-process group collapses a multi-call turn, so
|
||||
// it opens first. Rows expand via a right-edge click: the row center can
|
||||
// land on the nested fileLink button, which would hand the path to the
|
||||
// Host's opener.
|
||||
await page.getByRole('button', { name: `${String(CALLS.length)} tool calls` }).click()
|
||||
for (const row of [
|
||||
/^Search clickable link styles/,
|
||||
/^Fetch /,
|
||||
/^Read docs\/guide\.md/,
|
||||
/^Edit src\/tokens\.css/,
|
||||
/^Grep linkColor/,
|
||||
/Run the lint gate|pnpm run lint/,
|
||||
]) {
|
||||
const toggle = page.getByRole('button', { name: row }).first()
|
||||
await toggle.waitFor({ timeout: 10_000 })
|
||||
const box = await toggle.boundingBox()
|
||||
await toggle.click(box === null ? {} : { position: { x: box.width - 8, y: box.height / 2 } })
|
||||
}
|
||||
// Both generic rows (the unclassified str_replace_editor and the unknown
|
||||
// design_tokens_sync) expand to their IN/OUT surfaces.
|
||||
const genericRows = page.getByRole('button', { name: /^Tool call/ })
|
||||
for (let index = 0; index < await genericRows.count(); index += 1) {
|
||||
const toggle = genericRows.nth(index)
|
||||
const box = await toggle.boundingBox()
|
||||
await toggle.click(box === null ? {} : { position: { x: box.width - 8, y: box.height / 2 } })
|
||||
}
|
||||
const sourceLink = page.locator(`a[href="${SOURCE_URL}"]`)
|
||||
await expect.poll(() => sourceLink.count(), { timeout: 10_000 }).toBe(1)
|
||||
expect(await page.locator('a[href^="ftp:"]').count()).toBe(0)
|
||||
expect(await page.locator(`a[href="${FETCH_URL}"]`).count()).toBe(1)
|
||||
expect(await page.locator(`a[href="${GUIDE_URL}"]`).count()).toBe(2)
|
||||
|
||||
const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
|
||||
.split(SEED_ID).join('{{seededId}}')
|
||||
.split(imageUrl).join('{{imageUrl}}')
|
||||
await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
|
||||
|
||||
// The link language itself — ARIA records none of it, so pin the computed
|
||||
// styles: link-blue 500-weight text, no underline at rest, dotted underline
|
||||
// on hover, and a leading currentColor glyph. Light theme, so the link
|
||||
// alias resolves to deepseek-500.
|
||||
const LINK_BLUE = 'rgb(65, 118, 230)'
|
||||
const styleOf = async (target: ReturnType<Page['locator']>, property: string): Promise<string> =>
|
||||
target.evaluate((el, p) => getComputedStyle(el).getPropertyValue(p), property)
|
||||
const guideLink = markdown.locator(`a[href="${GUIDE_URL}"]`).first()
|
||||
const chip = page.locator('button[aria-label="Open site/report.html"]').first()
|
||||
for (const [name, link] of [
|
||||
['markdown anchor', guideLink],
|
||||
['file mention', mentions.first()],
|
||||
['search source', sourceLink.first()],
|
||||
['fetch url', page.locator(`a[href="${FETCH_URL}"]`).first()],
|
||||
['produced chip', chip],
|
||||
] as const) {
|
||||
expect.soft(await styleOf(link, 'color'), `${name} color`).toBe(LINK_BLUE)
|
||||
expect.soft(await styleOf(link, 'font-weight'), `${name} weight`).toBe('500')
|
||||
expect.soft(await styleOf(link, 'text-decoration-line'), `${name} at rest`).toBe('none')
|
||||
expect.soft(await link.locator('svg').count(), `${name} glyph`).toBe(1)
|
||||
}
|
||||
await guideLink.hover()
|
||||
expect(await styleOf(guideLink, 'text-decoration-line')).toBe('underline')
|
||||
expect(await styleOf(guideLink, 'text-decoration-style')).toBe('dotted')
|
||||
expect(await styleOf(guideLink, 'text-underline-offset')).toBe('3px')
|
||||
await chip.hover()
|
||||
expect(await styleOf(chip, 'text-decoration-style')).toBe('dotted')
|
||||
expect(await styleOf(chip, 'background-color')).toBe('rgba(0, 0, 0, 0)')
|
||||
// The excluded grey affordance: tool-row file links keep their own color.
|
||||
expect(await styleOf(page.locator('button[class*="fileLink"]').first(), 'color')).not.toBe(LINK_BLUE)
|
||||
}, 90_000)
|
||||
})
|
||||
@@ -1,8 +1,8 @@
|
||||
// @vitest-environment jsdom
|
||||
// The command image-attachment envelope over the BUILT client graph (real
|
||||
// The command attachment envelope over the BUILT client graph (real
|
||||
// bundles via AppWebEntry, keyless fixture Connection RPC): an enter
|
||||
// submission carrying composer images resolves only through a command whose
|
||||
// descriptor declares `input.images`. A non-declaring command refuses with
|
||||
// submission carrying composer attachments resolves only through a command whose
|
||||
// descriptor declares `input.attachments`. A non-declaring command refuses with
|
||||
// one composer error banner and everything retained; a declaring command
|
||||
// consumes the images — serialized through the real draft-image chain into
|
||||
// the commands/execute payload — and clears the composer on success, including
|
||||
@@ -47,7 +47,7 @@ async function pasteImage(textarea: HTMLElement, name: string): Promise<void> {
|
||||
},
|
||||
})
|
||||
await waitFor(() => {
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending images"]')
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending attachments"]')
|
||||
if (rail === null) throw new Error('attachment rail missing')
|
||||
expect([...rail.querySelectorAll('img')].map(img => img.getAttribute('alt'))).toContain(name)
|
||||
}, { timeout: 5_000 })
|
||||
@@ -58,7 +58,7 @@ it('refuses an image-carrying submit to a non-declaring command and keeps draft
|
||||
const textarea = await freshComposer()
|
||||
await pasteImage(textarea, 'ref.png')
|
||||
|
||||
// /echo is a leadingInput fixture command without `input.images`.
|
||||
// /echo is a leadingInput fixture command without `input.attachments`.
|
||||
await pasteText(textarea, '/echo hello')
|
||||
fireEvent.keyDown(textarea, { key: 'Enter' })
|
||||
|
||||
@@ -66,16 +66,16 @@ it('refuses an image-carrying submit to a non-declaring command and keeps draft
|
||||
// failures; session activity remains on its separate status live region.
|
||||
const notice = await waitFor(() => {
|
||||
const el = [...document.querySelectorAll('[role="alert"]')]
|
||||
.find(candidate => candidate.textContent?.includes('image attachments') ?? false)
|
||||
.find(candidate => candidate.textContent?.includes('attachments') ?? false)
|
||||
if (el === undefined) throw new Error('composer refusal banner missing')
|
||||
return el
|
||||
}, { timeout: 5_000 })
|
||||
expect(notice.textContent).toBe('/echo does not accept image attachments; remove them first')
|
||||
expect(notice.textContent).toBe('/echo does not accept attachments; remove them first')
|
||||
expect([...document.querySelectorAll('[role="status"]')]
|
||||
.some(candidate => candidate.textContent?.includes('image attachments') ?? false)).toBe(false)
|
||||
.some(candidate => candidate.textContent?.includes('attachments') ?? false)).toBe(false)
|
||||
// The whole envelope is retained: draft text and the rail thumbnail.
|
||||
await waitFor(() => { expect(textarea.textContent).toBe('/echo hello') })
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending images"]')
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending attachments"]')
|
||||
expect([...(rail?.querySelectorAll('img') ?? [])].map(img => img.getAttribute('alt'))).toEqual(['ref.png'])
|
||||
})
|
||||
|
||||
@@ -84,14 +84,14 @@ it('consumes images through a declaring command and clears the composer on succe
|
||||
const textarea = await freshComposer()
|
||||
await pasteImage(textarea, 'goal-ref.png')
|
||||
|
||||
// /goal declares `input.images` in the fixture catalog; the claim submit
|
||||
// /goal declares `input.attachments` in the fixture catalog; the claim submit
|
||||
// serializes the pasted bytes and the fixture executor admits them.
|
||||
await pasteText(textarea, '/goal rebuild the cathedral')
|
||||
fireEvent.keyDown(textarea, { key: 'Enter' })
|
||||
|
||||
await waitFor(() => {
|
||||
expect(textarea.textContent).toBe('')
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending images"]')).toBeNull()
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).toBeNull()
|
||||
}, { timeout: 5_000 })
|
||||
})
|
||||
|
||||
@@ -107,7 +107,7 @@ it('submits a bare /plan with an image as an image-only plan request', async ()
|
||||
|
||||
await waitFor(() => {
|
||||
expect(textarea.textContent).toBe('')
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending images"]')).toBeNull()
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).toBeNull()
|
||||
}, { timeout: 5_000 })
|
||||
expect([...document.querySelectorAll('[role="alert"]')]
|
||||
.some(candidate => candidate.textContent?.includes('/plan') ?? false)).toBe(false)
|
||||
|
||||
@@ -0,0 +1,204 @@
|
||||
- banner:
|
||||
- navigation "Session hierarchy":
|
||||
- button "Clickable links gallery" [disabled]
|
||||
- button "Session log":
|
||||
- text: Session log
|
||||
- img
|
||||
- tablist:
|
||||
- tab "Chat" [selected]
|
||||
- tab "Trajectory"
|
||||
- text: "Assemble the link gallery: write the report and styles, inspect the sources, and summarize. {{clock}}"
|
||||
- button "Copy":
|
||||
- img
|
||||
- button "16 tool calls" [expanded]:
|
||||
- text: 16 tool calls
|
||||
- img
|
||||
- button "Write site/report.html +1 -0":
|
||||
- img
|
||||
- img
|
||||
- text: Write
|
||||
- button "site/report.html"
|
||||
- text: +1 -0
|
||||
- button "Write a/style.css +1 -0":
|
||||
- img
|
||||
- img
|
||||
- text: Write
|
||||
- button "a/style.css"
|
||||
- text: +1 -0
|
||||
- button "Write b/style.css +1 -0":
|
||||
- img
|
||||
- img
|
||||
- text: Write
|
||||
- button "b/style.css"
|
||||
- text: +1 -0
|
||||
- button "Write site/index.html +1 -0":
|
||||
- img
|
||||
- img
|
||||
- text: Write
|
||||
- button "site/index.html"
|
||||
- text: +1 -0
|
||||
- button "Write site/app.js +1 -0":
|
||||
- img
|
||||
- img
|
||||
- text: Write
|
||||
- button "site/app.js"
|
||||
- text: +1 -0
|
||||
- button "Edit src/tokens.css +1 -1" [expanded]:
|
||||
- img
|
||||
- text: Edit
|
||||
- button "src/tokens.css"
|
||||
- text: +1 -1
|
||||
- button "Copy"
|
||||
- text: "src/tokens.css - --inline-code: #EBEEF2; + --inline-code: #F5F5F5; └ +1 -1 · 1 file"
|
||||
- button "Inspect"
|
||||
- button "Tool call str_replace_editor · create" [expanded]:
|
||||
- img
|
||||
- text: Tool call str_replace_editor · create
|
||||
- text: "IN { \"command\": \"create\", \"path\": \"docs/press.md\", \"file_text\": \"# Press kit\\n\" } OUT Created docs/press.md"
|
||||
- button "Inspect"
|
||||
- text: Failed
|
||||
- 'button "Write permission denied: c/broken.css"':
|
||||
- img
|
||||
- text: "Write permission denied: c/broken.css"
|
||||
- button "Read docs/guide.md" [expanded]:
|
||||
- img
|
||||
- text: Read
|
||||
- button "docs/guide.md"
|
||||
- text: docs/guide.md
|
||||
- button "Copy"
|
||||
- text: "# Link style guide guide line 2 guide line 3 guide line 4"
|
||||
- button "Expand 4 more lines": … 4 more lines
|
||||
- text: guide line 9 guide line 10 guide line 11 guide line 12
|
||||
- button "Inspect"
|
||||
- button "Grep linkColor" [expanded]:
|
||||
- img
|
||||
- text: Grep linkColor
|
||||
- text: 9 matches · 3 files
|
||||
- button "Copy"
|
||||
- button "a/style.css 3" [expanded]
|
||||
- text: "3: color: var(--linkColor); 7: color: var(--linkColor); 11: color: var(--linkColor);"
|
||||
- button "Expand 4 more result lines": … 4 more lines
|
||||
- button "src/tokens.css 3" [expanded]
|
||||
- text: "3: color: var(--linkColor); 7: color: var(--linkColor); 11: color: var(--linkColor);"
|
||||
- button "Inspect"
|
||||
- button "Glob **/*.css":
|
||||
- img
|
||||
- img
|
||||
- text: Glob **/*.css
|
||||
- button "Bash List the built site":
|
||||
- img
|
||||
- img
|
||||
- text: Bash List the built site
|
||||
- button "Failed Bash Run the lint gate" [expanded]:
|
||||
- img
|
||||
- text: Failed Bash Run the lint gate
|
||||
- text: Failed site pnpm run lint exit code 1
|
||||
- button "Copy"
|
||||
- text: "style.css: unexpected hex literal"
|
||||
- button "Inspect"
|
||||
- button "Search clickable link styles, produced files ui" [expanded]:
|
||||
- img
|
||||
- text: Search clickable link styles, produced files ui
|
||||
- paragraph:
|
||||
- text: Unify links per
|
||||
- link "the guide":
|
||||
- /url: https://docs.example.test/guide
|
||||
- text: .
|
||||
- list:
|
||||
- listitem:
|
||||
- link "Link styles reference":
|
||||
- /url: https://docs.example.test/links
|
||||
- text: One cursor token, one focus ring.
|
||||
- listitem: Mirror spec (non-http) A non-http source renders inert.
|
||||
- button "Inspect"
|
||||
- button "Fetch https://docs.example.test/tokens" [expanded]:
|
||||
- img
|
||||
- text: Fetch https://docs.example.test/tokens
|
||||
- link "https://docs.example.test/tokens":
|
||||
- /url: https://docs.example.test/tokens
|
||||
- text: HTTP 200
|
||||
- button "Inspect"
|
||||
- button "Tool call design_tokens_sync · design-platform.css" [expanded]:
|
||||
- img
|
||||
- text: Tool call design_tokens_sync · design-platform.css
|
||||
- text: "IN { \"source\": \"design-platform.css\", \"dryRun\": false } OUT {\"synced\":true,\"tokens\":12}"
|
||||
- button "Inspect"
|
||||
- heading "Link gallery" [level=2]
|
||||
- paragraph:
|
||||
- text: "Docs:"
|
||||
- link "style guide":
|
||||
- /url: https://docs.example.test/guide
|
||||
- text: and
|
||||
- code:
|
||||
- link "https://docs.example.test/api":
|
||||
- /url: https://docs.example.test/api
|
||||
- text: ; see
|
||||
- link "the release notes":
|
||||
- /url: https://docs.example.test/releases
|
||||
- text: ", contact"
|
||||
- link "the maintainer":
|
||||
- /url: mailto:owner@example.test
|
||||
- text: ", and check the fine print"
|
||||
- superscript: "1"
|
||||
- text: .
|
||||
- paragraph:
|
||||
- text: "Inert contrasts:"
|
||||
- code: curl https://docs.example.test/api
|
||||
- text: ","
|
||||
- code: javascript:alert(1)
|
||||
- text: ", and"
|
||||
- code: pnpm run build
|
||||
- text: .
|
||||
- paragraph:
|
||||
- text: Wrote
|
||||
- code:
|
||||
- button "Open site/report.html": report.html
|
||||
- text: plus two
|
||||
- code: style.css
|
||||
- text: copies;
|
||||
- code: notes.md
|
||||
- text: untouched.
|
||||
- paragraph:
|
||||
- img "Token preview"
|
||||
- text: css
|
||||
- button "Copy"
|
||||
- code: "--inline-code: #F5F5F5;"
|
||||
- paragraph: LINK_GALLERY_DONE
|
||||
- heading "Footnotes" [level=2]
|
||||
- list:
|
||||
- listitem:
|
||||
- paragraph: Footnote references stay inert superscripts. ↩
|
||||
- text: Produced
|
||||
- button "Open site/report.html": report.html
|
||||
- button "Open a/style.css": style.css
|
||||
- button "Open b/style.css": style.css
|
||||
- button "Open site/index.html": index.html
|
||||
- button "Open site/app.js": app.js
|
||||
- button "Open src/tokens.css": tokens.css
|
||||
- text: + 1 file
|
||||
- button "Show in folder"
|
||||
- button "Copy":
|
||||
- img
|
||||
- button "Good response":
|
||||
- img
|
||||
- button "Bad response":
|
||||
- img
|
||||
- button "Branch into a new conversation":
|
||||
- img
|
||||
- button "Ran for {{duration}}":
|
||||
- img
|
||||
- text: Ran for {{duration}}
|
||||
- text: {{clock}}
|
||||
- button "Back to bottom":
|
||||
- img
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
- img
|
||||
- button "Send message" [disabled]
|
||||
- text: 1 turns · 1 steps LLM {{duration}} · Tool call {{duration}}
|
||||
@@ -0,0 +1,9 @@
|
||||
# Mixed composer attachment rail
|
||||
|
||||
- selection order: poem.txt > reference-1.png > reference-2.png > reference-3.png > reference-4.png > reference-5.png > reference-6.png > reference-7.png > reference-8.png > reference-9.png > reference-10.png
|
||||
- one attachment group: true
|
||||
- all cards share one row: true
|
||||
- every card is 64px high: true
|
||||
- the file card is wider than an image: true
|
||||
- overflowing cards scroll horizontally: true
|
||||
- the rail does not wrap: true
|
||||
@@ -0,0 +1,10 @@
|
||||
# Mixed history attachment flow
|
||||
|
||||
- source order: poem.txt > reference-1.png
|
||||
- one attachment group: true
|
||||
- file and image share one row: true
|
||||
- both cards are 64px high: true
|
||||
- the image is a 64px tile: true
|
||||
- the file card is wider than the image: true
|
||||
- the group wraps when needed: true
|
||||
- the group is right-aligned: true
|
||||
@@ -51,6 +51,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Read Only"': Read Only
|
||||
- button "Select model, current github-webhook-review-test/reply":
|
||||
- text: github-webhook-review-test/reply
|
||||
|
||||
@@ -43,6 +43,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Read Only"': Read Only
|
||||
- button "Select model, current github-webhook-review-test/reply":
|
||||
- text: github-webhook-review-test/reply
|
||||
|
||||
@@ -17,6 +17,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -51,6 +51,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -30,6 +30,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -42,6 +42,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -46,6 +46,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
- listbox "Trigger suggestions":
|
||||
- text: Skills
|
||||
- option "policy-user-only user-only · Available only to user invocation" [selected]
|
||||
@@ -43,6 +43,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -35,6 +35,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -462,6 +462,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -34,6 +34,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -53,6 +53,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -41,6 +41,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current DeepSeek-V4-Flash":
|
||||
- text: DeepSeek-V4-Flash
|
||||
|
||||
@@ -0,0 +1,283 @@
|
||||
// Web e2e scenario: generic file upload round trip. A real chromium picks a
|
||||
// file through the composer paperclip input; the upload RPC stores the exact
|
||||
// bytes below the scaffold's isolated DSH_HOME, the prompt cites the staged
|
||||
// reference, request assembly projects the file block to handle text, and the
|
||||
// model (replayed or live) reads the saved copy with the REAL read tool. The
|
||||
// content-addressed store makes the saved path identical across record and
|
||||
// replay once the workspace cwd is tokenized, so the recorded read arguments
|
||||
// replay verbatim against a freshly re-uploaded object.
|
||||
// Record: DSH_SNAPSHOT=record rewrites session.v2.jsonl, then a keyless
|
||||
// DSH_SNAPSHOT=refresh regenerates ui.expected.md.
|
||||
import { readFile } from 'node:fs/promises'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import type { Browser, Page } from 'playwright'
|
||||
import { chromium } 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, saveFailureShot } from './support.ts'
|
||||
|
||||
const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/file-upload-round', import.meta.url))
|
||||
const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/file-upload-round/session.v2.jsonl', import.meta.url))
|
||||
const UI_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/file-upload-round/ui.expected.md', import.meta.url))
|
||||
const TRAJECTORY_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/file-upload-round/trajectory.expected.md', import.meta.url))
|
||||
const OVERRIDE = fileURLToPath(new URL('../../../snapshots/web/file-upload-round/replay.override.json', import.meta.url))
|
||||
const DRAFT_EXPECTED = fileURLToPath(new URL('./expected/file-upload-round/draft.expected.md', import.meta.url))
|
||||
const HISTORY_EXPECTED = fileURLToPath(new URL('./expected/file-upload-round/history.expected.md', import.meta.url))
|
||||
const IMAGE_FIXTURE = fileURLToPath(new URL('../../../snapshots/session/read-image/workspace/red.png', import.meta.url))
|
||||
const MODE = webSnapshotMode()
|
||||
|
||||
/** The uploaded fixture file: constant bytes so record and replay share one content digest. */
|
||||
const FILE_NAME = 'poem.txt'
|
||||
const FILE_TEXT = 'UPLOAD_ROUND_OK\n'
|
||||
const PROMPT = 'Read the attached file with the read tool, reply with exactly the single word it contains, and stop.'
|
||||
const IMAGE_NAMES = Array.from({ length: 10 }, (_unused, index) => `reference-${String(index + 1)}.png`)
|
||||
|
||||
/** Browser-measured relations for the mixed composer attachment rail. */
|
||||
interface DraftRailGeometry {
|
||||
readonly order: readonly string[]
|
||||
readonly oneGroup: boolean
|
||||
readonly oneRow: boolean
|
||||
readonly equalHeight: boolean
|
||||
readonly fileWider: boolean
|
||||
readonly horizontalOverflow: boolean
|
||||
readonly noWrap: boolean
|
||||
}
|
||||
|
||||
/** Render stable relations instead of platform-dependent absolute coordinates. */
|
||||
function renderDraftRailGeometry(geometry: DraftRailGeometry): string {
|
||||
return [
|
||||
'# Mixed composer attachment rail',
|
||||
'',
|
||||
`- selection order: ${geometry.order.join(' > ')}`,
|
||||
`- one attachment group: ${String(geometry.oneGroup)}`,
|
||||
`- all cards share one row: ${String(geometry.oneRow)}`,
|
||||
`- every card is 64px high: ${String(geometry.equalHeight)}`,
|
||||
`- the file card is wider than an image: ${String(geometry.fileWider)}`,
|
||||
`- overflowing cards scroll horizontally: ${String(geometry.horizontalOverflow)}`,
|
||||
`- the rail does not wrap: ${String(geometry.noWrap)}`,
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
/** Browser-measured relations for one durable mixed-attachment message. */
|
||||
interface HistoryAttachmentGeometry {
|
||||
readonly order: readonly string[]
|
||||
readonly oneGroup: boolean
|
||||
readonly oneRow: boolean
|
||||
readonly equalHeight: boolean
|
||||
readonly imageIsTile: boolean
|
||||
readonly fileWider: boolean
|
||||
readonly wrapsWhenNeeded: boolean
|
||||
readonly rightAligned: boolean
|
||||
}
|
||||
|
||||
/** Render stable history-layout relations instead of absolute coordinates. */
|
||||
function renderHistoryAttachmentGeometry(geometry: HistoryAttachmentGeometry): string {
|
||||
return [
|
||||
'# Mixed history attachment flow',
|
||||
'',
|
||||
`- source order: ${geometry.order.join(' > ')}`,
|
||||
`- one attachment group: ${String(geometry.oneGroup)}`,
|
||||
`- file and image share one row: ${String(geometry.oneRow)}`,
|
||||
`- both cards are 64px high: ${String(geometry.equalHeight)}`,
|
||||
`- the image is a 64px tile: ${String(geometry.imageIsTile)}`,
|
||||
`- the file card is wider than the image: ${String(geometry.fileWider)}`,
|
||||
`- the group wraps when needed: ${String(geometry.wrapsWhenNeeded)}`,
|
||||
`- the group is right-aligned: ${String(geometry.rightAligned)}`,
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
describe('web e2e: generic file upload through the real assembly', () => {
|
||||
let scaffold: WebScaffold
|
||||
let browser: Browser
|
||||
let page: Page
|
||||
let tripwire: ReturnType<typeof watchConsole>
|
||||
const sessionEvents: SessionEvent[] = []
|
||||
|
||||
beforeAll(async () => {
|
||||
scaffold = await launchWebScaffold({
|
||||
compareReplaySession: true,
|
||||
// The override rescripts the recorded read arguments with a
|
||||
// `{{fromRequest:…}}` placeholder: the saved-copy path differs per run,
|
||||
// and the live handle line in the request carries the current one.
|
||||
...(MODE === 'record' ? {} : { replayFixture: FIXTURE, replayOverride: OVERRIDE, paceMs: 15 }),
|
||||
})
|
||||
scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) })
|
||||
browser = await chromium.launch()
|
||||
page = await newEnglishPage(browser)
|
||||
await page.setViewportSize({ width: 900, height: 900 })
|
||||
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 () => {
|
||||
await browser?.close()
|
||||
await scaffold?.close()
|
||||
})
|
||||
|
||||
it('uploads on pick, gates send on the staged receipt, and settles the turn (all modes)', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-file-upload-drive'))
|
||||
if (MODE !== 'record') {
|
||||
// Drift guard: the committed fixture must carry exactly the drive prompt.
|
||||
expect(fixtureUserPrompts(await readFile(FIXTURE, 'utf8'))).toEqual([PROMPT])
|
||||
}
|
||||
const input = page.locator('[data-composer-input]').first()
|
||||
await input.waitFor({ timeout: 10_000 })
|
||||
const modelTrigger = page.getByRole('button', { name: /^Select model, current/ })
|
||||
await modelTrigger.click()
|
||||
await page.getByRole('menuitem', { name: /^Model\b/ }).click()
|
||||
await page.getByRole('menuitemradio', { name: 'DeepSeek-V4-Flash-Vision-Exp' }).click()
|
||||
await expect.poll(() => modelTrigger.getAttribute('aria-label'), { timeout: 10_000 })
|
||||
.toContain('DeepSeek-V4-Flash-Vision-Exp')
|
||||
const imageBytes = await readFile(IMAGE_FIXTURE)
|
||||
// Pick through the composer's hidden file input: the upload RPC runs
|
||||
// immediately and the pending card appears before any prompt is typed.
|
||||
await page.locator('input[type="file"]').setInputFiles([
|
||||
{ name: FILE_NAME, mimeType: 'text/plain', buffer: Buffer.from(FILE_TEXT) },
|
||||
...IMAGE_NAMES.map(name => ({ name, mimeType: 'image/png', buffer: imageBytes })),
|
||||
])
|
||||
await page.getByTitle(FILE_NAME).waitFor({ timeout: 10_000 })
|
||||
const rail = page.getByRole('group', { name: 'Pending attachments' })
|
||||
await expect.poll(() => rail.locator(':scope > *').count(), { timeout: 10_000 })
|
||||
.toBe(IMAGE_NAMES.length + 1)
|
||||
const geometry = await rail.evaluate((element): DraftRailGeometry => {
|
||||
const cards = [...element.children] as HTMLElement[]
|
||||
const boxes = cards.map(card => card.getBoundingClientRect())
|
||||
const imageWidth = boxes[cards.findIndex(card => card.querySelector('img') !== null)]?.width ?? 0
|
||||
const fileWidth = boxes[cards.findIndex(card => card.querySelector('[title="poem.txt"]') !== null)]?.width ?? 0
|
||||
return {
|
||||
order: cards.map(card => card.querySelector('img')?.getAttribute('alt')
|
||||
?? card.querySelector<HTMLElement>('[title]')?.title ?? ''),
|
||||
oneGroup: document.querySelectorAll('[role="group"][aria-label="Pending attachments"]').length === 1,
|
||||
oneRow: boxes.every(box => Math.abs(box.top - (boxes[0]?.top ?? box.top)) < 0.5),
|
||||
equalHeight: boxes.every(box => Math.abs(box.height - 64) < 0.5),
|
||||
fileWider: fileWidth > imageWidth,
|
||||
horizontalOverflow: element.scrollWidth > element.clientWidth,
|
||||
noWrap: getComputedStyle(element).flexWrap === 'nowrap',
|
||||
}
|
||||
})
|
||||
await compareOrRefreshGolden(DRAFT_EXPECTED, renderDraftRailGeometry(geometry), MODE)
|
||||
for (const name of IMAGE_NAMES.slice(1)) {
|
||||
await page.getByRole('button', { name: `Remove image ${name}` }).click({ force: true })
|
||||
}
|
||||
await expect.poll(() => rail.locator(':scope > *').count(), { timeout: 10_000 }).toBe(2)
|
||||
await input.fill(PROMPT)
|
||||
// Send unlocks only after the upload receipt lands (the staged file gate).
|
||||
const send = page.getByRole('button', { name: 'Send message' })
|
||||
await send.waitFor({ state: 'visible', timeout: 15_000 })
|
||||
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) {
|
||||
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(',')}`)
|
||||
}
|
||||
const sessionId = await settled
|
||||
if (MODE === 'record') await recordFixture(scaffold, sessionId, FIXTURE)
|
||||
}, 200_000)
|
||||
|
||||
it.skipIf(MODE === 'record')('persists the file block and reads the stored copy with the real read tool', () => {
|
||||
const userMessage = sessionEvents.find(
|
||||
(event): event is Extract<SessionEvent, { type: 'user/message' }> =>
|
||||
event.type === 'user/message' && event.data.source.kind === 'user',
|
||||
)
|
||||
if (userMessage === undefined) throw new Error('the replayed turn recorded no user message')
|
||||
const fileBlock = userMessage.data.content.find(block => block.type === 'file')
|
||||
if (fileBlock?.type !== 'file') throw new Error('the user message carries no file block')
|
||||
expect(fileBlock.attachment.name).toBe(FILE_NAME)
|
||||
expect(fileBlock.attachment.bytes).toBe(Buffer.byteLength(FILE_TEXT))
|
||||
expect(String(fileBlock.attachment.attachmentId)).toMatch(/^sha256:[0-9a-f]{64}$/)
|
||||
|
||||
const readCall = sessionEvents.find(
|
||||
(event): event is Extract<SessionEvent, { type: 'tool/call' }> =>
|
||||
event.type === 'tool/call' && event.data.name === 'read',
|
||||
)
|
||||
if (readCall === undefined) throw new Error('the replayed turn did not call the read tool')
|
||||
expect(readCall.data.arguments).toContain(FILE_NAME)
|
||||
const readResult = sessionEvents.find(
|
||||
(event): event is Extract<SessionEvent, { type: 'tool/result' }> =>
|
||||
event.type === 'tool/result' && event.data.message.source.callId === readCall.data.callId,
|
||||
)
|
||||
if (readResult === undefined) throw new Error('the read call produced no durable result')
|
||||
const content = readResult.data.message.content[0]
|
||||
expect(content.isError).toBe(false)
|
||||
expect(content.content.filter(block => block.type === 'text').map(block => block.text).join(''))
|
||||
.toContain('UPLOAD_ROUND_OK')
|
||||
|
||||
const turnEnds = sessionEvents.filter(event => event.type === 'turn/end')
|
||||
expect(turnEnds.length).toBe(1)
|
||||
expect((turnEnds[0] as SessionEvent & { data: { reason: { kind: string } } }).data.reason.kind).toBe('completed')
|
||||
})
|
||||
|
||||
it.skipIf(MODE === 'record')('renders the durable file card beside the settled answer', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-file-upload-aria'))
|
||||
await expect.poll(() => page.getByText('UPLOAD_ROUND_OK', { exact: false }).count(), { timeout: 15_000 })
|
||||
.toBeGreaterThanOrEqual(1)
|
||||
await page.getByTitle(FILE_NAME).first().waitFor({ timeout: 10_000 })
|
||||
const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
|
||||
await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
|
||||
})
|
||||
|
||||
it.skipIf(MODE === 'record')('keeps a mixed durable message in one ordered wrapping attachment flow', async () => {
|
||||
const groups = page.locator('[data-message-attachments]')
|
||||
await expect.poll(() => groups.count(), { timeout: 10_000 }).toBe(1)
|
||||
const geometry = await groups.first().evaluate((element): HistoryAttachmentGeometry => {
|
||||
const cards = [...element.children] as HTMLElement[]
|
||||
const renderedCards = cards.map((card) => {
|
||||
const box = card.getBoundingClientRect()
|
||||
return box.width === 0 && box.height === 0 && card.firstElementChild instanceof HTMLElement
|
||||
? card.firstElementChild
|
||||
: card
|
||||
})
|
||||
const boxes = renderedCards.map(card => card.getBoundingClientRect())
|
||||
const imageIndex = cards.findIndex(card => card.querySelector('img') !== null)
|
||||
const fileIndex = cards.findIndex(card => card.getAttribute('title') === 'poem.txt')
|
||||
const imageBox = boxes[imageIndex]
|
||||
const fileBox = boxes[fileIndex]
|
||||
return {
|
||||
order: cards.map(card => card.getAttribute('title') ?? card.querySelector('img')?.getAttribute('alt') ?? ''),
|
||||
oneGroup: document.querySelectorAll('[data-message-attachments]').length === 1,
|
||||
oneRow: boxes.every(box => Math.abs(box.top - (boxes[0]?.top ?? box.top)) < 0.5),
|
||||
equalHeight: boxes.every(box => Math.abs(box.height - 64) < 0.5),
|
||||
imageIsTile: imageBox !== undefined && Math.abs(imageBox.width - 64) < 0.5,
|
||||
fileWider: fileBox !== undefined && imageBox !== undefined && fileBox.width > imageBox.width,
|
||||
wrapsWhenNeeded: getComputedStyle(element).flexWrap === 'wrap',
|
||||
rightAligned: getComputedStyle(element).justifyContent === 'flex-end',
|
||||
}
|
||||
})
|
||||
await compareOrRefreshGolden(HISTORY_EXPECTED, renderHistoryAttachmentGeometry(geometry), MODE)
|
||||
})
|
||||
|
||||
it.skipIf(MODE === 'record')('marks the durable file in Trajectory without copying the Chat card', async () => {
|
||||
await page.getByRole('tab', { name: 'Trajectory', exact: true }).click()
|
||||
await page.getByLabel('Trajectory timeline').waitFor({ timeout: 30_000 })
|
||||
await page.getByRole('row', { name: /Files ×1/ }).waitFor({ timeout: 10_000 })
|
||||
const snapshot = await captureStableAria(
|
||||
page,
|
||||
'[data-trajectory-row-key][aria-label*="Files ×1"]',
|
||||
scaffold.workspaceCwd,
|
||||
)
|
||||
await compareOrRefreshGolden(TRAJECTORY_EXPECTED, snapshot, MODE)
|
||||
})
|
||||
|
||||
it.skipIf(MODE === 'record')('stayed clean and kept the exact fixture inventory', async () => {
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
await assertFixtureInventory(SNAPSHOT_DIR, [
|
||||
'session.v2.jsonl', 'replay.override.json', 'ui.expected.md', 'trajectory.expected.md',
|
||||
])
|
||||
})
|
||||
})
|
||||
@@ -67,17 +67,26 @@ describe('web e2e: /goal human transcript presentation', () => {
|
||||
const typography = await commandInput.evaluate((element) => {
|
||||
const bubble = element.firstElementChild?.firstElementChild
|
||||
if (!(bubble instanceof HTMLElement)) throw new Error('command input bubble is missing')
|
||||
const chip = bubble.querySelector('[data-ref-chip="command"]')
|
||||
if (!(chip instanceof HTMLElement)) throw new Error('command chip is missing')
|
||||
const rootStyle = getComputedStyle(element)
|
||||
const bubbleStyle = getComputedStyle(bubble)
|
||||
const chipStyle = getComputedStyle(chip)
|
||||
return {
|
||||
fontFamily: bubbleStyle.fontFamily,
|
||||
parentFontFamily: rootStyle.fontFamily,
|
||||
fontSize: bubbleStyle.fontSize,
|
||||
lineHeight: bubbleStyle.lineHeight,
|
||||
chipText: chip.textContent,
|
||||
chipFontFamily: chipStyle.fontFamily,
|
||||
chipFontSize: chipStyle.fontSize,
|
||||
}
|
||||
})
|
||||
expect(typography).toMatchObject({ fontSize: '14px', lineHeight: '22px' })
|
||||
expect(typography.fontFamily).not.toBe(typography.parentFontFamily)
|
||||
expect(typography).toMatchObject({ fontSize: '14px', lineHeight: '22px', chipText: '/goal', chipFontSize: '14px' })
|
||||
// The bubble reads in the body face like a user bubble; only the command
|
||||
// chip carries the code face that marks the echoed token as a command.
|
||||
expect(typography.fontFamily).toBe(typography.parentFontFamily)
|
||||
expect(typography.chipFontFamily).not.toBe(typography.fontFamily)
|
||||
const resultRow = page.locator('[data-variant="others"]').filter({ hasText: 'No goal is currently set.' })
|
||||
await expect.poll(() => resultRow.count(), { timeout: 10_000 }).toBe(1)
|
||||
expect(await resultRow.getByText('goal', { exact: true }).count()).toBe(1)
|
||||
|
||||
@@ -106,7 +106,7 @@ it('accepts pasted images into the composer rail in order and removes them', asy
|
||||
// The rail is an accessible group holding the draft thumbnail (queried via
|
||||
// DOM: jsdom's a11y-visibility computation hides the composer subtree).
|
||||
const rail = await waitFor(() => {
|
||||
const el = document.querySelector('[role="group"][aria-label="Pending images"]')
|
||||
const el = document.querySelector('[role="group"][aria-label="Pending attachments"]')
|
||||
if (el === null) throw new Error('attachment rail missing')
|
||||
return el
|
||||
}, { timeout: 5_000 })
|
||||
@@ -137,23 +137,19 @@ it('accepts pasted images into the composer rail in order and removes them', asy
|
||||
if (remove.length !== 2) throw new Error('remove buttons missing')
|
||||
for (const button of remove) fireEvent.click(button)
|
||||
await waitFor(() => {
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending images"]')).toBeNull()
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).toBeNull()
|
||||
})
|
||||
|
||||
// An unsupported file announces a transient toast (the inline strip is
|
||||
// gone) and the banner dismisses itself after its hold-and-fade lifetime.
|
||||
// A non-image paste follows the generic-file path and remains in the
|
||||
// composer as a file card.
|
||||
fireEvent.paste(textarea, {
|
||||
clipboardData: {
|
||||
items: [{ kind: 'file', type: 'text/plain', getAsFile: () => new File(['x'], 'notes.txt', { type: 'text/plain' }) }],
|
||||
getData: () => '',
|
||||
},
|
||||
})
|
||||
const unsupportedMessage = 'Only PNG, JPG, WebP, and GIF images are supported'
|
||||
const toast = await screen.findByText(unsupportedMessage)
|
||||
expect(toast.closest('[role="alert"]')).not.toBeNull()
|
||||
await waitFor(() => {
|
||||
expect(screen.queryByText(unsupportedMessage)).toBeNull()
|
||||
}, { timeout: 6_000 })
|
||||
const files = await screen.findByRole('group', { name: 'Pending attachments' })
|
||||
expect(files.textContent).toContain('notes.txt')
|
||||
})
|
||||
|
||||
it('accepts a whole-page drop under the limits-labeled overlay and refuses an over-limit batch at intake', async () => {
|
||||
@@ -178,15 +174,15 @@ it('accepts a whole-page drop under the limits-labeled overlay and refuses an ov
|
||||
const dataTransfer = { types: ['Files'], files: [image], dropEffect: 'none' }
|
||||
fireEvent.dragEnter(document.body, { dataTransfer })
|
||||
const overlay = await screen.findByRole('status')
|
||||
expect(overlay.textContent).toContain('Drag images here to add them')
|
||||
expect(overlay.textContent).toContain('Drag files or images here to add them')
|
||||
await waitFor(() => {
|
||||
expect(overlay.textContent).toContain('Up to 20 images, 5MB each')
|
||||
expect(overlay.textContent).toContain('Image limit: up to 20 images, 5MB each')
|
||||
})
|
||||
|
||||
// Dropping on the transcript area (not the composer card) lands in the rail.
|
||||
fireEvent.drop(document.body, { dataTransfer })
|
||||
await waitFor(() => {
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending images"]')
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending attachments"]')
|
||||
if (rail === null) throw new Error('attachment rail missing after page drop')
|
||||
expect([...rail.querySelectorAll('img')].map(img => img.getAttribute('alt'))).toEqual(['dropped.png'])
|
||||
}, { timeout: 5_000 })
|
||||
@@ -206,7 +202,7 @@ it('accepts a whole-page drop under the limits-labeled overlay and refuses an ov
|
||||
const limitMessage = 'A message can include up to 20 images'
|
||||
const banner = await screen.findByText(limitMessage)
|
||||
expect(banner.closest('[role="alert"]')).not.toBeNull()
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending images"]')
|
||||
const rail = document.querySelector('[role="group"][aria-label="Pending attachments"]')
|
||||
expect([...(rail?.querySelectorAll('img') ?? [])]).toHaveLength(1)
|
||||
})
|
||||
|
||||
@@ -233,7 +229,7 @@ it('renders a host dimension rejection with the projected 2000px limit', async (
|
||||
},
|
||||
})
|
||||
await waitFor(() => {
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending images"]')).not.toBeNull()
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).not.toBeNull()
|
||||
})
|
||||
fireEvent.keyDown(textarea, { key: 'Enter' })
|
||||
|
||||
@@ -245,5 +241,5 @@ it('renders a host dimension rejection with the projected 2000px limit', async (
|
||||
"text": "Image sides must be at most 2000px; downscale it and try again",
|
||||
}
|
||||
`)
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending images"]')).not.toBeNull()
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).not.toBeNull()
|
||||
})
|
||||
@@ -296,16 +296,15 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
|
||||
const recoveryTripwire = watchConsole(recoveryPage)
|
||||
const sockets: WebSocketRoute[] = []
|
||||
let rejectConnections = false
|
||||
let holdConnections = false
|
||||
await recoveryPage.routeWebSocket('**/api/remote.mux', (route) => {
|
||||
sockets.push(route)
|
||||
if (rejectConnections) {
|
||||
void route.close({ code: 4001, reason: 'connection recovery test' })
|
||||
return
|
||||
}
|
||||
if (rejectConnections || holdConnections) return
|
||||
route.connectToServer()
|
||||
})
|
||||
onTestFailed(() => saveFailureShot(recoveryPage, 'web-e2e-connection-recovery'))
|
||||
try {
|
||||
await recoveryPage.clock.install()
|
||||
await recoveryPage.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
|
||||
await recoveryPage.waitForSelector('[class*="frame"]', { timeout: 30_000 })
|
||||
await expect.poll(() => sockets.length).toBe(1)
|
||||
@@ -316,16 +315,16 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
|
||||
name: 'Disconnected, reconnect now', exact: true,
|
||||
})
|
||||
await offline.waitFor({ timeout: 2_000 })
|
||||
await recoveryPage.waitForTimeout(750)
|
||||
await recoveryPage.clock.fastForward(60_000)
|
||||
expect(sockets).toHaveLength(1)
|
||||
|
||||
await recoveryPage.context().setOffline(false)
|
||||
await expect.poll(() => recoveryPage.evaluate(() => navigator.onLine)).toBe(true)
|
||||
const connecting = recoveryPage.getByRole('button', {
|
||||
name: 'Connecting, restart now', exact: true,
|
||||
name: 'Reconnecting automatically, reconnect now', exact: true,
|
||||
})
|
||||
await connecting.waitFor({ timeout: 10_000 })
|
||||
expect(await connecting.innerText()).toMatch(/^Connecting\.{1,3}$/)
|
||||
expect(await connecting.innerText()).toMatch(/^Reconnecting\.{1,3}$/)
|
||||
const connectingGeometry = await connectionIndicatorGeometry(connecting)
|
||||
expect(await connectionIndicatorTextAlignment(connecting)).toBe('left')
|
||||
await connecting.hover()
|
||||
@@ -333,13 +332,21 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
|
||||
expect(await connectionIndicatorGeometry(connecting)).toEqual(connectingGeometry)
|
||||
await recoveryPage.mouse.move(0, 0)
|
||||
|
||||
await expect.poll(() => sockets.length, { timeout: 40_000 }).toBe(7)
|
||||
const indicator = recoveryPage.getByRole('button', {
|
||||
name: 'Disconnected, reconnect now', exact: true,
|
||||
})
|
||||
await indicator.waitFor({ timeout: 10_000 })
|
||||
for (let count = 2; count <= 9; count++) {
|
||||
await recoveryPage.clock.fastForward(10_000)
|
||||
await expect.poll(() => sockets.length).toBe(count)
|
||||
if (count === 2) {
|
||||
await recoveryPage.clock.fastForward(1_000)
|
||||
expect(sockets).toHaveLength(count)
|
||||
}
|
||||
await sockets.at(-1)!.close({ code: 4001, reason: 'connection recovery test' })
|
||||
// Drain the close event's promise continuations before advancing the next retry timer.
|
||||
await recoveryPage.evaluate(() => {})
|
||||
}
|
||||
const indicator = connecting
|
||||
expect(await connectionIndicatorGeometry(indicator)).toEqual(connectingGeometry)
|
||||
expect(await connectionIndicatorTextAlignment(indicator)).toBe('left')
|
||||
await indicator.hover()
|
||||
const snapshot = await captureStableAria(recoveryPage, '[class*="footArea"]', scaffold.workspaceCwd)
|
||||
await compareOrRefreshGolden(CONNECTION_ERROR_EXPECTED, snapshot, MODE)
|
||||
const style = await indicator.evaluate((element) => {
|
||||
@@ -362,6 +369,20 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
|
||||
expect(style.color).toBe(style.referenceColor)
|
||||
expect(await indicator.locator('svg').count()).toBe(1)
|
||||
expect(await indicator.getAttribute('title')).toBeNull()
|
||||
rejectConnections = false
|
||||
await recoveryPage.clock.fastForward(10_000)
|
||||
await expect.poll(() => sockets.length).toBe(10)
|
||||
const automaticRecovery = recoveryPage.getByRole('status')
|
||||
await automaticRecovery.waitFor({ timeout: 10_000 })
|
||||
expect(await automaticRecovery.innerText()).toBe('Connected')
|
||||
await recoveryPage.clock.fastForward(2_000)
|
||||
await automaticRecovery.waitFor({ state: 'detached' })
|
||||
|
||||
holdConnections = true
|
||||
await sockets.at(-1)!.close({ code: 4001, reason: 'manual recovery test' })
|
||||
await connecting.waitFor()
|
||||
await recoveryPage.clock.fastForward(500)
|
||||
await expect.poll(() => sockets.length).toBe(11)
|
||||
const idleBackground = await indicator.evaluate(element => getComputedStyle(element).backgroundColor)
|
||||
await indicator.hover()
|
||||
expect(await indicator.innerText()).toBe('Reconnect now')
|
||||
@@ -370,19 +391,20 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
|
||||
await recoveryPage.mouse.down()
|
||||
await expect.poll(() => indicator.evaluate(element => getComputedStyle(element).backgroundColor))
|
||||
.not.toBe(hoverBackground)
|
||||
rejectConnections = false
|
||||
holdConnections = false
|
||||
await recoveryPage.mouse.up()
|
||||
|
||||
await expect.poll(() => sockets.length).toBe(8)
|
||||
await expect.poll(() => sockets.length).toBe(12)
|
||||
const recovered = recoveryPage.getByRole('status')
|
||||
await recovered.waitFor({ timeout: 10_000 })
|
||||
expect(await recovered.innerText()).toBe('Connected')
|
||||
expect(await connectionIndicatorGeometry(recovered)).toEqual(connectingGeometry)
|
||||
expect(await connectionIndicatorTextAlignment(recovered)).toBe('left')
|
||||
await recoveryPage.clock.fastForward(2_000)
|
||||
await recovered.waitFor({ state: 'detached', timeout: 5_000 })
|
||||
expect(recoveryTripwire.pageErrors).toEqual([])
|
||||
expect(recoveryTripwire.warnings.filter(warning => /connection lost, retry #[1-6]/i.test(warning)))
|
||||
.toHaveLength(7)
|
||||
expect(recoveryTripwire.warnings.filter(warning => /connection lost, retry #/i.test(warning)))
|
||||
.toHaveLength(11)
|
||||
} finally {
|
||||
await recoveryPage.close()
|
||||
}
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
// Web e2e scenario: message IconActions + clocks. Cold-seeds a deterministic
|
||||
// completed-turn-tail fork case (zero model calls) and pins the settled
|
||||
// conversation aria after the footers are focus-revealed — the surface package
|
||||
// jsdom tests cannot substitute for (docs/testing.md snapshot rule).
|
||||
// completed-turn-tail fork case with an unchanged resume header (zero model
|
||||
// calls) and pins the settled conversation aria after the footers are
|
||||
// focus-revealed — the surface package jsdom tests cannot substitute for
|
||||
// (docs/testing.md snapshot rule).
|
||||
import { mkdir, readFile, writeFile } from 'node:fs/promises'
|
||||
import { join } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
@@ -70,6 +71,10 @@ function completedTailFixture(raw: string): string {
|
||||
},
|
||||
}
|
||||
})
|
||||
const inheritedHeader = kept.findLast(event => event.type === 'request/header')
|
||||
if (inheritedHeader?.type !== 'request/header') {
|
||||
throw new Error('borrowed recording has no request header')
|
||||
}
|
||||
let seq = (kept.at(-1)?.seq ?? -1) + 1
|
||||
let time = (kept.at(-1)?.time ?? -1) + 1
|
||||
const at = (event: Record<string, unknown>): { seq: number; time: number } & Record<string, unknown> => ({
|
||||
@@ -109,6 +114,7 @@ function completedTailFixture(raw: string): string {
|
||||
surfaceOp: 'append',
|
||||
}),
|
||||
at({ type: 'step/start', data: { turn: 2, step: 1 } }),
|
||||
at({ type: 'request/header', data: { header: inheritedHeader.data.header, reason: 'resume' } }),
|
||||
at({
|
||||
type: 'assistant/message',
|
||||
data: {
|
||||
@@ -149,6 +155,9 @@ describe('web e2e: message IconActions and clocks on settled history', () => {
|
||||
await writeFile(join(sessionCwd, 'b.txt'), 'beta\n')
|
||||
const raw = completedTailFixture(await readFile(SEED, 'utf8'))
|
||||
expect(fixtureUserPrompts(raw), 'adapted seed must carry both prompts').toEqual([PROMPT, SECOND_PROMPT])
|
||||
expect(parseSeedFixture(raw).events.flatMap(event => event.type === 'request/header'
|
||||
? [event.data.reason]
|
||||
: []), 'adapted seed must carry an unchanged resume header').toEqual(['initial', 'resume'])
|
||||
await seedSession(scaffold, raw, SEED_ID)
|
||||
browser = await chromium.launch()
|
||||
page = await newEnglishPage(browser)
|
||||
@@ -172,6 +181,10 @@ describe('web e2e: message IconActions and clocks on settled history', () => {
|
||||
await sessionRow.click()
|
||||
await expect.poll(() => page.getByText(MID_TURN_TEXT, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
|
||||
await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
|
||||
await expect.poll(
|
||||
() => page.getByRole('button', { name: 'System prompt', exact: true }).count(),
|
||||
{ timeout: 10_000 },
|
||||
).toBe(1)
|
||||
|
||||
// Focus-reveal the footers (hover:hover keeps them opacity-hidden until
|
||||
// hover/focus-within). Branch renders only under assistant answers — user
|
||||
|
||||
@@ -26,6 +26,8 @@ const LAYOUT_EXPECTED = join(SNAPSHOT_DIR, 'layout.expected.md')
|
||||
const PRESERVED_EXPECTED = join(SNAPSHOT_DIR, 'preserved.expected.md')
|
||||
const PRESERVED_EXPANDED_EXPECTED = join(SNAPSHOT_DIR, 'preserved-expanded.expected.md')
|
||||
const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md')
|
||||
const SENDING_EXPECTED = join(SNAPSHOT_DIR, 'sending.expected.md')
|
||||
const FAILED_EXPECTED = join(SNAPSHOT_DIR, 'failed.expected.md')
|
||||
const MODE = webSnapshotMode()
|
||||
|
||||
const ACTIVE_PROMPT = 'Reply with a one-sentence description of event sourcing, then stop.'
|
||||
@@ -34,6 +36,7 @@ const EDIT = 'Queue item to edit'
|
||||
const EDITED = 'Edited queue item'
|
||||
const TAIL = 'Queue item preserved after stop'
|
||||
const WAKE = 'Wake the preserved queue'
|
||||
const FAILED = 'Queue submission to retry'
|
||||
|
||||
/** Durable turn-end classifications observed by the scenario. */
|
||||
function turnEndReasons(events: readonly SessionEvent[]): string[] {
|
||||
@@ -93,15 +96,44 @@ describe('web e2e: queue row actions', () => {
|
||||
await input.press('Enter')
|
||||
await expect.poll(() => existsSync(readyFile), { timeout: 15_000 }).toBe(true)
|
||||
|
||||
for (const text of [REMOVE, EDIT]) {
|
||||
// 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)
|
||||
const received = Promise.withResolvers<undefined>()
|
||||
const release = Promise.withResolvers<undefined>()
|
||||
await page.route('**/api/session/prompt', async (route) => {
|
||||
received.resolve(undefined)
|
||||
await release.promise
|
||||
await route.continue()
|
||||
}, { times: 1 })
|
||||
try {
|
||||
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')
|
||||
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)
|
||||
}
|
||||
await expect.poll(() => page.getByRole('button', { name: 'Remove queued message' }).isEnabled()).toBe(true)
|
||||
expect(await page.locator('[data-queue-dock] [data-submission-echo]').count()).toBe(0)
|
||||
expect(await page.locator('[data-queue-dock]').getByRole('status').count()).toBe(0)
|
||||
await input.fill(EDIT)
|
||||
await input.press('Enter')
|
||||
const queueHeader = page.getByRole('button', { name: '2 queued messages' })
|
||||
await expect.poll(() => queueHeader.getAttribute('aria-expanded'), { timeout: 10_000 })
|
||||
.toBe('false')
|
||||
await expect.poll(() => queueHeader.getByRole('status').count(), { timeout: 10_000 }).toBe(0)
|
||||
const collapsedSnapshot = await captureStableAria(
|
||||
page,
|
||||
'[class*="centerCol"]',
|
||||
@@ -110,7 +142,7 @@ describe('web e2e: queue row actions', () => {
|
||||
await compareOrRefreshGolden(COLLAPSED_EXPECTED, collapsedSnapshot, MODE)
|
||||
await queueHeader.click()
|
||||
await expect.poll(
|
||||
() => page.getByRole('button', { name: 'Remove queued message' }).count(),
|
||||
() => page.getByRole('button', { name: 'Remove queued message', disabled: false }).count(),
|
||||
{ timeout: 10_000 },
|
||||
).toBe(2)
|
||||
|
||||
@@ -150,13 +182,36 @@ describe('web e2e: queue row actions', () => {
|
||||
const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
|
||||
await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
|
||||
expect(sessionEvents.filter(event => event.type === 'user/message' && event.data.source.kind === 'user')).toHaveLength(1)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
await page.route('**/api/session/prompt', async (route) => {
|
||||
const envelope = route.request().postDataJSON() as { rpcId: string }
|
||||
await route.fulfill({
|
||||
status: 200,
|
||||
contentType: 'application/json',
|
||||
json: {
|
||||
type: 'server-response', rpcId: envelope.rpcId,
|
||||
result: {
|
||||
ok: false,
|
||||
error: { code: 'session/agent-busy', message: 'Queue submission failed', details: { reason: 'admission refused' } },
|
||||
},
|
||||
},
|
||||
})
|
||||
}, { times: 1 })
|
||||
await input.fill(FAILED)
|
||||
await input.press('Enter')
|
||||
const failure = page.getByRole('alert').filter({ hasText: 'Queue submission failed' })
|
||||
await failure.waitFor()
|
||||
await expect.poll(() => input.textContent()).toBe(FAILED)
|
||||
expect(await page.locator('[data-queue-dock] [data-submission-echo]').count()).toBe(0)
|
||||
const failed = [
|
||||
await failure.ariaSnapshot(),
|
||||
await captureStableAria(page, '[data-composer-card]', scaffold.workspaceCwd),
|
||||
].join('\n')
|
||||
await compareOrRefreshGolden(FAILED_EXPECTED, failed, MODE)
|
||||
|
||||
await input.fill(TAIL)
|
||||
await input.press('Enter')
|
||||
await expect.poll(
|
||||
() => page.getByRole('button', { name: 'Remove queued message' }).count(),
|
||||
() => page.getByRole('button', { name: 'Remove queued message', disabled: false }).count(),
|
||||
{ timeout: 10_000 },
|
||||
).toBe(2)
|
||||
|
||||
@@ -186,6 +241,8 @@ describe('web e2e: queue row actions', () => {
|
||||
? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
|
||||
: [])).toEqual([ACTIVE_PROMPT, EDITED, TAIL, WAKE])
|
||||
await expect.poll(() => page.locator('[data-queue-dock]').count()).toBe(0)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
}, 120_000)
|
||||
|
||||
it.skipIf(MODE === 'record')('orders Todo before Goal and Queue on one responsive card column', async () => {
|
||||
@@ -232,6 +289,7 @@ describe('web e2e: queue row actions', () => {
|
||||
const queueHeader = page.getByRole('button', { name: '2 queued messages' })
|
||||
await expect.poll(() => queueHeader.getAttribute('aria-expanded'), { timeout: 10_000 })
|
||||
.toBe('false')
|
||||
await expect.poll(() => queueHeader.getByRole('status').count(), { timeout: 10_000 }).toBe(0)
|
||||
|
||||
const layoutSnapshot = await captureStableAria(
|
||||
page,
|
||||
@@ -241,9 +299,13 @@ describe('web e2e: queue row actions', () => {
|
||||
await compareOrRefreshGolden(LAYOUT_EXPECTED, layoutSnapshot, MODE)
|
||||
|
||||
const expectAlignedContextPanels = async () => {
|
||||
const queuePanelBox = await page.locator('[data-queue-dock] > div').boundingBox()
|
||||
const todoBox = await page.locator('[data-testid="todo-panel"]').boundingBox()
|
||||
const goalBox = await page.locator('[data-goal-bar] > div').boundingBox()
|
||||
// Sample one layout: the responsive grid can move between separate browser round trips.
|
||||
const [queuePanelBox, todoBox, goalBox] = await page.evaluate(() => [
|
||||
'[data-queue-dock] > div', '[data-testid="todo-panel"]', '[data-goal-bar] > div',
|
||||
].map((selector) => {
|
||||
const box = document.querySelector(selector)?.getBoundingClientRect()
|
||||
return box === undefined ? null : { x: box.x, y: box.y, width: box.width }
|
||||
}))
|
||||
expect(queuePanelBox).not.toBeNull()
|
||||
expect(todoBox).not.toBeNull()
|
||||
expect(goalBox).not.toBeNull()
|
||||
@@ -282,6 +344,7 @@ describe('web e2e: queue row actions', () => {
|
||||
[
|
||||
'collapsed.expected.md', 'editing.expected.md', 'layout.expected.md',
|
||||
'preserved.expected.md', 'preserved-expanded.expected.md', 'ui.expected.md',
|
||||
'sending.expected.md', 'failed.expected.md',
|
||||
],
|
||||
)
|
||||
})
|
||||
|
||||
@@ -105,7 +105,7 @@ describe('web e2e: queued image submission', () => {
|
||||
await dockThumb.waitFor({ timeout: 15_000 })
|
||||
await expect.poll(() => dockThumb.getAttribute('src')).toMatch(/^blob:/)
|
||||
await page.getByText(QUEUED_TEXT, { exact: true }).waitFor()
|
||||
await page.getByRole('button', { name: 'Remove queued message' }).waitFor({ timeout: 15_000 })
|
||||
await page.getByRole('button', { name: 'Remove queued message', disabled: false }).waitFor({ timeout: 15_000 })
|
||||
const queuedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
|
||||
await compareOrRefreshGolden(QUEUED_EXPECTED, queuedSnapshot, MODE)
|
||||
|
||||
|
||||
+46
-12
@@ -192,7 +192,18 @@ const INSTALL_ANCHOR = join(REPO_ROOT, 'apps/cli/package.json')
|
||||
const REPLAY_PROVIDERS = [{
|
||||
id: 'deepseek-official',
|
||||
name: 'DeepSeek',
|
||||
models: [{ id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', contextWindow: 128_000 }],
|
||||
models: [
|
||||
{ id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', contextWindow: 128_000 },
|
||||
{
|
||||
id: 'deepseek-v4-flash-vision-exp',
|
||||
name: 'DeepSeek-V4-Flash-Vision-Exp',
|
||||
contextWindow: 1_000_000,
|
||||
inputModalities: ['text', 'image'] as const,
|
||||
defaultMaxTokens: 256_000,
|
||||
reasoningEfforts: ['off', 'low', 'high', 'max'],
|
||||
defaultReasoningEffort: 'high',
|
||||
},
|
||||
],
|
||||
}]
|
||||
|
||||
/**
|
||||
@@ -819,6 +830,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
|
||||
replayFixture,
|
||||
mode,
|
||||
`http://${browserHost}:${port}`,
|
||||
harnessHome,
|
||||
)
|
||||
} catch (error) {
|
||||
failures.push(error)
|
||||
@@ -953,6 +965,7 @@ function stableSessionFixture(
|
||||
session: Session,
|
||||
existing: string,
|
||||
workspaceCwd: string,
|
||||
harnessHome: string,
|
||||
): string {
|
||||
const prepared = prepareSessionSnapshotFixtureForComparison(
|
||||
normalizeWebSessionVolatiles(rawSessionLog(session), workspaceCwd),
|
||||
@@ -965,6 +978,7 @@ function stableSessionFixture(
|
||||
})
|
||||
const fresh = scrubSessionSnapshot(stabilized)
|
||||
.split(session.id).join('{{sessionId}}')
|
||||
.split(harnessHome).join('{{harnessHome}}')
|
||||
const stable = redactSessionSnapshotIds(stabilizeFixtureMessageIds([fresh], [existing]))[0]
|
||||
if (stable === undefined) throw new Error('session harvest produced no stabilized fixture')
|
||||
return stable
|
||||
@@ -975,6 +989,7 @@ async function assertReplaySession(
|
||||
fixturePath: string,
|
||||
mode: WebSnapshotMode,
|
||||
webUrl: string,
|
||||
harnessHome: string,
|
||||
): Promise<void> {
|
||||
let expected = await readFile(fixturePath, 'utf8')
|
||||
const fixtureDir = dirname(fixturePath)
|
||||
@@ -997,7 +1012,7 @@ async function assertReplaySession(
|
||||
if (sessionCwd === undefined) throw new Error(`${fixturePath}: replayed session has no cwd`)
|
||||
const actual = rawSessionLog(session)
|
||||
if (mode === 'refresh' && writesCurrentSessionFixtures(manifest, mode)) {
|
||||
expected = stableSessionFixture(session, expected, sessionCwd)
|
||||
expected = stableSessionFixture(session, expected, sessionCwd, harnessHome)
|
||||
expectedPath = recordedSessionFixturePath(fixturePath, session.header.version)
|
||||
await writeFile(expectedPath, expected)
|
||||
}
|
||||
@@ -1010,8 +1025,11 @@ async function assertReplaySession(
|
||||
sessionIds: typeof expectedHeader.id === 'string' ? [expectedHeader.id] : [],
|
||||
cwd: typeof expectedHeader.cwd === 'string' ? expectedHeader.cwd : '\0no-cwd\0',
|
||||
}
|
||||
expect(normalizeSessionSnapshots([normalizeWebSessionVolatiles(actual)], actualContext)[0], `${fixturePath}: persisted replay`)
|
||||
.toBe(normalizeSessionSnapshots([normalizeWebSessionVolatiles(expected)], expectedContext)[0])
|
||||
const actualSnapshot = normalizeSessionSnapshots([normalizeWebSessionVolatiles(actual)], actualContext)[0]
|
||||
?.split(harnessHome).join('{{harnessHome}}')
|
||||
const expectedSnapshot = normalizeSessionSnapshots([normalizeWebSessionVolatiles(expected)], expectedContext)[0]
|
||||
?.split(harnessHome).join('{{harnessHome}}')
|
||||
expect(actualSnapshot, `${fixturePath}: persisted replay`).toBe(expectedSnapshot)
|
||||
|
||||
if (manifest.header?.pin !== true) return
|
||||
const normalizePrompt = (value: string): string => value
|
||||
@@ -1032,7 +1050,7 @@ async function assertReplaySession(
|
||||
|
||||
/**
|
||||
* Record-mode fixture write-back: harvest the live session, scrub request
|
||||
* headers to {{system}}/{{tools}}, tokenize the run-local cwd, redact opaque
|
||||
* headers to {{system}}/{{tools}}, tokenize the run-local cwd and Harness Home, redact opaque
|
||||
* identities with typed relationship-preserving tokens, and write the fixture.
|
||||
* A manifest-retained historical generation makes the write-back a no-op.
|
||||
* @param scaffold - the record-mode scaffold.
|
||||
@@ -1048,7 +1066,12 @@ export async function recordFixture(scaffold: WebScaffold, sessionId: SessionId,
|
||||
const target = recordedSessionFixturePath(fixturePath, agent.session.header.version)
|
||||
const existingPath = existsSync(target) ? target : fixturePath
|
||||
const existing = existsSync(existingPath) ? await readFile(existingPath, 'utf8') : ''
|
||||
await writeFile(target, stableSessionFixture(agent.session, existing, scaffold.workspaceCwd))
|
||||
await writeFile(target, stableSessionFixture(
|
||||
agent.session,
|
||||
existing,
|
||||
scaffold.workspaceCwd,
|
||||
scaffold.harnessHome,
|
||||
))
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1078,8 +1101,8 @@ export function fixtureIdentity(
|
||||
|
||||
/**
|
||||
* Realize a recorded seed fixture against one scaffold: substitute the
|
||||
* `{{sessionId}}`/`{{cwd}}` placeholders and rewrite the recorded cwd to the
|
||||
* scaffold's workspace. Idempotent, so a caller may realize early (e.g. to
|
||||
* `{{sessionId}}`/`{{cwd}}`/`{{harnessHome}}` placeholders and rewrite the
|
||||
* recorded cwd to the scaffold's workspace. Idempotent, so a caller may realize early (e.g. to
|
||||
* price content exactly as the host will fold it) and still pass the result
|
||||
* through {@link seedSession}.
|
||||
* @param scaffold - the booted scaffold whose workspace the seed targets.
|
||||
@@ -1104,6 +1127,7 @@ export function realizeSeedFixture(scaffold: WebScaffold, fixtureText: string, i
|
||||
.replace(/\{\{session:([2-9]\d*)\}\}/g, (_token, ordinal: string) => `${id}-child-${ordinal}`)
|
||||
.replace(/\{\{(message|approval|workflow|command|rpc|retry|id):([1-9]\d*)\}\}/g, (_token, kind: string, ordinal: string) =>
|
||||
fixtureIdentity(kind as 'message' | 'approval' | 'workflow' | 'command' | 'rpc' | 'retry' | 'id', Number(ordinal)))
|
||||
.split('{{harnessHome}}').join(scaffold.harnessHome)
|
||||
.split('{{cwd}}').join(scaffold.workspaceCwd)
|
||||
return result
|
||||
})
|
||||
@@ -1373,20 +1397,30 @@ function normalizeAria(snapshot: string, workspaceCwd: string, age: boolean): st
|
||||
* @param selector - the region locator selector.
|
||||
* @param workspaceCwd - normalization input.
|
||||
* @param options - `normalizeAge` collapses relative-time buckets to `{{age}}`
|
||||
* for a region whose rows are dated from live wall-clock state.
|
||||
* for a region whose rows are dated from live wall-clock state;
|
||||
* `replacements` tokenizes scenario-owned values before generic normalization.
|
||||
* @returns the stable normalized snapshot.
|
||||
*/
|
||||
export async function captureStableAria(
|
||||
page: Page,
|
||||
selector: string,
|
||||
workspaceCwd: string,
|
||||
options: { normalizeAge?: boolean } = {},
|
||||
options: {
|
||||
normalizeAge?: boolean
|
||||
replacements?: readonly (readonly [value: string, token: string])[]
|
||||
} = {},
|
||||
): Promise<string> {
|
||||
const region = page.locator(selector).first()
|
||||
const age = options.normalizeAge === true
|
||||
let previous = normalizeAria(await region.ariaSnapshot(), workspaceCwd, age)
|
||||
const normalize = (snapshot: string): string => {
|
||||
for (const [value, token] of options.replacements ?? []) {
|
||||
snapshot = snapshot.split(value).join(token)
|
||||
}
|
||||
return normalizeAria(snapshot, workspaceCwd, age)
|
||||
}
|
||||
let previous = normalize(await region.ariaSnapshot())
|
||||
await expect.poll(async () => {
|
||||
const current = normalizeAria(await region.ariaSnapshot(), workspaceCwd, age)
|
||||
const current = normalize(await region.ariaSnapshot())
|
||||
const stable = current === previous
|
||||
previous = current
|
||||
return stable
|
||||
|
||||
@@ -18,10 +18,11 @@ import {
|
||||
webSnapshotMode,
|
||||
type WebScaffold,
|
||||
} from './scaffold.ts'
|
||||
import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
|
||||
import { connectFreshWorkspace, newEnglishPage, saveFailureShot, writeComposerDraft } from './support.ts'
|
||||
|
||||
const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/skill-invocation-policy', import.meta.url))
|
||||
const MENU_EXPECTED = join(SNAPSHOT_DIR, 'menu.expected.md')
|
||||
const FUZZY_MENU_EXPECTED = join(SNAPSHOT_DIR, 'menu-fuzzy.expected.md')
|
||||
const MODE = webSnapshotMode()
|
||||
|
||||
interface SeedSkill {
|
||||
@@ -111,8 +112,16 @@ describe('web e2e: skill invocation policy through the real host', () => {
|
||||
|
||||
const snapshot = await captureStableAria(page, '[role="listbox"]', scaffold.workspaceCwd)
|
||||
await compareOrRefreshGolden(MENU_EXPECTED, snapshot, MODE)
|
||||
|
||||
// Discovery needs no prefix: an in-order subsequence of one skill name
|
||||
// ranks that skill alone, through the ranker the command group uses.
|
||||
await writeComposerDraft(page, input, '/plcyusr')
|
||||
await expect.poll(() => menu.getByRole('option').count(), { timeout: 10_000 }).toBe(1)
|
||||
expect(await menu.getByRole('option', { name: /policy-user-only/ }).count()).toBe(1)
|
||||
const fuzzySnapshot = await captureStableAria(page, '[role="listbox"]', scaffold.workspaceCwd)
|
||||
await compareOrRefreshGolden(FUZZY_MENU_EXPECTED, fuzzySnapshot, MODE)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
await assertFixtureInventory(SNAPSHOT_DIR, ['menu.expected.md'])
|
||||
await assertFixtureInventory(SNAPSHOT_DIR, ['menu-fuzzy.expected.md', 'menu.expected.md'])
|
||||
})
|
||||
})
|
||||
@@ -130,6 +130,10 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
|
||||
await settled
|
||||
const process = page.getByRole('button', { name: 'Thought for a while', exact: true })
|
||||
await process.waitFor({ state: 'visible', timeout: 10_000 })
|
||||
// The chip derives from the step's logged injection, so it must survive
|
||||
// every later Node rebuild of the Turn (process publication, turn close).
|
||||
expect(await bubble.count()).toBe(1)
|
||||
expect(await bubble.textContent()).toBe(`/${SKILL_NAME}`)
|
||||
await expandOwningTurnProcess(page, injectionFlow)
|
||||
const injectionRow = page.getByRole('button', { name: `Context injection ${SKILL_NAME}` })
|
||||
await injectionRow.click()
|
||||
|
||||
@@ -27,6 +27,8 @@
|
||||
- textbox "Message or run a task... / commands, @ files or sessions"
|
||||
- button "Commands":
|
||||
- img
|
||||
- button "Add attachment":
|
||||
- img
|
||||
- 'button "Access mode, current: Workspace Write"': Workspace Write
|
||||
- button "Select model, current streaming-fence-highlight-test/streaming-fence":
|
||||
- text: streaming-fence-highlight-test/streaming-fence
|
||||
|
||||
@@ -33,7 +33,7 @@ it('paints the submission echo on the send keystroke and swaps it for the durabl
|
||||
},
|
||||
})
|
||||
await waitFor(() => {
|
||||
if (document.querySelector('[role="group"][aria-label="Pending images"] img') === null) {
|
||||
if (document.querySelector('[role="group"][aria-label="Pending attachments"] img') === null) {
|
||||
throw new Error('attachment rail missing')
|
||||
}
|
||||
}, { timeout: 5_000 })
|
||||
@@ -53,7 +53,7 @@ it('paints the submission echo on the send keystroke and swaps it for the durabl
|
||||
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 images"]')).toBeNull()
|
||||
expect(document.querySelector('[role="group"][aria-label="Pending attachments"]')).toBeNull()
|
||||
|
||||
// The fixture's durable user/message (source.rpcId echoes the prompt
|
||||
// requestId) replaces the echo: one bubble, no marker left, and the image
|
||||
|
||||
@@ -63,6 +63,7 @@
|
||||
"tests/composer-draft-scroll.e2e.ts",
|
||||
"tests/cordis-tool-round.e2e.ts",
|
||||
"tests/web-search-round.e2e.ts",
|
||||
"tests/file-upload-round.e2e.ts",
|
||||
"tests/message-actions.e2e.ts",
|
||||
"tests/message-feedback.e2e.ts",
|
||||
"tests/message-feedback-layout.e2e.ts",
|
||||
@@ -72,6 +73,7 @@
|
||||
"tests/math-rendering.e2e.ts",
|
||||
"tests/markdown-cjk-strong.e2e.ts",
|
||||
"tests/markdown-inline-code-links.e2e.ts",
|
||||
"tests/clickable-links-gallery.e2e.ts",
|
||||
"tests/queue-actions.e2e.ts",
|
||||
"tests/queue-image.e2e.ts",
|
||||
"tests/skill-invocation-policy.e2e.ts",
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/capability-seams.md
|
||||
capability-seams.md: 5c9f56519d9cdf7305a0876b069b8ba35ab7b32f
|
||||
capability-seams.zh.md: dcba318582ed9760a3eb81e69d6b1cf885ce8b5a
|
||||
capability-seams.md: 5089740d3d2c51dd8a0d5d9d6b90ebf5830456f4
|
||||
capability-seams.zh.md: 5a66714b179b1bf60b84d3273aade842f1ed23ef
|
||||
@@ -14,6 +14,8 @@ flowchart LR
|
||||
pkg_tool_fs["tool-fs"]
|
||||
pkg_llm_pi_ai["llm-pi-ai"]
|
||||
pkg_llm_deepseek["llm-deepseek"]
|
||||
pkg_client_file_upload["client-file-upload"]
|
||||
svc_fileUploads["ctx.fileUploads<br/>Agent-scoped staged file uploads"]
|
||||
pkg_llm["llm"]
|
||||
svc_llm["ctx.llm<br/>LLM adapter registry"]
|
||||
pkg_llm_replay["llm-replay"]
|
||||
@@ -237,6 +239,7 @@ flowchart LR
|
||||
pkg_authorization --> svc_authorization
|
||||
pkg_bash_local --> svc_shell
|
||||
pkg_bash_sandbox --> svc_shell
|
||||
pkg_client_file_upload --> svc_fileUploads
|
||||
pkg_client_modules --> svc_clientModules
|
||||
pkg_code_runtime --> svc_codeRuntime
|
||||
pkg_code_runtime_worker_thread --> svc_codeRuntime
|
||||
@@ -367,6 +370,7 @@ flowchart LR
|
||||
svc_e2b --> pkg_fs_e2b
|
||||
svc_e2b --> pkg_subprocess_e2b
|
||||
svc_fileReferences --> pkg_api_session_controller
|
||||
svc_fileUploads --> pkg_api_session_controller
|
||||
svc_fs --> pkg_tool_fs
|
||||
svc_invariants --> pkg_agent
|
||||
svc_invariants --> pkg_agent_loop
|
||||
@@ -469,6 +473,7 @@ flowchart LR
|
||||
| ctx key | Role | Owner | Implementations | Direct consumers | Companion plugins | Note |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `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.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. |
|
||||
|
||||
@@ -16,6 +16,8 @@ flowchart LR
|
||||
pkg_tool_fs["tool-fs"]
|
||||
pkg_llm_pi_ai["llm-pi-ai"]
|
||||
pkg_llm_deepseek["llm-deepseek"]
|
||||
pkg_client_file_upload["client-file-upload"]
|
||||
svc_fileUploads["ctx.fileUploads<br/>Agent-scoped staged file uploads"]
|
||||
pkg_llm["llm"]
|
||||
svc_llm["ctx.llm<br/>LLM adapter registry"]
|
||||
pkg_llm_replay["llm-replay"]
|
||||
@@ -239,6 +241,7 @@ flowchart LR
|
||||
pkg_authorization --> svc_authorization
|
||||
pkg_bash_local --> svc_shell
|
||||
pkg_bash_sandbox --> svc_shell
|
||||
pkg_client_file_upload --> svc_fileUploads
|
||||
pkg_client_modules --> svc_clientModules
|
||||
pkg_code_runtime --> svc_codeRuntime
|
||||
pkg_code_runtime_worker_thread --> svc_codeRuntime
|
||||
@@ -369,6 +372,7 @@ flowchart LR
|
||||
svc_e2b --> pkg_fs_e2b
|
||||
svc_e2b --> pkg_subprocess_e2b
|
||||
svc_fileReferences --> pkg_api_session_controller
|
||||
svc_fileUploads --> pkg_api_session_controller
|
||||
svc_fs --> pkg_tool_fs
|
||||
svc_invariants --> pkg_agent
|
||||
svc_invariants --> pkg_agent_loop
|
||||
@@ -471,6 +475,7 @@ flowchart LR
|
||||
| ctx 键 | 角色 | 所属包 | 实现 | 直接消费方 | 配套插件 | 说明 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `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.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) | - | 拥有按会话隔离的回放折叠区;压力消费方共享不可变且带修订版本的测量结果。 |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/config-catalog.md
|
||||
config-catalog.md: 5e428e74303860a7914b24b7cc6650a842f4683f
|
||||
config-catalog.zh.md: 5296861c8c4dcc691900ddcb419e9c2d4d707b86
|
||||
config-catalog.md: b54b97fe0c6940eb2166c49a015653676fdef097
|
||||
config-catalog.zh.md: 3ba9f26939abe08f4e69617380ca4e61ae01101f
|
||||
+25
-5
@@ -203,7 +203,7 @@ Source: [`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/in
|
||||
|
||||
## `@deepseek-ai/dsh-api-session-controller`
|
||||
|
||||
Requires: `agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry`
|
||||
Requires: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `llm` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry`
|
||||
|
||||
```ts config-catalog
|
||||
/** Session Controller deployment policy. */
|
||||
@@ -213,7 +213,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts)
|
||||
Source: [`packages/api/session-controller/src/index.ts:69`](../packages/api/session-controller/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-api-settings-controller"></a>
|
||||
|
||||
@@ -262,7 +262,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/attachment/attachment-local/src/index.ts:55`](../packages/attachment/attachment-local/src/index.ts)
|
||||
Source: [`packages/attachment/attachment-local/src/index.ts:61`](../packages/attachment/attachment-local/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-bash-local"></a>
|
||||
|
||||
@@ -318,8 +318,10 @@ Source: [`packages/shell/bash-sandbox/src/index.ts:35`](../packages/shell/bash-s
|
||||
Requires: `webServer` · `credentials`
|
||||
|
||||
```ts config-catalog
|
||||
/** Plugin config: the deployment's non-loopback serving authorities. */
|
||||
/** Browser authentication, request limits, and connection recovery configuration. */
|
||||
export interface ConnectionConfig {
|
||||
/** Browser recovery timing, injected into each served page. */
|
||||
recovery?: ConnectionRecoveryConfig
|
||||
/**
|
||||
* Authorities this deployment serves beyond loopback: exact `host:port`, or
|
||||
* port-less `host` matching any port. The /api trust fence refuses any
|
||||
@@ -334,9 +336,26 @@ export interface ConnectionConfig {
|
||||
/** Maximum buffered JSON body for every `/api` request. Default: 300 MiB. */
|
||||
maxRequestBodyBytes?: number
|
||||
}
|
||||
|
||||
/** Timing for generation readiness and automatic reconnection. */
|
||||
export interface ConnectionRecoveryConfig {
|
||||
/** First-retry delay cap in ms; actual delay is 50–100% of the cap. Default: 500. */
|
||||
backoffBaseMs?: number
|
||||
/** Finite growth factor of at least 1 per failed attempt; 1 keeps a fixed cap. Default: 2. */
|
||||
backoffFactor?: number
|
||||
/** Maximum retry delay cap in ms; retries continue at this cap. Default: 10000. */
|
||||
backoffMaxMs?: number
|
||||
/**
|
||||
* Delay before reporting a slow handshake, without cancelling it. Default: 3000.
|
||||
* Omitted when readiness, failure, cancellation, or the hard deadline occurs first.
|
||||
*/
|
||||
generationReadyWarnMs?: number
|
||||
/** Deadline in ms for readiness, including physical connection setup. Default: 15000. */
|
||||
generationReadyTimeoutMs?: number
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/client/connection/src/index.ts:70`](../packages/client/connection/src/index.ts)
|
||||
Source: [`packages/client/connection/src/index.ts:72`](../packages/client/connection/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-client-hmr"></a>
|
||||
|
||||
@@ -3396,6 +3415,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
|
||||
- `@deepseek-ai/dsh-api-remotes` — requires `typertGateway` ([`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts))
|
||||
- `@deepseek-ai/dsh-api-workspace-controller` — requires `typert` · `workspaceRegistry` ([`packages/api/workspace-controller/src/index.ts`](../packages/api/workspace-controller/src/index.ts))
|
||||
- `@deepseek-ai/dsh-authorization` — requires `credentials` ([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-file-upload` — requires `agents` · `attachments` · `commands` · `connection` ([`packages/client/file-upload/src/index.ts`](../packages/client/file-upload/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-modules` — requires `webServer` · `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-agent-preset` ([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts))
|
||||
|
||||
@@ -205,7 +205,7 @@ export interface Config {
|
||||
|
||||
## `@deepseek-ai/dsh-api-session-controller`
|
||||
|
||||
需要:`agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry`
|
||||
需要:`agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `llm` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry`
|
||||
|
||||
```ts config-catalog
|
||||
/** Session Controller deployment policy. */
|
||||
@@ -215,7 +215,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts)
|
||||
来源:[`packages/api/session-controller/src/index.ts:69`](../packages/api/session-controller/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-api-settings-controller"></a>
|
||||
|
||||
@@ -264,7 +264,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/attachment/attachment-local/src/index.ts:55`](../packages/attachment/attachment-local/src/index.ts)
|
||||
来源:[`packages/attachment/attachment-local/src/index.ts:61`](../packages/attachment/attachment-local/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-bash-local"></a>
|
||||
|
||||
@@ -317,11 +317,13 @@ export type Config = LocalConfig
|
||||
|
||||
## `@deepseek-ai/dsh-client-connection`
|
||||
|
||||
需要:`webServer` · `credentials`
|
||||
需要: `webServer` · `credentials`
|
||||
|
||||
```ts config-catalog
|
||||
/** Plugin config: the deployment's non-loopback serving authorities. */
|
||||
/** Browser authentication, request limits, and connection recovery configuration. */
|
||||
export interface ConnectionConfig {
|
||||
/** Browser recovery timing, injected into each served page. */
|
||||
recovery?: ConnectionRecoveryConfig
|
||||
/**
|
||||
* Authorities this deployment serves beyond loopback: exact `host:port`, or
|
||||
* port-less `host` matching any port. The /api trust fence refuses any
|
||||
@@ -336,9 +338,26 @@ export interface ConnectionConfig {
|
||||
/** Maximum buffered JSON body for every `/api` request. Default: 300 MiB. */
|
||||
maxRequestBodyBytes?: number
|
||||
}
|
||||
|
||||
/** Timing for generation readiness and automatic reconnection. */
|
||||
export interface ConnectionRecoveryConfig {
|
||||
/** First-retry delay cap in ms; actual delay is 50–100% of the cap. Default: 500. */
|
||||
backoffBaseMs?: number
|
||||
/** Finite growth factor of at least 1 per failed attempt; 1 keeps a fixed cap. Default: 2. */
|
||||
backoffFactor?: number
|
||||
/** Maximum retry delay cap in ms; retries continue at this cap. Default: 10000. */
|
||||
backoffMaxMs?: number
|
||||
/**
|
||||
* Delay before reporting a slow handshake, without cancelling it. Default: 3000.
|
||||
* Omitted when readiness, failure, cancellation, or the hard deadline occurs first.
|
||||
*/
|
||||
generationReadyWarnMs?: number
|
||||
/** Deadline in ms for readiness, including physical connection setup. Default: 15000. */
|
||||
generationReadyTimeoutMs?: number
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/client/connection/src/index.ts:55`](../packages/client/connection/src/index.ts)
|
||||
来源: [`packages/client/connection/src/index.ts:72`](../packages/client/connection/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-client-hmr"></a>
|
||||
|
||||
@@ -3398,6 +3417,7 @@ export interface Config {
|
||||
- `@deepseek-ai/dsh-api-remotes` — 需要 `typertGateway`([`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts))
|
||||
- `@deepseek-ai/dsh-api-workspace-controller` — 需要 `typert` · `workspaceRegistry`([`packages/api/workspace-controller/src/index.ts`](../packages/api/workspace-controller/src/index.ts))
|
||||
- `@deepseek-ai/dsh-authorization` — 需要 `credentials`([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-file-upload` — 需要 `agents` · `attachments` · `commands` · `connection`([`packages/client/file-upload/src/index.ts`](../packages/client/file-upload/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-locale`([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-modules` — 需要 `webServer` · `loader`([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-agent-preset`([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts))
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
|
||||
event-producer-consumer.md: b9e6421f7973fc7c447b80ebf4e0cd809724173a
|
||||
event-producer-consumer.zh.md: 098277d87f11104f8e556450729a55a6b9cb105b
|
||||
event-producer-consumer.md: 5214745ec346ff51051affe13c1478418a21a884
|
||||
event-producer-consumer.zh.md: a72e92a0538df0e40b2c0ec6b4dc9dc85f889e98
|
||||
@@ -22,14 +22,14 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:262`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:223`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
|
||||
| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:333`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:581`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:561`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:588`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:567`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:574`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:566`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:572`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:579`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
|
||||
| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:87`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
|
||||
| `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
@@ -44,12 +44,12 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../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) |
|
||||
| `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) |
|
||||
| `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), [`llm`](../packages/llm/llm), `remotes` |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:68`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:71`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `mcp-manager/status` | `emit` | [`packages/mcp/mcp-manager/src/types.ts:55`](../packages/mcp/mcp-manager/src/types.ts) | [`mcp-manager`](../packages/mcp/mcp-manager) (`emit`) | [`mcp-manager`](../packages/mcp/mcp-manager) |
|
||||
| `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:51`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:61`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `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) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:73`](../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-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `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), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:61`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `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) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:73`](../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-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`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), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `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), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:82`](../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:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` |
|
||||
| `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
|
||||
@@ -67,7 +67,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
|
||||
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
|
||||
| `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:85`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` |
|
||||
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `inspector`, `modules` |
|
||||
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `connection`, `inspector`, `modules` |
|
||||
| `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), [`workflow`](../packages/workflow/workflow) |
|
||||
| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
|
||||
| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
|
||||
|
||||
@@ -24,11 +24,11 @@
|
||||
| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:262`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:223`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
|
||||
| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:333`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:581`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:561`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:588`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:567`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:574`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:566`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:572`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:579`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
|
||||
| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
|
||||
@@ -46,12 +46,12 @@
|
||||
| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../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) |
|
||||
| `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) |
|
||||
| `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), [`llm`](../packages/llm/llm), `remotes` |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:68`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:71`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `mcp-manager/status` | `emit` | [`packages/mcp/mcp-manager/src/types.ts:55`](../packages/mcp/mcp-manager/src/types.ts) | [`mcp-manager`](../packages/mcp/mcp-manager) (`emit`) | [`mcp-manager`](../packages/mcp/mcp-manager) |
|
||||
| `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:51`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:61`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `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) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:73`](../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-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `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), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:61`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `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) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:73`](../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-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`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), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `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), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:82`](../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:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` |
|
||||
| `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
|
||||
@@ -69,7 +69,7 @@
|
||||
| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
|
||||
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
|
||||
| `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:85`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` |
|
||||
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `inspector`, `modules` |
|
||||
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `connection`, `inspector`, `modules` |
|
||||
| `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), [`workflow`](../packages/workflow/workflow) |
|
||||
| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
|
||||
| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/module-graph.md
|
||||
module-graph.md: 2a580b94bc26ba36d61c67fd0a16f7fd55f127b8
|
||||
module-graph.zh.md: 9af46f7b04e9031a7976c73e7b6a029b14209b88
|
||||
module-graph.md: 5f7559e18846ab312a13f4612a94c1024c3467b8
|
||||
module-graph.zh.md: 6579c68e1b858cb972d6c87d1bf2dcfc70568a8e
|
||||
@@ -132,6 +132,7 @@ flowchart TD
|
||||
end
|
||||
subgraph group_client["packages/client"]
|
||||
pkg_client_connection["client-connection"]
|
||||
pkg_client_file_upload["client-file-upload"]
|
||||
pkg_client_hmr["client-hmr"]
|
||||
pkg_client_locale["client-locale"]
|
||||
pkg_client_modules["client-modules"]
|
||||
@@ -408,6 +409,7 @@ flowchart TD
|
||||
pkg_api_remotes --> pkg_scope
|
||||
pkg_attachment_local --> pkg_attachment
|
||||
pkg_attachment_local --> pkg_home_paths
|
||||
pkg_client_file_upload --> pkg_scope
|
||||
pkg_authorization --> pkg_credentials
|
||||
pkg_authorization --> pkg_invariants
|
||||
pkg_authorization --> pkg_llm
|
||||
@@ -1059,6 +1061,8 @@ flowchart TD
|
||||
pkg_api_session_controller --> pkg_api_gateway
|
||||
pkg_api_session_controller --> pkg_attachment
|
||||
pkg_api_session_controller --> pkg_client_connection
|
||||
pkg_api_session_controller --> pkg_client_file_upload
|
||||
pkg_api_session_controller --> pkg_commands
|
||||
pkg_api_session_controller --> pkg_file_reference
|
||||
pkg_api_session_controller --> pkg_jobs
|
||||
pkg_api_session_controller --> pkg_llm
|
||||
@@ -1268,6 +1272,7 @@ flowchart TD
|
||||
| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) |
|
||||
| [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) |
|
||||
| [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths) |
|
||||
| [`client-file-upload`](../packages/client/file-upload) | `client` | [`scope`](../packages/core/scope) |
|
||||
| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`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) |
|
||||
| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
|
||||
@@ -1399,7 +1404,7 @@ flowchart TD
|
||||
| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
|
||||
| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
|
||||
| [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`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-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`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), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
|
||||
| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`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), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`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), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
|
||||
| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
|
||||
| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
|
||||
| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`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) |
|
||||
|
||||
@@ -134,6 +134,7 @@ flowchart TD
|
||||
end
|
||||
subgraph group_client["packages/client"]
|
||||
pkg_client_connection["client-connection"]
|
||||
pkg_client_file_upload["client-file-upload"]
|
||||
pkg_client_hmr["client-hmr"]
|
||||
pkg_client_locale["client-locale"]
|
||||
pkg_client_modules["client-modules"]
|
||||
@@ -410,6 +411,7 @@ flowchart TD
|
||||
pkg_api_remotes --> pkg_scope
|
||||
pkg_attachment_local --> pkg_attachment
|
||||
pkg_attachment_local --> pkg_home_paths
|
||||
pkg_client_file_upload --> pkg_scope
|
||||
pkg_authorization --> pkg_credentials
|
||||
pkg_authorization --> pkg_invariants
|
||||
pkg_authorization --> pkg_llm
|
||||
@@ -1061,6 +1063,8 @@ flowchart TD
|
||||
pkg_api_session_controller --> pkg_api_gateway
|
||||
pkg_api_session_controller --> pkg_attachment
|
||||
pkg_api_session_controller --> pkg_client_connection
|
||||
pkg_api_session_controller --> pkg_client_file_upload
|
||||
pkg_api_session_controller --> pkg_commands
|
||||
pkg_api_session_controller --> pkg_file_reference
|
||||
pkg_api_session_controller --> pkg_jobs
|
||||
pkg_api_session_controller --> pkg_llm
|
||||
@@ -1270,6 +1274,7 @@ flowchart TD
|
||||
| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) |
|
||||
| [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) |
|
||||
| [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths) |
|
||||
| [`client-file-upload`](../packages/client/file-upload) | `client` | [`scope`](../packages/core/scope) |
|
||||
| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`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) |
|
||||
| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
|
||||
@@ -1401,7 +1406,7 @@ flowchart TD
|
||||
| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
|
||||
| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
|
||||
| [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`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-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`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), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
|
||||
| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`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), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`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), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
|
||||
| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
|
||||
| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
|
||||
| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`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) |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/persistence-catalog.md
|
||||
persistence-catalog.md: 76d91ea8e8edb625f9733b6ad28d225d2ee059a8
|
||||
persistence-catalog.zh.md: 52625069c16094e1b056b9ee9013409fd1690705
|
||||
persistence-catalog.md: 0b52801083498542c814d06171942f33d013efe2
|
||||
persistence-catalog.zh.md: eda29e00c9dfaff6c5d35afba55f2a8cfb95f075
|
||||
@@ -268,7 +268,7 @@ Source: [`packages/core/session/src/types.ts:299`](../packages/core/session/src/
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/interaction/commands/src/types.ts:104`](../packages/interaction/commands/src/types.ts)
|
||||
Source: [`packages/interaction/commands/src/types.ts:110`](../packages/interaction/commands/src/types.ts)
|
||||
|
||||
<a id="commandrun--log-only"></a>
|
||||
|
||||
@@ -288,7 +288,7 @@ Source: [`packages/interaction/commands/src/types.ts:104`](../packages/interacti
|
||||
'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
|
||||
```
|
||||
|
||||
Source: [`packages/interaction/commands/src/types.ts:97`](../packages/interaction/commands/src/types.ts)
|
||||
Source: [`packages/interaction/commands/src/types.ts:103`](../packages/interaction/commands/src/types.ts)
|
||||
|
||||
### `compaction/*`
|
||||
|
||||
|
||||
@@ -270,7 +270,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/interaction/commands/src/types.ts:104`](../packages/interaction/commands/src/types.ts)
|
||||
来源:[`packages/interaction/commands/src/types.ts:110`](../packages/interaction/commands/src/types.ts)
|
||||
|
||||
<a id="commandrun--log-only"></a>
|
||||
|
||||
@@ -290,7 +290,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
|
||||
```
|
||||
|
||||
来源:[`packages/interaction/commands/src/types.ts:97`](../packages/interaction/commands/src/types.ts)
|
||||
来源:[`packages/interaction/commands/src/types.ts:103`](../packages/interaction/commands/src/types.ts)
|
||||
|
||||
### `compaction/*`
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/attachment.md
|
||||
attachment.md: 15daa2b8d541ba847d48f5c43a06c1c537df6d11
|
||||
attachment.zh.md: c74a18f6bec63e117afcdb141512be04f8d75f9a
|
||||
attachment.md: 53b3e51e5b1c87625256178287061386342bc055
|
||||
attachment.zh.md: 549c06cc5abe542e5d6feeba10b24ebf6ba8dfd1
|
||||
@@ -1,10 +1,10 @@
|
||||
# Durable Image Attachments
|
||||
# Durable Attachments
|
||||
|
||||
English | [中文](attachment.zh.md)
|
||||
|
||||
The attachment seam separates binary image ownership from the session log. A producer gives validated encoded bytes to [`ctx.attachments`](#ctxattachments--attachmentstore-abstract-seam); the service publishes an immutable content-addressed reference only after the object is durable. Session events and model-visible `ImageBlock`s contain that reference and metadata, never a browser object URL, host temporary path, provider URL, or base64 payload.
|
||||
The attachment seam separates binary image and generic-file ownership from the session log. A producer gives bytes to [`ctx.attachments`](#ctxattachments--attachmentstore-abstract-seam); the service publishes an immutable content-addressed reference only after the object is durable. Session events and model-visible attachment blocks contain that reference and metadata, never a browser object URL, host temporary path, provider URL, or base64 payload. The independent [`ctx.fileUploads`](#ctxfileuploads--fileuploads) service binds browser file transfers and staged receipts to the receiving Agent.
|
||||
|
||||
Unsent browser drafts may stay in memory and native clients may stage them in operating-system temporary storage. Once the host accepts a user message, its images move below `<DSH_HOME>/attachments/v1` before the user event is appended. Structured model image output follows the same persist-before-event rule.
|
||||
Unsent browser drafts may stay in memory and native clients may stage them in operating-system temporary storage. Browser generic files become durable before they receive a staged prompt receipt. Once the host accepts a user message, its images move below `<DSH_HOME>/attachments/v1` before the user event is appended. Structured model image output follows the same persist-before-event rule.
|
||||
|
||||
Source: [`packages/attachment/attachment/src/types.ts`](../../packages/attachment/attachment/src/types.ts)
|
||||
|
||||
@@ -62,6 +62,38 @@ The reference records intrinsic dimensions and encoded length so clients can lay
|
||||
|
||||
## Commit and verified-read payloads
|
||||
|
||||
```ts type-equiv
|
||||
/**
|
||||
* Browser-submitted prompt content accepted by Host prompt endpoints; the
|
||||
* accepting Host promotes image parts to durable references through
|
||||
* `ctx.attachments.admitPromptContent()` before any message is created, so a wire caller can
|
||||
* never cite an attachment it did not upload.
|
||||
*/
|
||||
type PromptContentPart =
|
||||
| { readonly type: 'text'; readonly text: string }
|
||||
| {
|
||||
readonly type: 'image'
|
||||
readonly mediaType: ImageMediaType
|
||||
readonly data: string
|
||||
readonly name?: string
|
||||
}
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
/** Host prompt content whose file receipts are resolved and whose image bytes await admission. */
|
||||
type AttachmentAdmissionPart =
|
||||
| PromptContentPart
|
||||
| { readonly type: 'file'; readonly attachment: FileAttachmentRef }
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
/** Host-admitted prompt content with every attachment represented by its durable reference. */
|
||||
type AdmittedPromptContentPart =
|
||||
| { readonly type: 'text'; readonly text: string }
|
||||
| { readonly type: 'image'; readonly attachment: ImageAttachmentRef }
|
||||
| { readonly type: 'file'; readonly attachment: FileAttachmentRef }
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
/** Base64-encoded image upload accompanying one wire request. */
|
||||
interface EncodedImageAttachment {
|
||||
@@ -125,7 +157,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. `admitEncodedImages()` is the wire entry for base64 uploads and delegates count, aggregate-byte, and ordered batch admission to `saveImages()`. `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 under an exact route pixel and byte budget. 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 file receipt resolution, replaces base64 image uploads with durable references, and passes durable file references unchanged. `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 under an exact route pixel and byte budget. 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.
|
||||
|
||||
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
||||
|
||||
@@ -157,6 +189,30 @@ abstract validateImage(input: SaveImageAttachment): Promise<void>
|
||||
*/
|
||||
async saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>
|
||||
|
||||
/**
|
||||
* Admit one Host prompt and replace each uploaded image with its durable reference.
|
||||
* Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
|
||||
* @param content - prompt parts in message order after file receipt resolution.
|
||||
* @returns admitted prompt parts in the same order as `content`.
|
||||
* @throws AttachmentError when the image batch is refused.
|
||||
*/
|
||||
async admitPromptContent( content: readonly AttachmentAdmissionPart[], ): Promise<AdmittedPromptContentPart[]>
|
||||
|
||||
/**
|
||||
* Decode and durably commit one canonical base64 file upload.
|
||||
* @param input - canonical base64 bytes and optional display name.
|
||||
* @returns the durable content-addressed file reference.
|
||||
* @throws AttachmentError when the encoding or storage operation is refused.
|
||||
*/
|
||||
admitEncodedFile(input: EncodedFileAttachment): Promise<FileAttachmentRef>
|
||||
|
||||
/**
|
||||
* Identify a failure emitted by this attachment capability by its stable code.
|
||||
* @param error - value caught from an attachment operation.
|
||||
* @returns whether the value is an attachment failure.
|
||||
*/
|
||||
isAttachmentError(error: unknown): error is AttachmentError
|
||||
|
||||
/**
|
||||
* Validate and durably commit one image before its owning session event is appended.
|
||||
* The returned reference describes the persisted normalized image. When
|
||||
@@ -184,6 +240,43 @@ abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<Store
|
||||
*/
|
||||
imageHostPath(ref: ImageAttachmentRef): string | undefined
|
||||
|
||||
/**
|
||||
* Durably commit one file byte-for-byte before its owning session event is
|
||||
* appended. Files carry no admission limits: any byte content and length is
|
||||
* accepted, and the stored object is the exact submitted bytes. Backends
|
||||
* without verbatim file storage keep this default rejection.
|
||||
* @param input - exact bytes and optional display name.
|
||||
* @returns the durable content-addressed file reference.
|
||||
*/
|
||||
saveFile(input: SaveFileAttachment): Promise<FileAttachmentRef>
|
||||
|
||||
/**
|
||||
* Durably commit one file byte-for-byte from bounded chunks. Providers must
|
||||
* apply backpressure and must not collect the complete file in memory.
|
||||
* Backends without streamed verbatim storage keep this default rejection.
|
||||
* @param input - ordered exact bytes, optional cancellation, and display name.
|
||||
* @returns the durable content-addressed file reference.
|
||||
*/
|
||||
saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>
|
||||
|
||||
/**
|
||||
* 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 signal - optional cancellation for backend reads and verification work.
|
||||
* @returns exact file bytes in order; integrity failures reject the iteration.
|
||||
*/
|
||||
async *readFileStream( ref: FileAttachmentRef, signal?: AbortSignal, ): AsyncIterable<Uint8Array>
|
||||
|
||||
/**
|
||||
* Locate the verbatim stored file object in the harness host filesystem.
|
||||
* @param ref - durable file reference.
|
||||
* @returns an absolute host path, or undefined when this backend is not host-file-backed.
|
||||
* @throws an AttachmentError when the durable reference is invalid.
|
||||
*/
|
||||
fileHostPath(ref: FileAttachmentRef): string | undefined
|
||||
|
||||
/**
|
||||
* Generate or read one deterministic model-request version from the stored normalized image.
|
||||
* @param ref - durable provider-independent normalized attachment reference.
|
||||
@@ -195,4 +288,64 @@ readImageRequest( ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?:
|
||||
```
|
||||
|
||||
Source: [`packages/attachment/attachment/src/index.ts`](../../packages/attachment/attachment/src/index.ts)
|
||||
|
||||
<a id="ctxfileuploads--fileuploads"></a>
|
||||
|
||||
### `ctx.fileUploads` — `FileUploads`
|
||||
|
||||
Host service owning upload storage and Agent-scoped staged receipts.
|
||||
|
||||
```ts cordis-catalog
|
||||
/**
|
||||
* Register the ordinary-Session resolver used when a raw upload addresses a cold Session.
|
||||
* @param resolve - resolver that returns the exact live Agent or throws a Remote error.
|
||||
* @returns disposer removing this resolver.
|
||||
*/
|
||||
registerAgentResolver(resolve: AgentResolver): () => void
|
||||
|
||||
/**
|
||||
* Persist one encoded upload and stage it under the Agent receiver selected by Typert.
|
||||
* @param agent - receiving Agent resolved from the Remote Agent scope.
|
||||
* @param request - canonical base64 bytes and optional display name.
|
||||
* @param signal - caller cancellation before storage begins.
|
||||
* @returns the staged receipt and durable file reference.
|
||||
*/
|
||||
@Remote('upload') upload(agent: Agent, request: EncodedFileUploadRequest, signal: AbortSignal): Promise<FileUploadValue>
|
||||
|
||||
/**
|
||||
* Persist raw chunks for one Session without aggregating the upload.
|
||||
* @param request - Session identity, ordered bytes, cancellation, and optional display name.
|
||||
* @returns the staged receipt and durable file reference.
|
||||
*/
|
||||
async uploadStream(request: { readonly sessionId: SessionId readonly data: AsyncIterable<Uint8Array> readonly signal?: AbortSignal readonly name?: string }): Promise<FileUploadValue>
|
||||
|
||||
/**
|
||||
* Resolve one staged receipt inside its receiving Agent scope.
|
||||
* @param agent - receiving Agent.
|
||||
* @param receiptId - opaque receipt minted for one completed upload.
|
||||
* @returns durable file reference, or `undefined` for an unknown or foreign receipt.
|
||||
*/
|
||||
resolve(agent: Agent, receiptId: FileUploadReceiptId): FileAttachmentRef | undefined
|
||||
|
||||
/**
|
||||
* Bind receipts while one prompt enters an Agent inbox.
|
||||
* Disposal restores every prior binding unless the caller commits successful delivery.
|
||||
* @param agent - receiving Agent.
|
||||
* @param receiptIds - distinct staged receipts referenced by the prompt.
|
||||
* @param requestId - prompt identity later observed in queue or history.
|
||||
* @returns binding kept after commit until queue or history observation retires its receipts.
|
||||
*/
|
||||
bindPrompt( agent: Agent, receiptIds: readonly FileUploadReceiptId[], requestId: string, ): PromptFileBinding
|
||||
|
||||
/**
|
||||
* Retire every receipt accepted by one removed queue occurrence.
|
||||
* @param agent - receiving Agent.
|
||||
* @param requestId - prompt identity carried by the queue occurrence.
|
||||
*/
|
||||
retirePrompt(agent: Agent, requestId: string): void
|
||||
```
|
||||
|
||||
Types: [Agent](core.md) · [SessionId](core.md)
|
||||
|
||||
Source: [`packages/client/file-upload/src/index.ts`](../../packages/client/file-upload/src/index.ts)
|
||||
<!-- END GENERATED cordis-surface -->
|
||||
@@ -1,10 +1,10 @@
|
||||
# 持久图片附件
|
||||
# 持久附件
|
||||
|
||||
[English](attachment.md) | 中文
|
||||
|
||||
附件 seam 将二进制图片的所有权与会话日志分离。生产方把经过校验的编码字节交给 [`ctx.attachments`](#ctxattachments--attachmentstore-abstract-seam);只有对象完成持久化后,该服务才会发布不可变的内容寻址引用。会话事件和模型可见的 `ImageBlock` 包含该引用及其元数据,绝不包含浏览器对象 URL、宿主临时路径、提供方 URL 或 base64 数据。
|
||||
附件 seam 将二进制图片和通用文件的所有权与会话日志分离。生产方把字节交给 [`ctx.attachments`](#ctxattachments--attachmentstore-abstract-seam);只有对象完成持久化后,该服务才会发布不可变的内容寻址引用。会话事件和模型可见的附件块包含该引用及其元数据,绝不包含浏览器对象 URL、宿主临时路径、提供方 URL 或 base64 数据。独立的 [`ctx.fileUploads`](#ctxfileuploads--fileuploads) 服务把浏览器文件传输与暂存凭证绑定到接收方 Agent。
|
||||
|
||||
未发送的浏览器草稿可以保留在内存中,原生客户端也可以将其暂存于操作系统临时存储。宿主接受用户消息后,会先把消息中的图片移到 `<DSH_HOME>/attachments/v1` 下,再追加用户事件。结构化模型图片输出遵循同样的先持久化、后追加事件规则。
|
||||
未发送的浏览器草稿可以保留在内存中,原生客户端也可以将其暂存于操作系统临时存储。浏览器通用文件取得暂存 prompt 凭证前会完成持久化。宿主接受用户消息后,会先把消息中的图片移到 `<DSH_HOME>/attachments/v1` 下,再追加用户事件。结构化模型图片输出遵循同样的先持久化、后追加事件规则。
|
||||
|
||||
来源:[`packages/attachment/attachment/src/types.ts`](../../packages/attachment/attachment/src/types.ts)
|
||||
|
||||
@@ -62,6 +62,38 @@ interface ImageAttachmentLimits {
|
||||
|
||||
## 提交与经校验读取的数据
|
||||
|
||||
```ts type-equiv
|
||||
/**
|
||||
* Browser-submitted prompt content accepted by Host prompt endpoints; the
|
||||
* accepting Host promotes image parts to durable references through
|
||||
* `ctx.attachments.admitPromptContent()` before any message is created, so a wire caller can
|
||||
* never cite an attachment it did not upload.
|
||||
*/
|
||||
type PromptContentPart =
|
||||
| { readonly type: 'text'; readonly text: string }
|
||||
| {
|
||||
readonly type: 'image'
|
||||
readonly mediaType: ImageMediaType
|
||||
readonly data: string
|
||||
readonly name?: string
|
||||
}
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
/** Host prompt content whose file receipts are resolved and whose image bytes await admission. */
|
||||
type AttachmentAdmissionPart =
|
||||
| PromptContentPart
|
||||
| { readonly type: 'file'; readonly attachment: FileAttachmentRef }
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
/** Host-admitted prompt content with every attachment represented by its durable reference. */
|
||||
type AdmittedPromptContentPart =
|
||||
| { readonly type: 'text'; readonly text: string }
|
||||
| { readonly type: 'image'; readonly attachment: ImageAttachmentRef }
|
||||
| { readonly type: 'file'; readonly attachment: FileAttachmentRef }
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
/** Base64-encoded image upload accompanying one wire request. */
|
||||
interface EncodedImageAttachment {
|
||||
@@ -125,7 +157,7 @@ interface RequestImageAttachment {
|
||||
}
|
||||
```
|
||||
|
||||
`saveImage()` 准备并原子提交提供方无关的规范化附件,然后直接返回 `ImageAttachmentRef`。`saveImages()` 在发布批次前为每个成员各准备一次经过验证的附件,因此校验拒绝不会留下部分对象,发布也不会重复解码或选择质量。`admitEncodedImages()` 是面向 base64 上传的 wire 入口,把张数、聚合字节和有序批量准入交给 `saveImages()`。`readImage()` 校验来自已授权会话路径的规范化附件。`imageHostPath()` 只公开提供方所持对象的宿主位置,不判断当前工具执行环境能否读取它。`readImageRequest()` 按确切路由的像素和字节预算派生并缓存确定性请求版本。该版本包含编码字节和元数据,不包含执行环境路径。新条目在发布前完整解码,缓存命中只做有界元数据探测。调用方需要有序批次时,对单数方法使用 `Promise.all`。本地实现按需编码首选候选、合并相同请求身份的并发任务、允许每个等待方单独取消、没有等待方时停止共享任务,并通过实例级限流器限制全部变换,默认同时执行两项。该服务不规定保留策略:恢复和 fork 后的会话可能共享对象,因此基于引用的垃圾回收会延期实现,不与单个会话的删除绑定。
|
||||
`saveImage()` 准备并原子提交提供方无关的规范化附件,然后直接返回 `ImageAttachmentRef`。`saveImages()` 在发布批次前为每个成员各准备一次经过验证的附件,因此校验拒绝不会留下部分对象,发布也不会重复解码或选择质量。`admitPromptContent()` 在文件凭证解析后接收完整且有序的 Host prompt,把 base64 图片上传替换为持久引用,并让持久文件引用原样通过。`admitEncodedImages()` 支持其他 wire 入口,把张数、聚合字节和有序批量准入交给 `saveImages()`。`admitEncodedFile()` 让编码协议适配器使用服务拥有的规范 base64 准入,`isAttachmentError()` 让这些适配器无需导入实现辅助函数即可识别稳定的附件错误。`readImage()` 校验来自已授权会话路径的规范化附件。`imageHostPath()` 只公开提供方所持对象的宿主位置,不判断当前工具执行环境能否读取它。`readImageRequest()` 按确切路由的像素和字节预算派生并缓存确定性请求版本。该版本包含编码字节和元数据,不包含执行环境路径。新条目在发布前完整解码,缓存命中只做有界元数据探测。调用方需要有序批次时,对单数方法使用 `Promise.all`。本地实现按需编码首选候选、合并相同请求身份的并发任务、允许每个等待方单独取消、没有等待方时停止共享任务,并通过实例级限流器限制全部变换,默认同时执行两项。该服务不规定保留策略:恢复和 fork 后的会话可能共享对象,因此基于引用的垃圾回收会延期实现,不与单个会话的删除绑定。
|
||||
|
||||
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
||||
|
||||
@@ -157,6 +189,30 @@ abstract validateImage(input: SaveImageAttachment): Promise<void>
|
||||
*/
|
||||
async saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>
|
||||
|
||||
/**
|
||||
* Admit one Host prompt and replace each uploaded image with its durable reference.
|
||||
* Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
|
||||
* @param content - prompt parts in message order after file receipt resolution.
|
||||
* @returns admitted prompt parts in the same order as `content`.
|
||||
* @throws AttachmentError when the image batch is refused.
|
||||
*/
|
||||
async admitPromptContent( content: readonly AttachmentAdmissionPart[], ): Promise<AdmittedPromptContentPart[]>
|
||||
|
||||
/**
|
||||
* Decode and durably commit one canonical base64 file upload.
|
||||
* @param input - canonical base64 bytes and optional display name.
|
||||
* @returns the durable content-addressed file reference.
|
||||
* @throws AttachmentError when the encoding or storage operation is refused.
|
||||
*/
|
||||
admitEncodedFile(input: EncodedFileAttachment): Promise<FileAttachmentRef>
|
||||
|
||||
/**
|
||||
* Identify a failure emitted by this attachment capability by its stable code.
|
||||
* @param error - value caught from an attachment operation.
|
||||
* @returns whether the value is an attachment failure.
|
||||
*/
|
||||
isAttachmentError(error: unknown): error is AttachmentError
|
||||
|
||||
/**
|
||||
* Validate and durably commit one image before its owning session event is appended.
|
||||
* The returned reference describes the persisted normalized image. When
|
||||
@@ -184,6 +240,43 @@ abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<Store
|
||||
*/
|
||||
imageHostPath(ref: ImageAttachmentRef): string | undefined
|
||||
|
||||
/**
|
||||
* Durably commit one file byte-for-byte before its owning session event is
|
||||
* appended. Files carry no admission limits: any byte content and length is
|
||||
* accepted, and the stored object is the exact submitted bytes. Backends
|
||||
* without verbatim file storage keep this default rejection.
|
||||
* @param input - exact bytes and optional display name.
|
||||
* @returns the durable content-addressed file reference.
|
||||
*/
|
||||
saveFile(input: SaveFileAttachment): Promise<FileAttachmentRef>
|
||||
|
||||
/**
|
||||
* Durably commit one file byte-for-byte from bounded chunks. Providers must
|
||||
* apply backpressure and must not collect the complete file in memory.
|
||||
* Backends without streamed verbatim storage keep this default rejection.
|
||||
* @param input - ordered exact bytes, optional cancellation, and display name.
|
||||
* @returns the durable content-addressed file reference.
|
||||
*/
|
||||
saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>
|
||||
|
||||
/**
|
||||
* 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 signal - optional cancellation for backend reads and verification work.
|
||||
* @returns exact file bytes in order; integrity failures reject the iteration.
|
||||
*/
|
||||
async *readFileStream( ref: FileAttachmentRef, signal?: AbortSignal, ): AsyncIterable<Uint8Array>
|
||||
|
||||
/**
|
||||
* Locate the verbatim stored file object in the harness host filesystem.
|
||||
* @param ref - durable file reference.
|
||||
* @returns an absolute host path, or undefined when this backend is not host-file-backed.
|
||||
* @throws an AttachmentError when the durable reference is invalid.
|
||||
*/
|
||||
fileHostPath(ref: FileAttachmentRef): string | undefined
|
||||
|
||||
/**
|
||||
* Generate or read one deterministic model-request version from the stored normalized image.
|
||||
* @param ref - durable provider-independent normalized attachment reference.
|
||||
@@ -195,4 +288,64 @@ readImageRequest( ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?:
|
||||
```
|
||||
|
||||
Source: [`packages/attachment/attachment/src/index.ts`](../../packages/attachment/attachment/src/index.ts)
|
||||
|
||||
<a id="ctxfileuploads--fileuploads"></a>
|
||||
|
||||
### `ctx.fileUploads` — `FileUploads`
|
||||
|
||||
Host service owning upload storage and Agent-scoped staged receipts.
|
||||
|
||||
```ts cordis-catalog
|
||||
/**
|
||||
* Register the ordinary-Session resolver used when a raw upload addresses a cold Session.
|
||||
* @param resolve - resolver that returns the exact live Agent or throws a Remote error.
|
||||
* @returns disposer removing this resolver.
|
||||
*/
|
||||
registerAgentResolver(resolve: AgentResolver): () => void
|
||||
|
||||
/**
|
||||
* Persist one encoded upload and stage it under the Agent receiver selected by Typert.
|
||||
* @param agent - receiving Agent resolved from the Remote Agent scope.
|
||||
* @param request - canonical base64 bytes and optional display name.
|
||||
* @param signal - caller cancellation before storage begins.
|
||||
* @returns the staged receipt and durable file reference.
|
||||
*/
|
||||
@Remote('upload') upload(agent: Agent, request: EncodedFileUploadRequest, signal: AbortSignal): Promise<FileUploadValue>
|
||||
|
||||
/**
|
||||
* Persist raw chunks for one Session without aggregating the upload.
|
||||
* @param request - Session identity, ordered bytes, cancellation, and optional display name.
|
||||
* @returns the staged receipt and durable file reference.
|
||||
*/
|
||||
async uploadStream(request: { readonly sessionId: SessionId readonly data: AsyncIterable<Uint8Array> readonly signal?: AbortSignal readonly name?: string }): Promise<FileUploadValue>
|
||||
|
||||
/**
|
||||
* Resolve one staged receipt inside its receiving Agent scope.
|
||||
* @param agent - receiving Agent.
|
||||
* @param receiptId - opaque receipt minted for one completed upload.
|
||||
* @returns durable file reference, or `undefined` for an unknown or foreign receipt.
|
||||
*/
|
||||
resolve(agent: Agent, receiptId: FileUploadReceiptId): FileAttachmentRef | undefined
|
||||
|
||||
/**
|
||||
* Bind receipts while one prompt enters an Agent inbox.
|
||||
* Disposal restores every prior binding unless the caller commits successful delivery.
|
||||
* @param agent - receiving Agent.
|
||||
* @param receiptIds - distinct staged receipts referenced by the prompt.
|
||||
* @param requestId - prompt identity later observed in queue or history.
|
||||
* @returns binding kept after commit until queue or history observation retires its receipts.
|
||||
*/
|
||||
bindPrompt( agent: Agent, receiptIds: readonly FileUploadReceiptId[], requestId: string, ): PromptFileBinding
|
||||
|
||||
/**
|
||||
* Retire every receipt accepted by one removed queue occurrence.
|
||||
* @param agent - receiving Agent.
|
||||
* @param requestId - prompt identity carried by the queue occurrence.
|
||||
*/
|
||||
retirePrompt(agent: Agent, requestId: string): void
|
||||
```
|
||||
|
||||
Types: [Agent](core.zh.md) · [SessionId](core.zh.md)
|
||||
|
||||
Source: [`packages/client/file-upload/src/index.ts`](../../packages/client/file-upload/src/index.ts)
|
||||
<!-- END GENERATED cordis-surface -->
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/commands.md
|
||||
commands.md: 46d3b736afd3a72d1119c9744cd592a86b9cbc29
|
||||
commands.zh.md: db8d6e722e3a1742887aaa4023ab67b9ed914552
|
||||
commands.md: 4705048e06796792d8e013450b72035b1f87315b
|
||||
commands.zh.md: f3af9f6e81745514efd1e073868292a02f90dca8
|
||||
+24
-15
@@ -8,7 +8,7 @@ Source: [`packages/interaction/commands/src/index.ts`](../../packages/interactio
|
||||
|
||||
## Input metadata
|
||||
|
||||
The service exposes one optional unstructured-input descriptor: a hint plus an image-acceptance flag. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
|
||||
The service exposes one optional unstructured-input descriptor: a hint plus an attachment-acceptance flag. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
|
||||
|
||||
```ts type-equiv
|
||||
/** Immutable metadata for a command's optional unstructured input. */
|
||||
@@ -16,13 +16,13 @@ interface CommandInputDescriptor {
|
||||
/** Placeholder shown before the user supplies free-form input. */
|
||||
readonly hint: string
|
||||
/**
|
||||
* Whether composer image attachments may accompany an invocation. Absent or
|
||||
* false = the executor rejects an invocation carrying images and capable
|
||||
* Whether composer attachments may accompany an invocation. Absent or
|
||||
* false = the executor rejects an invocation carrying attachments and capable
|
||||
* composers refuse the submission before dispatch. A declaring command's
|
||||
* handler receives the admitted durable blocks and owns every further
|
||||
* grammar decision, including rejecting sub-commands that cannot use them.
|
||||
*/
|
||||
readonly images?: boolean
|
||||
readonly attachments?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
@@ -64,13 +64,13 @@ interface CommandInvocation {
|
||||
/** Exact text following the registered command name, including separator whitespace. */
|
||||
readonly rawInput: string
|
||||
/**
|
||||
* Durably admitted image blocks accompanying this invocation, in submission
|
||||
* order; empty unless the definition declares `input.images`. The handler
|
||||
* Durably admitted image and file blocks accompanying this invocation, in submission
|
||||
* order; empty unless the definition declares `input.attachments`. The handler
|
||||
* owns their model-visible use — the registry never schedules them itself —
|
||||
* and a handler whose grammar cannot use them in this invocation returns an
|
||||
* error so the dispatching composer retains the originals.
|
||||
*/
|
||||
readonly attachments: readonly ImageBlock[]
|
||||
readonly attachments: readonly (ImageBlock | FileBlock)[]
|
||||
/** Cancellation signal owned by the dispatching UI request. */
|
||||
readonly signal: AbortSignal
|
||||
}
|
||||
@@ -138,6 +138,13 @@ Human-command registry. Plain-context definitions are global; definitions regist
|
||||
*/
|
||||
register(definition: CommandDefinition): () => void
|
||||
|
||||
/**
|
||||
* Register the sole authority that resolves staged file receipts for command submissions.
|
||||
* @param resolver - Session-aware receipt resolver.
|
||||
* @returns disposer that removes this exact resolver.
|
||||
*/
|
||||
registerFileReceiptResolver(resolver: CommandFileReceiptResolver): () => void
|
||||
|
||||
/**
|
||||
* List the effective immutable command descriptors for one agent.
|
||||
* @param agent - exact receiving agent and scoped-layer key.
|
||||
@@ -166,23 +173,25 @@ find(agent: Agent, name: string): CommandDefinition | undefined
|
||||
* handler-failure path is contained so the handler's own error stays the
|
||||
* reported failure.
|
||||
*
|
||||
* Image admission is enforced here, not in the composer: images sent to a
|
||||
* command that does not declare `input.images`, an absent attachment store,
|
||||
* and an exceeded attachment limit each settle as an error result before
|
||||
* the handler runs, and a rejected batch publishes no durable object.
|
||||
* Attachment admission is enforced here, not in the composer: attachments sent to a
|
||||
* command that does not declare `input.attachments`, an absent attachment store,
|
||||
* and an exceeded image limit each settle as an error result before
|
||||
* the handler runs. Validation rejection starts no attachment writes;
|
||||
* a storage failure can leave only unreachable content-addressed objects
|
||||
* for deferred collection.
|
||||
*
|
||||
* @param agent - exact receiving agent.
|
||||
* @param line - complete slash-command line.
|
||||
* @param images - base64-encoded composer images accompanying the line, in
|
||||
* submission order; empty for a plain invocation.
|
||||
* @param submittedAttachments - encoded images and staged file receipts accompanying the line,
|
||||
* in submission order; empty for a plain invocation.
|
||||
* @param signal - cancellation signal owned by the UI request.
|
||||
* @returns the settled execution (result + lifecycle pairing id), or
|
||||
* `undefined` when syntax or name does not resolve.
|
||||
*/
|
||||
@Remote async execute( agent: Agent, line: string, images: readonly EncodedImageAttachment[], signal: AbortSignal, ): Promise<CommandExecution | undefined>
|
||||
@Remote async execute( agent: Agent, line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal: AbortSignal, ): Promise<CommandExecution | undefined>
|
||||
```
|
||||
|
||||
Types: [Agent](core.md) · [EncodedImageAttachment](attachment.md)
|
||||
Types: [Agent](core.md)
|
||||
|
||||
Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
## 输入元数据
|
||||
|
||||
该服务公开一个可选的非结构化输入描述符:提示文本加图片接受标志。命令的可用性由插件组合决定:每个消费注册表的适配器都会看到全部生效定义。
|
||||
该服务公开一个可选的非结构化输入描述符:提示文本加附件接受标志。命令的可用性由插件组合决定:每个消费注册表的适配器都会看到全部生效定义。
|
||||
|
||||
```ts type-equiv
|
||||
/** Immutable metadata for a command's optional unstructured input. */
|
||||
@@ -16,13 +16,13 @@ interface CommandInputDescriptor {
|
||||
/** Placeholder shown before the user supplies free-form input. */
|
||||
readonly hint: string
|
||||
/**
|
||||
* Whether composer image attachments may accompany an invocation. Absent or
|
||||
* false = the executor rejects an invocation carrying images and capable
|
||||
* Whether composer attachments may accompany an invocation. Absent or
|
||||
* false = the executor rejects an invocation carrying attachments and capable
|
||||
* composers refuse the submission before dispatch. A declaring command's
|
||||
* handler receives the admitted durable blocks and owns every further
|
||||
* grammar decision, including rejecting sub-commands that cannot use them.
|
||||
*/
|
||||
readonly images?: boolean
|
||||
readonly attachments?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
@@ -64,13 +64,13 @@ interface CommandInvocation {
|
||||
/** Exact text following the registered command name, including separator whitespace. */
|
||||
readonly rawInput: string
|
||||
/**
|
||||
* Durably admitted image blocks accompanying this invocation, in submission
|
||||
* order; empty unless the definition declares `input.images`. The handler
|
||||
* Durably admitted image and file blocks accompanying this invocation, in submission
|
||||
* order; empty unless the definition declares `input.attachments`. The handler
|
||||
* owns their model-visible use — the registry never schedules them itself —
|
||||
* and a handler whose grammar cannot use them in this invocation returns an
|
||||
* error so the dispatching composer retains the originals.
|
||||
*/
|
||||
readonly attachments: readonly ImageBlock[]
|
||||
readonly attachments: readonly (ImageBlock | FileBlock)[]
|
||||
/** Cancellation signal owned by the dispatching UI request. */
|
||||
readonly signal: AbortSignal
|
||||
}
|
||||
@@ -138,6 +138,13 @@ Human-command registry. Plain-context definitions are global; definitions regist
|
||||
*/
|
||||
register(definition: CommandDefinition): () => void
|
||||
|
||||
/**
|
||||
* Register the sole authority that resolves staged file receipts for command submissions.
|
||||
* @param resolver - Session-aware receipt resolver.
|
||||
* @returns disposer that removes this exact resolver.
|
||||
*/
|
||||
registerFileReceiptResolver(resolver: CommandFileReceiptResolver): () => void
|
||||
|
||||
/**
|
||||
* List the effective immutable command descriptors for one agent.
|
||||
* @param agent - exact receiving agent and scoped-layer key.
|
||||
@@ -166,23 +173,25 @@ find(agent: Agent, name: string): CommandDefinition | undefined
|
||||
* handler-failure path is contained so the handler's own error stays the
|
||||
* reported failure.
|
||||
*
|
||||
* Image admission is enforced here, not in the composer: images sent to a
|
||||
* command that does not declare `input.images`, an absent attachment store,
|
||||
* and an exceeded attachment limit each settle as an error result before
|
||||
* the handler runs, and a rejected batch publishes no durable object.
|
||||
* Attachment admission is enforced here, not in the composer: attachments sent to a
|
||||
* command that does not declare `input.attachments`, an absent attachment store,
|
||||
* and an exceeded image limit each settle as an error result before
|
||||
* the handler runs. Validation rejection starts no attachment writes;
|
||||
* a storage failure can leave only unreachable content-addressed objects
|
||||
* for deferred collection.
|
||||
*
|
||||
* @param agent - exact receiving agent.
|
||||
* @param line - complete slash-command line.
|
||||
* @param images - base64-encoded composer images accompanying the line, in
|
||||
* submission order; empty for a plain invocation.
|
||||
* @param submittedAttachments - encoded images and staged file receipts accompanying the line,
|
||||
* in submission order; empty for a plain invocation.
|
||||
* @param signal - cancellation signal owned by the UI request.
|
||||
* @returns the settled execution (result + lifecycle pairing id), or
|
||||
* `undefined` when syntax or name does not resolve.
|
||||
*/
|
||||
@Remote async execute( agent: Agent, line: string, images: readonly EncodedImageAttachment[], signal: AbortSignal, ): Promise<CommandExecution | undefined>
|
||||
@Remote async execute( agent: Agent, line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal: AbortSignal, ): Promise<CommandExecution | undefined>
|
||||
```
|
||||
|
||||
Types: [Agent](core.zh.md) · [EncodedImageAttachment](attachment.zh.md)
|
||||
Types: [Agent](core.zh.md)
|
||||
|
||||
Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
|
||||
llm-streaming.md: d0d83897db4924de885f012212a200fa7d88b36e
|
||||
llm-streaming.zh.md: 962cea4bf6ec5c4db84d7613c7a2317693bf5c47
|
||||
llm-streaming.md: e88741c6bb63b819a314f74fc425c89b865b5906
|
||||
llm-streaming.zh.md: 4bc7fc6124e77c7e3bbbc474bff9bc79fbd8eb27
|
||||
@@ -23,12 +23,13 @@ interface ContentBlockMap {
|
||||
'text': TextBlock
|
||||
'reasoning': ReasoningBlock
|
||||
'image': ImageBlock
|
||||
'file': FileBlock
|
||||
'tool-call': ToolCallBlock
|
||||
'tool-result': ToolResultBlock
|
||||
}
|
||||
```
|
||||
|
||||
The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ImageBlock` (a durable [image attachment](attachment.md)), `ToolCallBlock` (`id: ToolCallId`, `name`, raw-JSON `arguments`), and `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. A new modality belongs in the merge-extensible map only when its adapter, UI, compaction, and durable replay paths honor it.
|
||||
The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ImageBlock` (a durable [image attachment](attachment.md)), `FileBlock` (a durable verbatim [file attachment](attachment.md) that request assembly projects to handle text for every route), `ToolCallBlock` (`id: ToolCallId`, `name`, raw-JSON `arguments`), and `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. A new modality belongs in the merge-extensible map only when its adapter, UI, compaction, and durable replay paths honor it.
|
||||
|
||||
Image access belongs to request serialization rather than the durable attachment or deterministic request-image version. `resolveImageAttachmentAccess()` combines the attachment provider's optional host object path with a mapping supplied by the consumer for the current tool execution filesystem. The result is available only for that request and does not participate in `variantId`.
|
||||
|
||||
@@ -961,6 +962,14 @@ providerRetryPolicy(provider: string): ResolvedRetryPolicy
|
||||
*/
|
||||
imageRequestPricing(provider: string, model: string): LlmImageRequestPricing | undefined
|
||||
|
||||
/**
|
||||
* Resolve the exact text one durable file occurrence contributes to every
|
||||
* provider request in the current execution environment.
|
||||
* @param ref - durable verbatim file reference from model history.
|
||||
* @returns the same deterministic handle text used at adapter dispatch.
|
||||
*/
|
||||
fileRequestText(ref: FileAttachmentRef): string
|
||||
|
||||
/**
|
||||
* Discover models advertised by one registered provider. Catalog membership
|
||||
* is advisory and never changes routing or request validation.
|
||||
@@ -1016,6 +1025,8 @@ async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<Prepared
|
||||
stream(options: GenerateOptions): AsyncIterable<StreamChunk>
|
||||
```
|
||||
|
||||
Types: [FileAttachmentRef](attachment.md)
|
||||
|
||||
Source: [`packages/llm/llm/src/index.ts`](../../packages/llm/llm/src/index.ts)
|
||||
|
||||
<a id="llm-events"></a>
|
||||
|
||||
@@ -23,12 +23,13 @@ interface ContentBlockMap {
|
||||
'text': TextBlock
|
||||
'reasoning': ReasoningBlock
|
||||
'image': ImageBlock
|
||||
'file': FileBlock
|
||||
'tool-call': ToolCallBlock
|
||||
'tool-result': ToolResultBlock
|
||||
}
|
||||
```
|
||||
|
||||
各块接口(完整字段见源码):`TextBlock`(`text`)、`ReasoningBlock`(thinking,区别于可见文本)、`ImageBlock`(一个持久的[图片附件](attachment.zh.md))、`ToolCallBlock`(`id: ToolCallId`、`name`、原始 JSON `arguments`),以及 `ToolResultBlock`(`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`)。`ContentBlock = ContentBlockMap[ContentBlockType]`。仅当适配器、UI、压缩(compaction)和持久回放路径均支持某种新模态时,才将其纳入可合并扩展的 map。
|
||||
各块接口(完整字段见源码):`TextBlock`(`text`)、`ReasoningBlock`(thinking,区别于可见文本)、`ImageBlock`(一个持久的[图片附件](attachment.zh.md))、`FileBlock`(一个持久的原样[文件附件](attachment.zh.md),请求组装对每条路由都把它投影为 handle 文本)、`ToolCallBlock`(`id: ToolCallId`、`name`、原始 JSON `arguments`),以及 `ToolResultBlock`(`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`)。`ContentBlock = ContentBlockMap[ContentBlockType]`。仅当适配器、UI、压缩(compaction)和持久回放路径均支持某种新模态时,才将其纳入可合并扩展的 map。
|
||||
|
||||
图片访问方式属于请求序列化,不属于持久附件或确定性请求图片版本。`resolveImageAttachmentAccess()` 把附件提供方可选的宿主对象路径,与消费方为当前工具执行文件系统提供的映射组合起来。结果只适用于本次请求,不参与 `variantId`。
|
||||
|
||||
@@ -967,6 +968,14 @@ providerRetryPolicy(provider: string): ResolvedRetryPolicy
|
||||
*/
|
||||
imageRequestPricing(provider: string, model: string): LlmImageRequestPricing | undefined
|
||||
|
||||
/**
|
||||
* Resolve the exact text one durable file occurrence contributes to every
|
||||
* provider request in the current execution environment.
|
||||
* @param ref - durable verbatim file reference from model history.
|
||||
* @returns the same deterministic handle text used at adapter dispatch.
|
||||
*/
|
||||
fileRequestText(ref: FileAttachmentRef): string
|
||||
|
||||
/**
|
||||
* Discover models advertised by one registered provider. Catalog membership
|
||||
* is advisory and never changes routing or request validation.
|
||||
@@ -1022,6 +1031,8 @@ async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<Prepared
|
||||
stream(options: GenerateOptions): AsyncIterable<StreamChunk>
|
||||
```
|
||||
|
||||
Types: [FileAttachmentRef](attachment.zh.md)
|
||||
|
||||
Source: [`packages/llm/llm/src/index.ts`](../../packages/llm/llm/src/index.ts)
|
||||
|
||||
<a id="llm-events"></a>
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/web-styling.md
|
||||
web-styling.md: dd057a3121422e4decfac06b9a3cf57e52254011
|
||||
web-styling.zh.md: 5ec0b65390b29e915fe3da633bb7c56ef92e17d6
|
||||
web-styling.md: 250936b82f06b47d00c0b6646cbea5bdb41f42ea
|
||||
web-styling.zh.md: 9845b4f5d8341624d294a008f505c0fb1ec9757a
|
||||
@@ -22,6 +22,7 @@ Global style sheets belong in `ui-theme/src/styles/`. Component styles live besi
|
||||
- Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
|
||||
- Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)`, `var(--dsw-elevation-prominent)`, or the composer's `var(--dsw-elevation-soft)` (larger blur at lower alpha): the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
|
||||
- Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
|
||||
- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Text-leading anchors also lead with the ui-primitives `LinkIcon` category glyph riding `currentColor`; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance ([clickable-link Agent Note](../.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md)).
|
||||
|
||||
## Changing the system
|
||||
|
||||
|
||||
@@ -22,6 +22,7 @@
|
||||
- 支持的引擎上,圆角继承 ui-theme `corner-shape.css` 的全局超级椭圆平滑。每个正圆 `border-radius`(`50%`、`100%` 或胶囊半径)必须配对 `corner-shape: round`,使圆形与胶囊保持圆弧;ui-theme 的 corner-shape spec 强制这一配对。
|
||||
- 高层级表面(菜单、浮层、对话框、面板、悬浮按钮、输入框)设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)`、`var(--dsw-elevation-prominent)` 或输入框专用的 `var(--dsw-elevation-soft)`(更大模糊、更低透明度):0.5px 发丝描边是第一层投影,`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝;状态色 border(warn 面板)保持真 border。
|
||||
- 使用中性 `--dsw-alias-border-*` token 的平面边框与分割线一律 `0.5px`——按钮、输入框、卡片、行分割线,以及以填充盒绘制的分隔线(菜单分隔、对话标题栏接缝、markdown `hr`、竖向轨道线)共用发丝线粗细,Chromium 将其绘制为一个设备像素。dashed 记号与状态色 border 保持 1px;spinner 圆环经 spec 的显式豁免保留原宽度。更宽的中性 solid border 会被 ui-theme elevation spec 拒绝。
|
||||
- 可点击产物链接(Markdown 锚点、正文文件引用、网页来源与抓取链接、产物 chips、workflow 成员链接)经 `--dsw-alias-link` 着色、`font-weight: 500`,默认无下划线,hover/focus 时为 3px offset 的点状下划线。带文字的锚点另以 ui-primitives 的 `LinkIcon` 分类图形(随 `currentColor`)作前置;workflow 成员链接与只包图片的锚点不带图形,工具行文件链接保持其灰色点线示能([可点击链接 Agent Note](../.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.zh.md))。
|
||||
|
||||
## 变更系统
|
||||
|
||||
|
||||
Loaded 100 of 732 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user